x509crlwrite.h File Reference

X.509 certificate revocation list builder, signing, and PEM encoding interface. More...

#include "qsccommon.h"
#include "x509crl.h"
#include "x509types.h"

Go to the source code of this file.

Data Structures
struct	qsc_x509_crl_builder_t

Macros
#define	QSC_X509_CRL_WRITE_MAX   8192U
	The maximum number of octets used by the CRL writer scratch buffers.

Typedefs
typedef struct qsc_x509_crl_builder_t	qsc_x509_crl_builder

Functions
QSC_EXPORT_API void	qsc_x509_crl_builder_initialize (qsc_x509_crl_builder *builder)
	Initialize a CRL builder.
QSC_EXPORT_API void	qsc_x509_crl_builder_clear (qsc_x509_crl_builder *builder)
	Clear a CRL builder.
QSC_EXPORT_API qsc_asn1_status	qsc_x509_crl_builder_set_issuer (qsc_x509_crl_builder *builder, const qsc_x509_name *issuer)
	Set the CRL issuer distinguished name.
QSC_EXPORT_API qsc_asn1_status	qsc_x509_crl_builder_set_update_times (qsc_x509_crl_builder *builder, const qsc_asn1_time *thisupdate, const qsc_asn1_time *nextupdate)
	Set the CRL update times.
QSC_EXPORT_API qsc_asn1_status	qsc_x509_crl_builder_set_signature_algorithm (qsc_x509_crl_builder *builder, const qsc_x509_algorithm_identifier *signaturealgorithm)
	Set the CRL signature algorithm identifier.
QSC_EXPORT_API qsc_asn1_status	qsc_x509_crl_builder_validate_issuer (const qsc_x509_crl_builder *builder, const qsc_x509_certificate *issuer)
	Validate the builder issuer against an issuer certificate.
QSC_EXPORT_API qsc_asn1_status	qsc_x509_crl_builder_add_revoked_serial (qsc_x509_crl_builder *builder, const uint8_t *serialnumber, size_t serialnumberlen, const qsc_asn1_time *revocationdate)
	Add a revoked certificate entry by serial number.
QSC_EXPORT_API qsc_asn1_status	qsc_x509_crl_builder_add_extension (qsc_x509_crl_builder *builder, const qsc_x509_extension *extension)
	Add a CRL extension to the builder.
QSC_EXPORT_API qsc_asn1_status	qsc_x509_crl_builder_encode_tbs_der (const qsc_x509_crl_builder *builder, uint8_t *output, size_t *outputlen)
	Encode the TBSCertList portion as DER.
QSC_EXPORT_API qsc_asn1_status	qsc_x509_crl_builder_sign (const qsc_x509_crl_builder *builder, qsc_x509_certificate_sign_callback signcallback, void *context, uint8_t *output, size_t *outputlen)
	Sign and encode a complete CRL.
QSC_EXPORT_API qsc_asn1_status	qsc_x509_crl_der_encode_pem (const uint8_t *der, size_t derlen, char *output, size_t *outputlen)
	Encode a DER CRL into PEM.
QSC_EXPORT_API qsc_asn1_status	qsc_x509_crl_encode_pem (const qsc_x509_crl *crl, char *output, size_t *outputlen)
	Encode a decoded CRL object into PEM.

Detailed Description

X.509 certificate revocation list builder, signing, and PEM encoding interface.

This header declares the public interface used to construct, validate, encode, sign, and PEM-convert X.509 Certificate Revocation Lists (CRLs). The builder stores the issuer name, update times, signature algorithm, optional CRL extensions, and a bounded list of revoked certificate entries.

The interface supports generation of the TBSCertList DER payload, final CertificateList signing through a caller supplied signing callback, and conversion of either a DER encoded CRL or a decoded CRL object into PEM.

Macro Definition Documentation

QSC_X509_CRL_WRITE_MAX

#define QSC_X509_CRL_WRITE_MAX   8192U

The maximum number of octets used by the CRL writer scratch buffers.

This constant defines the fixed upper bound used by internal CRL writing routines when assembling temporary DER encodings during CRL generation.

Function Documentation

qsc_x509_crl_builder_add_extension()

QSC_EXPORT_API qsc_asn1_status qsc_x509_crl_builder_add_extension	(	qsc_x509_crl_builder *	builder,
		const qsc_x509_extension *	extension )

Add a CRL extension to the builder.

Appends a caller supplied extension object to the set of CRL extensions being assembled by the builder. Duplicate extension types or duplicate extension object identifiers are rejected.

Parameters

builder	[struct] The destination CRL builder.
extension	[const][struct] The extension to add.

Returns

[enum] Returns a qsc_asn1_status code indicating success or failure.

qsc_x509_crl_builder_add_revoked_serial()

QSC_EXPORT_API qsc_asn1_status qsc_x509_crl_builder_add_revoked_serial	(	qsc_x509_crl_builder *	builder,
		const uint8_t *	serialnumber,
		size_t	serialnumberlen,
		const qsc_asn1_time *	revocationdate )

Add a revoked certificate entry by serial number.

Appends a revoked-certificate entry to the builder using the supplied serial number and revocation date. Leading zero octets in the supplied serial number are normalized before storage, and duplicate serial numbers are rejected.

Parameters

builder	[struct] The destination CRL builder.
serialnumber	[const] The revoked certificate serial number.
serialnumberlen	The length of the serial number in bytes.
revocationdate	[const][struct] The revocation date for the entry.

Returns

[enum] Returns a qsc_asn1_status code indicating success or failure.

qsc_x509_crl_builder_clear()

QSC_EXPORT_API void qsc_x509_crl_builder_clear

(

qsc_x509_crl_builder *

builder

)

Clear a CRL builder.

Clears all builder state and resets any accumulated CRL construction data. This function is used to erase or reinitialize a builder after use.

Parameters

builder

[struct] The CRL builder to clear.

Returns

[void] This function does not return a value.

qsc_x509_crl_builder_encode_tbs_der()

QSC_EXPORT_API qsc_asn1_status qsc_x509_crl_builder_encode_tbs_der	(	const qsc_x509_crl_builder *	builder,
		uint8_t *	output,
		size_t *	outputlen )

Encode the TBSCertList portion as DER.

Serializes the builder contents into the DER representation of the TBSCertList structure without applying a signature. The caller may pass a null output buffer to query the required size through outputlen.

Parameters

builder	[const][struct] The source CRL builder.
output	The destination buffer receiving the DER encoding.
outputlen	The input capacity of output and, on success, the number of bytes written.

Returns

[enum] Returns a qsc_asn1_status code indicating success or failure.

qsc_x509_crl_builder_initialize()

QSC_EXPORT_API void qsc_x509_crl_builder_initialize

(

qsc_x509_crl_builder *

builder

)

Initialize a CRL builder.

Resets the CRL builder to a clean default state suitable for CRL construction. This function shall be called before any other builder mutator is used on the object.

Parameters

builder

[struct] The CRL builder to initialize.

Returns

[void] This function does not return a value.

qsc_x509_crl_builder_set_issuer()

QSC_EXPORT_API qsc_asn1_status qsc_x509_crl_builder_set_issuer	(	qsc_x509_crl_builder *	builder,
		const qsc_x509_name *	issuer )

Set the CRL issuer distinguished name.

Copies the issuer name into the builder for subsequent TBSCertList or CertificateList encoding.

Parameters

builder	[struct] The destination CRL builder.
issuer	[const][struct] The issuer distinguished name.

Returns

[enum] Returns a qsc_asn1_status code indicating success or failure.

qsc_x509_crl_builder_set_signature_algorithm()

QSC_EXPORT_API qsc_asn1_status qsc_x509_crl_builder_set_signature_algorithm	(	qsc_x509_crl_builder *	builder,
		const qsc_x509_algorithm_identifier *	signaturealgorithm )

Set the CRL signature algorithm identifier.

Assigns the AlgorithmIdentifier used in the TBSCertList signature field and the outer CertificateList signature field when the CRL is signed.

Parameters

builder	[struct] The destination CRL builder.
signaturealgorithm	[const][struct] The signature AlgorithmIdentifier.

Returns

[enum] Returns a qsc_asn1_status code indicating success or failure.

qsc_x509_crl_builder_set_update_times()

QSC_EXPORT_API qsc_asn1_status qsc_x509_crl_builder_set_update_times	(	qsc_x509_crl_builder *	builder,
		const qsc_asn1_time *	thisupdate,
		const qsc_asn1_time *	nextupdate )

Set the CRL update times.

Assigns the thisUpdate and nextUpdate values that define the CRL validity interval. The interval is rejected when thisUpdate is later than nextUpdate.

Parameters

builder	[struct] The destination CRL builder.
thisupdate	[const][struct] The CRL thisUpdate time.
nextupdate	[const][struct] The CRL nextUpdate time.

Returns

[enum] Returns a qsc_asn1_status code indicating success or failure.

qsc_x509_crl_builder_sign()

QSC_EXPORT_API qsc_asn1_status qsc_x509_crl_builder_sign	(	const qsc_x509_crl_builder *	builder,
		qsc_x509_certificate_sign_callback	signcallback,
		void *	context,
		uint8_t *	output,
		size_t *	outputlen )

Sign and encode a complete CRL.

Encodes the TBSCertList, invokes the caller supplied signing callback to produce the CRL signature, and emits the final DER encoded CertificateList structure.

Parameters

builder	[const][struct] The source CRL builder.
signcallback	The signing callback used to produce the CRL signature.
context	Caller defined opaque signing context passed to the callback.
output	The destination buffer receiving the DER encoded CRL.
outputlen	The input capacity of output and, on success, the number of bytes written.

Returns

[enum] Returns a qsc_asn1_status code indicating success or failure.

qsc_x509_crl_builder_validate_issuer()

QSC_EXPORT_API qsc_asn1_status qsc_x509_crl_builder_validate_issuer	(	const qsc_x509_crl_builder *	builder,
		const qsc_x509_certificate *	issuer )

Validate the builder issuer against an issuer certificate.

Checks that the builder issuer state is compatible with the supplied issuer certificate before CRL signing or issuance.

Parameters

builder	[const][struct] The source CRL builder.
issuer	[const][struct] The issuer certificate expected to sign the CRL.

Returns

[enum] Returns a qsc_asn1_status code indicating validation success or failure.

qsc_x509_crl_der_encode_pem()

QSC_EXPORT_API qsc_asn1_status qsc_x509_crl_der_encode_pem	(	const uint8_t *	der,
		size_t	derlen,
		char *	output,
		size_t *	outputlen )

Encode a DER CRL into PEM.

Converts a DER encoded CRL into textual PEM form including the BEGIN X509 CRL and END X509 CRL encapsulation markers.

Parameters

der	[const] The DER encoded CRL input.
derlen	The length of the DER input in bytes.
output	The destination character buffer receiving the PEM text.
outputlen	The input capacity of output and, on success, the number of characters written.

Returns

[enum] Returns a qsc_asn1_status code indicating success or failure.

qsc_x509_crl_encode_pem()

QSC_EXPORT_API qsc_asn1_status qsc_x509_crl_encode_pem	(	const qsc_x509_crl *	crl,
		char *	output,
		size_t *	outputlen )

Encode a decoded CRL object into PEM.

Serializes a decoded CRL object and converts it into textual PEM form. This function provides object-to-PEM conversion for CRL instances already held in decoded representation.

Parameters

crl	[const][struct] The decoded CRL object.
output	The destination character buffer receiving the PEM text.
outputlen	The input capacity of output and, on success, the number of characters written.

Returns

[enum] Returns a qsc_asn1_status code indicating success or failure.