x509ocsp.h File Reference

X.509 OCSP response parsing and online certificate status validation interface. More...

#include "qsccommon.h"
#include "x509cert.h"
#include "x509store.h"
#include "x509verify.h"

Go to the source code of this file.

Data Structures
struct	qsc_x509_ocsp_response_t

Macros
#define	QSC_X509_OCSP_NONCE_MAX   32U
	The maximum supported OCSP nonce length in bytes.

Typedefs
typedef enum qsc_x509_ocsp_cert_status_t	qsc_x509_ocsp_cert_status
typedef struct qsc_x509_ocsp_response_t	qsc_x509_ocsp_response
typedef bool(*	qsc_x509_ocsp_fetch_callback) (const char *url, const uint8_t *request, size_t requestlen, uint8_t *response, size_t *responselen, void *context)
	Caller-supplied OCSP transport callback.

Enumerations
enum	qsc_x509_ocsp_cert_status_t { QSC_X509_OCSP_STATUS_GOOD = 0 , QSC_X509_OCSP_STATUS_REVOKED = 1 , QSC_X509_OCSP_STATUS_UNKNOWN = 2 }

Functions
QSC_EXPORT_API bool	qsc_x509_ocsp_parse_response (const uint8_t *der, size_t derlen, qsc_x509_ocsp_response *response)
	Parse an OCSP response from DER.
QSC_EXPORT_API bool	qsc_x509_ocsp_validate (const qsc_x509_certificate *certificate, const qsc_x509_certificate *issuer, const char *url, qsc_x509_ocsp_fetch_callback fetch, void *context, const qsc_asn1_time *now, qsc_x509_ocsp_response *response)
	Validate a certificate using OCSP.
QSC_EXPORT_API bool	qsc_x509_ocsp_verify_responder (const qsc_x509_certificate *responder, const qsc_x509_certificate *issuer, const qsc_x509_store *store, const qsc_asn1_time *now)
	Verify an OCSP responder certificate.

Detailed Description

X.509 OCSP response parsing and online certificate status validation interface.

This header defines the public interface used to parse a simplified OCSP response result and to perform OCSP-based certificate status validation through a caller-supplied fetch callback. The interface models the resulting certificate status, optional revocation time, and optional nonce returned by the responder.

The OCSP transport operation is intentionally abstracted. Network retrieval is delegated to the application through a callback that accepts the responder URL and a serialized OCSP request buffer and returns the responder output bytes for local validation and parsing.

Typedef Documentation

qsc_x509_ocsp_fetch_callback

typedef bool(* qsc_x509_ocsp_fetch_callback) (const char *url, const uint8_t *request, size_t requestlen, uint8_t *response, size_t *responselen, void *context)

Caller-supplied OCSP transport callback.

This callback performs the responder fetch operation for OCSP validation. The caller receives the responder URL and serialized request bytes and is responsible for transmitting the request and returning the raw OCSP response bytes.

Parameters

url	[const] The OCSP responder URL.
request	[const] The serialized OCSP request buffer.
requestlen	The length of the request buffer in bytes.
response	The destination buffer receiving the responder output bytes.
responselen	The input capacity of the response buffer and, on success, the number of bytes written.
context	Caller-defined opaque transport context.

Returns

Returns true on successful fetch and response delivery; otherwise returns false.

Enumeration Type Documentation

qsc_x509_ocsp_cert_status_t

enum qsc_x509_ocsp_cert_status_t

Enumerator
QSC_X509_OCSP_STATUS_GOOD	The responder reported that the certificate status is good.
QSC_X509_OCSP_STATUS_REVOKED	The responder reported that the certificate has been revoked.
QSC_X509_OCSP_STATUS_UNKNOWN	The responder could not determine the certificate status.

Function Documentation

qsc_x509_ocsp_parse_response()

QSC_EXPORT_API bool qsc_x509_ocsp_parse_response	(	const uint8_t *	der,
		size_t	derlen,
		qsc_x509_ocsp_response *	response )

Parse an OCSP response from DER.

Decodes a DER encoded OCSP response using strict DER parsing and extracts the normalized certificate status, optional revocation time, and optional nonce fields into the supplied response object.

Parameters

der	[const] The DER encoded OCSP response buffer.
derlen	The length of the DER buffer in bytes.
response	[struct] The destination parsed OCSP response object.

Returns

Returns true if the OCSP response was successfully parsed; otherwise returns false.

qsc_x509_ocsp_validate()

QSC_EXPORT_API bool qsc_x509_ocsp_validate	(	const qsc_x509_certificate *	certificate,
		const qsc_x509_certificate *	issuer,
		const char *	url,
		qsc_x509_ocsp_fetch_callback	fetch,
		void *	context,
		const qsc_asn1_time *	now,
		qsc_x509_ocsp_response *	response )

Validate a certificate using OCSP.

Builds an OCSP request for the supplied certificate and issuer certificate, retrieves the responder output through the caller-supplied fetch callback, validates and parses the result, verifies the BasicOCSPResponse using the preserved signed bytes, and stores the normalized OCSP status in the destination response object.

Parameters

certificate	[const][struct] The certificate whose revocation status is being queried.
issuer	[const][struct] The issuer certificate for the queried certificate.
url	[const] The OCSP responder URL.
fetch	The caller-supplied OCSP transport callback.
context	Caller-defined opaque transport context.
now	[const][struct] The caller-supplied validation time used for responder and response freshness checks.
response	[struct] The destination parsed OCSP response object.

Returns

Returns true if OCSP validation completed successfully; otherwise returns false.

qsc_x509_ocsp_verify_responder()

QSC_EXPORT_API bool qsc_x509_ocsp_verify_responder	(	const qsc_x509_certificate *	responder,
		const qsc_x509_certificate *	issuer,
		const qsc_x509_store *	store,
		const qsc_asn1_time *	now )

Verify an OCSP responder certificate.

Validates that the supplied responder certificate is acceptable for signing OCSP BasicOCSPResponse objects for the supplied issuer. The function checks the responder validity interval, enforces the OCSP signing extended key usage for delegated responders, optionally accepts an explicitly trusted responder present in the supplied trust store, and otherwise verifies the responder certificate against the issuer certificate using the library's signature verification path.

When the responder certificate is the issuer certificate itself, the OCSP signing extended key usage is not required. When the responder is delegated, the certificate must include either anyExtendedKeyUsage or id-kp-OCSPSigning. If the KeyUsage extension is present, the digitalSignature bit must be set.

Parameters

responder	[const][struct] The responder certificate extracted from the OCSP response.
issuer	[const][struct] The issuer certificate for the certificate whose status is being checked.
store	[const][struct] Optional trust store containing explicitly trusted responder certificates.
now	[const][struct] The caller-supplied validation time.

Returns

Returns true if the responder certificate is acceptable for OCSP response signing; otherwise returns false.