ocsp.h

Functions

	Name
WOLFSSL_OCSP *	wc_NewOCSP(WOLFSSL_CERT_MANAGER * cm) Allocates and initialises an OCSP context.
void	wc_FreeOCSP(WOLFSSL_OCSP * ocsp) Frees resources associated with an OCSP context.
int	wc_CheckCertOcspResponse(WOLFSSL_OCSP * ocsp, DecodedCert * cert, byte * response, int responseSz, void * heap) Checks the OCSP response for a given certificate.
OcspRequest *	wc_OcspRequest_new(void * heap) Allocates a new OcspRequest structure.
void	wc_OcspRequest_free(OcspRequest * request) Frees an OcspRequest structure.
int	wc_InitOcspRequest(OcspRequest * req, DecodedCert * cert, byte useNonce, void * heap) Initializes an OcspRequest from a decoded certificate.
int	wc_EncodeOcspRequest(OcspRequest * req, byte * output, word32 size) Encodes an OCSP request into DER format.
OcspResponse *	wc_OcspResponse_new(void * heap) Allocates a new OcspResponse structure.
void	wc_OcspResponse_free(OcspResponse * response) Frees an OcspResponse structure.
OcspResponder *	wc_OcspResponder_new(void * heap, int sendCerts) Allocates and initializes a new OCSP Responder.
void	wc_OcspResponder_free(OcspResponder * responder) Frees an OCSP Responder and all associated resources.
int	wc_OcspResponder_AddSigner(OcspResponder * responder, const byte * signerDer, word32 signerDerSz, const byte * keyDer, word32 keyDerSz, const byte * issuerCertDer, word32 issuerCertDerSz) Adds a signing certificate and key to the OCSP Responder.
int	wc_OcspResponder_SetCertStatus(OcspResponder * responder, const char * caSubject, word32 caSubjectSz, const byte * serial, word32 serialSz, enum Ocsp_Cert_Status status, time_t revocationTime, enum WC_CRL_Reason revocationReason, word32 validityPeriod) Sets the revocation status of a certificate in the OCSP Responder.
int	wc_OcspResponder_WriteResponse(OcspResponder * responder, const byte * request, word32 requestSz, byte * response, word32 * responseSz) Generates an OCSP response for a given OCSP request.
int	wc_OcspResponder_WriteErrorResponse(enum Ocsp_Response_Status status, byte * response, word32 * responseSz) Generates an OCSP error response.

Functions Documentation

function wc_NewOCSP

WOLFSSL_OCSP * wc_NewOCSP(
    WOLFSSL_CERT_MANAGER * cm
)

Allocates and initialises an OCSP context.

Parameters:

cm Pointer to the certificate manager.

See: wc_FreeOCSP

Return:

Pointer to allocated WOLFSSL_OCSP on success
NULL on failure

This function allocates and initialises a WOLFSSL_OCSP structure for use with OCSP operations.

function wc_FreeOCSP

void wc_FreeOCSP(
    WOLFSSL_OCSP * ocsp
)

Frees resources associated with an OCSP context.

Parameters:

ocsp Pointer to the WOLFSSL_OCSP structure to free.

See: wc_NewOCSP

Return: void

This function releases any resources associated with a WOLFSSL_OCSP structure.

function wc_CheckCertOcspResponse

int wc_CheckCertOcspResponse(
    WOLFSSL_OCSP * ocsp,
    DecodedCert * cert,
    byte * response,
    int responseSz,
    void * heap
)

Checks the OCSP response for a given certificate.

Parameters:

ocsp Pointer to the WOLFSSL_OCSP structure.
cert Pointer to the decoded certificate.
response Pointer to the OCSP response buffer.
responseSz Size of the OCSP response buffer.
heap Optional heap pointer.

Return:

0 on success
<0 on failure

This function verifies an OCSP response for a specific certificate.

function wc_OcspRequest_new

OcspRequest * wc_OcspRequest_new(
    void * heap
)

Allocates a new OcspRequest structure.

Parameters:

heap Pointer to a heap hint for dynamic memory allocation, or NULL to use the default allocator.

See:

Return:

Pointer to a newly allocated OcspRequest on success.
NULL on memory allocation failure.

This function allocates and zero-initializes an OcspRequest structure on the heap. The caller must free the returned object with wc_OcspRequest_free().

function wc_OcspRequest_free

void wc_OcspRequest_free(
    OcspRequest * request
)

Frees an OcspRequest structure.

Parameters:

request Pointer to the OcspRequest to free. May be NULL, in which case this function is a no-op.

See: wc_OcspRequest_new

Return: void

This function releases all resources associated with an OcspRequest that was allocated with wc_OcspRequest_new(). It frees any internal allocations associated with the request before freeing the structure itself.

function wc_InitOcspRequest

int wc_InitOcspRequest(
    OcspRequest * req,
    DecodedCert * cert,
    byte useNonce,
    void * heap
)

Initializes an OcspRequest from a decoded certificate.

Parameters:

req Pointer to the OcspRequest structure to initialize.
cert Pointer to the DecodedCert from which to extract certificate information.
useNonce If non-zero, a nonce extension will be added to the OCSP request.
heap Pointer to a heap hint for dynamic memory allocation, or NULL.

See:

Return:

0 on success.
BAD_FUNC_ARG if req or cert is NULL.
Other negative values on internal errors.

This function populates an OcspRequest structure with the issuer hash, issuer key hash, and serial number extracted from the given decoded certificate. Optionally, a nonce can be included in the request.

function wc_EncodeOcspRequest

int wc_EncodeOcspRequest(
    OcspRequest * req,
    byte * output,
    word32 size
)

Encodes an OCSP request into DER format.

Parameters:

req Pointer to the initialized OcspRequest to encode.
output Pointer to the output buffer that will receive the DER-encoded OCSP request.
size Size of the output buffer in bytes.

See:

Return:

The size of the encoded request in bytes on success.
Negative error code on failure.

This function encodes a previously initialized OcspRequest into its DER wire format suitable for transmission to an OCSP responder.

function wc_OcspResponse_new

OcspResponse * wc_OcspResponse_new(
    void * heap
)

Allocates a new OcspResponse structure.

Parameters:

heap Pointer to a heap hint for dynamic memory allocation, or NULL to use the default allocator.

See: wc_OcspResponse_free

Return:

Pointer to a newly allocated OcspResponse on success.
NULL on memory allocation failure.

This function allocates and zero-initializes an OcspResponse structure on the heap. The caller must free the returned object with wc_OcspResponse_free().

function wc_OcspResponse_free

void wc_OcspResponse_free(
    OcspResponse * response
)

Frees an OcspResponse structure.

Parameters:

response Pointer to the OcspResponse to free. May be NULL, in which case this function is a no-op.

See: wc_OcspResponse_new

Return: void

This function releases all resources associated with an OcspResponse that was allocated with wc_OcspResponse_new(). It frees any internal allocations associated with the response before freeing the structure itself.

function wc_OcspResponder_new

OcspResponder * wc_OcspResponder_new(
    void * heap,
    int sendCerts
)

Allocates and initializes a new OCSP Responder.

Parameters:

heap Pointer to a heap hint for dynamic memory allocation, or NULL.
sendCerts If non-zero, the responder will include the signer certificate in generated OCSP responses.

See:

Return:

Pointer to a newly allocated OcspResponder on success.
NULL on failure (memory allocation or RNG initialization failure).

This function creates an OcspResponder that can process OCSP requests and generate signed responses. The responder must have at least one signer added via wc_OcspResponder_AddSigner() before it can produce responses.

Requires HAVE_OCSP_RESPONDER to be defined.

function wc_OcspResponder_free

void wc_OcspResponder_free(
    OcspResponder * responder
)

Frees an OCSP Responder and all associated resources.

Parameters:

responder Pointer to the OcspResponder to free. May be NULL, in which case this function is a no-op.

See: wc_OcspResponder_new

Return: void

This function releases all memory associated with an OcspResponder, including all CA entries, certificate statuses, private keys, and the internal RNG.

Requires HAVE_OCSP_RESPONDER to be defined.

function wc_OcspResponder_AddSigner

int wc_OcspResponder_AddSigner(
    OcspResponder * responder,
    const byte * signerDer,
    word32 signerDerSz,
    const byte * keyDer,
    word32 keyDerSz,
    const byte * issuerCertDer,
    word32 issuerCertDerSz
)

Adds a signing certificate and key to the OCSP Responder.

Parameters:

responder Pointer to the OcspResponder.
signerDer Pointer to the DER-encoded signer certificate.
signerDerSz Size of the signer certificate in bytes.
keyDer Pointer to the DER-encoded private key.
keyDerSz Size of the private key in bytes.
issuerCertDer Pointer to the DER-encoded issuing CA certificate, or NULL if the signer is itself the CA.
issuerCertDerSz Size of the issuing CA certificate in bytes, or 0 if the signer is itself the CA.

See:

Return:

0 on success.
BAD_FUNC_ARG if required parameters are NULL/zero, if the private key does not match the certificate, or if an authorized responder is missing the OCSP Signing extended key usage.
MEMORY_E on memory allocation failure.
DUPE_ENTRY_E if a signer with the same issuer hashes already exists.
Other negative error codes on parsing or key loading failures.

This function registers a signer with the OCSP responder. The signer certificate and its corresponding private key are used to sign OCSP responses. The signer can be either:

A CA certificate that directly issued the certificates being queried (issuerCertDer is NULL or zero-length).
An authorized OCSP responder delegated by the issuing CA (issuerCertDer points to the issuing CA certificate). In this case the signer certificate must have the OCSP Signing extended key usage.

All certificate and key data must be in DER format.

Requires HAVE_OCSP_RESPONDER to be defined.

function wc_OcspResponder_SetCertStatus

int wc_OcspResponder_SetCertStatus(
    OcspResponder * responder,
    const char * caSubject,
    word32 caSubjectSz,
    const byte * serial,
    word32 serialSz,
    enum Ocsp_Cert_Status status,
    time_t revocationTime,
    enum WC_CRL_Reason revocationReason,
    word32 validityPeriod
)

Sets the revocation status of a certificate in the OCSP Responder.

Parameters:

responder Pointer to the OcspResponder.
caSubject The issuing CA subject name in the one-line distinguished name format used internally by the library (e.g. "/C=US/O=Org/CN=CA"). To avoid mismatches, obtain this value from wc_GetDecodedCertSubject() rather than constructing the string manually.
caSubjectSz Length of the caSubject string in bytes, not including any NUL terminator.
serial Pointer to the certificate serial number bytes.
serialSz Size of the serial number in bytes.
status Certificate status: CERT_GOOD, CERT_REVOKED, or CERT_UNKNOWN.
revocationTime The time of revocation (only used when status is CERT_REVOKED, must be > 0 for revoked certs).
revocationReason The CRL reason code for revocation (only used when status is CERT_REVOKED). See enum WC_CRL_Reason for valid values.
validityPeriod Validity period in seconds for CERT_GOOD responses. Must be non-zero for CERT_GOOD status and zero for other statuses.

See:

Return:

0 on success.
BAD_FUNC_ARG if required parameters are NULL/zero or if status/revocation parameters are inconsistent.
ASN_NO_SIGNER_E if no CA with the given subject name is found.
MEMORY_E on memory allocation failure.

This function configures the status that the responder will report for a specific certificate identified by its serial number. The certificate must belong to a CA that has been previously added via wc_OcspResponder_AddSigner(). The CA is identified by its subject name.

If a status entry already exists for the given serial number, it will be updated.

Requires HAVE_OCSP_RESPONDER to be defined.

function wc_OcspResponder_WriteResponse

int wc_OcspResponder_WriteResponse(
    OcspResponder * responder,
    const byte * request,
    word32 requestSz,
    byte * response,
    word32 * responseSz
)

Generates an OCSP response for a given OCSP request.

Parameters:

responder Pointer to the OcspResponder.
request Pointer to the DER-encoded OCSP request.
requestSz Size of the OCSP request in bytes.
response Pointer to the output buffer for the DER-encoded OCSP response.
responseSz Pointer to a word32 containing the size of the response buffer on input, and receiving the actual response size on output.

See:

Return:

0 on success.
BAD_FUNC_ARG if required parameters are NULL/zero.
Negative error codes on decode, lookup, or encoding failures.

This function processes a DER-encoded OCSP request, looks up the certificate status in the responder's database, and produces a signed OCSP response. The responder must have a signer and certificate status entries configured via wc_OcspResponder_AddSigner() and wc_OcspResponder_SetCertStatus() before calling this function.

Requires HAVE_OCSP_RESPONDER to be defined.

function wc_OcspResponder_WriteErrorResponse

int wc_OcspResponder_WriteErrorResponse(
    enum Ocsp_Response_Status status,
    byte * response,
    word32 * responseSz
)

Generates an OCSP error response.

Parameters:

status The OCSP error status code. Must not be OCSP_SUCCESSFUL. Valid values include OCSP_MALFORMED_REQUEST, OCSP_INTERNAL_ERROR, OCSP_TRY_LATER, OCSP_SIG_REQUIRED, and OCSP_UNAUTHORIZED.
response Pointer to the output buffer for the DER-encoded error response.
responseSz Pointer to a word32 containing the size of the response buffer on input, and receiving the actual response size on output.

See: wc_OcspResponder_WriteResponse

Return:

0 on success.
BAD_FUNC_ARG if responseSz is NULL or if status is OCSP_SUCCESSFUL.
Negative error codes on encoding failure.

This function encodes an OCSP response with an error status code and no response body. This is used when the responder cannot process a request (e.g., malformed request, internal error, unauthorized).

Requires HAVE_OCSP_RESPONDER to be defined.

Source code


WOLFSSL_OCSP* wc_NewOCSP(WOLFSSL_CERT_MANAGER* cm);

void wc_FreeOCSP(WOLFSSL_OCSP* ocsp);

int wc_CheckCertOcspResponse(WOLFSSL_OCSP *ocsp, DecodedCert *cert, byte *response, int responseSz, void* heap);

OcspRequest* wc_OcspRequest_new(void* heap);

void wc_OcspRequest_free(OcspRequest* request);

int wc_InitOcspRequest(OcspRequest* req, DecodedCert* cert,
                                    byte useNonce, void* heap);

int wc_EncodeOcspRequest(OcspRequest* req, byte* output,
                                      word32 size);

OcspResponse* wc_OcspResponse_new(void* heap);

void wc_OcspResponse_free(OcspResponse* response);

OcspResponder* wc_OcspResponder_new(void* heap, int sendCerts);

void wc_OcspResponder_free(OcspResponder* responder);

int wc_OcspResponder_AddSigner(OcspResponder* responder,
    const byte* signerDer, word32 signerDerSz,
    const byte* keyDer, word32 keyDerSz,
    const byte* issuerCertDer, word32 issuerCertDerSz);

int wc_OcspResponder_SetCertStatus(OcspResponder* responder,
    const char* caSubject, word32 caSubjectSz,
    const byte* serial, word32 serialSz, enum Ocsp_Cert_Status status,
    time_t revocationTime, enum WC_CRL_Reason revocationReason,
    word32 validityPeriod);

int wc_OcspResponder_WriteResponse(OcspResponder* responder,
    const byte* request, word32 requestSz,
    byte* response, word32* responseSz);

int wc_OcspResponder_WriteErrorResponse(
    enum Ocsp_Response_Status status,
    byte* response, word32* responseSz);

Updated on 2026-04-22 at 01:11:02 +0000