Security
Based on the fundamentals of the HANDLE service all authenticated transactions must use HTTPS. Over HTTP authentication is ignored and requests which require authorization return 403 Forbidden.
Handle-Based Certificates#
Requests over HTTPS involve certificates, but generally self-signed certificates which wrap public keys stored in the handle records. A handle server’s SSL certificate, for instance, will generally be a self-signed certificate where the public key is the public key from the handle server’s siteinfo (HS_SITE handle value). Client applications should authenticate the servers they contact, by comparing the public key in the server certificate with the public key in the previously obtained HS_SITE information for the server. Since browser-based JavaScript does not have access to the server certificate, there is another way to authenticate the server using the Authorization: Handle mechanism described below.
Client-Side Certificates#
If a client-side certificate is used, it will provide authentication for any request where an Authorization: header is not otherwise sent. This corresponds to Handle protocol HS_PUBKEY authentication. The handle identity of the caller is given as the string {index}:{handle} and must be in either a UID attribute or, if there is no UID attribute, a CN attribute in the distinguished name of the certificate subject. The public key of the certificate must correspond to the HS_PUBKEY value stored at that handle and index. A self-signed certificate is acceptable; the issuer of the certificate is ignored.
In general, handle servers do not request client-side certificates. This is to prevent unpleasant behavior in browser-based applications. A server can be asked to request a client-side certificate by sending the header
Authorization: Handle clientCert="true"
To ask the handle server to renegotiate an existing HTTPS connection, such as to change which client-side certificate is used, send the header
Authorization: Handle clientCert="true", renegotiate="true"
Basic Access Authentication#
Any individual request may be authenticated by sending an Authorization: Basic header. This corresponds to Handle protocol HS_SECKEY authentication. The Authorization: Basic header, as usual, takes as parameter the Base64-encoding of {username}:{password}. Here, the {username} is the usual handle identity {index}:{handle}, however, to deal with the colon, it must be percent-encoded. A minimal percent encoding is to replace every percent-sign in {handle} with %25, and then the colon between {index} and {handle} and every colon in {handle} with %3A. Characters in {handle} outside ASCII may be either percent-encoded or UTF-8-encoded before the Base64 encoding. The secret key {password} corresponds to the bytes in the HS_SECKEY value at the given index and handle; if it is considered as text it will need to be UTF-8-encoded before the Base64 encoding.
Authentication via Authorization: Handle#
A challenge-response framework based on Handle protocol authentication is available. It is the only option for HS_PUBKEY authentication in environments which can not easily specify client-side certificates (as in cross-origin browser-based JavaScript). This framework uses Authorization: Handle and WWW-Authenticate: Handle headers which contain parameters of the form key=”value”, key=”value”. Note the HTTP headers are restricted to ASCII; the documentation below clarifies how various parameters are encoded to avoid that being a problem.