About this document
Release information
The change history table lists the changes that have been made to this document.
| Date | Version | Confidentiality | Change |
|---|---|---|---|
| January 2019 | 1.0 Beta 1 | Non-confidential | First public beta release. |
| February 2019 | 1.0 Beta 2 | Non-confidential | Update for release with other PSA Dev API specifications. |
| May 2019 | 1.0 Beta 3 | Non-confidential | Update for release with other PSA API specifications. |
| February 2020 | 1.0 Final | Non-confidential | 1.0 API finalized. |
| August 2020 | 1.0.1 Final | Non-confidential | Update to fix errors and provide clarifications. |
| February 2022 | 1.1.0 Final | Non-confidential | New API for EdDSA, password hashing and key stretching. Many significant clarifications and improvements across the documentation. |
The detailed changes in each release are described in Document change history.
PSA Cryptography API
Copyright © 2018-2022, Arm Limited or its affiliates. All rights reserved. The copyright statement reflects the fact that some draft issues of this document have been released, to a limited circulation.
Arm Non-Confidential Document Licence (“Licence”)
This Licence is a legal agreement between you and Arm Limited (“Arm”) for the use of Arm’s intellectual property (including, without limitation, any copyright) embodied in the document accompanying this Licence (“Document”). Arm licenses its intellectual property in the Document to you on condition that you agree to the terms of this Licence. By using or copying the Document you indicate that you agree to be bound by the terms of this Licence.
“Subsidiary” means any company the majority of whose voting shares is now or hereafter owner or controlled, directly or indirectly, by you. A company shall be a Subsidiary only for the period during which such control exists.
This Document is NON-CONFIDENTIAL and any use by you and your Subsidiaries (“Licensee”) is subject to the terms of this Licence between you and Arm.
Subject to the terms and conditions of this Licence, Arm hereby grants to Licensee under the intellectual property in the Document owned or controlled by Arm, a non-exclusive, non-transferable, non-sub-licensable, royalty-free, worldwide licence to:
- use and copy the Document for the purpose of designing and having designed products that comply with the Document;
- manufacture and have manufactured products which have been created under the licence granted in (i) above; and
- sell, supply and distribute products which have been created under the licence granted in (i) above.
Licensee hereby agrees that the licences granted above shall not extend to any portion or function of a product that is not itself compliant with part of the Document.
Except as expressly licensed above, Licensee acquires no right, title or interest in any Arm technology or any intellectual property embodied therein.
THE DOCUMENT IS PROVIDED “AS IS”. ARM PROVIDES NO REPRESENTATIONS AND NO WARRANTIES, EXPRESS, IMPLIED OR STATUTORY, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTABILITY, SATISFACTORY QUALITY, NON-INFRINGEMENT OR FITNESS FOR A PARTICULAR PURPOSE WITH RESPECT TO THE DOCUMENT. Arm may make changes to the Document at any time and without notice. For the avoidance of doubt, Arm makes no representation with respect to, and has undertaken no analysis to identify or understand the scope and content of, third party patents, copyrights, trade secrets, or other rights.
NOTWITHSTANDING ANYTHING TO THE CONTRARY CONTAINED IN THIS LICENCE, TO THE FULLEST EXTENT PERMITTED BY LAW, IN NO EVENT WILL ARM BE LIABLE FOR ANY DAMAGES, IN CONTRACT, TORT OR OTHERWISE, IN CONNECTION WITH THE SUBJECT MATTER OF THIS LICENCE (INCLUDING WITHOUT LIMITATION) (I) LICENSEE’S USE OF THE DOCUMENT; AND (II) THE IMPLEMENTATION OF THE DOCUMENT IN ANY PRODUCT CREATED BY LICENSEE UNDER THIS LICENCE). THE EXISTENCE OF MORE THAN ONE CLAIM OR SUIT WILL NOT ENLARGE OR EXTEND THE LIMIT. LICENSEE RELEASES ARM FROM ALL OBLIGATIONS, LIABILITY, CLAIMS OR DEMANDS IN EXCESS OF THIS LIMITATION.
This Licence shall remain in force until terminated by Licensee or by Arm. Without prejudice to any of its other rights, if Licensee is in breach of any of the terms and conditions of this Licence then Arm may terminate this Licence immediately upon giving written notice to Licensee. Licensee may terminate this Licence at any time. Upon termination of this Licence by Licensee or by Arm, Licensee shall stop using the Document and destroy all copies of the Document in its possession. Upon termination of this Licence, all terms shall survive except for the licence grants.
Any breach of this Licence by a Subsidiary shall entitle Arm to terminate this Licence as if you were the party in breach. Any termination of this Licence shall be effective in respect of all Subsidiaries. Any rights granted to any Subsidiary hereunder shall automatically terminate upon such Subsidiary ceasing to be a Subsidiary.
The Document consists solely of commercial items. Licensee shall be responsible for ensuring that any use, duplication or disclosure of the Document complies fully with any relevant export laws and regulations to assure that the Document or any portion thereof is not exported, directly or indirectly, in violation of such export laws.
This Licence may be translated into other languages for convenience, and Licensee agrees that if there is any conflict between the English version of this Licence and any translation, the terms of the English version of this Licence shall prevail.
The Arm corporate logo and words marked with ® or ™ are registered trademarks or trademarks of Arm Limited (or its subsidiaries) in the US and/or elsewhere. All rights reserved. Other brands and names mentioned in this document may be the trademarks of their respective owners. No licence, express, implied or otherwise, is granted to Licensee under this Licence, to use the Arm trade marks in connection with the Document or any products based thereon. Visit Arm’s website at https://www.arm.com/company/policies/trademarks for more information about Arm’s trademarks.
The validity, construction and performance of this Licence shall be governed by English Law.
Copyright © 2018-2022, Arm Limited or its affiliates. All rights reserved.
Arm document reference: LES-PRE-21585 version 4.0
References
This document refers to the following documents.
| Ref | Document Number | Title |
|---|---|---|
| [FF-M] | ARM DEN 0063 | Arm® Platform Security Architecture Firmware Framework. https://pages.arm.com/psa-apis |
| [PSA-ITS] | ARM IHI 0087 | PSA Storage API. https://pages.arm.com/psa-apis |
| [PSA-PAKE] | ARM AES 0058 | PSA Cryptographic API 1.1 PAKE Extension. https://developer.arm.com/documentation/aes0058/latest |
| Ref | Title |
|---|---|
| [C99] | ISO/IEC, ISO/IEC 9899:1999 — Programming Languages — C, December 1999. https://www.iso.org/standard/29237.html |
| [CHACHA20] | Bernstein, D., ChaCha, a variant of Salsa20, January 2008. http://cr.yp.to/chacha/chacha-20080128.pdf |
| [CLULOW] | Clulow, Jolyon, On the Security of PKCS #11, 2003. https://link.springer.com/chapter/10.1007/978-3-540-45238-6_32 |
| [CSTC0002] | Cryptography Standardization Technical Committee, GM/T 0002-2012: SM4 block cipher algorithm, March 2012. http://www.gmbz.org.cn/main/viewfile/20180108015408199368.html |
| [CSTC0002/E] | Cryptography Standardization Technical Committee, GM/T 0002-2012: SM4 block cipher algorithm, April 2018 (English version). http://www.gmbz.org.cn/main/postDetail.html?id=20180404044052 |
| [CSTC0004] | Cryptography Standardization Technical Committee, GM/T 0004-2012: SM3 cryptographic hash algorithm, March 2012. http://www.gmbz.org.cn/main/viewfile/20180108023812835219.html |
| [CSTC0004/E] | Cryptography Standardization Technical Committee, GM/T 0004-2012: SM3 cryptographic hash algorithm, July 2018 (English version). http://www.gmbz.org.cn/main/postDetail.html?id=20180724105928 |
| [Curve25519] | Bernstein et al., Curve25519: new Diffie-Hellman speed records, LNCS 3958, 2006. https://www.iacr.org/archive/pkc2006/39580209/39580209.pdf |
| [Curve448] | Hamburg, Ed448-Goldilocks, a new elliptic curve, NIST ECC Workshop, 2015. https://eprint.iacr.org/2015/625.pdf |
| [Ed25519] | Bernstein et al., Twisted Edwards curves, Africacrypt, 2008. https://eprint.iacr.org/2008/013.pdf |
| [Ed448] | Hamburg, Ed448-Goldilocks, a new elliptic curve, NIST ECC Workshop, 2015. https://eprint.iacr.org/2015/625.pdf |
| [FIPS180-4] | NIST, FIPS Publication 180-4: Secure Hash Standard (SHS), August 2015. https://doi.org/10.6028/NIST.FIPS.180-4 |
| [FIPS186-4] | NIST, FIPS Publication 186-4: Digital Signature Standard (DSS), July 2013. https://doi.org/10.6028/NIST.FIPS.186-4 |
| [FIPS197] | NIST, FIPS Publication 197: Advanced Encryption Standard (AES), November 2001. https://doi.org/10.6028/NIST.FIPS.197 |
| [FIPS202] | NIST, FIPS Publication 202: SHA-3 Standard: Permutation-Based Hash and Extendable-Output Functions, August 2015. https://doi.org/10.6028/NIST.FIPS.202 |
| [FRP] | Agence nationale de la sécurité des systèmes d’information, Publication d’un paramétrage de courbe elliptique visant des applications de passeport électronique et de l’administration électronique française, 21 November 2011. https://www.ssi.gouv.fr/agence/rayonnement-scientifique/publications-scientifiques/articles-ouvrages-actes |
| [IEEE-XTS] | IEEE, 1619-2018 — IEEE Standard for Cryptographic Protection of Data on Block-Oriented Storage Devices, January 2019. https://ieeexplore.ieee.org/servlet/opac?punumber=8637986 |
| [ISO10118] | ISO/IEC, ISO/IEC 10118-3:2018 IT Security techniques — Hash-functions — Part 3: Dedicated hash-functions, October 2018. https://www.iso.org/standard/67116.html |
| [ISO9797] | ISO/IEC, ISO/IEC 9797-1:2011 Information technology — Security techniques — Message Authentication Codes (MACs) — Part 1: Mechanisms using a block cipher, March 2011. https://www.iso.org/standard/50375.html |
| [NTT-CAM] | NTT Corporation and Mitsubishi Electric Corporation, Specification of Camellia — a 128-bit Block Cipher, September 2001. https://info.isl.ntt.co.jp/crypt/eng/camellia/specifications |
| [RFC1319] | IETF, The MD2 Message-Digest Algorithm, April 1992. https://tools.ietf.org/html/rfc1319.html |
| [RFC1320] | IETF, The MD4 Message-Digest Algorithm, April 1992. https://tools.ietf.org/html/rfc1320.html |
| [RFC1321] | IETF, The MD5 Message-Digest Algorithm, April 1992. https://tools.ietf.org/html/rfc1321.html |
| [RFC2104] | IETF, HMAC: Keyed-Hashing for Message Authentication, February 1997. https://tools.ietf.org/html/rfc2104.html |
| [RFC2315] | IETF, PKCS #7: Cryptographic Message Syntax Version 1.5, March 1998. https://tools.ietf.org/html/rfc2315.html |
| [RFC3279] | IETF, Algorithms and Identifiers for the Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile, April 2002. https://tools.ietf.org/html/rfc3279.html |
| [RFC3610] | IETF, Counter with CBC-MAC (CCM), September 2003. https://tools.ietf.org/html/rfc3610 |
| [RFC3713] | IETF, A Description of the Camellia Encryption Algorithm, April 2004. https://tools.ietf.org/html/rfc3713 |
| [RFC4279] | IETF, Pre-Shared Key Ciphersuites for Transport Layer Security (TLS), December 2005. https://tools.ietf.org/html/rfc4279.html |
| [RFC4615] | IETF, The Advanced Encryption Standard-Cipher-based Message Authentication Code-Pseudo-Random Function-128 (AES-CMAC-PRF-128) Algorithm for the Internet Key Exchange Protocol (IKE), August 2006. https://tools.ietf.org/html/rfc4615.html |
| [RFC5116] | IETF, An Interface and Algorithms for Authenticated Encryption, January 2008. https://tools.ietf.org/html/rfc5116.html |
| [RFC5246] | IETF, The Transport Layer Security (TLS) Protocol Version 1.2, August 2008. https://tools.ietf.org/html/rfc5246.html |
| [RFC5639] | IETF, Elliptic Curve Cryptography (ECC) Brainpool Standard Curves and Curve Generation, March 2010. https://tools.ietf.org/html/rfc5639.html |
| [RFC5794] | IETF, A Description of the ARIA Encryption Algorithm, March 2010. https://datatracker.ietf.org/doc/html/rfc5794 |
| [RFC5869] | IETF, HMAC-based Extract-and-Expand Key Derivation Function (HKDF), May 2010. https://tools.ietf.org/html/rfc5869.html |
| [RFC5915] | IETF, Elliptic Curve Private Key Structure, June 2010. https://tools.ietf.org/html/rfc5915.html |
| [RFC6979] | IETF, Deterministic Usage of the Digital Signature Algorithm (DSA) and Elliptic Curve Digital Signature Algorithm (ECDSA), August 2013. https://tools.ietf.org/html/rfc6979.html |
| [RFC7539] | IETF, ChaCha20 and Poly1305 for IETF Protocols, May 2015. https://tools.ietf.org/html/rfc7539.html |
| [RFC7748] | IETF, Elliptic Curves for Security, January 2016. https://tools.ietf.org/html/rfc7748.html |
| [RFC7919] | IETF, Negotiated Finite Field Diffie-Hellman Ephemeral Parameters for Transport Layer Security (TLS), August 2016. https://tools.ietf.org/html/rfc7919.html |
| [RFC8017] | IETF, PKCS #1: RSA Cryptography Specifications Version 2.2, November 2016. https://tools.ietf.org/html/rfc8017.html |
| [RFC8018] | IETF, PKCS #5: Password-Based Cryptography Specification Version 2.1, January 2017. https://tools.ietf.org/html/rfc8018.html |
| [RFC8032] | IRTF, Edwards-Curve Digital Signature Algorithm (EdDSA), January 2017. https://tools.ietf.org/html/rfc8032.html |
| [RIPEMD] | Dobbertin, Bosselaers and Preneel, RIPEMD-160: A Strengthened Version of RIPEMD, April 1996. https://homes.esat.kuleuven.be/~bosselae/ripemd160.html |
| [SEC1] | Standards for Efficient Cryptography, SEC 1: Elliptic Curve Cryptography, May 2009. https://www.secg.org/sec1-v2.pdf |
| [SEC2] | Standards for Efficient Cryptography, SEC 2: Recommended Elliptic Curve Domain Parameters, January 2010. https://www.secg.org/sec2-v2.pdf |
| [SEC2v1] | Standards for Efficient Cryptography, SEC 2: Recommended Elliptic Curve Domain Parameters, Version 1.0, September 2000. https://www.secg.org/SEC2-Ver-1.0.pdf |
| [SP800-30] | NIST, NIST Special Publication 800-30 Revision 1: Guide for Conducting Risk Assessments, September 2012. https://doi.org/10.6028/NIST.SP.800-30r1 |
| [SP800-38A] | NIST, NIST Special Publication 800-38A: Recommendation for Block Cipher Modes of Operation: Methods and Techniques, December 2001. https://doi.org/10.6028/NIST.SP.800-38A |
| [SP800-38B] | NIST, NIST Special Publication 800-38B: Recommendation for Block Cipher Modes of Operation: the CMAC Mode for Authentication, May 2005. https://doi.org/10.6028/NIST.SP.800-38B |
| [SP800-38D] | NIST, NIST Special Publication 800-38D: Recommendation for Block Cipher Modes of Operation: Galois/Counter Mode (GCM) and GMAC, November 2007. https://doi.org/10.6028/NIST.SP.800-38D |
| [SP800-56A] | NIST, NIST Special Publication 800-56A: Recommendation for Pair-Wise Key-Establishment Schemes Using Discrete Logarithm Cryptography, April 2018. https://doi.org/10.6028/NIST.SP.800-56Ar3 |
| [SP800-67] | NIST, NIST Special Publication 800-67: Recommendation for the Triple Data Encryption Algorithm (TDEA) Block Cipher, November 2017. https://doi.org/10.6028/NIST.SP.800-67r2 |
| [X9-62] | ANSI, Public Key Cryptography For The Financial Services Industry: The Elliptic Curve Digital Signature Algorithm (ECDSA). https://standards.globalspec.com/std/1955141/ANSI%20X9.62 |
Terms and abbreviations
This document uses the following terms and abbreviations.
| Term | Meaning |
|---|---|
| AEAD | See Authenticated Encryption with Associated Data. |
| Algorithm | A finite sequence of steps to perform a particular operation. In this specification, an algorithm is a cipher or a related function. Other texts call this a cryptographic mechanism. |
| API | Application Programming Interface. |
| Asymmetric | See Public-key cryptography. |
| Authenticated Encryption with Associated Data (AEAD) | A type of encryption that provides confidentiality and authenticity of data using symmetric keys. |
| Byte | In this specification, a unit of storage comprising eight bits, also called an octet. |
| Caller isolation | Property of an implementation in which there are multiple application instances, with a security boundary between the application instances, as well as between the cryptoprocessor and the application instances. See Optional isolation. |
| Cipher | An algorithm used for encryption or decryption with a symmetric key. |
| Cryptoprocessor | The component that performs cryptographic operations. A cryptoprocessor might contain a keystore and countermeasures against a range of physical and timing attacks. |
| Cryptoprocessor isolation | Property of an implementation in which there is a security boundary between the application and the cryptoprocessor, but the cryptoprocessor does not communicate with other applications. See Optional isolation. |
| Hash | A cryptographic hash function, or the value returned by such a function. |
| HMAC | A type of MAC that uses a cryptographic key with a hash function. |
| Implementation defined | Behavior that is not defined by the architecture, but is defined and documented by individual implementations. |
| Initialization vector (IV) | An additional input that is not part of the message. It is used to prevent an attacker from making any correlation between cipher text and plain text. This specification uses the term for such initial inputs in all contexts. For example, the initial counter in CTR mode is called the IV. |
| Isolation | Property of an implementation in which there is a security boundary between the application and the cryptoprocessor. See Optional isolation. |
| IV | See Initialization vector. |
| KDF | See Key Derivation Function. |
| Key agreement | An algorithm for two or more parties to establish a common secret key. |
| Key Derivation Function (KDF) | Key Derivation Function. An algorithm for deriving keys from secret material. |
| Key identifier | A reference to a cryptographic key. Key identifiers in the PSA Crypto API are 32-bit integers. |
| Key policy | Key metadata that describes and restricts what a key can be used for. |
| Key size | The size of a key as defined by common conventions for each key type. For keys that are built from several numbers of strings, this is the size of a particular one of these numbers or strings. This specification expresses key sizes in bits. |
| Key type | Key metadata that describes the structure and content of a key. |
| Keystore | A hardware or software component that protects, stores, and manages cryptographic keys. |
| Lifetime | Key metadata that describes when a key is destroyed. |
| MAC | See Message Authentication Code. |
| Message Authentication Code (MAC) | A short piece of information used to authenticate a message. It is created and verified using a symmetric key. |
| Message digest | A hash of a message. Used to determine if a message has been tampered. |
| Multi-part operation | An API which splits a single cryptographic operation into a sequence of separate steps. |
| No isolation | Property of an implementation in which there is no security boundary between the application and the cryptoprocessor. See Optional isolation. |
| Non-extractable key | A key with a key policy that prevents it from being read by ordinary means. |
| Nonce | Used as an input for certain AEAD algorithms. Nonces must not be reused with the same key because this can break a cryptographic protocol. |
| Persistent key | A key that is stored in protected non-volatile memory. See Key lifetimes. |
| PSA | Platform Security Architecture |
| Public-key cryptography | A type of cryptographic system that uses key pairs. A keypair consists of a (secret) private key and a public key (not secret). A public key cryptographic algorithm can be used for key distribution and for digital signatures. |
| Salt | Used as an input for certain algorithms, such as key derivations. |
| Signature | The output of a digital signature scheme that uses an asymmetric keypair. Used to establish who produced a message. |
| Single-part function | An API that implements the cryptographic operation in a single function call. |
| Specification defined | Behavior that is defined by this specification. |
| Symmetric | A type of cryptographic algorithm that uses a single key. A symmetric key can be used with a block cipher or a stream cipher. |
| Volatile key | A key that has a short lifespan and is guaranteed not to exist after a restart of an application instance. See Key lifetimes. |
Potential for change
The contents of this specification are stable for version 1.1.
The following may change in updates to the version 1.1 specification:
- Small optional feature additions.
- Clarifications.
Significant additions, or any changes that affect the compatibility of the interfaces defined in this specification will only be included in a new major or minor version of the specification.
Conventions
Typographical conventions
The typographical conventions are:
- italic
- Introduces special terminology, and denotes citations.
monospaceUsed for assembler syntax descriptions, pseudocode, and source code examples.
Also used in the main text for instruction mnemonics and for references to other items appearing in assembler syntax descriptions, pseudocode, and source code examples.
- small capitals
Used for some common terms such as implementation defined.
Used for a few terms that have specific technical meanings, and are included in the Terms and abbreviations.
- Red text
- Indicates an open issue.
- Blue text
Indicates a link. This can be
- A cross-reference to another location within the document
- A URL, for example http://infocenter.arm.com
Numbers
Numbers are normally written in decimal. Binary numbers are preceded by 0b, and
hexadecimal numbers by 0x.
In both cases, the prefix and the associated value are written in a monospace
font, for example 0xFFFF0000. To improve readability, long numbers can be
written with an underscore separator between every four characters, for example
0xFFFF_0000_0000_0000. Ignore any underscores when interpreting the value of
a number.
Pseudocode descriptions
This book uses a form of pseudocode to provide precise descriptions of the specified functionality. This pseudocode is written in a monospace font. The pseudocode language is described in the Arm Architecture Reference Manual.
Assembler syntax descriptions
This book is not expected to contain assembler code or pseudo code examples.
Any code examples are shown in a monospace font.
Feedback
Arm welcomes feedback on its documentation.
Feedback on this book
If you have comments on the content of this book, send an e-mail to arm.psa-feedback@arm.com. Give:
- The title (PSA Cryptography API).
- The number and issue (IHI 0086 1.1.0).
- The page numbers to which your comments apply.
- The rule identifiers to which your comments apply, if applicable.
- A concise explanation of your comments.
Arm also welcomes general suggestions for additions and improvements.