IoTivity-Lite
oc_pki.h File Reference

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/platform_time.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
deviceThe device index the key belongs to.
grp_idThe ECP group identifier.
pkThe destination key. The key is initialized by MBEDTLS_PK_ECKEY.
f_rngThe RNG function to use. This must not be NULL.
p_rngThe 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
deviceThe device index the key belongs to.
pkThe PK context to fill. It must have been initialized but not set up.
keyInput 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).
keylenSize of key in bytes. For PEM data, this includes the terminating null byte, so keylen must be equal to strlen(key) + 1.
pwdOptional 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.
pwdlenSize of the password in bytes. Ignored if pwd is NULL.
f_rngRNG function, must not be NULL. Used for blinding.
p_rngRNG 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
deviceThe device index the key belongs to.
ctxPK context which must contain a valid private key.
bufbuffer to write to
sizesize 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
peerTLS peer connection
crtCertificate
depthDepth of the certificate chain, 0 is the leaf certificate.
flagsVerification 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
deviceThe device index the key belongs to.
keyThe private key to free.
keylenThe 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]deviceindex of the logical device the identity certificate belongs to
[in]certpointer to a string containing a PEM encoded identity certificate
[in]cert_sizethe size of the cert string
[in]keythe PEM encoded private key associated with this certificate
[in]key_sizethe 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]deviceindex of the logical device the identity certificate belongs to
[in]certpointer to a string containing a PEM encoded identity certificate
[in]cert_sizethe size of the cert string
[in]keythe PEM encoded private key associated with this certificate
[in]key_sizethe 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]deviceindex of the logical device the certificate chain belongs to
[in]credidthe credential ID of the /oic/sec/cred entry containing the end-entity certificate
[in]certpointer to a string containing a PEM encoded certificate
[in]cert_sizethe 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]deviceindex of the logical device the trust anchor CA belongs to
[in]certpointer to a string containing a PEM encoded certificate
[in]cert_sizethe 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]deviceindex of the logical device the trust anchor CA belongs to
[in]certpointer to a string containing a PEM encoded certificate
[in]cert_sizethe 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_functionsthe 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_functionsthe 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]cbthe callback function