[[PageOutline]]
= HTTPS for all MF/PL members =

Every website hosted by MF/PL should provide HTTPS access.  It should also be simple for members to update their web site to require HTTPS.

[ticket:5561 This is a work in progress].  This documentation is for server administrators to understand what's going on.  Regular MF/PL members shouldn't need to learn these details (but i'm happy if they want to!)

== canonical key, certificate, and CSR locations on MOSHes ==

Each MOSH should have a separate key for each web site it hosts.  Those keys should be stored in a predictable place.  The active X.509 certificate associated with that key should also be stored in a reasonable place, as should any needed intermediate certificates.  The MOSH should also be willing to createa reasonable CSR for any web site it controls and make that CSR available to the member.

I propose the following locations, all derived from the numeric ID of the red "web configuration" object, represented here as WEBID:

 secret key:: `/etc/ssl/private/member_keys/WEBID.key`
 server certificate (cert):: `/etc/ssl/member_certs/WEBID_cert.pem`
 certificate signing request (CSR):: `/etc/ssl/member_csrs/WEBID.csr`
 intermediate CA certs (iCAs):: `/etc/ssl/member_certs/WEBID_intermediates.pem`
 backups:: Automatically backed-up files would go in `/etc/ssl/mfpl-backups/` and would have the timestamp (to 1Hz precision, ISO-8601 format) of the backup prefixed to their name with a dot (e.g. `/etc/ssl/mfpl-backups/2012-05-23_03:32:55.WEBID_cert.pem`)

A mosh would examine its list of active web configurations from red.  for each webconfig WC, with numeric ID WEBID, it would scan these files for trouble, creating or generating them as needed.

=== Secret key ===
Creation:
 * create the file, ownership root:root, mode 0400
 * if apache config stanza contains [https://httpd.apache.org/docs/2.2/mod/mod_ssl.html#sslcertificatekeyfile SSLCertificateKeyFile], copy the contents from there.
 * otherwise, generate and store a 2048-bit RSA key, no passphrase

Mandatory checks:
 * permission should be 0400, owned by root (otherwise: report an error and fix the ownership and mode)
 * must parse as a valid PEM-encoded, passphraseless secret key (otherwise: backup and regenerate)

Optional checks:
 * the secret key should be RSA, 2048 bits (otherwise: report an error)

=== Server Certificate ===
Creation:
 * create the file, ownership root:root, mode 0400
 * if apache config stanza contains [https://httpd.apache.org/docs/2.2/mod/mod_ssl.html#sslcertificatefile SSLCertificateFile], copy the contents from there.
 * if the red web configuration object contains a blob for the Server Certificate, verify the cert against the mandatory checks below, and place the blob's contents into the file if they pass (report an error if they don't all pass).
 * generate and store a self-signed cert from the secret key with a Subject of CN=ServerName, and subjectAltName extensions of dNSNames pointing to ServerName and every ServerAlias.

Mandatory checks (unless otherwise noted, if these checks fail, the certificate should be backed up and replaced with a re-generated self-signed cert):
 * owned by root, mode 0444 (otherwise: report an error and fix the ownership and mode)
 * must parse as a single PEM-encoded X.509 certificate
 * the public key contained in the cert should match the public key of the secret key
 * the cert's Subject should have a leaf CN that matches the web configuration's ServerName directive
 * the cert's X.509v3 extensions should include a subjectAltName field of type dNSName that matches the web configuration's ServerName directive
 * the cert's creation date should be in the past.
 * the cert's certificateKeyUsage must include Signing and Key Encipherment
 * the cert's extendedKeyUsage must include TLS Web Server Authentication (OID 1.3.6.1.5.5.7.3.1)

Optional checks:
 * the cert's X.509v3 extensions should include a subjectAltName field of type dNSName that matches each of the items in the web configuration's ServerAlias directive. (otherwise: one-time warning?  we don't want to hassle people about example.mayfirst.org not being included in a cartel-issued cert)
 * the cert's expiration date should be in the future (otherwise: warning)
 * OCSP/CRL checking?

=== Certificate Signing Request ===
Creation:
 * generate and store a CSR with:
  * DN of `/CN=ServerName/`
  * subjectAltName extensions of dNSNames pointing to ServerName and every ServerAlias
  * certificateKeyUsage includes Signing and Key Encipherment
  * extendedKeyUsage of TLS Web Server Authenicatiyon (OID 1.3.6.1.5.5.7.3.1)

Mandatory checks (if any of these checks fail, the CSR should be backed up and replaced with a re-generated CSR):
 * the public key contained in the CSR should match the public key of the secret key
 * the CSR's Subject should have a leaf CN that matches the web configuration's ServerName directive
 * the CSR's X.509v3 extensions should include a subjectAltName field of type dNSName that matches the web configuration's ServerName directive
 * the CSR's creation date should be no older than 1 year ago
 * the CSR's creation date should be in the past.

=== Intermediate CA certificates ===
Creation:
 * if apache config stanza contains [https://httpd.apache.org/docs/2.2/mod/mod_ssl.html#sslcertificatechainfile SSLCertificateChainFile], copy the contents from there.

Mandatory checks (if any of these fail, report an error, back the file up, and truncate it to zero length):
 * must be a list of 0 or more PEM-encoded CAs
 * must start with a CA certifying the Server Certificate
 * each subsequent CA must certify the CA before it

Optional checks (report an error):
 * Must not include any self-signed certificates

== mosh server changes ==

Perhaps we want to expose `/etc/ssl/member_csrs` directly to the web under the mosh's canonical hostname?  That way we could link to them directly (or include them in an iframe) in the control panel's web UI.

== red changes ==

Once the above files are populated on every server, we need to change red's web configuration items:

 * SSLCertificate* directives should not be allowed in the apache stanza, but should be auto-generated for https web configs
 * SSLEngine directive should not be allowed in the apache stanza, but should be auto-generated for https web configs
 * display of a web configuration item should include a link or iframe containing the CSR
 * editing a web configuration should add a textarea for pasting in a Server Certificate
 * update of an apache config stanza should cause the above checks to be run on the node for the modified web configuration

If the above can all happen smoothly, the next steps would be:

 * remove the http/https option for the web configuration object
 * auto-generate duplicate apache stanzas from web configuration object: one for port 80, one for port 443.
 * port 443 stanza should include additional `SSLEngine On` and SSLCertificate* directives.
 * add new "https" dropdown, with three options: enabled, enforced, permanent (see below for meaning)

=== new HTTPS option ===
this new option for the web configuration object should have three states:

  enabled:: normal port 80 config stanza
  enforced:: port 80 stanza retains only ServerName and ServerAlias options from apache config, adds auto-generated mod_rewrite rules to send the user's browser to `https://$ServerName`
  permanent:: as with "enforced", but also adds a Strict-Transport-Security header with a 6-month duration

== Toolchain ==

At the moment, i lean toward perl as the language to do this in.  I have no idea how to integrate that cleanly with red.

== Status ==

None of this is implemented yet, alas.

== Unhandled Scenarios/future work ==

As of yet, there are a few corner cases this scheme doesn't permit.

=== CSRs that need to embed a challenge ===

I have yet to encounter a reasonably-priced CA that requires these for certificate issuance

=== Wildcard Certs ===

Maybe we can handle this as a special case?  How many of these do we currently support on moshes?

=== sites with multiple, non-wildcard names that want distinct certs ===

I don't think we should even try to support this use case.  The member can simply make a new web config in this scenario.

=== Embedding OpenPGP indicators ===

It's not clear to me whether the auto-generated certificates and CSRs should contain the [http://www.imc.org/ietf-openpgp/mail-archive/msg05320.html PGPExtension] or [https://lists.riseup.net/www/arc/monkeysphere/2011-03/msg00027.html the NullSignatureUseOpenPGP extension].  Doing so would be a nice way to extend monkeysphere access on all MF/PL machines, though.

=== using MF/PL CA for initial Server Certificates ===

We don't need to just use self-signed certs for the initial setup; we could also sign them with the MF/PL CA, or with a subordinate CA for that purpose.