Credentials

If the Configuration Document contains an enrollment-server element, credentials are REQUIRED to join the Overlay Instance. A peer which does not yet have credentials MUST contact the enrollment server to acquire them.

RELOAD defines its own trivial certificate request protocol. We would have liked to have used an existing protocol, but were concerned about the implementation burden of even the simplest of those protocols, such as [RFC5272] and [RFC5273]. The objective was to have a protocol which could be easily implemented in a Web server which the operator did not control (e.g., in a hosted service) and which was compatible with the existing certificate-handling tooling as used with the Web certificate infrastructure. This means

accepting bare PKCS#10 requests and returning a single bare X.509 certificate. Although the MIME types for these objects are defined, none of the existing protocols support exactly this model.

The certificate request protocol MUST be performed over HTTPS. The server certificate MUST match the overlay name as described in [RFC2818]. The request MUST be an HTTP POST with the parameters encoded as described in [RFC2388] and with the following properties:

o If authentication is required, there MUST be form parameters of "password" and "username" containing the user’s account name and password in the clear (hence the need for HTTPS). The username and password strings MUST be UTF-8 strings compared as binary objects. Applications using RELOAD SHOULD define any needed string preparation as per [RFC4013] or its successor documents.

o If more than one Node-ID is required, there MUST be a form

parameter of "nodeids" containing the number of Node-IDs required.

o There MUST be a form parameter of "csr" with a content type of "application/pkcs10", as defined in [RFC2311], that contains the certificate signing request (CSR).

o The Accept header MUST contain the type "application/pkix-cert",

The enrollment server MUST authenticate the request using the provided account name and password. The reason for using the RFC 2388 "multipart/form-data" encoding is so that the password parameter will not be encoded in the URL, to reduce the chance of accidental leakage of the password. If the authentication succeeds and the requested user name in the CSR is acceptable, the server MUST

generate and return a certificate for the CSR in the "csr" parameter of the request. The SubjectAltName field in the certificate MUST contain the following values:

o One or more Node-IDs which MUST be cryptographically random

[RFC4086]. Each MUST be chosen by the enrollment server in such a way that it is unpredictable to the requesting user. For example, the user MUST NOT be informed of potential (random) Node-IDs prior to authenticating. Each is placed in the subjectAltName using the uniformResourceIdentifier type, each MUST contain RELOAD URI, as described in Section 14.15, and each MUST contain a Destination List with a single entry of type "node_id". The enrollment server SHOULD maintain a mapping of users to Node-IDs and if the same user returns (e.g., to have their certificate re-issued), the enrollment server should return the same Node-IDs, thus avoiding the need for implementations to re-store all their data when their certificates expire.

o A single name (the "user name") that this user is allowed to use in the overlay, using type rfc822Name. Enrollment servers SHOULD take care to allow only legal characters in the name (e.g., no embedded NULs), rather than simply accepting any name provided by the user. In some usages, the right side of the user name will match the overlay name, but there is no requirement for this match in this specification. Applications using this specification MAY define such a requirement or MAY otherwise limit the allowed range of allowed user names.

The SubjectAltName field in the certificate MUST NOT contain any identities other than those listed above. The subject distinguished name in the certificate MUST be empty.

The certificate MUST be returned as type "application/pkix-cert", as defined in [RFC2585], with an HTTP status code of 200 OK.

Certificate processing errors SHOULD result in an HTTP return code of 403 Forbidden, along with a body of type "text/plain" and body that consists of one of the tokens defined in the following list:

failed_authentication

The account name and password combination used in the HTTPS request was not valid.

username_not_available

The requested user name in the CSR was not acceptable.

Node-IDs_not_available

The number of Node-IDs requested was not acceptable.

bad_CSR

There was some other problem with the CSR.

If the client receives an unknown token in the body, it SHOULD treat it as a failure for an unknown reason.

The client MUST check that the returned certificate chains back to one of the certificates received in the "root-cert" list of the overlay configuration data (including PKIX BasicConstraints checks).

The node then reads the certificate to find the Node-ID it can use.

11.3.1. Self-Generated Credentials

If the "self-signed-permitted" element is present in the

configuration and is set to "true", then a node MUST generate its own self-signed certificate to join the overlay. The self-signed

certificate MAY contain any user name of the user’s choice.

For self-signed certificates containing only one Node-ID, the Node-ID MUST be computed by applying the digest specified in the permitted element to the DER representation of the user’s public key (more specifically, the subjectPublicKeyInfo) and taking the order bits. For self-signed certificates containing multiple

Node-IDs, the index of the Node-ID (from 1 to the number of Node-IDs needed) must be prepended as a 4-byte big-endian integer to the DER representation of the user’s public key and taking the high-order bits. When accepting a self-signed certificate, nodes MUST check that the Node-ID and public keys match. This prevents Node-ID theft.

Once the node has constructed a self-signed certificate, it MAY join the overlay. It MUST store its certificate in the overlay

(Section 8), but SHOULD look to see if the user name is already taken and, if so, choose another user name. Note that this provides

still possible. If protection against name theft is desired, then the enrollment service MUST be used.