Keys and Configuration Manager (KCM) APIs. More...

Functions
kcm_status_e	kcm_init (void)
	Initiate the KCM module.
kcm_status_e	kcm_finalize (void)
	Finalize the KCM module.
kcm_status_e	kcm_item_store (const uint8_t kcm_item_name, size_t kcm_item_name_len, kcm_item_type_e kcm_item_type, bool kcm_item_is_factory, const uint8_t kcm_item_data, size_t kcm_item_data_size, const kcm_security_desc_s security_desc)
	Store the KCM item into a secure storage.
kcm_status_e	kcm_item_get_data_size (const uint8_t kcm_item_name, size_t kcm_item_name_len, kcm_item_type_e kcm_item_type, size_t kcm_item_data_size_out)
	Retrieve the KCM item data size from a secure storage.
kcm_status_e	kcm_item_get_data (const uint8_t kcm_item_name, size_t kcm_item_name_len, kcm_item_type_e kcm_item_type, uint8_t kcm_item_data_out, size_t kcm_item_data_max_size, size_t *kcm_item_data_act_size_out)
	Retrieve KCM item data from a secure storage.
kcm_status_e	kcm_item_delete (const uint8_t *kcm_item_name, size_t kcm_item_name_len, kcm_item_type_e kcm_item_type)
	Delete a KCM item from a secure storage.
kcm_status_e	kcm_cert_chain_create (kcm_cert_chain_handle kcm_chain_handle, const uint8_t kcm_chain_name, size_t kcm_chain_name_len, size_t kcm_chain_len, bool kcm_chain_is_factory)
	The API initializes the chain context for the write chain operation.
kcm_status_e	kcm_cert_chain_open (kcm_cert_chain_handle kcm_chain_handle, const uint8_t kcm_chain_name, size_t kcm_chain_name_len, size_t *kcm_chain_len_out)
	The API initializes the chain context for the read chain operation.
kcm_status_e	kcm_cert_chain_add_next (kcm_cert_chain_handle kcm_chain_handle, const uint8_t *kcm_cert_data, size_t kcm_cert_data_size)
	This API adds the next chain of certificates to the storage.
kcm_status_e	kcm_cert_chain_delete (const uint8_t *kcm_chain_name, size_t kcm_chain_name_len)
	The API deletes all certificates of the chain from the storage.
kcm_status_e	kcm_cert_chain_get_next_size (kcm_cert_chain_handle kcm_chain_handle, size_t *kcm_cert_data_size)
	This API returns the size of the next certificate in the chain.
kcm_status_e	kcm_cert_chain_get_next_data (kcm_cert_chain_handle kcm_chain_handle, uint8_t kcm_cert_data, size_t kcm_max_cert_data_size, size_t kcm_actual_cert_data_size)
	This API returns the data of the next certificate in the chain.
kcm_status_e	kcm_cert_chain_close (kcm_cert_chain_handle kcm_chain_handle)
	The API releases the context and frees allocated resources.
kcm_status_e	kcm_factory_reset (void)
	Reset the KCM secure storage to factory state.
kcm_status_e	kcm_key_pair_generate_and_store (const kcm_crypto_key_scheme_e key_scheme, const uint8_t private_key_name, size_t private_key_name_len, const uint8_t public_key_name, size_t public_key_name_len, bool kcm_item_is_factory, const kcm_security_desc_s *kcm_params)
	Generate a key pair complying the given cryptographic scheme in DER format.
kcm_status_e	kcm_csr_generate (const uint8_t private_key_name, size_t private_key_name_len, const kcm_csr_params_s csr_params, uint8_t csr_buff_out, size_t csr_buff_max_size, size_t csr_buff_act_size)
	Generate a general CSR from the given private key.
kcm_status_e	kcm_generate_keys_and_csr (kcm_crypto_key_scheme_e key_scheme, const uint8_t private_key_name, size_t private_key_name_len, const uint8_t public_key_name, size_t public_key_name_len, bool kcm_item_is_factory, const kcm_csr_params_s csr_params, uint8_t csr_buff_out, size_t csr_buff_max_size, size_t csr_buff_act_size_out, const kcm_security_desc_s kcm_params)
	Generate private and public key and CSR from the generated keys.
kcm_status_e	kcm_certificate_verify_with_private_key (const uint8_t kcm_cert_data, size_t kcm_cert_data_size, const uint8_t kcm_priv_key_name, size_t kcm_priv_key_name_len)
	Verify the device-generated certificate against the given private key name from storage.

Detailed Description

Keys and Configuration Manager (KCM) APIs.

Definition in file key_config_manager.h.

Function Documentation

kcm_status_e kcm_cert_chain_add_next	(	kcm_cert_chain_handle	kcm_chain_handle,
		const uint8_t *	kcm_cert_data,
		size_t	kcm_cert_data_size
	)

This API adds the next chain of certificates to the storage.

It also validates the previous certificate (unless it is the first certificate) with the public key from `kcm_cert_data`. The certificates should be added in the order from lowest child, followed by the certificate that signs it and so on, all the way to the root of the chain.

Parameters:

[in]	kcm_chain_handle	The certificate chain handle.
[in]	kcm_cert_data	A pointer to the certificate data in DER format.
[in]	kcm_cert_data_size	The size of the certificate data buffer.

Returns:: KCM_STATUS_SUCCESS in case of success. KCM_STATUS_CERTIFICATE_CHAIN_VERIFICATION_FAILED if one of the certificates in the chain failed to verify its predecessor. In other cases, one of the `kcm_status_e` errors.

Definition at line 231 of file key_config_manager.c.

kcm_status_e kcm_cert_chain_close ( kcm_cert_chain_handle kcm_chain_handle )

The API releases the context and frees allocated resources.

When the operation type is creation and if the total number of added/stored certificates is not equal to the number of certificates in the chain, the API returns an error.

Parameters:

[in] kcm_chain_handle The certificate chain handle.

Returns:: KCM_STATUS_SUCCESS in success. KCM_STATUS_CLOSE_INCOMPLETE_CHAIN if all certificates were not saved. In this case the chain will be deleted. Otherwise, one of the `kcm_status_e` errors.

Definition at line 319 of file key_config_manager.c.

kcm_status_e kcm_cert_chain_create	(	kcm_cert_chain_handle *	kcm_chain_handle,
		const uint8_t *	kcm_chain_name,
		size_t	kcm_chain_name_len,
		size_t	kcm_chain_len,
		bool	kcm_chain_is_factory
	)

The API initializes the chain context for the write chain operation.

It should be called before `kcm_cert_chain_add_next` API.

Parameters:

[out]	kcm_chain_handle	A pointer to the certificate chain handle.
[in]	kcm_chain_name	A pointer to the certificate chain name.
[in]	kcm_chain_name_len	The length of the certificate name buffer.
[in]	kcm_chain_len	The number of certificates in the chain.
[in]	kcm_chain_is_factory	True if the KCM chain is a factory item, otherwise false.

Returns:: KCM_STATUS_SUCCESS in case of success or one of the `kcm_status_e` errors otherwise.

Definition at line 198 of file key_config_manager.c.

kcm_status_e kcm_cert_chain_delete	(	const uint8_t *	kcm_chain_name,
		size_t	kcm_chain_name_len
	)

The API deletes all certificates of the chain from the storage.

In case of invalid chain the API deletes all reachable certificates and return relevant error for indication.

Parameters:

[in]	kcm_chain_name	A pointer to certificate chain name.
[in]	kcm_chain_name_len	The length of certificate chain name.

Returns:: KCM_STATUS_SUCCESS in success or one of the `kcm_status_e` errors otherwise.

Definition at line 284 of file key_config_manager.c.

kcm_status_e kcm_cert_chain_get_next_data	(	kcm_cert_chain_handle	kcm_chain_handle,
		uint8_t *	kcm_cert_data,
		size_t	kcm_max_cert_data_size,
		size_t *	kcm_actual_cert_data_size
	)

This API returns the data of the next certificate in the chain.

To get the exact size of the next certificate, use `kcm_cert_chain_get_next_size`. In the end of the get data operation, the chain context points to the next certificate of the current chain.

Parameters:

[in]	kcm_chain_handle	The certificate chain handle.
	in/out]	kcm_cert_data A pointer to the certificate data in DER format.
[in]	kcm_max_cert_data_size	The max size of the certificate data buffer.
[out]	kcm_actual_cert_data_size	The actual size of the certificate data.

Returns:: KCM_STATUS_SUCCESS in success. KCM_STATUS_INVALID_NUM_OF_CERT_IN_CHAIN if the end of the chain was reached. Otherwise, one of the `kcm_status_e` errors.

Definition at line 307 of file key_config_manager.c.

kcm_status_e kcm_cert_chain_get_next_size	(	kcm_cert_chain_handle	kcm_chain_handle,
		size_t *	kcm_cert_data_size
	)

This API returns the size of the next certificate in the chain.

It should be called before `kcm_cert_chain_get_next_data`. This operation does not increase the chain's context iterator.

Parameters:

[in]	kcm_chain_handle	The certificate chain handle.
[out]	kcm_cert_data_size	The pointer size of the next certificate.

Returns:: KCM_STATUS_SUCCESS in success. KCM_STATUS_INVALID_NUM_OF_CERT_IN_CHAIN if the end of the chain was reached. Otherwise, one of the `kcm_status_e` errors.

Definition at line 296 of file key_config_manager.c.

kcm_status_e kcm_cert_chain_open	(	kcm_cert_chain_handle *	kcm_chain_handle,
		const uint8_t *	kcm_chain_name,
		size_t	kcm_chain_name_len,
		size_t *	kcm_chain_len_out
	)

The API initializes the chain context for the read chain operation.

This API should be called before `kcm_cert_chain_get_next_size` and `kcm_cert_chain_get_next_data` APIs.

Parameters:

[out]	kcm_chain_handle	A pointer to the certificate chain handle.
[in]	kcm_chain_name	A pointer to the certificate chain name.
[in]	kcm_chain_name_len	The size of the certificate name buffer.
[out]	kcm_chain_len	The length of the certificate chain.

Returns:: KCM_STATUS_SUCCESS in case of success or one of the `kcm_status_e` errors otherwise.

Definition at line 209 of file key_config_manager.c.

kcm_status_e kcm_certificate_verify_with_private_key	(	const uint8_t *	kcm_cert_data,
		size_t	kcm_cert_data_size,
		const uint8_t *	kcm_priv_key_name,
		size_t	kcm_priv_key_name_len
	)

Verify the device-generated certificate against the given private key name from storage.

This function can be called when the certificate creation is initiated by the device using `kcm_generate_keys_and_csr` or `kcm_csr_generate` functions. In this case, the function checks the correlation between certificate's public key and given private key generated by the device and saved in device storage.

Parameters:

[in]	kcm_cert_data	The DER certificate data buffer.
[in]	kcm_cert_data_size	The size of the DER certificate data buffer in bytes.
[in]	kcm_priv_key_name	The private key name of the certificate. The function assumes that the key was generated by the device and saved in the storage.
[in]	kcm_priv_key_name_len	The length of the private key name of the certificate.

Returns:: KCM_STATUS_SUCCESS in case of success. KCM_STATUS_ITEM_NOT_FOUND if the private key was not found in the storage. Otherwise, one of the `kcm_status_e` errors.

Definition at line 540 of file key_config_manager.c.

kcm_status_e kcm_csr_generate	(	const uint8_t *	private_key_name,
		size_t	private_key_name_len,
		const kcm_csr_params_s *	csr_params,
		uint8_t *	csr_buff_out,
		size_t	csr_buff_max_size,
		size_t *	csr_buff_act_size
	)

Generate a general CSR from the given private key.

Parameters:

private_key_name	The private key name to fetch from storage.
private_key_name_len	The length of the private key name.
csr_params	CSR parameters.
csr_buff_out	A pointer to the generated CSR buffer to fill.
csr_buff_max_size	The size of the supplied CSR buffer.
csr_buff_act_size	The actual size of the filled CSR buffer.

Returns:: KCM_STATUS_SUCCESS in success. Otherwise, one of the `kcm_status_e` errors.

Definition at line 403 of file key_config_manager.c.

kcm_status_e kcm_factory_reset ( void )

Reset the KCM secure storage to factory state.

Returns:: KCM_STATUS_SUCCESS in success. Otherwise, one of the `kcm_status_e` errors.

Definition at line 178 of file key_config_manager.c.

kcm_status_e kcm_finalize ( void )

Finalize the KCM module.

Finalizes and frees file storage resources.

Returns:: KCM_STATUS_SUCCESS in case of success or one of the `kcm_status_e` errors otherwise.

Definition at line 69 of file key_config_manager.c.

kcm_status_e kcm_generate_keys_and_csr	(	kcm_crypto_key_scheme_e	key_scheme,
		const uint8_t *	private_key_name,
		size_t	private_key_name_len,
		const uint8_t *	public_key_name,
		size_t	public_key_name_len,
		bool	kcm_item_is_factory,
		const kcm_csr_params_s *	csr_params,
		uint8_t *	csr_buff_out,
		size_t	csr_buff_max_size,
		size_t *	csr_buff_act_size_out,
		const kcm_security_desc_s *	kcm_params
	)

Generate private and public key and CSR from the generated keys.

Parameters:

key_scheme	The cryptographic scheme.
private_key_name	The private key name to generate.
private_key_name_len	The length of the private key name.
public_key_name	The public key name for which a key pair is generated. This parameter is optional. If not provided, the key will be generated, but not stored.
public_key_name_len	The length of the public key name. Must be 0, if `public_key_name` is not provided.
kcm_item_is_factory	True if the KCM item is a factory item, otherwise false.
csr_params	CSR parameters.
csr_buff_out	A pointer to the generated CSR buffer to fill.
csr_buff_max_size	The size of the supplied CSR buffer.
csr_buff_act_size	The actual size of the filled CSR buffer.
kcm_data_pkcm_params	Additional `kcm_params`. Currently void.

Returns:: KCM_STATUS_SUCCESS in success. Otherwise, one of the `kcm_status_e` errors.

Definition at line 457 of file key_config_manager.c.

kcm_status_e kcm_init ( void )

Initiate the KCM module.

Allocates and initializes file storage resources.

Returns:: KCM_STATUS_SUCCESS in case of success or one of the `kcm_status_e` errors otherwise.

Definition at line 32 of file key_config_manager.c.

kcm_status_e kcm_item_delete	(	const uint8_t *	kcm_item_name,
		size_t	kcm_item_name_len,
		kcm_item_type_e	kcm_item_type
	)

Delete a KCM item from a secure storage.

Parameters:

[in]	kcm_item_name	KCM item name.
[in]	kcm_item_name_len	KCM item name length.
[in]	kcm_item_type	KCM item type as defined in `kcm_item_type_e`

Returns:: KCM_STATUS_SUCCESS status in case of success or one of kcm_status_e errors otherwise.

Definition at line 168 of file key_config_manager.c.

kcm_status_e kcm_item_get_data	(	const uint8_t *	kcm_item_name,
		size_t	kcm_item_name_len,
		kcm_item_type_e	kcm_item_type,
		uint8_t *	kcm_item_data_out,
		size_t	kcm_item_data_max_size,
		size_t *	kcm_item_data_act_size_out
	)

Retrieve KCM item data from a secure storage.

Parameters:

[in]	kcm_item_name	KCM item name.
[in]	kcm_item_name_len	KCM item name length.
[in]	kcm_item_type	KCM item type as defined in `kcm_item_type_e`
[out]	kcm_item_data_out	KCM item data output buffer. Can be NULL if `kcm_item_data_size` is 0.
[in]	kcm_item_data_max_size	The maximum size of the KCM item data output buffer in bytes.
[out]	kcm_item_data_act_size_out	Actual KCM item data output buffer size in bytes.

Returns:: KCM_STATUS_SUCCESS in case of success or one of the `kcm_status_e` errors otherwise.

Definition at line 155 of file key_config_manager.c.

kcm_status_e kcm_item_get_data_size	(	const uint8_t *	kcm_item_name,
		size_t	kcm_item_name_len,
		kcm_item_type_e	kcm_item_type,
		size_t *	kcm_item_data_size_out
	)

Retrieve the KCM item data size from a secure storage.

Parameters:

[in]	kcm_item_name	KCM item name.
[in]	kcm_item_name_len	KCM item name length.
[in]	kcm_item_type	KCM item type as defined in `kcm_item_type_e`
[out]	kcm_item_data_size_out	KCM item data size in bytes.

Returns:: KCM_STATUS_SUCCESS in case of success or one of the `kcm_status_e` errors otherwise.

Definition at line 142 of file key_config_manager.c.

kcm_status_e kcm_item_store	(	const uint8_t *	kcm_item_name,
		size_t	kcm_item_name_len,
		kcm_item_type_e	kcm_item_type,
		bool	kcm_item_is_factory,
		const uint8_t *	kcm_item_data,
		size_t	kcm_item_data_size,
		const kcm_security_desc_s	security_desc
	)

Store the KCM item into a secure storage.

Item name restrictions (the kcm_item_name argument): If you are using Mbed OS 5.11 or higher with the built-in secure storage (KVStore), or your own secure storage (ported to the Pelion client), kcm_item_name must only include the following characters: 'a'-'z', 'A'-'Z', '0'-'9', '_', '-', '.'. If you are using the Pelion client secure storage (SOTP and ESFS), KCM file names have no character restrictions. Note that this feature will be deprecated in the future and the same character restriction will apply ('a'-'z', 'A'-'Z', '0'-'9', '_', '-', '.').

Parameters:

[in]	kcm_item_name	KCM item name. See comment above.
[in]	kcm_item_name_len	KCM item name length. kcm_item_name_len must be at most KCM_MAX_FILENAME_SIZE bytes.
[in]	kcm_item_type	KCM item type as defined in `kcm_item_type_e`
[in]	kcm_item_is_factory	True if the KCM item is a factory item, otherwise false.
[in]	kcm_item_data	KCM item data buffer. Can be NULL if `kcm_item_data_size` is 0.
[in]	kcm_item_data_size	KCM item data buffer size in bytes. Can be 0 if you wish to store an empty file.
[in]	security_desc	Security descriptor.

Returns:: KCM_STATUS_SUCCESS in success. KCM_STATUS_FILE_EXIST if trying to store an item that already exists. KCM_STATUS_FILE_NAME_TOO_LONG if kcm_item_name_len is too long. KCM_STATUS_FILE_NAME_INVALID if kcm_item_name contains illegal characters. One of the `kcm_status_e` errors otherwise.

Definition at line 94 of file key_config_manager.c.

kcm_status_e kcm_key_pair_generate_and_store	(	const kcm_crypto_key_scheme_e	key_scheme,
		const uint8_t *	private_key_name,
		size_t	private_key_name_len,
		const uint8_t *	public_key_name,
		size_t	public_key_name_len,
		bool	kcm_item_is_factory,
		const kcm_security_desc_s *	kcm_params
	)

Generate a key pair complying the given cryptographic scheme in DER format.

Saves the private and public key if provided.

Parameters:

key_scheme	The cryptographic scheme.
private_key_name	The private key name for which a key pair is generated.
private_key_name_len	The length of the private key name.
public_key_name	The public key name for which a key pair is generated. This parameter is optional. If not provided, the key will be generated, but not stored.
public_key_name_len	The length of the public key name. Must be 0, if `public_key_name` not provided.
kcm_item_is_factory	True if the KCM item is a factory item, otherwise false.
kcm_params	Additional `kcm_params`. Currently void.

Returns:: KCM_STATUS_SUCCESS in success. Otherwise, one of the `kcm_status_e` errors.

Definition at line 331 of file key_config_manager.c.

Type:	Program
Mbed OS support:	Mbed OS
Created:	19 Nov 2019
Imports:	1
Forks:	0
Commits:	1
Dependents:	0
Dependencies:	2
Followers:	1

Important changes to repositories hosted on mbed.com

key_config_manager.h File Reference

Functions

Detailed Description

Function Documentation

Repository toolbox

Repository details

Important Information for this Arm website

Important changes to repositories hosted on mbed.com

key_config_manager.h File Reference

Functions

Detailed Description

Function Documentation

Repository toolbox

Repository details

Important Information for this Arm website

Access Warning