1 @node More on certificate authentication
2 @section More on certificate authentication
3 @cindex certificate authentication
5 Certificates are not the only structures involved in a public key
6 infrastructure. Several other structures that are used for certificate
7 requests, encrypted private keys, revocation lists, GnuTLS abstract key
8 structures, etc., are discussed in this chapter.
11 * PKCS 10 certificate requests::
12 * PKIX certificate revocation lists::
13 * OCSP certificate status checking::
14 * Managing encrypted keys::
15 * certtool Invocation:: Invoking certtool
16 * ocsptool Invocation:: Invoking ocsptool
17 * danetool Invocation:: Invoking danetool
20 @node PKCS 10 certificate requests
21 @subsection @acronym{PKCS} #10 certificate requests
22 @cindex certificate requests
25 A certificate request is a structure, which contain information about
26 an applicant of a certificate service. It usually contains a private
27 key, a distinguished name and secondary data such as a challenge
28 password. @acronym{GnuTLS} supports the requests defined in
29 @acronym{PKCS} #10 @xcite{RFC2986}. Other formats of certificate requests
30 are not currently supported.
32 A certificate request can be generated by
33 associating it with a private key, setting the
34 subject's information and finally self signing it.
35 The last step ensures that the requester is in
36 possession of the private key.
38 @showfuncF{gnutls_x509_crq_set_version,gnutls_x509_crq_set_dn,gnutls_x509_crq_set_dn_by_oid,gnutls_x509_crq_set_key_usage,gnutls_x509_crq_set_key_purpose_oid,gnutls_x509_crq_set_basic_constraints}
40 The @funcref{gnutls_x509_crq_set_key} and @funcref{gnutls_x509_crq_sign2}
41 functions associate the request with a private key and sign it. If a
42 request is to be signed with a key residing in a PKCS #11 token it is recommended to use
43 the signing functions shown in @ref{Abstract key types}.
45 @showfuncdesc{gnutls_x509_crq_set_key}
46 @showfuncdesc{gnutls_x509_crq_sign2}
48 The following example is about generating a certificate request, and a
49 private key. A certificate request can be later be processed by a CA
50 which should return a signed certificate.
53 @verbatiminclude examples/ex-crq.c
55 @node PKIX certificate revocation lists
56 @subsection PKIX certificate revocation lists
57 @cindex certificate revocation lists
60 A certificate revocation list (CRL) is a structure issued by an authority
61 periodically containing a list of revoked certificates serial numbers.
62 The CRL structure is signed with the issuing authorities' keys. A typical
63 CRL contains the fields as shown in @ref{tab:crl}.
64 Certificate revocation lists are used to complement the expiration date of a certificate,
65 in order to account for other reasons of revocation, such as compromised keys, etc.
67 Each CRL is valid for limited amount of
68 time and is required to provide, except for the current issuing time, also
69 the issuing time of the next update.
72 @multitable @columnfractions .2 .7
74 @headitem Field @tab Description
77 The field that indicates the version of the CRL structure.
80 A signature by the issuing authority.
83 Holds the issuer's distinguished name.
86 The issuing time of the revocation list.
89 The issuing time of the revocation list that will update that one.
91 @item revokedCertificates @tab
92 List of revoked certificates serial numbers.
95 Optional CRL structure extensions.
98 @caption{Certificate revocation list fields.}
101 The basic CRL structure functions follow.
103 @showfuncD{gnutls_x509_crl_init,gnutls_x509_crl_import,gnutls_x509_crl_export,gnutls_x509_crl_export}
105 @subsubheading Reading a CRL
107 The most important function that extracts the certificate revocation
108 information from a CRL is @funcref{gnutls_x509_crl_get_crt_serial}. Other
109 functions that return other fields of the CRL structure are also provided.
111 @showfuncdesc{gnutls_x509_crl_get_crt_serial}
113 @showfuncF{gnutls_x509_crl_get_version,gnutls_x509_crl_get_issuer_dn,gnutls_x509_crl_get_issuer_dn2,gnutls_x509_crl_get_this_update,gnutls_x509_crl_get_next_update,gnutls_x509_crl_get_crt_count}
115 @subsubheading Generation of a CRL
117 The following functions can be used to generate a CRL.
119 @showfuncB{gnutls_x509_crl_set_version,gnutls_x509_crl_set_crt_serial}
120 @showfuncC{gnutls_x509_crl_set_crt,gnutls_x509_crl_set_next_update,gnutls_x509_crl_set_this_update}
122 The @funcref{gnutls_x509_crl_sign2} and @funcref{gnutls_x509_crl_privkey_sign}
123 functions sign the revocation list with a private key. The latter function
124 can be used to sign with a key residing in a PKCS #11 token.
126 @showfuncdesc{gnutls_x509_crl_sign2}
127 @showfuncdesc{gnutls_x509_crl_privkey_sign}
129 Few extensions on the CRL structure are supported, including the
130 CRL number extension and the authority key identifier.
132 @showfuncB{gnutls_x509_crl_set_number,gnutls_x509_crl_set_authority_key_id}
134 @node OCSP certificate status checking
135 @subsection @acronym{OCSP} certificate status checking
136 @cindex certificate status
137 @cindex Online Certificate Status Protocol
140 Certificates may be revoked before their expiration time has been
141 reached. There are several reasons for revoking certificates, but a
142 typical situation is when the private key associated with a
143 certificate has been compromised. Traditionally, Certificate
144 Revocation Lists (CRLs) have been used by application to implement
145 revocation checking, however, several problems with CRLs have been
146 identified @xcite{RIVESTCRL}.
148 The Online Certificate Status Protocol, or @acronym{OCSP} @xcite{RFC2560},
149 is a widely implemented protocol which performs certificate revocation status
150 checking. An application that wish to verify the
151 identity of a peer will verify the certificate against a set of
152 trusted certificates and then check whether the certificate is listed
153 in a CRL and/or perform an OCSP check for the certificate.
155 Note that in the context of a TLS session the server may provide an
156 OCSP response that will be used during the TLS certificate verification
157 (see @funcref{gnutls_certificate_verify_peers2}).
158 You may obtain this response using @funcref{gnutls_ocsp_status_request_get}.
160 Before performing the OCSP query, the application will need to figure
161 out the address of the OCSP server. The OCSP server address can be
162 provided by the local user in manual configuration or may be stored
163 in the certificate that is being checked. When stored in a certificate
164 the OCSP server is in the extension field called the Authority Information
165 Access (AIA). The following function
166 extracts this information from a certificate.
168 @showfuncA{gnutls_x509_crt_get_authority_info_access}
170 There are several functions in GnuTLS for creating and manipulating
171 OCSP requests and responses. The general idea is that a client
172 application creates an OCSP request object, stores some information
173 about the certificate to check in the request, and then exports the
174 request in DER format. The request will then need to be sent to the
175 OCSP responder, which needs to be done by the application (GnuTLS does
176 not send and receive OCSP packets). Normally an OCSP response is
177 received that the application will need to import into an OCSP
178 response object. The digital signature in the OCSP response needs to
179 be verified against a set of trust anchors before the information in
180 the response can be trusted.
182 The ASN.1 structure of OCSP requests are briefly as follows. It is
183 useful to review the structures to get an understanding of which
184 fields are modified by GnuTLS functions.
187 OCSPRequest ::= SEQUENCE @{
188 tbsRequest TBSRequest,
189 optionalSignature [0] EXPLICIT Signature OPTIONAL @}
191 TBSRequest ::= SEQUENCE @{
192 version [0] EXPLICIT Version DEFAULT v1,
193 requestorName [1] EXPLICIT GeneralName OPTIONAL,
194 requestList SEQUENCE OF Request,
195 requestExtensions [2] EXPLICIT Extensions OPTIONAL @}
197 Request ::= SEQUENCE @{
199 singleRequestExtensions [0] EXPLICIT Extensions OPTIONAL @}
201 CertID ::= SEQUENCE @{
202 hashAlgorithm AlgorithmIdentifier,
203 issuerNameHash OCTET STRING, -- Hash of Issuer's DN
204 issuerKeyHash OCTET STRING, -- Hash of Issuers public key
205 serialNumber CertificateSerialNumber @}
208 The basic functions to initialize, import, export and deallocate OCSP
209 requests are the following.
211 @showfuncE{gnutls_ocsp_req_init,gnutls_ocsp_req_deinit,gnutls_ocsp_req_import,gnutls_ocsp_req_export,gnutls_ocsp_req_print}
213 To generate an OCSP request the issuer name hash, issuer key hash, and
214 the checked certificate's serial number are required. There are two
215 interfaces available for setting those in an OCSP request.
216 The is a low-level function when you have the
217 issuer name hash, issuer key hash, and certificate serial number in
218 binary form. The second is more useful if you have the
219 certificate (and its issuer) in a @code{gnutls_x509_crt_t} type.
220 There is also a function to extract this information from existing an OCSP
223 @showfuncC{gnutls_ocsp_req_add_cert_id,gnutls_ocsp_req_add_cert,gnutls_ocsp_req_get_cert_id}
225 Each OCSP request may contain a number of extensions. Extensions are
226 identified by an Object Identifier (OID) and an opaque data buffer
227 whose syntax and semantics is implied by the OID. You can extract or
228 set those extensions using the following functions.
230 @showfuncB{gnutls_ocsp_req_get_extension,gnutls_ocsp_req_set_extension}
232 A common OCSP Request extension is the nonce extension (OID
233 1.3.6.1.5.5.7.48.1.2), which is used to avoid replay attacks of
234 earlier recorded OCSP responses. The nonce extension carries a value
235 that is intended to be sufficiently random and unique so that an
236 attacker will not be able to give a stale response for the same nonce.
238 @showfuncC{gnutls_ocsp_req_get_nonce,gnutls_ocsp_req_set_nonce,gnutls_ocsp_req_randomize_nonce}
240 The OCSP response structures is a complex structure. A simplified overview
241 of it is in @ref{tab:ocsp-response}. Note that a response may contain
242 information on multiple certificates.
244 @float Table,tab:ocsp-response
245 @multitable @columnfractions .2 .7
247 @headitem Field @tab Description
250 The OCSP response version number (typically 1).
252 @item responder ID @tab
253 An identifier of the responder (DN name or a hash of its key).
255 @item issue time @tab
256 The time the response was generated.
258 @item thisUpdate @tab
259 The issuing time of the revocation information.
261 @item nextUpdate @tab
262 The issuing time of the revocation information that will update that one.
264 @item @tab Revoked certificates
266 @item certificate status @tab
267 The status of the certificate.
269 @item certificate serial @tab
270 The certificate's serial number.
272 @item revocationTime @tab
273 The time the certificate was revoked.
275 @item revocationReason @tab
276 The reason the certificate was revoked.
279 @caption{The most important OCSP response fields.}
283 We provide basic functions for initialization, importing, exporting
284 and deallocating OCSP responses.
286 @showfuncE{gnutls_ocsp_resp_init,gnutls_ocsp_resp_deinit,gnutls_ocsp_resp_import,gnutls_ocsp_resp_export,gnutls_ocsp_resp_print}
288 The utility function that extracts the revocation as well as other information
289 from a response is shown below.
291 @showfuncdesc{gnutls_ocsp_resp_get_single}
293 The possible revocation reasons available in an OCSP response are shown
296 @showenumdesc{gnutls_x509_crl_reason_t,The revocation reasons}
298 Note, that the OCSP response needs to be verified against some set of trust
299 anchors before it can be relied upon. It is also important to check
300 whether the received OCSP response corresponds to the certificate being checked.
302 @showfuncC{gnutls_ocsp_resp_verify,gnutls_ocsp_resp_verify_direct,gnutls_ocsp_resp_check_crt}
304 @node Managing encrypted keys
305 @subsection Managing encrypted keys
306 @cindex Encrypted keys
308 Transferring or storing private keys in plain may not be a
309 good idea, since any compromise is irreparable.
310 Storing the keys in hardware security modules (see @ref{Smart cards and HSMs})
311 could solve the storage problem but it is not always practical
312 or efficient enough. This section describes ways to store and
313 transfer encrypted private keys.
315 There are methods for key encryption, namely the
316 PKCS #8, PKCS #12 and OpenSSL's custom encrypted private key formats.
317 The PKCS #8 and the OpenSSL's method allow encryption of the private key,
318 while the PKCS #12 method allows, in addition, the bundling of accompanying
319 data into the structure. That is typically the corresponding certificate, as
320 well as a trusted CA certificate.
322 @subsubheading High level functionality
323 Generic and higher level private key import functions are available, that
324 import plain or encrypted keys and will auto-detect the encrypted key format.
326 @showfuncdesc{gnutls_privkey_import_x509_raw}
328 @showfuncdesc{gnutls_x509_privkey_import2}
330 Any keys imported using those functions can be imported to a certificate
331 credentials structure using @funcref{gnutls_certificate_set_key}, or alternatively
332 they can be directly imported using @funcref{gnutls_certificate_set_x509_key_file2}.
334 @subsubheading @acronym{PKCS} #8 structures
337 PKCS #8 keys can be imported and exported as normal private keys using
338 the functions below. An addition to the normal import functions, are
339 a password and a flags argument. The flags can be any element of the @code{gnutls_pkcs_encrypt_flags_t}
340 enumeration. Note however, that GnuTLS only supports the PKCS #5 PBES2
341 encryption scheme. Keys encrypted with the obsolete PBES1 scheme cannot
344 @showfuncC{gnutls_x509_privkey_import_pkcs8,gnutls_x509_privkey_export_pkcs8,gnutls_x509_privkey_export2_pkcs8}
346 @showenumdesc{gnutls_pkcs_encrypt_flags_t,Encryption flags}
348 @subsubheading @acronym{PKCS} #12 structures
351 A @acronym{PKCS} #12 structure @xcite{PKCS12} usually contains a user's
352 private keys and certificates. It is commonly used in browsers to
353 export and import the user's identities. A file containing such a key can
354 be directly imported to a certificate credentials structure by using
355 @funcref{gnutls_certificate_set_x509_simple_pkcs12_file}.
357 In @acronym{GnuTLS} the @acronym{PKCS} #12 structures are handled
358 using the @code{gnutls_pkcs12_t} type. This is an abstract type that
359 may hold several @code{gnutls_pkcs12_bag_t} types. The bag types are
360 the holders of the actual data, which may be certificates, private
361 keys or encrypted data. A bag of type encrypted should be decrypted
362 in order for its data to be accessed.
364 To reduce the complexity in parsing the structures the simple
365 helper function @funcref{gnutls_pkcs12_simple_parse} is provided. For more
366 advanced uses, manual parsing of the structure is required using the
369 @showfuncD{gnutls_pkcs12_get_bag,gnutls_pkcs12_verify_mac,gnutls_pkcs12_bag_decrypt,gnutls_pkcs12_bag_get_count}
371 @showfuncdesc{gnutls_pkcs12_simple_parse}
372 @showfuncC{gnutls_pkcs12_bag_get_data,gnutls_pkcs12_bag_get_key_id,gnutls_pkcs12_bag_get_friendly_name}
374 The functions below are used to generate a PKCS #12 structure. An example
375 of their usage is shown at @ref{PKCS12 structure generation example}.
377 @showfuncC{gnutls_pkcs12_set_bag,gnutls_pkcs12_bag_encrypt,gnutls_pkcs12_generate_mac}
378 @showfuncE{gnutls_pkcs12_bag_set_data,gnutls_pkcs12_bag_set_crl,gnutls_pkcs12_bag_set_crt,gnutls_pkcs12_bag_set_key_id,gnutls_pkcs12_bag_set_friendly_name}
380 @subsubheading OpenSSL encrypted keys
381 @cindex OpenSSL encrypted keys
382 Unfortunately the structures discussed in the previous sections are
383 not the only structures that may hold an encrypted private key. For example
384 the OpenSSL library offers a custom key encryption method. Those structures
385 are also supported in GnuTLS with @funcref{gnutls_x509_privkey_import_openssl}.
387 @showfuncdesc{gnutls_x509_privkey_import_openssl}
389 @include invoke-certtool.texi
391 @include invoke-ocsptool.texi
393 @include invoke-danetool.texi