Otfad

## Data Structures

struct | otfad_kek_t
| Format of OTFAD key wrap key (KEK). More...
struct | keyblob_t
| Key Blob format. More...
struct | keyblob_data_t

## Enumerations

enum | _otfad_driver_errors { kStatus_OtfadSecurityViolation = MAKE_STATUS(kStatusGroup_OTFADDriver, 0), kStatus_OtfadLogicallyDisabled = MAKE_STATUS(kStatusGroup_OTFADDriver, 1), kStatus_OtfadInvalidKey = MAKE_STATUS(kStatusGroup_OTFADDriver, 2), kStatus_OtfadInvalidKeyBlob = MAKE_STATUS(kStatusGroup_OTFADDriver, 3) }
| OTFAD Driver status codes.
enum | _constants { kAesKeySizeBytes = 16, kCtrSizeBytes = 8, kCrc32SizeBytes = 32, kNumKeyBlobs = 4, kKeyBlobSizeBytes = 64, kKeyBlobArraySizeBytes = kKeyBlobSizeBytes * kNumKeyBlobs }
| Constants. More...

## Functions

status_t | otfad_init (uint32_t instance, const uint8_t *keyBlobs, const otfad_kek_t *kek)
| Initialize. More...
static void | program_contexts (OTFAD_Type *baseAddr, uint8_t *keyBlobs, uint32_t *kek)
| Program context regiters with information from key blobs. More...
static bool | validate_crc (const keyblob_t *keyBlob)
| Validate CRC32 in key blob. More...

## Variables

const uint32_t | g_otfadBaseAddr [] = OTFAD_BASE_ADDRS
| Instance base addresses.

## Usage Information

## Data Structure Documentation

struct otfad_kek_t

Format of OTFAD key wrap key (KEK).

The four consecutive little-endian memory-mapped registers provide 128 bits of key storage.

Data Fields
uint32_t | keyWord0 | Word0: KEY[31:0][A03, A02, A01, A00].
uint32_t | keyWord1 | Word1: KEY[31:0][A07, A06, A05, A04].
uint32_t | keyWord2 | Word2: KEY[31:0][A11, A10, A09, A08].
uint32_t | keyWord3 | Word3: KEY[31:0][A15, A14, A13, A12].

struct keyblob_t

Key Blob format.

Data Fields
uint8_t | ctr[kCtrSizeBytes] |
uint32_t | endaddr |
uint8_t | expanded_wrap_data[8] |
uint8_t | key[kAesKeySizeBytes] |
uint32_t | key_blob_crc32 |
uint32_t | srtaddr |
uint8_t | unused_filler[16] |
uint32_t | zero_fill |

struct keyblob_data_t

Collaboration diagram for keyblob_data_t:
[legend]

Data Fields
uint8_t | ivHeader[8] |
keyblob_t | keyBlob |

## Enumeration Type Documentation

enum _constants

Constants.

Enumerator
kAesKeySizeBytes | Number of bytes in AES-128 key.
kCtrSizeBytes | Number of bytes in Ctr.
kCrc32SizeBytes | Number of bytes covered by CRC32.
kNumKeyBlobs | Number of key blobs.
kKeyBlobSizeBytes | Key blob size in bytes.
kKeyBlobArraySizeBytes | Key blob array size in bytes.

## Function Documentation

status_t otfad_init | ( | uint32_t | instance,
|  | const uint8_t * | keyBlobs,
|  | const otfad_kek_t * | kek
| ) |  |

Initialize.

If OTFAD KEY in the SIM module is invalid, or the key blobs are invalid, then the OTFAD will be initialized to bypass mode (no decryption). Otherwise, keyBlobs will be unwrapped and programmed into the OTFAD context registers.

Parameters

  instance | Module instance
  keyBlobs | Pointer to array of 4 key blobs
  kek | Pointer to OTFAD Key Encryption Key (KEK)

Return values

  kStatus_OtfadLogicallyDisabled | OTFAD is disabled
  kStatus_OtfadSecurityViolation | Security violation detectd
  kStatus_Success | OTFAD has been initialized

static void program_contexts | ( | OTFAD_Type * | baseAddr,
|  | uint8_t * | keyBlobs,
|  | uint32_t * | kek
| ) |  |

static

Program context regiters with information from key blobs.

Key blobs are unwrapped first. Each blob is validated with CRC32.

Parameters

  baseAddr | OTFAD module base address
  keyBlobs | pointer to array of 4 key blobs
  kek | KeK words

bool validate_crc | ( | const keyblob_t * | keyBlob | ) |

static

Validate CRC32 in key blob.

Parameters

  keyBlob | Pointer to key blob

Returns
  True if CRC matches, False otherwise