Gateway Interfaces for Gemini

[Sean Conner]

  I just finished support for SCGI for GLV-1.12556, which makes it the
second gateway interface it supports (the other being CGI).  And I feel this
is probably the time to talk variables---what informatino can be expected
for CGI and SCGI programs when then run under Gemini.  The CGI specification
[1] calls such information "meta-variables".  The SCGI specification [2]
calls them "headers".  Most people know them as "environment variables" [3],
but whatever, it would be nice to know what a gateway interface program can
expect in the way of data from the server.

  As I've mentioned before, for CGI, I follow the spec (with some minor
variations due to Gemini).  For SCGI, I decided to pass along the same
information but with a minor variation.  So, for BOTH, the data I pass
along:

	GEMINI_DOCUMENT_ROOT	Path to the domain's main content directory
	GEMINI_URL		The requested URL
	GEMINI_URL_PATH		The path portion of the requested URL
	PATH_INFO		optional per CGI
	PATH_TRANSLATED		optional per CGI
	QUERY_STRING		Query string portion of request, or "" [a]
	REMOTE_ADDR		Remote address [b]
	REMOTE_HOST		Remote hostname [b][c]
	SCRIPT_NAME		Name of the script [d]
	SERVER_NAME		Hostname of the request
	SERVER_PORT		Port number from the request
	SERVER_SOFTWARE		"GLV-1.12556/1"

	AUTH_TYPE		"Certificate" [e]
	REMOTE_USER		The subject CN from the client cert [e]

	TLS_CIPHER		TLS cipher used [e][f]
	TLS_CLIENT_HASH		TLS hash [e][f]
	TLS_CLIENT_ISSUER	The issuer field [e][f][g]
	TLS_CLIENT_ISSUER_*	Subfields from the isser (like C, CN, etc.) [e][f]
	TLS_CLIENT_NOT_AFTER	Expiration date [e][f]
	TLS_CLIENT_NOT_BEFORE	Valid date [e][f]
	TLS_CLIENT_REMAIN	Number of days until cert expires [e][f]
	TLS_CLIENT_SUBJECT	The subject field [e][f]
	TLS_CLIENT_SUBJECT_*	Subfields from the subject(like CN, etc.) [e][f][g]
	TLS_VERSION		TLS version being used [e][f]

[a]	Mandatory per RFC-3875
[b]	Mandatory per RFC-3875---the more security conscience of you might
	not like this, but in that case, I can recommend the value of
	"127.0.0.1" or "::1" 
[c]	Can be the IP address, which is what I do
[d]	In my case, it's the full path to the file (CGI) or symbolic link
	(SCGI) 
[e]	Only set if a client certificate is sent
[f]	Only set if configured to do so.
[g]	For example, TLS_CLIENT_SUBJECT_CN, TLS_CLIENT_SUBJECT_OU

  I added GEMINI_DOCUMENT_ROOT to mimic Apache's DOCUMENT_ROOT, and
GEMINI_URL and GEMINI_URL_PATH because I found a few servers that defined
GEMINI_URL and passed either the full URL or the path portion, and I wanted
to cover both cases with something.

  For CGI, the program will also receive the following variable:

	GATEWAY_INTERFACE	"CGI/1.1" (mandatory per RFC-3875)

  And for SCGI, the program will receive the following variables:

	CONTENT_LENGTH		"0" (mandatory per spec)
	SCGI			"1" (mandatory per spec)

  Why SCGI didn't use GATEWAY_INTERFACE="SCGI/1" is beyond me, but anyway,
there's the variables I pass along for both CGI and SCGI.  You can see
actual values used by following these links:

	gemini://gemini.conman.org/cgi/test
	gemini://gemini.conman.org/cgi/test/path/file
	gemini://gemini.conman.org/scgi-sample
	gemini://gemini.conman.org/scgi-sample/path/file

  If you see some extra data, it's because I allow extra values to be set.

  And my question to you is---what variables should a CGI/SCGI program
depend upon to exist?

  -spc

[1]	RFC-3875

[2]	https://web.archive.org/web/20020403050958/http://python.ca/nas/scgi/protocol.txt

[3]	Because how they're passed to CGI scripts.