kcgi is a minimal CGI library for web applications in ISC licensed ISO C.
It was designed to be secure and auditable.
See a Comparison of CGI Libraries in C
To start, download kcgi.tgz and run
make install into your
PREFIX of choice.
The kcgi(3) manpage documents usage.
kcgi is a BSD.lv project.
Most kcgi applications work as follows (the sample.c file distributed in the source consists of a full working example):
khttp_parseas early as possible. This will parse forms, query, and cookie data; validate fields; set up the HTTP environment; and map page and MIME requests. Validation uses
kvalid_uint, or locally-defined functions for validation.
struct kpairelements of the
struct kreqstructure and potentially perform high-level, database-driven revalidation. This structure contains all elements parsed by
Emit HTTP headers with
khttp_head, followed by
khttp_bodyto begin the HTTP body. The latter will automatically trigger compression if requested by the client.
Emit HTTP body output using HTML5 tree-building functions
khttp_template_buffunctions to populate file templates; or
khttp_freeto close the HTTP document and free all memory.
This library is still quite new. Contact Kristaps with questions or comments.
The following is a rough feature list of kcgi. See the manual for details.
- input processing: parses and validates query string, cookie, and form input
- output processing: pretty-prints HTML5 trees, outputs HTTP headers, formats URLs
- templating: populates file templates with callbacks
- security: process-separated, sandboxed parsing of input
- compression: automatically compresses HTTP response
- extensibility: extensible MIME types, HTTP headers, etc. with reasonable defaults
- portability: compatibility across UNIX systems and web servers
As a security precaution, the kcgi library parses and validates untrusted
network data in a sandboxed child process as follows.
khttp_parse will fork.
The child process is responsible for reading and parsing form data from the web server.
This parsed data is returned to the parent process over a
kcgi follows OpenSSH's method of sandboxing the untrusted child process. This requires special handling for each operating system. For now, only two methods are supported.
systrace(4)device as found on OpenBSD and other operating systems. This requires the existence of
/dev/systraceif running in a
Note: if you're using a stock OpenBSD, make sure that the mount-point of the
- Mac OS X Sandbox
pure computationprovided in Mac OS X Leopard and later. This is supplemented by resource limiting with
Since validation occurs within the sandbox, special care must be taken that validation routines don't access the environment (e.g., by opening files), as the child will be abruptly killed.
kcgi should run on any modern UNIX systems and with any web server.
To date, it has been built and run on GNU/Linux machines, BSD (OpenBSD), and Mac OSX
(Snow Leopard, Lion) on i386 and AMD64.
It has been deployed under Apache and nginx (via the
Portability across UNIX systems is made possible by a small
configure script that checks
for minor inconsistencies such as
strlcpy, the Security mechanisms,
and for Compression support.
While page maps and input validation are entirely driven by the interfacing application, kcgi also allows for extension of the default HTTP headers, schemas, MIME
types, and so on.
Reasonable default have been provided for convenience.
For specifics, see the
khttp_parsex in kcgi(3).
HAVE_ZLIB is enabled during compilation (via the Portability
khttp_body will signal use of zlib to
compress the HTTP body.
Compression is only enabled if the client provides the correct (
gzip) HTTP request header.
All common input methods—query string, cookie, and form (multipart form-data and mixed, urlencoded, and plain—are supported by kcgi. As described in the Security section, these fields are all parsed and validated from network data in a child process. Each input key-value pair can be matched (by key name) to a validator, which is run when fields are parsed. You can then look up key-value pairs constant-time in a table indexed by that key.
kcgi provides just the necessary functions for building HTML5 trees, outputting
HTTP headers, and building URLs to get by.
Many of these functions have both a basic and an extended calling style (with the function name ending
x, such as
As a convenience, it also provides memory allocation wrappers, but these can be safely disregarded or
mixed with the standard UNIX memory allocation routines.
While you can build HTML5 trees as noted in Functions, most application will
want just to fill in a template.
kcgi provides two simple functions,
khttp_template_buf, to fill in files or memory buffers with data.
Templates are the most common usage of kcgi, as they allow for a strong
disconnect between prsentation and logic.