: Etherpad users! We are developing an extension that will allow you to create pages from etherpads quickly and easily. Please visit our sandbox and help us test it.

CA:Certificate Download Specification

From MozillaWiki
Jump to: navigation, search

This document describes the data formats used by Mozilla products for installing certificates.
(Work in Progress)

Data Formats

Mozilla products can accept certificates in several formats. In all cases the certificates are X509 version 1, 2, or 3.

Binary Formats

FireFox's certificate loader will recognize several binary formats. They are:

  • DER encoded certificate: This is a single binary DER encoded certificate.
  • PKCS#7 certificate chain: This is a PKCS#7 SignedData object. The only significant field in the SignedData object is the certificates. In particular, the signature and the contents are ignored. In future versions of the software, the CRLs will also be used. The PKCS#7 format allows multiple certificates to be downloaded at once. See section below on Certificate Chains for more information about how multiple certificates are handled.
  • Netscape Certificate Sequence: This is a simpler format for downloading certificate chains. It consists of a PKCS#7 ContentInfo structure, wrapping a sequence of certificates. The value of the contentType field should be netscape-cert-sequence (see Object Identifiers), while the content field is the following structure:
   CertificateSequence ::= SEQUENCE OF Certificate

This format allows multiple certificates to be downloaded at once. See section below on Certificate Chains for more information about how multiple certificates are handled.

Text Formats

Any of the above binary formats can also be imported in text form. The text form begins with the following line:

   -----BEGIN CERTIFICATE-----

Following this line should be the certificate data, which can be in any of the binary formats described above. This data should be base64 encoded as described by RFC 1113. Following the data should be the following line:

   -----END CERTIFICATE-----

Importing Certificate Chains

Several of the formats described above can contain several certificates. When the certificate decoder encounters one of these collections of multiple certificates they are handled in the following way:

  • The first certificate is processed in a context specific manner, depending upon how it is being imported. For the browser, this handling will depend upon the MIME Content-Type that is used on the object being downloaded.
  • Subsequent certificates are all treated the same. If a certificate contains a BasicConstraints extension identifying it as a CA certificate, and does not already exist in the local certificate database, it is added as an untrusted CA. In this way CA certs may be used for certificate chain validation, as long as there is a trusted CA somewhere along the chain.

Importing Certificates into Firefox

Firefox imports certificates via the HTTP protocol. There are several MIME content types that are used to indicate to the browser what type of certificate is being imported. These MIME content types are:

  • application/x-x509-user-cert The certificate being downloaded is a user certificate belonging to the user operating the browser. If the private key associated with the certificate does not exist in the user's local key database, then an error dialog is generated and the certificate is not imported. If a certificate chain is being imported then the first certificate in the chain must be the user certificate, and any subsequent certificates will be added as untrusted CA certificates to the local database.
  • application/x-x509-ca-cert The certificate being downloaded represents a Certificate Authority. When it is downloaded the user will be shown a sequence of dialogs that will guide them through the process of accepting the Certificate Authority and deciding if they wish to trust sites certified by the CA. If a certificate chain is being imported then the first certificate in the chain must be the CA certificate, and any subsequent certificates will be added as untrusted CA certificates to the local database.
  • application/x-x509-email-cert The certificate being downloaded is a user certificate belonging to another user for use with S/MIME. If a certificate chain is being imported then the first certificate in the chain must be the user certificate, and any subsequent certificates will be added as untrusted CA certificates to the local database. This is intended to allow people or CAs to post their e-mail certificates on web pages for download by other users who want to send them encrypted mail.

Note: the browser checks that the size of the object being downloaded matches the size of the encoded certificates. Therefore it is important to ensure that no extra characters, such as NULLs or newlines are added at the end of the object.

Object Identifiers

The base of all Netscape Object IDs is:

   netscape OBJECT IDENTIFIER ::= { 2 16 840 1 113730 }

The hexadecimal byte value of this OID when DER encoded is:

   0x60, 0x86, 0x48, 0x01, 0x86, 0xf8, 0x42

The following OIDs are mentioned in this document:

   netscape-data-type OBJECT IDENTIFIER :: = { netscape 2 }
   netscape-cert-sequence OBJECT IDENTIFIER :: = { netscape-data-type 5 }