OCSP certificate status checking (GnuTLS 3.8.10)

OCSP certificate status checking (GnuTLS 3.8.10)
Next:
OCSP stapling
, Previous:
PKIX certificate revocation lists
, Up:
More on certificate authentication
Contents
][
Index
4.2.3
OCSP
certificate status checking
Certificates may be revoked before their expiration time has been
reached. There are several reasons for revoking certificates, but a
typical situation is when the private key associated with a
certificate has been compromised. Traditionally, Certificate
Revocation Lists (CRLs) have been used by application to implement
revocation checking, however, several problems with CRLs have been
identified [
RIVESTCRL
].
The Online Certificate Status Protocol, or
OCSP
RFC2560
],
is a widely implemented protocol which performs certificate revocation status
checking. An application that wish to verify the
identity of a peer will verify the certificate against a set of
trusted certificates and then check whether the certificate is listed
in a CRL and/or perform an OCSP check for the certificate.
Applications are typically expected to contact the OCSP server in order to
request the certificate validity status. The OCSP server replies with an OCSP
response. This section describes this online communication (which can be avoided
when using OCSP stapled responses, for that, see
OCSP stapling
).
Before performing the OCSP query, the application will need to figure
out the address of the OCSP server. The OCSP server address can be
provided by the local user in manual configuration or may be stored
in the certificate that is being checked. When stored in a certificate
the OCSP server is in the extension field called the Authority Information
Access (AIA). The following function
extracts this information from a certificate.
int
gnutls_x509_crt_get_authority_info_access
(gnutls_x509_crt_t
crt
, unsigned int
seq
, int
what
, gnutls_datum_t *
data
, unsigned int *
critical
There are several functions in GnuTLS for creating and manipulating
OCSP requests and responses. The general idea is that a client
application creates an OCSP request object, stores some information
about the certificate to check in the request, and then exports the
request in DER format. The request will then need to be sent to the
OCSP responder, which needs to be done by the application (GnuTLS does
not send and receive OCSP packets). Normally an OCSP response is
received that the application will need to import into an OCSP
response object. The digital signature in the OCSP response needs to
be verified against a set of trust anchors before the information in
the response can be trusted.
The ASN.1 structure of OCSP requests are briefly as follows. It is
useful to review the structures to get an understanding of which
fields are modified by GnuTLS functions.
OCSPRequest ::= SEQUENCE {
tbsRequest TBSRequest,
optionalSignature [0] EXPLICIT Signature OPTIONAL }

TBSRequest ::= SEQUENCE {
version [0] EXPLICIT Version DEFAULT v1,
requestorName [1] EXPLICIT GeneralName OPTIONAL,
requestList SEQUENCE OF Request,
requestExtensions [2] EXPLICIT Extensions OPTIONAL }

Request ::= SEQUENCE {
reqCert CertID,
singleRequestExtensions [0] EXPLICIT Extensions OPTIONAL }

CertID ::= SEQUENCE {
hashAlgorithm AlgorithmIdentifier,
issuerNameHash OCTET STRING, -- Hash of Issuer's DN
issuerKeyHash OCTET STRING, -- Hash of Issuers public key
serialNumber CertificateSerialNumber }
The basic functions to initialize, import, export and deallocate OCSP
requests are the following.
int
gnutls_ocsp_req_init
(gnutls_ocsp_req_t *
req
void
gnutls_ocsp_req_deinit
(gnutls_ocsp_req_t
req
int
gnutls_ocsp_req_import
(gnutls_ocsp_req_t
req
, const gnutls_datum_t *
data
int
gnutls_ocsp_req_export
(gnutls_ocsp_req_const_t
req
, gnutls_datum_t *
data
int
gnutls_ocsp_req_print
(gnutls_ocsp_req_const_t
req
, gnutls_ocsp_print_formats_t
format
, gnutls_datum_t *
out
To generate an OCSP request the issuer name hash, issuer key hash, and
the checked certificate’s serial number are required. There are two
interfaces available for setting those in an OCSP request.
The is a low-level function when you have the
issuer name hash, issuer key hash, and certificate serial number in
binary form. The second is more useful if you have the
certificate (and its issuer) in a
gnutls_x509_crt_t
type.
There is also a function to extract this information from existing an OCSP
request.
int
gnutls_ocsp_req_add_cert_id
(gnutls_ocsp_req_t
req
, gnutls_digest_algorithm_t
digest
, const gnutls_datum_t *
issuer_name_hash
, const gnutls_datum_t *
issuer_key_hash
, const gnutls_datum_t *
serial_number
int
gnutls_ocsp_req_add_cert
(gnutls_ocsp_req_t
req
, gnutls_digest_algorithm_t
digest
, gnutls_x509_crt_t
issuer
, gnutls_x509_crt_t
cert
int
gnutls_ocsp_req_get_cert_id
(gnutls_ocsp_req_const_t
req
, unsigned
indx
, gnutls_digest_algorithm_t *
digest
, gnutls_datum_t *
issuer_name_hash
, gnutls_datum_t *
issuer_key_hash
, gnutls_datum_t *
serial_number
Each OCSP request may contain a number of extensions. Extensions are
identified by an Object Identifier (OID) and an opaque data buffer
whose syntax and semantics is implied by the OID. You can extract or
set those extensions using the following functions.
int
gnutls_ocsp_req_get_extension
(gnutls_ocsp_req_const_t
req
, unsigned
indx
, gnutls_datum_t *
oid
, unsigned int *
critical
, gnutls_datum_t *
data
int
gnutls_ocsp_req_set_extension
(gnutls_ocsp_req_t
req
, const char *
oid
, unsigned int
critical
, const gnutls_datum_t *
data
A common OCSP Request extension is the nonce extension (OID
1.3.6.1.5.5.7.48.1.2), which is used to avoid replay attacks of
earlier recorded OCSP responses. The nonce extension carries a value
that is intended to be sufficiently random and unique so that an
attacker will not be able to give a stale response for the same nonce.
int
gnutls_ocsp_req_get_nonce
(gnutls_ocsp_req_const_t
req
, unsigned int *
critical
, gnutls_datum_t *
nonce
int
gnutls_ocsp_req_set_nonce
(gnutls_ocsp_req_t
req
, unsigned int
critical
, const gnutls_datum_t *
nonce
int
gnutls_ocsp_req_randomize_nonce
(gnutls_ocsp_req_t
req
The OCSP response structures is a complex structure. A simplified overview
of it is in
Table 4.6
. Note that a response may contain
information on multiple certificates.
Field
Description
version
The OCSP response version number (typically 1).
responder ID
An identifier of the responder (DN name or a hash of its key).
issue time
The time the response was generated.
thisUpdate
The issuing time of the revocation information.
nextUpdate
The issuing time of the revocation information that will update that one.
Revoked certificates
certificate status
The status of the certificate.
certificate serial
The certificate’s serial number.
revocationTime
The time the certificate was revoked.
revocationReason
The reason the certificate was revoked.
Table 4.6:
The most important OCSP response fields.
We provide basic functions for initialization, importing, exporting
and deallocating OCSP responses.
int
gnutls_ocsp_resp_init
(gnutls_ocsp_resp_t *
resp
void
gnutls_ocsp_resp_deinit
(gnutls_ocsp_resp_t
resp
int
gnutls_ocsp_resp_import
(gnutls_ocsp_resp_t
resp
, const gnutls_datum_t *
data
int
gnutls_ocsp_resp_export
(gnutls_ocsp_resp_const_t
resp
, gnutls_datum_t *
data
int
gnutls_ocsp_resp_print
(gnutls_ocsp_resp_const_t
resp
, gnutls_ocsp_print_formats_t
format
, gnutls_datum_t *
out
The utility function that extracts the revocation as well as other information
from a response is shown below.
Function:
int
gnutls_ocsp_resp_get_single
(gnutls_ocsp_resp_const_t
resp
, unsigned
indx
, gnutls_digest_algorithm_t *
digest
, gnutls_datum_t *
issuer_name_hash
, gnutls_datum_t *
issuer_key_hash
, gnutls_datum_t *
serial_number
, unsigned int *
cert_status
, time_t *
this_update
, time_t *
next_update
, time_t *
revocation_time
, unsigned int *
revocation_reason
resp
: should contain a
gnutls_ocsp_resp_t
type
indx
: Specifies response number to get. Use (0) to get the first one.
digest
: output variable with
gnutls_digest_algorithm_t
hash algorithm
issuer_name_hash
: output buffer with hash of issuer’s DN
issuer_key_hash
: output buffer with hash of issuer’s public key
serial_number
: output buffer with serial number of certificate to check
cert_status
: a certificate status, a
gnutls_ocsp_cert_status_t
enum.
this_update
: time at which the status is known to be correct.
next_update
: when newer information will be available, or (time_t)-1 if unspecified
revocation_time
: when
cert_status
is
GNUTLS_OCSP_CERT_REVOKED
, holds time of revocation.
revocation_reason
: revocation reason, a
gnutls_x509_crl_reason_t
enum.
This function will return the certificate information of the
indx
’ed response in the Basic OCSP Response
resp
. The
information returned corresponds to the OCSP SingleResponse structure
except the final singleExtensions.
Each of the pointers to output variables may be NULL to indicate
that the caller is not interested in that value.
Returns:
On success,
GNUTLS_E_SUCCESS
(0) is returned, otherwise a
negative error code is returned. If you have reached the last
CertID available
GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE
will be
returned.
The possible revocation reasons available in an OCSP response are shown
below.
GNUTLS_X509_CRLREASON_UNSPECIFIED
Unspecified reason.
GNUTLS_X509_CRLREASON_KEYCOMPROMISE
Private key compromised.
GNUTLS_X509_CRLREASON_CACOMPROMISE
CA compromised.
GNUTLS_X509_CRLREASON_AFFILIATIONCHANGED
Affiliation has changed.
GNUTLS_X509_CRLREASON_SUPERSEDED
Certificate superseded.
GNUTLS_X509_CRLREASON_CESSATIONOFOPERATION
Operation has ceased.
GNUTLS_X509_CRLREASON_CERTIFICATEHOLD
Certificate is on hold.
GNUTLS_X509_CRLREASON_REMOVEFROMCRL
Will be removed from delta CRL.
GNUTLS_X509_CRLREASON_PRIVILEGEWITHDRAWN
Privilege withdrawn.
GNUTLS_X509_CRLREASON_AACOMPROMISE
AA compromised.
Figure 4.4:
The revocation reasons
Note, that the OCSP response needs to be verified against some set of trust
anchors before it can be relied upon. It is also important to check
whether the received OCSP response corresponds to the certificate being checked.
int
gnutls_ocsp_resp_verify
(gnutls_ocsp_resp_const_t
resp
, gnutls_x509_trust_list_t
trustlist
, unsigned int *
verify
, unsigned int
flags
int
gnutls_ocsp_resp_verify_direct
(gnutls_ocsp_resp_const_t
resp
, gnutls_x509_crt_t
issuer
, unsigned int *
verify
, unsigned int
flags
int
gnutls_ocsp_resp_check_crt
(gnutls_ocsp_resp_const_t
resp
, unsigned int
indx
, gnutls_x509_crt_t
crt
Next:
OCSP stapling
, Previous:
PKIX certificate revocation lists
, Up:
More on certificate authentication
Contents
][
Index