Crypto Service Manager

Detailed Description

Defines APIs for managing Trusted Little Kernel (TLK) crypto services.

Modules
	Crypto Services

Macros
#define	KEYSLOT_TYPE_AES   0
#define	KEYSLOT_TYPE_RSA   1
#define	MAX_HWRANDOM_SIZE   4096

Enumerations
enum	{   KEYSLOT_RICH_OS_NO_READ_NO_WRITE_KEY_ACCESSIBLE = 0,   KEYSLOT_CONFIG_ALL }
enum	keystore_lookup_type {   KEYSTORE_LOOKUP_ABSOLUTE = 1,   KEYSTORE_LOOKUP_RELATIVE,   KEYSTORE_LOOKUP_BY_ID }
enum	keybox_attr_type { KEYBOX_ATTR_SIZE = 1 }

Functions
te_error_t	ote_nvcrypto_init (void)
	Initializes and opens an nvcrypto service session. More...
te_error_t	ote_nvcrypto_deinit (void)
	Closes an nvcrypto service session. More...
te_error_t	ote_nvcrypto_get_keybox (uint32_t keybox_lookup_index, keystore_lookup_type lookup_type, void *buf, uint32_t *len)
	Gets the key box provisioned in the EKS partition. More...
te_error_t	ote_nvcrypto_get_keybox_size (uint32_t keybox_lookup_index, keystore_lookup_type lookup_type, uint32_t *len)
	Gets the size of the key box provisioned in the EKS partition. More...
te_error_t	ote_nvcrypto_get_storage_key (uint8_t *key, uint32_t key_size)
	Gets the storage key. More...
te_error_t	ote_nvcrypto_get_rollback_key (uint8_t *key, uint32_t key_size)
	Gets the rollback key. More...
te_error_t	ote_nvcrypto_get_ro_trust_key (uint8_t *key, uint32_t key_size)
	Gets the key derived from the root of trust. More...
te_error_t	ote_nvcrypto_get_random (uint8_t *buf, uint32_t buf_len)
	Gets SE HW random number generated data. More...
te_error_t	ote_nvcrypto_get_wv_rsa_sig_key (uint8_t *key, uint32_t *key_size)
	Gets the wv rsa sig key. More...
te_error_t	ote_nvcrypto_get_gs_key (uint8_t *key, uint32_t *key_size)
	Gets the vrr auth key. More...
te_error_t	ote_nvcrypto_get_key (uint8_t *key, uint32_t key_size, uint32_t key_type)
	Gets the storage/rollback key. More...
te_error_t	ote_nvcrypto_derive_key (const uint8_t *src_buffer, const uint32_t src_buf_len, uint8_t *dest)
	Generates a unique encryption key by performing crypto operations on the src_buffer a predefined initial vector IV and a secure storage key. More...
te_error_t	ote_nvcrypto_get_widevine_key (uint8_t *key, uint32_t key_size)
	Gets the Widevine Device Unique key. More...
te_error_t	ote_nvcrypto_update_se_keyslot (uint32_t KeySlotType, uint32_t KeySlotIdx, uint32_t access_control, const uint32_t *pData, uint32_t pData_len)
	Updates the HW security engine AES/RSA keyslots with an input Key. More...
te_error_t	ote_nvcrypto_rsa_raw_private_encrypt (uint8_t *pri_key, uint32_t pri_key_len, uint32_t *data_in, uint32_t data_in_len, uint8_t *signedData, uint32_t signed_data_len)
	Interface sign a data blob with a RSA key with no data padding. More...
te_error_t	ote_nvcrypto_do_crypt_functions (uint32_t algo, uint32_t mode, uint8_t *inbuf, uint32_t inbuf_len, uint8_t *iv, uint32_t iv_len, uint8_t *key, uint32_t key_len, uint8_t *outbuf, uint32_t *outbuf_len)
	Interface for crypto operations such as AES, SHA, and RSA using openssl library. More...
te_error_t	ote_nvcrypto_get_eks2_mac_key (uint8_t *key, uint32_t *key_size)
	Gets the EKS2 mac key, which is used to validate integrity of the EKS2 blob coming from the non-secure world. More...
te_error_t	ote_nvcrypto_install_eks2_keys (const uint8_t *buf, uint32_t buf_len, uint32_t num_keys)
	Installs EKS2 keys in NVCrypto key slots. More...

Macro Definition Documentation

#define KEYSLOT_TYPE_AES   0

Definition at line 80 of file ote_nvcrypto.h.

#define KEYSLOT_TYPE_RSA   1

Definition at line 81 of file ote_nvcrypto.h.

#define MAX_HWRANDOM_SIZE   4096

Definition at line 200 of file ote_nvcrypto.h.

Enumeration Type Documentation

anonymous enum

Enumerator
KEYSLOT_RICH_OS_NO_READ_NO_WRITE_KEY_ACCESSIBLE
KEYSLOT_CONFIG_ALL

Definition at line 84 of file ote_nvcrypto.h.

enum keybox_attr_type

Enumerator
KEYBOX_ATTR_SIZE

Definition at line 116 of file ote_nvcrypto.h.

enum keystore_lookup_type

Enumerator
KEYSTORE_LOOKUP_ABSOLUTE
KEYSTORE_LOOKUP_RELATIVE
KEYSTORE_LOOKUP_BY_ID

Definition at line 105 of file ote_nvcrypto.h.

Function Documentation

te_error_t ote_nvcrypto_deinit

(

void

)

Closes an nvcrypto service session.

Returns

OTE_SUCCESS to indicate that the operation was successful.

te_error_t ote_nvcrypto_derive_key	(	const uint8_t *	src_buffer,
		const uint32_t	src_buf_len,
		uint8_t *	dest
	)

Generates a unique encryption key by performing crypto operations on the src_buffer a predefined initial vector IV and a secure storage key.

Parameters

[in]	src_buffer	A pointer to the input data buffer.
[in]	src_buf_len	Length of input buffer, it must be a multiple of 16.
[out]	dest	A pointer to an output buffer. The length of the dest buffer must match the length of the src_buffer.

Return values

OTE_SUCCESS	The operation was successful.
OTE_ERROR_BAD_STATE	The nvcrypto session was not open.
OTE_ERROR_BAD_PARAMS	A dest or src_buffer was empty, or src_buf_len was not a multiple of 16.

te_error_t ote_nvcrypto_do_crypt_functions	(	uint32_t	algo,
		uint32_t	mode,
		uint8_t *	inbuf,
		uint32_t	inbuf_len,
		uint8_t *	iv,
		uint32_t	iv_len,
		uint8_t *	key,
		uint32_t	key_len,
		uint8_t *	outbuf,
		uint32_t *	outbuf_len
	)

Interface for crypto operations such as AES, SHA, and RSA using openssl library.

Parameters

[in]	algo	Algorithm to use (AES, SHA, or RSA).
[in]	mode	Mode in which the algorithm is called (SHA1, SHA256, etc...).
[in]	inbuf	Input buffer.
[in]	inbuf_len	Length of input buffer in bytes.
[in]	iv	Initial buffer (IV).
[in]	iv_len	Length of initial buffer in bytes.
[in]	key	Key buffer.
[in]	key_len	Length of key buffer in bytes.
[out]	outbuf	Output buffer.
[in,out]	outbuf_len	Length of output buffer in bytes.

Return values

OTE_SUCCESS

The operation was successful

te_error_t ote_nvcrypto_get_eks2_mac_key	(	uint8_t *	key,
		uint32_t *	key_size
	)

Gets the EKS2 mac key, which is used to validate integrity of the EKS2 blob coming from the non-secure world.

Return values

OTE_SUCCESS

The operation was successful.

Parameters

[out]	key	A pointer to the key.
[out]	key_size	A pointer to the length of the key in bytes.

te_error_t ote_nvcrypto_get_gs_key	(	uint8_t *	key,
		uint32_t *	key_size
	)

Gets the vrr auth key.

Return values

OTE_SUCCESS

The operation was successful.

Parameters

[in,out]	key	A pointer to the key.
[in,out]	key_size	A pointer to the length of the key in bytes.

te_error_t ote_nvcrypto_get_key	(	uint8_t *	key,
		uint32_t	key_size,
		uint32_t	key_type
	)

Gets the storage/rollback key.

It helps in getting 2 key types STORAGE_MASTER_KEY - used as a key to sign log, meta data files ROLLBACK_KEY - used as a key to sign data written to RPMB device.

Return values

OTE_SUCCESS

The operation was successful.

Parameters

[in,out]	key	A pointer to the key.
[in]	key_size	The length of the key in bytes.
[in]	key_type	The storage key operation. Supported values are: CRYPTO_SERVICE_GET_STORAGE_MASTER_KEY CRYPTO_SERVICE_GET_ROLLBACK_KEY

Return values

OTE_SUCCESS	Indicates the operation was successful.
OTE_ERROR_BAD_STATE	The nvcrypto session was not open.
OTE_ERROR_BAD_PARAMS	key was empty.

te_error_t ote_nvcrypto_get_keybox	(	uint32_t	keybox_lookup_index,
		keystore_lookup_type	lookup_type,
		void *	buf,
		uint32_t *	len
	)

Gets the key box provisioned in the EKS partition.

A TA calls this function to import its keybox from the EKS partition.

Parameters

[in]	keybox_lookup_index	The index of the keybox.
[in]	lookup_type	The type of lookup requested.
[in,out]	buf	A pointer to the key.
[in,out]	len	A pointer to the length of the buffer in bytes.

Return values

OTE_SUCCESS	The operation was successful.
OTE_BAD_STATE	The nvcrypto session was not open.
OTE_ERROR_BAD_PARAMS	buf was empty.

te_error_t ote_nvcrypto_get_keybox_size	(	uint32_t	keybox_lookup_index,
		keystore_lookup_type	lookup_type,
		uint32_t *	len
	)

Gets the size of the key box provisioned in the EKS partition.

Parameters

[in]	keybox_lookup_index	The index of the keybox.
[in]	lookup_type	The type of lookup requested.
[out]	len	A pointer to the size of the keybox in bytes.

Return values

OTE_SUCCESS	The operation was successful.
OTE_BAD_STATE	The nvcrypto session was not open.
OTE_ERROR_BAD_PARAMS	len was empty.

te_error_t ote_nvcrypto_get_random	(	uint8_t *	buf,
		uint32_t	buf_len
	)

Gets SE HW random number generated data.

Parameters

[in,out]	buf	A pointer to the result buffer.
[in]	buf_len	Number of bytes requested from nvcrypto, up to the maximum size supported.

te_error_t ote_nvcrypto_get_ro_trust_key	(	uint8_t *	key,
		uint32_t	key_size
	)

Gets the key derived from the root of trust.

Parameters

[out]	key	A pointer to the key.
[in]	key_size	The length of the key in bytes.

Return values

OTE_SUCCESS

The operation was successful.

te_error_t ote_nvcrypto_get_rollback_key	(	uint8_t *	key,
		uint32_t	key_size
	)

Gets the rollback key.

Return values

OTE_SUCCESS

The operation was successful.

Parameters

[out]	key	A pointer to the key.
[in]	key_size	The length of the key in bytes.

te_error_t ote_nvcrypto_get_storage_key	(	uint8_t *	key,
		uint32_t	key_size
	)

Gets the storage key.

Return values

OTE_SUCCESS

The operation was successful.

Parameters

[in,out]	key	A pointer to the key.
[in]	key_size	The length of the key in bytes.

te_error_t ote_nvcrypto_get_widevine_key	(	uint8_t *	key,
		uint32_t	key_size
	)

Gets the Widevine Device Unique key.

Return values

OTE_SUCCESS

Indicates the operation was successful.

Parameters

[out]	key	A pointer to the key.
[in,out]	key_size	The length of the key in bytes.

te_error_t ote_nvcrypto_get_wv_rsa_sig_key	(	uint8_t *	key,
		uint32_t *	key_size
	)

Gets the wv rsa sig key.

Return values

OTE_SUCCESS

The operation was successful.

Parameters

[in,out]	key	A pointer to the key.
[in,out]	key_size	A pointer to the length of the key in bytes.

te_error_t ote_nvcrypto_init

(

void

)

Initializes and opens an nvcrypto service session.

This function keeps track of the number of open sessions.

The ote_nvcrypto* functions provide an interface to the crypto_service.

To use the crypto_service through this interface:

1. Initialize the service with ote_nvcrypto_init()
2. Call the necessary operation such as ote_nvcrypto_get_keybox() or ote_nvcrypto_get_key().
3. Un-initalize the service with ote_nvcrypto_deinit().

Return values

OTE_SUCCESS

The operation was successful.

te_error_t ote_nvcrypto_install_eks2_keys	(	const uint8_t *	buf,
		uint32_t	buf_len,
		uint32_t	num_keys
	)

Installs EKS2 keys in NVCrypto key slots.

Parameters

[in]	buf	A pointer to the buffer with EKS2 keys.
[in]	buf_len	Length of the buffer.
[in]	num_keys	Number of keys in the buffer.

Return values

OTE_SUCCESS

The operation was successful.

te_error_t ote_nvcrypto_rsa_raw_private_encrypt	(	uint8_t *	pri_key,
		uint32_t	pri_key_len,
		uint32_t *	data_in,
		uint32_t	data_in_len,
		uint8_t *	signedData,
		uint32_t	signed_data_len
	)

Interface sign a data blob with a RSA key with no data padding.

Calls the following openssl API with padding = RSA_NO_PADDING. All clients need to ensure their data is padded securely such that the datasize matches the RSA exponent size. https://www.openssl.org/docs/manmaster/crypto/RSA_private_encrypt.html

Parameters

[in]	pri_key	Private RSA key in DER format with which to sign the data.
[in]	pri_key_len	Length of the RSA key in bytes.
[in]	data_in	Input buffer.
[in]	data_in_len	Length of the input buffer in bytes.
[out]	signedData	Output buffer.
[out]	signed_data_len	Length of output buffer in bytes.

Return values

OTE_SUCCESS

The operation was successful

te_error_t ote_nvcrypto_update_se_keyslot	(	uint32_t	KeySlotType,
		uint32_t	KeySlotIdx,
		uint32_t	access_control,
		const uint32_t *	pData,
		uint32_t	pData_len
	)

Updates the HW security engine AES/RSA keyslots with an input Key.

Parameters

[in]	KeySlotType	Keyslot type, AES or RSA.
[in]	KeySlotIdx	Index of the key to be updated.
[in]	access_control	Permissions to be set for this keyslot.
[in]	pData	A pointer to the key data bytes.
[in]	pData_len	Length of the key data.

Return values

OTE_SUCCESS

The operation was successful.