x509spki.h File Reference

X.509 AlgorithmIdentifier and SubjectPublicKeyInfo decoding, initialization, and validation interface. More...

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

Go to the source code of this file.

Functions
QSC_EXPORT_API qsc_asn1_status	qsc_x509_algorithm_identifier_decode (const qsc_encoding_ber_element *element, qsc_x509_algorithm_identifier *algorithm)
	Decode an AlgorithmIdentifier object.
QSC_EXPORT_API qsc_asn1_status	qsc_x509_algorithm_identifier_validate (const qsc_x509_algorithm_identifier *algorithm)
QSC_EXPORT_API qsc_asn1_status	qsc_x509_subject_public_key_info_decode (const qsc_encoding_ber_element *element, qsc_x509_subject_public_key_info *spki)
	Decode a SubjectPublicKeyInfo object.
QSC_EXPORT_API qsc_asn1_status	qsc_x509_spki_validate (const qsc_x509_subject_public_key_info *spki)
	Validate a normalized SubjectPublicKeyInfo object.
QSC_EXPORT_API bool	qsc_x509_spki_is_uncompressed_ec_point (const qsc_x509_subject_public_key_info *spki)
	Test whether an SPKI contains an uncompressed EC point.
QSC_EXPORT_API size_t	qsc_x509_named_curve_coordinate_size (qsc_x509_named_curve curve)
	Get the coordinate size for a named elliptic curve.
QSC_EXPORT_API size_t	qsc_x509_named_curve_public_key_size (qsc_x509_named_curve curve)
	Get the encoded public-key size for a named elliptic curve.
QSC_EXPORT_API qsc_asn1_status	qsc_x509_spki_get_ec_coordinates (const qsc_x509_subject_public_key_info *spki, uint8_t *x, size_t xlen, uint8_t *y, size_t ylen)
	Extract affine EC coordinates from an SPKI object.
QSC_EXPORT_API void	qsc_x509_algorithm_identifier_initialize (qsc_x509_algorithm_identifier *algorithm)
	Initialize an AlgorithmIdentifier object.
QSC_EXPORT_API void	qsc_x509_subject_public_key_info_initialize (qsc_x509_subject_public_key_info *spki)
	Initialize a SubjectPublicKeyInfo object.
QSC_EXPORT_API size_t	qsc_x509_pqc_public_key_size (qsc_x509_pqc_parameter_set parameterset)
	Get the expected public-key size for a PQC parameter set.
QSC_EXPORT_API bool	qsc_x509_algorithm_identifier_is_mldsa (const qsc_x509_algorithm_identifier *algorithm)
	Test whether an AlgorithmIdentifier denotes ML-DSA.
QSC_EXPORT_API bool	qsc_x509_algorithm_identifier_is_mlkem (const qsc_x509_algorithm_identifier *algorithm)
	Test whether an AlgorithmIdentifier denotes ML-KEM.
QSC_EXPORT_API qsc_asn1_status	qsc_x509_algorithm_identifier_initialize_mldsa (qsc_x509_algorithm_identifier *algorithm, qsc_x509_pqc_parameter_set parameterset)
	Initialize an AlgorithmIdentifier for ML-DSA.
QSC_EXPORT_API qsc_asn1_status	qsc_x509_algorithm_identifier_initialize_mlkem (qsc_x509_algorithm_identifier *algorithm, qsc_x509_pqc_parameter_set parameterset)
	Initialize an AlgorithmIdentifier for ML-KEM.
QSC_EXPORT_API qsc_asn1_status	qsc_x509_spki_initialize_ec (qsc_x509_subject_public_key_info *spki, qsc_x509_named_curve curve, const uint8_t *publickey, size_t publickeylen)
	Initialize an SPKI object for an elliptic-curve public key.
QSC_EXPORT_API qsc_asn1_status	qsc_x509_spki_initialize_ml_dsa (qsc_x509_subject_public_key_info *spki, qsc_x509_pqc_parameter_set parameterset, const uint8_t *publickey, size_t publickeylen)
	Initialize an SPKI object for an ML-DSA public key.
QSC_EXPORT_API qsc_asn1_status	qsc_x509_spki_initialize_ml_kem (qsc_x509_subject_public_key_info *spki, qsc_x509_pqc_parameter_set parameterset, const uint8_t *publickey, size_t publickeylen)
	Initialize an SPKI object for an ML-KEM public key.

Detailed Description

X.509 AlgorithmIdentifier and SubjectPublicKeyInfo decoding, initialization, and validation interface.

This header defines helper functions used to decode, initialize, validate, and query X.509 AlgorithmIdentifier and SubjectPublicKeyInfo objects. The interface supports classical elliptic-curve public keys together with post-quantum ML-DSA and ML-KEM parameter sets carried through OID-driven algorithm identifiers and raw public-key payloads.

The decoding functions operate on ASN.1 BER/DER elements and populate the normalized X.509 type-layer structures. The initialization functions provide canonical construction helpers for EC, ML-DSA, and ML-KEM SPKI objects. Additional query helpers expose named-curve coordinate sizing, public-key sizing, algorithm classification, and coordinate extraction for uncompressed EC points.

Function Documentation

qsc_x509_algorithm_identifier_decode()

QSC_EXPORT_API qsc_asn1_status qsc_x509_algorithm_identifier_decode	(	const qsc_encoding_ber_element *	element,
		qsc_x509_algorithm_identifier *	algorithm )

Decode an AlgorithmIdentifier object.

Parses an ASN.1 DER encoded AlgorithmIdentifier sequence and populates the normalized qsc_x509_algorithm_identifier structure.

Parameters

element	[const][struct] The ASN.1 element containing the AlgorithmIdentifier sequence.
algorithm	[struct] The destination algorithm identifier object.

Returns

[enum] Returns a qsc_asn1_status code.

qsc_x509_algorithm_identifier_initialize()

QSC_EXPORT_API void qsc_x509_algorithm_identifier_initialize

(

qsc_x509_algorithm_identifier *

algorithm

)

Initialize an AlgorithmIdentifier object.

Resets the supplied algorithm identifier object to a clean default state.

Parameters

algorithm

[struct] The algorithm identifier object to initialize.

Returns

[void] This function does not return a value.

qsc_x509_algorithm_identifier_initialize_mldsa()

QSC_EXPORT_API qsc_asn1_status qsc_x509_algorithm_identifier_initialize_mldsa	(	qsc_x509_algorithm_identifier *	algorithm,
		qsc_x509_pqc_parameter_set	parameterset )

Initialize an AlgorithmIdentifier for ML-DSA.

Populates the supplied algorithm identifier object with the OID and parameter-set metadata corresponding to the selected ML-DSA parameter set.

Parameters

algorithm	[struct] The algorithm identifier object to initialize.
parameterset	[enum] The ML-DSA parameter-set identifier.

Returns

[enum] Returns a qsc_asn1_status code.

qsc_x509_algorithm_identifier_initialize_mlkem()

QSC_EXPORT_API qsc_asn1_status qsc_x509_algorithm_identifier_initialize_mlkem	(	qsc_x509_algorithm_identifier *	algorithm,
		qsc_x509_pqc_parameter_set	parameterset )

Initialize an AlgorithmIdentifier for ML-KEM.

Populates the supplied algorithm identifier object with the OID and parameter-set metadata corresponding to the selected ML-KEM parameter set.

Parameters

algorithm	[struct] The algorithm identifier object to initialize.
parameterset	[enum] The ML-KEM parameter-set identifier.

Returns

[enum] Returns a qsc_asn1_status code.

qsc_x509_algorithm_identifier_is_mldsa()

QSC_EXPORT_API bool qsc_x509_algorithm_identifier_is_mldsa

(

const qsc_x509_algorithm_identifier *

algorithm

)

Test whether an AlgorithmIdentifier denotes ML-DSA.

Examines the object identifier and parameter-set metadata in the supplied algorithm identifier and reports whether it represents an ML-DSA algorithm.

Parameters

algorithm

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

Returns

Returns true if the algorithm identifier represents ML-DSA; otherwise returns false.

qsc_x509_algorithm_identifier_is_mlkem()

QSC_EXPORT_API bool qsc_x509_algorithm_identifier_is_mlkem

(

const qsc_x509_algorithm_identifier *

algorithm

)

Test whether an AlgorithmIdentifier denotes ML-KEM.

Examines the object identifier and parameter-set metadata in the supplied algorithm identifier and reports whether it represents an ML-KEM algorithm.

Parameters

algorithm

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

Returns

Returns true if the algorithm identifier represents ML-KEM; otherwise returns false.

qsc_x509_algorithm_identifier_validate()

QSC_EXPORT_API qsc_asn1_status qsc_x509_algorithm_identifier_validate

(

const qsc_x509_algorithm_identifier *

algorithm

)

brief Validate a normalized AlgorithmIdentifier object.

Performs strict OID-driven validation of an AlgorithmIdentifier, including parameter presence or absence rules, named-curve consistency, and ML-DSA or ML-KEM parameter-set consistency. This helper is intended for callers that need to validate decoded algorithm metadata independently of a full SPKI decode.

Parameters

algorithm

[const][struct] The algorithm identifier object to validate.

Returns

[enum] Returns a qsc_asn1_status code.

qsc_x509_named_curve_coordinate_size()

QSC_EXPORT_API size_t qsc_x509_named_curve_coordinate_size

(

qsc_x509_named_curve

curve

)

Get the coordinate size for a named elliptic curve.

Returns the coordinate width in bytes for the supplied named curve. This helper is used when validating or extracting affine coordinates from EC public keys.

Parameters

curve

[enum] The named elliptic curve identifier.

Returns

Returns the coordinate size in bytes, or zero if the curve is unsupported.

qsc_x509_named_curve_public_key_size()

QSC_EXPORT_API size_t qsc_x509_named_curve_public_key_size

(

qsc_x509_named_curve

curve

)

Get the encoded public-key size for a named elliptic curve.

Returns the expected byte length of an uncompressed EC public key for the supplied named curve.

Parameters

curve

[enum] The named elliptic curve identifier.

Returns

Returns the encoded public-key size in bytes, or zero if the curve is unsupported.

qsc_x509_pqc_public_key_size()

QSC_EXPORT_API size_t qsc_x509_pqc_public_key_size

(

qsc_x509_pqc_parameter_set

parameterset

)

Get the expected public-key size for a PQC parameter set.

Returns the implementation-defined public-key size associated with the supplied ML-DSA or ML-KEM parameter set.

Parameters

parameterset

[enum] The post-quantum parameter-set identifier.

Returns

Returns the expected public-key size in bytes, or zero if the parameter set is unsupported.

qsc_x509_spki_get_ec_coordinates()

QSC_EXPORT_API qsc_asn1_status qsc_x509_spki_get_ec_coordinates	(	const qsc_x509_subject_public_key_info *	spki,
		uint8_t *	x,
		size_t	xlen,
		uint8_t *	y,
		size_t	ylen )

Extract affine EC coordinates from an SPKI object.

Reads the uncompressed elliptic-curve public-key payload from the supplied SPKI object and writes the affine x and y coordinates to the caller-supplied output buffers.

Parameters

spki	[const][struct] The subject public key information object containing the EC public key.
x	The destination buffer receiving the x-coordinate bytes.
xlen	The capacity of the x-coordinate buffer in bytes.
y	The destination buffer receiving the y-coordinate bytes.
ylen	The capacity of the y-coordinate buffer in bytes.

Returns

[enum] Returns a qsc_asn1_status code.

qsc_x509_spki_initialize_ec()

QSC_EXPORT_API qsc_asn1_status qsc_x509_spki_initialize_ec	(	qsc_x509_subject_public_key_info *	spki,
		qsc_x509_named_curve	curve,
		const uint8_t *	publickey,
		size_t	publickeylen )

Initialize an SPKI object for an elliptic-curve public key.

Populates the supplied SubjectPublicKeyInfo object using the selected named curve and the supplied EC public-key bytes.

Parameters

spki	[struct] The destination subject public key information object.
curve	[enum] The named elliptic curve identifier.
publickey	[const] The raw encoded EC public-key bytes.
publickeylen	The length of the public key in bytes.

Returns

[enum] Returns a qsc_asn1_status code.

qsc_x509_spki_initialize_ml_dsa()

QSC_EXPORT_API qsc_asn1_status qsc_x509_spki_initialize_ml_dsa	(	qsc_x509_subject_public_key_info *	spki,
		qsc_x509_pqc_parameter_set	parameterset,
		const uint8_t *	publickey,
		size_t	publickeylen )

Initialize an SPKI object for an ML-DSA public key.

Populates the supplied SubjectPublicKeyInfo object using the selected ML-DSA parameter set and the supplied public-key bytes. This helper accepts only the ML-DSA parameter set supported by the current build.

Parameters

spki	[struct] The destination subject public key information object.
parameterset	[enum] The ML-DSA parameter-set identifier.
publickey	[const] The raw ML-DSA public-key bytes.
publickeylen	The length of the public key in bytes.

Returns

[enum] Returns a qsc_asn1_status code.

qsc_x509_spki_initialize_ml_kem()

QSC_EXPORT_API qsc_asn1_status qsc_x509_spki_initialize_ml_kem	(	qsc_x509_subject_public_key_info *	spki,
		qsc_x509_pqc_parameter_set	parameterset,
		const uint8_t *	publickey,
		size_t	publickeylen )

Initialize an SPKI object for an ML-KEM public key.

Populates the supplied SubjectPublicKeyInfo object using the selected ML-KEM parameter set and the supplied public-key bytes. This helper accepts only the ML-KEM parameter set supported by the current build.

Parameters

spki	[struct] The destination subject public key information object.
parameterset	[enum] The ML-KEM parameter-set identifier.
publickey	[const] The raw ML-KEM public-key bytes.
publickeylen	The length of the public key in bytes.

Returns

[enum] Returns a qsc_asn1_status code.

qsc_x509_spki_is_uncompressed_ec_point()

QSC_EXPORT_API bool qsc_x509_spki_is_uncompressed_ec_point

(

const qsc_x509_subject_public_key_info *

spki

)

Test whether an SPKI contains an uncompressed EC point.

Evaluates the subject public key payload and associated algorithm metadata to determine whether the encoded elliptic-curve public key uses the standard uncompressed point format.

Parameters

spki	[const][struct] The subject public key information object to inspect.

Returns

Returns true if the SPKI contains an uncompressed EC point; otherwise returns false.

qsc_x509_spki_validate()

QSC_EXPORT_API qsc_asn1_status qsc_x509_spki_validate

(

const qsc_x509_subject_public_key_info *

spki

)

Validate a normalized SubjectPublicKeyInfo object.

Performs structural and algorithm-specific validation of the supplied SPKI object, including parameter-set and public-key size consistency checks where applicable.

Parameters

spki	[const][struct] The subject public key information object to validate.

Returns

[enum] Returns a qsc_asn1_status code.

qsc_x509_subject_public_key_info_decode()

QSC_EXPORT_API qsc_asn1_status qsc_x509_subject_public_key_info_decode	(	const qsc_encoding_ber_element *	element,
		qsc_x509_subject_public_key_info *	spki )

Decode a SubjectPublicKeyInfo object.

Parses an ASN.1 DER encoded SubjectPublicKeyInfo sequence and populates the normalized qsc_x509_subject_public_key_info structure with the decoded algorithm identifier and subject public key bytes.

Parameters

element	[const][struct] The ASN.1 element containing the SubjectPublicKeyInfo sequence.
spki	[struct] The destination subject public key information object.

Returns

[enum] Returns a qsc_asn1_status code.

qsc_x509_subject_public_key_info_initialize()

QSC_EXPORT_API void qsc_x509_subject_public_key_info_initialize

(

qsc_x509_subject_public_key_info *

spki

)

Initialize a SubjectPublicKeyInfo object.

Resets the supplied subject public key information object to a clean default state.

Parameters

spki	[struct] The subject public key information object to initialize.

Returns

[void] This function does not return a value.