[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
D.4 OCSP API
The following functions are for OCSP certificate status checking. Their prototypes lie in ‘gnutls/ocsp.h’.
gnutls_ocsp_req_add_cert
- Function: 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)
req: should contain a
gnutls_ocsp_req_t
structuredigest: hash algorithm, a
gnutls_digest_algorithm_t
valueissuer: issuer of
subject
certificatecert: certificate to request status for
This function will add another request to the OCSP request for a particular certificate. The issuer name hash, issuer key hash, and serial number fields is populated as follows. The issuer name and the serial number is taken from
cert
. The issuer key is taken fromissuer
. The hashed values will be hashed using thedigest
algorithm, normallyGNUTLS_DIG_SHA1
.Returns: On success,
GNUTLS_E_SUCCESS
(0) is returned, otherwise a negative error code is returned.
gnutls_ocsp_req_add_cert_id
- Function: 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)
req: should contain a
gnutls_ocsp_req_t
structuredigest: hash algorithm, a
gnutls_digest_algorithm_t
valueissuer_name_hash: hash of issuer’s DN
issuer_key_hash: hash of issuer’s public key
serial_number: serial number of certificate to check
This function will add another request to the OCSP request for a particular certificate having the issuer name hash of
issuer_name_hash
and issuer key hash ofissuer_key_hash
(both hashed usingdigest
) and serial numberserial_number
.The information needed corresponds to the CertID structure:
<informalexample><programlisting> CertID ::= SEQUENCE { hashAlgorithm AlgorithmIdentifier, issuerNameHash OCTET STRING, – Hash of Issuer’s DN issuerKeyHash OCTET STRING, – Hash of Issuers public key serialNumber CertificateSerialNumber } </programlisting></informalexample>
Returns: On success,
GNUTLS_E_SUCCESS
(0) is returned, otherwise a negative error code is returned.
gnutls_ocsp_req_deinit
- Function: void gnutls_ocsp_req_deinit (gnutls_ocsp_req_t req)
req: The structure to be deinitialized
This function will deinitialize a OCSP request structure.
gnutls_ocsp_req_export
- Function: int gnutls_ocsp_req_export (gnutls_ocsp_req_t req, gnutls_datum_t * data)
req: Holds the OCSP request
data: newly allocate buffer holding DER encoded OCSP request
This function will export the OCSP request to DER format.
Returns: In case of failure a negative error code will be returned, and 0 on success.
gnutls_ocsp_req_get_cert_id
- Function: int gnutls_ocsp_req_get_cert_id (gnutls_ocsp_req_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)
req: should contain a
gnutls_ocsp_req_t
structureindx: Specifies which extension OID to get. Use (0) to get the first one.
digest: output variable with
gnutls_digest_algorithm_t
hash algorithmissuer_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
This function will return the certificate information of the
indx
’ed request in the OCSP request. The information returned corresponds to the CertID structure:<informalexample><programlisting> CertID ::= SEQUENCE { hashAlgorithm AlgorithmIdentifier, issuerNameHash OCTET STRING, – Hash of Issuer’s DN issuerKeyHash OCTET STRING, – Hash of Issuers public key serialNumber CertificateSerialNumber } </programlisting></informalexample>
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 availableGNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE
will be returned.
gnutls_ocsp_req_get_extension
- Function: int gnutls_ocsp_req_get_extension (gnutls_ocsp_req_t req, unsigned indx, gnutls_datum_t * oid, unsigned int * critical, gnutls_datum_t * data)
req: should contain a
gnutls_ocsp_req_t
structureindx: Specifies which extension OID to get. Use (0) to get the first one.
oid: will hold newly allocated buffer with OID of extension, may be NULL
critical: output variable with critical flag, may be NULL.
data: will hold newly allocated buffer with extension data, may be NULL
This function will return all information about the requested extension in the OCSP request. The information returned is the OID, the critical flag, and the data itself. The extension OID will be stored as a string. Any of
oid
,critical
, anddata
may be NULL which means that the caller is not interested in getting that information back.The caller needs to deallocate memory by calling
gnutls_free()
onoid
->data anddata
->data.Returns: On success,
GNUTLS_E_SUCCESS
(0) is returned, otherwise a negative error code is returned. If you have reached the last extension availableGNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE
will be returned.
gnutls_ocsp_req_get_nonce
- Function: int gnutls_ocsp_req_get_nonce (gnutls_ocsp_req_t req, unsigned int * critical, gnutls_datum_t * nonce)
req: should contain a
gnutls_ocsp_req_t
structurecritical: whether nonce extension is marked critical, or NULL
nonce: will hold newly allocated buffer with nonce data
This function will return the OCSP request nonce extension data.
The caller needs to deallocate memory by calling
gnutls_free()
onnonce
->data.Returns: On success,
GNUTLS_E_SUCCESS
(0) is returned, otherwise a negative error code is returned.
gnutls_ocsp_req_get_version
- Function: int gnutls_ocsp_req_get_version (gnutls_ocsp_req_t req)
req: should contain a
gnutls_ocsp_req_t
structureThis function will return the version of the OCSP request. Typically this is always 1 indicating version 1.
Returns: version of OCSP request, or a negative error code on error.
gnutls_ocsp_req_import
- Function: int gnutls_ocsp_req_import (gnutls_ocsp_req_t req, const gnutls_datum_t * data)
req: The structure to store the parsed request.
data: DER encoded OCSP request.
This function will convert the given DER encoded OCSP request to the native
gnutls_ocsp_req_t
format. The output will be stored inreq
.Returns: On success,
GNUTLS_E_SUCCESS
(0) is returned, otherwise a negative error value.
gnutls_ocsp_req_init
- Function: int gnutls_ocsp_req_init (gnutls_ocsp_req_t * req)
req: The structure to be initialized
This function will initialize an OCSP request structure.
Returns: On success,
GNUTLS_E_SUCCESS
(0) is returned, otherwise a negative error value.
gnutls_ocsp_req_print
- Function: int gnutls_ocsp_req_print (gnutls_ocsp_req_t req, gnutls_ocsp_print_formats_t format, gnutls_datum_t * out)
req: The structure to be printed
format: Indicate the format to use
out: Newly allocated datum with (0) terminated string.
This function will pretty print a OCSP request, suitable for display to a human.
If the format is
GNUTLS_PRINT_FULL
then all fields of the request will be output, on multiple lines.The output
out
->data needs to be deallocate usinggnutls_free()
.Returns: On success,
GNUTLS_E_SUCCESS
(0) is returned, otherwise a negative error value.
gnutls_ocsp_req_randomize_nonce
- Function: int gnutls_ocsp_req_randomize_nonce (gnutls_ocsp_req_t req)
req: should contain a
gnutls_ocsp_req_t
structureThis function will add or update an nonce extension to the OCSP request with a newly generated random value.
Returns: On success,
GNUTLS_E_SUCCESS
(0) is returned, otherwise a negative error code is returned.
gnutls_ocsp_req_set_extension
- Function: int gnutls_ocsp_req_set_extension (gnutls_ocsp_req_t req, const char * oid, unsigned int critical, const gnutls_datum_t * data)
req: should contain a
gnutls_ocsp_req_t
structureoid: buffer with OID of extension as a string.
critical: critical flag, normally false.
data: the extension data
This function will add an extension to the OCSP request. Calling this function multiple times for the same OID will overwrite values from earlier calls.
Returns: On success,
GNUTLS_E_SUCCESS
(0) is returned, otherwise a negative error code is returned.
gnutls_ocsp_req_set_nonce
- Function: int gnutls_ocsp_req_set_nonce (gnutls_ocsp_req_t req, unsigned int critical, const gnutls_datum_t * nonce)
req: should contain a
gnutls_ocsp_req_t
structurecritical: critical flag, normally false.
nonce: the nonce data
This function will add an nonce extension to the OCSP request. Calling this function multiple times will overwrite values from earlier calls.
Returns: On success,
GNUTLS_E_SUCCESS
(0) is returned, otherwise a negative error code is returned.
gnutls_ocsp_resp_deinit
- Function: void gnutls_ocsp_resp_deinit (gnutls_ocsp_resp_t resp)
resp: The structure to be deinitialized
This function will deinitialize a OCSP response structure.
gnutls_ocsp_resp_export
- Function: int gnutls_ocsp_resp_export (gnutls_ocsp_resp_t resp, gnutls_datum_t * data)
resp: Holds the OCSP response
data: newly allocate buffer holding DER encoded OCSP response
This function will export the OCSP response to DER format.
Returns: In case of failure a negative error code will be returned, and 0 on success.
gnutls_ocsp_resp_get_certs
- Function: int gnutls_ocsp_resp_get_certs (gnutls_ocsp_resp_t resp, gnutls_x509_crt_t ** certs, size_t * ncerts)
resp: should contain a
gnutls_ocsp_resp_t
structurecerts: newly allocated array with
gnutls_x509_crt_t
certificatesncerts: output variable with number of allocated certs.
This function will extract the X.509 certificates found in the Basic OCSP Response. The
certs
output variable will hold a newly allocated zero-terminated array with X.509 certificates.Every certificate in the array needs to be de-allocated with
gnutls_x509_crt_deinit()
and the array itself must be freed usinggnutls_free()
.Both the
certs
andncerts
variables may be NULL. Then the function will work as normal but will not return the NULL:d information. This can be used to get the number of certificates only, or to just get the certificate array without its size.Returns: On success,
GNUTLS_E_SUCCESS
(0) is returned, otherwise a negative error value.
gnutls_ocsp_resp_get_extension
- Function: int gnutls_ocsp_resp_get_extension (gnutls_ocsp_resp_t resp, unsigned indx, gnutls_datum_t * oid, unsigned int * critical, gnutls_datum_t * data)
resp: should contain a
gnutls_ocsp_resp_t
structureindx: Specifies which extension OID to get. Use (0) to get the first one.
oid: will hold newly allocated buffer with OID of extension, may be NULL
critical: output variable with critical flag, may be NULL.
data: will hold newly allocated buffer with extension data, may be NULL
This function will return all information about the requested extension in the OCSP response. The information returned is the OID, the critical flag, and the data itself. The extension OID will be stored as a string. Any of
oid
,critical
, anddata
may be NULL which means that the caller is not interested in getting that information back.The caller needs to deallocate memory by calling
gnutls_free()
onoid
->data anddata
->data.Returns: On success,
GNUTLS_E_SUCCESS
(0) is returned, otherwise a negative error code is returned. If you have reached the last extension availableGNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE
will be returned.
gnutls_ocsp_resp_get_nonce
- Function: int gnutls_ocsp_resp_get_nonce (gnutls_ocsp_resp_t resp, unsigned int * critical, gnutls_datum_t * nonce)
resp: should contain a
gnutls_ocsp_resp_t
structurecritical: whether nonce extension is marked critical
nonce: will hold newly allocated buffer with nonce data
This function will return the Basic OCSP Response nonce extension data.
The caller needs to deallocate memory by calling
gnutls_free()
onnonce
->data.Returns: On success,
GNUTLS_E_SUCCESS
(0) is returned, otherwise a negative error code is returned.
gnutls_ocsp_resp_get_produced
- Function: time_t gnutls_ocsp_resp_get_produced (gnutls_ocsp_resp_t resp)
resp: should contain a
gnutls_ocsp_resp_t
structureThis function will return the time when the OCSP response was signed.
Returns: signing time, or (time_t)-1 on error.
gnutls_ocsp_resp_get_responder
- Function: int gnutls_ocsp_resp_get_responder (gnutls_ocsp_resp_t resp, gnutls_datum_t * dn)
resp: should contain a
gnutls_ocsp_resp_t
structuredn: newly allocated buffer with name
This function will extract the name of the Basic OCSP Response in the provided buffer. The name will be in the form "C=xxxx,O=yyyy,CN=zzzz" as described in RFC2253. The output string will be ASCII or UTF-8 encoded, depending on the certificate data.
The caller needs to deallocate memory by calling
gnutls_free()
ondn
->data.Returns: On success,
GNUTLS_E_SUCCESS
(0) is returned, otherwise a negative error code is returned.
gnutls_ocsp_resp_get_response
- Function: int gnutls_ocsp_resp_get_response (gnutls_ocsp_resp_t resp, gnutls_datum_t * response_type_oid, gnutls_datum_t * response)
resp: should contain a
gnutls_ocsp_resp_t
structureresponse_type_oid: newly allocated output buffer with response type OID
response: newly allocated output buffer with DER encoded response
This function will extract the response type OID in and the response data from an OCSP response. Normally the
response_type_oid
is always "1.3.6.1.5.5.7.48.1.1" which means theresponse
should be decoded as a Basic OCSP Response, but technically other response types could be used.This function is typically only useful when you want to extract the response type OID of an response for diagnostic purposes. Otherwise
gnutls_ocsp_resp_import()
will decode the basic OCSP response part and the caller need not worry about that aspect.Returns: On success,
GNUTLS_E_SUCCESS
(0) is returned, otherwise a negative error value.
gnutls_ocsp_resp_get_signature
- Function: int gnutls_ocsp_resp_get_signature (gnutls_ocsp_resp_t resp, gnutls_datum_t * sig)
resp: should contain a
gnutls_ocsp_resp_t
structuresig: newly allocated output buffer with signature data
This function will extract the signature field of a OCSP response.
Returns: On success,
GNUTLS_E_SUCCESS
(0) is returned, otherwise a negative error value.
gnutls_ocsp_resp_get_signature_algorithm
- Function: int gnutls_ocsp_resp_get_signature_algorithm (gnutls_ocsp_resp_t resp)
resp: should contain a
gnutls_ocsp_resp_t
structureThis function will return a value of the
gnutls_sign_algorithm_t
enumeration that is the signature algorithm that has been used to sign the OCSP response.Returns: a
gnutls_sign_algorithm_t
value, or a negative error code on error.
gnutls_ocsp_resp_get_single
- Function: int gnutls_ocsp_resp_get_single (gnutls_ocsp_resp_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
structureindx: Specifies which extension OID to get. Use (0) to get the first one.
digest: output variable with
gnutls_digest_algorithm_t
hash algorithmissuer_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
isGNUTLS_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 Responseresp
. The information returned corresponds to the SingleResponse structure except the final singleExtensions, reproduced here for illustration:<informalexample><programlisting> SingleResponse ::= SEQUENCE { certID CertID, certStatus CertStatus, thisUpdate GeneralizedTime, nextUpdate [0] EXPLICIT GeneralizedTime OPTIONAL, singleExtensions [1] 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 }
CertStatus ::= CHOICE { good [0] IMPLICIT NULL, revoked [1] IMPLICIT RevokedInfo, unknown [2] IMPLICIT UnknownInfo }
RevokedInfo ::= SEQUENCE { revocationTime GeneralizedTime, revocationReason [0] EXPLICIT CRLReason OPTIONAL } </programlisting></informalexample>
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 availableGNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE
will be returned.
gnutls_ocsp_resp_get_status
- Function: int gnutls_ocsp_resp_get_status (gnutls_ocsp_resp_t resp)
resp: should contain a
gnutls_ocsp_resp_t
structureThis function will return the status of a OCSP response, an
gnutls_ocsp_resp_status_t
enumeration.Returns: status of OCSP request as a
gnutls_ocsp_resp_status_t
, or a negative error code on error.
gnutls_ocsp_resp_get_version
- Function: int gnutls_ocsp_resp_get_version (gnutls_ocsp_resp_t resp)
resp: should contain a
gnutls_ocsp_resp_t
structureThis function will return the version of the Basic OCSP Response. Typically this is always 1 indicating version 1.
Returns: version of Basic OCSP response, or a negative error code on error.
gnutls_ocsp_resp_import
- Function: int gnutls_ocsp_resp_import (gnutls_ocsp_resp_t resp, const gnutls_datum_t * data)
resp: The structure to store the parsed response.
data: DER encoded OCSP response.
This function will convert the given DER encoded OCSP response to the native
gnutls_ocsp_resp_t
format. It also decodes the Basic OCSP Response part, if any. The output will be stored inresp
.Returns: On success,
GNUTLS_E_SUCCESS
(0) is returned, otherwise a negative error value.
gnutls_ocsp_resp_init
- Function: int gnutls_ocsp_resp_init (gnutls_ocsp_resp_t * resp)
resp: The structure to be initialized
This function will initialize an OCSP response structure.
Returns: On success,
GNUTLS_E_SUCCESS
(0) is returned, otherwise a negative error value.
gnutls_ocsp_resp_print
- Function: int gnutls_ocsp_resp_print (gnutls_ocsp_resp_t resp, gnutls_ocsp_print_formats_t format, gnutls_datum_t * out)
resp: The structure to be printed
format: Indicate the format to use
out: Newly allocated datum with (0) terminated string.
This function will pretty print a OCSP response, suitable for display to a human.
If the format is
GNUTLS_PRINT_FULL
then all fields of the response will be output, on multiple lines.The output
out
->data needs to be deallocate usinggnutls_free()
.Returns: On success,
GNUTLS_E_SUCCESS
(0) is returned, otherwise a negative error value.
gnutls_ocsp_resp_verify
- Function: int gnutls_ocsp_resp_verify (gnutls_ocsp_resp_t resp, gnutls_x509_trust_list_t trustlist, unsigned int * verify, unsigned int flags)
resp: should contain a
gnutls_ocsp_resp_t
structuretrustlist: trust anchors as a
gnutls_x509_trust_list_t
structureverify: output variable with verification status, an
gnutls_ocsp_cert_status_t
flags: verification flags, 0 for now.
Verify signature of the Basic OCSP Response against the public key in the certificate of a trusted signer. The
trustlist
should be populated with trust anchors. The function will extract the signer certificate from the Basic OCSP Response and will verify it against thetrustlist
. A trusted signer is a certificate that is either intrustlist
, or it is signed directly by a certificate intrustlist
and has the id-ad-ocspSigning Extended Key Usage bit set.The output
verify
variable will hold verification status codes (e.g.,GNUTLS_OCSP_VERIFY_SIGNER_NOT_FOUND
,GNUTLS_OCSP_VERIFY_INSECURE_ALGORITHM
) which are only valid if the function returnedGNUTLS_E_SUCCESS
.Note that the function returns
GNUTLS_E_SUCCESS
even when verification failed. The caller must always inspect theverify
variable to find out the verification status.The
flags
variable should be 0 for now.Returns: On success,
GNUTLS_E_SUCCESS
(0) is returned, otherwise a negative error value.
gnutls_ocsp_resp_verify_direct
- Function: int gnutls_ocsp_resp_verify_direct (gnutls_ocsp_resp_t resp, gnutls_x509_crt_t issuer, unsigned int * verify, unsigned int flags)
resp: should contain a
gnutls_ocsp_resp_t
structureissuer: certificate believed to have signed the response
verify: output variable with verification status, an
gnutls_ocsp_cert_status_t
flags: verification flags, 0 for now.
Verify signature of the Basic OCSP Response against the public key in the
issuer
certificate.The output
verify
variable will hold verification status codes (e.g.,GNUTLS_OCSP_VERIFY_SIGNER_NOT_FOUND
,GNUTLS_OCSP_VERIFY_INSECURE_ALGORITHM
) which are only valid if the function returnedGNUTLS_E_SUCCESS
.Note that the function returns
GNUTLS_E_SUCCESS
even when verification failed. The caller must always inspect theverify
variable to find out the verification status.The
flags
variable should be 0 for now.Returns: On success,
GNUTLS_E_SUCCESS
(0) is returned, otherwise a negative error value.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
This document was generated on March 23, 2012 using texi2html 5.0.