X.509 Certificate Parsing Handling

Macros
#define	LC_X509_KEYS_SPHINCS_ON_STACK(name)
	Allocate memory for struct lc_x509_keys_data holding Sphincs Plus keys on stack.
#define	LC_X509_KEYS_DILITHIUM_ON_STACK(name)
	Allocate memory for struct lc_x509_keys_data holding Dilithium keys on stack.
#define	LC_X509_KEYS_DILITHIUM_ED25519_ON_STACK(name)
	Allocate memory for struct lc_x509_keys_data holding Dilithium-ED25519 keys on stack.
#define	LC_X509_KEYS_DILITHIUM_ED448_ON_STACK(name)
	Allocate memory for struct lc_x509_keys_data holding Dilithium-ED448 keys on stack.
#define	LC_X509_KEYS_ON_STACK(name)
	Allocate memory for struct lc_x509_keys_data holding any kind of key type on stack.

Functions
void	lc_x509_cert_clear (struct lc_x509_certificate *cert)
	Clear the resources used by the X.509 certificate parsing state.
int	lc_x509_cert_decode (struct lc_x509_certificate *cert, const uint8_t *data, size_t datalen)
	Decode an X.509 certificate.
int	lc_x509_keys_dilithium_ed25519_alloc (struct lc_x509_key_data **keys)
	Allocate memory for struct lc_x509_keys_data holding Dilithium-ED25519 keys on heap.
int	lc_x509_keys_dilithium_ed448_alloc (struct lc_x509_key_data **keys)
	Allocate memory for struct lc_x509_keys_data holding Dilithium-ED448 keys on heap.
int	lc_x509_keys_dilithium_alloc (struct lc_x509_key_data **keys)
	Allocate memory for struct lc_x509_keys_data holding Dilithium keys on heap.
int	lc_x509_keys_sphincs_alloc (struct lc_x509_key_data **keys)
	Allocate memory for struct lc_x509_keys_data holding Sphincs Plus keys on heap.
int	lc_x509_keys_alloc (struct lc_x509_key_data **keys)
	Allocate memory for struct lc_x509_keys_data holding holding any kind of key type on heap.
void	lc_x509_keys_zero_free (struct lc_x509_key_data *keys)
	Zeroize and free keys buffer.
int	lc_x509_sk_decode (struct lc_x509_key_data *key, enum lc_sig_types key_type, const uint8_t *data, size_t datalen)
	Decode a private key in DER format.
int	lc_x509_pk_decode (struct lc_x509_key_data *key, enum lc_sig_types key_type, const uint8_t *data, size_t datalen)
	Decode a public key in raw format.
int	lc_x509_signature_verify (const uint8_t *sig_data, size_t siglen, const struct lc_x509_certificate *cert, const uint8_t *m, size_t mlen, const struct lc_hash *prehash_algo)
	Verify signature over user-supplied data.
int	lc_x509_cert_load_pk_dilithium_ed25519 (struct lc_dilithium_ed25519_pk *dilithium_ed25519_pk, const uint8_t *pk_ptr, size_t pk_len)
	Parse a Composite ML-DSA ASN.1 structure into a public key structure.
int	lc_x509_cert_load_pk_dilithium_ed448 (struct lc_dilithium_ed448_pk *dilithium_ed448_pk, const uint8_t *pk_ptr, size_t pk_len)
	Parse a Composite ML-DSA ASN.1 structure into a public key structure.
int	lc_x509_cert_get_pubkey (const struct lc_x509_certificate *cert, const uint8_t **pk, size_t *pk_size, enum lc_sig_types *key_type)
	Get a reference of the public key data.
int	lc_x509_cert_get_eku (const struct lc_x509_certificate *cert, const char ***eku_names, unsigned int *num_eku)
	Get the extended key usage in human readable form.
int	lc_x509_cert_get_eku_val (const struct lc_x509_certificate *cert, uint16_t *val)
	Get the extended key usage in integer form.
int	lc_x509_cert_get_keyusage (const struct lc_x509_certificate *cert, const char ***keyusage_names, unsigned int *num_keyusage)
	Get the key usage in human readable form.
int	lc_x509_cert_get_keyusage_val (const struct lc_x509_certificate *cert, uint16_t *val)
	Get the key usage in integer form.
int	lc_x509_cert_get_san_dns (const struct lc_x509_certificate *cert, const char **san_dns_name, size_t *san_dns_len)
	Get the SAN DNS name.
int	lc_x509_cert_get_san_ip (const struct lc_x509_certificate *cert, const uint8_t **san_ip, size_t *san_ip_len)
	Get the SAN IP value.
int	lc_x509_dec_san_ip (const uint8_t *ip, size_t ip_len, char *ip_name, size_t ip_name_len)
	Helper to convert the binary IP address value into human-readable form.
int	lc_x509_cert_get_skid (const struct lc_x509_certificate *cert, const uint8_t **skid, size_t *skidlen)
	Get the SKID value.
int	lc_x509_cert_get_akid (const struct lc_x509_certificate *cert, const uint8_t **akid, size_t *akidlen)
	Get the AKID value.
int	lc_x509_cert_get_valid_from (const struct lc_x509_certificate *cert, time64_t *time_since_epoch)
	Get the valid-from data from the certificate.
int	lc_x509_cert_get_valid_to (const struct lc_x509_certificate *cert, time64_t *time_since_epoch)
	Get the valid-to data from the certificate.
int	lc_x509_cert_get_subject_cn (const struct lc_x509_certificate *cert, const char **string, size_t *string_len)
	Get the subject CN field from the certificate.
int	lc_x509_cert_get_subject_email (const struct lc_x509_certificate *cert, const char **string, size_t *string_len)
	Get the subject email field from the certificate.
int	lc_x509_cert_get_subject_ou (const struct lc_x509_certificate *cert, const char **string, size_t *string_len)
	Get the subject OU field from the certificate.
int	lc_x509_cert_get_subject_o (const struct lc_x509_certificate *cert, const char **string, size_t *string_len)
	Get the subject O field from the certificate.
int	lc_x509_cert_get_subject_st (const struct lc_x509_certificate *cert, const char **string, size_t *string_len)
	Get the subject ST field from the certificate.
int	lc_x509_cert_get_subject_c (const struct lc_x509_certificate *cert, const char **string, size_t *string_len)
	Get the subject C field from the certificate.
int	lc_x509_cert_get_issuer_cn (const struct lc_x509_certificate *cert, const char **string, size_t *string_len)
	Get the issuer CN field from the certificate.
int	lc_x509_cert_get_issuer_email (const struct lc_x509_certificate *cert, const char **string, size_t *string_len)
	Get the issuer email field from the certificate.
int	lc_x509_cert_get_issuer_ou (const struct lc_x509_certificate *cert, const char **string, size_t *string_len)
	Get the issuer OU field from the certificate.
int	lc_x509_cert_get_issuer_o (const struct lc_x509_certificate *cert, const char **string, size_t *string_len)
	Get the issuer O field from the certificate.
int	lc_x509_cert_get_issuer_st (const struct lc_x509_certificate *cert, const char **string, size_t *string_len)
	Get the issuer ST field from the certificate.
int	lc_x509_cert_get_issuer_c (const struct lc_x509_certificate *cert, const char **string, size_t *string_len)
	Get the issuer C field from the certificate.
int	lc_x509_cert_get_serial (const struct lc_x509_certificate *cert, const uint8_t **serial, size_t *serial_len)
	Get the serial number of the certificate.
lc_x509_pol_ret_t	lc_x509_policy_is_ca (const struct lc_x509_certificate *cert)
	Is the given certificate a CA certificate (root or intermediate)?
lc_x509_pol_ret_t	lc_x509_policy_can_validate_crls (const struct lc_x509_certificate *cert)
	Can the given certificate validate CRLs?
lc_x509_pol_ret_t	lc_x509_policy_is_selfsigned (const struct lc_x509_certificate *cert)
	Is the given certificate a self-signed certificate?
lc_x509_pol_ret_t	lc_x509_policy_is_root_ca (const struct lc_x509_certificate *cert)
	Is the given certificate a root CA certificate?
lc_x509_pol_ret_t	lc_x509_policy_match_akid (const struct lc_x509_certificate *cert, const uint8_t *reference_akid, size_t reference_akid_len)
	Does the given AKID match the certificate AKID?
lc_x509_pol_ret_t	lc_x509_policy_match_skid (const struct lc_x509_certificate *cert, const uint8_t *reference_skid, size_t reference_skid_len)
	Does the given SKID match the certificate SKID?
lc_x509_pol_ret_t	lc_x509_policy_match_key_usage (const struct lc_x509_certificate *cert, uint16_t required_key_usage)
	Check if set of required key usage flags are present.
lc_x509_pol_ret_t	lc_x509_policy_match_extended_key_usage (const struct lc_x509_certificate *cert, uint16_t required_eku)
	Check if set of required extended key usage flags are present.
lc_x509_pol_ret_t	lc_x509_policy_time_valid (const struct lc_x509_certificate *cert, time64_t current_time)
	Check if the given time falls within the range of the certificate validity time.
lc_x509_pol_ret_t	lc_x509_policy_cert_valid (const struct lc_x509_certificate *cert)
	Check if certificate is valid.
int	lc_x509_policy_verify_cert (const struct lc_public_key *pkey, const struct lc_x509_certificate *cert, uint64_t flags)
	Verification of an X.509 certificate against a public key.

Detailed Description

Concept of X.509 certificate parsing handling in leancrypto

The leancrypto library provides an X.509 parser which can read and understand X.509 certificates. To appropriately use the X.509 parser, please consider the following rules:

1. The parser interprets the provided X.509 data blob and fills a data structure which allows immediate access to the certificate properties by the leancrypto code. The data structure x509_certificate is provided as part of the official header file. But it is NOT considered to be an API. I.e. member variables or the structure format may change between versions of leancrypto without announcement. The reason for providing the data structure in the official header file is to support stack-only clients.
2. The parser fills the data structure with pointers into the original X.509 data blob. The caller MUST keep the original X.509 data blob at the same location for the life time of the associated instance of the x509_certificate data structure.
3. The X.509 parser API call only interprets and parses the X.509 data blob. It does NOT enforce any kind of restrictions or policies. The caller MUST use the provided X.509 policy API to enforce policies on the given certificate.

Macro Definition Documentation

LC_X509_KEYS_DILITHIUM_ED25519_ON_STACK

#define LC_X509_KEYS_DILITHIUM_ED25519_ON_STACK

(

name

)

Value:

        _Pragma("GCC diagnostic push") _Pragma(                                \
                "GCC diagnostic ignored \"-Wdeclaration-after-statement\"")    \
                _Pragma("GCC diagnostic ignored \"-Wcast-align\"")             \
                        LC_ALIGNED_BUFFER(name##_ctx_buf,                      \
                                          LC_X509_KEYS_DILITHIUM_ED25519_SIZE, \
                                          LC_HASH_COMMON_ALIGNMENT);           \
        struct lc_x509_key_data *name =                                        \
                (struct lc_x509_key_data *)name##_ctx_buf;                     \
        LC_X509_KEYS_DILITHIUM_ED25519_SET(name);                              \
        _Pragma("GCC diagnostic pop")

Allocate memory for struct lc_x509_keys_data holding Dilithium-ED25519 keys on stack.

Parameters

[in]

name

Name of stack variable

Definition at line 218 of file lc_x509_parser.h.

LC_X509_KEYS_DILITHIUM_ED448_ON_STACK

#define LC_X509_KEYS_DILITHIUM_ED448_ON_STACK

(

name

)

Value:

        _Pragma("GCC diagnostic push") _Pragma(                                \
                "GCC diagnostic ignored \"-Wdeclaration-after-statement\"")    \
                _Pragma("GCC diagnostic ignored \"-Wcast-align\"")             \
                        LC_ALIGNED_BUFFER(name##_ctx_buf,                      \
                                          LC_X509_KEYS_DILITHIUM_ED448_SIZE,   \
                                          LC_HASH_COMMON_ALIGNMENT);           \
        struct lc_x509_key_data *name =                                        \
                (struct lc_x509_key_data *)name##_ctx_buf;                     \
        LC_X509_KEYS_DILITHIUM_ED448_SET(name);                                \
        _Pragma("GCC diagnostic pop")

Allocate memory for struct lc_x509_keys_data holding Dilithium-ED448 keys on stack.

Parameters

[in]

name

Name of stack variable

Definition at line 237 of file lc_x509_parser.h.

LC_X509_KEYS_DILITHIUM_ON_STACK

#define LC_X509_KEYS_DILITHIUM_ON_STACK

(

name

)

Value:

        _Pragma("GCC diagnostic push") _Pragma(                                \
                "GCC diagnostic ignored \"-Wdeclaration-after-statement\"")    \
                LC_ALIGNED_BUFFER(name##_ctx_buf, LC_X509_KEYS_DILITHIUM_SIZE, \
                                  LC_HASH_COMMON_ALIGNMENT);                   \
        struct lc_x509_key_data *name =                                        \
                (struct lc_x509_key_data *)name##_ctx_buf;                     \
        LC_X509_KEYS_DILITHIUM_SET(name);                                      \
        _Pragma("GCC diagnostic pop")

Allocate memory for struct lc_x509_keys_data holding Dilithium keys on stack.

Parameters

[in]

name

Name of stack variable

Definition at line 157 of file lc_x509_parser.h.

LC_X509_KEYS_ON_STACK

#define LC_X509_KEYS_ON_STACK

(

name

)

Value:

LC_X509_KEYS_DILITHIUM_ED448_ON_STACK(name)

Allocate memory for struct lc_x509_keys_data holding any kind of key type on stack.

Parameters

[in]

name

Name of stack variable

Definition at line 257 of file lc_x509_parser.h.

LC_X509_KEYS_SPHINCS_ON_STACK

#define LC_X509_KEYS_SPHINCS_ON_STACK

(

name

)

Value:

        _Pragma("GCC diagnostic push") _Pragma(                                \
                "GCC diagnostic ignored \"-Wdeclaration-after-statement\"")    \
                LC_ALIGNED_BUFFER(name##_ctx_buf, LC_X509_KEYS_SPHINCS_SIZE,   \
                                  LC_HASH_COMMON_ALIGNMENT);                   \
        struct lc_x509_key_data *name =                                        \
                (struct lc_x509_key_data *)name##_ctx_buf;                     \
        LC_X509_KEYS_SPHINCS_SET(name);                                        \
        _Pragma("GCC diagnostic pop")

Allocate memory for struct lc_x509_keys_data holding Sphincs Plus keys on stack.

Parameters

[in]

name

Name of stack variable

Definition at line 122 of file lc_x509_parser.h.

Function Documentation

lc_x509_cert_clear()

void lc_x509_cert_clear

(

struct lc_x509_certificate *

cert

)

Clear the resources used by the X.509 certificate parsing state.

Parameters

[in]

cert

Certificate structure to be cleared

lc_x509_cert_decode()

int lc_x509_cert_decode	(	struct lc_x509_certificate *	cert,
		const uint8_t *	data,
		size_t	datalen )

Decode an X.509 certificate.

The function parses an X.509 data buffer into a data structure that allows accessing the various data points of the certificate.

Note

The cert data structure will contain pointers to the data buffer. I.e. the certificate parsing analyzes data and finds all relevant data in the raw X.509 data blob. The caller MUST therefore keep the data pointer constant as long as the cert pointer is valid.

This function only loads and parses the certificate into the data structure to allow leancrypto to immediately access the information. This function call does not validate the certificate (except for a self-signed signature). Thus, the caller MUST apply the X.509 policy check functions to validate the certificate considering that the loading of the certificate has no information about the use case.

Parameters

[in,out]	cert	The data structure that is filled with all parameters from the X.509 certificate data buffer. The buffer must have been allocated by the caller. It is permissible to keep it on the stack.
[in]	data	Raw X.509 data blob in DER / BER format
[in]	datalen	Length of the raw X.509 certificate buffer

Returns

0 on success or < 0 on error

lc_x509_cert_get_akid()

int lc_x509_cert_get_akid	(	const struct lc_x509_certificate *	cert,
		const uint8_t **	akid,
		size_t *	akidlen )

Get the AKID value.

Note

The returned pointers have the same life time as cert.

Parameters

[in]	cert	X.509 certificate from which the data is to be obtained
[out]	akid	Binary representation of AKID
[out]	akidlen	length of the AKID buffer

Returns

0 on success or < 0 on error

lc_x509_cert_get_eku()

int lc_x509_cert_get_eku	(	const struct lc_x509_certificate *	cert,
		const char ***	eku_names,
		unsigned int *	num_eku )

Get the extended key usage in human readable form.

The service function returns an array of EKU names the certificate contains

Parameters

[in]	cert	X.509 certificate from which the data is to be obtained
[out]	eku_names	Reference to an array of strings
[out]	num_eku	Number of returned EKU strings

Returns

0 on success or < 0 on error

lc_x509_cert_get_eku_val()

int lc_x509_cert_get_eku_val	(	const struct lc_x509_certificate *	cert,
		uint16_t *	val )

Get the extended key usage in integer form.

Parameters

[in]	cert	X.509 certificate from which the data is to be obtained
[out]	val	EKU value holding the LC_KEY_EKU_* flags

Returns

0 on success or < 0 on error

lc_x509_cert_get_issuer_c()

int lc_x509_cert_get_issuer_c	(	const struct lc_x509_certificate *	cert,
		const char **	string,
		size_t *	string_len )

Get the issuer C field from the certificate.

Note

The returned pointers have the same life time as cert.

The returned pointer may not be NULL-terminated which implies that this function returns also the size of the string. Yet, it is a human readable string.

Parameters

[in]	cert	X.509 certificate from which the data is to be obtained
[out]	string	Reference to data field
[out]	string_len	Length of the data field

Returns

0 on success or < 0 on error

lc_x509_cert_get_issuer_cn()

int lc_x509_cert_get_issuer_cn	(	const struct lc_x509_certificate *	cert,
		const char **	string,
		size_t *	string_len )

Get the issuer CN field from the certificate.

Note

The returned pointers have the same life time as cert.

The returned pointer may not be NULL-terminated which implies that this function returns also the size of the string. Yet, it is a human readable string.

Parameters

[in]	cert	X.509 certificate from which the data is to be obtained
[out]	string	Reference to data field
[out]	string_len	Length of the data field

Returns

0 on success or < 0 on error

lc_x509_cert_get_issuer_email()

int lc_x509_cert_get_issuer_email	(	const struct lc_x509_certificate *	cert,
		const char **	string,
		size_t *	string_len )

Get the issuer email field from the certificate.

Note

The returned pointers have the same life time as cert.

The returned pointer may not be NULL-terminated which implies that this function returns also the size of the string. Yet, it is a human readable string.

Parameters

[in]	cert	X.509 certificate from which the data is to be obtained
[out]	string	Reference to data field
[out]	string_len	Length of the data field

Returns

0 on success or < 0 on error

lc_x509_cert_get_issuer_o()

int lc_x509_cert_get_issuer_o	(	const struct lc_x509_certificate *	cert,
		const char **	string,
		size_t *	string_len )

Get the issuer O field from the certificate.

Note

The returned pointers have the same life time as cert.

The returned pointer may not be NULL-terminated which implies that this function returns also the size of the string. Yet, it is a human readable string.

Parameters

[in]	cert	X.509 certificate from which the data is to be obtained
[out]	string	Reference to data field
[out]	string_len	Length of the data field

Returns

0 on success or < 0 on error

lc_x509_cert_get_issuer_ou()

int lc_x509_cert_get_issuer_ou	(	const struct lc_x509_certificate *	cert,
		const char **	string,
		size_t *	string_len )

Get the issuer OU field from the certificate.

Note

The returned pointers have the same life time as cert.

The returned pointer may not be NULL-terminated which implies that this function returns also the size of the string. Yet, it is a human readable string.

Parameters

[in]	cert	X.509 certificate from which the data is to be obtained
[out]	string	Reference to data field
[out]	string_len	Length of the data field

Returns

0 on success or < 0 on error

lc_x509_cert_get_issuer_st()

int lc_x509_cert_get_issuer_st	(	const struct lc_x509_certificate *	cert,
		const char **	string,
		size_t *	string_len )

Get the issuer ST field from the certificate.

Note

The returned pointers have the same life time as cert.

The returned pointer may not be NULL-terminated which implies that this function returns also the size of the string. Yet, it is a human readable string.

Parameters

[in]	cert	X.509 certificate from which the data is to be obtained
[out]	string	Reference to data field
[out]	string_len	Length of the data field

Returns

0 on success or < 0 on error

lc_x509_cert_get_keyusage()

int lc_x509_cert_get_keyusage	(	const struct lc_x509_certificate *	cert,
		const char ***	keyusage_names,
		unsigned int *	num_keyusage )

Get the key usage in human readable form.

The service function returns an array of key usage names the certificate contains

Parameters

[in]	cert	X.509 certificate from which the data is to be obtained
[out]	keyusage_names	Reference to an array of strings
[out]	num_keyusage	Number of returned key usage strings

Returns

0 on success or < 0 on error

lc_x509_cert_get_keyusage_val()

int lc_x509_cert_get_keyusage_val	(	const struct lc_x509_certificate *	cert,
		uint16_t *	val )

Get the key usage in integer form.

Parameters

[in]	cert	X.509 certificate from which the data is to be obtained
[out]	val	key usage value holding the LC_KEY_USAGE_* flags

Returns

0 on success or < 0 on error

lc_x509_cert_get_pubkey()

int lc_x509_cert_get_pubkey	(	const struct lc_x509_certificate *	cert,
		const uint8_t **	pk,
		size_t *	pk_size,
		enum lc_sig_types *	key_type )

Get a reference of the public key data.

The service function returns a pointer to the public key data in the certificate.

Note

The returned pointers have the same life time as cert.

Parameters

[in]	cert	X.509 certificate from which the public is to be obtained
[out]	pk	X.509 public key buffer reference (may be NULL)
[out]	pk_size	Size of the public key (may be NULL)
[out]	key_type	Type of the public key (may be NULL)

Returns

0 on success or < 0 on error

lc_x509_cert_get_san_dns()

int lc_x509_cert_get_san_dns	(	const struct lc_x509_certificate *	cert,
		const char **	san_dns_name,
		size_t *	san_dns_len )

Get the SAN DNS name.

Note

The san_dns_name may not be NULL-terminated which implies that this function returns also the size of the string. Yet, it is a human readable string.

The returned pointers have the same life time as cert.

Parameters

[in]	cert	X.509 certificate from which the data is to be obtained
[out]	san_dns_name	Reference to the SAN DNS name
[out]	san_dns_len	Length of the SAN DNS name

Returns

0 on success or < 0 on error

lc_x509_cert_get_san_ip()

int lc_x509_cert_get_san_ip	(	const struct lc_x509_certificate *	cert,
		const uint8_t **	san_ip,
		size_t *	san_ip_len )

Get the SAN IP value.

Note

The returned pointers have the same life time as cert.

Parameters

[in]	cert	X.509 certificate from which the data is to be obtained
[out]	san_ip	Binary representation of IP address
[out]	san_ip_len	Length of the SAN IP address

Returns

0 on success or < 0 on error

lc_x509_cert_get_serial()

int lc_x509_cert_get_serial	(	const struct lc_x509_certificate *	cert,
		const uint8_t **	serial,
		size_t *	serial_len )

Get the serial number of the certificate.

Note

The returned pointers have the same life time as cert.

Parameters

[in]	cert	X.509 certificate from which the data is to be obtained
[out]	serial	Binary representation of serial number
[out]	serial_len	Length of the serial number

Returns

0 on success or < 0 on error

lc_x509_cert_get_skid()

int lc_x509_cert_get_skid	(	const struct lc_x509_certificate *	cert,
		const uint8_t **	skid,
		size_t *	skidlen )

Get the SKID value.

Note

The returned pointers have the same life time as cert.

Parameters

[in]	cert	X.509 certificate from which the data is to be obtained
[out]	skid	Binary representation of SKID
[out]	skidlen	length of the SKID buffer

Returns

0 on success or < 0 on error

lc_x509_cert_get_subject_c()

int lc_x509_cert_get_subject_c	(	const struct lc_x509_certificate *	cert,
		const char **	string,
		size_t *	string_len )

Get the subject C field from the certificate.

Note

The returned pointers have the same life time as cert.

The returned pointer may not be NULL-terminated which implies that this function returns also the size of the string. Yet, it is a human readable string.

Parameters

[in]	cert	X.509 certificate from which the data is to be obtained
[out]	string	Reference to data field
[out]	string_len	Length of the data field

Returns

0 on success or < 0 on error

lc_x509_cert_get_subject_cn()

int lc_x509_cert_get_subject_cn	(	const struct lc_x509_certificate *	cert,
		const char **	string,
		size_t *	string_len )

Get the subject CN field from the certificate.

Note

The returned pointers have the same life time as cert.

The returned pointer may not be NULL-terminated which implies that this function returns also the size of the string. Yet, it is a human readable string.

Parameters

[in]	cert	X.509 certificate from which the data is to be obtained
[out]	string	Reference to data field
[out]	string_len	Length of the data field

Returns

0 on success or < 0 on error

lc_x509_cert_get_subject_email()

int lc_x509_cert_get_subject_email	(	const struct lc_x509_certificate *	cert,
		const char **	string,
		size_t *	string_len )

Get the subject email field from the certificate.

Note

The returned pointers have the same life time as cert.

The returned pointer may not be NULL-terminated which implies that this function returns also the size of the string. Yet, it is a human readable string.

Parameters

[in]	cert	X.509 certificate from which the data is to be obtained
[out]	string	Reference to data field
[out]	string_len	Length of the data field

Returns

0 on success or < 0 on error

lc_x509_cert_get_subject_o()

int lc_x509_cert_get_subject_o	(	const struct lc_x509_certificate *	cert,
		const char **	string,
		size_t *	string_len )

Get the subject O field from the certificate.

Note

The returned pointers have the same life time as cert.

The returned pointer may not be NULL-terminated which implies that this function returns also the size of the string. Yet, it is a human readable string.

Parameters

[in]	cert	X.509 certificate from which the data is to be obtained
[out]	string	Reference to data field
[out]	string_len	Length of the data field

Returns

0 on success or < 0 on error

lc_x509_cert_get_subject_ou()

int lc_x509_cert_get_subject_ou	(	const struct lc_x509_certificate *	cert,
		const char **	string,
		size_t *	string_len )

Get the subject OU field from the certificate.

Note

The returned pointers have the same life time as cert.

The returned pointer may not be NULL-terminated which implies that this function returns also the size of the string. Yet, it is a human readable string.

Parameters

[in]	cert	X.509 certificate from which the data is to be obtained
[out]	string	Reference to data field
[out]	string_len	Length of the data field

Returns

0 on success or < 0 on error

lc_x509_cert_get_subject_st()

int lc_x509_cert_get_subject_st	(	const struct lc_x509_certificate *	cert,
		const char **	string,
		size_t *	string_len )

Get the subject ST field from the certificate.

Note

The returned pointers have the same life time as cert.

The returned pointer may not be NULL-terminated which implies that this function returns also the size of the string. Yet, it is a human readable string.

Parameters

[in]	cert	X.509 certificate from which the data is to be obtained
[out]	string	Reference to data field
[out]	string_len	Length of the data field

Returns

0 on success or < 0 on error

lc_x509_cert_get_valid_from()

int lc_x509_cert_get_valid_from	(	const struct lc_x509_certificate *	cert,
		time64_t *	time_since_epoch )

Get the valid-from data from the certificate.

The returned time data is an integer giving the data in seconds since EPOCH.

Parameters

[in]	cert	X.509 certificate from which the data is to be obtained
[out]	time_since_epoch	Time in seconds since EPOCH

Returns

0 on success or < 0 on error

lc_x509_cert_get_valid_to()

int lc_x509_cert_get_valid_to	(	const struct lc_x509_certificate *	cert,
		time64_t *	time_since_epoch )

Get the valid-to data from the certificate.

The returned time data is an integer giving the data in seconds since EPOCH.

Parameters

[in]	cert	X.509 certificate from which the data is to be obtained
[out]	time_since_epoch	Time in seconds since EPOCH

Returns

0 on success or < 0 on error

lc_x509_cert_load_pk_dilithium_ed25519()

int lc_x509_cert_load_pk_dilithium_ed25519	(	struct lc_dilithium_ed25519_pk *	dilithium_ed25519_pk,
		const uint8_t *	pk_ptr,
		size_t	pk_len )

Parse a Composite ML-DSA ASN.1 structure into a public key structure.

Parameters

[out]	dilithium_ed25519_pk	Public key to be filled
[in]	pk_ptr	Pointer to ASN.1 structure
[out]	pk_len	Size of the public key ASN.1 structure

Returns

0 on success or < 0 on error

lc_x509_cert_load_pk_dilithium_ed448()

int lc_x509_cert_load_pk_dilithium_ed448	(	struct lc_dilithium_ed448_pk *	dilithium_ed448_pk,
		const uint8_t *	pk_ptr,
		size_t	pk_len )

Parse a Composite ML-DSA ASN.1 structure into a public key structure.

Parameters

[out]	dilithium_ed448_pk	Public key to be filled
[in]	pk_ptr	Pointer to ASN.1 structure
[out]	pk_len	Size of the public key ASN.1 structure

Returns

0 on success or < 0 on error

lc_x509_dec_san_ip()

int lc_x509_dec_san_ip	(	const uint8_t *	ip,
		size_t	ip_len,
		char *	ip_name,
		size_t	ip_name_len )

Helper to convert the binary IP address value into human-readable form.

Parameters

[in]	ip	Binary representation of IP address
[in]	ip_len	Length of the IP address
[out]	ip_name	Caller-provided buffer to fill with human-readable form
[in]	ip_name_len	Size of the ip_name buffer that can be filled

Returns

0 on success or < 0 on error

lc_x509_keys_alloc()

int lc_x509_keys_alloc

(

struct lc_x509_key_data **

keys

)

Allocate memory for struct lc_x509_keys_data holding holding any kind of key type on heap.

Parameters

[in]

keys

Variable to allocate

Returns

0 on success or < 0 on error

lc_x509_keys_dilithium_alloc()

int lc_x509_keys_dilithium_alloc

(

struct lc_x509_key_data **

keys

)

Allocate memory for struct lc_x509_keys_data holding Dilithium keys on heap.

Parameters

[in]

keys

Variable to allocate

Returns

0 on success or < 0 on error

lc_x509_keys_dilithium_ed25519_alloc()

int lc_x509_keys_dilithium_ed25519_alloc

(

struct lc_x509_key_data **

keys

)

Allocate memory for struct lc_x509_keys_data holding Dilithium-ED25519 keys on heap.

Parameters

[in]

keys

Variable to allocate

Returns

0 on success or < 0 on error

lc_x509_keys_dilithium_ed448_alloc()

int lc_x509_keys_dilithium_ed448_alloc

(

struct lc_x509_key_data **

keys

)

Allocate memory for struct lc_x509_keys_data holding Dilithium-ED448 keys on heap.

Parameters

[in]

keys

Variable to allocate

Returns

0 on success or < 0 on error

lc_x509_keys_sphincs_alloc()

int lc_x509_keys_sphincs_alloc

(

struct lc_x509_key_data **

keys

)

Allocate memory for struct lc_x509_keys_data holding Sphincs Plus keys on heap.

Parameters

[in]

keys

Variable to allocate

Returns

0 on success or < 0 on error

lc_x509_keys_zero_free()

void lc_x509_keys_zero_free

(

struct lc_x509_key_data *

keys

)

Zeroize and free keys buffer.

Parameters

[in]

keys

Variable to zeroize and free

lc_x509_pk_decode()

int lc_x509_pk_decode	(	struct lc_x509_key_data *	key,
		enum lc_sig_types	key_type,
		const uint8_t *	data,
		size_t	datalen )

Decode a public key in raw format.

The function parses a private data buffer into a data structure that allows immediate use of the parsed key data with the cryptographic primitives.

Note

The key data structure will contain the data of the public keys. I.e. the key material is loaded into the databuffer as during load time, various checks are applied. The caller MUST ensure proper disposal of the buffer holding sensitive data.

Parameters

[out]	key	The data structure that is filled with the public key. The caller must have allocated sufficient space with one of LC_X509_KEYS*_ON_STACK or lc_x509_keys*_alloc
[in]	key_type	Type of the private key - prevent the deduction of the the private key from the key file
[in]	data	Raw data blob
[in]	datalen	Length of the raw buffer

Returns

0 on success or < 0 on error

lc_x509_policy_can_validate_crls()

lc_x509_pol_ret_t lc_x509_policy_can_validate_crls

(

const struct lc_x509_certificate *

cert

)

Can the given certificate validate CRLs?

Parameters

[in]

cert

Reference to the certificate

Returns

< 0 on error, LC_X509_POL_TRUE or LC_X509_POL_FALSE

lc_x509_policy_cert_valid()

lc_x509_pol_ret_t lc_x509_policy_cert_valid

(

const struct lc_x509_certificate *

cert

)

Check if certificate is valid.

This check validates all RFC5280 constraints for a conforming certificate.

Parameters

[in]

cert

Reference to the certificate

Returns

< 0 on error, LC_X509_POL_TRUE or LC_X509_POL_FALSE

lc_x509_policy_is_ca()

lc_x509_pol_ret_t lc_x509_policy_is_ca

(

const struct lc_x509_certificate *

cert

)

Is the given certificate a CA certificate (root or intermediate)?

Parameters

[in]

cert

Reference to the certificate

Returns

< 0 on error, LC_X509_POL_TRUE or LC_X509_POL_FALSE

lc_x509_policy_is_root_ca()

lc_x509_pol_ret_t lc_x509_policy_is_root_ca

(

const struct lc_x509_certificate *

cert

)

Is the given certificate a root CA certificate?

Parameters

[in]

cert

Reference to the certificate

Returns

< 0 on error, LC_X509_POL_TRUE or LC_X509_POL_FALSE

lc_x509_policy_is_selfsigned()

lc_x509_pol_ret_t lc_x509_policy_is_selfsigned

(

const struct lc_x509_certificate *

cert

)

Is the given certificate a self-signed certificate?

Parameters

[in]

cert

Reference to the certificate

Returns

< 0 on error, LC_X509_POL_TRUE or LC_X509_POL_FALSE

lc_x509_policy_match_akid()

lc_x509_pol_ret_t lc_x509_policy_match_akid	(	const struct lc_x509_certificate *	cert,
		const uint8_t *	reference_akid,
		size_t	reference_akid_len )

Does the given AKID match the certificate AKID?

Parameters

[in]	cert	Reference to the certificate
[in]	reference_akid	AKID in binary format to be matched
[in]	reference_akid_len	length of AKID binary buffer

Returns

< 0 on error, LC_X509_POL_TRUE or LC_X509_POL_FALSE

lc_x509_policy_match_extended_key_usage()

lc_x509_pol_ret_t lc_x509_policy_match_extended_key_usage	(	const struct lc_x509_certificate *	cert,
		uint16_t	required_eku )

Check if set of required extended key usage flags are present.

Parameters

[in]	cert	Reference to the certificate
[in]	required_eku	flags field with the bits set that the certificate must contain

Returns

< 0 on error, LC_X509_POL_TRUE or LC_X509_POL_FALSE

lc_x509_policy_match_key_usage()

lc_x509_pol_ret_t lc_x509_policy_match_key_usage	(	const struct lc_x509_certificate *	cert,
		uint16_t	required_key_usage )

Check if set of required key usage flags are present.

Parameters

[in]	cert	Reference to the certificate
[in]	required_key_usage	flags field with the bits set that the certificate must contain

Returns

< 0 on error, LC_X509_POL_TRUE or LC_X509_POL_FALSE

lc_x509_policy_match_skid()

lc_x509_pol_ret_t lc_x509_policy_match_skid	(	const struct lc_x509_certificate *	cert,
		const uint8_t *	reference_skid,
		size_t	reference_skid_len )

Does the given SKID match the certificate SKID?

Parameters

[in]	cert	Reference to the certificate
[in]	reference_skid	SKID in binary format to be matched
[in]	reference_skid_len	length of SKID binary buffer

Returns

< 0 on error, LC_X509_POL_TRUE or LC_X509_POL_FALSE

lc_x509_policy_time_valid()

lc_x509_pol_ret_t lc_x509_policy_time_valid	(	const struct lc_x509_certificate *	cert,
		time64_t	current_time )

Check if the given time falls within the range of the certificate validity time.

Parameters

[in]	cert	Reference to the certificate
[in]	current_time	Time value to verify - this time is given in seconds since EPOCH, e.g. by the POSIX service function time.

Returns

< 0 on error, LC_X509_POL_TRUE or LC_X509_POL_FALSE

lc_x509_policy_verify_cert()

int lc_x509_policy_verify_cert	(	const struct lc_public_key *	pkey,
		const struct lc_x509_certificate *	cert,
		uint64_t	flags )

Verification of an X.509 certificate against a public key.

This function performs the signature verification of the signature associated with an X.509 certificate against the public key provided by the caller. In addition, it performs all validity checks required as part of the verification operation, including the validity time enforcement. Only if all checks pass, the certificate is considered to be validated.

Parameters

[in]	pkey	Public key to check the certificate against
[in]	cert	Reference to the certificate to be validated
[in]	flags	Flags for the verification process (currently unused)

Returns

0 on success, < 0 on error

lc_x509_signature_verify()

int lc_x509_signature_verify	(	const uint8_t *	sig_data,
		size_t	siglen,
		const struct lc_x509_certificate *	cert,
		const uint8_t *	m,
		size_t	mlen,
		const struct lc_hash *	prehash_algo )

Verify signature over user-supplied data.

Note

This function only performs the signature verification. It does not enforce any key usage or EKU definition present in the X.509 certificate.

Parameters

[in]	sig_data	Caller-supplied buffer with signature
[in]	siglen	Length of the sig_data buffer
[in]	cert	The certificate to be used to verify signature
[in]	m	Message to be verified
[in]	mlen	Length of message
[in]	prehash_algo	It is permissible that the message is prehashed. If so, it is indicated by this parameter which points to the used message digest the caller used to generate the prehashed message digest. This forces the use of the Hash[ML|SLH|Composite]-DSA.

Returns

0 on success or < 0 on error

lc_x509_sk_decode()

int lc_x509_sk_decode	(	struct lc_x509_key_data *	key,
		enum lc_sig_types	key_type,
		const uint8_t *	data,
		size_t	datalen )

Decode a private key in DER format.

The function parses a private data buffer into a data structure that allows immediate use of the parsed key data with the cryptographic primitives.

Note

The key data structure will contain the data of the secret keys. I.e. the key material is loaded into the databuffer as during load time, various checks are applied. The caller MUST ensure proper disposal of the buffer holding sensitive data.

Parameters

[out]	key	The data structure that is filled with the private key. The caller must have allocated sufficient space with one of LC_X509_KEYS*_ON_STACK or lc_x509_keys*_alloc
[in]	key_type	Type of the private key - prevent the deduction of the the private key from the key file
[in]	data	Raw DER data blob in DER format
[in]	datalen	Length of the raw DER buffer

Returns

0 on success or < 0 on error