OCF public key infrastructure (PKI) functions. More...

#include "oc_export.h"
#include "oc_sp.h"
#include <mbedtls/build_info.h>
#include <mbedtls/mbedtls_config.h>
#include <mbedtls/x509_crt.h>
#include <stddef.h>
#include <stdbool.h>

Typedefs
typedef int(*	mbedtls_pk_ecp_gen_key_cb_t) (size_t device, mbedtls_ecp_group_id grp_id, mbedtls_pk_context pk, int(f_rng) (void , unsigned char , size_t), void *p_rng)
	This function generates the ECP key for the identity certificate of the device. More...

typedef int(*	mbedtls_pk_parse_key_cb_t) (size_t device, mbedtls_pk_context pk, const unsigned char key, size_t keylen, const unsigned char pwd, size_t pwdlen, int(f_rng) (void , unsigned char , size_t), void *p_rng)
	This function loads a private key for use with identity or manufacturer certificates stored in the credential resource of a device. More...

typedef int(*	mbedtls_pk_write_key_der_cb_t) (size_t device, const mbedtls_pk_context ctx, unsigned char buf, size_t size)
	This function writes a private key to the credential resource for storage. More...

typedef struct oc_pki_pk_functions_s	oc_pki_pk_functions_t

typedef int(*	oc_pki_verify_certificate_cb_t) (struct oc_tls_peer_t peer, const mbedtls_x509_crt crt, int depth, uint32_t *flags)
	Callback invoked after ocf verifies the certificate chain. More...

typedef bool(*	pk_free_key_cb_t) (size_t device, const unsigned char *key, size_t keylen)
	This function frees the private key of the device generated by mbedtls_pk_ecp_gen_key_cb_t. More...

Functions
int	oc_pki_add_identity_cert (size_t device, const unsigned char cert, size_t cert_size, const unsigned char key, size_t key_size)
	Add a PKI identity certificate. More...

int	oc_pki_add_mfg_cert (size_t device, const unsigned char cert, size_t cert_size, const unsigned char key, size_t key_size)
	Add the manufacturer's PKI identity certificate. More...

int	oc_pki_add_mfg_intermediate_cert (size_t device, int credid, const unsigned char *cert, size_t cert_size)
	Add an intermediate manufacture CA certificate. More...

int	oc_pki_add_mfg_trust_anchor (size_t device, const unsigned char *cert, size_t cert_size)
	Add manufacture trust anchor CA. More...

int	oc_pki_add_trust_anchor (size_t device, const unsigned char *cert, size_t cert_size)
	Add trust anchor CA. More...

bool	oc_pki_get_pk_functions (oc_pki_pk_functions_t *pk_functions)
	Get the PK functions for the identity certificate or the manufacturer certificate. More...

oc_pki_verify_certificate_cb_t	oc_pki_get_verify_certificate_cb (void)
	Get the verification callback for the certificate chain. More...

bool	oc_pki_set_pk_functions (const oc_pki_pk_functions_t *pk_functions)
	Set the PK functions for the identity certificate or the manufacturer certificate. More...

void	oc_pki_set_verify_certificate_cb (oc_pki_verify_certificate_cb_t cb)
	Set the verification callback for the certificate chain. More...

Detailed Description

OCF public key infrastructure (PKI) functions.

Collection of functions used to add public key infrastructure (PKI) support to devices.

Typedef Documentation

◆ mbedtls_pk_ecp_gen_key_cb_t

typedef int(* mbedtls_pk_ecp_gen_key_cb_t) (size_t device, mbedtls_ecp_group_id grp_id, mbedtls_pk_context *pk, int(*f_rng)(void *, unsigned char *, size_t), void *p_rng)

This function generates the ECP key for the identity certificate of the device.

If the device has a TPM, the function will generate a private key within the TPM and store it there. The generated key is returned as an object that can be used to create an identity certificate.

Parameters

device	The device index the key belongs to.
grp_id	The ECP group identifier.
pk	The destination key. The key is initialized by MBEDTLS_PK_ECKEY.
f_rng	The RNG function to use. This must not be `NULL`.
p_rng	The RNG context to be passed to `f_rng`. This may be `NULL` if `f_rng` doesn't need a context argument.

Returns: 0 on success.; An MBEDTLS_ERR_ECP_XXX or MBEDTLS_MPI_XXX error code on failure.

See also: https://arm-software.github.io/CMSIS-mbedTLS/latest/ecp_8h.html#a0c9a407214f019493ba5d7bc27fa57dc

◆ mbedtls_pk_parse_key_cb_t

typedef int(* mbedtls_pk_parse_key_cb_t) (size_t device, mbedtls_pk_context *pk, const unsigned char *key, size_t keylen, const unsigned char *pwd, size_t pwdlen, int(*f_rng)(void *, unsigned char *, size_t), void *p_rng)

This function loads a private key for use with identity or manufacturer certificates stored in the credential resource of a device.

The private key can be provided in either PEM or DER format, or by reference to a previously stored private key in TPM. The function parses the provided private key and returns a loaded private key object, which can then be used in cryptographic operations.

Parameters

device	The device index the key belongs to.
pk	The PK context to fill. It must have been initialized but not set up.
key	Input buffer to parse. The buffer must contain the input exactly, with no extra trailing material. For PEM, the buffer must contain a null-terminated string. It could be PEM, DER or the reference key (eg in TPM).
keylen	Size of key in bytes. For PEM data, this includes the terminating null byte, so `keylen` must be equal to `strlen(key) + 1`.
pwd	Optional password for decryption. Pass `NULL` if expecting a non-encrypted key. Pass a string of `pwdlen` bytes if expecting an encrypted key; a non-encrypted key will also be accepted. The empty password is not supported.
pwdlen	Size of the password in bytes. Ignored if `pwd` is `NULL`.
f_rng	RNG function, must not be `NULL`. Used for blinding.
p_rng	RNG parameter

Note: On entry, ctx must be empty, either freshly initialised with mbedtls_pk_init() or reset with mbedtls_pk_free(). If you need a specific key type, check the result with mbedtls_pk_can_do().; The key is also checked for correctness.

Returns: 0 if successful, or a specific PK or PEM error code

See also: https://arm-software.github.io/CMSIS-mbedTLS/latest/pk_8h.html#aad02107b63f2a47020e6e1ef328e4393

◆ mbedtls_pk_write_key_der_cb_t

typedef int(* mbedtls_pk_write_key_der_cb_t) (size_t device, const mbedtls_pk_context *ctx, unsigned char *buf, size_t size)

This function writes a private key to the credential resource for storage.

The private key can be provided as an object and will be written in either PKCS#1 or SEC1 DER structure, depending on the specified format. Alternatively, a reference to a private key stored in TPM can be provided, and the function will write the reference to the credential resource. Once the private key is written, it can be used with identity or manufacturer certificates for cryptographic operations. Note: data is written at the end of the buffer! Use the return value to determine where you should start using the buffer

Parameters

device	The device index the key belongs to.
ctx	PK context which must contain a valid private key.
buf	buffer to write to
size	size of the buffer

Returns: length of data written if successful, or a specific error code

See also: https://arm-software.github.io/CMSIS-mbedTLS/latest/pk_8h.html#a2cf4ebaa430cc90954c9556ace2d4dc0

◆ oc_pki_verify_certificate_cb_t

typedef int(* oc_pki_verify_certificate_cb_t) (struct oc_tls_peer_t *peer, const mbedtls_x509_crt *crt, int depth, uint32_t *flags)

Callback invoked after ocf verifies the certificate chain.

For each certificate in the chain, the callback is invoked with the depth of the certificate in the chain.

Parameters

peer	TLS peer connection
crt	Certificate
depth	Depth of the certificate chain, 0 is the leaf certificate.
flags	Verification flags from mbedtls_x509_crt_verify(), see https://github.com/Mbed-TLS/mbedtls/blob/10ada3501975e7abab25a7fa28e9e8e0f6b4259f/include/mbedtls/x509.h#L99

Returns: 0 if the certificate is valid, otherwise -1

◆ pk_free_key_cb_t

typedef bool(* pk_free_key_cb_t) (size_t device, const unsigned char *key, size_t keylen)

This function frees the private key of the device generated by mbedtls_pk_ecp_gen_key_cb_t.

It is called when factory reset is performed or during generating csr when the key-pair is not valid.

Parameters

device	The device index the key belongs to.
key	The private key to free.
keylen	The length of the private key.

Returns: true, the key is invalid and needs to be regenerated; false, the key is still valid

Note: default implementation returns false, so the key is same as before.

See also: oc_mbedtls_pk_ecp_gen_key

Function Documentation

◆ oc_pki_add_identity_cert()

int oc_pki_add_identity_cert	(	size_t	device,
		const unsigned char *	cert,
		size_t	cert_size,
		const unsigned char *	key,
		size_t	key_size
	)

Add a PKI identity certificate.

Parameters

[in]	device	index of the logical device the identity certificate belongs to
[in]	cert	pointer to a string containing a PEM encoded identity certificate
[in]	cert_size	the size of the `cert` string
[in]	key	the PEM encoded private key associated with this certificate
[in]	key_size	the size of the `key` string

Returns

the credential ID of the /oic/sec/cred entry containing the certificate chain
-1 on failure

◆ oc_pki_add_mfg_cert()

int oc_pki_add_mfg_cert	(	size_t	device,
		const unsigned char *	cert,
		size_t	cert_size,
		const unsigned char *	key,
		size_t	key_size
	)

Add the manufacturer's PKI identity certificate.

Parameters

[in]	device	index of the logical device the identity certificate belongs to
[in]	cert	pointer to a string containing a PEM encoded identity certificate
[in]	cert_size	the size of the `cert` string
[in]	key	the PEM encoded private key associated with this certificate
[in]	key_size	the size of the `key` string

Returns

the credential ID of the /oic/sec/cred entry containing the certificate chain
-1 on failure

◆ oc_pki_add_mfg_intermediate_cert()

int oc_pki_add_mfg_intermediate_cert	(	size_t	device,
		int	credid,
		const unsigned char *	cert,
		size_t	cert_size
	)

Add an intermediate manufacture CA certificate.

Parameters

[in]	device	index of the logical device the certificate chain belongs to
[in]	credid	the credential ID of the /oic/sec/cred entry containing the end-entity certificate
[in]	cert	pointer to a string containing a PEM encoded certificate
[in]	cert_size	the size of the `cert` string

Returns

the credential ID of the /oic/sec/cred entry containing the certificate chain
-1 on failure

◆ oc_pki_add_mfg_trust_anchor()

int oc_pki_add_mfg_trust_anchor	(	size_t	device,
		const unsigned char *	cert,
		size_t	cert_size
	)

Add manufacture trust anchor CA.

Parameters

[in]	device	index of the logical device the trust anchor CA belongs to
[in]	cert	pointer to a string containing a PEM encoded certificate
[in]	cert_size	the size of the `cert` string

Returns

the credential ID of the /oic/sec/cred entry containing the certificate chain
-1 on failure

◆ oc_pki_add_trust_anchor()

int oc_pki_add_trust_anchor	(	size_t	device,
		const unsigned char *	cert,
		size_t	cert_size
	)

Add trust anchor CA.

Parameters

[in]	device	index of the logical device the trust anchor CA belongs to
[in]	cert	pointer to a string containing a PEM encoded certificate
[in]	cert_size	the size of the `cert` strung

Returns

the credential ID of the /oic/sec/cred entry containing the certificate chain
-1 on failure

◆ oc_pki_get_pk_functions()

bool oc_pki_get_pk_functions ( oc_pki_pk_functions_t * pk_functions )

Get the PK functions for the identity certificate or the manufacturer certificate.

Parameters

[out] pk_functions the PK functions

Returns: true if the PK functions have been configured through the oc_pki_set_pk_functions function.

◆ oc_pki_get_verify_certificate_cb()

oc_pki_verify_certificate_cb_t oc_pki_get_verify_certificate_cb ( void )

Get the verification callback for the certificate chain.

Returns: the callback function

◆ oc_pki_set_pk_functions()

bool oc_pki_set_pk_functions ( const oc_pki_pk_functions_t * pk_functions )

Set the PK functions for the identity certificate or the manufacturer certificate.

Parameters

[in] pk_functions the PK functions, if NULL, the default mbedtls functions will be used.

Returns: true if the PK functions have been set.; false when any of the functions is NULL.

◆ oc_pki_set_verify_certificate_cb()

void oc_pki_set_verify_certificate_cb ( oc_pki_verify_certificate_cb_t cb )

Set the verification callback for the certificate chain.

It is invoked after ocf verifies the certificate chain.

Parameters

[in] cb the callback function

Typedefs

Functions

Detailed Description

Typedef Documentation

◆ mbedtls_pk_ecp_gen_key_cb_t

◆ mbedtls_pk_parse_key_cb_t

◆ mbedtls_pk_write_key_der_cb_t

◆ oc_pki_verify_certificate_cb_t

◆ pk_free_key_cb_t

Function Documentation

◆ oc_pki_add_identity_cert()

◆ oc_pki_add_mfg_cert()

◆ oc_pki_add_mfg_intermediate_cert()

◆ oc_pki_add_mfg_trust_anchor()

◆ oc_pki_add_trust_anchor()

◆ oc_pki_get_pk_functions()

◆ oc_pki_get_verify_certificate_cb()

◆ oc_pki_set_pk_functions()

◆ oc_pki_set_verify_certificate_cb()