x509pem.h File Reference

PEM bundle decoding, object extraction, and PEM encoding utilities for X.509 objects. More...

#include "qsccommon.h"
#include "x509cert.h"
#include "x509crl.h"
#include "x509csr.h"
#include "x509key.h"
#include "x509types.h"

Go to the source code of this file.

Macros
#define	QSC_X509_PEM_DER_MAX   16384U
	The maximum DER object size supported by the PEM conversion helpers.
#define	QSC_X509_PEM_BINARY_MAX   8192U
	Maximum binary input size for PEM encoding operations.
#define	QSC_X509_PEM_TEXT_MAX   ((((QSC_X509_PEM_BINARY_MAX + 2U) / 3U) * 4U) + 512U)
	Maximum buffer size required for PEM-encoded text output.

Functions
QSC_EXPORT_API qsc_asn1_status	qsc_x509_certificate_decode_pem (const char *pem, size_t pemlen, qsc_x509_certificate *certificate)
	Decode a PEM encoded certificate.
QSC_EXPORT_API void	qsc_x509_chain_free (qsc_x509_chain *chain)
	Free the resources associated with a decoded certificate chain.
QSC_EXPORT_API void	qsc_x509_store_free (qsc_x509_store *store)
	Free the resources associated with a certificate store.
QSC_EXPORT_API qsc_asn1_status	qsc_x509_chain_decode_pem_bundle (const char *pem, size_t pemlen, qsc_x509_certificate *certificates, size_t certcount, qsc_x509_chain *chain)
	Decode a PEM certificate bundle into a chain object.
QSC_EXPORT_API qsc_asn1_status	qsc_x509_store_load_pem_bundle (const char *pem, size_t pemlen, qsc_x509_trust_anchor *anchors, size_t anchorcount, qsc_x509_store *store)
	Load a PEM trust-anchor bundle into a certificate store.
QSC_EXPORT_API qsc_asn1_status	qsc_x509_csr_decode_pem_from_bundle (const char *pem, size_t pemlen, qsc_x509_csr *csr)
	Decode a CSR from a PEM bundle.
QSC_EXPORT_API qsc_asn1_status	qsc_x509_crl_decode_pem (const char *pem, size_t pemlen, qsc_x509_crl *crl)
	Decode a CRL from a PEM bundle.
QSC_EXPORT_API qsc_asn1_status	qsc_x509_private_key_decode_pem_from_bundle (const char *pem, size_t pemlen, qsc_x509_private_key *key)
	Decode a private key from a PEM bundle.
QSC_EXPORT_API qsc_asn1_status	qsc_x509_private_key_decode_sec1_pem_from_bundle (const char *pem, size_t pemlen, qsc_x509_private_key *key)
	Decode a SEC 1 private key from a PEM bundle.
QSC_EXPORT_API qsc_asn1_status	qsc_x509_private_key_decode_pkcs8_pem_from_bundle (const char *pem, size_t pemlen, qsc_x509_private_key *key)
	Decode a PKCS #8 private key from a PEM bundle.
QSC_EXPORT_API qsc_asn1_status	qsc_x509_private_key_decode_pkcs8_pem_ex_from_bundle (const char *pem, size_t pemlen, qsc_x509_algorithm_identifier *algorithm, uint8_t *privatekey, size_t privatekeycapacity, size_t *privatekeylen, uint8_t *publickey, size_t publickeycapacity, size_t *publickeylen, bool *publickeypresent)
	Decode a PKCS #8 private key from a PEM bundle into caller-supplied buffers.
QSC_EXPORT_API qsc_asn1_status	qsc_x509_pem_encode_private_key_pkcs8 (const uint8_t *der, size_t derlen, char *pem, size_t *pemlen)
	Convert a DER encoded PKCS #8 private key to PEM.
QSC_EXPORT_API qsc_asn1_status	qsc_x509_pem_encode_private_key_sec1 (const uint8_t *der, size_t derlen, char *pem, size_t *pemlen)
	Convert a DER encoded SEC 1 private key to PEM.
QSC_EXPORT_API qsc_asn1_status	qsc_x509_pem_encode_private_key_pkcs8_from_key (const qsc_x509_private_key *key, bool includepublickey, char *pem, size_t *pemlen)
	Encode a normalized private key object as PKCS #8 PEM.
QSC_EXPORT_API qsc_asn1_status	qsc_x509_pem_encode_private_key_sec1_from_key (const qsc_x509_private_key *key, bool includeparameters, bool includepublickey, char *pem, size_t *pemlen)
	Encode a normalized private key object as SEC 1 PEM.
QSC_EXPORT_API qsc_asn1_status	qsc_x509_pem_encode_certificate (const uint8_t *der, size_t derlen, char *pem, size_t *pemlen)
	Convert a DER encoded certificate to PEM.
QSC_EXPORT_API qsc_asn1_status	qsc_x509_pem_encode_crl (const uint8_t *der, size_t derlen, char *pem, size_t *pemlen)
	Convert a DER encoded CRL to PEM.
QSC_EXPORT_API qsc_asn1_status	qsc_x509_pem_encode_csr (const uint8_t *der, size_t derlen, char *pem, size_t *pemlen)
	Convert a DER encoded CSR to PEM.

Detailed Description

PEM bundle decoding, object extraction, and PEM encoding utilities for X.509 objects.

This header defines helper functions used to decode PEM encoded X.509 certificates, chains, trust stores, certificate signing requests, certificate revocation lists, and private keys. The interface also provides PEM emission helpers for DER encoded certificates, CRLs, CSRs, and private keys in PKCS #8 and SEC 1 form.

PEM bundle decoding helpers accept concatenated PEM text and extract the first matching object or populate caller-supplied chain and store containers. All searches are bounded by the supplied pemlen window so trailing or adjacent data outside that window is not consulted during label discovery. PEM encoding helpers support the standard two-pass pattern: pass a NULL output pointer or a too-small output buffer to receive the required size in pemlen and a QSC_ASN1_STATUS_BUFFER_TOO_SMALL result, then call again with a suitably sized output buffer. Private-key bundle helpers support both generic dispatch and format-specific SEC 1 and PKCS #8 decoding paths.

Macro Definition Documentation

QSC_X509_PEM_BINARY_MAX

#define QSC_X509_PEM_BINARY_MAX   8192U

Maximum binary input size for PEM encoding operations.

This macro defines the upper bound, in bytes, of DER-encoded (binary) data that may be supplied to PEM encoding routines. It is derived from QSC_X509_KEY_WRITE_MAX and therefore reflects the maximum size of supported X.509 key material in binary form, including structures such as PKCS#8 private keys and SubjectPublicKeyInfo.

This value is used as the input capacity for base64 encoding when generating PEM output. It does not represent the size of the resulting PEM text.

Note

The corresponding PEM text output buffer must be sized using QSC_X509_PEM_TEXT_MAX, which accounts for base64 expansion and formatting overhead.

QSC_X509_PEM_TEXT_MAX

#define QSC_X509_PEM_TEXT_MAX   ((((QSC_X509_PEM_BINARY_MAX + 2U) / 3U) * 4U) + 512U)

Maximum buffer size required for PEM-encoded text output.

This macro defines the maximum number of bytes required to store the PEM representation of binary X.509 data. It accounts for:

• Base64 expansion (4 output bytes for every 3 input bytes),
• Line breaks inserted during PEM formatting,
• Header and footer delimiters (e.g. "-----BEGIN ...-----"),
• A safety margin to accommodate formatting variations.

The base64 expansion is computed as: ceil(n / 3) * 4 where n is the binary input size (QSC_X509_PEM_BINARY_MAX).

An additional fixed overhead of 512 bytes is included to ensure sufficient space for PEM headers, footers, line wrapping, and null termination.

This macro should be used to size buffers passed to PEM encoding functions such as qsc_x509_certificate_encode_pem(), qsc_x509_csr_encode_pem(), and qsc_x509_private_key_encode_pkcs8_pem().

Note

This value is format-dependent and independent of the underlying cryptographic algorithm. Larger key types (e.g. ML-DSA-87) increase the required size through QSC_X509_PEM_BINARY_MAX.

Function Documentation

qsc_x509_certificate_decode_pem()

QSC_EXPORT_API qsc_asn1_status qsc_x509_certificate_decode_pem	(	const char *	pem,
		size_t	pemlen,
		qsc_x509_certificate *	certificate )

Decode a PEM encoded certificate.

Parses a PEM encoded X.509 certificate and decodes the contained DER Certificate object into the supplied certificate structure.

Parameters

pem	[const] The PEM encoded certificate text.
pemlen	The length of the PEM text in bytes.
certificate	[struct] The destination certificate object.

Returns

[enum] Returns a qsc_asn1_status code.

qsc_x509_chain_decode_pem_bundle()

QSC_EXPORT_API qsc_asn1_status qsc_x509_chain_decode_pem_bundle	(	const char *	pem,
		size_t	pemlen,
		qsc_x509_certificate *	certificates,
		size_t	certcount,
		qsc_x509_chain *	chain )

Decode a PEM certificate bundle into a chain object.

Parses a concatenated PEM bundle containing one or more certificates and loads the decoded certificates into the caller-supplied chain object using the provided certificate storage array.

Parameters

pem	[const] The PEM bundle text.
pemlen	The length of the PEM bundle in bytes.
certificates	[struct] The caller-supplied certificate storage array.
certcount	The number of certificate elements available in certificates.
chain	[struct] The destination certificate chain object.

Returns

[enum] Returns a qsc_asn1_status code.

qsc_x509_chain_free()

QSC_EXPORT_API void qsc_x509_chain_free

(

qsc_x509_chain *

chain

)

Free the resources associated with a decoded certificate chain.

Releases or resets any internal state held by the supplied chain object after PEM bundle loading or chain construction.

Parameters

chain

[struct] The certificate chain object to free.

Returns

[void] This function does not return a value.

qsc_x509_crl_decode_pem()

QSC_EXPORT_API qsc_asn1_status qsc_x509_crl_decode_pem	(	const char *	pem,
		size_t	pemlen,
		qsc_x509_crl *	crl )

Decode a CRL from a PEM bundle.

Searches a PEM bundle for a certificate revocation list object and decodes the first matching CRL into the destination structure.

Parameters

pem	[const] The PEM bundle text.
pemlen	The length of the PEM bundle in bytes.
crl	[struct] The destination CRL object.

Returns

[enum] Returns a qsc_asn1_status code.

qsc_x509_csr_decode_pem_from_bundle()

QSC_EXPORT_API qsc_asn1_status qsc_x509_csr_decode_pem_from_bundle	(	const char *	pem,
		size_t	pemlen,
		qsc_x509_csr *	csr )

Decode a CSR from a PEM bundle.

Searches a PEM bundle for a certificate signing request object and decodes the first matching CSR into the destination structure.

Parameters

pem	[const] The PEM bundle text.
pemlen	The length of the PEM bundle in bytes.
csr	[struct] The destination CSR object.

Returns

[enum] Returns a qsc_asn1_status code.

qsc_x509_pem_encode_certificate()

QSC_EXPORT_API qsc_asn1_status qsc_x509_pem_encode_certificate	(	const uint8_t *	der,
		size_t	derlen,
		char *	pem,
		size_t *	pemlen )

Convert a DER encoded certificate to PEM.

Parameters

der	[const] The DER encoded certificate.
derlen	The length of the DER input in bytes.
pem	The destination PEM buffer.
pemlen	The input capacity of the PEM buffer and, on success, the number of characters written.

Returns

[enum] Returns a qsc_asn1_status code.

qsc_x509_pem_encode_crl()

QSC_EXPORT_API qsc_asn1_status qsc_x509_pem_encode_crl	(	const uint8_t *	der,
		size_t	derlen,
		char *	pem,
		size_t *	pemlen )

Convert a DER encoded CRL to PEM.

Parameters

der	[const] The DER encoded CRL.
derlen	The length of the DER input in bytes.
pem	The destination PEM buffer.
pemlen	The input capacity of the PEM buffer and, on success, the number of characters written.

Returns

[enum] Returns a qsc_asn1_status code.

qsc_x509_pem_encode_csr()

QSC_EXPORT_API qsc_asn1_status qsc_x509_pem_encode_csr	(	const uint8_t *	der,
		size_t	derlen,
		char *	pem,
		size_t *	pemlen )

Convert a DER encoded CSR to PEM.

Parameters

der	[const] The DER encoded CSR.
derlen	The length of the DER input in bytes.
pem	The destination PEM buffer.
pemlen	The input capacity of the PEM buffer and, on success, the number of characters written.

Returns

[enum] Returns a qsc_asn1_status code.

qsc_x509_pem_encode_private_key_pkcs8()

QSC_EXPORT_API qsc_asn1_status qsc_x509_pem_encode_private_key_pkcs8	(	const uint8_t *	der,
		size_t	derlen,
		char *	pem,
		size_t *	pemlen )

Convert a DER encoded PKCS #8 private key to PEM.

Parameters

der	[const] The DER encoded private key.
derlen	The length of the DER input in bytes.
pem	The destination PEM buffer.
pemlen	The input capacity of the PEM buffer and, on success, the number of characters written.

Returns

[enum] Returns a qsc_asn1_status code.

qsc_x509_pem_encode_private_key_pkcs8_from_key()

QSC_EXPORT_API qsc_asn1_status qsc_x509_pem_encode_private_key_pkcs8_from_key	(	const qsc_x509_private_key *	key,
		bool	includepublickey,
		char *	pem,
		size_t *	pemlen )

Encode a normalized private key object as PKCS #8 PEM.

Serializes the supplied private-key container as PKCS #8 and converts the resulting DER object to PEM text form.

Parameters

key	[const][struct] The source private-key container.
includepublickey	Includes the optional embedded public key when set to true.
pem	The destination PEM buffer.
pemlen	The input capacity of the PEM buffer and, on success, the number of characters written.

Returns

[enum] Returns a qsc_asn1_status code.

qsc_x509_pem_encode_private_key_sec1()

QSC_EXPORT_API qsc_asn1_status qsc_x509_pem_encode_private_key_sec1	(	const uint8_t *	der,
		size_t	derlen,
		char *	pem,
		size_t *	pemlen )

Convert a DER encoded SEC 1 private key to PEM.

Parameters

der	[const] The DER encoded private key.
derlen	The length of the DER input in bytes.
pem	The destination PEM buffer.
pemlen	The input capacity of the PEM buffer and, on success, the number of characters written.

Returns

[enum] Returns a qsc_asn1_status code.

qsc_x509_pem_encode_private_key_sec1_from_key()

QSC_EXPORT_API qsc_asn1_status qsc_x509_pem_encode_private_key_sec1_from_key	(	const qsc_x509_private_key *	key,
		bool	includeparameters,
		bool	includepublickey,
		char *	pem,
		size_t *	pemlen )

Encode a normalized private key object as SEC 1 PEM.

Serializes the supplied private-key container as SEC 1 and converts the resulting DER object to PEM text form.

Parameters

key	[const][struct] The source private-key container.
includeparameters	Includes algorithm parameters when set to true.
includepublickey	Includes the optional embedded public key when set to true.
pem	The destination PEM buffer.
pemlen	The input capacity of the PEM buffer and, on success, the number of characters written.

Returns

[enum] Returns a qsc_asn1_status code.

qsc_x509_private_key_decode_pem_from_bundle()

QSC_EXPORT_API qsc_asn1_status qsc_x509_private_key_decode_pem_from_bundle	(	const char *	pem,
		size_t	pemlen,
		qsc_x509_private_key *	key )

Decode a private key from a PEM bundle.

Searches a PEM bundle for a supported private-key object and decodes the first matching key into the normalized private-key container.

Parameters

pem	[const] The PEM bundle text.
pemlen	The length of the PEM bundle in bytes.
key	[struct] The destination private-key object.

Returns

[enum] Returns a qsc_asn1_status code.

qsc_x509_private_key_decode_pkcs8_pem_ex_from_bundle()

QSC_EXPORT_API qsc_asn1_status qsc_x509_private_key_decode_pkcs8_pem_ex_from_bundle	(	const char *	pem,
		size_t	pemlen,
		qsc_x509_algorithm_identifier *	algorithm,
		uint8_t *	privatekey,
		size_t	privatekeycapacity,
		size_t *	privatekeylen,
		uint8_t *	publickey,
		size_t	publickeycapacity,
		size_t *	publickeylen,
		bool *	publickeypresent )

Decode a PKCS #8 private key from a PEM bundle into caller-supplied buffers.

Searches a PEM bundle for a PEM encoded PKCS #8 private key and decodes the first matching object into caller-managed algorithm, private-key, and public- key buffers.

Parameters

pem	[const] The PEM bundle text.
pemlen	The length of the PEM bundle in bytes.
algorithm	[struct] The destination algorithm identifier.
privatekey	The destination private key buffer.
privatekeycapacity	The capacity of the private key buffer in bytes.
privatekeylen	The number of bytes written to the private key buffer.
publickey	The destination public key buffer.
publickeycapacity	The capacity of the public key buffer in bytes.
publickeylen	The number of bytes written to the public key buffer.
publickeypresent	Indicates whether a public key was present in the decoded object.

Returns

[enum] Returns a qsc_asn1_status code.

qsc_x509_private_key_decode_pkcs8_pem_from_bundle()

QSC_EXPORT_API qsc_asn1_status qsc_x509_private_key_decode_pkcs8_pem_from_bundle	(	const char *	pem,
		size_t	pemlen,
		qsc_x509_private_key *	key )

Decode a PKCS #8 private key from a PEM bundle.

Searches a PEM bundle for a PEM encoded PKCS #8 private key and decodes the first matching object into the normalized private-key container.

Parameters

pem	[const] The PEM bundle text.
pemlen	The length of the PEM bundle in bytes.
key	[struct] The destination private-key object.

Returns

[enum] Returns a qsc_asn1_status code.

qsc_x509_private_key_decode_sec1_pem_from_bundle()

QSC_EXPORT_API qsc_asn1_status qsc_x509_private_key_decode_sec1_pem_from_bundle	(	const char *	pem,
		size_t	pemlen,
		qsc_x509_private_key *	key )

Decode a SEC 1 private key from a PEM bundle.

Searches a PEM bundle for a PEM encoded SEC 1 private key and decodes the first matching object into the normalized private-key container.

Parameters

pem	[const] The PEM bundle text.
pemlen	The length of the PEM bundle in bytes.
key	[struct] The destination private-key object.

Returns

[enum] Returns a qsc_asn1_status code.

qsc_x509_store_free()

QSC_EXPORT_API void qsc_x509_store_free

(

qsc_x509_store *

store

)

Free the resources associated with a certificate store.

Releases or resets any internal state held by the supplied trust store object after PEM bundle loading or verification use.

Parameters

store

[struct] The certificate store object to free.

Returns

[void] This function does not return a value.

qsc_x509_store_load_pem_bundle()

QSC_EXPORT_API qsc_asn1_status qsc_x509_store_load_pem_bundle	(	const char *	pem,
		size_t	pemlen,
		qsc_x509_trust_anchor *	anchors,
		size_t	anchorcount,
		qsc_x509_store *	store )

Load a PEM trust-anchor bundle into a certificate store.

Parses a concatenated PEM bundle containing one or more trust-anchor certificates and populates the destination store using the provided anchor storage array.

Parameters

pem	[const] The PEM bundle text.
pemlen	The length of the PEM bundle in bytes.
anchors	[struct] The caller-supplied trust-anchor storage array.
anchorcount	The number of trust-anchor elements available in anchors.
store	[struct] The destination certificate store object.

Returns

[enum] Returns a qsc_asn1_status code.