Protected storage

The Protected Storage volume will generally be a region of the microcontroller FLASH though it could be an external volume such as serial FLASH memory. The PS storage volume can be located in either the Secure or Non-Secure partition through PSA storage functions are always located in the Secure Partition. The Protected Storage is different from the other services in that it is run as a service within the Application RoT rather than the PSA RoT. The protected storage is capable of providing confidentiality, integrity, and replay protection. However, depending on the threat model and user requirements, data may be stored without confidentiality or replay protection, while data integrity is always validated.

The protected storage volume is accessed through an API provided to the Non-Secure code by adding the header file “psa/protected_storage.h” to the application Non-Secure code. This provides the following storage API (Table 13.1):

When storing data, additional flags are used to control the security settings for a given data item. While confidentiality and anti-replay are optional, integrity is always applied.

In the case of public data, it is possible to disable encryption:

          PSA_STORAGE_FLAG_NO_CONFIDENTIALITY

Similarly, we can also disable replay protection if required.

          PSA_STORAGE_FLAG_NO_REPLAY_PROTECTION

We can also store an item as a constant so that one it has been written it cannot be updated. Such an immutable item can be created with the following flag.

          PSA_STORAGE_FLAG_WRITE_ONCE

Data items are stored as key value pairs, which are referenced through a Unique Identifier (UID) using the type:

          psa:storage_uid_tPS_Block = 0x01;

We can store a data item as follows:

   psa:status_t res ;   size_t PS_BlockSize =  20;   uint8_t PS_Blockdata[10] = "1234567890";   psa:storage_create_flags_t PS_CreateFlags = 0;   res = psa:ps_set( PS_Block, PS_BlockSize, PS_Blockdata, PS_CreateFlags);

When data are stored, depending on the implementation, the modifying flags may be ignored. For example, you may request no confidentiality, but the storage service may be configured to always encrypt the data. We can check the actual storage state using the following API call:

   struct psa:storage_info_t PS_block_info;   res = psa:ps_get_info(PS_Block, &PS_block_info);

which will return the capacity of the storage, the size of the data currently stored, and any flags that were set during creation.

If you need to create a storage item but only want to store part of the record, you must first create the item and then use the psa:ps_set_extended() function to add the data.

   size_t PS_DataSize = 10;   size_t PS_Offset = 10;   If( psa:ps_get_support() == PSA_STORAGE_SUPPORT_SET_EXTENDED )   {   res = psa:ps_create(PS_Block, PS_BlockSize, PS_CreateFlags);res = psa:ps_set_extended(PS_Block,PS_Offset, PS_DataSize,PS_Blockdata );   }

Data items can be retrieved or partially retrieved in a similar fashion and if necessary deleted.

   res =psa:ps_get(PS_Block, 0, PS_BlockSize, PS_Read_Blockdata, &PS_Read_Size);   res = psa:ps_remove(PS_Block);

Exercise: Protected storage

This exercise uses the Protected Storage API to save and retrieve data to the protected storage volume.

• Locate Exercise 13.1 in the pack installer and press the copy button.
• Make the nonsecure project the active project.
• Batch build both projects and start the debugger.
• Open the RTE and the TFM::Secure Service branch.

The protected storage API is enabled as an encrypted volume.

• In the secure project, open TFM::tfm_config.h

Examine the configuration options for the protected storage volume (Fig. 13.2).

We can control the FLASH volume by selecting an appropriate CMSIS-FLASH driver. It is also possible to enable rollback protection and control the maximum item storage size and number of items that can be saved to the protected storage volume.

The “Create Flash layout” option will force the secure service to format the FLASH volume and erase all existing data.

Validate FLASH Metadata will force the secure service to check the item metadata during a read operation to ensure that it is not corrupted or subject to a malicious change.

If you change any of these options, you must also consider how any change to the size of the protected storage volume will impact the memory map defined in the original CMSIS Zone project.

• Open app_main.c and step through the code.

The app-main thread uses each of the Protected Storage functions to save, retrieve and extend blocks of data into the secure FLASH volume.

Internal trusted storage

The Internal Trusted Storage is used to store a small number of high-value secrets and consequently always provides confidentiality, integrity, and replay protection. The Internal Trusted Storage is run as a service within the PSA Root of Trust, and the data will be stored in a small volume located in the internal secure FLASH memory. The API is defined by including the header file:

          "psa/internal_trusted_storage.h"

and contains the following functions (Table 13.2):

The Internal Trusted Storage functions operate with a similar but more limited API compared to the protected storage functions. When a data item is stored in the internal protected memory, the NO_CONFIDENTIALITY and PSA_STORAGE_FLAG_NO_REPLAY_PROTECTION have no effect, while the STORAGE_FLAG_WRITE_ONCE flag will always work.

We can now store secrets in the Internal Trusted Storage.

psa:status_t  psa:storage_create_flags_t ITS_CreateFlags = 0;  psa:storage_uid_t ITS_Block = 0x01;  size_t ITS_BlockSize =  20;  uint8_t ITS_Blockdata[10] = "1234567890";  uint8_t ITS_Read_Blockdata[10];  size_t ITS_Read_Size = 0;  res = psa:its_set(ITS_Block,ITS_BlockSize,  ITS_Blockdata,  ITS_CreateFlags);  res =psa:its_get(ITS_Block,0,  10,  ITS_Read_Blockdata,  &ITS_Read_Size);  psa:its_remove(ITS_Block);

Multipart operation

The symmetric cipher, MAC, and message digest abstraction layers may be used with a single block of data or are capable of working with large blocks of data or streaming data. A multipart operation consists of an initial setup function followed by a call to an update function. Once the data have been processed, the session can be terminated, and if appropriate, a final result can be calculated with a finish function.

To access the mbedCrypto functions, you must include the header “psa/crypto.h”.

Random

The mbedCrypto service provides a random function that are used to provide keying material and streams of random values (Table 13.4).

We can fill a local buffer with random data as follows.

   uint8_t random[10] ;   status = psa:generate_random(random, sizeof(random));

Key management

In addition to the core cryptographic algorithms, mbedCrypto provides a rich API to create and manage encryption keys. By default, the Internal Trusted Storage is used to hold the encryption keys, but the API can be modified to target a secure key store provided by the underlying microcontroller. When using the key management API, the Non-Secure code and other security services reference the keys by identifiers, which are defined during the key generation process. When created, a key may be given a range of attributes and usage policies that allow it to be used by the Non-Secure code and/or other secure services. Each key is given a lifetime, which allows it to be persistent and be stored in the ITS until it is destroyed, or it may be a volatile key that has a lifetime limited to the current session. We can also control if a key is allowed to leave the Secure World by defining it as extractable or nonextractable. As an example, both a public and private key may be held in the Internal Trusted Storage. The private key would be labeled as nonextractable, while the public key would be defined as extractable. Once a key has been generated, an additional set of functions are used to manage its lifecycle, as shown in Table 13.5.

The capabilities of a key are stored in a structure psa:key_attributes_t. This structure contains a set of elements that define the following features (Table 13.6).

When a key is created, we pass a unique integer value of type psa:key_id_t. This becomes the key ID that is used by the Non-Secure code to reference the key for all future operations. When a key is defined, we must also specify its usage policy as a set of flags (Table 13.7), which algorithms it can be used with and its bit size.

The Non-Secure code does not have access to the key and its attributes directly but can manage the key, and its attributes through a set of helper functions (Table 13.8). We again define the range of algorithms the key can be used for. Although this is already defined in key type, this second entry defines additional information necessary to use the algorithm, such as padding type.

The PSA crypto library also provides a set of high-level functions, which can be used to initialize, read, and reset the key attributes as a whole (Table 13.9). The reset function should be called after any operations on the key to wipe the Non-Secure attribute memory.

Once a key has been created, it is stored in the Internal Trusted Storage. Within the Non-Secure code, it is then referenced by its ID. We can now use these functions to create a set of keys and store them in the ITS. First, declare and initialize the attributes object and the key ID:

   psa:key_attributes_t attributes = PSA_KEY_ATTRIBUTES_INIT;   psa:key_id_ttest_key_id;

To manage our key, we can create a key ID value:

          #define TEST_KEY_ID (psa:key_id_t) 1

This is stored in the attributes along with other the key parameters and policies.

   psa:set_key_id(&attributes,TEST_KEY_ID)   psa:set_key_usage_flags(&attributes,PSA_KEY_USAGE_ENCRYPT         PSA_KEY_USAGE_DECRYPT );

   psa:set_key_algorithm(&attributes, 0);   psa:set_key_type(&attributes, PSA_KEY_TYPE_AES);   psa:set_key_bits(&attributes, 128);   psa:set_key_lifetime(&attributes, PSA_KEY_LIFETIME_PERSISTENT);

Now we can store an existing key with psa:key_import() or generate a symmetrical key using a random process in the secure service.

          status = psa:generate_key(&attributes, &test_key_id);

Once the key has been generated, the returned test_key_id will equal original define TEST_KEY_ID.

Once we have a set of keys, we can start to use the mbedCrypto algorithms.

Key derivation

For some algorithms, we will need to create ephemeral session keys. The mbedCrypto library provides a set of key derivation functions to manage these operations (Table 13.10).

First create and initialize the key objects:

   psa:key_attributes_t attributes = PSA_KEY_ATTRIBUTES_INIT;   psa:key_derivation_operation_t operation = PSA_KEY_DERIVATION_OPERATION_INIT;

We must also create a salt to prevent lookup attacks:

          const unsigned char salt[] = {0x1,0x2,0x3,0x4};

We can also select the underlying algorithm used for the derivation:

          psa:algorithm_t alg = PSA_ALG_HKDF(PSA_ALG_SHA_256);

then define the characteristics of the required key:

   size_t derived_bits = 128;   size_t capacity = PSA_BITS_TO_BYTES(derived_bits);

and then define the id’s used to manage an existing and derived key:

   psa:key_id_ttest_key_aes = 1;   psa:key_id_t derived_key;

To derive the key, we can setup the key derivation algorithm and its bit size capacity:

   status = psa:key_derivation_setup(&operation, alg);   status = psa:key_derivation_set_capacity(&operation, capacity);

Then, add the keying material:

   status = psa:key_derivation_input_bytes(&operation,         PSA_KEY_DERIVATION_INPUT_SALTsalt, sizeof(salt));   status = psa:key_derivation_input_key(&operation,         PSA_KEY_DERIVATION_INPUT_SECRET, test_key_aes);   status = psa:key_derivation_input_bytes(&operation,         PSA_KEY_DERIVATION_INPUT_INFO, info,sizeof(info));

Then, define the key attributes:

    psa:set_key_usage_flags(&attributes, PSA_KEY_USAGE_ENCRYPT);    psa:set_key_algorithm(&attributes, PSA_ALG_CTR);    psa:set_key_type(&attributes, PSA_KEY_TYPE_AES);    psa:set_key_bits(&attributes, 128);

Finally, derive the key:

    status = psa:key_derivation_output_key(&attributes,&operation,&derived_key);

Symmetrical ciphers

The mbedCrypto service provides an abstraction layer for any symmetrical ciphers that have been enabled in the secure service (Table 13.11).

To use a symmetrical cipher, we can first setup the attributes objects and define the chaining method:

   psa:status_t status;psa:key_attributes_t attributes = PSA_KEY_ATTRIBUTES_INIT;psa:algorithm_t alg = PSA_ALG_CBC_NO_PADDING;uint8_t plaintext[block_size] = “Hello World”;   uint8_t iv[block_size];   size_t iv_len;   uint8_t output[block_size];   size_t output_len;   psa:key_handle_t handle;   psa:cipher_operation_t operation = PSA_CIPHER_OPERATION_INIT;

Now we can open a test key and setup the cipher for multipart operation:

          status = psa:cipher_encrypt_setup(&operation,test_key_aes, alg);

Before the first packet of plaintext, we must generate an IV:

   status = psa:cipher_generate_iv(&operation,iv,         sizeof(iv),         &iv_len);

Then we can iterate through the data:

   status = psa:cipher_update(&operation,plaintext,         sizeof(plaintext),         output,         sizeof(output),         &output_len);

Until we finish with the last packet:

   status = psa:cipher_finish(&operation,output + output_len,         sizeof(output) - output_len,         &output_len);

Authenticated encryption with associated data

The AEAD algorithm is also provided as a set of API functions (Table 13.12).

We can use the AEAD algorithm to perform a simple encryption of a block of data. Here, we must provide the key ID, a NONCE, which must be unique for each session, the unencrypted associated data, and the input data, which will be encrypted:

   status = psa:aead_encrypt(test_key_aead,PSA_ALG_CCM,         nonce,         sizeof(nonce),         additional_data,         sizeof(additional_data),         input_data,         sizeof(input_data),         output_data,         output_size,         &output_length);

The same key and NONCE is used in the decryption function.

   status = psa:aead_decrypt(test_key_aead,PSA_ALG_CCM,         nonce,         sizeof(nonce),         additional_data,         sizeof(additional_data),         input_data,         sizeof(input_data),         output_data,         output_size,         &output_length);

We can also perform a multipart operation in a similar fashion to the symmetrical cipher above.

Message digest

The mbedCrypto library also provides an abstraction layer for the mbedTLS hashing algorithms (Table 13.13).

We can perform a multipart hashing operation by first setting up the hash operation with the selected hash algorithm:

          status = psa:hash_setup(&operation, alg);

Then we can apply packets of the data:

          status = psa:hash_update(&operation, input, sizeof(input));

Until we reach the end of the data block when we can generate the final hash:

   status = psa:hash_finish(&operation,actual_hash,         sizeof(actual_hash),         &actual_hash_len);

Or verify against an existing hash:

   status = psa:hash_verify(&operation,expected_hash,         expected_hash_len);

Message authentication codes (MAC)

A set of MAC functions are also available. The base hashing algorithm can be selected at the start of the MAC operation (Table 13.14).

Like the hash algorithms, we can MAC a single packet of data or setup a multipart operation.

   psa:mac_compute(test_key_mac,PSA_ALG_HMAC(PSA_ALG_SHA_256),         test_buffer,sizeof(test_buffer),         &mac,mac_size,&mac_len);   psa:mac_verify(test_key_mac,PSA_ALG_HMAC(PSA_ALG_SHA_256),         test_buffer,sizeof(test_buffer),         &mac,mac_len);

Asymmetric signing and encryption

The mbedCrypto library also supports a range of asymmetric algorithms for encryptiondecryption and signing of data (Table 13.15). The abstraction layer supports both the RSA cryptosystem and the Diffie-Hellman key agreement algorithm. Signing can also be accomplished with RSA, DSA, or ECDSA.

Here we can sign a message using an already calculated hash. The key will define the algorithm though we must also specify a padding method:

   status = psa:sign_hash (pk_handle,         PSA_ALG_RSA_PKCS1V15_SIGN_RAW,         hash,         sizeof(hash),         signature,         sizeof(signature),         &signature_length);

Key agreement

The Key Agreement API allows us to calculate a shared secret by combining our key with the public key from a peer (Table 13.16). We can also calculate the secret and derive a symmetric encryption key with a single API call.

Once we exchange public keys with a peer, it is possible to calculate a shared secret.

   psa:raw_key_agreement(PSA_ALG_ECDH,private_key,         &peer_key,         peer_key_length,         &output,         output_size,         &output_length);

Attestation token

A token will encode a number of security claims that are used to describe its origin and capabilities to the server. The Internet Assigned Numbers Authority maintains a registry of claims which may be used as templates for any given application. If a suitable token is not available, you can create your own security claims and token description. The format shown below is currently used (Table 13.17).

A claim is then added for each software component, typically this will be the Application Image, Trusted Firmware, and the PSA bootloader. Each claim is made up of the measurements shown in Table 13.18.

The token data will be encoded as a CBOR object and then will be encrypted and signed in a “CBOR Object Signing and Encryption” COSE format.

Attestation infrastructure

Alongside the token, a device will create an ECDSA key pair. The private key will be stored in the device itself, and the public key will be stored in a database that is part of an attestation server (Fig. 13.6).

The attestation server may be a public service or a private part of your system. When an IoT device wishes to communicate with a server, it first sends its token to the server. The server does not read the token but blindly passes the token to the attestation verification service for authentication using the instance ID to identify the matching public key. The attestation server will return a validation result to the server. If the token is found to be valid, the server can examine the claims made in the token and make a decision to grant the service request made by the IoT device (Fig. 13.7).

The header file “psa/initial_attestation.h” provides the Non-Secure code with an API to access the Attestation token and public key. The available functions are shown in Table 13.19.

The Non-Secure code can create a token by providing a block of challenge data and then requesting the token.

   #define TEST_TOKEN_SIZE (0x200)   #define TEST_CHALLENGE_OBJ_SIZE (32u)   static uint8_t token_buffer[TEST_TOKEN_SIZE];   static uint8_t challenge_buffer[TEST_CHALLENGE_OBJ_SIZE] =   {//32 bytes of user data};   uint32_t token_size;   attest_err = psa:initial_attest_get_token_size(TEST_CHALLENGE_OBJ_SIZE,         &token_size);   attest_err = psa:initial_attest_get_token(challenge_buffer,         TEST_CHALLENGE_OBJ_SIZE,         token_buffer,         &token_size);

Secure partition

The secure services and partition manager can write messages to the audit log using the API shown in Table 13.20.

Non-secure partition

The Non-Secure code can monitor and read the audit log (Table 13.21) using the header file “psa/initial_audit_api.h”.

The Non-Secure code can read the audit log using this simple API.

   psa:audit_get_info(numRecords,totalSize);   for(n  =  0;n  <  numRecords;n  ++){   psa:audit_get_record_info(n,&curRecSize);   psa:audit_retrieve_record(n,sizeof(auditBuf),NULL,0,&curRecSize);   printf(“%s”, auditBuf);   psa:audit_delete_record(n);   }

Exercise: Audit

The audit log is generated secure partition and accessed by the nonsecure code. The nonsecure audit client provides a minimal API to manage the audit records.

• Locate Exercise 13.5 in the pack installer and press the copy button.
• Make the nonsecure project the active project.
• Batch build both projects and start the debugger.
• Open the RTE and the TFM::Secure Service branch.
• Check that the audit logging client is enabled.

In the secure project the Audit logging is enabled in the RTE and currently has no further configuration options.

The client API provides functions to get the total number of audit records their total stored size and the size of a particular record.

psa:audit_get_info(&num_records, &stored_size);  psa:audit_get_record_info(0, &recordSize);

We can then read and delete a specific record.

psa:audit_retrieve_record(0,//record index  LOCAL_BUFFER_SIZE,//buffer size  0,//challenge token currently NULL  0,//challenge token size  &auditBuffer[0],//record buffer  &recordSize);//record buffer size