x509ext.h File Reference

X.509 certificate extension decoding, encoding, representation, and query interface. More...

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

Go to the source code of this file.

Functions
QSC_CPLUSPLUS_ENABLED_START QSC_EXPORT_API void	qsc_x509_extension_initialize (qsc_x509_extension *ext)
QSC_EXPORT_API void	qsc_x509_extensions_initialize (qsc_x509_extensions *extensions)
QSC_EXPORT_API qsc_asn1_status	qsc_x509_extension_validate (const qsc_x509_extension *ext)
QSC_EXPORT_API qsc_asn1_status	qsc_x509_extensions_validate (const qsc_x509_extensions *extensions)
QSC_EXPORT_API qsc_asn1_status	qsc_x509_extension_decode (const qsc_encoding_ber_element *element, qsc_x509_extension *ext)
	Decode a single X.509 Extension sequence.
QSC_EXPORT_API qsc_asn1_status	qsc_x509_extensions_decode (const qsc_encoding_ber_element *element, qsc_x509_extensions *extensions)
	Decode an X.509 Extensions sequence.
QSC_EXPORT_API qsc_asn1_status	qsc_x509_ext_basic_constraints_decode (const uint8_t *data, size_t datalen, qsc_x509_basic_constraints *bc)
	Decode a BasicConstraints extension payload.
QSC_EXPORT_API qsc_asn1_status	qsc_x509_ext_key_usage_decode (const uint8_t *data, size_t datalen, uint16_t *usage)
	Decode a KeyUsage extension payload.
QSC_EXPORT_API qsc_asn1_status	qsc_x509_ext_extended_key_usage_decode (const uint8_t *data, size_t datalen, qsc_x509_extended_key_usage *eku)
	Decode an ExtendedKeyUsage extension payload.
QSC_EXPORT_API qsc_asn1_status	qsc_x509_ext_subject_key_identifier_decode (const uint8_t *data, size_t datalen, qsc_x509_subject_key_identifier *ski)
	Decode a SubjectKeyIdentifier extension payload.
QSC_EXPORT_API qsc_asn1_status	qsc_x509_ext_authority_key_identifier_decode (const uint8_t *data, size_t datalen, qsc_x509_authority_key_identifier *aki)
	Decode an AuthorityKeyIdentifier extension payload.
QSC_EXPORT_API qsc_asn1_status	qsc_x509_ext_basic_constraints_encode (const qsc_x509_basic_constraints *bc, uint8_t *output, size_t *outputlen)
	Encode a BasicConstraints extension payload.
QSC_EXPORT_API qsc_asn1_status	qsc_x509_ext_key_usage_encode (const qsc_x509_key_usage *keyusage, uint8_t *output, size_t *outputlen)
	Encode a KeyUsage extension payload.
QSC_EXPORT_API qsc_asn1_status	qsc_x509_ext_extended_key_usage_encode (const qsc_x509_extended_key_usage *eku, uint8_t *output, size_t *outputlen)
	Encode an ExtendedKeyUsage extension payload.
QSC_EXPORT_API bool	qsc_x509_ext_has_eku (const qsc_x509_extended_key_usage *eku, uint32_t bitmask)
	Test whether an Extended Key Usage set contains a requested usage bit.
QSC_EXPORT_API qsc_asn1_status	qsc_x509_ext_subject_key_identifier_encode (const qsc_x509_subject_key_identifier *ski, uint8_t *output, size_t *outputlen)
	Encode a SubjectKeyIdentifier extension payload.
QSC_EXPORT_API qsc_asn1_status	qsc_x509_ext_authority_key_identifier_encode (const qsc_x509_authority_key_identifier *aki, uint8_t *output, size_t *outputlen)
	Encode an AuthorityKeyIdentifier extension payload.
QSC_EXPORT_API qsc_asn1_status	qsc_x509_ext_subject_alt_name_decode (const uint8_t *data, size_t datalen, qsc_x509_subject_alt_name *san)
	Decode a SubjectAltName extension payload.
QSC_EXPORT_API qsc_asn1_status	qsc_x509_ext_subject_alt_name_encode (const qsc_x509_subject_alt_name *san, uint8_t *output, size_t *outputlen)
	Encode a SubjectAltName extension payload.
QSC_EXPORT_API qsc_asn1_status	qsc_x509_ext_issuer_alt_name_decode (const uint8_t *data, size_t datalen, qsc_x509_issuer_alt_name *ian)
	Decode an IssuerAltName extension payload.
QSC_EXPORT_API qsc_asn1_status	qsc_x509_ext_issuer_alt_name_encode (const qsc_x509_issuer_alt_name *ian, uint8_t *output, size_t *outputlen)
	Encode an IssuerAltName extension payload.
QSC_EXPORT_API qsc_asn1_status	qsc_x509_ext_subject_alt_name_add_dns (qsc_x509_subject_alt_name *san, const char *dnsname, size_t dnsnamelen)
	Add a DNS name entry to a Subject Alternative Name object.
QSC_EXPORT_API qsc_asn1_status	qsc_x509_ext_subject_alt_name_add_ip (qsc_x509_subject_alt_name *san, const uint8_t *address, size_t addresslen)
	Add an IP address entry to a Subject Alternative Name object.

Detailed Description

X.509 certificate extension decoding, encoding, representation, and query interface.

This header defines the public interface used to decode, encode, represent, and query X.509 certificate extensions. Extensions are carried in the TBSCertificate extensions field as DER encoded Extension sequences identified by object identifiers. The interface normalizes outer Extension objects into qsc_x509_extension and qsc_x509_extensions containers and provides typed decoders and encoders for commonly used extension payloads.

Supported typed extension payloads include Basic Constraints, Key Usage, Extended Key Usage, Subject Key Identifier, Authority Key Identifier, Subject Alternative Name, and Issuer Alternative Name. Unknown or otherwise unsupported extensions may still be preserved in normalized form through the generic extension containers defined in the X.509 type layer.

The decoder interface expects extension payload decoding functions to receive the contents of the extnValue OCTET STRING, not the full outer Extension sequence. The encoder interface produces DER payloads suitable for placement inside an Extension extnValue OCTET STRING by the surrounding certificate or CSR writer.

Function Documentation

qsc_x509_ext_authority_key_identifier_decode()

QSC_EXPORT_API qsc_asn1_status qsc_x509_ext_authority_key_identifier_decode	(	const uint8_t *	data,
		size_t	datalen,
		qsc_x509_authority_key_identifier *	aki )

Decode an AuthorityKeyIdentifier extension payload.

Parses the DER encoded extnValue contents of an AuthorityKeyIdentifier extension and extracts the supported authority key identifier fields.

The ASN.1 definition is:

AuthorityKeyIdentifier ::= SEQUENCE { keyIdentifier [0] KeyIdentifier OPTIONAL, authorityCertIssuer [1] GeneralNames OPTIONAL, authorityCertSerialNumber [2] CertificateSerialNumber OPTIONAL }

Parameters

data	[const] The DER encoded Authority Key Identifier payload.
datalen	The length of the encoded payload in bytes.
aki	[struct] The destination Authority Key Identifier object.

Returns

[enum] Returns a qsc_asn1_status code.

qsc_x509_ext_authority_key_identifier_encode()

QSC_EXPORT_API qsc_asn1_status qsc_x509_ext_authority_key_identifier_encode	(	const qsc_x509_authority_key_identifier *	aki,
		uint8_t *	output,
		size_t *	outputlen )

Encode an AuthorityKeyIdentifier extension payload.

Serializes a qsc_x509_authority_key_identifier object into the DER representation of an AuthorityKeyIdentifier extension payload.

Parameters

aki	[const][struct] The source Authority Key Identifier object.
output	The destination buffer receiving the DER payload.
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_ext_basic_constraints_decode()

QSC_EXPORT_API qsc_asn1_status qsc_x509_ext_basic_constraints_decode	(	const uint8_t *	data,
		size_t	datalen,
		qsc_x509_basic_constraints *	bc )

Decode a BasicConstraints extension payload.

Parses the DER encoded extnValue contents of a BasicConstraints extension and writes the result to the supplied qsc_x509_basic_constraints structure.

The ASN.1 definition is:

BasicConstraints ::= SEQUENCE { cA BOOLEAN DEFAULT FALSE, pathLenConstraint INTEGER OPTIONAL }

The cA field indicates whether the subject may act as a certification authority. The optional pathLenConstraint limits the number of non-self-issued CA certificates that may follow this certificate in a certification path.

Parameters

data	[const] The DER encoded BasicConstraints payload.
datalen	The length of the encoded payload in bytes.
bc	[struct] The destination Basic Constraints object.

Returns

[enum] Returns a qsc_asn1_status code.

qsc_x509_ext_basic_constraints_encode()

QSC_EXPORT_API qsc_asn1_status qsc_x509_ext_basic_constraints_encode	(	const qsc_x509_basic_constraints *	bc,
		uint8_t *	output,
		size_t *	outputlen )

Encode a BasicConstraints extension payload.

Serializes a qsc_x509_basic_constraints object into the DER representation of a BasicConstraints extension payload suitable for placement inside extnValue.

Parameters

bc	[const][struct] The source Basic Constraints object.
output	The destination buffer receiving the DER payload.
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_ext_extended_key_usage_decode()

QSC_EXPORT_API qsc_asn1_status qsc_x509_ext_extended_key_usage_decode	(	const uint8_t *	data,
		size_t	datalen,
		qsc_x509_extended_key_usage *	eku )

Decode an ExtendedKeyUsage extension payload.

Parses the DER encoded extnValue contents of an ExtendedKeyUsage extension and records the contained key purpose identifiers.

The ASN.1 definition is:

ExtKeyUsageSyntax ::= SEQUENCE SIZE (1..MAX) OF KeyPurposeId

KeyPurposeId ::= OBJECT IDENTIFIER

Parameters

data	[const] The DER encoded Extended Key Usage payload.
datalen	The length of the encoded payload in bytes.
eku	[struct] The destination Extended Key Usage object.

Returns

[enum] Returns a qsc_asn1_status code.

qsc_x509_ext_extended_key_usage_encode()

QSC_EXPORT_API qsc_asn1_status qsc_x509_ext_extended_key_usage_encode	(	const qsc_x509_extended_key_usage *	eku,
		uint8_t *	output,
		size_t *	outputlen )

Encode an ExtendedKeyUsage extension payload.

Serializes a qsc_x509_extended_key_usage object into the DER representation of an ExtendedKeyUsage extension payload.

Parameters

eku	[const][struct] The source Extended Key Usage object.
output	The destination buffer receiving the DER payload.
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_ext_has_eku()

QSC_EXPORT_API bool qsc_x509_ext_has_eku	(	const qsc_x509_extended_key_usage *	eku,
		uint32_t	bitmask )

Test whether an Extended Key Usage set contains a requested usage bit.

Evaluates the supplied implementation-defined bit mask against the decoded or constructed Extended Key Usage object and reports whether the requested usage is present.

Parameters

eku	[const][struct] The Extended Key Usage object to inspect.
bitmask	The implementation-defined usage bit mask to test.

Returns

Returns true if the requested usage is present; otherwise returns false.

qsc_x509_ext_issuer_alt_name_decode()

QSC_EXPORT_API qsc_asn1_status qsc_x509_ext_issuer_alt_name_decode	(	const uint8_t *	data,
		size_t	datalen,
		qsc_x509_issuer_alt_name *	ian )

Decode an IssuerAltName extension payload.

Parses the DER encoded extnValue contents of an Issuer Alternative Name extension and records the supported GeneralName entries.

Parameters

data	[const] The DER encoded Issuer Alternative Name payload.
datalen	The length of the encoded payload in bytes.
ian	[struct] The destination Issuer Alternative Name object.

Returns

[enum] Returns a qsc_asn1_status code.

qsc_x509_ext_issuer_alt_name_encode()

QSC_EXPORT_API qsc_asn1_status qsc_x509_ext_issuer_alt_name_encode	(	const qsc_x509_issuer_alt_name *	ian,
		uint8_t *	output,
		size_t *	outputlen )

Encode an IssuerAltName extension payload.

Serializes a qsc_x509_issuer_alt_name object into the DER representation of an Issuer Alternative Name extension payload.

Parameters

ian	[const][struct] The source Issuer Alternative Name object.
output	The destination buffer receiving the DER payload.
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_ext_key_usage_decode()

QSC_EXPORT_API qsc_asn1_status qsc_x509_ext_key_usage_decode	(	const uint8_t *	data,
		size_t	datalen,
		uint16_t *	usage )

Decode a KeyUsage extension payload.

Parses the DER encoded extnValue contents of a KeyUsage extension and converts the BIT STRING representation into the implementation-defined usage mask stored in the caller supplied output variable.

The ASN.1 definition is:

KeyUsage ::= BIT STRING

Parameters

data	[const] The DER encoded KeyUsage payload.
datalen	The length of the encoded payload in bytes.
usage	The destination usage bit mask.

Returns

[enum] Returns a qsc_asn1_status code.

qsc_x509_ext_key_usage_encode()

QSC_EXPORT_API qsc_asn1_status qsc_x509_ext_key_usage_encode	(	const qsc_x509_key_usage *	keyusage,
		uint8_t *	output,
		size_t *	outputlen )

Encode a KeyUsage extension payload.

Serializes a qsc_x509_key_usage object into the DER representation of a KeyUsage extension payload.

Parameters

keyusage	[const][struct] The source Key Usage object.
output	The destination buffer receiving the DER payload.
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_ext_subject_alt_name_add_dns()

QSC_EXPORT_API qsc_asn1_status qsc_x509_ext_subject_alt_name_add_dns	(	qsc_x509_subject_alt_name *	san,
		const char *	dnsname,
		size_t	dnsnamelen )

Add a DNS name entry to a Subject Alternative Name object.

Appends a dNSName GeneralName entry to the supplied Subject Alternative Name container.

Parameters

san	[struct] The Subject Alternative Name object to update.
dnsname	[const] The DNS host name string.
dnsnamelen	The length of the DNS host name string in bytes.

Returns

[enum] Returns a qsc_asn1_status code.

qsc_x509_ext_subject_alt_name_add_ip()

QSC_EXPORT_API qsc_asn1_status qsc_x509_ext_subject_alt_name_add_ip	(	qsc_x509_subject_alt_name *	san,
		const uint8_t *	address,
		size_t	addresslen )

Add an IP address entry to a Subject Alternative Name object.

Appends an iPAddress GeneralName entry to the supplied Subject Alternative Name container.

Parameters

san	[struct] The Subject Alternative Name 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_ext_subject_alt_name_decode()

QSC_EXPORT_API qsc_asn1_status qsc_x509_ext_subject_alt_name_decode	(	const uint8_t *	data,
		size_t	datalen,
		qsc_x509_subject_alt_name *	san )

Decode a SubjectAltName extension payload.

Parses the DER encoded extnValue contents of a Subject Alternative Name extension and records the supported GeneralName entries.

Parameters

data	[const] The DER encoded Subject Alternative Name payload.
datalen	The length of the encoded payload in bytes.
san	[struct] The destination Subject Alternative Name object.

Returns

[enum] Returns a qsc_asn1_status code.

qsc_x509_ext_subject_alt_name_encode()

QSC_EXPORT_API qsc_asn1_status qsc_x509_ext_subject_alt_name_encode	(	const qsc_x509_subject_alt_name *	san,
		uint8_t *	output,
		size_t *	outputlen )

Encode a SubjectAltName extension payload.

Serializes a qsc_x509_subject_alt_name object into the DER representation of a Subject Alternative Name extension payload.

Parameters

san	[const][struct] The source Subject Alternative Name object.
output	The destination buffer receiving the DER payload.
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_ext_subject_key_identifier_decode()

QSC_EXPORT_API qsc_asn1_status qsc_x509_ext_subject_key_identifier_decode	(	const uint8_t *	data,
		size_t	datalen,
		qsc_x509_subject_key_identifier *	ski )

Decode a SubjectKeyIdentifier extension payload.

Parses the DER encoded extnValue contents of a SubjectKeyIdentifier extension and copies the identifier bytes to the supplied output structure.

The ASN.1 definition is:

SubjectKeyIdentifier ::= OCTET STRING

Parameters

data	[const] The DER encoded Subject Key Identifier payload.
datalen	The length of the encoded payload in bytes.
ski	[struct] The destination Subject Key Identifier object.

Returns

[enum] Returns a qsc_asn1_status code.

qsc_x509_ext_subject_key_identifier_encode()

QSC_EXPORT_API qsc_asn1_status qsc_x509_ext_subject_key_identifier_encode	(	const qsc_x509_subject_key_identifier *	ski,
		uint8_t *	output,
		size_t *	outputlen )

Encode a SubjectKeyIdentifier extension payload.

Serializes a qsc_x509_subject_key_identifier object into the DER representation of a SubjectKeyIdentifier extension payload.

Parameters

ski	[const][struct] The source Subject Key Identifier object.
output	The destination buffer receiving the DER payload.
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_extension_decode()

QSC_EXPORT_API qsc_asn1_status qsc_x509_extension_decode	(	const qsc_encoding_ber_element *	element,
		qsc_x509_extension *	ext )

Decode a single X.509 Extension sequence.

Parses an ASN.1 DER encoded Extension object and converts it to the normalized qsc_x509_extension representation. The decoded extension includes the extension object identifier, the optional critical flag, and the raw extnValue OCTET STRING contents.

The ASN.1 definition is:

Extension ::= SEQUENCE { extnID OBJECT IDENTIFIER, critical BOOLEAN DEFAULT FALSE, extnValue OCTET STRING }

This function does not interpret the inner extnValue payload beyond extracting it from the outer OCTET STRING wrapper. Typed interpretation is performed by the extension-specific decode routines declared below.

Parameters

element	[const][struct] The ASN.1 sequence element containing the encoded Extension structure.
ext	[struct] The destination normalized extension object.

Returns

[enum] Returns a qsc_asn1_status code.

qsc_x509_extension_initialize()

QSC_CPLUSPLUS_ENABLED_START QSC_EXPORT_API void qsc_x509_extension_initialize

(

qsc_x509_extension *

ext

)

brief Initialize a normalized extension entry.

Parameters

ext	[struct] The extension object to initialize.

qsc_x509_extension_validate()

QSC_EXPORT_API qsc_asn1_status qsc_x509_extension_validate

(

const qsc_x509_extension *

ext

)

brief Validate a normalized extension entry.

Performs structural and payload-adjacent validation on a decoded extension entry. This routine does not replace object-level certificate, CSR, or CRL policy validation, but it rejects malformed critical fields, missing extnValue content, and inconsistent normalized state.

Parameters

ext	[const][struct] The decoded extension entry.

eturn [enum] Returns a qsc_asn1_status code.

qsc_x509_extensions_decode()

QSC_EXPORT_API qsc_asn1_status qsc_x509_extensions_decode	(	const qsc_encoding_ber_element *	element,
		qsc_x509_extensions *	extensions )

Decode an X.509 Extensions sequence.

Parses an ASN.1 Extensions container and decodes each contained Extension entry into the normalized qsc_x509_extensions output structure.

The ASN.1 definition is:

Extensions ::= SEQUENCE OF Extension

Each entry is first normalized by qsc_x509_extension_decode. Typed payload interpretation, when required, is then performed separately by the extension-specific decode functions.

Parameters

element	[const][struct] The ASN.1 sequence element containing the Extensions collection.
extensions	[struct] The destination normalized extension set.

Returns

[enum] Returns a qsc_asn1_status code.

qsc_x509_extensions_initialize()

QSC_EXPORT_API void qsc_x509_extensions_initialize

(

qsc_x509_extensions *

extensions

)

brief Initialize a normalized extension set.

Parameters

extensions

[struct] The extension set object to initialize.

qsc_x509_extensions_validate()

QSC_EXPORT_API qsc_asn1_status qsc_x509_extensions_validate

(

const qsc_x509_extensions *

extensions

)

brief Validate a normalized extension set.

Performs set-level structural checks such as duplicate extension rejection and consistency checks across already-decoded typed extension state.

Parameters

extensions

[const][struct] The decoded extension set.

eturn [enum] Returns a qsc_asn1_status code.