Internet Draft                                       Editor: Peter Gutmanndraft-ietf-pkix-certstore-http-03.txt                University of AucklandDecember 2002Expires June 2003                Internet X.509 Public Key Infrastructure       Operational Protocols: Certificate Store Access via HTTPStatus of this memoThis document is an Internet-Draft and is in full conformance with allprovisions of Section 10 of RFC2026.  Internet-Drafts are working documents ofthe Internet Engineering Task Force (IETF), its areas, and its working groups.Note that other groups may also distribute working documents as Internet-Drafts.Internet-Drafts are draft documents valid for a maximum of six months and maybe updated, replaced, or obsoleted by other documents at any time.  It isinappropriate to use Internet-Drafts as reference material or to cite themother than as "work in progress."The list of current Internet-Drafts can be accessed athttp://www.ietf.org/ietf/1id-abstracts.txtThe list of Internet-Draft Shadow Directories can be accessed athttp://www.ietf.org/shadow.html.AbstractThe protocol conventions described in this document satisfy some of theoperational requirements of the Internet Public Key Infrastructure (PKI). Thisdocument specifies the conventions for using the Hypertext Transfer Protocol(HTTP/HTTPS) as an interface mechanism to obtain certificates and certificaterevocation lists (CRLs) from PKI repositories.  Additional mechanismsaddressing PKIX operational requirements are specified in separate documents.1. IntroductionThis specification is part of a multi-part standard for the Internet PublicKey Infrastructure (PKI) using X.509 certificates and certificate revocationlists (CRLs).  This document specifies the conventions for using the HypertextTransfer Protocol (HTTP) or optionally HTTPS (throughout the remainder of thisdocument the generic term HTTP will be used to cover either option) as aninterface mechanism to obtain certificates and certificate revocation lists(CRLs) from PKI repositories.Although RFC 2585 [RFC2585] covers fetching certificates via HTTP, this merelymentions that certificates may be fetched from a static URL, which doesn'tprovide any general-purpose interface capabilities to a certificate store.The conventions described in this document allows HTTP to be used as ageneral- purpose, transparent interface to any type of certificate storeranging from flat files through to standard databases such as Berkeley DB andrelational databases, as well as traditional X.500/LDAP directories.  Typicalapplications would include use with web-enabled relational databases (whichmost current databases are) or simple key/data lookup mechanisms such asBerkeley DB and its various descendants.Additional mechanisms addressing PKIX operational requirements are specifiedin separate documents.The key words "MUST", "MUST NOT", "REQUIRED", "SHOULD", "SHOULD NOT","RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted asdescribed in [RFC2119].This draft is being discussed on the "ietf-pkix" mailing list.  To join thelist, send a message to <ietf-pkix-request@imc.org> with the single word"subscribe" in the body of the message.  Also, there is a Web site for themailing list at <http://www.imc.org/ietf-pkix>.2. HTTP Certificate Store InterfaceThe GET method is used in combination with a query URI to retrievecertificates from the underlying certificate store [RFC2068].  The parametersfor the query URI are a certificate identifier consisting of an attribute typeand a value that specifies one or more certificates to be returned from thequery.  The query URI may be specified in a certificate SubjectInfoaccess orAuthorityInfoAccess extension or configured at the client (see section 3).Permitted attribute types and associated values are described below.Arbitrary-length binary values (indicated in the table below) are convertedinto a search key by the process described in section 2.1.  Note that thevalues are checked for an exact match, and are therefore case-sensitive.Attribute  Binary  Value---------  ------  -----certHash     Y     Search key derived from the SHA-1 hash of the                   certificate (sometimes called the certificate                   fingerprint).email        N     Subject email address contained in the certificate,                   typically as an rfc882Name attribute.iHash        Y     Search key derived from the issuer DN as it                   appears in the certificate, CRL, or other object.iAndSHash    Y     Search key derived from the certificate's                   issuerAndSerialNumber [RFC2630].name         N     Subject CommonName contained in the certificate.sHash        Y     Search key derived from the subject DN as it                   appears in the certificate or other object.sKIDHash     Y     Search key derived from the certificate's                   subjectKeyIdentifier.The full URI is formed by concatenating the query URI and the attribute andvalue.  Certificates are retrieved from one query URI (the certificate URI)and CRLs from another query URI (the CRL URI).  These may or may notcorrespond to the same certificate store and/or server (the exactinterpretation is a local configuration issue).  The form of the complete URIis therefore:  <query URI> '?' <attribute> '=' <value>The query value MUST be encoded using the form-urlencoded media type[RFC1866].Certificate URIs MUST support retrieval by all of the above attribute types.CRL URIs MUST support retrival by the iHash and sKID attribute types, whichidentify the issuer of the CRL.If more than one certificate matches a query, it MUST be returned as amultipart/mixed response.Responses to unsuccessful queries (for example to indicate a non-match or anerror conditions) are handled in the standard manner as per [RFC2068].Clients should in particular be aware that in some instances servers mayreturn HTTP type 3xx redirection requests to explicitly redirect queries toanother server.  Obviously, implicit DNS-based redirection is also possible.Other information such as naming conventions and MIME types are specified in[RFC2585].2.1 Convering Binary Blobs into Search KeysThe fields marked as binary data in the table in section 2 are of arbitrarylength and contain non-textual data.  Both of these properties make themunsuited for direct use in HTTP queries.  In order to make them usable, theyare first hashed down to a fixed-length 160-bit value and then base64-encoded:  Step 1: Hash the key value using SHA-1 to produce a 160-bit value  Step 2: Encode the hash value using base64-encoding to produce a          27-byte text-only valueCertificate stores should verify that the base64-encoded values submitted inrequests contain only characters in the range 'a'-'z', 'A'-'Z', '0'-'9', '/',and '.'.  Queries containing any other character MUST be rejected (see theimplementation notes in section 2.2 and the security considerations in section4 for more details on this requirement).2.2 Implementation NotesAlthough clients will always submit a fixed 160-bit value, servers are free toutilise as many bits of this value as they require, for example a server maychoose to use only the first 40 or 64 or 80 or 128 bits for efficiency insearching and maintaining indices.The base64-encoded form of the identifier should be carefully checked forinvalid characters since allowing raw data through presents a security risk.Consider for example a certificate store implemented using an RDBMS in whichthe 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 thecertificate store administrators.  For this reason only valid base64 encodingsshould be allowed.  The same checking applies to queries by name or emailaddress.Various network efficiency considerations need to be taken into account whenimplementing this certificate distribution mechanism.  For example, asimplistic implementation that performs two writes (the HTTP header and thecertificate written seperately) followed by a read will interact badly withTCP delayed-ACK and slow-start.  The reason for this is that the TCP MSS istypically 1460 bytes on a LAN (Ethernet) or 512/536 bytes on a WAN, while HTTPheaders are ~200-300 bytes, far less than the MSS.  When an HTTP message isfirst sent, the TCP congestion window begins at one segment, with the TCPslow-start then doubling its size for each ACK.  Sending the headersseparately will send one short segment and a second MSS-size segment,whereupon the TCP stack will wait for the responder's ACK before continuing.The responder gets both segments, then delays its ACK for 200ms in the hopesof piggybacking it on responder data, which is never sent since it's stillwaiting for the rest of the HTTP body from the initiator.  As a result, thisresults in a 200ms (+ assorted RTT) delay in each message sent.There are various other considerations that need to be taken into account inorder to provide maximum efficiency.  These are covered in depth elsewhere[Spero] [Heidemann] [Nielsen].  A rule of thumb for optimal performance is tocombine the HTTP header and data payload into a single write (any reasonableHTTP implementation will do this anyway, thanks to the considerable body ofexperience that exists for HTTP server performance tuning), and to keep theHTTP headers to a minimum to try and fit data within a TCP MSS.  Since thisprotocol doesn't involve a web browser, there's no need to include the usualheaders covering browser versions and languages and so on; a minimal set ofcontent-type/encoding and host and session control information will suffice.2.3 ExamplesTo convert the subject DN C=NZ, O=... CN=Fred Dagg into a search key:  Hash the DN, in the DER-encoded form it appears in the certificate, to  obtain:    96 4C 70 C4 1E C9 08 E5 CA 45 25 10 D6 C8 28 3A 1A C1 DF E2  base-64 encode this to obtain:    lkxwxB7JCOXKRSUQ1sgoOhrB3+IThis is the search key to use in the query URI.To fetch all certificates useful for sending encrypted email to foo@bar.com:  GET /search-cgi?email=foo%40bar.com HTTP/1.1In this case "/search-cgi" is the abs_path portion of the query URI, and therequest is submitted to the server located at the net_loc portion of the queryURI.  Note the encoding of the '@' symbol as per [RFC1866].  Remainingrequired headers such as the "Host" header required by HTTP 1.1 have beenomitted for the sake of clarity.To fetch the CA certificate that issued the email certificate:  <Convert the issuer DN to a search key>  GET /search-cgi?iHash=<search key> HTTP/1.1Alternatively, if chaining is by key identifier:  <Extract the keyIdentifier from the authorityKeyIdentifier>  GET /search-cgi?sKID=<search key> HTTP/1.1To fetch other certificates belonging to the same user as the emailcertificate:  <Convert the subject DN to a search key>  GET /search-cgi?sHash=<search key> HTTP/1.1To fetch the CRL for the certificate:  <Convert the issuer DN to a search key>  GET /search-cgi?iHash=<search key> HTTP/1.1Note that since the differentiator is the URI base, the above two queriesappear identical (since the URI base isn't shown) but are in fact distinct.2.4 RationaleThe identifiers are taken from PKCS #15 [PKCS15], a standard that covers(among other things) a transparent interface to a certificate store.  Theseidentifiers have been field proven through having been in common use for anumber of years, typically via PKCS #11 [PKCS11].  Certificate stores and theidentifiers that are required for typical certificate lookup operations areanalysed in some detail in [Gutmann].Another possible identifier that has been suggested is an IP address or DNSname, which will be required for web-enabled embedded devices.  This isnecessary to allow for example a home automation controller to be queried forcertificates for the devices that it controls.  Since this value is regardedas the CN for the device, common practice is to use this value for the CN inthe 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 query types have been specifically chosen to be not just an HTTP interfaceto LDAP but as a general-purpose retrieval mechanism that allows arbitrarycertificate storage mechanisms (with a bias towards simple key/data stores,which are deployed almost universally, whether as ISAM, Berkeley DB, or anRDBMS) to be employed as back-ends.Hashes are used for arbitrary-length fields such as ones containing DNs inplace of the full field to keep the length manageable.  In addition the use ofthe hashed form emphasizes the fact that searching for structured name dataisn't a supported feature, since this is a simple interface to a key/datacertificate store rather than an HTTP interface to an X.500 directory.  Usersspecifically requiring an HTTP interface to X.500 may use technology such asHTTP LDAP gateways for this purpose.The attributes are given shortened name forms (for example iAndSHash in placeof issuerAndSerialNumberHash) in order to keep the lengths reasonable, orcommon name forms (for example email in place of rfc822Name, rfc822Mailbox,emailAddress, mail, email, etc etc) where multiple name forms exist.Multiple response are returned as multipart/mixed rather than an ASN.1SEQUENCE OF Certificate or PKCS #7/CMS certificate chain because this is morestraightforward to implement with standard web-enabled tools.  An additionaladvantage is that it doesn't restrict this access mechanism to DER-based data,allowing it to be extended to other certificate types such as XML, PGP, andSPKI.Certificate and CRL stores are allocated separate URIs because they may beimplemented using different mechanisms.  A certificate store typicallycontains large numbers of small items while a CRL store contains a very smallnumber of potentially large items, by providing independant URIs it's possible