ocsp

ocsp

Synopsis

#define             GNUTLS_OCSP_NONCE
enum                gnutls_ocsp_cert_status_t;
enum                gnutls_ocsp_print_formats_t;
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_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);
void                gnutls_ocsp_req_deinit              (gnutls_ocsp_req_t req);
int                 gnutls_ocsp_req_export              (gnutls_ocsp_req_t req,
                                                         gnutls_datum_t *data);
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);
int                 gnutls_ocsp_req_get_extension       (gnutls_ocsp_req_t req,
                                                         unsigned  indx,
                                                         gnutls_datum_t *oid,
                                                         unsigned int *critical,
                                                         gnutls_datum_t *data);
int                 gnutls_ocsp_req_get_nonce           (gnutls_ocsp_req_t req,
                                                         unsigned int *critical,
                                                         gnutls_datum_t *nonce);
int                 gnutls_ocsp_req_get_version         (gnutls_ocsp_req_t req);
int                 gnutls_ocsp_req_import              (gnutls_ocsp_req_t req,
                                                         const gnutls_datum_t *data);
int                 gnutls_ocsp_req_init                (gnutls_ocsp_req_t *req);
struct              gnutls_ocsp_req_int;
int                 gnutls_ocsp_req_print               (gnutls_ocsp_req_t req,
                                                         gnutls_ocsp_print_formats_t format,
                                                         gnutls_datum_t *out);
int                 gnutls_ocsp_req_randomize_nonce     (gnutls_ocsp_req_t req);
int                 gnutls_ocsp_req_set_extension       (gnutls_ocsp_req_t req,
                                                         const char *oid,
                                                         unsigned int critical,
                                                         const gnutls_datum_t *data);
int                 gnutls_ocsp_req_set_nonce           (gnutls_ocsp_req_t req,
                                                         unsigned int critical,
                                                         const gnutls_datum_t *nonce);
typedef             gnutls_ocsp_req_t;
int                 gnutls_ocsp_resp_check_crt          (gnutls_ocsp_resp_t resp,
                                                         unsigned int indx,
                                                         gnutls_x509_crt_t crt);
void                gnutls_ocsp_resp_deinit             (gnutls_ocsp_resp_t resp);
int                 gnutls_ocsp_resp_export             (gnutls_ocsp_resp_t resp,
                                                         gnutls_datum_t *data);
int                 gnutls_ocsp_resp_get_certs          (gnutls_ocsp_resp_t resp,
                                                         gnutls_x509_crt_t **certs,
                                                         size_t *ncerts);
int                 gnutls_ocsp_resp_get_extension      (gnutls_ocsp_resp_t resp,
                                                         unsigned  indx,
                                                         gnutls_datum_t *oid,
                                                         unsigned int *critical,
                                                         gnutls_datum_t *data);
int                 gnutls_ocsp_resp_get_nonce          (gnutls_ocsp_resp_t resp,
                                                         unsigned int *critical,
                                                         gnutls_datum_t *nonce);
time_t              gnutls_ocsp_resp_get_produced       (gnutls_ocsp_resp_t resp);
int                 gnutls_ocsp_resp_get_responder      (gnutls_ocsp_resp_t resp,
                                                         gnutls_datum_t *dn);
int                 gnutls_ocsp_resp_get_response       (gnutls_ocsp_resp_t resp,
                                                         gnutls_datum_t *response_type_oid,
                                                         gnutls_datum_t *response);
int                 gnutls_ocsp_resp_get_signature      (gnutls_ocsp_resp_t resp,
                                                         gnutls_datum_t *sig);
int                 gnutls_ocsp_resp_get_signature_algorithm
                                                        (gnutls_ocsp_resp_t resp);
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);
int                 gnutls_ocsp_resp_get_status         (gnutls_ocsp_resp_t resp);
int                 gnutls_ocsp_resp_get_version        (gnutls_ocsp_resp_t resp);
int                 gnutls_ocsp_resp_import             (gnutls_ocsp_resp_t resp,
                                                         const gnutls_datum_t *data);
int                 gnutls_ocsp_resp_init               (gnutls_ocsp_resp_t *resp);
struct              gnutls_ocsp_resp_int;
int                 gnutls_ocsp_resp_print              (gnutls_ocsp_resp_t resp,
                                                         gnutls_ocsp_print_formats_t format,
                                                         gnutls_datum_t *out);
enum                gnutls_ocsp_resp_status_t;
typedef             gnutls_ocsp_resp_t;
int                 gnutls_ocsp_resp_verify             (gnutls_ocsp_resp_t resp,
                                                         gnutls_x509_trust_list_t trustlist,
                                                         unsigned int *verify,
                                                         unsigned int flags);
int                 gnutls_ocsp_resp_verify_direct      (gnutls_ocsp_resp_t resp,
                                                         gnutls_x509_crt_t issuer,
                                                         unsigned int *verify,
                                                         unsigned int flags);
enum                gnutls_ocsp_verify_reason_t;
enum                gnutls_x509_crl_reason_t;

Description

Details

GNUTLS_OCSP_NONCE

#define GNUTLS_OCSP_NONCE "1.3.6.1.5.5.7.48.1.2"


enum gnutls_ocsp_cert_status_t

typedef enum {
      GNUTLS_OCSP_CERT_GOOD = 0,
      GNUTLS_OCSP_CERT_REVOKED = 1,
      GNUTLS_OCSP_CERT_UNKNOWN = 2
} gnutls_ocsp_cert_status_t;

Enumeration of different OCSP response certificate status codes.

GNUTLS_OCSP_CERT_GOOD

Positive response to status inquiry.

GNUTLS_OCSP_CERT_REVOKED

Certificate has been revoked.

GNUTLS_OCSP_CERT_UNKNOWN

The responder doesn't know about the certificate.

enum gnutls_ocsp_print_formats_t

typedef enum {
      GNUTLS_OCSP_PRINT_FULL = 0,
      GNUTLS_OCSP_PRINT_COMPACT = 1,
} gnutls_ocsp_print_formats_t;

Enumeration of different OCSP printing variants.

GNUTLS_OCSP_PRINT_FULL

Full information about OCSP request/response.

GNUTLS_OCSP_PRINT_COMPACT

More compact information about OCSP request/response.

gnutls_ocsp_req_add_cert ()

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);

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 from issuer. The hashed values will be hashed using the digest algorithm, normally GNUTLS_DIG_SHA1.

req :

should contain a gnutls_ocsp_req_t structure

digest :

hash algorithm, a gnutls_digest_algorithm_t value

issuer :

issuer of subject certificate

cert :

certificate to request status for

Returns :

On success, GNUTLS_E_SUCCESS (0) is returned, otherwise a negative error code is returned.

gnutls_ocsp_req_add_cert_id ()

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);

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 of issuer_key_hash (both hashed using digest) and serial number serial_number.

The information needed corresponds to the CertID structure:

1
2
3
4
5
CertID          ::=     SEQUENCE {
    hashAlgorithm       AlgorithmIdentifier,
    issuerNameHash      OCTET STRING, -- Hash of Issuer's DN
    issuerKeyHash       OCTET STRING, -- Hash of Issuers public key
    serialNumber        CertificateSerialNumber }

req :

should contain a gnutls_ocsp_req_t structure

digest :

hash algorithm, a gnutls_digest_algorithm_t value

issuer_name_hash :

hash of issuer's DN

issuer_key_hash :

hash of issuer's public key

serial_number :

serial number of certificate to check

Returns :

On success, GNUTLS_E_SUCCESS (0) is returned, otherwise a negative error code is returned.

gnutls_ocsp_req_deinit ()

void                gnutls_ocsp_req_deinit              (gnutls_ocsp_req_t req);

This function will deinitialize a OCSP request structure.

req :

The structure to be deinitialized

gnutls_ocsp_req_export ()

int                 gnutls_ocsp_req_export              (gnutls_ocsp_req_t req,
                                                         gnutls_datum_t *data);

This function will export the OCSP request to DER format.

req :

Holds the OCSP request

data :

newly allocate buffer holding DER encoded OCSP request

Returns :

In case of failure a negative error code will be returned, and 0 on success.

gnutls_ocsp_req_get_cert_id ()

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);

This function will return the certificate information of the indx'ed request in the OCSP request. The information returned corresponds to the CertID structure:

1
2
3
4
5
CertID          ::=     SEQUENCE {
    hashAlgorithm       AlgorithmIdentifier,
    issuerNameHash      OCTET STRING, -- Hash of Issuer's DN
    issuerKeyHash       OCTET STRING, -- Hash of Issuers public key
    serialNumber        CertificateSerialNumber }

Each of the pointers to output variables may be NULL to indicate that the caller is not interested in that value.

req :

should contain a gnutls_ocsp_req_t structure

indx :

Specifies which extension OID 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

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.

gnutls_ocsp_req_get_extension ()

int                 gnutls_ocsp_req_get_extension       (gnutls_ocsp_req_t req,
                                                         unsigned  indx,
                                                         gnutls_datum_t *oid,
                                                         unsigned int *critical,
                                                         gnutls_datum_t *data);

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, and data 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() on oid->data and data->data.

req :

should contain a gnutls_ocsp_req_t structure

indx :

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

Returns :

On success, GNUTLS_E_SUCCESS (0) is returned, otherwise a negative error code is returned. If you have reached the last extension available GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE will be returned.

gnutls_ocsp_req_get_nonce ()

int                 gnutls_ocsp_req_get_nonce           (gnutls_ocsp_req_t req,
                                                         unsigned int *critical,
                                                         gnutls_datum_t *nonce);

This function will return the OCSP request nonce extension data.

The caller needs to deallocate memory by calling gnutls_free() on nonce->data.

req :

should contain a gnutls_ocsp_req_t structure

critical :

whether nonce extension is marked critical, or NULL

nonce :

will hold newly allocated buffer with nonce data

Returns :

On success, GNUTLS_E_SUCCESS (0) is returned, otherwise a negative error code is returned.

gnutls_ocsp_req_get_version ()

int                 gnutls_ocsp_req_get_version         (gnutls_ocsp_req_t req);

This function will return the version of the OCSP request. Typically this is always 1 indicating version 1.

req :

should contain a gnutls_ocsp_req_t structure

Returns :

version of OCSP request, or a negative error code on error.

gnutls_ocsp_req_import ()

int                 gnutls_ocsp_req_import              (gnutls_ocsp_req_t req,
                                                         const gnutls_datum_t *data);

This function will convert the given DER encoded OCSP request to the native gnutls_ocsp_req_t format. The output will be stored in req.

req :

The structure to store the parsed request.

data :

DER encoded OCSP request.

Returns :

On success, GNUTLS_E_SUCCESS (0) is returned, otherwise a negative error value.

gnutls_ocsp_req_init ()

int                 gnutls_ocsp_req_init                (gnutls_ocsp_req_t *req);

This function will initialize an OCSP request structure.

req :

The structure to be initialized

Returns :

On success, GNUTLS_E_SUCCESS (0) is returned, otherwise a negative error value.

struct gnutls_ocsp_req_int

struct gnutls_ocsp_req_int;


gnutls_ocsp_req_print ()

int                 gnutls_ocsp_req_print               (gnutls_ocsp_req_t req,
                                                         gnutls_ocsp_print_formats_t format,
                                                         gnutls_datum_t *out);

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 using gnutls_free().

req :

The structure to be printed

format :

Indicate the format to use

out :

Newly allocated datum with (0) terminated string.

Returns :

On success, GNUTLS_E_SUCCESS (0) is returned, otherwise a negative error value.

gnutls_ocsp_req_randomize_nonce ()

int                 gnutls_ocsp_req_randomize_nonce     (gnutls_ocsp_req_t req);

This function will add or update an nonce extension to the OCSP request with a newly generated random value.

req :

should contain a gnutls_ocsp_req_t structure

Returns :

On success, GNUTLS_E_SUCCESS (0) is returned, otherwise a negative error code is returned.

gnutls_ocsp_req_set_extension ()

int                 gnutls_ocsp_req_set_extension       (gnutls_ocsp_req_t req,
                                                         const char *oid,
                                                         unsigned int critical,
                                                         const gnutls_datum_t *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.

req :

should contain a gnutls_ocsp_req_t structure

oid :

buffer with OID of extension as a string.

critical :

critical flag, normally false.

data :

the extension data

Returns :

On success, GNUTLS_E_SUCCESS (0) is returned, otherwise a negative error code is returned.

gnutls_ocsp_req_set_nonce ()

int                 gnutls_ocsp_req_set_nonce           (gnutls_ocsp_req_t req,
                                                         unsigned int critical,
                                                         const gnutls_datum_t *nonce);

This function will add an nonce extension to the OCSP request. Calling this function multiple times will overwrite values from earlier calls.

req :

should contain a gnutls_ocsp_req_t structure

critical :

critical flag, normally false.

nonce :

the nonce data

Returns :

On success, GNUTLS_E_SUCCESS (0) is returned, otherwise a negative error code is returned.

gnutls_ocsp_req_t

  typedef struct gnutls_ocsp_req_int *gnutls_ocsp_req_t;


gnutls_ocsp_resp_check_crt ()

int                 gnutls_ocsp_resp_check_crt          (gnutls_ocsp_resp_t resp,
                                                         unsigned int indx,
                                                         gnutls_x509_crt_t crt);

This function will check whether the OCSP response is about the provided certificate.

resp :

should contain a gnutls_ocsp_resp_t structure

indx :

Specifies response number to get. Use (0) to get the first one.

crt :

The certificate to check

Returns :

On success, GNUTLS_E_SUCCESS (0) is returned, otherwise a negative error code is returned.

gnutls_ocsp_resp_deinit ()

void                gnutls_ocsp_resp_deinit             (gnutls_ocsp_resp_t resp);

This function will deinitialize a OCSP response structure.

resp :

The structure to be deinitialized

gnutls_ocsp_resp_export ()

int                 gnutls_ocsp_resp_export             (gnutls_ocsp_resp_t resp,
                                                         gnutls_datum_t *data);

This function will export the OCSP response to DER format.

resp :

Holds the OCSP response

data :

newly allocate buffer holding DER encoded OCSP response

Returns :

In case of failure a negative error code will be returned, and 0 on success.

gnutls_ocsp_resp_get_certs ()

int                 gnutls_ocsp_resp_get_certs          (gnutls_ocsp_resp_t resp,
                                                         gnutls_x509_crt_t **certs,
                                                         size_t *ncerts);

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 using gnutls_free().

Both the certs and ncerts 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.

resp :

should contain a gnutls_ocsp_resp_t structure

certs :

newly allocated array with gnutls_x509_crt_t certificates

ncerts :

output variable with number of allocated certs.

Returns :

On success, GNUTLS_E_SUCCESS (0) is returned, otherwise a negative error value.

gnutls_ocsp_resp_get_extension ()

int                 gnutls_ocsp_resp_get_extension      (gnutls_ocsp_resp_t resp,
                                                         unsigned  indx,
                                                         gnutls_datum_t *oid,
                                                         unsigned int *critical,
                                                         gnutls_datum_t *data);

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, and data 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() on oid->data and data->data.

resp :

should contain a gnutls_ocsp_resp_t structure

indx :

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

Returns :

On success, GNUTLS_E_SUCCESS (0) is returned, otherwise a negative error code is returned. If you have reached the last extension available GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE will be returned.

gnutls_ocsp_resp_get_nonce ()

int                 gnutls_ocsp_resp_get_nonce          (gnutls_ocsp_resp_t resp,
                                                         unsigned int *critical,
                                                         gnutls_datum_t *nonce);

This function will return the Basic OCSP Response nonce extension data.

The caller needs to deallocate memory by calling gnutls_free() on nonce->data.

resp :

should contain a gnutls_ocsp_resp_t structure

critical :

whether nonce extension is marked critical

nonce :

will hold newly allocated buffer with nonce data

Returns :

On success, GNUTLS_E_SUCCESS (0) is returned, otherwise a negative error code is returned.

gnutls_ocsp_resp_get_produced ()

time_t              gnutls_ocsp_resp_get_produced       (gnutls_ocsp_resp_t resp);

This function will return the time when the OCSP response was signed.

resp :

should contain a gnutls_ocsp_resp_t structure

Returns :

signing time, or (time_t)-1 on error.

gnutls_ocsp_resp_get_responder ()

int                 gnutls_ocsp_resp_get_responder      (gnutls_ocsp_resp_t resp,
                                                         gnutls_datum_t *dn);

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() on dn->data.

resp :

should contain a gnutls_ocsp_resp_t structure

dn :

newly allocated buffer with name

Returns :

On success, GNUTLS_E_SUCCESS (0) is returned, otherwise a negative error code is returned.

gnutls_ocsp_resp_get_response ()

int                 gnutls_ocsp_resp_get_response       (gnutls_ocsp_resp_t resp,
                                                         gnutls_datum_t *response_type_oid,
                                                         gnutls_datum_t *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 the response 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.

resp :

should contain a gnutls_ocsp_resp_t structure

response_type_oid :

newly allocated output buffer with response type OID

response :

newly allocated output buffer with DER encoded response

Returns :

On success, GNUTLS_E_SUCCESS (0) is returned, otherwise a negative error value.

gnutls_ocsp_resp_get_signature ()

int                 gnutls_ocsp_resp_get_signature      (gnutls_ocsp_resp_t resp,
                                                         gnutls_datum_t *sig);

This function will extract the signature field of a OCSP response.

resp :

should contain a gnutls_ocsp_resp_t structure

sig :

newly allocated output buffer with signature data

Returns :

On success, GNUTLS_E_SUCCESS (0) is returned, otherwise a negative error value.

gnutls_ocsp_resp_get_signature_algorithm ()

int                 gnutls_ocsp_resp_get_signature_algorithm
                                                        (gnutls_ocsp_resp_t resp);

This 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.

resp :

should contain a gnutls_ocsp_resp_t structure

Returns :

a gnutls_sign_algorithm_t value, or a negative error code on error.

gnutls_ocsp_resp_get_single ()

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);

This function will return the certificate information of the indx'ed response in the Basic OCSP Response resp. The information returned corresponds to the SingleResponse structure except the final singleExtensions, reproduced here for illustration:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
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 }

Each of the pointers to output variables may be NULL to indicate that the caller is not interested in that value.

resp :

should contain a gnutls_ocsp_resp_t structure

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.

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.

gnutls_ocsp_resp_get_status ()

int                 gnutls_ocsp_resp_get_status         (gnutls_ocsp_resp_t resp);

This function will return the status of a OCSP response, an gnutls_ocsp_resp_status_t enumeration.

resp :

should contain a gnutls_ocsp_resp_t structure

Returns :

status of OCSP request as a gnutls_ocsp_resp_status_t, or a negative error code on error.

gnutls_ocsp_resp_get_version ()

int                 gnutls_ocsp_resp_get_version        (gnutls_ocsp_resp_t resp);

This function will return the version of the Basic OCSP Response. Typically this is always 1 indicating version 1.

resp :

should contain a gnutls_ocsp_resp_t structure

Returns :

version of Basic OCSP response, or a negative error code on error.

gnutls_ocsp_resp_import ()

int                 gnutls_ocsp_resp_import             (gnutls_ocsp_resp_t resp,
                                                         const gnutls_datum_t *data);

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 in resp.

resp :

The structure to store the parsed response.

data :

DER encoded OCSP response.

Returns :

On success, GNUTLS_E_SUCCESS (0) is returned, otherwise a negative error value.

gnutls_ocsp_resp_init ()

int                 gnutls_ocsp_resp_init               (gnutls_ocsp_resp_t *resp);

This function will initialize an OCSP response structure.

resp :

The structure to be initialized

Returns :

On success, GNUTLS_E_SUCCESS (0) is returned, otherwise a negative error value.

struct gnutls_ocsp_resp_int

struct gnutls_ocsp_resp_int;


gnutls_ocsp_resp_print ()

int                 gnutls_ocsp_resp_print              (gnutls_ocsp_resp_t resp,
                                                         gnutls_ocsp_print_formats_t format,
                                                         gnutls_datum_t *out);

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 using gnutls_free().

resp :

The structure to be printed

format :

Indicate the format to use

out :

Newly allocated datum with (0) terminated string.

Returns :

On success, GNUTLS_E_SUCCESS (0) is returned, otherwise a negative error value.

enum gnutls_ocsp_resp_status_t

typedef enum {
      GNUTLS_OCSP_RESP_SUCCESSFUL = 0,
      GNUTLS_OCSP_RESP_MALFORMEDREQUEST = 1,
      GNUTLS_OCSP_RESP_INTERNALERROR = 2,
      GNUTLS_OCSP_RESP_TRYLATER = 3,
      GNUTLS_OCSP_RESP_SIGREQUIRED = 5,
      GNUTLS_OCSP_RESP_UNAUTHORIZED = 6
} gnutls_ocsp_resp_status_t;

Enumeration of different OCSP response status codes.

GNUTLS_OCSP_RESP_SUCCESSFUL

Response has valid confirmations.

GNUTLS_OCSP_RESP_MALFORMEDREQUEST

Illegal confirmation request

GNUTLS_OCSP_RESP_INTERNALERROR

Internal error in issuer

GNUTLS_OCSP_RESP_TRYLATER

Try again later

GNUTLS_OCSP_RESP_SIGREQUIRED

Must sign the request

GNUTLS_OCSP_RESP_UNAUTHORIZED

Request unauthorized

gnutls_ocsp_resp_t

  typedef struct gnutls_ocsp_resp_int *gnutls_ocsp_resp_t;


gnutls_ocsp_resp_verify ()

int                 gnutls_ocsp_resp_verify             (gnutls_ocsp_resp_t resp,
                                                         gnutls_x509_trust_list_t trustlist,
                                                         unsigned int *verify,
                                                         unsigned int flags);

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 the trustlist. A trusted signer is a certificate that is either in trustlist, or it is signed directly by a certificate in trustlist 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 returned GNUTLS_E_SUCCESS.

Note that the function returns GNUTLS_E_SUCCESS even when verification failed. The caller must always inspect the verify variable to find out the verification status.

The flags variable should be 0 for now.

resp :

should contain a gnutls_ocsp_resp_t structure

trustlist :

trust anchors as a gnutls_x509_trust_list_t structure

verify :

output variable with verification status, an gnutls_ocsp_cert_status_t

flags :

verification flags, 0 for now.

Returns :

On success, GNUTLS_E_SUCCESS (0) is returned, otherwise a negative error value.

gnutls_ocsp_resp_verify_direct ()

int                 gnutls_ocsp_resp_verify_direct      (gnutls_ocsp_resp_t resp,
                                                         gnutls_x509_crt_t issuer,
                                                         unsigned int *verify,
                                                         unsigned int flags);

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 returned GNUTLS_E_SUCCESS.

Note that the function returns GNUTLS_E_SUCCESS even when verification failed. The caller must always inspect the verify variable to find out the verification status.

The flags variable should be 0 for now.

resp :

should contain a gnutls_ocsp_resp_t structure

issuer :

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.

Returns :

On success, GNUTLS_E_SUCCESS (0) is returned, otherwise a negative error value.

enum gnutls_ocsp_verify_reason_t

typedef enum {
      GNUTLS_OCSP_VERIFY_SIGNER_NOT_FOUND = 1,
      GNUTLS_OCSP_VERIFY_SIGNER_KEYUSAGE_ERROR = 2,
      GNUTLS_OCSP_VERIFY_UNTRUSTED_SIGNER = 4,
      GNUTLS_OCSP_VERIFY_INSECURE_ALGORITHM = 8,
      GNUTLS_OCSP_VERIFY_SIGNATURE_FAILURE = 16,
      GNUTLS_OCSP_VERIFY_CERT_NOT_ACTIVATED = 32,
      GNUTLS_OCSP_VERIFY_CERT_EXPIRED = 64
} gnutls_ocsp_verify_reason_t;

Enumeration of OCSP verify status codes, used by gnutls_ocsp_resp_verify() and gnutls_ocsp_resp_verify_direct().

GNUTLS_OCSP_VERIFY_SIGNER_NOT_FOUND

Signer cert not found.

GNUTLS_OCSP_VERIFY_SIGNER_KEYUSAGE_ERROR

Signer keyusage bits incorrect.

GNUTLS_OCSP_VERIFY_UNTRUSTED_SIGNER

Signer is not trusted.

GNUTLS_OCSP_VERIFY_INSECURE_ALGORITHM

Signature using insecure algorithm.

GNUTLS_OCSP_VERIFY_SIGNATURE_FAILURE

Signature mismatch.

GNUTLS_OCSP_VERIFY_CERT_NOT_ACTIVATED

Signer cert is not yet activated.

GNUTLS_OCSP_VERIFY_CERT_EXPIRED

Signer cert has expired.

enum gnutls_x509_crl_reason_t

typedef enum {
      GNUTLS_X509_CRLREASON_UNSPECIFIED = 0,
      GNUTLS_X509_CRLREASON_KEYCOMPROMISE = 1,
      GNUTLS_X509_CRLREASON_CACOMPROMISE = 2,
      GNUTLS_X509_CRLREASON_AFFILIATIONCHANGED = 3,
      GNUTLS_X509_CRLREASON_SUPERSEDED = 4,
      GNUTLS_X509_CRLREASON_CESSATIONOFOPERATION = 5,
      GNUTLS_X509_CRLREASON_CERTIFICATEHOLD = 6,
      /* -- value 7 is not used */
      GNUTLS_X509_CRLREASON_REMOVEFROMCRL = 8,
      GNUTLS_X509_CRLREASON_PRIVILEGEWITHDRAWN = 9,
      GNUTLS_X509_CRLREASON_AACOMPROMISE = 10
} gnutls_x509_crl_reason_t;

Enumeration of different reason codes. Note that this corresponds to the CRLReason ASN.1 enumeration type, and not the ReasonFlags ASN.1 bit string.

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.