diff --git a/README.md b/README.md index b5e8d2d..271f356 100644 --- a/README.md +++ b/README.md @@ -121,7 +121,7 @@ a directory is requested, jetforce will look for a file named **index.gmi** in t directory to return. Otherwise, a directory file listing will be automatically generated. -### CGI Scripts +### CGI Jetforce supports a simplified version of CGI scripting. It doesn't exactly follow the [RFC 3875](https://tools.ietf.org/html/rfc3875) @@ -130,36 +130,7 @@ specification for CGI, but it gets the job done for the purposes of Gemini. Any executable file placed in the server's ``cgi-bin/`` directory will be 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 request using environment variables: - -| Variable Name | Description | Example | -| --- | --- | --- | -| GATEWAY_INTERFACE | CGI version (for compatability). | ``GCI/1.1`` | -| SERVER_PROTOCOL | The server protocol. | ``GEMINI`` | -| SERVER_SOFTWARE | The server version string. | ``jetforce/0.0.7`` | -| GEMINI_URL | Raw URL string from the request. | ``gemini://mozz.us/cgi-bin/example.cgi/hello?world`` -| SCRIPT_NAME | The part of the URL's path that corresponds to the CGI script location. | ``/cgi-bin/example.cgi`` | -| PATH_INFO | The remainder of the URL's path after the CGI script location. | ``/hello`` | -| QUERY_STRING | The query string portion of the request URL. | ``world`` | -| HOSTNAME | Server hostname. | ``mozz.us`` | -| SERVER_NAME | Server hostname (alias for HOSTNAME). | ``mozz.us`` | -| REMOTE_ADDR | Client IP address. | ``10.10.0.2`` | -| REMOTE_HOST | Client IP address (alias for REMOTE_ADDR). | ``10.10.0.2`` | -| SERVER_PORT | Server port number. | ``1965`` | -| TLS_CIPHER | TLS cipher that was negotiated. | ``TLS_AES_256_GCM_SHA384``| -| TLS_VERSION | TLS version that was negotiated. | ``TLSv1.3`` | - -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`` (not verified) / ``1`` (verified) | +the request using environment variables. 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 @@ -167,6 +138,151 @@ optional response body on subsequent lines. The bytes generated by the CGI script will be forwarded *verbatim* to the gemini client, without any additional modification by the server. +#### CGI Environment Variables + +
+
GATEWAY_INTERFACE
+
+ CGI version (for compatability with RFC 3785).
+ Example: "GCI/1.1" +
+ +
SERVER_PROTOCOL
+
+ The server protocol.
+ Example: "GEMINI" +
+ +
SERVER_SOFTWARE
+
+ The server name and version.
+ Example: "jetforce/0.0.7" +
+ +
GEMINI_URL
+
+ The entire URL that was requested by the client.
+ Example: "gemini://mozz.us/cgi-bin/example.cgi/hello?world" +
+ +
SCRIPT_NAME
+
+ The part of the URL's path that corresponds to the CGI script location.
+ Example: "/cgi-bin/example.cgi" +
+ +
PATH_INFO
+
+ The remainder of the URL's path after the SCRIPT_NAME.
+ Example: "/hello" +
+ +
QUERY_STRING
+
+ The query string portion of the request URL.
+ Example: "world" +
+ +
HOSTNAME
+
+ The server hostname.
+ Example: "mozz.us" +
+ +
SERVER_NAME
+
+ The server hostname (alias for HOSTNAME).
+ Example: "mozz.us" +
+ +
SERVER_PORT
+
+ The server port number.
+ Example: "1965" +
+ +
REMOTE_HOST
+
+ The client's IP address (alias for REMOTE_ADDR).
+ Example: "10.10.0.2" +
+ +
REMOTE_ADDR
+
+ The client's IP address.
+ Example: "10.10.0.2" +
+ +
REMOTE_HOST
+
+ The client's IP address (alias for REMOTE_ADDR).
+ Example: "10.10.0.2" +
+ +
TLS_CIPHER
+
+ The negotiated TLS cipher
+ Example: "TLS_AES_256_GCM_SHA384" +
+ +
TLS_VERSION
+
+ The negotiated TLS version.
+ Example: "TLSv1.3" +
+ +
+ +#### CGI Environment Variables - Authenticated + +Additional CGI variables will be included only when the client connection uses a TLS client certificate: + +
+ +
AUTH_TYPE
+
+ Authentication type (for compatability with RFC 3785).
+ Example: "CERTIFICATE" +
+ +
REMOTE_USER
+
+ The certificate's subject CommonName attribute, if provided.
+ Example: "mozz123" +
+ +
TLS_CLIENT_HASH
+
+ A base64-encoded fingerprint that can be used to uniquely identify the certificate.
+ Example: "hjQftIC/4zPDQ1MNdav5nRQ39pM482xoTIgxtjyZOpY=" +
+ +
TLS_CLIENT_NOT_BEFORE
+
+ The certificate's activation date.
+ Example: "2020-04-05T04:18:22Z" +
+ +
TLS_CLIENT_NOT_AFTER
+
+ The certificate's activation date.
+ Example: "2021-04-05T04:18:22Z" +
+ +
TLS_CLIENT_SERIAL_NUMBER
+
+ The certificate's serial number.
+ Example: "73629018972631" +
+ +
TLS_CLIENT_VERIFIED
+
+ Was the certificate deemed trusted by the server's certificate store.
+ 0 (not verified) / 1 (verified) +
+ +
+ ## Deployment Jetforce is intended to be run behind a process manager that handles