Request for Comments: 4387 University of Auckland
Category: Standards Track February 2006
Internet X.509 Public Key Infrastructure
Operational Protocols: Certificate Store Access via HTTP
Status of This Memo
This document specifies an Internet standards track protocol for the
Internet community, and requests discussion and suggestions for
improvements. Please refer to the current edition of the "Internet
Official Protocol Standards" (STD 1) for the standardization state
and status of this protocol. Distribution of this memo is unlimited.
Copyright Notice
Copyright (C) The Internet Society (2006).
Abstract
The protocol conventions described in this document satisfy some of
the operational requirements of the Internet Public Key
Infrastructure (PKI). This document specifies the conventions for
using the Hypertext Transfer Protocol (HTTP/HTTPS) as an interface
mechanism to obtain certificates and certificate revocation lists
(CRLs) from PKI repositories. Additional mechanisms addressing PKIX
operational requirements are specified in separate documents.
Table of Contents
1. Introduction ....................................................2
2. HTTP Certificate Store Interface ................................3
2.1. Converting Binary Blobs into Search Keys ...................4
2.2. Attribute Types: X.509 .....................................5
2.3. Attribute Types: PGP .......................................6
2.4. Attribute Types: XML .......................................6
2.5. Implementation Notes and Rationale .........................6
2.5.1. Identification ......................................7
2.5.2. Checking of Input Values ............................9
2.5.3. URI Notes ..........................................10
2.5.4. Responses ..........................................11
2.5.5. Performance Issues .................................12
2.5.6. Miscellaneous ......................................13
2.6. Examples ..................................................14
3. Locating HTTP Certificate Stores ...............................15
3.1. Information in the Certificate ............................15
3.2. Use of DNS SRV ............................................16
3.2.1. Example ............................................16
3.3. Use of a "well-known" Location ............................16
3.3.1. Examples ...........................................17
3.4. Manual Configuration of the Client Software ...............18
3.5. Implementation Notes and Rationale ........................18
3.5.1. DNS SRV ............................................18
3.5.2. "well-known" Locations .............................19
3.5.3. Information in the Certificate .....................19
3.5.4. Miscellaneous ......................................20
4. Security Considerations ........................................20
5. IANA Considerations ............................................22
6. Acknowledgements ...............................................22
7. References .....................................................22
7.1. Normative References ......................................22
7.2. Informative References ....................................23
1. Introduction
This specification is part of a multi-part standard for the Internet
Public Key Infrastructure (PKI) using X.509 certificates and
certificate revocation lists (CRLs). This document specifies the
conventions for using the Hypertext Transfer Protocol (HTTP), or
optionally, HTTPS as an interface mechanism to obtain certificates or
public keys, and certificate revocation lists (CRLs), from PKI
repositories. Throughout the remainder of this document the generic
term HTTP will be used to cover either option.
Although RFC 2585 [RFC2585] covers fetching certificates via HTTP,
this merely mentions that certificates may be fetched from a static
URL, which doesn’t provide any general-purpose interface capabilities
to a certificate store. The conventions described in this document
allow HTTP to be used as a general-purpose, transparent interface to
any type of certificate or key store including flat files, standard
databases such as Berkeley DB and relational databases, and
traditional X.500/LDAP directories. Typical applications would
include use with web-enabled relational databases (which most
databases are) or simple {key,value} lookup mechanisms such as
Berkeley DB and its various descendants.
Additional mechanisms addressing PKIX operational requirements are
specified in separate documents.
The key words "MUST", "MUST NOT", "REQUIRED", "SHOULD", "SHOULD NOT",
"RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be
interpreted as described in [RFC2119].
2. HTTP Certificate Store Interface
The GET method is used in combination with an HTTP query URI
[RFC2616] to retrieve certificates from the underlying certificate
store:
http_URL = "http:" "//" host [ ":" port ] [ abs_path [ "?" query ]]
The parameters for the query portion of the URI are a certificate or
key identifier consisting of an attribute type and a value that
specifies one or more certificates or public keys to be returned from
the query:
query = attribute ’=’ value
Certificates and public keys are retrieved from one URI (the
certificate URI) and CRLs from another URI (the revocation URI).
These may or may not correspond to the same certificate store and/or
server (the exact interpretation is a local configuration issue).
The query value MUST be encoded using the form-urlencoded media type
[RFC2854]. Further details of URI construction, size limits, and
other factors are given in [RFC2616].
Responses to unsuccessful queries (for example, to indicate a non-
match or an error condition) are handled in the standard manner as
per [RFC2616]. Clients should in particular be aware that in some
instances servers may return HTTP type 3xx redirection requests to
explicitly redirect queries to another server. Obviously, implicit
DNS-based redirection is also possible.
If more than one certificate matches a query, it MUST be returned as
a multipart/mixed response. The returned data MUST be returned
verbatim; it MUST NOT use any additional content- or transfer-
encoding at the HTTP level (for example, it can’t be compressed or
encoded as base64 or quoted-printable text). Implementations SHOULD
NOT use chunked encoding in responses.
The query component of the URI MAY optionally contain additional
attribute/value pairs separated by the standard ampersand delimiter
’&’ that specify further actions to be taken by the certificate
store. Certificate stores SHOULD ignore any additional unrecognised
attribute/value pairs present in the URI.
Other information, such as naming conventions and MIME types, is
specified in [RFC2585] (with additional MIME types for non-X.509
content in [RFC3156] and [RFC3275]).
2.1. Converting Binary Blobs into Search Keys
Some fields (indicated by the "Process" column in the tables below)
are of arbitrary length and/or contain non-textual data. Both of
these properties make them unsuited for direct use in HTTP queries.
In order to make them usable, fields for which the processing option
is "Hash" are first hashed down to a fixed-length 160-bit value.
Fields for which the processing option is "Hash" or "Base64" are
base64-encoded to transform the binary data into textual forms:
Processing Processing step
option
"Hash" Hash the key value using SHA-1 [FIPS180] to produce a
160-bit value, then continue with the base64 encoding
step that follows.
"Hash" Encode the binary value using base64 encoding to produce
"Base64" a 27-byte text-only value. Base64 encoding of the 20
byte value will produce 28 bytes, and the last byte will
always be a ’=’ padding character. The 27-byte value is
created by dropping the trailing ’=’ character.
For cases where the binary value is smaller or larger than the 20-
byte SHA-1 output (for example, with 64-bit/8 byte PGP key IDs), the
final value is created by removing any trailing ’=’ padding from the
encoding of the binary value (this is a generalisation of the above
case).
Implementations MUST verify that the base64-encoded values submitted
in requests contain only characters in the ranges ’a’-’z’, ’A’-’Z’,
’0’-’9’, ’+’, and ’/’. Queries containing any other character MUST
be rejected. (See the implementation notes in Section 2.5 and the
security considerations in Section 4 for more details on this
requirement.)
2.2. Attribute Types: X.509
Permitted attribute types and associated values for use with X.509
certificates and CRLs are described below. Arbitrary-length binary
values (as indicated in the table below) are converted into a search
key by the process described in Section 2.1. Note that the values
are checked for an exact match (after decoding of any form-urlencoded
[RFC2854] portions if this is necessary) and are therefore case
sensitive.
Attribute Process Value
--------- ------- -----
certHash Hash Search key derived from the SHA-1 hash of the
certificate (sometimes called the certificate
fingerprint or thumbprint).
uri None Subject URI associated with the certificate,
without the (optional) scheme specifier. The URI
type depends on the certificate. For S/MIME
certificates, it would be an email address; for
SSL/TLS certificates, it would be the server’s DNS
name (this is usually also specified as the
CommonName); for IPsec certificates, it would be
the DNS name/IP address; and so on.
iHash Hash Search key derived from the DER-encoded issuer DN
as it appears in the certificate, CRL, or other
object.
iAndSHash Hash Search key derived from the certificate’s
DER-encoded issuerAndSerialNumber [RFC3852].
name None Subject CommonName contained in the certificate.
sHash Hash Search key derived from the DER-encoded subject
DN as it appears in the certificate or other
object.
sKIDHash Hash Search key derived from the certificate’s
subjectKeyIdentifier (specifically the contents
octets of the KeyIdentifier OCTET STRING).
Certificate URIs MUST support retrieval by all the above attribute
types.
CRL URIs MUST support retrieval by the iHash and sKIDHash attribute
types, which identify the issuer of the CRL. In addition, CRL URIs
MAY support retrieval by certHash and iAndSHash attribute types, for
cases where this is required by the use of the
issuingDistributionPoint extension. A CRL query MUST return the
matching CRL with the greatest thisUpdate value (in other words, the
most recent CRL).
2.3. Attribute Types: PGP
Permitted attribute types and associated values for use with PGP
public keys and key revocation information are described below.
Binary values (as indicated in the table below) are converted into a
search key by the process described in Section 2.1.
Attribute Process Value
--------- ------- -----
email None email address associated with the key.
fingerprint Base64 160-bit PGP key fingerprint [RFC2440].
keyID Base64 64-bit PGP key ID [RFC2440].
name None User name associated with the key.
Key URIs MUST support retrieval by all of the above attribute types.
Revocation URIs MUST support retrieval by the fingerprint and keyID
attribute types, which identify the issuer of the key revocation.
2.4. Attribute Types: XML
Permitted attribute types and associated values for use with XML are
as specified in sections 2.2 and 2.3. Since XML allows arbitrary
attributes to be associated with the <RetrievalMethod> child element
of <KeyInfo> [RFC3275], there are no additional special requirements
for use with XML.
2.5. Implementation Notes and Rationale
This informative section documents the rationale behind the design in
Section 2 and provides guidance for implementors.
2.5.1. Identification
The identifiers are taken from PKCS #15 [PKCS15], a standard that
covers (among other things) a transparent interface to a
certificate/public key store. These identifiers have been field
proven, as they have been in common use for a number of years,
typically via PKCS #11 [PKCS11]. Certificate stores and the
identifiers that are required for typical certificate lookup
operations are analysed in some detail in [Gutmann].
The URI identifier type specifies the identifier associated with the
certificate’s intended usage with a given Internet security protocol.
For example, an SSL/TLS server certificate would contain the server’s
DNS name (this is traditionally also specified as the CommonName or
CN) an S/MIME certificate would contain the subject’s email address;
an IPsec certificate would contain a DNS name or IP address; and a
SIP certificate would contain a SIP URI. A modicum of common sense
is assumed when deciding upon an appropriate URI field value.
For historical reasons going back to its primary use as a means of
looking up users’ S/MIME email certificates, some clients may specify
the URI attribute name as "email" rather than "uri". Although not
required by this specification, servers may choose to allow the use
of "email" as an alias for "uri".
In addition, it is common practice to use the Internet identifier
associated with the certificate’s intended field of application as
the CN for the certificate when this is the most sensible name for
the certificate subject. For example, an SSL/TLS server certificate
will contain the server’s DNS name in the CN field. In web-enabled
devices, this may indeed be the only name that exists for the device.
It is therefore quite possible that the URI will duplicate the CN,
and that it may be the only identifier present (that is, there’s no
full DN but only a single CN field).
By long-standing convention, URIs in certificates are given without a
scheme specifier. For example, an SSL/TLS server certificate would
contain www.example.com rather than https://www.example.com, and an
S/MIME certificate would contain user@example.com rather than
mailto:user@example.com. This convention is extended to other URI
types as well, so that a certificate containing the (effective) URIs
im:user@example.com and xmpp:user@example.com would be queried using
the single URI user@example.com. The certificate store would then
return all certificates containing this URI, leaving it to the client
to determine which one is most appropriate for its use. This
approach is taken both because for the most common URI types there’s
no schema specifier (see the paragraphs above) and no easy way to
determine what the intended use is (an SSL/TLS server certificate is
simply one presented by an SSL/TLS server), and because the relying
party/client is in a better position to judge the certificate’s most
appropriate use than the certificate store server.
Another possible identifier that has been suggested is an IP address
or DNS name, which will be required for web-enabled embedded devices.
This is necessary to allow for example a home automation controller
to be queried for certificates for the devices that it controls.
Since this value is regarded as the CN for the device, common
practice is to use this value for the CN in the same way that web
server certificates set the CN to the server’s DNS name, so this
option is already covered in a widely-accepted manner.
The name and email address are an exact copy of what is present in
the certificate, without any canonicalisation or rewriting (other
than the transport encoding required by HTTP). This follows standard
implementation practice, which transfers an exact copy of these data
items in order to avoid problems due to character set translation,
handling of whitespace, and other issues.
Hashes are used for arbitrary-length fields such as ones containing
DNs in place of the full field to keep the length manageable. In
addition, the use of the hashed form emphasizes that searching for
structured name data isn’t a supported feature, since this is a
simple interface to a {key,value} certificate store rather than an
HTTP interface to an X.500 directory. Users specifically requiring
an HTTP interface to X.500 may use technology such as HTTP LDAP
gateways for this purpose.
Although clients will always submit a fixed 160-bit value, servers
are free to use as many bits of this value as they require. For
example, a server may choose to use only the first 40, 64, 80, or 128
bits for efficiency in searching and maintaining indices.
PGP has traditionally encoded IDs using a C-style 0xABCDEF notation
based on the display format used for IDs in PGP 2.0. Unfortunately,
strings in this format are also valid strings in the base64 format,
complicated further by the fact that near-misses such as 0xABCDRF
could be either a mistyped attempt at a hex ID or a valid base64 ID.
For this reason, and to ensure consistency, base64 IDs are used
throughout this specification. The search keys used internally will
be binary values, so whether these are converted from ASCII-hex or
base64 is immaterial in the long run.
The attributes are given shortened name forms (for example, iAndSHash
in place of issuerAndSerialNumberHash) in order to keep the lengths
reasonable, or common name forms (for example, email in place of
rfc822Name, rfc822Mailbox, emailAddress, mail, or email) where
multiple name forms exist.
In some cases, users may require additional, application-specific
attribute types. For example, a healthcare application that uses a
healthcare ID as the primary key for its databases may require the
ability to perform certificate lookups based on this healthcare ID.
The formatting and use of such application-specific identifiers is
beyond the scope of this document. However, they should begin with
’x-’ to ensure that they don’t conflict with identifiers that may be
defined in future versions of this specification.
2.5.2. Checking of Input Values
The attribute value portion of the identifier should be carefully
checked for invalid characters since allowing raw data presents a
security risk. Consider, for example, a certificate/public key store
implemented using an RDBMS in which the SQL query is built up as
"SELECT certificate FROM certificates WHERE iHash = " + <search key>.
If <search key> is set to "ABCD;DELETE FROM certificates", the
results of the query will be quite different from what was expected
by the certificate store administrators. Even a read-only query can
be problematic; for example, setting <search key> to "UNION SELECT
password FROM master.sysxlogins" will list all passwords in an SQL
Server database (in an easily-decrypted format) if the user is
running under the sa (DBA) account. For this reason, only valid
base64 encodings should be allowed. The same checking applies to
queries by name or email address.
Straightforward sanitisation of queries may not be sufficient to
prevent all attacks; for example, a filter that removes the SQL query
string "DELETE" can be bypassed by submitting the string embedded in
another instance of the string. Removing "DELETE" from
"DELDELETEETE" leaves the outer "DELETE" in place. Abusing the
truncation of over-long strings by filters can also be used as a
means of attack, with the attacker ensuring that the truncation
occurs in the middle of an escape sequence, bypassing the filtering.
Although in theory recursive filtering may help here, the use of
parameterised queries (often called placeholders) that aren’t
vulnerable to SQL injection should be used to avoid these attacks.
More information on securing database back-ends may be found in
[Birkholz], and more comments on sanitisation and safety concerns may
be found in the security considerations section.
2.5.3. URI Notes
Pre-constructed URIs that fetch a certificate/public key matching a
fixed search criterion may be useful for items such as web pages or
business cards, or even for technical support/helpdesk staff who want
to mail to users but can’t find the certificate themselves. These
URIs may also be used to enforce privacy measures when distributing
certificates by perturbing the search key in a manner known only to
the certificate/public key store, or to the certificate store and
users (in other words, by converting the URI into a capability). For
example, a user with a newly-issued certificate could be instructed
to fetch it with a key of "x-encrCertHash=...", which is decrypted by
the certificate store to fetch the appropriate certificate, ensuring
that only the certificate owner can fetch their certificate
immediately after issue. Similarly, an organisation that doesn’t
want to make its certificates available for public query might
require a MAC on search keys (e.g., "x-macCertHash=...") to ensure
that only authorised users can search for certificates (although a
more logical place for access control, if a true web server is being
used to access the store, would obviously be at the HTTP level).
The query types have been specifically chosen to be not just an HTTP
interface to LDAP but a general-purpose retrieval mechanism that
allows arbitrary certificate/public key storage mechanisms (with a
bias towards simple {key,value} stores, which are deployed almost
universally, whether as ISAM, Berkeley DB, or an RDBMS) to be
employed as back-ends. This specification has been deliberately
written to be technology neutral, allowing any {key,value} lookup
mechanism to be used. It doesn’t matter if you choose to have
trained chimpanzees look up certificates in books of tables, as long
as your method can provide the correct response with reasonable
efficiency.
Certificate/public key and CRL stores are allocated separate URIs
because they may be implemented using different mechanisms. A
certificate store typically contains large numbers of small items,
while a CRL store contains a very small number of potentially large
items. By providing independent URIs, it’s possible to implement the
two stores using mechanisms tailored to the data they contain.
PGP combines key and revocation information into a single data object
so that it’s possible to return both public keys and revocation
information from the same URI. If distinct key and revocation
servers are available, these can provide a slight performance gain
since fetching revocation information doesn’t require fetching the
key that it applies to. If no separate servers are available, a
single server can be used to satisfy both types of queries with a
slight performance loss, since fetching revocation information will
also fetch the public key data associated with the revocation data.
2.5.4. Responses
The disallowance of exotic encoding forms reflects the fact that most
clients (and many servers, particularly for embedded devices) are not
general-purpose web browsers or servers capable of handling an
arbitrary range of encoding forms and types, but simply basic HTTP
engines attached to key management applications. In other words, the
HTTP interface is a rudimentary add-on to a key management
application, rather than key-management being an add-on to a
general-purpose web client or server. Eliminating unnecessary
choices simplifies the implementation task and reduces code size and
complexity, with an accompanying decrease in the probability of