Cryptographic Services

Introduction

The Cryptographic services allow tifs client to encrypt/decrypt data blobs using one of AES-ECB, AES-CBC or AES-GCM operations.

Functional Goals

Cryptographic Service System provides the following functionality:

1. API to encrypt a data blob.
2. API to decrypt a data blob.

Design

The to-be encrypted/decrypted blob must be preceded by a context. The blob starts immediately after the context blob ends. The context blob contains information like the algorithm to use, key, key size, iv, data length etc.

The response contains calculated tag when the mode is AES-GCM and operation type is ‘encryption’.

The user may use one of the keys in the imported symmetric keyring, that has appropriate rights set to be be used in the CSP API. In order to do so, the user must populate the key id in the context.

The context also contains a revision field that denotes the context version. The revision field has been added to support different variations of the service in the future. Currently, just one version is supported which is version 0.

The structure of the context v0 is given below.

Context Structure

struct csp_aes_ctx_v0 {
  uint32_t  revision;
  uint8_t     mode;
  uint8_t     key_size;
  uint8_t     ctr_width;
  uint8_t     key_id;
  uint64_t    data_len;
  uint64_t    dest_addr;
  uint32_t    key[8];
  uint32_t    iv[4];
  uint32_t    tag[4];
}

revision	32-bit magic word - set to 0x0AE50000
mode	AES operation mode (ECB - 0, CBC - 1, GCM - 3)
key_size	AES key size (128 bits - 0, 256 bits - 2)
ctr_width	Reserved for future use
key_id	This should have the key id if a ‘symmetric keyring’ key is to be used for encryption/decryption, otherwise set to 0
data_len	Length of data in bytes
dest_addr	64-bits physical address where encrypted/decrypted blob has to be loaded
key	Encryption key if key_id is zero (‘key in the context’ mode), otherwise set to 0
iv	Initialization vector for AES operation. Required for CBC and GCM modes. Not used for ECB mode.
tag	Authentication tag as an array of 4 words (16 bytes) for GCM mode encryption operations, set to 0 for non-GCM modes