minimal CGI and FastCGI library for C/C++
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
afl
man
regress
GNUmakefile
LICENSE.md
README.md
archive.css
archive.xml
atom-template.xml
auth.c
child.c
compats.c
configure
datetime.c
extending01-a.dot
extending01-b.dot Adding extension documentation. Mar 15, 2016
extending01-c.dot
extending01-d.dot
extending01.xml
extern.h
fcgi.c
figure1.dot
figure2-cgi-naked.tsv
figure2-cgi.tsv
figure2-fcgi.tsv
figure2-static.tsv
figure2.gnuplot
figure4.dot
functions.xml Unify subtitle. Apr 8, 2018
genindex.sh
httpauth.c Accept hex nc's, inspired by #42. Jun 18, 2018
index.css
index.xml
kcgi.c
kcgi.h
kcgihtml.c
kcgihtml.h
kcgijson.c
kcgijson.h
kcgiregress.c
kcgiregress.h
kcgixml.c
kcgixml.h
kfcgi.c
logging.c
mandoc.css
output.c
parent.c
prettify.css
prettify.js
sample-cgi.c
sample-fcgi.c
sample.c Merge #37, thanks! Jun 9, 2018
samplepp.cc
sandbox-capsicum.c
sandbox-darwin.c
sandbox-pledge.c
sandbox-seccomp-filter.c
sandbox.c
template.c
template.xml
tests.c
tutorial.css
tutorial.xml
tutorial0.xml
tutorial1.xml
tutorial2.xml
tutorial3.xml
tutorial4.xml
tutorial5.xml
tutorial6.dot
tutorial6.xml
versions.xml
wrappers.c

README.md

Synopsis

kcgi is an open source CGI and FastCGI library for C/C++ web applications. It is minimal, secure, and auditable; and fits within your BCHS software stack.

This repository consists of bleeding-edge code between versions: to keep up to date with the current stable release of kcgi, visit the kcgi website. The website also contains canonical installation, deployment, and usage documentation. This page describes using the bleeding-edge version of the system.

Example

Implementing a CGI or FastCGI application with kcgi is easy (for values of easy strictly greater than "knows C/C++"). Specify the pages recognised by the application and the known HTML form inputs. kcgi parses the request and can manage output.

#include <sys/types.h> /* size_t, ssize_t */
#include <stdarg.h> /* va_list */
#include <stddef.h> /* NULL */
#include <stdint.h> /* int64_t */
#include <kcgi.h>
 
int main(void) {
  struct kreq r;
  const char *page = "index";
  if (KCGI_OK != khttp_parse(&r, NULL, 0, &page, 1, 0))
	return 0;
  khttp_head(&r, kresps[KRESP_STATUS],
	"%s", khttps[KHTTP_200]);
  khttp_head(&r, kresps[KRESP_CONTENT_TYPE], 
	"%s", kmimetypes[KMIME_TEXT_PLAIN]);
  khttp_body(&r);
  khttp_puts(&r, "Hello, world!\n");
  khttp_free(&r);
  return 0;
}

For a fuller example reflecting the repository sources, see sample.c or, for C++, samplepp.cc.

Installation

To use the bleeding-edge version of kcgi (instead of from your system's packages or a stable version), the process it the similar as for source releases.

Begin by cloning or downloading. Then configure with ./configure, compile with make (GNU make, so it may be gmake on your system), then sudo make install (or using doas). To install in an alternative directory to /usr/local, set the PREFIX variable when you run configure. (See the configure script for details.)

./configure
make
doas make install

You can also change the default value in the GNUmakefile.

API Reference

For the repository version of kcgi, the locally-installed manpages are the canonical source of information. (The web-site reflects the latest release, which may be older than what you have.)

man kcgi
apropos kcgi

This assumes that kcgi has been installed in a path recognised by your manpage reader. If you're using an alternative installation path, you may need to edit /etc/man.conf or other configuration file appropriate to your system.

Tests

It's useful to run the installed regression tests on the bleeding edge sources. (Again, this uses GNU make, so it may be gmake on your system.)

make regress

The system contains a full regression suite and is also built to work with AFL. To run some of the bundled tests, use the binaries compiled into the afl directory. (Again, this uses GNU make, so it may be gmake on your system.)

make afl
cd afl
afl-fuzz -i in/urlencoded -o out -- ./afl-urlencoded

License

All sources use the ISC (like OpenBSD) license. See the LICENSE.md file for details.