|
Packit Service |
4684c1 |
@node More on certificate authentication
|
|
Packit Service |
4684c1 |
@section More on certificate authentication
|
|
Packit Service |
4684c1 |
@cindex certificate authentication
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
Certificates are not the only structures involved in a public key
|
|
Packit Service |
4684c1 |
infrastructure. Several other structures that are used for certificate
|
|
Packit Service |
4684c1 |
requests, encrypted private keys, revocation lists, GnuTLS abstract key
|
|
Packit Service |
4684c1 |
structures, etc., are discussed in this chapter.
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@menu
|
|
Packit Service |
4684c1 |
* PKCS 10 certificate requests::
|
|
Packit Service |
4684c1 |
* PKIX certificate revocation lists::
|
|
Packit Service |
4684c1 |
* OCSP certificate status checking::
|
|
Packit Service |
4684c1 |
* OCSP stapling::
|
|
Packit Service |
4684c1 |
* Managing encrypted keys::
|
|
Packit Service |
4684c1 |
* certtool Invocation:: Invoking certtool
|
|
Packit Service |
4684c1 |
* ocsptool Invocation:: Invoking ocsptool
|
|
Packit Service |
4684c1 |
* danetool Invocation:: Invoking danetool
|
|
Packit Service |
4684c1 |
@end menu
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@node PKCS 10 certificate requests
|
|
Packit Service |
4684c1 |
@subsection @acronym{PKCS} #10 certificate requests
|
|
Packit Service |
4684c1 |
@cindex certificate requests
|
|
Packit Service |
4684c1 |
@cindex PKCS #10
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
A certificate request is a structure, which contain information about
|
|
Packit Service |
4684c1 |
an applicant of a certificate service. It typically contains a public
|
|
Packit Service |
4684c1 |
key, a distinguished name and secondary data such as a challenge
|
|
Packit Service |
4684c1 |
password. @acronym{GnuTLS} supports the requests defined in
|
|
Packit Service |
4684c1 |
@acronym{PKCS} #10 @xcite{RFC2986}. Other formats of certificate requests
|
|
Packit Service |
4684c1 |
are not currently supported by GnuTLS.
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
A certificate request can be generated by
|
|
Packit Service |
4684c1 |
associating it with a private key, setting the
|
|
Packit Service |
4684c1 |
subject's information and finally self signing it.
|
|
Packit Service |
4684c1 |
The last step ensures that the requester is in
|
|
Packit Service |
4684c1 |
possession of the private key.
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@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}
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
The @funcref{gnutls_x509_crq_set_key} and @funcref{gnutls_x509_crq_sign2}
|
|
Packit Service |
4684c1 |
functions associate the request with a private key and sign it. If a
|
|
Packit Service |
4684c1 |
request is to be signed with a key residing in a PKCS #11 token it is recommended to use
|
|
Packit Service |
4684c1 |
the signing functions shown in @ref{Abstract key types}.
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@showfuncdesc{gnutls_x509_crq_set_key}
|
|
Packit Service |
4684c1 |
@showfuncdesc{gnutls_x509_crq_sign2}
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
The following example is about generating a certificate request, and a
|
|
Packit Service |
4684c1 |
private key. A certificate request can be later be processed by a CA
|
|
Packit Service |
4684c1 |
which should return a signed certificate.
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@anchor{ex-crq}
|
|
Packit Service |
4684c1 |
@verbatiminclude examples/ex-crq.c
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@node PKIX certificate revocation lists
|
|
Packit Service |
4684c1 |
@subsection PKIX certificate revocation lists
|
|
Packit Service |
4684c1 |
@cindex certificate revocation lists
|
|
Packit Service |
4684c1 |
@cindex CRL
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
A certificate revocation list (CRL) is a structure issued by an authority
|
|
Packit Service |
4684c1 |
periodically containing a list of revoked certificates serial numbers.
|
|
Packit Service |
4684c1 |
The CRL structure is signed with the issuing authorities' keys. A typical
|
|
Packit Service |
4684c1 |
CRL contains the fields as shown in @ref{tab:crl}.
|
|
Packit Service |
4684c1 |
Certificate revocation lists are used to complement the expiration date of a certificate,
|
|
Packit Service |
4684c1 |
in order to account for other reasons of revocation, such as compromised keys, etc.
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
Each CRL is valid for limited amount of
|
|
Packit Service |
4684c1 |
time and is required to provide, except for the current issuing time, also
|
|
Packit Service |
4684c1 |
the issuing time of the next update.
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@float Table,tab:crl
|
|
Packit Service |
4684c1 |
@multitable @columnfractions .2 .7
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@headitem Field @tab Description
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@item version @tab
|
|
Packit Service |
4684c1 |
The field that indicates the version of the CRL structure.
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@item signature @tab
|
|
Packit Service |
4684c1 |
A signature by the issuing authority.
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@item issuer @tab
|
|
Packit Service |
4684c1 |
Holds the issuer's distinguished name.
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@item thisUpdate @tab
|
|
Packit Service |
4684c1 |
The issuing time of the revocation list.
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@item nextUpdate @tab
|
|
Packit Service |
4684c1 |
The issuing time of the revocation list that will update that one.
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@item revokedCertificates @tab
|
|
Packit Service |
4684c1 |
List of revoked certificates serial numbers.
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@item extensions @tab
|
|
Packit Service |
4684c1 |
Optional CRL structure extensions.
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@end multitable
|
|
Packit Service |
4684c1 |
@caption{Certificate revocation list fields.}
|
|
Packit Service |
4684c1 |
@end float
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
The basic CRL structure functions follow.
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@showfuncD{gnutls_x509_crl_init,gnutls_x509_crl_import,gnutls_x509_crl_export,gnutls_x509_crl_export}
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@subsubheading Reading a CRL
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
The most important function that extracts the certificate revocation
|
|
Packit Service |
4684c1 |
information from a CRL is @funcref{gnutls_x509_crl_get_crt_serial}. Other
|
|
Packit Service |
4684c1 |
functions that return other fields of the CRL structure are also provided.
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@showfuncdesc{gnutls_x509_crl_get_crt_serial}
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@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}
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@subsubheading Generation of a CRL
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
The following functions can be used to generate a CRL.
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@showfuncB{gnutls_x509_crl_set_version,gnutls_x509_crl_set_crt_serial}
|
|
Packit Service |
4684c1 |
@showfuncC{gnutls_x509_crl_set_crt,gnutls_x509_crl_set_next_update,gnutls_x509_crl_set_this_update}
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
The @funcref{gnutls_x509_crl_sign2} and @funcref{gnutls_x509_crl_privkey_sign}
|
|
Packit Service |
4684c1 |
functions sign the revocation list with a private key. The latter function
|
|
Packit Service |
4684c1 |
can be used to sign with a key residing in a PKCS #11 token.
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@showfuncdesc{gnutls_x509_crl_sign2}
|
|
Packit Service |
4684c1 |
@showfuncdesc{gnutls_x509_crl_privkey_sign}
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
Few extensions on the CRL structure are supported, including the
|
|
Packit Service |
4684c1 |
CRL number extension and the authority key identifier.
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@showfuncB{gnutls_x509_crl_set_number,gnutls_x509_crl_set_authority_key_id}
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@node OCSP certificate status checking
|
|
Packit Service |
4684c1 |
@subsection @acronym{OCSP} certificate status checking
|
|
Packit Service |
4684c1 |
@cindex certificate status
|
|
Packit Service |
4684c1 |
@cindex Online Certificate Status Protocol
|
|
Packit Service |
4684c1 |
@cindex OCSP
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
Certificates may be revoked before their expiration time has been
|
|
Packit Service |
4684c1 |
reached. There are several reasons for revoking certificates, but a
|
|
Packit Service |
4684c1 |
typical situation is when the private key associated with a
|
|
Packit Service |
4684c1 |
certificate has been compromised. Traditionally, Certificate
|
|
Packit Service |
4684c1 |
Revocation Lists (CRLs) have been used by application to implement
|
|
Packit Service |
4684c1 |
revocation checking, however, several problems with CRLs have been
|
|
Packit Service |
4684c1 |
identified @xcite{RIVESTCRL}.
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
The Online Certificate Status Protocol, or @acronym{OCSP} @xcite{RFC2560},
|
|
Packit Service |
4684c1 |
is a widely implemented protocol which performs certificate revocation status
|
|
Packit Service |
4684c1 |
checking. An application that wish to verify the
|
|
Packit Service |
4684c1 |
identity of a peer will verify the certificate against a set of
|
|
Packit Service |
4684c1 |
trusted certificates and then check whether the certificate is listed
|
|
Packit Service |
4684c1 |
in a CRL and/or perform an OCSP check for the certificate.
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
Applications are typically expected to contact the OCSP server in order to
|
|
Packit Service |
4684c1 |
request the certificate validity status. The OCSP server replies with an OCSP
|
|
Packit Service |
4684c1 |
response. This section describes this online communication (which can be avoided
|
|
Packit Service |
4684c1 |
when using OCSP stapled responses, for that, see @ref{OCSP stapling}).
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
Before performing the OCSP query, the application will need to figure
|
|
Packit Service |
4684c1 |
out the address of the OCSP server. The OCSP server address can be
|
|
Packit Service |
4684c1 |
provided by the local user in manual configuration or may be stored
|
|
Packit Service |
4684c1 |
in the certificate that is being checked. When stored in a certificate
|
|
Packit Service |
4684c1 |
the OCSP server is in the extension field called the Authority Information
|
|
Packit Service |
4684c1 |
Access (AIA). The following function
|
|
Packit Service |
4684c1 |
extracts this information from a certificate.
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@showfuncA{gnutls_x509_crt_get_authority_info_access}
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
There are several functions in GnuTLS for creating and manipulating
|
|
Packit Service |
4684c1 |
OCSP requests and responses. The general idea is that a client
|
|
Packit Service |
4684c1 |
application creates an OCSP request object, stores some information
|
|
Packit Service |
4684c1 |
about the certificate to check in the request, and then exports the
|
|
Packit Service |
4684c1 |
request in DER format. The request will then need to be sent to the
|
|
Packit Service |
4684c1 |
OCSP responder, which needs to be done by the application (GnuTLS does
|
|
Packit Service |
4684c1 |
not send and receive OCSP packets). Normally an OCSP response is
|
|
Packit Service |
4684c1 |
received that the application will need to import into an OCSP
|
|
Packit Service |
4684c1 |
response object. The digital signature in the OCSP response needs to
|
|
Packit Service |
4684c1 |
be verified against a set of trust anchors before the information in
|
|
Packit Service |
4684c1 |
the response can be trusted.
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
The ASN.1 structure of OCSP requests are briefly as follows. It is
|
|
Packit Service |
4684c1 |
useful to review the structures to get an understanding of which
|
|
Packit Service |
4684c1 |
fields are modified by GnuTLS functions.
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@example
|
|
Packit Service |
4684c1 |
OCSPRequest ::= SEQUENCE @{
|
|
Packit Service |
4684c1 |
tbsRequest TBSRequest,
|
|
Packit Service |
4684c1 |
optionalSignature [0] EXPLICIT Signature OPTIONAL @}
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
TBSRequest ::= SEQUENCE @{
|
|
Packit Service |
4684c1 |
version [0] EXPLICIT Version DEFAULT v1,
|
|
Packit Service |
4684c1 |
requestorName [1] EXPLICIT GeneralName OPTIONAL,
|
|
Packit Service |
4684c1 |
requestList SEQUENCE OF Request,
|
|
Packit Service |
4684c1 |
requestExtensions [2] EXPLICIT Extensions OPTIONAL @}
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
Request ::= SEQUENCE @{
|
|
Packit Service |
4684c1 |
reqCert CertID,
|
|
Packit Service |
4684c1 |
singleRequestExtensions [0] EXPLICIT Extensions OPTIONAL @}
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
CertID ::= SEQUENCE @{
|
|
Packit Service |
4684c1 |
hashAlgorithm AlgorithmIdentifier,
|
|
Packit Service |
4684c1 |
issuerNameHash OCTET STRING, -- Hash of Issuer's DN
|
|
Packit Service |
4684c1 |
issuerKeyHash OCTET STRING, -- Hash of Issuers public key
|
|
Packit Service |
4684c1 |
serialNumber CertificateSerialNumber @}
|
|
Packit Service |
4684c1 |
@end example
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
The basic functions to initialize, import, export and deallocate OCSP
|
|
Packit Service |
4684c1 |
requests are the following.
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@showfuncE{gnutls_ocsp_req_init,gnutls_ocsp_req_deinit,gnutls_ocsp_req_import,gnutls_ocsp_req_export,gnutls_ocsp_req_print}
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
To generate an OCSP request the issuer name hash, issuer key hash, and
|
|
Packit Service |
4684c1 |
the checked certificate's serial number are required. There are two
|
|
Packit Service |
4684c1 |
interfaces available for setting those in an OCSP request.
|
|
Packit Service |
4684c1 |
The is a low-level function when you have the
|
|
Packit Service |
4684c1 |
issuer name hash, issuer key hash, and certificate serial number in
|
|
Packit Service |
4684c1 |
binary form. The second is more useful if you have the
|
|
Packit Service |
4684c1 |
certificate (and its issuer) in a @code{gnutls_x509_crt_t} type.
|
|
Packit Service |
4684c1 |
There is also a function to extract this information from existing an OCSP
|
|
Packit Service |
4684c1 |
request.
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@showfuncC{gnutls_ocsp_req_add_cert_id,gnutls_ocsp_req_add_cert,gnutls_ocsp_req_get_cert_id}
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
Each OCSP request may contain a number of extensions. Extensions are
|
|
Packit Service |
4684c1 |
identified by an Object Identifier (OID) and an opaque data buffer
|
|
Packit Service |
4684c1 |
whose syntax and semantics is implied by the OID. You can extract or
|
|
Packit Service |
4684c1 |
set those extensions using the following functions.
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@showfuncB{gnutls_ocsp_req_get_extension,gnutls_ocsp_req_set_extension}
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
A common OCSP Request extension is the nonce extension (OID
|
|
Packit Service |
4684c1 |
1.3.6.1.5.5.7.48.1.2), which is used to avoid replay attacks of
|
|
Packit Service |
4684c1 |
earlier recorded OCSP responses. The nonce extension carries a value
|
|
Packit Service |
4684c1 |
that is intended to be sufficiently random and unique so that an
|
|
Packit Service |
4684c1 |
attacker will not be able to give a stale response for the same nonce.
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@showfuncC{gnutls_ocsp_req_get_nonce,gnutls_ocsp_req_set_nonce,gnutls_ocsp_req_randomize_nonce}
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
The OCSP response structures is a complex structure. A simplified overview
|
|
Packit Service |
4684c1 |
of it is in @ref{tab:ocsp-response}. Note that a response may contain
|
|
Packit Service |
4684c1 |
information on multiple certificates.
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@float Table,tab:ocsp-response
|
|
Packit Service |
4684c1 |
@multitable @columnfractions .2 .7
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@headitem Field @tab Description
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@item version @tab
|
|
Packit Service |
4684c1 |
The OCSP response version number (typically 1).
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@item responder ID @tab
|
|
Packit Service |
4684c1 |
An identifier of the responder (DN name or a hash of its key).
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@item issue time @tab
|
|
Packit Service |
4684c1 |
The time the response was generated.
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@item thisUpdate @tab
|
|
Packit Service |
4684c1 |
The issuing time of the revocation information.
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@item nextUpdate @tab
|
|
Packit Service |
4684c1 |
The issuing time of the revocation information that will update that one.
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@item @tab Revoked certificates
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@item certificate status @tab
|
|
Packit Service |
4684c1 |
The status of the certificate.
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@item certificate serial @tab
|
|
Packit Service |
4684c1 |
The certificate's serial number.
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@item revocationTime @tab
|
|
Packit Service |
4684c1 |
The time the certificate was revoked.
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@item revocationReason @tab
|
|
Packit Service |
4684c1 |
The reason the certificate was revoked.
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@end multitable
|
|
Packit Service |
4684c1 |
@caption{The most important OCSP response fields.}
|
|
Packit Service |
4684c1 |
@end float
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
We provide basic functions for initialization, importing, exporting
|
|
Packit Service |
4684c1 |
and deallocating OCSP responses.
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@showfuncE{gnutls_ocsp_resp_init,gnutls_ocsp_resp_deinit,gnutls_ocsp_resp_import,gnutls_ocsp_resp_export,gnutls_ocsp_resp_print}
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
The utility function that extracts the revocation as well as other information
|
|
Packit Service |
4684c1 |
from a response is shown below.
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@showfuncdesc{gnutls_ocsp_resp_get_single}
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
The possible revocation reasons available in an OCSP response are shown
|
|
Packit Service |
4684c1 |
below.
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@showenumdesc{gnutls_x509_crl_reason_t,The revocation reasons}
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
Note, that the OCSP response needs to be verified against some set of trust
|
|
Packit Service |
4684c1 |
anchors before it can be relied upon. It is also important to check
|
|
Packit Service |
4684c1 |
whether the received OCSP response corresponds to the certificate being checked.
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@showfuncC{gnutls_ocsp_resp_verify,gnutls_ocsp_resp_verify_direct,gnutls_ocsp_resp_check_crt}
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@node OCSP stapling
|
|
Packit Service |
4684c1 |
@subsection OCSP stapling
|
|
Packit Service |
4684c1 |
@cindex certificate status
|
|
Packit Service |
4684c1 |
@cindex Online Certificate Status Protocol
|
|
Packit Service |
4684c1 |
@cindex OCSP stapling
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
To avoid applications contacting the OCSP server directly, TLS servers
|
|
Packit Service |
4684c1 |
can provide a "stapled" OCSP response in the TLS handshake. That way
|
|
Packit Service |
4684c1 |
the client application needs to do nothing more. GnuTLS will automatically
|
|
Packit Service |
4684c1 |
consider the stapled OCSP response during the TLS certificate verification
|
|
Packit Service |
4684c1 |
(see @funcref{gnutls_certificate_verify_peers2}). To disable the automatic
|
|
Packit Service |
4684c1 |
OCSP verification the flag @code{GNUTLS_VERIFY_DISABLE_CRL_CHECKS} should be
|
|
Packit Service |
4684c1 |
specified to @funcref{gnutls_certificate_set_verify_flags}.
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
Since GnuTLS 3.5.1 the client certificate verification will consider the @xcite{RFC7633}
|
|
Packit Service |
4684c1 |
OCSP-Must-staple certificate extension, and will consider it while checking for stapled
|
|
Packit Service |
4684c1 |
OCSP responses. If the extension is present and no OCSP staple is found, the certificate
|
|
Packit Service |
4684c1 |
verification will fail and the status code @code{GNUTLS_CERT_MISSING_OCSP_STATUS} will
|
|
Packit Service |
4684c1 |
returned from the verification function.
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
Under TLS 1.2 only one stapled response can be sent by a server, the OCSP
|
|
Packit Service |
4684c1 |
response associated with the end-certificate. Under TLS 1.3 a server can
|
|
Packit Service |
4684c1 |
send multiple OCSP responses, typically one for each certificate in the
|
|
Packit Service |
4684c1 |
certificate chain. The following functions can be used by a client
|
|
Packit Service |
4684c1 |
application to retrieve the OCSP responses as sent by the server.
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@showfuncB{gnutls_ocsp_status_request_get,gnutls_ocsp_status_request_get2}
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
GnuTLS servers can provide OCSP responses to their clients using the following functions.
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@showfuncC{gnutls_certificate_set_retrieve_function3,gnutls_certificate_set_ocsp_status_request_file2,gnutls_ocsp_status_request_is_checked}
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
A server is expected to provide the relevant certificate's OCSP responses using
|
|
Packit Service |
4684c1 |
@funcref{gnutls_certificate_set_ocsp_status_request_file2}, and ensure a
|
|
Packit Service |
4684c1 |
periodic reload/renew of the credentials. An estimation of the OCSP responses
|
|
Packit Service |
4684c1 |
expiration can be obtained using the @funcref{gnutls_certificate_get_ocsp_expiration} function.
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@showfuncdesc{gnutls_certificate_get_ocsp_expiration}
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
Prior to GnuTLS 3.6.4, the functions
|
|
Packit Service |
4684c1 |
@funcref{gnutls_certificate_set_ocsp_status_request_function2}
|
|
Packit Service |
4684c1 |
@funcref{gnutls_certificate_set_ocsp_status_request_file} were provided
|
|
Packit Service |
4684c1 |
to set OCSP responses. These functions are still functional, but cannot be used
|
|
Packit Service |
4684c1 |
to set multiple OCSP responses as allowed by TLS1.3.
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
The responses can be updated periodically using the 'ocsptool' command
|
|
Packit Service |
4684c1 |
(see also @ref{ocsptool Invocation}).
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@example
|
|
Packit Service |
4684c1 |
ocsptool --ask --load-cert server_cert.pem --load-issuer the_issuer.pem
|
|
Packit Service |
4684c1 |
--load-signer the_issuer.pem --outfile ocsp.resp
|
|
Packit Service |
4684c1 |
@end example
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
In order to allow multiple OCSP responses to be concatenated, GnuTLS
|
|
Packit Service |
4684c1 |
supports PEM-encoded OCSP responses. These can be generated using
|
|
Packit Service |
4684c1 |
'ocsptool' with the '--no-outder' parameter.
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@node Managing encrypted keys
|
|
Packit Service |
4684c1 |
@subsection Managing encrypted keys
|
|
Packit Service |
4684c1 |
@cindex Encrypted keys
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
Transferring or storing private keys in plain may not be a
|
|
Packit Service |
4684c1 |
good idea, since any compromise is irreparable.
|
|
Packit Service |
4684c1 |
Storing the keys in hardware security modules (see @ref{Smart cards and HSMs})
|
|
Packit Service |
4684c1 |
could solve the storage problem but it is not always practical
|
|
Packit Service |
4684c1 |
or efficient enough. This section describes ways to store and
|
|
Packit Service |
4684c1 |
transfer encrypted private keys.
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
There are methods for key encryption, namely the
|
|
Packit Service |
4684c1 |
PKCS #8, PKCS #12 and OpenSSL's custom encrypted private key formats.
|
|
Packit Service |
4684c1 |
The PKCS #8 and the OpenSSL's method allow encryption of the private key,
|
|
Packit Service |
4684c1 |
while the PKCS #12 method allows, in addition, the bundling of accompanying
|
|
Packit Service |
4684c1 |
data into the structure. That is typically the corresponding certificate, as
|
|
Packit Service |
4684c1 |
well as a trusted CA certificate.
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@subsubheading High level functionality
|
|
Packit Service |
4684c1 |
Generic and higher level private key import functions are available, that
|
|
Packit Service |
4684c1 |
import plain or encrypted keys and will auto-detect the encrypted key format.
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@showfuncdesc{gnutls_privkey_import_x509_raw}
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@showfuncdesc{gnutls_x509_privkey_import2}
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
Any keys imported using those functions can be imported to a certificate
|
|
Packit Service |
4684c1 |
credentials structure using @funcref{gnutls_certificate_set_key}, or alternatively
|
|
Packit Service |
4684c1 |
they can be directly imported using @funcref{gnutls_certificate_set_x509_key_file2}.
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@subsubheading @acronym{PKCS} #8 structures
|
|
Packit Service |
4684c1 |
@cindex PKCS #8
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
PKCS #8 keys can be imported and exported as normal private keys using
|
|
Packit Service |
4684c1 |
the functions below. An addition to the normal import functions, are
|
|
Packit Service |
4684c1 |
a password and a flags argument. The flags can be any element of the @code{gnutls_pkcs_encrypt_flags_t}
|
|
Packit Service |
4684c1 |
enumeration. Note however, that GnuTLS only supports the PKCS #5 PBES2
|
|
Packit Service |
4684c1 |
encryption scheme. Keys encrypted with the obsolete PBES1 scheme cannot
|
|
Packit Service |
4684c1 |
be decrypted.
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@showfuncC{gnutls_x509_privkey_import_pkcs8,gnutls_x509_privkey_export_pkcs8,gnutls_x509_privkey_export2_pkcs8}
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@showenumdesc{gnutls_pkcs_encrypt_flags_t,Encryption flags}
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@subsubheading @acronym{PKCS} #12 structures
|
|
Packit Service |
4684c1 |
@cindex PKCS #12
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
A @acronym{PKCS} #12 structure @xcite{PKCS12} usually contains a user's
|
|
Packit Service |
4684c1 |
private keys and certificates. It is commonly used in browsers to
|
|
Packit Service |
4684c1 |
export and import the user's identities. A file containing such a key can
|
|
Packit Service |
4684c1 |
be directly imported to a certificate credentials structure by using
|
|
Packit Service |
4684c1 |
@funcref{gnutls_certificate_set_x509_simple_pkcs12_file}.
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
In @acronym{GnuTLS} the @acronym{PKCS} #12 structures are handled
|
|
Packit Service |
4684c1 |
using the @code{gnutls_pkcs12_t} type. This is an abstract type that
|
|
Packit Service |
4684c1 |
may hold several @code{gnutls_pkcs12_bag_t} types. The bag types are
|
|
Packit Service |
4684c1 |
the holders of the actual data, which may be certificates, private
|
|
Packit Service |
4684c1 |
keys or encrypted data. A bag of type encrypted should be decrypted
|
|
Packit Service |
4684c1 |
in order for its data to be accessed.
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
To reduce the complexity in parsing the structures the simple
|
|
Packit Service |
4684c1 |
helper function @funcref{gnutls_pkcs12_simple_parse} is provided. For more
|
|
Packit Service |
4684c1 |
advanced uses, manual parsing of the structure is required using the
|
|
Packit Service |
4684c1 |
functions below.
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@showfuncD{gnutls_pkcs12_get_bag,gnutls_pkcs12_verify_mac,gnutls_pkcs12_bag_decrypt,gnutls_pkcs12_bag_get_count}
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@showfuncdesc{gnutls_pkcs12_simple_parse}
|
|
Packit Service |
4684c1 |
@showfuncC{gnutls_pkcs12_bag_get_data,gnutls_pkcs12_bag_get_key_id,gnutls_pkcs12_bag_get_friendly_name}
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
The functions below are used to generate a PKCS #12 structure. An example
|
|
Packit Service |
4684c1 |
of their usage is shown at @ref{PKCS12 structure generation example}.
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@showfuncC{gnutls_pkcs12_set_bag,gnutls_pkcs12_bag_encrypt,gnutls_pkcs12_generate_mac}
|
|
Packit Service |
4684c1 |
@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}
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@subsubheading OpenSSL encrypted keys
|
|
Packit Service |
4684c1 |
@cindex OpenSSL encrypted keys
|
|
Packit Service |
4684c1 |
Unfortunately the structures discussed in the previous sections are
|
|
Packit Service |
4684c1 |
not the only structures that may hold an encrypted private key. For example
|
|
Packit Service |
4684c1 |
the OpenSSL library offers a custom key encryption method. Those structures
|
|
Packit Service |
4684c1 |
are also supported in GnuTLS with @funcref{gnutls_x509_privkey_import_openssl}.
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@showfuncdesc{gnutls_x509_privkey_import_openssl}
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@include invoke-certtool.texi
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@include invoke-ocsptool.texi
|
|
Packit Service |
4684c1 |
|
|
Packit Service |
4684c1 |
@include invoke-danetool.texi
|