x509key.h File Reference

X.509 private key decoding, size validation, and certificate-key matching interface. More...

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

Go to the source code of this file.

Data Structures
struct	qsc_x509_private_key_t

Macros
#define	QSC_X509_ML_DSA_44_PRIVATEKEY_SIZE   2560U
	The ML-DSA-44 private key size in bytes.
#define	QSC_X509_ML_DSA_65_PRIVATEKEY_SIZE   4032U
	The ML-DSA-65 private key size in bytes.
#define	QSC_X509_ML_DSA_87_PRIVATEKEY_SIZE   4896U
	The ML-DSA-87 private key size in bytes.
#define	QSC_X509_ML_KEM_512_PRIVATEKEY_SIZE   1632U
	The ML-KEM-512 private key size in bytes.
#define	QSC_X509_ML_KEM_768_PRIVATEKEY_SIZE   2400U
	The ML-KEM-768 private key size in bytes.
#define	QSC_X509_ML_KEM_1024_PRIVATEKEY_SIZE   3168U
	The ML-KEM-1024 private key size in bytes.
#define	QSC_X509_PRIVATE_KEY_MAX   QSC_X509_ML_DSA_87_PRIVATEKEY_SIZE
#define	QSC_X509_PRIVATE_KEY_PUBLIC_MAX   QSC_X509_SPKI_MAX
	The maximum supported embedded public key length in bytes.

Typedefs
typedef struct qsc_x509_private_key_t	qsc_x509_private_key

Functions
QSC_EXPORT_API void	qsc_x509_private_key_initialize (qsc_x509_private_key *key)
	Initialize a private-key container.
QSC_EXPORT_API qsc_asn1_status	qsc_x509_private_key_decode_sec1_der (const uint8_t *data, size_t datalen, qsc_x509_private_key *key)
	Decode a SEC 1 DER private key.
QSC_EXPORT_API qsc_asn1_status	qsc_x509_private_key_decode_sec1_pem (const char *pem, size_t pemlen, qsc_x509_private_key *key)
	Decode a SEC 1 PEM private key.
QSC_EXPORT_API qsc_asn1_status	qsc_x509_private_key_decode_pkcs8_der (const uint8_t *data, size_t datalen, qsc_x509_private_key *key)
	Decode a PKCS #8 DER private key.
QSC_EXPORT_API qsc_asn1_status	qsc_x509_private_key_decode_pkcs8_pem (const char *pem, size_t pemlen, qsc_x509_private_key *key)
	Decode a PKCS #8 PEM private key.
QSC_EXPORT_API qsc_asn1_status	qsc_x509_private_key_validate (const qsc_x509_private_key *key)
	Get the expected private key size for an algorithm identifier.
QSC_EXPORT_API size_t	qsc_x509_private_key_expected_private_size (const qsc_x509_algorithm_identifier *algorithm)
QSC_EXPORT_API size_t	qsc_x509_private_key_expected_public_size (const qsc_x509_algorithm_identifier *algorithm)
	Get the expected public key size for an algorithm identifier.
QSC_EXPORT_API qsc_asn1_status	qsc_x509_private_key_decode_pkcs8_der_ex (const uint8_t *data, size_t datalen, 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 DER private key into caller-supplied buffers.
QSC_EXPORT_API qsc_asn1_status	qsc_x509_private_key_decode_pkcs8_pem_ex (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 PEM private key into caller-supplied buffers.
QSC_EXPORT_API bool	qsc_x509_certificate_key_match (const qsc_x509_certificate *certificate, const qsc_x509_private_key *key)
	Test whether a certificate matches a private key object.

Detailed Description

X.509 private key decoding, size validation, and certificate-key matching interface.

This header defines constants and helper functions used to decode private-key objects represented in SEC 1 and PKCS #8 form, including PEM and DER input variants. The interface stores the decoded private key together with its algorithm identifier and an optional embedded public key, allowing the implementation to support both classical and post-quantum key formats.

The public interface also provides algorithm-dependent size expectation helpers for strict validation of private and public key lengths, together with a certificate-to-private-key matching helper used to confirm that a certificate SubjectPublicKeyInfo corresponds to a supplied private key object.

Macro Definition Documentation

QSC_X509_PRIVATE_KEY_PUBLIC_MAX

#define QSC_X509_PRIVATE_KEY_PUBLIC_MAX   QSC_X509_SPKI_MAX

The maximum supported embedded public key length in bytes.

This value is aligned to the maximum SubjectPublicKeyInfo storage capacity used by the X.509 type layer.

Function Documentation

qsc_x509_certificate_key_match()

QSC_EXPORT_API bool qsc_x509_certificate_key_match	(	const qsc_x509_certificate *	certificate,
		const qsc_x509_private_key *	key )

Test whether a certificate matches a private key object.

Compares the subject public key information contained in the certificate with the public key material associated with the supplied private-key object.

Parameters

certificate	[const][struct] The certificate to evaluate.
key	[const][struct] The private-key object to compare.

Returns

Returns true if the certificate corresponds to the supplied private key; otherwise returns false.

qsc_x509_private_key_decode_pkcs8_der()

QSC_EXPORT_API qsc_asn1_status qsc_x509_private_key_decode_pkcs8_der	(	const uint8_t *	data,
		size_t	datalen,
		qsc_x509_private_key *	key )

Decode a PKCS #8 DER private key.

Parses a DER encoded PKCS #8 private key object and populates the destination private-key container.

Parameters

data	[const] The DER encoded input buffer.
datalen	The length of the input buffer in bytes.
key	[struct] The destination private-key container.

Returns

[enum] Returns a qsc_asn1_status code.

qsc_x509_private_key_decode_pkcs8_der_ex()

QSC_EXPORT_API qsc_asn1_status qsc_x509_private_key_decode_pkcs8_der_ex	(	const uint8_t *	data,
		size_t	datalen,
		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 DER private key into caller-supplied buffers.

Parses a DER encoded PKCS #8 private key object and writes the decoded algorithm identifier, private key bytes, optional public key bytes, and presence flag into caller-managed storage. On entry, the caller supplies the output buffer capacities. On return, the length outputs are set to the number of bytes written, or reset to zero when decoding fails before a value is produced.

Parameters

data	[const] The DER encoded input buffer.
datalen	The length of the input buffer 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()

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

Decode a PKCS #8 PEM private key.

Parses a PEM encoded PKCS #8 private key object and populates the destination private-key container.

Parameters

pem	[const] The NULL-terminated PEM text.
pemlen	The length of the PEM text.
key	[struct] The destination private-key container.

Returns

[enum] Returns a qsc_asn1_status code.

qsc_x509_private_key_decode_pkcs8_pem_ex()

QSC_EXPORT_API qsc_asn1_status qsc_x509_private_key_decode_pkcs8_pem_ex	(	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 PEM private key into caller-supplied buffers.

Parses a PEM encoded PKCS #8 private key object and writes the decoded algorithm identifier, private key bytes, optional public key bytes, and presence flag into caller-managed storage. The helper first base64-decodes the PEM object into an internal DER buffer and then applies the same strict PKCS #8 decode rules as the DER interface.

Parameters

pem	[const] The NULL-terminated PEM text.
pemlen	The length of the PEM text.
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_sec1_der()

QSC_EXPORT_API qsc_asn1_status qsc_x509_private_key_decode_sec1_der	(	const uint8_t *	data,
		size_t	datalen,
		qsc_x509_private_key *	key )

Decode a SEC 1 DER private key.

Parses a DER encoded SEC 1 private key object and populates the destination private-key container.

Parameters

data	[const] The DER encoded input buffer.
datalen	The length of the input buffer in bytes.
key	[struct] The destination private-key container.

Returns

[enum] Returns a qsc_asn1_status code.

qsc_x509_private_key_decode_sec1_pem()

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

Decode a SEC 1 PEM private key.

Parses a PEM encoded SEC 1 private key object and populates the destination private-key container.

Parameters

pem	[const] The NULL-terminated PEM text.
pemlen	The length of the pem array.
key	[struct] The destination private-key container.

Returns

[enum] Returns a qsc_asn1_status code.

qsc_x509_private_key_expected_public_size()

QSC_EXPORT_API size_t qsc_x509_private_key_expected_public_size

(

const qsc_x509_algorithm_identifier *

algorithm

)

Get the expected public key size for an algorithm identifier.

Returns the implementation-defined public key length associated with the supplied algorithm identifier. This helper is used for strict parameter-set validation during decode and import operations.

Parameters

algorithm

[const][struct] The algorithm identifier to evaluate.

Returns

Returns the expected public key size in bytes, or zero if the algorithm is unsupported.

qsc_x509_private_key_initialize()

QSC_EXPORT_API void qsc_x509_private_key_initialize

(

qsc_x509_private_key *

key

)

Initialize a private-key container.

Resets the private-key object to a clean default state before decoding or reuse.

Parameters

key	[struct] The private-key container to initialize.

Returns

[void] This function does not return a value.

qsc_x509_private_key_validate()

QSC_EXPORT_API qsc_asn1_status qsc_x509_private_key_validate

(

const qsc_x509_private_key *

key

)

Get the expected private key size for an algorithm identifier.

Returns the implementation-defined private key length associated with the supplied algorithm identifier. This helper is used for strict parameter-set validation during decode and import operations.

Parameters

algorithm

[const][struct] The algorithm identifier to evaluate.

Returns

Returns the expected private key size in bytes, or zero if the algorithm is unsupported.

brief Validate a decoded private-key object.

Performs strict algorithm, parameter-set, and key-size validation on a normalized private-key object. When an embedded public key is present, the helper also validates its size against the decoded algorithm identifier.

Parameters

key	[const][struct] The private-key object to validate.

eturn [enum] Returns a qsc_asn1_status code.