This repository has been archived on 2024-08-20. You can view files and clone it, but cannot push or open issues or pull requests.
Opal/README.md
dece 237959fb42 use OpenSSL bindings instead of Rustls
Rustls is fine but it's hard to change the default "secure" behaviour
for Gemini usage. Not that Gemini is unsecure but things like
self-signed client certificates should not be such a stupidly hard thing
to accept.
2021-11-24 12:15:08 +01:00

83 lines
4.2 KiB
Markdown

Opal
====
Opal is a Gemini server written in Rust. It is meant to serve dynamic content
through CGI and does not serve static files. In a way, it is a companion project
to the [Agate][agate] Gemini server which only serves static files, trying to
focus on a smaller set of features but do them correctly.
[agate]: https://github.com/mbrubeck/agate/
Opal uses the `openssl` Rust bindings, which work with OpenSSL and LibreSSL, so
it should work properly on those platforms. I only support Linux systems but
feel free to patch stuff!
Usage
-----
Use `opal -h` to get a list of options. There is no config file.
CGI support
-----------
Opal tries to implement [RFC 3875][rfc3875] (CGI 1.1) and provides all the
required environment variables to processes. It also add a bunch of Gemini
specific variables, like a lot of other servers (Gemserv, Gmid, Gmnisrv, …). The
environment for the subprocess is cleaned and should only contain those
variables.
[rfc3875]: https://datatracker.ietf.org/doc/html/rfc3875
| Presence | Variable | Description |
|-------------|------------------------|------------------------------------------------------|
| always | GATEWAY_INTERFACE | "CGI/1.1" |
| always | REMOTE_ADDR | Peer IP address and port |
| always | REMOTE_HOST | Same as REMOTE_ADDR |
| always | REQUEST_METHOD | Empty string for compatibility |
| always | SCRIPT_NAME | Script name part of the URL path |
| always | SERVER_NAME | Hostname used for SNI |
| always | SERVER_PORT | Port where the request has been received |
| always | SERVER_PROTOCOL | "GEMINI" |
| always | SERVER_SOFTWARE | "opal/version", e.g. "opal/0.1.0" |
| always | GEMINI_DOCUMENT_ROOT | CGI root |
| always | GEMINI_SCRIPT_FILENAME | CGI script that matched the URL path |
| always | GEMINI_URL | Full URL, normalized |
| always | GEMINI_URL_PATH | URL path, normalized |
| always | TLS_VERSION | TLS version, e.g. "TLSv1.3" |
| always | TLS_CIPHER | TLS cipher suite, e.g. "TLS_AES_256_GCM_SHA384" |
| optional | PATH_INFO | Path passed to the CGI process after the script name |
| optional | QUERY_STRING | Query string if provided, still URL-encoded |
| client cert | AUTH_TYPE | "CERTIFICATE" if one is provided |
| client cert | REMOTE_USER | Subject common name (empty if unavailable) |
| client cert | TLS_CLIENT_ISSUER | Issuer common name (empty if unavailable) |
| client cert | TLS_CLIENT_HASH | Digest of the DER reprensetation of the cert |
| client cert | TLS_CLIENT_NOT_AFTER | Validity end date, RFC 3339 format |
| client cert | TLS_CLIENT_NOT_BEFORE | Validity start date, RFC 3339 format |
Opal does not provide `CONTENT_LENGTH`, `CONTENT_TYPE`, `REMOTE_IDENT` because
they do not make much sense in Gemini. `PATH_TRANSLATED` is also not implemented
by pure laziness.
The `TLS_CLIENT_HASH` is a string that starts with "SHA256:" followed by the
SHA256 digest of the DER representation of the client certificate, as an
uppercase hex-string.
It can be a bit confusing which variable represent what data, especially those
related to the URL and the path. Take the following request as example:
`gemini://localhost/env/sub1/sub2?search=élément`. Suppose our CGI root, in
`/cgi`, contains the executable script named `env`. The variables will be:
```
GEMINI_DOCUMENT_ROOT=/cgi
GEMINI_SCRIPT_FILENAME=/cgi/env
GEMINI_URL=gemini://localhost/env/sub1/sub2?search=%C3%A9l%C3%A9ment
GEMINI_URL_PATH=/env/sub1/sub2
SCRIPT_NAME=/env
PATH_INFO=/sub1/sub2
QUERY_STRING=search=%C3%A9l%C3%A9ment
```