x509csr.h File Reference

PKCS#10 certificate signing request encoding, decoding, mutation, and verification interface. More...

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

Go to the source code of this file.

Data Structures
struct	qsc_x509_csr_attribute_t
	A decoded or mutable PKCS#10 CSR attribute. More...
struct	qsc_x509_csr_t
	A decoded or mutable PKCS#10 certificate signing request. More...

Macros
#define	QSC_X509_CSR_ATTRIBUTES_MAX   8U
	The maximum number of generic non-extension CSR attributes stored in a CSR object.
#define	QSC_X509_CSR_ATTRIBUTE_VALUE_MAX   1024U
	The maximum number of DER octets stored for a generic CSR attribute value.
#define	QSC_X509_CSR_WRITE_MAX   16384U
	The maximum number of octets used by CSR writer scratch buffers.

Typedefs
typedef QSC_EXPORT_API struct qsc_x509_csr_attribute_t	qsc_x509_csr_attribute
	A decoded or mutable PKCS#10 CSR attribute.
typedef QSC_EXPORT_API struct qsc_x509_csr_t	qsc_x509_csr
	A decoded or mutable PKCS#10 certificate signing request.
typedef bool(*	qsc_x509_csr_signature_verify_callback) (const qsc_x509_csr *csr, void *state)
	Caller-supplied CSR signature verification callback type.

Functions
QSC_EXPORT_API bool	qsc_x509_csr_verify_with_spki (const qsc_x509_csr *csr, const qsc_x509_subject_public_key_info *signerspki)
	Verify a CSR signature against a caller-supplied signer SPKI.
QSC_EXPORT_API void	qsc_x509_csr_initialize (qsc_x509_csr *csr)
	Initialize a CSR object.
QSC_EXPORT_API void	qsc_x509_csr_clear (qsc_x509_csr *csr)
	Clear a CSR object.
QSC_EXPORT_API qsc_asn1_status	qsc_x509_csr_set_subject (qsc_x509_csr *csr, const qsc_x509_name *subject)
	Set the CSR subject distinguished name.
QSC_EXPORT_API qsc_asn1_status	qsc_x509_csr_set_spki (qsc_x509_csr *csr, const qsc_x509_subject_public_key_info *spki)
	Set the CSR subject public key information.
QSC_EXPORT_API qsc_asn1_status	qsc_x509_csr_set_signature_algorithm (qsc_x509_csr *csr, const qsc_x509_algorithm_identifier *signaturealgorithm)
	Set the CSR signature algorithm identifier.
QSC_EXPORT_API qsc_asn1_status	qsc_x509_csr_set_extension_request (qsc_x509_csr *csr, const qsc_x509_extensions *extensions)
	Set the normalized extensionRequest payload.
QSC_EXPORT_API const qsc_x509_extensions *	qsc_x509_csr_get_extension_request (const qsc_x509_csr *csr)
	Get the normalized extensionRequest payload.
QSC_EXPORT_API qsc_asn1_status	qsc_x509_csr_copy_extension_request (const qsc_x509_csr *csr, qsc_x509_extensions *extensions)
	Copy the normalized extensionRequest payload.
QSC_EXPORT_API qsc_asn1_status	qsc_x509_csr_encode_info_der (const qsc_x509_csr *csr, uint8_t *output, size_t *outputlen)
	Encode the CertificationRequestInfo structure as DER.
QSC_EXPORT_API qsc_asn1_status	qsc_x509_csr_encode_der (const qsc_x509_csr *csr, qsc_x509_certificate_sign_callback signcallback, void *context, uint8_t *output, size_t *outputlen)
	Encode and sign a complete CSR as DER.
QSC_EXPORT_API qsc_asn1_status	qsc_x509_csr_sign (const qsc_x509_csr *csr, qsc_x509_certificate_sign_callback signcallback, void *context, uint8_t *output, size_t *outputlen)
	Sign and encode a CSR as DER.
QSC_EXPORT_API qsc_asn1_status	qsc_x509_csr_decode_der (qsc_x509_csr *csr, const uint8_t *input, size_t inputlen)
	Decode a DER encoded CSR.
QSC_EXPORT_API qsc_asn1_status	qsc_x509_csr_decode_pem (qsc_x509_csr *csr, const char *input, size_t inputlen)
	Decode a PEM encoded CSR.
QSC_EXPORT_API const qsc_x509_extension *	qsc_x509_csr_find_extension (const qsc_x509_csr *csr, qsc_x509_extension_type type)
	Find a requested extension by type.
QSC_EXPORT_API bool	qsc_x509_csr_verify (const qsc_x509_csr *csr)
	Verify a CSR using its contained subject public key information.
QSC_EXPORT_API bool	qsc_x509_csr_verify_ex (const qsc_x509_csr *csr, qsc_x509_csr_signature_verify_callback verifycallback, void *state)
	Verify a CSR using a caller-supplied verification callback.
QSC_EXPORT_API qsc_asn1_status	qsc_x509_csr_encode_pem (const uint8_t *der, size_t derlen, char *output, size_t *outputlen)
	Encode a DER CSR as PEM.
QSC_EXPORT_API qsc_asn1_status	qsc_x509_csr_add_attribute (qsc_x509_csr *csr, const qsc_asn1_oid *oid, const uint8_t *value, size_t valuelen)
	Add a generic non-extension CSR attribute.
QSC_EXPORT_API const qsc_x509_csr_attribute *	qsc_x509_csr_get_attribute (const qsc_x509_csr *csr, const qsc_asn1_oid *oid)
	Get a generic CSR attribute by OID.
QSC_EXPORT_API qsc_asn1_status	qsc_x509_csr_set_subject_alt_name (qsc_x509_csr *csr, const qsc_x509_subject_alt_name *subjectaltname)
	Set the requested Subject Alternative Name extension.
QSC_EXPORT_API qsc_asn1_status	qsc_x509_csr_add_san_dns (qsc_x509_csr *csr, const char *dnsname, size_t dnsnamelen)
	Add a DNS name to the requested Subject Alternative Name extension.
QSC_EXPORT_API qsc_asn1_status	qsc_x509_csr_add_san_ip (qsc_x509_csr *csr, const uint8_t *address, size_t addresslen)
	Add an IP address to the requested Subject Alternative Name extension.
QSC_EXPORT_API qsc_asn1_status	qsc_x509_csr_set_extended_key_usage (qsc_x509_csr *csr, const qsc_x509_extended_key_usage *extendedkeyusage)
	Set the requested Extended Key Usage extension.
QSC_EXPORT_API qsc_asn1_status	qsc_x509_csr_set_subject_key_identifier (qsc_x509_csr *csr, const qsc_x509_subject_key_identifier *subjectkeyidentifier)
	Set the requested Subject Key Identifier extension.
QSC_EXPORT_API qsc_asn1_status	qsc_x509_csr_set_ml_dsa_signature_algorithm (qsc_x509_csr *csr, uint32_t level)
	Set the CSR signature algorithm to an ML-DSA variant.
QSC_EXPORT_API qsc_asn1_status	qsc_x509_csr_set_ml_dsa_spki (qsc_x509_csr *csr, uint32_t level, const uint8_t *publickey, size_t publickeylen)
	Set the CSR subject public key information to an ML-DSA key.
QSC_EXPORT_API qsc_asn1_status	qsc_x509_csr_set_ml_kem_spki (qsc_x509_csr *csr, uint32_t level, const uint8_t *publickey, size_t publickeylen)
	Set the CSR subject public key information to an ML-KEM key.

Detailed Description

PKCS#10 certificate signing request encoding, decoding, mutation, and verification interface.

This header defines the public interface used to construct, decode, inspect, sign, verify, and PEM-convert PKCS#10 certificate signing requests. The CSR object stores the request subject name, subject public key information, signature algorithm identifier, requested X.509 extensions, optional generic CSR attributes, signature bytes, and references to the original DER-encoded CertificationRequestInfo and full CertificationRequest buffers.

The interface supports direct field mutation for request construction, extensionRequest normalization through the qsc_x509_extensions container, generic non-extension attribute storage, callback-driven signing, default and custom verification paths, and convenience helpers for Subject Alternative Name, Extended Key Usage, Subject Key Identifier, ML-DSA, and ML-KEM request population. Decoded CSRs preserve an owned copy of the original DER request buffer together with the exact CertificationRequestInfo signed region so that verification can prefer the original wire encoding.

Typedef Documentation

qsc_x509_csr_attribute

typedef QSC_EXPORT_API struct qsc_x509_csr_attribute_t qsc_x509_csr_attribute

A decoded or mutable PKCS#10 CSR attribute.

The value buffer stores the DER encoding of the first value element contained in the Attribute values SET. The PKCS#9 extensionRequest attribute is not represented through this generic container; it is normalized into the qsc_x509_extensions structure stored in the parent CSR object.

qsc_x509_csr_signature_verify_callback

typedef bool(* qsc_x509_csr_signature_verify_callback) (const qsc_x509_csr *csr, void *state)

Caller-supplied CSR signature verification callback type.

This callback is used by qsc_x509_csr_verify_ex to delegate cryptographic signature verification to the surrounding verification layer.

Parameters

csr	[const][struct] The CSR to verify.
state	Caller-defined opaque verification context.

Returns

Returns true if the CSR signature is valid; otherwise returns false.

Function Documentation

qsc_x509_csr_add_attribute()

QSC_EXPORT_API qsc_asn1_status qsc_x509_csr_add_attribute	(	qsc_x509_csr *	csr,
		const qsc_asn1_oid *	oid,
		const uint8_t *	value,
		size_t	valuelen )

Add a generic non-extension CSR attribute.

Adds a generic CSR attribute identified by the supplied OID and storing the DER encoding of the first attribute value.

Parameters

csr	[struct] The CSR object to update.
oid	[const][struct] The attribute object identifier.
value	[const] The DER encoded first attribute value.
valuelen	The length of the value in bytes.

Returns

[enum] Returns a qsc_asn1_status code.

qsc_x509_csr_add_san_dns()

QSC_EXPORT_API qsc_asn1_status qsc_x509_csr_add_san_dns	(	qsc_x509_csr *	csr,
		const char *	dnsname,
		size_t	dnsnamelen )

Add a DNS name to the requested Subject Alternative Name extension.

Parameters

csr	[struct] The CSR object to update.
dnsname	[const] The DNS name string.
dnsnamelen	The length of the DNS name string in bytes.

Returns

[enum] Returns a qsc_asn1_status code.

qsc_x509_csr_add_san_ip()

QSC_EXPORT_API qsc_asn1_status qsc_x509_csr_add_san_ip	(	qsc_x509_csr *	csr,
		const uint8_t *	address,
		size_t	addresslen )

Add an IP address to the requested Subject Alternative Name extension.

Parameters

csr	[struct] The CSR object to update.
address	[const] The binary IP address.
addresslen	The length of the binary IP address in bytes.

Returns

[enum] Returns a qsc_asn1_status code.

qsc_x509_csr_clear()

QSC_EXPORT_API void qsc_x509_csr_clear

(

qsc_x509_csr *

csr

)

Clear a CSR object.

Clears all mutable and decoded state held in the CSR object.

Parameters

csr	[struct] The CSR object to clear.

Returns

[void] This function does not return a value.

qsc_x509_csr_copy_extension_request()

QSC_EXPORT_API qsc_asn1_status qsc_x509_csr_copy_extension_request	(	const qsc_x509_csr *	csr,
		qsc_x509_extensions *	extensions )

Copy the normalized extensionRequest payload.

Parameters

csr	[const][struct] The CSR object to inspect.
extensions	[struct] The destination extension set.

Returns

[enum] Returns a qsc_asn1_status code.

qsc_x509_csr_decode_der()

QSC_EXPORT_API qsc_asn1_status qsc_x509_csr_decode_der	(	qsc_x509_csr *	csr,
		const uint8_t *	input,
		size_t	inputlen )

Decode a DER encoded CSR.

Parameters

csr	[struct] The destination CSR object.
input	[const] The DER encoded CSR input buffer.
inputlen	The length of the input buffer in bytes.

Returns

[enum] Returns a qsc_asn1_status code.

qsc_x509_csr_decode_pem()

QSC_EXPORT_API qsc_asn1_status qsc_x509_csr_decode_pem	(	qsc_x509_csr *	csr,
		const char *	input,
		size_t	inputlen )

Decode a PEM encoded CSR.

Parameters

csr	[struct] The destination CSR object.
input	[const] The PEM encoded CSR input buffer.
inputlen	The length of the input buffer in bytes.

Returns

[enum] Returns a qsc_asn1_status code.

qsc_x509_csr_encode_der()

QSC_EXPORT_API qsc_asn1_status qsc_x509_csr_encode_der	(	const qsc_x509_csr *	csr,
		qsc_x509_certificate_sign_callback	signcallback,
		void *	context,
		uint8_t *	output,
		size_t *	outputlen )

Encode and sign a complete CSR as DER.

Encodes the CertificationRequestInfo structure, invokes the supplied signing callback, and emits the complete DER encoded CertificationRequest object.

Parameters

csr	[const][struct] The CSR object to encode.
signcallback	The CSR signing callback.
context	Caller-defined opaque signing context.
output	The destination buffer receiving the DER CSR.
outputlen	The input capacity of the output buffer and, on success, the number of bytes written.

Returns

[enum] Returns a qsc_asn1_status code.

qsc_x509_csr_encode_info_der()

QSC_EXPORT_API qsc_asn1_status qsc_x509_csr_encode_info_der	(	const qsc_x509_csr *	csr,
		uint8_t *	output,
		size_t *	outputlen )

Encode the CertificationRequestInfo structure as DER.

Serializes only the unsigned CertificationRequestInfo portion of the CSR.

Parameters

csr	[const][struct] The CSR object to encode.
output	The destination buffer receiving the DER output.
outputlen	The input capacity of the output buffer and, on success, the number of bytes written.

Returns

[enum] Returns a qsc_asn1_status code.

qsc_x509_csr_encode_pem()

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

Encode a DER CSR as PEM.

Parameters

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

Returns

[enum] Returns a qsc_asn1_status code.

qsc_x509_csr_find_extension()

QSC_EXPORT_API const qsc_x509_extension * qsc_x509_csr_find_extension	(	const qsc_x509_csr *	csr,
		qsc_x509_extension_type	type )

Find a requested extension by type.

Parameters

csr	[const][struct] The CSR object to inspect.
type	[enum] The extension type to locate.

Returns

Returns a pointer to the matching extension, or NULL if no match is present.

qsc_x509_csr_get_attribute()

QSC_EXPORT_API const qsc_x509_csr_attribute * qsc_x509_csr_get_attribute	(	const qsc_x509_csr *	csr,
		const qsc_asn1_oid *	oid )

Get a generic CSR attribute by OID.

Parameters

csr	[const][struct] The CSR object to inspect.
oid	[const][struct] The attribute object identifier to locate.

Returns

Returns a pointer to the matching attribute, or NULL if no match is present.

qsc_x509_csr_get_extension_request()

QSC_EXPORT_API const qsc_x509_extensions * qsc_x509_csr_get_extension_request

(

const qsc_x509_csr *

csr

)

Get the normalized extensionRequest payload.

Parameters

csr	[const][struct] The CSR object to inspect.

Returns

Returns a pointer to the requested extension set.

qsc_x509_csr_initialize()

QSC_EXPORT_API void qsc_x509_csr_initialize

(

qsc_x509_csr *

csr

)

Initialize a CSR object.

Initializes a CSR object to a clean default state suitable for first use. For an object that may already hold decoded or owned DER state, call qsc_x509_csr_clear() instead.

Parameters

csr	[struct] The CSR object to initialize.

Returns

[void] This function does not return a value.

qsc_x509_csr_set_extended_key_usage()

QSC_EXPORT_API qsc_asn1_status qsc_x509_csr_set_extended_key_usage	(	qsc_x509_csr *	csr,
		const qsc_x509_extended_key_usage *	extendedkeyusage )

Set the requested Extended Key Usage extension.

Parameters

csr	[struct] The CSR object to update.
extendedkeyusage	[const][struct] The Extended Key Usage value.

Returns

[enum] Returns a qsc_asn1_status code.

qsc_x509_csr_set_extension_request()

QSC_EXPORT_API qsc_asn1_status qsc_x509_csr_set_extension_request	(	qsc_x509_csr *	csr,
		const qsc_x509_extensions *	extensions )

Set the normalized extensionRequest payload.

Replaces the CSR extensionRequest contents with the supplied X.509 extension set.

Parameters

csr	[struct] The CSR object to update.
extensions	[const][struct] The requested extension set.

Returns

[enum] Returns a qsc_asn1_status code.

qsc_x509_csr_set_ml_dsa_signature_algorithm()

QSC_EXPORT_API qsc_asn1_status qsc_x509_csr_set_ml_dsa_signature_algorithm	(	qsc_x509_csr *	csr,
		uint32_t	level )

Set the CSR signature algorithm to an ML-DSA variant.

Selects the ML-DSA parameter set corresponding to the supplied level and updates the CSR signature algorithm identifier accordingly.

Parameters

csr	[struct] The CSR object to update.
level	The ML-DSA parameter-set level selector.

Returns

[enum] Returns a qsc_asn1_status code.

qsc_x509_csr_set_ml_dsa_spki()

QSC_EXPORT_API qsc_asn1_status qsc_x509_csr_set_ml_dsa_spki	(	qsc_x509_csr *	csr,
		uint32_t	level,
		const uint8_t *	publickey,
		size_t	publickeylen )

Set the CSR subject public key information to an ML-DSA key.

Populates the CSR SPKI field using an ML-DSA public key and the supplied ML-DSA parameter-set level.

Parameters

csr	[struct] The CSR object to update.
level	The ML-DSA parameter-set level selector.
publickey	[const] The ML-DSA public key bytes.
publickeylen	The length of the public key in bytes.

Returns

[enum] Returns a qsc_asn1_status code.

qsc_x509_csr_set_ml_kem_spki()

QSC_EXPORT_API qsc_asn1_status qsc_x509_csr_set_ml_kem_spki	(	qsc_x509_csr *	csr,
		uint32_t	level,
		const uint8_t *	publickey,
		size_t	publickeylen )

Set the CSR subject public key information to an ML-KEM key.

Populates the CSR SPKI field using an ML-KEM public key and the supplied ML-KEM parameter-set level.

Parameters

csr	[struct] The CSR object to update.
level	The ML-KEM parameter-set level selector.
publickey	[const] The ML-KEM public key bytes.
publickeylen	The length of the public key in bytes.

Returns

[enum] Returns a qsc_asn1_status code.

qsc_x509_csr_set_signature_algorithm()

QSC_EXPORT_API qsc_asn1_status qsc_x509_csr_set_signature_algorithm	(	qsc_x509_csr *	csr,
		const qsc_x509_algorithm_identifier *	signaturealgorithm )

Set the CSR signature algorithm identifier.

Parameters

csr	[struct] The CSR object to update.
signaturealgorithm	[const][struct] The signature algorithm identifier.

Returns

[enum] Returns a qsc_asn1_status code.

qsc_x509_csr_set_spki()

QSC_EXPORT_API qsc_asn1_status qsc_x509_csr_set_spki	(	qsc_x509_csr *	csr,
		const qsc_x509_subject_public_key_info *	spki )

Set the CSR subject public key information.

Parameters

csr	[struct] The CSR object to update.
spki	[const][struct] The subject public key information.

Returns

[enum] Returns a qsc_asn1_status code.

qsc_x509_csr_set_subject()

QSC_EXPORT_API qsc_asn1_status qsc_x509_csr_set_subject	(	qsc_x509_csr *	csr,
		const qsc_x509_name *	subject )

Set the CSR subject distinguished name.

Parameters

csr	[struct] The CSR object to update.
subject	[const][struct] The subject distinguished name.

Returns

[enum] Returns a qsc_asn1_status code.

qsc_x509_csr_set_subject_alt_name()

QSC_EXPORT_API qsc_asn1_status qsc_x509_csr_set_subject_alt_name	(	qsc_x509_csr *	csr,
		const qsc_x509_subject_alt_name *	subjectaltname )

Set the requested Subject Alternative Name extension.

Parameters

csr	[struct] The CSR object to update.
subjectaltname	[const][struct] The Subject Alternative Name value.

Returns

[enum] Returns a qsc_asn1_status code.

qsc_x509_csr_set_subject_key_identifier()

QSC_EXPORT_API qsc_asn1_status qsc_x509_csr_set_subject_key_identifier	(	qsc_x509_csr *	csr,
		const qsc_x509_subject_key_identifier *	subjectkeyidentifier )

Set the requested Subject Key Identifier extension.

Parameters

csr	[struct] The CSR object to update.
subjectkeyidentifier	[const][struct] The Subject Key Identifier value.

Returns

[enum] Returns a qsc_asn1_status code.

qsc_x509_csr_sign()

QSC_EXPORT_API qsc_asn1_status qsc_x509_csr_sign	(	const qsc_x509_csr *	csr,
		qsc_x509_certificate_sign_callback	signcallback,
		void *	context,
		uint8_t *	output,
		size_t *	outputlen )

Sign and encode a CSR as DER.

This function performs CSR signing and final DER emission. It provides a semantically explicit signing entry point alongside qsc_x509_csr_encode_der.

Parameters

csr	[const][struct] The CSR object to sign.
signcallback	The CSR signing callback.
context	Caller-defined opaque signing context.
output	The destination buffer receiving the DER CSR.
outputlen	The input capacity of the output buffer and, on success, the number of bytes written.

Returns

[enum] Returns a qsc_asn1_status code.

qsc_x509_csr_verify()

QSC_EXPORT_API bool qsc_x509_csr_verify

(

const qsc_x509_csr *

csr

)

Verify a CSR using its contained subject public key information.

Parameters

csr	[const][struct] The CSR to verify.

Returns

Returns true if the CSR signature is valid; otherwise returns false.

qsc_x509_csr_verify_ex()

QSC_EXPORT_API bool qsc_x509_csr_verify_ex	(	const qsc_x509_csr *	csr,
		qsc_x509_csr_signature_verify_callback	verifycallback,
		void *	state )

Verify a CSR using a caller-supplied verification callback.

Parameters

csr	[const][struct] The CSR to verify.
verifycallback	The verification callback.
state	Caller-defined opaque verification context.

Returns

Returns true if the CSR signature is valid; otherwise returns false.

qsc_x509_csr_verify_with_spki()

QSC_EXPORT_API bool qsc_x509_csr_verify_with_spki	(	const qsc_x509_csr *	csr,
		const qsc_x509_subject_public_key_info *	signerspki )

Verify a CSR signature against a caller-supplied signer SPKI.

This function verifies the CSR signature using the supplied subject public key information structure rather than the SPKI carried inside the CSR. It is intended for cases where signature verification is performed against an external or previously normalized public key representation.

Parameters

csr	[const][struct] The CSR to verify.
signerspki	[const][struct] The signer subject public key information used for verification.

Returns

Returns true if the CSR signature is valid; otherwise returns false.