SNIF Certificate Authority Proxy Protocol

Jim Zubov <jz&vesvault.com> VESvault Corp.

Overview

This document specifies a protocol for securely acquiring and maintaining a publicly trusted TLS/SSL X.509 certificate issued by a Certificate Authority to a uniquely allocated hostname, by an agent that has no direct control over that hostname, or over a server the hostname is pointing to.

SNIF CA Proxy Protocol is designed to be used in conjunction with SNIF Relay.

SNIF CA Proxy is a combination of web-based services and background processes that run on a publicly accessible server, normally on the same physical server as SNIF Relay.

SNIF Connector is a process that runs on an IoT device, or on other type of device that provides TLS-based services through SNIF.

Certificate Authority (CA) is a service that issues public trusted TLS Certificates to specific hostnames when requested by the hostname owner, upon validating the ownership of the hostname.

Protocol Summary

SNIF CA Proxy accepts requests from SNIF Connectors via HTTP / HTTPS.

SNIF CA Proxy interacts with the CA using protocols defined by the CA, such as ACME, not covered by this document.

SNIF Connector is configured with a specific initiation URL ({initUrl}), which is specific to the SNIF CA Proxy server the Connector intends to work with. Depending on the CA Proxy rules, {initUrl} might be unique for each Connector, or common for multiple Connectors.

Protocol Flow

Upon the initial start or after a hard reset, the Connector MUST generate a Private Key, which needs to be securely permanently stored by the Connector. Any key algorithm acceptable by the CA can be used, generally RSA-4096 is recommended.

The Connector MUST send a CN Allocation Request using the {initUrl}.

Having the {cn}, the Connector MUST generate a CSR using the Private Key, the subject containing the {cn}. The CSR subject may or may not have other fields besides {cn}, according to the specific requirements of the CA.

The Connector MUST issue a CSR Submission Request to send the CSR to the CA Proxy.

Once the CSR is submitted, the Connector MUST permanently store the {cn} by some means – to minimize the storage compartments it might be practical to generate and store a dummy self-signed certificate with the {cn} in the subject until it gets replaced with a trusted certificate issued by the CA.

A this point, the Connector will normally know the SNIF hostname it will be using with the SNIF Relay – it matches the {cn} in case of a single host CN, or is a one sub-level down from a wildcard {cn}, the name being derived by the Connector in a way that is not deterministically derivable from the {cn}, e.g. a hash of the Private Key. The connector SHOULD communicate the hostname by some means to the SNIF Clients that will be accessing the Connector. The means of such communication is not covered by this document.

The Connector can now send a Certificate Download Request, and SHOULD verify the returned Certificate. If the Certificate is valid – the Connector MUST permanently store it.

If the Certificate Download Request fails – the Connector should repeat the request after certain delay. In case if the response was 401 and the {authUrl} is returned in a header, and the Connector has the means of communicating with the device user – the Connector also SHOULD alert the user and bring {authUrl} to their attention by some means, so the user can complete the required authorization steps. If the Connector has no means of alerting the user, which is often the case with IoT devices – the user should be provided with some external means of authorizing with the CA Proxy, not covered by this domcument.

Once the Certificate is stored, the Connector is capable of terminating SNIF connections, and may proceed launching a SNIF Control Connection.

The Connector SHOULD watch for the expiration of the stored Certificate. If the Certificate is about to expire in 7 days or less, or has already expired – the Connector SHOULD send a Certificate Download Requests, and repeat with appropriate delays until the renewed Certificate is successfully downloaded and verified.

At any stage of the flow, if the Connector receives unexpected volume of rejections or inconsistent responses from the CA Proxy, the Connector MAY decide to hard reset the storage and start the flow over from the beginning. In such case, the Connector will have to re-send its new SNIF hostname to any concerned SNIF Clients, the means of such communication is not covered by this document.

CN Allocation Request

Connection from: SNIF Connector.

Connection to: SNIF CA Proxy.

Protocol: https or http.

GET {initUrl}

Response 200: CN is successfully allocated. The response headers MUST include X-SNIF-CN: with the value of the allocated {cn}, either a wildcard starting with "*.", or a single hostname, depending on the CA Proxy rules. The response content type SHOULD by text/plain, the response body SHOULD include the copy of the allocated {cn}, optionally padded with newlines or spaces on the right.

Any other response: Error, try again later.

CSR Submission Request

Connection from: SNIF Connector.

Connection to: SNIF CA Proxy.

Protocol: http.

PUT http://{cn_host}/snif-cert/{cn_host}.csr
Content-Type: application/pkcs10

{cn_host} is a hostname derived from the {cn} – it is identical to {cn} in case of a single-host CN, or is the {cn} with truncated initial "*." in case of a wildcard CN.

The request body MUST contain a PEM encoded PKCS#10 CSR, the newlines are either <CR><LF> or <LF>, the maximum length of the body is 16384 bytes.

Note that a CSR for the specific allocated CN can be submitted to the CA Proxy once in a lifetime. In case of an incorrect submission the Connector should hard reset the storage and restart the flow from the beginning, including allocating a new CN.

Response 201: the CSR is successfully submitted. The response headers MAY include X-SNIF-AuthUrl: with the value of an {authUrl}, that SHOULD, if possible, be communicated to the user to authorize the certificate issuance.

Response 403: the CSR for this CN has already been submitted, or is denied by the CA Proxy rules. If the Connector receives 403, is SHOULD hard reset the storage and restart the CA Proxy flow from the beginning.

Response 404: the CN was not allocated.

Any other response: Error, try again later.

Certificate Download Request

Connection from: SNIF Connector.

Connection to: SNIF CA Proxy.

Protocol: http.

GET http://{cn_host}/snif-cert/{cn_host}.crt

{cn_host} is a hostname derived from the {cn} – it is identical to {cn} in case of a single-host CN, or is the {cn} with truncated initial "*." in case of a wildcard CN.

The CA Proxy SHOULD check for a cached previously generated Certificate chain for the {cn}. If the cached Certificate chain is found and if it expires in more that 10 days in the future – the cached Certificate chain SHOULD be returned with status 200. Otherwise, if the {cn} has a valid CSR and a proper authorization to issue a certificate – the CA Proxy SHOULD return status 503 and SHOULD launch a background process that communicates with the CA to issue or renew the certificate, and caches the issued Certificate chain for subsequent Certificate Download Requests.

Response 200: the Certificate chain is returned. The Content-Type of such response SHOULD be application/x-x509-ca-cert. The response body MUST by a PEM encoded X.509 certificate chain, the issued certificate being the first member, the newlines are either <CR><LF> or <LF>, the length of the body SHOULD NOT exceed 65535 bytes.

Response 503: the Certificate is being issued, try later.

Response 401: Certificate issuance authorization is required. The response headers MAY include X-SNIF-AuthUrl: with the value of an {authUrl}, that SHOULD, if possible, be communicated to the user to authorize the certificate issuance. If the Connector cannot communicate with the user, the CA Proxy should include external means of the authorization, not covered by this document.

Response 404: the CN was not allocated, or the CSR was not submitted.

Any other response: Error, try again later.

Security Considerations

All information communicated over plain unencrypted HTTP is safe to be exposed to third parties or to intruders without compromising any private information.