.. _psa_to_sl_porting-guide:

Platform Security Architecture (PSA)
====================================

PSA Certified APIs are open-source programming interfaces that provide 
developers with a trusted code base that complies with platform security 
specifications. The APIs are designed to be easy to use and provide interfaces 
to basic security functions, such as secure storage, crypto, and attestation. 

PSA Certified APIs also create a consistent interface to the underlying 
Root of Trust hardware, allowing software vendors to easily port to multiple 
chips and chips to port to multiple software platforms. PSA Cryptography API 
provides encrypt/decrypt, sign/verify, key management and derivation, hash, RNG, 
and key storage services with support for different key lifetime policies.

For more information regarding the PSA API please refer to the 
`PSA Certified Crypto API <https://developer.arm.com/documentation/ihi0086/latest/>`_.

SimpleLink API to PSA Mapping 
-----------------------------

.. note::
    The PSA wrapper does not require any crypto driver instances to be added to
    Sysconfig. If the developer wants to use the LAES engine, then the crypto
    driver instances are needed. 

+------------------------------------------+----------------------------------+
| SimpleLink API                           | PSA API                          |
+==========================================+==================================+
| AESCMAC_init + SHA2_init + ECDH_init +   | psa_crypto_init                  |
| AESCBC_init + AESECB_init, AESCTR_init + |                                  |
| AESCCM_init + AESGCM_init + ECDSA_init + |                                  |
| RNG_init                                 |                                  |
+------------------------------------------+----------------------------------+
| N/A                                      | psa_key_attributes_init          |
+------------------------------------------+----------------------------------+
| N/A                                      | psa_get_key_attributes           |                     
+------------------------------------------+----------------------------------+
| N/A                                      | psa_reset_key_attributes         |
+------------------------------------------+----------------------------------+
| N/A                                      | psa_set_key_type                 |
+------------------------------------------+----------------------------------+
| N/A                                      | psa_get_key_bits                 |
+------------------------------------------+----------------------------------+
| N/A                                      | psa_set_key_bits                 |
+------------------------------------------+----------------------------------+
| N/A                                      | psa_set_key_lifetime             |
+------------------------------------------+----------------------------------+
| N/A                                      | psa_get_key_lifetime             |
+------------------------------------------+----------------------------------+
| N/A                                      | psa_set_key_id                   |
+------------------------------------------+----------------------------------+
| N/A                                      | psa_get_key_id                   |
+------------------------------------------+----------------------------------+
| N/A                                      | psa_set_key_algorithm            |
+------------------------------------------+----------------------------------+
| N/A                                      | psa_get_key_algorithm            |
+------------------------------------------+----------------------------------+
| N/A                                      | psa_set_key_usage_flags          |
+------------------------------------------+----------------------------------+
| N/A                                      | psa_get_key_usage_flags          |
+------------------------------------------+----------------------------------+
| N/A                                      | psa_import_key                   |
+------------------------------------------+----------------------------------+
| RNG_getRandomBits                        | psa_generate_key                 |
+------------------------------------------+----------------------------------+
| N/A                                      | psa_copy_key                     |
+------------------------------------------+----------------------------------+
| N/A                                      | psa_destroy_key                  |
+------------------------------------------+----------------------------------+
| N/A                                      | psa_purge_key                    |
+------------------------------------------+----------------------------------+
| N/A                                      | psa_export_key                   |
+------------------------------------------+----------------------------------+
| N/A                                      | psa_export_public_key            |
+------------------------------------------+----------------------------------+
| Message Digests                                                             |
|                                                                             |
| Supported Algorithms:                                                       |
|                                                                             |
| - PSA_ALG_SHA_224                                                           |
| - PSA_ALG_SHA_256                                                           |
| - PSA_AL_SHA_384                                                            |
| - PSA_ALG_SHA_512                                                           |
|                                                                             |
| Unsupported Algorithms:                                                     |
|                                                                             |
| - PSA_ALG_MD2                                                               |
| - PSA_ALG_MD4                                                               |
| - PSA_ALG_MD5                                                               |
| - PSA_ALG_RIPEMD160                                                         |
| - PSA_ALG_SHA_1                                                             |
| - PSA_ALG_SHA_512_224                                                       |
| - PSA_ALG_SHA_512_256                                                       |
| - PSA_ALG_SHA3_256                                                          |
| - PSA_ALG_SHA3_384                                                          |
| - PSA_ALG_SHA3_512                                                          |
| - PSA_ALG_SM3                                                               |
+------------------------------------------+----------------------------------+
| SHA2_hashData                            | psa_hash_compute                 |
+------------------------------------------+----------------------------------+
| SHA2_hashData + Assertion                | psa_hash_compare                 |
+------------------------------------------+----------------------------------+
| N/A                                      | psa_hash_operation_init          |
+------------------------------------------+----------------------------------+
| SHA2_setHashType                         | psa_hash_setup                   |
+------------------------------------------+----------------------------------+
| SHA2_addData                             | psa_hash_update                  |
+------------------------------------------+----------------------------------+
| SHA2_finalize                            | psa_hash_finish                  |
+------------------------------------------+----------------------------------+
| SHA2_finalize + Assertion                | psa_hash_verify                  |
+------------------------------------------+----------------------------------+
| SHA2_cancelOperation                     | psa_hash_abort                   |
+------------------------------------------+----------------------------------+
| SHA2_cancelOperation                     | psa_hash_suspend                 |
|                                          |                                  | 
| Note: HSM SHA2 driver may store a full   |                                  |
| block of data for finalization. This is  |                                  |
| not supported by the PSA API             |                                  |
| specification for psa_hash_suspend.      |                                  |
| PSA_ERROR_NOT_SUPPORTED will be returned |                                  |
| in this particular case. Hash            |                                  |
| suspend/resume with an unprocessed data  |                                  |
| with an unprocessed data length of 0 to  |                                  |
| (block_size - 1) will be supported.      |                                  |
+------------------------------------------+----------------------------------+
| N/A                                      | psa_hash_resume                  |
+------------------------------------------+----------------------------------+
| SHA2_construct with another instance with| psa_hash_clone                   |
| the same setup.                          |                                  |
+------------------------------------------+----------------------------------+
| Message Authentication Codes (MAC)                                          |
|                                                                             |
| Unsupported Algorithms:                                                     |
|                                                                             |
| - PSA_ALG_HMAC (coming in future release)                                   |
| - PSA_ALG_CMAC (coming in future release)                                   |
| - PSA_ALG_CBC_CMAC (coming in future release)                               |
+-----------------------------------------+-----------------------------------+
| KeyStore_PSA_initKey +                  | psa_mac_compute                   |
| SHA2_hmac/AESCMAC_oneStepSign           |                                   |
+-----------------------------------------+-----------------------------------+
| KeyStore_PSA_initKey +                  | psa_mac_verify                    |
| SHA2_hmac/AESCMAC_oneStepVerify         |                                   |
+-----------------------------------------+-----------------------------------+
| N/A                                     | psa_mac_operation_init            |
+-----------------------------------------+-----------------------------------+
| KeyStore_PSA_initKey +                  | psa_mac_sign_setup                |
| (SHA2_setupHmac + SHA2_setHashType)     |                                   |
|                                         |                                   |
| - AESCMAC_setupSign                     |                                   |
+-----------------------------------------+-----------------------------------+
| SHA2_setupHmac + SHA2_setHashType/      | psa_mac_verify_setup              |
| AESCMAC_setupVerify                     |                                   |
+-----------------------------------------+-----------------------------------+
| - SHA2_addData                          | psa_mac_update                    |
| - AESCMAC_addData                       |                                   |
+-----------------------------------------+-----------------------------------+
| - SHA2_finalizeHmac                     | psa_mac_sign_finish               |
| - AESCMAC_finalize                      |                                   |
+-----------------------------------------+-----------------------------------+
| - SHA2_finalizeHmac                     | psa_mac_verify_finish             |
| - AESCMAC_finalize                      |                                   |
+-----------------------------------------+-----------------------------------+
| - SHA2_reset                            | psa_mac_abort                     |
| - AESCMAC_cancelOperation               |                                   |
+-----------------------------------------+-----------------------------------+
| Unauthenticated Ciphers:                                                    |
|                                                                             |
| Supported Algorithms:                                                       |
|                                                                             |
| - PSA_ALG_ECB_NO_PADDING                                                    |
| - PSA_ALG_CBC_NO_PADDING                                                    |
| - PSA_ALG_CTR                                                               |
|                                                                             |
| Unsupported Algorithms:                                                     |
|                                                                             |
| - PSA_ALG_STREAM_CIPHER                                                     |
| - PSA_ALG_CFB                                                               |
| - PSA_ALG_OFB                                                               |
| - PSA_ALG_XTS                                                               |
| - PSA_ALG_CBC_PKCS7                                                         |
+-----------------------------------------+-----------------------------------+
| KeyStore_PSA_initKey +                  |  psa_cipher_encrypt               |
|                                         |                                   |
| - AESECB_oneStepEncrypt                 |                                   |
| - AESCBC_oneStepEncrypt                 |                                   |
| - AESCTR_setupEncrypt                   |                                   |
+-----------------------------------------+-----------------------------------+
| KeyStore_PSA_initKey +                  |   psa_cipher_decrypt              |
|                                         |                                   |
| - AESECB_oneStepDecrypt                 |                                   |
| - AESCBC_oneStepDecrypt                 |                                   |
| - AESCTR_setupDecrypt                   |                                   |
+-----------------------------------------+-----------------------------------+
| N/A                                     | psa_cipher_operation_init         |
+-----------------------------------------+-----------------------------------+
| KeyStore_PSA_initKey +                  |  psa_cipher_encrypt_setup         |
|                                         |                                   |
| - AESECB_setupEncrypt                   |                                   |
| - AESCBC_setupEncrypt                   |                                   |
| - AESCTR_setupEncrypt                   |                                   |
+-----------------------------------------+-----------------------------------+
| KeyStore_PSA_initKey +                  |  psa_cipher_decrypt_setup         |
|                                         |                                   |
| - AESECB_setupDecrypt                   |                                   |
| - AESCBC_setupDecrypt                   |                                   |
| - AESCTR_setupDecrypt                   |                                   |
+-----------------------------------------+-----------------------------------+
| RNG_getRandomBits +                     | psa_cipher_generate_iv            |
|                                         |                                   |
| - AESCBC_setIV                          |                                   |
| - AESCTR_setupEncrypt +                 |                                   |
|   AESCTR_setupDecrypt                   |                                   |
+-----------------------------------------+-----------------------------------+
| - AESCBC_setIV                          | psa_cipher_set_iv                 |
+-----------------------------------------+-----------------------------------+
| - AESECB_addData                        | psa_cipher_update                 |
| - AESCBC_addData                        |                                   |
| - AESCTR_addData                        |                                   |
+-----------------------------------------+-----------------------------------+
| - AESECB_finalize                       | psa_cipher_finish                 |
| - AESCBC_finalize                       |                                   |
| - AESCTR_finalize                       |                                   |
+-----------------------------------------+-----------------------------------+
| - AESECB_cancelOperation                | psa_cipher_abort                  | 
| - AESCBC_cancelOperation                |                                   |
| - AESCTR_cancelOperation                |                                   |
+-----------------------------------------+-----------------------------------+
| Authenticated Encryption with Associated Data (AEAD)                        |
|                                                                             |
| Supported Algorithms:                                                       |
|                                                                             |
| - PSA_ALG_CCM                                                               |
| - PSA_ALG_AEAD_WITH_SHORTENED_TAG                                           |
| - PSA_ALG_GCM                                                               |
|                                                                             |
| Unsupported Algorithms:                                                     |
|                                                                             |
| - PSA_ALG_CHACHA20_POLY1305                                                 |
+-----------------------------------------+-----------------------------------+
| KeyStore_PSA_initKey +                  | psa_aead_encrypt                  |
|                                         |                                   |
| - AESCCM_Operation_init                 |                                   | 
| - AESGCM_Operation_init                 |                                   |
| - AESGCM_oneStepEncrypt                 |                                   |
| - AESCCM_oneStepEncrypt                 |                                   |
+-----------------------------------------+-----------------------------------+
| KeyStore_PSA_initKey +                  | psa_aead_decrypt                  |
|                                         |                                   |
| - AESCCM_Operation_init                 |                                   | 
| - AESGCM_Operation_init                 |                                   |
| - AESGCM_oneStepDecrypt                 |                                   |
| - AESCCM_oneStepDecrypt                 |                                   |
+-----------------------------------------+-----------------------------------+
| N/A                                     | psa_aead_operation_init           |
+-----------------------------------------+-----------------------------------+
| - AESCCM_setupEncrypt                   | psa_aead_encrypt_setup            |
| - AESGCM_setupEncrypt                   |                                   |
| - KeyStore_PSA_initKey                  |                                   |
+-----------------------------------------+-----------------------------------+
| - AESCCM_setupDecrypt                   | psa_aead_decrypt_setup            |
| - AESGCM_setupDecrypt                   |                                   |
| - KeyStore_PSA_initKey                  |                                   |
+-----------------------------------------+-----------------------------------+
| - AESCCM_setLengths                     | psa_aead_set_lengths              |
| - AESGCM_setLengths                     |                                   |
+-----------------------------------------+-----------------------------------+
| - RNG_getRandomBits                     | psa_aead_generate_nonce           |
+-----------------------------------------+-----------------------------------+
| - AESCCM_setNonce                       | psa_aead_set_nonce                |
| - AESGCM_setIV                          |                                   |
+-----------------------------------------+-----------------------------------+
| - AESCCM_addAAD                         | psa_aead_update_ad                |
| - AESGCM_addAAD                         |                                   |
+-----------------------------------------+-----------------------------------+
| - AESCCM_addData                        | psa_aead_update                   |
| - AESGCM_addData                        |                                   |
+-----------------------------------------+-----------------------------------+
| - AESCCM_finalizeEncrypt                | psa_aead_finish                   |
| - AESGCM_finalizeEncrypt                |                                   |
+-----------------------------------------+-----------------------------------+
| - AESCCM_finalizeDecrypt                | psa_aead_verify                   |
| - AESGCM_finalizeDecrypt + Assertion of |                                   |
|   tag                                   |                                   |
+-----------------------------------------+-----------------------------------+
| - AESCMM_close + AESCCM_open            | psa_aead_abort                    |
| - AESGCM_close + AESGCM_open            |                                   |
+-----------------------------------------+-----------------------------------+
| Key Derivation                                                              |
|                                                                             |
| Supported Algorithms:                                                       |
|                                                                             |
| - PSA_ALGO_SP800_108_COUNTER_CMAC                                           |
| - PSA_ALG_SP800_108_COUNTER_HMAC                                            |
|                                                                             |
| Unsupported Algorithms:                                                     |
|                                                                             |
| - PSA_ALG_HKDF                                                              |
| - PSA_ALG_TLS12_PRF                                                         |
| - PSA_ALG_TLS12_PSK_TO_MS                                                   |
+-----------------------------------------+-----------------------------------+
| N/A                                     | psa_key_derivation_operation_init |
+-----------------------------------------+-----------------------------------+
| N/A                                     | psa_key_derivation_setup          |
+-----------------------------------------+-----------------------------------+
| N/A                                     | psa_key_derivation_get_capacity   |
+-----------------------------------------+-----------------------------------+
| N/A                                     | psa_key_derivation_set_capacity   |
+-----------------------------------------+-----------------------------------+
| N/A                                     | psa_key_derivation_input_bytes    |
+-----------------------------------------+-----------------------------------+
| N/A                                     | psa_key_derivation_input_key      |
+-----------------------------------------+-----------------------------------+
| N/A                                     | psa_key_derivation_output_bytes   |
+-----------------------------------------+-----------------------------------+
| N/A                                     | psa_key_derivation_output_key     |
+-----------------------------------------+-----------------------------------+
| N/A                                     | psa_key_derivation_abort          |
+-----------------------------------------+-----------------------------------+
| Asymmetric Signature                                                        |
|                                                                             |
| Supported Algorithms:                                                       |
|                                                                             |
| - PSA_ALG_ECDSA                                                             |
| - PSA_ALG_ED25519PH                                                         |
|                                                                             |
| Supported Curves:                                                           |
|                                                                             |
| - NIST P224                                                                 |
| - NIST P256                                                                 |
| - NIST P384                                                                 |
| - NIST P521                                                                 |
| - Brainpool P256R1                                                          |
| - Brainpool P384R1                                                          |
| - Brainpool P512R1                                                          |
| - Curve25519                                                                |
|                                                                             |
| Unsupported Algorithms:                                                     |
|                                                                             |
| - PSA_ALG_DETERMINISTIC_ECDSA                                               |
| - PSA_ALG_RSA_PKCS1V15_SIGN                                                 |
| - PSA_ALG_RSA_PKCS1V15_SIGN_RAW                                             |
| - PSA_ALG_RSA_PSS                                                           |
+-----------------------------------------+-----------------------------------+
| - KeyStore_PSA_initKey                  | psa_sign_message                  |
| - EDDSA_sign                            |                                   |
| - ECDSA_sign + Sha2_hashData            |                                   |
+-----------------------------------------+-----------------------------------+
| - KeyStore_PSA_initKey                  | psa_verify_message                |
| - ECDSA_verify + Sha2_hashData          |                                   |     
+-----------------------------------------+-----------------------------------+
| - KeyStore_PSA_initKey                  | psa_sign_hash                     |
| - ECDSA_sign                            |                                   |
+-----------------------------------------+-----------------------------------+
| - KeyStore_PSA_initKey                  | psa_verify_hash                   |
| - ECDSA_verify                          |                                   |
+-----------------------------------------+-----------------------------------+
| Asymmetric Encryption                                                       |
|                                                                             |
| Supported Algorithms: None.                                                 |
|                                                                             |
| Unsupported Algorithms:                                                     |
|                                                                             |
| - PSA_ALG_RSA_PKCS1V15_CRYPT                                                |
| - PSA_ALG_RSA_OAEP                                                          |
|                                                                             |
+-----------------------------------------+-----------------------------------+
| No Support                              | psa_asymmetric_encrypt            |
+-----------------------------------------+-----------------------------------+
| No Support                              | psa_asymmetric_decrypt            |
+-----------------------------------------+-----------------------------------+
| Key Agreement                                                               |
|                                                                             |
| Supported Algorithms:                                                       |
|                                                                             |
| - PSA_ALG_ECDH                                                              |
|                                                                             |
| Unsupported Algorithms:                                                     |
|                                                                             |
| - PSA_ALG_FFDH                                                              |
|                                                                             |
| Supported Curves:                                                           |
|                                                                             |
| - NIST P224                                                                 |
| - NIST P256                                                                 |
| - NIST P384                                                                 |
| - NIST P521                                                                 |
| - Brainpool P256R1                                                          |
| - Brainpool P384R1                                                          |
| - Brainpool P512R1                                                          |
| - Curve25519                                                                |
+-----------------------------------------+-----------------------------------+
| ECDH_computerShareSecret +              | psa_raw_key_agreement             |
| KeyStore_PSA_initKey +                  |                                   |
| CryptoKeyPlaintext_initKey              |                                   |
+-----------------------------------------+-----------------------------------+
| RNG_getRandomBits                       | psa_generate_random               |
+-----------------------------------------+-----------------------------------+
| N/A                                     | psa_key_derivation_key_agreement  |
+-----------------------------------------+-----------------------------------+
