<-Zero Trust and Profiles Go to ToC MPAI as a Service ->
1 Reference Model
Figure 1 depicts the Reference Model of the Security API.

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 (Table 1). Every function that uses a key, a Secure Storage area or the root of trust is executed in the secure area.
Table 1 – Where the functions are executed
| Area | Functions |
| Secure area | 4 Secure Storage; 5 Attestation; 6.2 Key management; 6.3 Key exchange; 6.4 Message authentication code; 6.5 Ciphers; 6.6 Authenticated encryption with associated data; 6.7 Signature; 6.8 Asymmetric encryption; 6.9 Random generation |
| Non-secure area | 3.1 MPAI_AIFU_Controller_Initialize_Secure; 6.1 Hashing |
A caller in the non-secure area reaches a function of the secure area only through the Secure Controller (Zero Trust and Profiles), which executes the call for it after verifying that the caller is authorised to make it: that it is the Owner of the key (Table 4) or of the Secure Storage area (4) that the call uses. The Non-Secure Controller relays to the Secure Controller the requests of the Basic API that the User Agent makes, and their replies. What they carry – the requests themselves, the data of the Ports and of the Shared Storage – is encrypted and authenticated end to end between the User Agent and the Secure Controller, with a key they agree when the User Agent calls MPAI_AIFU_Controller_Initialize_Secure (3.1). The Secure Controller serves only the User Agents its User decided, each proving its identity. The Non-Secure Controller never has that key, a key of Secure Storage, a Grant, the content of Secure Storage or the data of the Module.
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 2).
Table 2 – 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). |
The types the functions use are in Table 3.
Table 3 – The types of the Security API
| Type | Meaning |
| error_t | The outcome a function returns: a value of the Basic API (2.3) – in particular MPAI_AIF_OK, MPAI_AIF_NOT_AUTHORISED (the caller is not the Owner of the key or of the area), MPAI_AIF_NOT_FOUND, MPAI_AIF_BUFFER_TOO_SMALL and MPAI_AIF_FAILED – or one of: MPAI_AIF_INVALID_SIGNATURE (a signature, a message authentication code, a hash or an authentication tag does not verify), MPAI_AIF_INSUFFICIENT_ENTROPY (the random generator cannot give the bytes asked), MPAI_AIF_NOT_SUPPORTED (the Implementation does not offer the algorithm or the key type). |
| key_id_t | The identifier of a key: an opaque 32-bit number (Table 4). |
| algorithm_t | An algorithm, named as each section lists it (6.1 to 6.9). |
| flags_t | The flags of a Secure Storage area, set at MPAI_AIFSS_Storage_Init: WRITE_ONCE (the area cannot be written again), NO_CONFIDENTIALITY (the content need not be kept secret), NO_REPLAY_PROTECTION (an earlier content need not be detected), as in the PSA Certified Secure Storage API (References). |
| storage_info_t | The information about a Secure Storage area: its capacity and its size in bytes, and its flags. |
| key_derivation_step_t | An input of a key derivation (6.3): SALT, SECRET or INFO. |
| hash_state_t, mac_state_t, cipher_state_t, aead_state_t, key_derivation_operation_t | The state of an operation in several calls: an opaque object of the Implementation, set up by the first call of the operation and released by its Finish or Abort. |
The data_t structure is used where an Implementation exposes memory locations. An Implementation in a programming language without pointers passes a byte array, and its size, where the functions pass a pointer and a size.
3 Functions called by the User Agent
3.1 MPAI_AIFU_Controller_Initialize_Secure
error_t MPAI_AIFU_Controller_Initialize_Secure()
Switches on and initialises the Controller in the Secure Profile, in particular its Secure Communication component. The Secure Profile always uses Attestation: the Controller gives its Attestation Evidence to the MPAI Store, to the Trust Authorities and to the other Controllers that verify it, and verifies the Attestation Evidence of the AIMs that execute apart from it (Zero Trust and Profiles). The User Agent verifies the Attestation Evidence of the Secure Controller – a token over a challenge that binds the key the Secure Controller agrees – before it agrees with it the key that protects its requests (1).
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. An area belongs to the AIM Instance, the Controller or the User Agent that initialised it – its Owner; the same name used by another caller names another area. Unless an area has the flag NO_REPLAY_PROTECTION, the Implementation detects an earlier content of the area put back, also where the whole of the storage is put back, with a monotonic counter of the root of trust.
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(const uint8_t* challenge, size_t challenge_size,
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, which includes challenge as its nonce claim. challenge is the nonce chosen by the Verifier; its size is 32, 48 or 64 bytes. The token is written into token_buf, of token_buf_size bytes, provided by the caller; token_size receives its size. The token over the challenge of a Verifier is the Attestation Evidence of MPAI-PTF. The token is a COSE_Sign1 signed with the identity key of the party, with the claims: eat_nonce (10), the challenge; ueid (256), the byte 0x01 followed by the SHA-256 of the SubjectPublicKeyInfo of the identity key; iat (6), when the token was made; mpai-party, the identifier of the party, its Trust Anchor; mpai-ptf-evidence, the Attestation Evidence of MPAI-PTF over the same challenge – the quote of the measurements of the code of the party and of the Implementations it loaded, with their log. A Verifier checks the signature with the identity key of the party it expects, the challenge, the UEID, the time and the Attestation Evidence.
5.2 MPAI_AIFAT_Get_Token_Size
error_t MPAI_AIFAT_Get_Token_Size(size_t challenge_size, size_t* token_size)
Returns the size of the buffer that a token over a challenge of challenge_size bytes needs.
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. A hash is computed in one call (6.1.1) or in several (6.1.2 to 6.1.6). hash_state_t is a state object of the Implementation.
6.1.1 MPAI_AIFCR_Hash_Compute
error_t MPAI_AIFCR_Hash_Compute(algorithm_t alg, const uint8_t* input, size_t input_length,
uint8_t* hash, size_t hash_size, size_t* hash_length)
Hashes an input buffer, given in one chunk, into an output buffer.
6.1.2 MPAI_AIFCR_Hash_Setup
error_t MPAI_AIFCR_Hash_Setup(hash_state_t* state, algorithm_t alg)
Sets up a hash of data given in several chunks.
6.1.3 MPAI_AIFCR_Hash_Update
error_t MPAI_AIFCR_Hash_Update(hash_state_t* state, const uint8_t* input, size_t input_length)
Adds a chunk of data to the hash; it may be repeated until the data is complete. The Implementation releases control to the rest of the system at the end of each chunk.
6.1.4 MPAI_AIFCR_Hash_Finish
error_t MPAI_AIFCR_Hash_Finish(hash_state_t* state, uint8_t* hash, size_t hash_size, size_t* hash_length)
Finishes the hash, returns it and releases the resources of the operation.
6.1.5 MPAI_AIFCR_Hash_Verify
error_t MPAI_AIFCR_Hash_Verify(hash_state_t* state, const uint8_t* hash, size_t hash_length)
Finishes the hash and verifies it against the given hash; returns MPAI_AIF_INVALID_SIGNATURE where they differ.
6.1.6 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 4.
Table 4 – 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, CHACHA20 (a 256-bit key of ALG_CHACHA20_POLY1305, 6.6), DES, RSA, ECC or DH. |
| Bits | The size of the key in bits: of an AES, CHACHA20, HMAC, RAW_DATA, DERIVE or PASSWORD key, its length; of an ECC key, the size of its curve (256, 384 or 521, the NIST curves); of an RSA key, the size of its modulus (2048 or more). Required to generate or derive a key; set by MPAI_AIFKM_Import_Key from the data where the caller gives 0. |
| 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. |
| Owner | The AIM Instance, the Controller or the User Agent that generated or imported the key, set by the Secure Controller, not by the caller. Only the Owner uses the key. MPAI_AIFKM_Copy_Key gives a copy to another Owner only where the Policy has COPY and the Controller authorises it. |
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. The attributes may name another Owner for the copy, which the Secure Controller sets only where the Policy of the source key has COPY and the Controller authorises it.
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 the SECRET input of a key derivation set up with MPAI_AIFKD_Setup.
6.3.3 MPAI_AIFKD_Setup
error_t MPAI_AIFKD_Setup(key_derivation_operation_t* operation, algorithm_t alg)
Sets up a key derivation. Algorithms: HKDF with SHA-256 at least (References).
6.3.4 MPAI_AIFKD_Input_Bytes
error_t MPAI_AIFKD_Input_Bytes(key_derivation_operation_t* operation, key_derivation_step_t step,
const uint8_t* data, size_t data_length)
Gives the derivation an input: its SALT, its SECRET (where 6.3.2 does not give it) or its INFO.
6.3.5 MPAI_AIFKD_Output_Key
error_t MPAI_AIFKD_Output_Key(const key_attributes_t* attributes, key_derivation_operation_t* operation,
key_id_t* key)
Derives a key with the given attributes; the caller is its Owner (Table 4).
6.3.6 MPAI_AIFKD_Abort
error_t MPAI_AIFKD_Abort(key_derivation_operation_t* operation)
Aborts a key derivation and releases its resources.
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. Algorithms: ALG_HMAC_SHA_256, ALG_HMAC_SHA_384 and ALG_HMAC_SHA_512 (References), with a key of type HMAC. 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_CTR, AIF_ALG_ECB_NO_PADDING, AIF_ALG_CBC_NO_PADDING and AIF_ALG_CBC_PKCS7 (References). AIF_ALG_ECB_NO_PADDING is used only on data of one block. Data exchanged between AIMs, and data written to storage, is encrypted with an algorithm of 6.6, which also authenticates it; the algorithms of 6.5 are used only where authentication is provided otherwise. Where a multiblock cipher is used, the developer manages the initialisation vector (IV): generates it with MPAI_AIFRNG_Generate_Random (6.9); 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, the caller of MPAI_AIFCIP_Encrypt_Setup either gives it in iv, generated with MPAI_AIFRNG_Generate_Random, or passes in iv a buffer of iv_size bytes with *iv_length 0, in which the Implementation writes the IV it generates, and its size in iv_length. MPAI_AIFCIP_Decrypt_Setup always takes the IV in iv. cipher_state_t is a state object of the Implementation.
6.5.1 MPAI_AIFCIP_Encrypt_Setup
error_t MPAI_AIFCIP_Encrypt_Setup(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_Setup
error_t MPAI_AIFCIP_Decrypt_Setup(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_Setup or MPAI_AIFCIP_Decrypt_Setup. 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).
6.7.1 MPAI_AIFSIGN_Sign_Message
error_t MPAI_AIFSIGN_Sign_Message(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(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). RSA_PKCS1V15_CRYPT is used only to interoperate with existing systems; new uses use RSA_OAEP.
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.
6.9 Random generation
The initialisation vectors of 6.5, the nonces of 6.6, the salts of 6.8 and the challenges of 5.1 are generated by this function.
6.9.1 MPAI_AIFRNG_Generate_Random
error_t MPAI_AIFRNG_Generate_Random(uint8_t* output, size_t output_size)
Fills output with output_size random bytes from the cryptographically secure random generator of the root of trust.
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.