waldek
/
jetforce
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Merge branch 'master' of github.com:michael-lazar/jetforce

This commit is contained in:
Michael Lazar 2020-05-24 21:48:35 -04:00
parent e5b1d5b41d 623a408ca4
commit 3a7c075521
1 changed files with 43 additions and 28 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

71
README.md
View File

@ -46,6 +46,8 @@ An Experimental Gemini Protocol Server
optional arguments: optional arguments:
-h, --help show this help message and exit -h, --help show this help message and exit
-V, --version show program's version number and exit -V, --version show program's version number and exit
server configuration:
--host HOST Server address to bind to (default: 127.0.0.1) --host HOST Server address to bind to (default: 127.0.0.1)
--port PORT Server port to bind to (default: 1965) --port PORT Server port to bind to (default: 1965)
--hostname HOSTNAME Server hostname (default: localhost) --hostname HOSTNAME Server hostname (default: localhost)
@ -54,6 +56,8 @@ optional arguments:
--tls-cafile FILE A CA file to use for validating clients (default: None) --tls-cafile FILE A CA file to use for validating clients (default: None)
--tls-capath DIR A directory containing CA files for validating clients --tls-capath DIR A directory containing CA files for validating clients
(default: None) (default: None)
fileserver configuration:
--dir DIR Root directory on the filesystem to serve (default: --dir DIR Root directory on the filesystem to serve (default:
/var/gemini) /var/gemini)
--cgi-dir DIR CGI script directory, relative to the server's root --cgi-dir DIR CGI script directory, relative to the server's root
@ -100,9 +104,8 @@ $ openssl req -newkey rsa:2048 -nodes -keyout {hostname}.key \
``` ```
Jetforce also supports TLS client certificates (both self-signed and CA verified). Jetforce also supports TLS client certificates (both self-signed and CA verified).
Connections made with a client certificate will have additional metadata included Requests that are made with client certificates will include additional
in the request environment. ``REMOTE_USER`` will contain the subject common name, CGI/environment variables with information about the TLS connection.
and ``TLS_CLIENT_HASH`` will contain a fingerprint that can be used for TOFU pinning.
You can specify a CA for client validation with the ``--tls-cafile`` or ``--tls-capath`` You can specify a CA for client validation with the ``--tls-cafile`` or ``--tls-capath``
flags. Connections validated by the CA will have the ``TLS_CLIENT_VERIFIED`` environment flags. Connections validated by the CA will have the ``TLS_CLIENT_VERIFIED`` environment
@ -112,13 +115,11 @@ this readme, but you can find many helpful tutorials
### Static Files ### Static Files
Jetforce will serve static files in the ``/var/gemini/`` directory: Jetforce will serve static files in the ``/var/gemini/`` directory by default.
Files ending with ***.gmi** will be interpreted as the *text/gemini* type. If
- Files ending with **.gmi** will be interpreted as the *text/gemini* type a directory is requested, jetforce will look for a file named **index.gmi** in that
- If a directory is requested, jetforce will look for a file in that directory directory to return. Otherwise, a directory file listing will be automatically
with the name of **index.gmi** generated.
- If it exists, the index file will be returned
- Otherwise, jetforce will generate a directory listing
### CGI Scripts ### CGI Scripts
@ -131,20 +132,34 @@ considered a CGI script. When a CGI script is requested by a gemini client,
the jetforce server will execute the script and pass along information about the jetforce server will execute the script and pass along information about
the request using environment variables: the request using environment variables:
| Variable Name | Example | | Variable Name | Description | Example |
| --- | --- | | --- | --- | --- |
| GATEWAY_INTERFACE | GCI/1.1 | | GATEWAY_INTERFACE | CGI version (for compatability). | ``GCI/1.1`` |
| GEMINI_URL | gemini://mozz.us/cgi-bin/debug.cgi?foobar | SERVER_PROTOCOL | The server protocol. | ``GEMINI`` |
| HOSTNAME | mozz.us | | SERVER_SOFTWARE | The server version string. | ``jetforce/0.0.7`` |
| PATH_INFO | /cgi-bin/debug.cgi | | GEMINI_URL | Raw URL string from the request. | ``gemini://mozz.us/cgi-bin/example.cgi/hello?world``
| QUERY_STRING | foobar | | SCRIPT_NAME | The part of the URL's path that corresponds to the CGI script location. | ``/cgi-bin/example.cgi`` |
| REMOTE_ADDR | 10.10.0.2 | | PATH_INFO | The remainder of the URL's path after the CGI script location. | ``/hello`` |
| REMOTE_HOST | 10.10.0.2 | | QUERY_STRING | The query string portion of the request URL. | ``world`` |
| SCRIPT_NAME | /usr/local/www/mozz/gemini/cgi-bin/debug.cgi | | HOSTNAME | Server hostname. | ``mozz.us`` |
| SERVER_NAME | mozz.us | | SERVER_NAME | Server hostname (alias for HOSTNAME). | ``mozz.us`` |
| SERVER_PORT | 1965 | | REMOTE_ADDR | Client IP address. | ``10.10.0.2`` |
| SERVER_PROTOCOL | GEMINI | | REMOTE_HOST | Client IP address (alias for REMOTE_ADDR). | ``10.10.0.2`` |
| SERVER_SOFTWARE | jetforce/0.0.7 | | SERVER_PORT | Server port number. | ``1965`` |
Additional CGI variables will also be included when the connection uses a TLS client certificate:
| Variable Name | Description | Example |
| --- | --- | --- |
| AUTH_TYPE | Authentication type (for compatability). | ``CERTIFICATE`` |
| REMOTE_USER | The subject CommonName attribute, if provided. | ``michael123`` |
| TLS_CLIENT_HASH | A base64-encoded certificate fingerprint. | ``hjQftIC/4zPDQ1MNdav5nRQ39pM482xoTIgxtjyZOpY=`` |
| TLS_CLIENT_NOT_BEFORE | Certificate activation date. | ``2020-04-05T04:18:22Z`` |
| TLS_CLIENT_NOT_AFTER | Certificate expiration date. | ``2021-04-05T04:18:22Z`` |
| TLS_CLIENT_SERIAL_NUMBER | Certificate serial number. | ``73629018972631`` |
| TLS_CLIENT_VERIFIED | Was the certificate verified by OpenSSL? | ``0`` (verified) / ``1`` (not verified) |
| TLS_CIPHER | TLS cipher that was negotiated. | ``TLS_AES_256_GCM_SHA384``|
| TLS_VERSION | TLS version that was negotiated. | ``TLSv1.3`` |
The CGI script must then write the gemini response to the *stdout* stream. The CGI script must then write the gemini response to the *stdout* stream.
This includes the status code and meta string on the first line, and the This includes the status code and meta string on the first line, and the
@ -208,10 +223,10 @@ journalctl -u jetforce -f
*WARNING* *WARNING*
The internet can be a scary place. You (yes you!) are responsible for securing your You are exposing a server to the internet. You (yes you!) are responsible for
server and setting up appropriate access permissions. This likely means *not* securing your server and setting up appropriate access permissions. This likely means
running jetforce as the root user. Security best practices are outside of the scope *not* running jetforce as the root user. Security best practices are outside of the
of this document and largely depend on your individual threat model. scope of this document and largely depend on your individual threat model.
## License ## License