index.rst (8979B)
1 .. _mozilla_projects_nss_certificate_download_specification: 2 3 NSS Certificate Download Specification 4 ====================================== 5 6 .. container:: 7 8 This document describes the data formats used by NSS 3.x for installing certificates. This 9 document is currently being revised and has not yet been reviewed for accuracy. 10 11 .. _data_formats: 12 13 `Data Formats <#data_formats>`__ 14 -------------------------------- 15 16 .. container:: 17 18 NSS can accept certificates in several formats. In all cases the certificates are X509 version 1, 19 2, or 3. 20 21 .. _binary_formats: 22 23 `Binary Formats <#binary_formats>`__ 24 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 25 26 .. container:: 27 28 NSS's certificate loader will recognize several binary formats. They are: 29 30 - **DER encoded certificate:** This is a single binary DER encoded certificate. 31 - **PKCS#7 certificate chain:** This is a single 32 `PKCS#7 <ftp://ftp.rfc-editor.org/in-notes/rfc2315.txt>`__ ``SignedData`` object. The only 33 significant field in the ``SignedData`` object is the ``certificates`` field, which may 34 contain multiple certificates to be imported together. The contents of the ``version``, 35 ``digestAlgorithms``, ``contentInfo``, ``crls``, and ``signerInfos`` fields are ignored. 36 - **Netscape Certificate Sequence:** This is another 37 `PKCS#7 <ftp://ftp.rfc-editor.org/in-notes/rfc2315.txt>`__ object format, and like the 38 ``SignedData`` format, it allows multiple certificates to be imported together. This format is 39 simpler than the `PKCS#7 <ftp://ftp.rfc-editor.org/in-notes/rfc2315.txt>`__ ``SignedData`` 40 object format. It consists of a `PKCS#7 <ftp://ftp.rfc-editor.org/in-notes/rfc2315.txt>`__ 41 ``ContentInfo`` structure, wrapping a sequence of certificates. The ``contentType`` field OID 42 must be ``netscape-cert-sequence`` (see 43 :ref:`mozilla_projects_nss_certificate_download_specification#object_identifiers`). The 44 ``content`` field is the following ASN.1 structure: 45 46 .. code:: 47 48 CertificateSequence ::= SEQUENCE OF Certificate 49 50 See the section below on 51 :ref:`mozilla_projects_nss_certificate_download_specification#importing_certificate_chains` for 52 more information about how multiple certificates are handled. 53 54 .. _text_formats: 55 56 `Text Formats <#text_formats>`__ 57 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 58 59 .. container:: 60 61 Any of the above :ref:`mozilla_projects_nss_certificate_download_specification#binary_formats` 62 can also be imported in text form. The text form begins with the following line: 63 64 .. code:: 65 66 -----BEGIN CERTIFICATE----- 67 68 Following this line should be the certificate data, which can be in any of the 69 :ref:`mozilla_projects_nss_certificate_download_specification#binary_formats` described above. 70 This data must be base64 encoded as described by `RFC 71 1113 <https://datatracker.ietf.org/doc/html/rfc1113>`__. Following the data should be the 72 following line: 73 74 .. code:: 75 76 -----END CERTIFICATE----- 77 78 In a text format download, NSS ignores any text before the first ``BEGIN CERTIFICATE`` line, and 79 ignores any text after the first ``END CERTIFICATE`` line. Between those two lines, there must be 80 exactly ONE item of any of the supported binary formats described above, and that one item must 81 be base64 encoded. Regardless of which of the supported binary formats is used, the ``BEGIN`` and 82 ``END`` lines must say ``CERTIFICATE``, and not any other word (such as ``KEY``). The ``BEGIN`` 83 and ``END`` lines must begin and end with 5 dashes, with no extra leading or trailing white space 84 (excluding the End Of Line characters). 85 86 .. _importing_certificate_chains: 87 88 `Importing Certificate Chains <#importing_certificate_chains>`__ 89 ---------------------------------------------------------------- 90 91 .. container:: 92 93 Several of the formats described above can contain several certificates. When NSS's certificate 94 decoder encounters one of these collections of multiple certificates they are handled in the 95 following way: 96 97 - The first certificate is processed in a context specific manner, depending upon how it is 98 being imported. For Mozilla browsers, this handling will depend upon the mime ``Content-Type`` 99 that is used on the object being downloaded. For NSS-based servers it will depend upon the 100 options selected in the server's administration interface. 101 102 - Subsequent certificates are all treated the same. If the certificates contain a 103 ``BasicConstraints`` certificate extension that indicates they are CA certificates, and do not 104 already exist in the local certificate database, they are added as untrusted CAs. In this way 105 they may be used for certificate chain validation, as long as there is a trusted CA somewhere 106 along the chain. 107 108 .. _importing_certificates_into_mozilla_browsers: 109 110 `Importing Certificates into Mozilla browsers <#importing_certificates_into_mozilla_browsers>`__ 111 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 112 113 .. container:: 114 115 Mozilla browsers import certificates found in HTTP protocol responses. There are several mime 116 content types that are used to indicate to the browser what type of certificate is being 117 imported. These mime types are: 118 119 - **``application/x-x509-user-cert``** The certificate being downloaded is a user certificate 120 belonging to the user operating the browser. If the private key associated with the 121 certificate does not exist in the user's local key database, then an error dialog is generated 122 and the certificate is not imported. If a certificate chain is being imported then the first 123 certificate in the chain must be the user certificate, and any subsequent certificates will be 124 added as untrusted CA certificates to the local database. 125 - **``application/x-x509-ca-cert``** The certificate being downloaded represents a Certificate 126 Authority. When it is downloaded the user will be shown a sequence of dialogs that will guide 127 them through the process of accepting the Certificate Authority and deciding if they wish to 128 trust sites certified by the CA. If a certificate chain is being imported then the first 129 certificate in the chain must be the CA certificate, and any subsequent certificates will be 130 added as untrusted CA certificates to the local database. 131 - **``application/x-x509-email-cert``** The certificate being downloaded is a user certificate 132 belonging to another user for use with S/MIME. If a certificate chain is being imported then 133 the first certificate in the chain must be the user certificate, and any subsequent 134 certificates will be added as untrusted CA certificates to the local database. This is 135 intended to allow people or CAs to post their e-mail certificates on web pages for download by 136 other users who want to send them encrypted mail. 137 138 Note: the browser checks that the size of the object being downloaded matches the size of the 139 encoded certificates. Therefore it is important to ensure that no extra characters, such as NULLs 140 or LineFeeds are added at the end of the object. 141 142 .. _importing_certificates_into_nss-based_servers: 143 144 `Importing Certificates into NSS-based servers <#importing_certificates_into_nss-based_servers>`__ 145 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 146 147 .. container:: 148 149 Consult your server's administration guide for the most accurate information. For some NSS-base 150 servers, the following information is correct. 151 152 Server certificates are imported via the server admin interface. Certificates are pasted into a 153 text input field in an HTML form, and then the form is submitted to the admin server. Since the 154 certificates are pasted into text fields, only the 155 :ref:`mozilla_projects_nss_certificate_download_specification#text_formats` described above are 156 supported for servers. The type of certificate being imported (e.g. server or CA or cert chain) 157 is specified by the server administrator by selections made on the admin pages. If a certificate 158 chain is being imported then the first certificate in the chain must be the server or CA 159 certificate, and any subsequent certificates will be added as untrusted CA certificates to the 160 local database. 161 162 .. _object_identifiers: 163 164 `Object Identifiers <#object_identifiers>`__ 165 -------------------------------------------- 166 167 .. container:: 168 169 The base of all Netscape object ids is: 170 171 .. code:: 172 173 netscape OBJECT IDENTIFIER ::= { 2 16 840 1 113730 } 174 175 The hexadecimal byte value of this OID when DER encoded is: 176 177 .. code:: 178 179 0x60, 0x86, 0x48, 0x01, 0x86, 0xf8, 0x42 180 181 The following OIDs are mentioned in this document: 182 183 .. code:: 184 185 netscape-data-type OBJECT IDENTIFIER :: = { netscape 2 } 186 netscape-cert-sequence OBJECT IDENTIFIER :: = { netscape-data-type 5 }