3
.\" Copyright (c) 2014--2017 Kristaps Dzonsons <kristaps@bsd.lv>
4
.\" Copyright (c) 2017 Ingo Schwarze <schwarze@openbsd.org>
6
.\" Permission to use, copy, modify, and distribute this software for any
7
.\" purpose with or without fee is hereby granted, provided that the above
8
.\" copyright notice and this permission notice appear in all copies.
10
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
11
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
12
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
13
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
14
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
15
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
16
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
24
.Nd parse a CGI instance for kcgi
35
.Fa "const struct kvalid *keys"
37
.Fa "const char *const *pages"
44
.Fa "const struct kmimemap *suffixes"
45
.Fa "const char *const *mimes"
47
.Fa "const struct kvalid *keys"
49
.Fa "const char *const *pages"
54
.Fa "void (*argfree)(void *arg)"
55
.Fa "unsigned int debugging"
56
.Fa "const struct kopts *opts"
58
.Vt extern const char *const kmimetypes[KMIME__MAX];
59
.Vt extern const char *const khttps[KHTTP__MAX];
60
.Vt extern const char *const kschemes[KSCHEME__MAX];
61
.Vt extern const char *const kmethods[KMETHOD__MAX];
62
.Vt extern const struct kmimemap ksuffixmap[];
63
.Vt extern const char *const ksuffixes[KMIME__MAX];
69
functions parse and validate input and the HTTP environment
70
(compression, paths, MIME types, and so on).
71
They are the central functions in the
73
library, parsing and validating key-value form (query string, message
74
body, cookie) data and opaque message bodies.
76
They must be matched by
78
if and only if the return value is
80
Otherwise, resources are internally freed.
82
The collective arguments are as follows:
85
A pointer to private application data.
86
It is not touched unless
92
by the child process starting to parse untrusted network data.
93
This makes sure that no unnecessary data is leaked into the child.
95
This bit-field enables debugging of the underlying parse and/or write
100
.Dv KREQ_DEBUG_READ_BODY
101
for the pre-parsed body.
104
consist of the process ID followed by
108
for writing or reading, a colon and space, then the logged data.
109
A newline will flush the existing line, as well reaching 80 characters.
110
If flushed at 80 characters and not a newline, an ellipsis will follow
112
The total logged bytes will be emitted at the end of all reads or
115
If no MIME type is specified (that is, there's no suffix to the
116
page request), use this index in the
120
If no page was specified (e.g., the default landing page), this is
121
provided as the requested page index.
123
An optional array of input and validation fields or
126
The number of elements in
129
The number of elements in
131
Also the MIME index used if no MIME type was matched.
134
which is used if there is no MIME suffix at all.
136
An array of MIME types (e.g.,
138
mapped into a MIME index during MIME body parsing.
139
This relates both to pages and input fields with a body type.
140
Any array should include at least
142
as this is the default content type for MIME documents.
144
Tunable options regarding socket buffer sizes and so on.
147
meaningful defaults are used.
149
An array of recognised pathnames.
150
When pathnames are parsed, they're matched to indices in this array.
152
The number of pages in
154
Also used if the requested page was not in
157
This structure is cleared and filled with input fields and HTTP context
158
parsed from the CGI environment.
159
It is the main structure carried around in a
163
Define the MIME type (suffix) mapping.
168
is for applications using the system-recognised MIME types.
169
This should work well enough for most applications.
170
It is equivalent to invoking the second form,
173
.Bd -literal -offset indent
174
khttp_parsex(req, ksuffixmap,
175
kmimetypes, KMIME__MAX, keys, keysz,
176
pages, pagesz, KMIME_TEXT_HTML,
177
defpage, NULL, NULL, 0, NULL);
182
object is filled in by
186
It consists of the following fields:
188
.It Vt "void *" Ns Va arg
189
Private application data.
192
.It Vt "enum kauth" Va auth
195
HTTP authorisation performed by the web server according to the
197
header variable, if any.
220
field for raw (i.e., not processed by the web server) authorisation
222
.It Vt "struct kpair **" Ns Va cookiemap
225
singly linked lists of elements of the
229
.Va cookie Ns -> Ns Va key
230
is equal to one of the entries of
233
.Va cookie Ns -> Ns Va state
238
the cookie is added to the list
239
.Va cookiemap Ns Bq Va cookie Ns -> Ns Va keypos .
242
If a list contains more than one cookie,
243
.Va cookie Ns -> Ns Va next
244
points to the next cookie.
245
For the last cookie in a list,
246
.Va cookie Ns -> Ns Va next
248
.It Vt "struct kpair **" Ns Va cookienmap
251
except that it contains the cookies where
252
.Va cookie Ns -> Ns Va state
255
.It Vt "struct kpair *" Ns Va cookies
256
Key-value pairs read from request cookies found in the
265
for key-value pairs from the request query string or message body.
266
.It Vt size_t Va cookiesz
270
.It Vt "struct kpair **" Ns Va fieldmap
273
except that the lists contain elements of the
276
.It Vt "struct kpair **" Ns Va fieldnmap
279
except that it contains the fields where
280
.Va field Ns -> Ns Va state
283
.It Vt "struct kpair *" Ns Va fields
284
Key-value pairs read from the
286
header variable and from the message body, or
293
for key-value pairs from request cookies.
294
.It Vt size_t Va fieldsz
295
The number of elements in the
298
.It Vt "char *" Ns Va fullpath
299
The full requested path as contained in the
302
For example, requesting
303
.Qq https://bsd.lv/app.cgi/dir/file.html?q=v ,
306
is the CGI program, this value would be
308
It is not guaranteed to start with a slash and it may be an empty
310
.It Vt "char *" Ns Va host
311
The host name received in the
314
When using name-based virtual hosting, this is typically the virtual
315
host name specified by the client in the HTTP request, and it should
316
not be confused with the canonical DNS name of the host running the
318
For example, a request to
319
.Qq https://bsd.lv/app.cgi/file
328
.It Vt "struct kdata *" Ns Va kdata
330
Should not be touched.
331
.It Vt "const struct kvalid *" Ns Va keys
334
.It Vt size_t Va keysz
337
.It Vt "enum kmethod" Va method
346
.Dv KMETHOD_MKCALENDAR ,
351
.Dv KMETHOD_PROPFIND ,
352
.Dv KMETHOD_PROPPATCH ,
358
submission method obtained from the
361
If an unknown method was requested,
364
If no method was specified, the default is
367
Applications will usually accept only
373
status for undesired methods.
375
The MIME type of the requested file as determined by its
393
when no suffix is specified or when the suffix is specified but not known.
395
The page index found by looking up
410
.It Vt "char *" Ns Va pagename
411
The first component of
413
or an empty string if there is none.
414
It is compared to the elements of the
416
array to determine which
423
this component corresponds to
429
.It Vt "char *" Ns Va path
436
at the end, or an empty string if there is none.
443
.It Vt "char *" Ns Va pname
444
The script name received in the
447
For example, for a request to a CGI program
448
.Pa /var/www/cgi-bin/app.cgi
449
mapped by the web server from
450
.Qq https://bsd.lv/app.cgi/file ,
453
This may not reflect a file system entity and it may be an empty string.
454
.It Vt uint16_t Va port
455
The server's receiving TCP port according to the
457
header variable, or 80 if that is not defined or an invalid number.
458
.It Vt "struct khttpauth" Va rawauth
459
The raw authorization request according to the
460
.Ev HTTP_AUTHORIZATION
461
header variable passed by the web server.
462
This is only set if the web server is not managing authorisation itself.
463
.It Vt "char *" Ns Va remote
464
The string form of the client's IPv4 or IPv6 address taken from the
468
if that is not defined.
469
The address format of the string is not checked.
470
.It Vt "struct khead *" Ns Va reqmap Ns Bq Dv KREQU__MAX
475
parsed from the input stream.
476
.It Vt "struct khead *" Ns Va reqs
477
List of all HTTP request headers, known via
479
and not known, parsed from the input stream, or
484
.It Vt size_t Va reqsz
485
Number of request headers in
487
.It Vt "enum kscheme" Va scheme
488
The access scheme according to the
490
header variable, either
494
is set and equal to the string
499
.It Vt "char *" Ns Va suffix
500
The suffix part of the last component of
502
or an empty string if there is none.
511
field for the MIME type parsed from the suffix.
514
The application may optionally define
522
This structure is central to the validation of input data.
523
It consists of the following fields:
525
.It Vt "const char *" Ns Va name
526
The field name, i.e., how it appears in the HTML form input name.
529
If the field name is an empty string and the HTTP message consists of an
530
opaque body (and not key-value pairs), then that field will be used to
531
validate the HTTP message body.
535
.It Vt "int (*)(struct kpair *)" Va valid
536
A validation function returning non-zero if parsing and validation
537
succeed or 0 otherwise.
540
then no validation is performed, the data is considered as valid,
541
and it is bucketed into
549
functions usually set the
553
fields in the key-value pair.
554
When working with binary data or with a key that can take different
555
data types, it is acceptable for a validation function to set the
559
and for the application to ignore the
561
field and to work directly with
566
The validation function is allowed to allocate new memory for
570
pointer changes during validation, the memory pointed to after validation
573
after the data is passed out of the sandbox.
575
These functions are invoked from within a system-specific sandbox
576
that may not allow some system calls, for example opening files or
578
In other words, validation functions should only do pure computation.
583
structure presents the user with fields parsed from input and (possibly)
590
It is also passed to the validation function to be filled in.
591
In this case, the MIME-related fields are already filled in and may be
592
examined to determine the method of validation.
593
This is useful when validating opaque message bodies.
595
.It Vt "char *" Ns Va ctype
596
The value's MIME content type (e.g.,
599
an empty string if not defined.
600
.It Vt "size_t" Va ctypepos
605
it is looked up in the
613
If found, it is set to the appropriate index.
616
.It Vt "char *" Ns Va file
617
The value's MIME source filename or
620
.It Vt "char *" Ns Va key
621
The NUL-terminated key (input) name.
622
If the HTTP message body is opaque (e.g.,
624
then an empty-string key is cooked up.
625
The key may contain an arbitrary sequence of non-NUL bytes, even
626
non-ASCII bytes, control characters, and shell metacharacters.
627
.It Vt "size_t" Va keypos
632
the index of the matching key.
635
.It Vt "struct kpair *" Ns Va next
636
In a cookie or field map,
638
points to the next parsed key-value pair with the same
641
This occurs most often in HTML checkbox forms, where many fields may
643
.It Vt "union parsed" Va parsed
644
The parsed, validated value.
645
These may be integer in
647
for a 64-bit signed integer; a string
649
for a NUL-termianted character string; or a double
651
for a double-precision floating-point number.
652
This is intentionally basic because the resulting data must be reliably
653
passed from the parsing context back into the web application.
654
.It Vt "enum kpairstate" Va state
657
if the pair was successfully validated by a validation function,
659
if a validation function was invoked but failed, or
661
if no validation function is defined for this
663
.It Vt "enum kpairtype" Va type
664
If parsed, the type of data in
668
.It Vt "char *" Ns Va val
669
The (input) value, which may contain an arbitrary sequence of bytes,
670
even NUL bytes, non-ASCII bytes, control characters, and shell
672
The byte following the end of the array,
673
.Va val Ns Va [ valsz ] ,
674
is always guaranteed to be NUL.
675
The validation function may modify the contents.
676
For example, for integer numbers and e-mail adresses, trailing
677
whitespace may be replaced with NUL bytes.
678
.It Vt "size_t" Va valsz
682
It is not a string length.
683
.It Vt "char *" Ns Va xcode
684
The value's MIME content transfer encoding (e.g.,
686
or an empty string if not defined.
691
structure holds authorisation data if passed by the server.
692
The specific fields are as follows.
694
.It Vt "enum kauth" Va type
695
If no data was passed by the server, the
705
signals that the authorisation type was not recognised.
706
.It Vt "int" Va authorised
712
authorisation, this field indicates whether all required values were
713
specified for the application to perform authorisation.
714
.It Vt "char *" Ns Va digest
719
header variables and the request body.
720
It is not a NUL-terminated string, but an array of exactly
724
.Ev HTTP_AUTHORIZATION
733
.Xr khttpdigest_validatehash 3 .
735
An anonymous union containing parsed fields per type:
736
.Vt "struct khttpbasic" Va basic
742
.Vt "struct khttpdigest" Va digest
747
If the field for an HTTP authorisation request is
751
it will consist of the following for its parsed entities in its
756
The hashed and encoded response string for
758
or an opaque string for
762
If the field for an HTTP authorisation request is
764
it will consist of the following in its
765
.Vt struct khttpdigest
769
The encoding algorithm, parsed from the possible
775
The quality of protection algorithm, which may be unspecified,
780
The user coordinating the request.
782
The URI for which the request is designated.
783
.Pq This must match the request URI .
787
The server-generated nonce value.
789
The (optional) client-generated nonce value.
791
The hashed and encoded response string, which entangled fields depending
792
on algorithm and quality of protection.
798
The (optional) opaque string requested by the server.
803
structure consists of tunables for network performance.
804
You probably don't want to use these unless you really know what you're
808
The size of the output buffer.
809
The output buffer is a heap-allocated region into which writes (via
813
are buffered instead of being flushed directly to the wire.
814
The buffer is flushed when it is full, when
815
the HTTP headers are flushed, and when
818
If the buffer size is zero, writes are flushed immediately to the wire.
819
If the buffer size is less than zero, it is filled with a meaningful
825
structure holds parsed HTTP headers.
828
Holds the HTTP header name.
829
This is not the CGI header name (e.g.,
831
but the reconstituted HTTP name (e.g.,
834
The opaque header value, which may be an empty string.
837
A number of variables are defined
839
to simplify invocations of the
842
Applications are strongly suggested to use these variables (and
843
associated enumerations) in
845
instead of overriding them with hand-rolled sets in
849
Indexed list of common MIME types, for example,
852
.Dq application/json .
857
Indexed list of HTTP status code and identifier, for example,
862
Indexed list of URL schemes, for example,
869
Indexed list of HTTP methods, for example,
876
Map of MIME types defined in
879
This array is terminated with a MIME type of
884
Indexed list of canonical suffixes for MIME types corresponding to
888
pointer for types that have no canonical suffix, for example.
889
.Dq application/octet-stream .
898
Success (not an error).
901
This can occur in many places: spawning a child, allocating memory,
902
creating sockets, etc.
904
Could not allocate file descriptors.
906
Could not spawn a child.
908
Malformed data between parent and child whilst parsing an HTTP request.
909
(Internal system error.)
911
Opaque operating system error.
914
On failure, the calling application should terminate as soon as possible.
917
try to write an HTTP 505 error or similar, but allow the web server to
918
handle the empty CGI response on its own.
927
functions were written by
928
.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv .