The CryptoKey type is an opaque representation of a cryptographic key.
============================================================================
Cryptographic keying material may be stored on an embedded system multiple ways.
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.
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>
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 enum CryptoKey_Encoding_ CryptoKey_Encoding |
List of the different types of CryptoKey.
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.
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.
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.
typedef struct CryptoKey_ CryptoKey |
CryptoKey datastructure.
This structure contains a CryptoKey_Encoding and one of
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.
enum CryptoKey_Encoding_ |
int_fast16_t CryptoKey_getCryptoKeyType | ( | CryptoKey * | keyHandle, |
CryptoKey_Encoding * | keyType | ||
) |
Gets the key type of the CryptoKey.
[in] | keyHandle | Pointer to a CryptoKey |
[out] | keyType | Type of the CryptoKey |
int_fast16_t CryptoKey_isBlank | ( | CryptoKey * | keyHandle, |
bool * | isBlank | ||
) |
Wheather the CryptoKey is 'blank' or represents valid keying material.
[in] | keyHandle | Pointer to a CryptoKey |
[out] | isBlank | Wheather the CryptoKey is 'blank' or not |
int_fast16_t CryptoKey_markAsBlank | ( | CryptoKey * | keyHandle | ) |
Marks a CryptoKey as 'blank'.
The CryptoKey will be unlinked from any previously connected keying material
[in] | keyHandle | Pointer to a CryptoKey |
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
[in] | policy | Pointer to a CryptoKey_SecurityPolicy |