Link to tutorial online:
kristaps.bsd.lv/absdcon2016

Link to examples:
kristaps.bsd.lv/absdcon2016/examples.tar.gz.

To print, just print in landscape mode.

Let's get started.

We'll begin with the introduction: HTTP, CGI, web servers, and operating systems.

1. manager opens socket
   1. forks application children
2. application listens on socket
3. web server receives request from client
   1. parses HTTP headers
   2. prepares FastCGI stream
   3. writes FastCGI stream to socket
4. application accept stream
   1. parses HTTP document from stream
   2. writes FastCGI document from stream
5. web server receives FastCGI document
   1. prepares HTTP document
   2. writes HTTP document to stream

Short story: accepts an HTTP request from a client and generates a response, also in HTTP.

Long story: process management and high-throughput I/O into and out of CGI and FastCGI processes.

• httpd(8)
• Apache (Apache1.3, Apache2)
• nginx
• lighttpd
• ...

1. receives and parses request from client
2. maps requested resource (e.g., /cgi-bin/foo) into a terminal resource (e.g., /var/www/cgi-bin/foo)
3. invokes the terminal resource handler (e.g., mod_cgi.so for Apache2)
4. manages I/O to (request) and from (response) the resource
5. constructs (or just post-processes) HTTP document from response
6. writes HTTP document to client

The Apache browser has two basic flavours on BSD: the current version available from the Apache project (Apache2) and the legacy version forked by OpenBSD (Apache1.3).

In the former case, the server configuration is in /etc/apache2/httpd.conf. In the latter case, /var/www/conf/httpd.conf.

The operating system brokers resources to and from the webserver, such as...

• static file server
• CGI (and managed FastCGI) processes

We'll focus primarily on OpenBSD, and care about the operating system to the extent of the security measures it provides.

A well-configured operating system can protect its non-web resources by enacting sandboxes. These fence the resources in a variety of ways. OpenBSD gives us privilege separation (users), file-system jail (files), and general sandboxing (system calls, files).

The chroot(2) system call protects us from accessing files outside of a directory sub-tree. This is mostly invoked by the web server or FastCGI manager. By default, httpd(8) will jail us to /var/www.

By invoking the setgid(2) and setuid(2) system call, we can protect ourselves from accessing resources owned by other users. Thus, if there are other users' files in our file-system jail, we can't access them.

Both file-system jails and privilege dropping help us with files, but don't do much more.

The new pledge(2) call (née tame(2) in 5.8) allows a much broader class of sandboxing. Another OpenBSD facility is systrace(4), which is more fine-grained, but difficult to control.

This concludes Part I. We'll next walk through a base installation of OpenBSD and how to set up our environment.

We'll start with a fresh OpenBSD installation with the httpd(8) system already in base.

1. edit /etc/doas.conf to do anything
2. edit /etc/httpd.conf with a minimal static file to test
3. test by manually starting httpd(8)
4. edit /etc/httpd.conf with our document root and indicate that we'll use FastCGI
5. manually start slowcgi(8) and httpd(8)
6. use rcctl(8) to start httpd(8) and slowcgi(8) on boot

Configure a directory as the root server directory. This is relative to the chroot /var/www.

ext_addr="egress"
prefork 2
server "localhost" {
	listen on $ext_addr port 80
	root "/htdocs"
}

This configures /var/www/htdocs as our document root.

Let's now add httpd(8) to the startup sequence and start it.

doas rcctl enable httpd
doas rcctl start httpd
doas rcctl check httpd

Why is slowcgi(8) necessary? It lets us emulate CGI in a FastCGI context. (httpd(8) supports only FastCGI natively.)

Next, configure a FastCGI location. We will use the slowcgi(8) system.

ext_addr="egress"
prefork 2
server "localhost" {
	listen on $ext_addr port 80
	root "/htdocs"
        location "/cgi-bin/*" {
                fastcgi
                root "/"
        }
}

This means that our scripts must go in /var/www/cgi-bin.

Let's now add slowcgi(8) to the startup sequence and start it. We then re-start httpd(8) to pick up the changes.

doas rcctl enable slowcgi
doas rcctl start slowcgi
doas rcctl check slowcgi
doas rcctl restart httpd

Let's start with a simple example, example1.c. It'll help to have the RFC 2616 (HTTP) and RFC 3875 (CGI) standards documents handy.

#include <stdlib.h>
#include <stdio.h>

int
main(void)
{

	puts("Status: 200 OK\r");
	puts("Content-Type: text/html\r");
	puts("\r");
	puts("Hello, world!");
	return(EXIT_SUCCESS);
}

Next we get our CGI script, example1.c, ready for action. Then we'll install it in the configured CGI root.

cc -static -g -W -Wall -o example1 example1.c
sudo install -u www -g www -m 0500 example1 /var/www/cgi-bin

Did it work?

Write a CGI script in C that will output all CGI variables in an HTML document. For example:

Accept: text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/*;q=0.8
Accept-Encoding: gzip, deflate, sdch
Accept-Language: en-US,en;q=0.8
Cache-Control: max-age=0
Connection: keep-alive
Host: localhost
Upgrade-Insecure-Requests: 1
User-Agent: Mozilla/5.0 (Linux; U; Android 4.0; en-us;...

Let's simplify CGI handling by using kcgi. Why? So we don't need to handle RFC 2616, RFC 3875, etc.

doas pkg_add -v kcgi

Disclaimer: I wrote kcgi(3), available at kristaps.bsd.lv/kcgi.

Let's prepare the same with kcgi(3) as example2.c. It's overkill for our purposes now, but later, we'll use this a lot more.

#include <stdint.h>
#include <stdlib.h>
#include <unistd.h>
#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(EXIT_FAILURE);
	khttp_head(&r, kresps[KRESP_STATUS], "%s", khttps[KHTTP_200]);
	khttp_head(&r, kresps[KRESP_CONTENT_TYPE], "%s", kmimetypes[r.mime]);
	khttp_body(&r);
	khttp_puts(&r, "Hello, world!\n");
	khttp_free(&r);
	return(EXIT_SUCCESS);
}

Now let's install the file.

cc -static -g -W -Wall -o example2 example2.c -lkcgi -lz
sudo install -u www -g www -m 0500 example2 /var/www/cgi-bin

Did it work?

If you're on an older OpenBSD machine, you'll need /dev/systrace in your chroot(2).

Amend your earlier quiz to print out CGI variables and form elements.

We'll now begin a longer case study, available as example3.c.

At the end of this part, you'll be familiar with how to parse form values and handle page requests.

Modify the case study to add a page, printenv, that prints CGI variables and form request variables. For example:

Accept: text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/*;q=0.8
Accept-Encoding: gzip, deflate, sdch
Accept-Language: en-US,en;q=0.8
Cache-Control: max-age=0
Connection: keep-alive
Host: localhost
Upgrade-Insecure-Requests: 1
User-Agent: Mozilla/5.0 (Linux; U; Android 4.0; en-us;...
Form[integer,0] = 123
Form[integer,1] = 321

We'll now begin another case study, which may be downloaded as example4.c.

In this study, we'll also use the SQLite database to record a stored value. The database system is pre-installed with OpenBSD systems. You'll need to append -lsqlite3 to the compilation routine, and execute the following additional steps to prepare for the database.

doas mkdir /var/www/tmp
doas chmod 1777 /var/www/tmp

Modify the previous example to include the last host to change the counter and when it was changed.

For the last quiz, see if you can modify the previous example to serve a JSON resource (hint: use kcgijson(3)), and have an HTML front-end (in /var/www/htdocs) asynchronously load format the output.

function loadJSON(path, success, error)
{
	var xhr = new XMLHttpRequest();
	xhr.onreadystatechange = function() {
		if (xhr.readyState === XMLHttpRequest.DONE) {
			if (xhr.status === 200) {
				success(JSON.parse(xhr.responseText));
			} else {
				error(xhr);
			}
		}
	};
	xhr.open("GET", path, true);
	xhr.send();
}

loadJSON('/cgi-bin/quiz4.json',
	function(data) { console.log(data); },
	function(xhr) { console.error(xhr); }
);

This concludes Part II. We'll next modify our case study applications to use the operating system's sandbox mechanism.

Our CGI scripts inherit the privilege-separation and chroot(2) environment of the web server. Can we do better?

We'll use the pledge(2) system call, introduced in OpenBSD 5.9.

Let's start with our simple sandbox example, example5.c. (The example file also includes a Darwin sandbox.)

#include <stdlib.h>
#include <stdio.h>
#include <unistd.h>

int
main(void)
{

	if (-1 == pledge("stdio", NULL)) 
		return(EXIT_FAILURE);
	printf("Status: 200 OK\r\n");
	printf("Content-Type: text/html\r\n");
	printf("\r\n");
	printf("Hello, world!\n");
	return(EXIT_SUCCESS);
}

Let's prepare the same with kcgi(3) as example6.c. (The example file also includes a Darwin sandbox.)

#include <stdint.h>
#include <stdlib.h>
#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(EXIT_FAILURE);
	if (-1 == pledge("stdio", NULL)) 
		return(EXIT_FAILURE);
	khttp_head(&r, kresps[KRESP_STATUS], 
		"%s", khttps[KHTTP_200]);
	khttp_head(&r, kresps[KRESP_CONTENT_TYPE], 
		"%s", kmimetypes[r.mime]);
	khttp_body(&r);
	khttp_puts(&r, "Hello, world!\n");
	khttp_free(&r);
	return(EXIT_SUCCESS);
}

Finally, let's sandbox our longer SQLite example in example7.c. (The example file also includes a Darwin sandbox.)

This concludes Part III. Questions? Comments?

Thank you for attending!