Detailed Description

The CryptoKey type is an opaque representation of a cryptographic key.

============================================================================

Warning: This is a beta API. It may change in future releases.

Cryptographic keying material may be stored on an embedded system multiple ways.

plaintext: in plaintext in flash or RAM
keyblob: in encrypted form in flash or RAM
key store: in a dedicated hardware database whose entries can not be directly read out.

Each storage option requires different approaches to handling the keying material when performing a crypto operation. In order to separate these concerns from the API of the various crypto drivers available with TI-RTOS, the CryptoKey type abstracts away from these details. It does not contain any cryptographic keying material itself but instead contains the details necessary for drivers to use the keying material. The driver implementation handles preparing and moving the keying material as necessary to perform the desired crypto operation.

The same CryptoKey may be passed to crypto APIs of different modes subject to restrictions placed on the key by their storage types. Plaintext keys may be used without restriction while key store and keyblob keys have their permitted uses restricted when the keying material is loaded or the keyblob is encrypted respectively. These restrictions are specified in a CryptoKey_SecurityPolicy that is device-specific and depends on the hardware capability of the device.

An application should never access a field within a CryptoKey struct itself. Where needed, helper functions are provided to do so.

Before using a CryptoKey in another crypto API call, it must be initialized with a call to one of the initialization functions.

CryptoKeyPlaintext_initKey()
CryptoKeyPlaintext_initBlankKey()
CryptoKeyKeyStore_initKey()
CryptoKeyKeyStore_initBlankKey()
CryptoKeyKeyBlob_initKey()
CryptoKeyKeyBlob_initBlankKey()

The keyblob and keystore CryptoKeys may be used to create a keyblob or load a key into a key store after their respective _init call.

CryptoKeys can be initialized "blank", without keying material but with an empty buffer or key store entry, to encode the destination of a key to be created in the future. This way, keys may be generated securely within a key store for example and never even be stored in RAM temporarily.

Not all devices support all CryptoKey functionality. This is hardware-dependent.

#include <stdint.h>
#include <stdbool.h>

Include dependency graph for CryptoKey.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	CryptoKey_Plaintext_
	Plaintext CryptoKey datastructure. More...

struct	CryptoKey_KeyStore_
	Key store CryptoKey datastructure. More...

struct	CryptoKey_KeyBlob_
	Keyblob CryptoKey datastructure. More...

struct	CryptoKey_
	CryptoKey datastructure. More...

Macros
#define	CryptoKey_STATUS_RESERVED (-32)

#define	CryptoKey_STATUS_SUCCESS (0)
	Successful status code. More...

#define	CryptoKey_STATUS_ERROR (-1)
	Generic error status code. More...

#define	CryptoKey_STATUS_UNDEFINED_ENCODING (-2)
	Returned if the encoding of a CryptoKey is not a CryptoKey_Encoding value. More...

Typedefs
typedef enum CryptoKey_Encoding_	CryptoKey_Encoding
	List of the different types of CryptoKey. More...

typedef struct CryptoKey_Plaintext_	CryptoKey_Plaintext
	Plaintext CryptoKey datastructure. More...

typedef struct CryptoKey_KeyStore_	CryptoKey_KeyStore
	Key store CryptoKey datastructure. More...

typedef struct CryptoKey_KeyBlob_	CryptoKey_KeyBlob
	Keyblob CryptoKey datastructure. More...

typedef struct CryptoKey_	CryptoKey
	CryptoKey datastructure. More...

typedef struct CryptoKey_SecurityPolicy_	CryptoKey_SecurityPolicy
	Structure that specifies the restrictions on a CryptoKey. More...

Enumerations
enum	CryptoKey_Encoding_ { CryptoKey_PLAINTEXT = 1 << 1, CryptoKey_BLANK_PLAINTEXT = 1 << 2, CryptoKey_KEYSTORE = 1 << 3, CryptoKey_BLANK_KEYSTORE = 1 << 4, CryptoKey_KEYBLOB = 1 << 5, CryptoKey_BLANK_KEYBLOB = 1 << 6 }
	List of the different types of CryptoKey. More...

Functions
int_fast16_t	CryptoKey_getCryptoKeyType (CryptoKey keyHandle, CryptoKey_Encoding keyType)
	Gets the key type of the CryptoKey. More...

int_fast16_t	CryptoKey_isBlank (CryptoKey keyHandle, bool isBlank)
	Wheather the CryptoKey is 'blank' or represents valid keying material. More...

int_fast16_t	CryptoKey_markAsBlank (CryptoKey *keyHandle)
	Marks a CryptoKey as 'blank'. More...

int_fast16_t	CryptoKey_initSecurityPolicy (CryptoKey_SecurityPolicy *policy)
	Function to initialize the CryptoKey_SecurityPolicy struct to its defaults. More...

Typedef Documentation

§ CryptoKey_Encoding

typedef enum CryptoKey_Encoding_ CryptoKey_Encoding

List of the different types of CryptoKey.

§ CryptoKey_Plaintext

typedef struct CryptoKey_Plaintext_ CryptoKey_Plaintext

Plaintext CryptoKey datastructure.

This structure contains all the information necessary to access keying material stored in plaintext form in flash or RAM.

§ CryptoKey_KeyStore

typedef struct CryptoKey_KeyStore_ CryptoKey_KeyStore

Key store CryptoKey datastructure.

This structure contains all the information necessary to access keying material stored in a dedicated key store or key database with memory access controls.

§ CryptoKey_KeyBlob

typedef struct CryptoKey_KeyBlob_ CryptoKey_KeyBlob

Keyblob CryptoKey datastructure.

This structure contains all the information necessary to access keying material stored in an encrypted structure in flash or RAM.

§ CryptoKey

typedef struct CryptoKey_ CryptoKey

CryptoKey datastructure.

This structure contains a CryptoKey_Encoding and one of

CryptoKey_Plaintext
CryptoKey_KeyStore
CryptoKey_KeyBlob

§ CryptoKey_SecurityPolicy

typedef struct CryptoKey_SecurityPolicy_ CryptoKey_SecurityPolicy

Structure that specifies the restrictions on a CryptoKey.

This structure is device-specific and declared here in incomplete form. The structure is fully defined in CryptoKeyDEVICE.h. This creates a link-time binding when using the structure with key store or keyblob functions. If the instance of the CryptoKey_SecurityPolicy is kept in a device-specific application-file, the gernic application code may still use references to it despite being an incomplete type in the generic application file at compile time.

Enumeration Type Documentation

§ CryptoKey_Encoding_

enum CryptoKey_Encoding_

List of the different types of CryptoKey.

Enumerator
CryptoKey_PLAINTEXT
CryptoKey_BLANK_PLAINTEXT
CryptoKey_KEYSTORE
CryptoKey_BLANK_KEYSTORE
CryptoKey_KEYBLOB
CryptoKey_BLANK_KEYBLOB

Function Documentation

§ CryptoKey_getCryptoKeyType()

int_fast16_t CryptoKey_getCryptoKeyType	(	CryptoKey *	keyHandle,
		CryptoKey_Encoding *	keyType
	)

Gets the key type of the CryptoKey.

Parameters

[in]	keyHandle	Pointer to a CryptoKey
[out]	keyType	Type of the CryptoKey

Returns: Returns a status code

§ CryptoKey_isBlank()

int_fast16_t CryptoKey_isBlank	(	CryptoKey *	keyHandle,
		bool *	isBlank
	)

Wheather the CryptoKey is 'blank' or represents valid keying material.

Parameters

[in]	keyHandle	Pointer to a CryptoKey
[out]	isBlank	Wheather the CryptoKey is 'blank' or not

Returns: Returns a status code

§ CryptoKey_markAsBlank()

int_fast16_t CryptoKey_markAsBlank ( CryptoKey * keyHandle )

Marks a CryptoKey as 'blank'.

The CryptoKey will be unlinked from any previously connected keying material

Parameters

[in] keyHandle Pointer to a CryptoKey

Returns: Returns a status code

§ CryptoKey_initSecurityPolicy()

int_fast16_t CryptoKey_initSecurityPolicy ( CryptoKey_SecurityPolicy * policy )

Function to initialize the CryptoKey_SecurityPolicy struct to its defaults.

This will zero-out all fields that cannot be set to safe defaults

Parameters

[in] policy Pointer to a CryptoKey_SecurityPolicy

Returns: Returns a status code

Detailed Description

Data Structures

Macros

Typedefs

Enumerations

Functions

Typedef Documentation

§ CryptoKey_Encoding

§ CryptoKey_Plaintext

§ CryptoKey_KeyStore

§ CryptoKey_KeyBlob

§ CryptoKey

§ CryptoKey_SecurityPolicy

Enumeration Type Documentation

§ CryptoKey_Encoding_

Function Documentation

§ CryptoKey_getCryptoKeyType()

§ CryptoKey_isBlank()

§ CryptoKey_markAsBlank()

§ CryptoKey_initSecurityPolicy()