ksgi
/
index.xml
463 строки · 20.9 Кб
1<!DOCTYPE html>2<html lang="en" prefix="og: http://ogp.me/ns#">3<head>4<meta name="viewport" content="width=device-width, initial-scale=1" />5<meta charset="utf-8" />6<title>kcgi | minimal CGI and FastCGI library for C/C++</title>7<link rel="alternate" href="atom.xml" type="application/atom+xml" title="kcgi version feed" />8<link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/font-awesome/4.5.0/css/font-awesome.min.css" />9<link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Alegreya+Sans:400,400italic,500,700" />10<link rel="stylesheet" href="https://bsd.lv/css/style.css" />11<link rel="stylesheet" href="index.css" />12<meta property="og:title" content="kcgi: minimal CGI and FastCGI library for C/C++" />13<meta property="og:description"14content="A C/C++ library for security-oriented web applications." />15<meta property="og:url" content="https://kristaps.bsd.lv/kcgi/index.html" />16<meta property="og:type" content="website" />17<meta name="description"18content="A C/C++ library for security-oriented web applications." />19</head>20<body itemscope="itemscope" itemtype="http://schema.org/SoftwareApplication">21<header>22<section id="breadcrumbs" class="text">23<a href="https://www.bsd.lv">BSD.lv</a> tools for <a href="https://learnbchs.org">BCHS</a>:24<a href="https://kristaps.bsd.lv/kcgi">kcgi</a>,25<a href="https://kristaps.bsd.lv/sqlbox">sqlbox</a>,26<a href="https://kristaps.bsd.lv/openradtool">ort</a>27</section>28<section id="header" class="text">29<h1>30<a href="index.html" itemprop="name" class="nm">kcgi</a>31–32<span itemprop="description" class="nd">minimal CGI and FastCGI library for C/C++</span>33</h1>34<nav>35<span class="version">36Version
37<nav data-sblg-nav="1" data-sblg-navtag="version"38data-sblg-navsz="1" data-sblg-navxml="1">39${sblg-titletext}
40</nav>41</span>42<a title="Source code" itemprop="downloadURL" href="snapshots/kcgi.tgz">43<i class="fa fa-fw fa-gears"></i>44</a>45<a title="Source fingerprint" href="snapshots/kcgi.tgz.sha512">46<i class="fa fa-fw fa-lock"></i>47</a>48<a title="Source archive" href="snapshots">49<i class="fa fa-fw fa-archive"></i>50</a>51<a title="Source repository" href="https://www.github.com/kristapsdz/kcgi">52<i class="fa fa-fw fa-github"></i>53</a>54<a title="Version feed" href="atom.xml">55<i class="fa fa-fw fa-rss"></i>56</a>57</nav>58</section>59</header>60<section class="text">61<p id="intro">62<span class="nm">kcgi</span> is an <a href="http://opensource.org/licenses/ISC" rel="license">open63source</a> CGI and FastCGI <span itemprop="applicationCategory">library for C/C++ web64applications</span>.65It is minimal, secure, and auditable.
66</p>67<p>68To start, <a href="#install">install</a> the library.69Then read the <a href="#deploying">deployment</a> and <a href="#usage">usage</a> guides.70Use the <a href="https://github.com/kristapsdz/kcgi">GitHub</a> tracker for questions or comments,71or find contact information there for direct contact.
72</p>73</section>74<figure id="sample">75<input type="radio" name="sample-show" value="0" id="show-nocomments" checked="checked" />76<input type="radio" name="sample-show" value="1" id="show-comments" />77<nav class="text">78<label id="label-nocomments" for="show-nocomments">79<i class="fa fa-fw fa-comments-o"></i> Hide source comments80</label>81<label id="label-comments" for="show-comments">82<i class="fa fa-fw fa-comments"></i> Show source comments83</label>84</nav>85<figcaption class="text">86The following echoes <q>Hello, World!</q> as an HTTP response to a CGI request.87</figcaption>88<pre id="nocomments" class="text prettyprint"><span class="cpp">#include</span> <span class="literal"><sys/types.h></span> /* size_t, ssize_t */89<span class="cpp">#include</span> <span class="literal"><stdarg.h></span> /* va_list */90<span class="cpp">#include</span> <span class="literal"><stddef.h></span> /* NULL */91<span class="cpp">#include</span> <span class="literal"><stdint.h></span> /* int64_t */92<span class="cpp">#include</span> <span class="literal"><<a href="kcgi.3.html">kcgi.h</a>></span>93
94<span class="ident">int</span> main(<span class="ident">void</span>) {95<span class="ident">struct</span> kreq r;96<span class="ident">const char</span> *page = <span class="literal">"index"</span>;97<span class="flow">if</span> (<a href="khttp_parse.3.html">khttp_parse</a>(&r, NULL, 0, &page, 1, 0) != KCGI_OK)98return 1;
99<a href="khttp_head.3.html">khttp_head</a>(&r, kresps[KRESP_STATUS],100<span class="literal">"%s"</span>, khttps[KHTTP_200]);101khttp_head(&r, kresps[KRESP_CONTENT_TYPE],102<span class="literal">"%s"</span>, kmimetypes[KMIME_TEXT_PLAIN]);103<a href="khttp_body.3.html">khttp_body</a>(&r);104<a href="khttp_write.3.html">khttp_puts</a>(&r, <span class="literal">"Hello, world!"</span>);105<a href="khttp_free.3.html">khttp_free</a>(&r);106<span class="flow">return</span> 0;107}</pre>108<pre id="comments" class="text prettyprint"><span class="cpp">#include</span> <span class="literal"><sys/types.h></span> /* size_t, ssize_t */109<span class="cpp">#include</span> <span class="literal"><stdarg.h></span> /* va_list */110<span class="cpp">#include</span> <span class="literal"><stddef.h></span> /* NULL */111<span class="cpp">#include</span> <span class="literal"><stdint.h></span> /* int64_t */112<span class="cpp">#include</span> <span class="literal"><<a href="kcgi.3.html">kcgi.h</a>></span>113
114<span class="ident">int</span> main(<span class="ident">void</span>) {115<span class="ident">struct</span> kreq r;116<span class="ident">const char</span> *page = <span class="literal">"index"</span>;117
118/*
119* Parse the HTTP environment.
120* We only know a single page, "index", which is also
121* the default page if none is supplied.
122* (We don't validate any input fields.)
123*/
124
125<span class="flow">if</span> (<a href="khttp_parse.3.html">khttp_parse</a>(&r, NULL, 0, &page, 1, 0) != KCGI_OK)126return 1;
127
128/*
129* Ordinarily, here I'd switch on the method (OPTIONS, etc.,
130* defined in the <q>method</q> variable) then switch on which131* page was requested (<q>page</q> variable).132* But for brevity's sake, just output a response: HTTP 200.
133*/
134
135<a href="khttp_head.3.html">khttp_head</a>(&r, kresps[KRESP_STATUS],136<span class="literal">"%s"</span>, khttps[KHTTP_200]);137
138/*
139* Show content-type unilaterally as text/plain.
140* This would usually be set from r.mime.
141*/
142
143khttp_head(&r, kresps[KRESP_CONTENT_TYPE],144<span class="literal">"%s"</span>, kmimetypes[KMIME_TEXT_PLAIN]);145
146/* No more HTTP headers: start the HTTP document body. */
147
148<a href="khttp_body.3.html">khttp_body</a>(&r);149
150/*
151* We can put any content below here: JSON, HTML, etc.
152* Usually we'd switch on our MIME type.
153* However, we're just going to put the literal string as noted…154*/
155
156<a href="khttp_write.3.html">khttp_puts</a>(&r, <span class="literal">"Hello, world!"</span>);157
158/* Flush the document and free resources. */
159
160<a href="khttp_free.3.html">khttp_free</a>(&r);161<span class="flow">return</span> 0;162}</pre>163</figure>164<section class="text">165<p>166For a fuller example, see <a href="sample.c.html">sample.c</a>, or jump to the <a href="#usage">Documentation</a> section.167(Want a C++ version? See <a href="samplepp.cc.html">samplepp.cc</a>.)168</p>169<p>170<i>kcgi</i> supports many features: auto-compression, handling of all HTTP input operations (query strings,171cookies, page bodies, multipart) with validation, authentication, configurable output caching, request
172debugging, and so on.
173Its strongest differentiating feature is using sandboxing and process separation for handling the untrusted
174input path.
175</p>176</section>177<section id="version">178<div class="text">179<h2>180current release
181</h2>182<nav data-sblg-nav="1" data-sblg-navtag="version" data-sblg-navsz="1" data-sblg-navcontent="1">183<div>184<div class="title">185Version <span class="version">${sblg-title}</span>:186<time datetime="${sblg-date}">${sblg-date}</time>187</div>188<div class="content">${sblg-aside}</div>189</div>190</nav>191<p class="archive">192(<a href="archive.html">release archive</a>)193</p>194</div>195</section>196<section id="install" class="text">197<h2>198installation
199</h2>200<p>201First, check if <span class="nm">kcgi</span> isn't already packaged for your system, such as202for <a href="https://cvsweb.openbsd.org/cgi-bin/cvsweb/ports/www/kcgi/">OpenBSD</a>, <a203href="https://svnweb.freebsd.org/ports/head/www/kcgi/">FreeBSD</a>,204<a href="https://aur.archlinux.org/packages/kcgi/">Arch Linux</a>, and so on.205(If it is, make sure it's up to date!)
206If so, install using that system.
207</p>208<p>209If not, you'll need a modern <span itemprop="operatingSystem">UNIX</span> system.210To date, <span class="nm">kcgi</span> has been built and run on211GNU/<a href="https://www.linux.org" itemprop="operatingSystem">Linux</a> machines212(musl and glibc), BSD
213(<a href="https://www.openbsd.org" itemprop="operatingSystem">OpenBSD</a>,214<a href="https://www.netbsd.org" itemprop="operatingSystem">NetBSD</a>,215<a href="https://www.freebsd.org" itemprop="operatingSystem">FreeBSD</a>),216<a href="https://www.oracle.com/solaris/solaris11" itemprop="operatingSystem">Solaris</a>,217<a href="https://omniosce.org" itemprop="operatingSystem">OmniOS</a>, and218<a href="https://www.apple.com/osx" itemprop="operatingSystem">Mac OS X</a>219(only Mojave and newer!) on i386, amd64, powerpc, arm64, and sparc64.
220It has been deployed under <a href="https://httpd.apache.org/">Apache</a>, <a221href="https://nginx.org">nginx</a>, and OpenBSD's <a222href="https://man.openbsd.org/httpd.8">httpd(8)</a>223(the latter two natively over FastCGI and via the <code>slowcgi</code> wrapper).224The only hard dependency is BSD make (<code>bmake</code> on Linux).225If you're running the regression tests (see <a href="#testing">Testing</a>), you'll need <a226href="https://curl.haxx.se/libcurl/">libcurl</a>.227</p>228<p>229Download <a href="snapshots/kcgi.tgz">kcgi.tgz</a> and verify the archive with <a230href="snapshots/kcgi.tgz.sha512">kcgi.tgz.sha512</a>.231Configure with <code>./configure</code>, compile with <code>make</code> (or <code>bmake</code>232on Linux systems).
233Finally, install the software using <code>make install</code>.234Optionally override default paths with a <code>configure.local</code> file (see the235<a href="https://github.com/kristapsdz/kcgi/blob/master/configure">configure</a> script236for details) prior to configuration.
237</p>238<p>239If <span class="nm">kcgi</span> doesn't compile, please send me the <span class="file">config.log</span>240file and the output of the failed compilation.
241Along with all of your operating system information of course.
242</p>243<p>244To run bleeding-edge code between releases, the CVS repository is mirrored on
245<a href="https://github.com/kristapsdz/kcgi">GitHub</a>. Installation instructions tracking the repository246version may be found on that page.
247</p>248</section>249<section id="deploying" class="text">250<h2>251deployment
252</h2>253<p>254To compile <span class="nm">kcgi</span> applications, use the package configuration.255Linking is similarly normative.
256</p>257<pre class="prettyprint">% cc `pkg-config --cflags kcgi` -c yourprog.c258% cc yourprog.o `pkg-config --libs kcgi`</pre>259<p>260Well-deployed web servers, such as the default <a href="https://www.openbsd.org">OpenBSD</a> server, by261default are deployed within a <a262href="https://man.openbsd.org/chroot.2">chroot(2)</a>. If263this is the case, you'll need to statically link your binary.
264</p>265<pre class="prettyprint">% cc -static yourprog.o `pkg-config --static --libs kcgi`</pre>266<p>267FastCGI applications may either be started directly by the web server (which is popular with <a268href="https://httpd.apache.org/">Apache</a>) or <q>externally</q> given a socket and <a269href="kfcgi.8.html">kfcgi(8)</a> (this method is normative for OpenBSD's <a270href="https://man.openbsd.org/httpd.8">httpd(8)</a> and271suggested for the security precautions taken by the wrapper).
272</p>273</section>274<section id="usage" class="text">275<h2>276documentation
277</h2>278<p>279The <span class="nm">kcgi</span> manpages, starting with <a href="kcgi.3.html">kcgi(3)</a>, are the280canonical source of documentation.
281The following is a list of all manpages:
282</p>283<nav id="mannav" data-sblg-nav="1" data-sblg-navtag="man" data-sblg-navcontent="1" data-sblg-navsort="title">284<a href="${sblg-stripbase}.html">${sblg-title}</a>285</nav>286<p>287If it's easier to start by example, you can use
288<a href="https://github.com/kristapsdz/kcgi-framework">kcgi-framework</a> as an initial boilerplate to289start your project.
290The following are introductory materials to the system.
291</p>292<nav data-sblg-nav="1" data-sblg-navtag="tutorial" data-sblg-navcontent="1" data-sblg-navsort="rdate">293<h3><a href="${sblg-base}.html">${sblg-titletext}</a></h3>294${sblg-aside}
295</nav>296<p>297In addition to these resources, the following conference sessions have referenced <span class="nm">kcgi</span>.298</p>299<ul>300<li>301Dzonsons, Kristaps. <i>Role-based Access Control in BCHS Web Applications</i>.302Proceedings of <a href="https://2018.asiabsdcon.org">AsiaBSDCon</a>, Tokyo, Japan, March 2018.303(<a href="https://kristaps.bsd.lv/absdcon2018">Slides</a>,304<a href="https://www.youtube.com/watch?v=FzF9e4jrnJ4">video</a>.)305<a href="https://kristaps.bsd.lv/absdcon2018/paper.pdf">paper</a>.)306</li>307<li>308Dzonsons, Kristaps. <i>Secure BSD Web Applications in C: Practical Strategies</i>.309Proceedings of <a href="https://2017.asiabsdcon.org">AsiaBSDCon</a>, Tokyo, Japan, March 2017.310(<a href="https://kristaps.bsd.lv/absdcon2017">Slides</a>.)311</li>312<li>313Dzonsons, Kristaps. <i>Secure BSD Web Application Development in C</i>.314Proceedings of <a href="https://2016.asiabsdcon.org">AsiaBSDCon</a>, Tokyo, Japan, March 2016.315(<a href="https://kristaps.bsd.lv/absdcon2016">Slides</a>.)316</li>317<li>318Dzonsons, Kristaps. <i>kcgi: securing CGI applications in C</i>.319Proceedings of <a href="https://2015.asiabsdcon.org">AsiaBSDCon</a>, Tokyo, Japan, March 2015.320(<a href="https://kristaps.bsd.lv/absdcon2015/talk.pdf">Slides</a>,321<a href="https://kristaps.bsd.lv/absdcon2015/paper.pdf">paper</a>.)322</li>323</ul>324<p>325And the following relate to extending standards:
326</p>327<ul>328<li>329Dzonsons, Kristaps. <a href="extending01.html">FastCGI Extensions for Management Control</a>. March3302016.
331</li>332</ul>333</section>334<section id="features" class="text">335<h2>336implementation details
337</h2>338<p>339The bulk of <span class="nm">kcgi</span>'s CGI handling lies in <a340href="khttp_parse.3.html">khttp_parse(3)</a>, which fully parses the HTTP request.341Application developers must invoke this function before all others.
342For FastCGI, this function is split between <a href="khttp_fcgi_init.3.html">khttp_fcgi_init(3)</a>, which343initialises context; and <a href="khttp_fcgi_parse.3.html">khttp_fcgi_parse(3)</a>, which receives new344parsed requests.
345In either case, requests must be freed by <a href="khttp_free.3.html">khttp_free(3)</a>.346</p>347<p>348All functions isolate the parsing and validation of untrusted network data within a <i>sandboxed</i>349child process.
350Sandboxes limit the environment available to a process, so exploitable errors in the parsing process (or
351validation with third-party libraries) cannot touch the system environment.
352This parsed data is returned to the parent process over a socket.
353In the following, the <i>HTTP parser</i> and <i>input validator</i> manage a single HTTP request, while354<i>connection delegator</i> accepts new HTTP requests and passes them along.355</p>356<figure>357<img src="figure1.svg" alt="Implementation Details" />358<img src="figure4.svg" alt="Implementation Details" />359</figure>360<p>361This method of sandboxing the untrusted parsing process follows <a362href="http://www.openssh.org">OpenSSH</a>, and requires special handling for each operating363system:
364</p>365<dl>366<dt>367<a href="http://man7.org/linux/man-pages/man2/seccomp.2.html">seccomp(2)</a>368(Linux)
369</dt>370<dd>371This requires a seccomp-enabled Linux kernel and a recognised hardware architecture.
372It is supplemented by <code>setrlimit(2)</code> limiting.373</dd>374<dt>375<a href="https://man.openbsd.org/pledge.2">pledge(2)</a>376(<a href="https://www.openbsd.org">OpenBSD</a>)377</dt>378<dd>379This will only work on OpenBSD >5.8.380</dd>381<dt>382<a href="https://developer.apple.com/library/mac/documentation/Darwin/Reference/ManPages/man3/sandbox_init.3.html">sandbox_init(3)</a>383(<a href="https://www.apple.com/osx/">Apple OSX</a>)384</dt>385<dd>386This uses the sandboxing profile for <q>pure computation</q> as provided in Mac OS X Leopard and387later.
388This is supplemented by resource limiting via <code>setrlimit(2)</code>.389</dd>390<dt>391<a href="https://www.freebsd.org/cgi/man.cgi?query=capsicum&sektion=4">capsicum(4)</a>392(<a href="https://www.freebsd.org">FreeBSD</a>)393</dt>394<dd>395Uses the capabilities facility on <a href="https://www.freebsd.org">FreeBSD</a> 10 and later.396This is supplemented by resource limiting with <code>setrlimit(2)</code>.397</dd>398</dl>399<p>400Since validation occurs within the sandbox, special care must be taken that validation routines don't
401access the environment (e.g., by opening files, network connections, etc.), as the child
402<strong>might</strong> be abruptly killed by the sandbox facility.403(Not all sandboxes do this.)
404If required, this kind of validation can take place after the parse validation sequence.
405</p>406<p>407The connection delegator is similar, but has different sandboxing rules, as it must manage an open
408socket connection and respond to new requests.
409</p>410</section>411<section class="text">412<h2 id="testing">413testing
414</h2>415<p>416<span class="nm">kcgi</span> is shipped with a fully automated testing framework executed with417<code>make regress</code>.418To test your own applications, use the <a href="kcgiregress.3.html">kcgiregress(3)</a> library.419This framework acts as a mini-webserver, listening on a local port, translating an HTTP document into a
420minimal CGI request, and passing the request to a <span class="nm">kcgi</span> CGI client.421For internal tests, test requests are constructed with <a422href="https://curl.haxx.se/libcurl/">libcurl</a>.423The binding local port is fixed: if you plan on running the regression suite, you may need to
424tweak its access port.
425</p>426<p>427Another testing framework exists for use with the <a href="http://lcamtuf.coredump.cx/afl/">American428fuzzy lop</a>.429To use this, you'll need to compile the <code>make afl</code> target with your compiler of choice, e.g.,430<code>make clean</code>, then <code>make afl CC=afl-gcc</code>.431Then run the <code>afl-fuzz</code> tool on the <code>afl-multipart</code>, <code>afl-plain</code>, and432<code>afl-urlencoded</code> binaries using the test cases (and dictionaries, for the first) provided.433</p>434</section>435<section class="text">436<h2>437performance
438</h2>439<p>440Security comes at a price—but not a stiff price.441By design, <span class="nm">kcgi</span> incurs overhead in three ways: first, spawning a child to442process the untrusted network data; second, enacting the sandbox framework; and third, passing parsed
443pairs back to the parent context.
444In the case of running CGI scripts, <span class="nm">kcgi</span> performance is bound to the operating445system's ability to spawn and reap processes.
446For FastCGI, the bottleneck becomes the transfer of data.
447</p>448</section>449<footer>450<div>451© 2014–2020452<a rel="author" href="https://github.com/kristapsdz">Kristaps Dzonsons</a>453</div>454<div>455<a href="snapshots/kcgi.tgz"><i class="fa fa-fw fa-gears"></i></a>456<a href="snapshots/kcgi.tgz.sha512"><i class="fa fa-fw fa-lock"></i></a>457<a href="snapshots"><i class="fa fa-fw fa-archive"></i></a>458<a href="https://www.github.com/kristapsdz/kcgi"><i class="fa fa-fw fa-github"></i></a>459<span>Built with <a href="https://kristaps.bsd.lv/sblg">sblg</a> on <a href="https://www.openbsd.org">OpenBSD</a></span>460</div>461</footer>462</body>463</html>464