<- Basic API Go to ToC Profiles ->
1 Data characterisation structure
These API are intended to support developers who need a secure environment. They are divided into two parts: the first part includes APIs whose calls are executed in the non-secure area and the second part APIs whose calls that are executed in the secure area.
Data, independently from its usage (as a key, an encrypted payload, plain text, etc.) will be passed to/from the APIs through data_t structure.
The data_t structure shall include the following fields:
- data_location_t location
the identifier of the location of the data (see data_location_t below).
- void* data
the pointer (within the location specified above) to the start of the data/
- size_t size
the size of the data (in bytes).
- data_flags_t flags
other flags characterizing data.
The data_location_t is uint32_t type and can take one of the following symbolic values:
- DATA_LOC_RAM
- DATA_LOC_EXT_FLASH
- DATA_LOC_INT_FLASH
- DATA_LOC_LOCAL_DISK
- DATA_LOC_REMOTE_DISK
The data_flags_t is uint32_t type and can take one of the following symbolic values:
- DATA_FLAG_Encrypted
- DATA_FLAG_plain
- DATA_FLAG_UNKNOWN
2 API called by User Agent
User Agents calls Connect to Controller API
| error_t MPAI_AIFU_Controller_Initialize_Secure(bool useAttestation) |
This function, called by the User Agent, switches on and initialises the Controller, in particular the Secure Communication Component.
- Start AIW
- Suspend
- Resume
- Stop
3 API to access Secure Storage
In the following stringname is a symbolic name of the security memory area.
3.1 User Agent initialises Secure Storage API
| Error_t MPAI_AIFSS_Storage_Init(string_t stringname, size_t data_length, const p_data_t data, flags_t flags flags) |
Flags specify the initialisation behaviour.
3.2 User Agent writes Secure Storage API
| Error_t MPAI_AIFSS_Storage_Write(string_t stringname, size_t data_length, const p_data_t data, flags_t flags flags) |
Flags specify the write behaviour.
3.3 User Agent reads Secure Storage API
| Error_t MPAI_AIFSS_Storage_Read(string_t stringname, size_t data_length,const p_data_t data, flags_t flags flags) |
Flags specify the read behaviour.
3.4 User Agent gets info from Secure Storage API
| Error_t MPAI_AIFSS_Storage_Getinfo(string_t stringname, struct storage_info_t * p_info) |
3.5 User Agent deletes a p_data in Secure Storage API
| Error_t MPAI_AIFSS_Storage_Delete(string_t stringname) |
We assume that there is a mechanism that takes a stringname of type string and maps to a numeric uid
4 API to access Attestation
Controller Trusted Service Attestation call (part of the Trusted Services API)
| Error_t MPAI_AIFAT_Get_Token(uint8_t *token_buf, size_t token_buf_size,size_t *token_size) |
Token Buffer and Token Manage are managed by the code of the API implementation.
Based on CBOR [13], COSE [14] and EAT [15] standards.
5 API to access cryptographic functions
5.1 Hashing
There are many different hashing algorithms in use today, but some of the most common ones include:
- SHA (Secure Hash Algorithm) [24]: A family of hash functions developed by the US National Security Agency (NSA). The most widely used members of this family are SHA-1 and SHA-256, both of which are commonly used to generate digital signatures and verify data integrity.
- MD5 (Message-Digest Algorithm 5) [17]: A widely used hash function that produces 128-bit hash values. Although it is widely used, it is not considered secure and has been replaced by more secure hash functions in many applications.
Hash_state_t state object type
Implementation dependent
| Error_t MPAI_AIFCR_Hash(Hash_state_t * state, algorithm_t alg, const uint8_t * hash, size_t * hash_length, size_t hash_size, const uint8_t * input, size_t input_length) |
Perform a hash operation on an input data buffer producing the resulting hash in an output buffer. The encryption engine provides support for encryption/decryption of data of arbitrary size by processing it either in one chunk or multiple chunks. Implementation note: encryption engine should be efficient and release control to the rest of the system on a regular basis (e.g., at the end of a chunk computation).
| 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) |
Perform a hash verification operation checking the hash against an input buffer.
| Error_t MPAI_AIFCR_Hash_abort(Hash_state_t * state) |
Abort operation and release internal resources.
5.2 Key management
Description:
- Applications access keys indirectly via an identifier
- Operations performed using a key without accessing the key material
If a key is externally provided it needs to map to the format below.
The key data is organised in a data structure that includes identifiers, the data itself, and the type of data as indicated below. The p_data structure includes information regarding the location where the key is stored.
5.2.1 MPAI_AIFKM_attributes_t structure
- Identifier (number)
- p_data (structure)
- Type:
- RAW_DATA (none)
- HMAC (hash)
- DERIVE
- PASSWORD (key derivation)
- AES
- DES
- RSA (asymmetric RSA cipher)
- ECC
- DH (asymmetric DH key exchange).
- Lifetime
- persistence level
- volatile keys → lifetime AIF_KEY_LIFETIME_VOLATILE, stored in RAM
- persistent keys → lifetime AIF_KEY_LIFETIME_PERSISTENT, stored in primary local storage or primary secure element.
- Policy
- set of usage flags + permitted algorithm
- permitted algorithms → restrict to a single algorithm, types: NONE or specific algorithm
- usage flags → EXPORT, COPY, CACHE, ENCRYPT, DECRYPT, SIGN_MESSAGE, VERIFY_MESSAGE, SIGN_HASH, VERIFY_HASH, DERIVE, VERIFY_DERIVATION
| Error_t MPAI_AIFKM_import_key(const key_attributes_t * attributes, const uint8_t * data, size_t data_length, key_id_t * key) |
When importing a key as a simple binary value, it is the responsibility of the programmer to fill in the attributes data structure. The identifier inside the attributes data structure will be internally generated as a response to the API call.
| Error_t MPAI_AIFKM_generate_key(const attributes_t * attributes, key_id_t * key) |
Generate key randomly.
| Error_t MPAI_AIFKM_copy_key(key_id_t source_key, const key_attributes_t * attributes, key_id_t * target_key) |
Copy key randomly.
| Error_t MPAI_AIFKM_destroy_key(key_id_t key) |
Destroy key.
| Error_t MPAI_AIFKM_export_key(key_id_t key, uint8_t * data, size_t data_size, size_t * data_length) |
Export key to output buffer.
| Error_t MPAI_AIFKM_export_public_key(key_id_t key, uint8_t * data, size_t data_size, size_t * data_length); |
Export public key to output buffer.
5.3 Key exchange
Algorithms: FFDH (finite-field Diffie-Hellman) [20], ECDH (elliptic curve Diffie-Hellman) [23]
| 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) |
Return the raw shared secret.
| 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) |
Key agreement and use the shared secret as input to a key derivation.
5.4 Message Authentication Code
The code is a cryptographic checksum on data. It uses a session key with the goal to detect any modification of the data. It requires the data and the shared session key known to the data originator and recipients. The cryptographic algorithms of algorithm_t are the same as defined above.
mac_state_t
Implementation dependent.
| error_t MPAI_AIFMAC_sign_setup(mac_state_t * state, key_id_t key, algorithm_t alg) |
Setup MAC sign operation.
| error_t MPAI_AIFMAC_verify_setup(mac_state _t * state, key_id_t key, algorithm_t alg) |
Setup MAC verify operation.
| error_t MPAI_AIFMAC_update(mac_state_t * state, const uint8_t * input, size_t input_length) |
Compute MAC for a chunk of data (can be repeated several times until completion of data).
| error_t MPAI_AIFMAC_mac_sign_finish(mac_state_t * state, uint8_t * mac, size_t mac_size, size_t * mac_length) |
Finish MAC sign operation.
| error_t MPAI_AIFMAC_mac_verify_finish(mac_state_t * state, const uint8_t * mac, size_t mac_length) |
Finish MAC verify operation at receiver side.
| error_t MPAI_AIFMAC_mac_abort(mac_state_t * state) |
Abort MAC operation.
5.5 Cyphers
MPAI-AIF V2 assumes that, in case multiblock cipher is used, the developer shall manage the IV parameter by explicitly generating the IV, i.e.:
- Not relying on a service doing that for them.
- Securely communicating the IV to the parties receiving the message, and
- If the IV is not disposed of, storing the IV in the Secure Storage.
Algorithms: AIF_ALG_XTS [16], AIF_ALG_ECB_NO_PADDING [25], AIF_ALG_CBC_NO_PADDING [25], AIF_ALG_CBC_PKCS7 [25]
In the following API calls, the IV parameter and IV size shall be set to NULL if not needed by the specific call. An IV shall securely generated by the API implementation in case the encryption algorithm needs an IV and NULL is passed to the API.
cipher_state_t
State object type (implementation dependent). In future version the state type may be defined.
| 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) |
Setup symmetric encryption.
| 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) |
Setup symmetric decryption.
| Error_t MPAI_AIFCIP_Abort(cipher_state_t * state) |
Abort symmetric encryption/decryption.
5.6 Authenticated encryption with associated data (AEAD)
Algorithms: ALG_GCM [26], ALG_CHACHA20_POLY1305 [19].
PSA_ALG_GCM requires a nonce of at least 1 byte in length.
aead_state_t
state object type (implementation dependent). In future version the state type may be defined.
| 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) |
| 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) |
| Error_t MPAI_AIFEAD_Abort(aead_state_t * state) |
5.7 Signature
Algorithms: RSA_PKCS1V15_SIGN [21], RSA_PSS [21], ECDSA [18], PURE_EDDSA [22].
sign_state_t
State object type (implementation dependent). In future version the state type may be defined.
| 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) |
Sign a message with a private key (for hash-and-sign algorithms, this includes the hashing step).
| 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) |
Verify a signature with a public key (for hash-and-sign algorithms, this includes the hashing step).
| psa_status_t psa_sign_hash(psa_key_id_t key, psa_algorithm_t alg, const uint8_t * hash, size_t hash_length, uint8_t * signature, size_t signature_size, size_t * signature_length) |
Sign an already-calculated hash with a private key.
| psa_status_t psa_verify_hash(psa_key_id_t key, psa_algorithm_t alg, const uint8_t * hash, size_t hash_length, const uint8_t * signature,
size_t signature_length) |
Verify the signature of a hash.
5.8 Asymmetric Encryption
Algorithms: RSA_PKCS1V15_CRYPT [21], RSA_OAEP [21].
| psa_status_t psa_asymmetric_encrypt(psa_key_id_t key, psa_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) |
Encrypt a short message with a public key.
| psa_status_t psa_asymmetric_decrypt(psa_key_id_t key, psa_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) |
Decrypt a short message with a private key.
6 API to enable secure communication
An implementer should rely on the CoAP and HTTPS support provided by secure transport libraries for the different programming languages.
