<-Zero Trust and Profiles Go to ToC MPAI as a Service ->
1 Reference Model
Figure 1 depicts the Reference Model of the Security API.
User Agentsecure initialisationControllerSecure ControllerAIMsof the ModuleSecurity APISecure StorageMPAI_AIFSS_*: initialise, write,read, get info, deleteAttestationMPAI_AIFAT_*: an EntityAttestation TokenCryptographyhashing MPAI_AIFCR_*; key management MPAI_AIFKM_*;key exchange MPAI_AIFKX_*; message authentication MPAI_AIFMAC_*;ciphers MPAI_AIFCIP_*; AEAD MPAI_AIFAEAD_*;signature MPAI_AIFSIGN_*; asymmetric encryption MPAI_AIFASYM_*Secure communicationthe HTTPS and CoAP support of secure transport librariesTrusted Serviceson a root of trust:a TPM, a TEE, a secure element;keys held in it,code measured into it,secrets sealed to it
Figure 1 – Reference Model of the Security API
The Security API gives the User Agent, the Controller and the AIMs of a Module access to the Trusted Services of the Secure Profile: Secure Storage, Attestation, cryptographic functions and secure communication, provided on a root of trust. It is distinct from the Trust interface of an AIM, through which the Controller verifies the AIM (AI Modules): the Security API provides services to its caller; it does not decide trust. The functions follow the PSA Certified Crypto, Secure Storage and Attestation APIs (References), and the conventions of the Basic API.
The functions are in two parts: those whose calls are executed in the non-secure area, and those whose calls are executed in the secure area.
2 Data
Data, whatever its use – a key, an encrypted payload, plain text – is passed to and from the functions in a data_t structure (Table 1).
Table 1 – The data_t structure
| Field | Meaning |
| data_location_t location | The location of the data: DATA_LOC_RAM, DATA_LOC_EXT_FLASH, DATA_LOC_INT_FLASH, DATA_LOC_LOCAL_DISK or DATA_LOC_REMOTE_DISK (uint32_t). |
| void* data | The pointer, within the location, to the start of the data. |
| size_t size | The size of the data in bytes. |
| data_flags_t flags | Other flags characterising the data: DATA_FLAG_ENCRYPTED, DATA_FLAG_PLAIN or DATA_FLAG_UNKNOWN (uint32_t). |
3 Functions called by the User Agent
3.1 MPAI_AIFU_Controller_Initialize_Secure
error_t MPAI_AIFU_Controller_Initialize_Secure(bool useAttestation)
Switches on and initialises the Controller in the Secure Profile, in particular its Secure Communication component, using Attestation where useAttestation is true.
The Module is then started, paused, resumed and stopped with the functions of the Basic API.
4 Secure Storage
In the following functions, name is the symbolic name of a Secure Storage area, which the Implementation maps to a numeric identifier. The flags specify the behaviour of the operation.
4.1 MPAI_AIFSS_Storage_Init
error_t MPAI_AIFSS_Storage_Init(string_t name, size_t data_length,
const p_data_t data, flags_t flags)
Initialises the Secure Storage area name.
4.2 MPAI_AIFSS_Storage_Write
error_t MPAI_AIFSS_Storage_Write(string_t name, size_t data_length,
const p_data_t data, flags_t flags)
Writes data to the area name.
4.3 MPAI_AIFSS_Storage_Read
error_t MPAI_AIFSS_Storage_Read(string_t name, size_t data_length,
p_data_t data, flags_t flags)
Reads data from the area name.
4.4 MPAI_AIFSS_Storage_GetInfo
error_t MPAI_AIFSS_Storage_GetInfo(string_t name, struct storage_info_t* p_info)
Returns information about the area name.
4.5 MPAI_AIFSS_Storage_Delete
error_t MPAI_AIFSS_Storage_Delete(string_t name)
Deletes the data in the area name.
5 Attestation
5.1 MPAI_AIFAT_Get_Token
error_t MPAI_AIFAT_Get_Token(uint8_t* token_buf, size_t token_buf_size, size_t* token_size)
Returns an Entity Attestation Token, based on CBOR, COSE and EAT (References), of the root of trust of the caller. The token buffer is managed by the Implementation of the API. A token over the nonce of a Verifier is the Attestation Evidence of MPAI-PTF.
6 Cryptography
6.1 Hashing
The SHA-2 and SHA-3 families of hash functions (References). MD5 and SHA-1 shall not be used where security depends on the hash. hash_state_t is a state object of the Implementation.
6.1.1 MPAI_AIFCR_Hash
error_t MPAI_AIFCR_Hash(hash_state_t* state, algorithm_t alg, uint8_t* hash,
size_t hash_size, size_t* hash_length,
const uint8_t* input, size_t input_length)
Hashes an input buffer into an output buffer. Data of arbitrary size may be processed in one chunk or in several; the Implementation releases control to the rest of the system at the end of each chunk.
6.1.2 MPAI_AIFCR_Hash_Verify
error_t MPAI_AIFCR_Hash_Verify(hash_state_t* state, const uint8_t* hash, size_t hash_length,
const uint8_t* input, size_t input_length)
Verifies a hash against an input buffer.
6.1.3 MPAI_AIFCR_Hash_Abort
error_t MPAI_AIFCR_Hash_Abort(hash_state_t* state)
Aborts the operation and releases its resources.
6.2 Key management
Applications reach keys indirectly, through an identifier, and operations use a key without access to the key material. A key provided from outside is mapped to the attributes of Table 2.
Table 2 – Key attributes (key_attributes_t)
| Attribute | Meaning |
| Identifier | A number, generated internally. |
| p_data | The key data and where it is stored. |
| Type | RAW_DATA, HMAC, DERIVE, PASSWORD, AES, DES, RSA, ECC or DH. |
| Lifetime | AIF_KEY_LIFETIME_VOLATILE – kept in RAM – or AIF_KEY_LIFETIME_PERSISTENT – kept in primary local storage or in the primary secure element. |
| Policy | The permitted algorithm – NONE or one algorithm – and the usage flags: EXPORT, COPY, CACHE, ENCRYPT, DECRYPT, SIGN_MESSAGE, VERIFY_MESSAGE, SIGN_HASH, VERIFY_HASH, DERIVE, VERIFY_DERIVATION. |
6.2.1 MPAI_AIFKM_Import_Key
error_t MPAI_AIFKM_Import_Key(const key_attributes_t* attributes, const uint8_t* data,
size_t data_length, key_id_t* key)
Imports a key given as a binary value. The caller fills in the attributes; the identifier is generated in response.
6.2.2 MPAI_AIFKM_Generate_Key
error_t MPAI_AIFKM_Generate_Key(const key_attributes_t* attributes, key_id_t* key)
Generates a random key.
6.2.3 MPAI_AIFKM_Copy_Key
error_t MPAI_AIFKM_Copy_Key(key_id_t source_key, const key_attributes_t* attributes,
key_id_t* target_key)
Copies a key, with new attributes.
6.2.4 MPAI_AIFKM_Destroy_Key
error_t MPAI_AIFKM_Destroy_Key(key_id_t key)
Destroys a key.
6.2.5 MPAI_AIFKM_Export_Key
error_t MPAI_AIFKM_Export_Key(key_id_t key, uint8_t* data, size_t data_size, size_t* data_length)
Exports a key to an output buffer, where its policy allows.
6.2.6 MPAI_AIFKM_Export_Public_Key
error_t MPAI_AIFKM_Export_Public_Key(key_id_t key, uint8_t* data, size_t data_size,
size_t* data_length)
Exports the public key of a key pair to an output buffer.
6.3 Key exchange
Algorithms: FFDH (finite-field Diffie-Hellman) and ECDH (elliptic-curve Diffie-Hellman) (References).
6.3.1 MPAI_AIFKX_Raw_Key_Agreement
error_t MPAI_AIFKX_Raw_Key_Agreement(algorithm_t alg, key_id_t private_key,
const uint8_t* peer_key, size_t peer_key_length,
uint8_t* output, size_t output_size, size_t* output_length)
Returns the raw shared secret.
6.3.2 MPAI_AIFKX_Key_Derivation_Key_Agreement
error_t MPAI_AIFKX_Key_Derivation_Key_Agreement(key_derivation_operation_t* operation,
key_derivation_step_t step, key_id_t private_key,
const uint8_t* peer_key, size_t peer_key_length)
Performs a key agreement and uses the shared secret as input to a key derivation.
6.4 Message authentication code
A message authentication code is a cryptographic checksum on data, computed with a key shared by the originator and the recipients, that detects any modification of the data. mac_state_t is a state object of the Implementation.
6.4.1 MPAI_AIFMAC_Sign_Setup
error_t MPAI_AIFMAC_Sign_Setup(mac_state_t* state, key_id_t key, algorithm_t alg)
Sets up a MAC sign operation.
6.4.2 MPAI_AIFMAC_Verify_Setup
error_t MPAI_AIFMAC_Verify_Setup(mac_state_t* state, key_id_t key, algorithm_t alg)
Sets up a MAC verify operation.
6.4.3 MPAI_AIFMAC_Update
error_t MPAI_AIFMAC_Update(mac_state_t* state, const uint8_t* input, size_t input_length)
Computes the MAC of a chunk of data; it may be repeated until the data is complete.
6.4.4 MPAI_AIFMAC_Sign_Finish
error_t MPAI_AIFMAC_Sign_Finish(mac_state_t* state, uint8_t* mac, size_t mac_size,
size_t* mac_length)
Finishes a MAC sign operation.
6.4.5 MPAI_AIFMAC_Verify_Finish
error_t MPAI_AIFMAC_Verify_Finish(mac_state_t* state, const uint8_t* mac, size_t mac_length)
Finishes a MAC verify operation at the receiver.
6.4.6 MPAI_AIFMAC_Abort
error_t MPAI_AIFMAC_Abort(mac_state_t* state)
Aborts a MAC operation.
6.5 Ciphers
Algorithms: AIF_ALG_XTS, AIF_ALG_ECB_NO_PADDING, AIF_ALG_CBC_NO_PADDING and AIF_ALG_CBC_PKCS7 (References). Where a multiblock cipher is used, the developer manages the initialisation vector (IV): generates it explicitly, without relying on a service to do so; communicates it securely to the parties receiving the message; and, if it is not disposed of, keeps it in Secure Storage. The iv parameter and its size are NULL where a call does not need them; where an algorithm needs an IV and NULL is passed, the Implementation generates it securely. cipher_state_t is a state object of the Implementation.
6.5.1 MPAI_AIFCIP_Encrypt
error_t MPAI_AIFCIP_Encrypt(cipher_state_t* state, key_id_t key, algorithm_t alg,
uint8_t* iv, size_t iv_size, size_t* iv_length)
Sets up a symmetric encryption.
6.5.2 MPAI_AIFCIP_Decrypt
error_t MPAI_AIFCIP_Decrypt(cipher_state_t* state, key_id_t key, algorithm_t alg,
uint8_t* iv, size_t iv_size, size_t* iv_length)
Sets up a symmetric decryption.
6.5.3 MPAI_AIFCIP_Update
error_t MPAI_AIFCIP_Update(cipher_state_t* state, const uint8_t* input, size_t input_length,
uint8_t* output, size_t output_size, size_t* output_length)
Encrypts or decrypts a chunk of data in an operation set up with MPAI_AIFCIP_Encrypt or MPAI_AIFCIP_Decrypt. It may be repeated until the data is complete.
6.5.4 MPAI_AIFCIP_Finish
error_t MPAI_AIFCIP_Finish(cipher_state_t* state, uint8_t* output, size_t output_size,
size_t* output_length)
Finishes the operation, returning any remaining output, and releases its resources.
6.5.5 MPAI_AIFCIP_Abort
error_t MPAI_AIFCIP_Abort(cipher_state_t* state)
Aborts a symmetric encryption or decryption.
6.6 Authenticated encryption with associated data
Algorithms: ALG_GCM and ALG_CHACHA20_POLY1305 (References). ALG_GCM requires a nonce of at least one byte. aead_state_t is a state object of the Implementation.
6.6.1 MPAI_AIFAEAD_Encrypt
error_t MPAI_AIFAEAD_Encrypt(aead_state_t* state, key_id_t key, algorithm_t alg,
const uint8_t* nonce, size_t nonce_length,
const uint8_t* additional_data, size_t additional_data_length,
const uint8_t* plaintext, size_t plaintext_length,
uint8_t* ciphertext, size_t ciphertext_size, size_t* ciphertext_length)
Encrypts and authenticates plaintext with its additional data.
6.6.2 MPAI_AIFAEAD_Decrypt
error_t MPAI_AIFAEAD_Decrypt(aead_state_t* state, key_id_t key, algorithm_t alg,
const uint8_t* nonce, size_t nonce_length,
const uint8_t* additional_data, size_t additional_data_length,
const uint8_t* ciphertext, size_t ciphertext_length,
uint8_t* plaintext, size_t plaintext_size, size_t* plaintext_length)
Decrypts and verifies ciphertext with its additional data.
6.6.3 MPAI_AIFAEAD_Abort
error_t MPAI_AIFAEAD_Abort(aead_state_t* state)
Aborts an AEAD operation.
6.7 Signature
Algorithms: RSA_PKCS1V15_SIGN, RSA_PSS, ECDSA and PURE_EDDSA (References). sign_state_t is a state object of the Implementation.
6.7.1 MPAI_AIFSIGN_Sign_Message
error_t MPAI_AIFSIGN_Sign_Message(sign_state_t* state, key_id_t key, algorithm_t alg,
const uint8_t* input, size_t input_length,
uint8_t* signature, size_t signature_size, size_t* signature_length)
Signs a message with a private key; for hash-and-sign algorithms, this includes the hashing.
6.7.2 MPAI_AIFSIGN_Verify_Message
error_t MPAI_AIFSIGN_Verify_Message(sign_state_t* state, key_id_t key, algorithm_t alg,
const uint8_t* input, size_t input_length,
const uint8_t* signature, size_t signature_length)
Verifies the signature of a message with a public key; for hash-and-sign algorithms, this includes the hashing.
6.7.3 MPAI_AIFSIGN_Sign_Hash
error_t MPAI_AIFSIGN_Sign_Hash(key_id_t key, algorithm_t alg,
const uint8_t* hash, size_t hash_length,
uint8_t* signature, size_t signature_size, size_t* signature_length)
Signs a hash already computed, with a private key.
6.7.4 MPAI_AIFSIGN_Verify_Hash
error_t MPAI_AIFSIGN_Verify_Hash(key_id_t key, algorithm_t alg,
const uint8_t* hash, size_t hash_length,
const uint8_t* signature, size_t signature_length)
Verifies the signature of a hash.
6.8 Asymmetric encryption
Algorithms: RSA_PKCS1V15_CRYPT and RSA_OAEP (References).
6.8.1 MPAI_AIFASYM_Encrypt
error_t MPAI_AIFASYM_Encrypt(key_id_t key, algorithm_t alg,
const uint8_t* input, size_t input_length, const uint8_t* salt, size_t salt_length,
uint8_t* output, size_t output_size, size_t* output_length)
Encrypts a short message with a public key.
6.8.2 MPAI_AIFASYM_Decrypt
error_t MPAI_AIFASYM_Decrypt(key_id_t key, algorithm_t alg,
const uint8_t* input, size_t input_length, const uint8_t* salt, size_t salt_length,
uint8_t* output, size_t output_size, size_t* output_length)
Decrypts a short message with a private key.
7 Secure communication
An Implementation relies on the HTTPS and CoAP support of the secure transport libraries of its programming language. Between machines, between Controllers, and between a User Agent and a Controller, communication is over mutual TLS, as Zero Trust and Profiles specifies.
