PSA Certified Crypto API 1.1 (2023) - page 1
PSA Certified
Crypto API 1.1
Document number: IHI 0086
Release Quality:
Final
Issue Number:
2
Confidentiality:
Non-confidential
Date of Issue:
23/03/2023
Abstract
This document is part of the PSA Certified API specifications. It defines interfaces to provide cryptographic
operations and key storage services.
Contents
About this document
vii
Release information
vii
License
viii
References
ix
Terms and abbreviations
xii
Potential for change
xv
Conventions
xv
Typographical conventions
xv
Numbers
xvi
Feedback
xvi
1
Introduction
17
1.1
About Platform Security Architecture
17
1.2
About the Crypto API
17
2
Design goals
18
2.1
Suitable for constrained devices
18
2.2
A keystore interface
18
2.3
Optional isolation
18
2.4
Choice of algorithms
19
2.5
Ease of use
20
2.6
Example use cases
20
2.6.1
Network Security (TLS)
20
2.6.2
Secure Storage
20
2.6.3
Network Credentials
20
2.6.4
Device Pairing
20
2.6.5
Secure Boot
20
2.6.6
Attestation
21
2.6.7
Factory Provisioning
21
3
Functionality overview
21
3.1
Library management
21
3.2
Key management
21
3.2.1
Key types
22
IHI 0086
Page i
1.1.2
Non-confidential
3.2.2
Key identifiers
22
3.2.3
Key lifetimes
22
3.2.4
Key policies
23
3.2.5
Recommendations of minimum standards for key management
23
3.3
Symmetric cryptography
23
3.3.1
Single-part Functions
24
3.3.2
Multi-part operations
24
3.3.3
Example of the symmetric cryptography API
26
3.4
Asymmetric cryptography
27
3.5
Randomness and key generation
27
4
Sample architectures
27
4.1
Single-partition architecture
27
4.2
Cryptographic token and single-application processor
28
4.3
Cryptoprocessor with no key storage
28
4.4
Multi-client cryptoprocessor
28
4.5
Multi-cryptoprocessor architecture
29
5
Library conventions
29
5.1
Header files
29
5.2
API conventions
30
5.2.1
Identifier names
30
5.2.2
Basic types
30
5.2.3
Data types
30
5.2.4
Constants
30
5.2.5
Function-like macros
31
5.2.6
Functions
31
5.3
Error handling
31
5.3.1
Return status
31
5.3.2
Behavior on error
32
5.4
Parameter conventions
33
5.4.1
Pointer conventions
33
5.4.2
Input buffer sizes
33
5.4.3
Output buffer sizes
33
5.4.4
Overlap between parameters
34
5.4.5
Stability of parameters
34
5.5
Key types and algorithms
35
5.5.1
Structure of key types and algorithms
35
5.6
Concurrent calls
35
IHI 0086
Page ii
1.1.2
Non-confidential
6
Implementation considerations
36
6.1
Implementation-specific aspects of the interface
36
6.1.1
Implementation profile
36
6.1.2
Implementation-specific types
36
6.1.3
Implementation-specific macros
36
6.2
Porting to a platform
37
6.2.1
Platform assumptions
37
6.2.2
Platform-specific types
38
6.2.3
Cryptographic hardware support
38
6.3
Security requirements and recommendations
38
6.3.1
Error detection
38
6.3.2
Indirect object references
38
6.3.3
Memory cleanup
39
6.3.4
Managing key material
39
6.3.5
Safe outputs on error
39
6.3.6
Attack resistance
40
6.4
Other implementation considerations
40
6.4.1
Philosophy of resource management
40
7
Usage considerations
40
7.1
Security recommendations
40
7.1.1
Always check for errors
40
7.1.2
Shared memory and concurrency
41
7.1.3
Cleaning up after use
41
8
Library management reference
41
8.1
Status codes
41
8.1.1
Common error codes
42
8.1.2
Error codes specific to the Crypto API
43
8.2
Crypto API library
44
8.2.1
API version
44
8.2.2
Library initialization
44
9
Key management reference
46
9.1
Key attributes
46
9.1.1
Managing key attributes
46
9.2
Key types
50
9.2.1
Key type encoding
50
9.2.2
Key categories
51
9.2.3
Symmetric keys
52
9.2.4
RSA keys
59
9.2.5
Elliptic Curve keys
60
IHI 0086
Page iii
1.1.2
Non-confidential
9.2.6
Diffie Hellman keys
67
9.2.7
Attribute accessors
70
9.3
Key lifetimes
72
9.3.1
Volatile keys
72
9.3.2
Persistent keys
73
9.3.3
Lifetime encodings
73
9.3.4
Lifetime values
76
9.3.5
Attribute accessors
78
9.3.6
Support macros
79
9.4
Key identifiers
80
9.4.1
Key identifier type
81
9.4.2
Attribute accessors
82
9.5
Key policies
83
9.5.1
Permitted algorithms
83
9.5.2
Key usage flags
85
9.6
Key management functions
90
9.6.1
Key creation
90
9.6.2
Key destruction
96
9.6.3
Key export
98
9.6.4
Key formats
103
10
Cryptographic operation reference
107
10.1
Algorithms
107
10.1.1
Algorithm encoding
108
10.1.2
Algorithm categories
108
10.2
Message digests (Hashes)
113
10.2.1
Hash algorithms
113
10.2.2
Single-part hashing functions
117
10.2.3
Multi-part hashing operations
119
10.2.4
Support macros
128
10.2.5
Hash suspend state
131
10.3
Message authentication codes (MAC)
133
10.3.1
MAC algorithms
134
10.3.2
Single-part MAC functions
137
10.3.3
Multi-part MAC operations
140
10.3.4
Support macros
147
10.4
Unauthenticated ciphers
149
10.4.1
Cipher algorithms
150
10.4.2
Single-part cipher functions
156
10.4.3
Multi-part cipher operations
159
10.4.4
Support macros
169
10.5
Authenticated encryption with associated data (AEAD)
175
10.5.1
AEAD algorithms
176
IHI 0086
Page iv
1.1.2
Non-confidential
10.5.2
Single-part AEAD functions
180
10.5.3
Multi-part AEAD operations
183
10.5.4
Support macros
199
10.6
Key derivation
205
10.6.1
Key derivation algorithms
206
10.6.2
Input step types
213
10.6.3
Key derivation functions
215
10.6.4
Support macros
231
10.7
Asymmetric signature
234
10.7.1
Asymmetric signature algorithms
235
10.7.2
Asymmetric signature functions
243
10.7.3
Support macros
250
10.8
Asymmetric encryption
256
10.8.1
Asymmetric encryption algorithms
256
10.8.2
Asymmetric encryption functions
257
10.8.3
Support macros
261
10.9
Key agreement
263
10.9.1
Key agreement algorithms
263
10.9.2
Standalone key agreement
266
10.9.3
Combining key agreement and key derivation
267
10.9.4
Support macros
269
10.10
Other cryptographic services
272
10.10.1 Random number generation
272
A
Example header file
273
A.1
psa/crypto.h
273
B
Algorithm and key type encoding
287
B.1
Algorithm identifier encoding
287
B.1.1
Algorithm categories
287
B.1.2
Hash algorithm encoding
288
B.1.3
MAC algorithm encoding
289
B.1.4
Cipher algorithm encoding
290
B.1.5
AEAD algorithm encoding
291
B.1.6
Key derivation algorithm encoding
291
B.1.7
Asymmetric signature algorithm encoding
292
B.1.8
Asymmetric encryption algorithm encoding
293
B.1.9
Key agreement algorithm encoding
293
B.2
Key type encoding
294
B.2.1
Key type categories
295
B.2.2
Raw key encoding
295
B.2.3
Symmetric key encoding
295
B.2.4
Asymmetric key encoding
296
IHI 0086
Page v
1.1.2
Non-confidential
C
Example macro implementations
298
C.1
Algorithm macros
299
C.2
Key type macros
303
C.3
Hash suspend state macros
304
D
Security Risk Assessment
305
D.1
Architecture
305
D.1.1
System definition
305
D.1.2
Assets and stakeholders
307
D.1.3
Security goals
308
D.2
Threat Model
308
D.2.1
Adversarial models
308
D.2.2
Threats and attacks
310
D.2.3
Risk assessment
312
D.3
Mitigations
313
D.3.1
Objectives
313
D.3.2
Requirements
314
D.4
Remediation & residual risk
317
D.4.1
Implementation remediations
317
D.4.2
Residual risk
318
E
Changes to the API
318
E.1
Document change history
318
E.1.1
Changes between 1.1.1 and 1.1.2
319
E.1.2
Changes between 1.1.0 and 1.1.1
319
E.1.3
Changes between 1.0.1 and 1.1.0
319
E.1.4
Changes between 1.0.0 and 1.0.1
321
E.1.5
Changes between 1.0 beta 3 and 1.0.0
322
E.1.6
Changes between 1.0 beta 2 and 1.0 beta 3
332
E.1.7
Changes between 1.0 beta 1 and 1.0 beta 2
333
E.2
Planned changes for version 1.1.x
333
E.3
Future additions
334
Index of API elements
335
IHI 0086
Page vi
1.1.2
Non-confidential
About this document
Release information
The change history table lists the changes that have been made to this document.
Table 1 Document revision history
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 Certified
API specifications.
May 2019
1.0 Beta 3
Non-confidential
Update for release with other PSA Certified
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.
October 2022
1.1.1 Final
Non-confidential
Relicensed as open source under CC BY-SA
4.0.
Improve support for TLS.
March 2023
1.1.2 Final
Non-confidential
Clarifications and fixes
The detailed changes in each release are described in Document change history on page 318.
IHI 0086
Page vii
1.1.2
Non-confidential
PSA Certified Crypto API
some draft issues of this document have been released, to a limited circulation.
License
Text and illustrations
Text and illustrations in this work are licensed under Attribution-ShareAlike 4.0 International (CC BY-SA 4.0). To view a copy of
the license, visit creativecommons.org/licenses/by-sa/4.0.
Grant of patent license. Subject to the terms and conditions of this license (both the CC BY-SA 4.0 Public License and this Patent
License), each Licensor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as
stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Licensed
Material, where such license applies only to those patent claims licensable by such Licensor that are necessarily infringed by their
contribution(s) alone or by combination of their contribution(s) with the Licensed Material to which such contribution(s) was
submitted. If You institute patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the
Licensed Material or a contribution incorporated within the Licensed Material constitutes direct or contributory patent
infringement, then any licenses granted to You under this license for that Licensed Material shall terminate as of the date such
litigation is filed.
The Arm trademarks featured here are registered trademarks or trademarks of Arm Limited (or its subsidiaries) in the US and/or
elsewhere. All rights reserved. Please visit arm.com/company/policies/trademarks for more information about Arm’s trademarks.
About the license
The language in the additional patent license is largely identical to that in section 3 of the Apache License, Version 2.0 (Apache
2.0), with two exceptions:
1. Changes are made related to the defined terms, to align those defined terms with the terminology in CC BY-SA 4.0 rather
than Apache 2.0 (for example, changing “Work” to “Licensed Material”).
2. The scope of the defensive termination clause is changed from “any patent licenses granted to You” to “any licenses
granted to You”. This change is intended to help maintain a healthy ecosystem by providing additional protection to the
community against patent litigation claims.
To view the full text of the Apache 2.0 license, visit apache.org/licenses/LICENSE-2.0.
Source code
Source code samples in this work are licensed under the Apache License, Version 2.0 (the “License”); you may not use such
samples except in compliance with the License. You may obtain a copy of the License at apache.org/licenses/LICENSE-2.0.
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “AS IS”
BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and limitations under the License.
IHI 0086
Page viii
1.1.2
Non-confidential
References
This document refers to the following documents.
Table 2 Arm documents referenced by this document
Ref
Document
Title
Number
[PSA-PAKE]
ARM AES 0058
PSA Certified Crypto API 1.1 PAKE Extension.
arm-software.github.io/psa-api/crypto
[PSM]
ARM DEN 0128
Platform Security Model.
developer.arm.com/documentation/den0128
[PSA-FFM]
ARM DEN 0063
Arm® Platform Security Architecture Firmware Framework.
pages.arm.com/psa-apis
[PSA-STAT]
ARM IHI 0097
PSA Certified Status code API.
arm-software.github.io/psa-api/status-code
Table 3 Other documents referenced by this document
Ref
Title
[C99]
ISO/IEC, ISO/IEC 9899:1999 - Programming Languages - C, December 1999.
[CHACHA20]
Bernstein, D., ChaCha, a variant of Salsa20, January 2008.
[CLULOW]
Clulow, Jolyon, On the Security of PKCS #11, 2003.
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.
[CSTC0004]
Cryptography Standardization Technical Committee, GM/T 0004-2012: SM3
cryptographic hash algorithm, March 2012.
[Curve25519]
Bernstein et al., Curve25519: new Diffie-Hellman speed records, LNCS 3958, 2006.
[Curve448]
Hamburg, Ed448-Goldilocks, a new elliptic curve, NIST ECC Workshop, 2015.
eprint.iacr.org/2015/625.pdf
[Ed25519]
Bernstein et al., Twisted Edwards curves, Africacrypt, 2008.
eprint.iacr.org/2008/013.pdf
[Ed448]
Hamburg, Ed448-Goldilocks, a new elliptic curve, NIST ECC Workshop, 2015.
eprint.iacr.org/2015/625.pdf
continues on next page
IHI 0086
Page ix
1.1.2
Non-confidential
Table 3 - continued from previous page
Ref
Title
[FIPS180-4]
NIST, FIPS Publication 180-4: Secure Hash Standard (SHS), August 2015.
doi.org/10.6028/NIST.FIPS.180-4
[FIPS186-4]
NIST, FIPS Publication 186-4: Digital Signature Standard (DSS), July 2013.
doi.org/10.6028/NIST.FIPS.186-4
[FIPS197]
NIST, FIPS Publication 197: Advanced Encryption Standard (AES), November 2001.
doi.org/10.6028/NIST.FIPS.197
[FIPS202]
NIST, FIPS Publication 202: SHA-3 Standard: Permutation-Based Hash and
Extendable-Output Functions, August 2015. 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.
scientifiques/articles-ouvrages-actes
[IEEE-XTS]
IEEE, 1619-2018 - IEEE Standard for Cryptographic Protection of Data on
Block-Oriented Storage Devices, January 2019.
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. 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. www.iso.org/standard/50375.html
[NTT-CAM]
NTT Corporation and Mitsubishi Electric Corporation, Specification of Camellia - a
128-bit Block Cipher, September 2001.
info.isl.ntt.co.jp/crypt/eng/camellia/specifications
[RFC1319]
IETF, The MD2 Message-Digest Algorithm, April 1992.
tools.ietf.org/html/rfc1319.html
[RFC1320]
IETF, The MD4 Message-Digest Algorithm, April 1992.
tools.ietf.org/html/rfc1320.html
[RFC1321]
IETF, The MD5 Message-Digest Algorithm, April 1992.
tools.ietf.org/html/rfc1321.html
[RFC2104]
IETF, HMAC: Keyed-Hashing for Message Authentication, February 1997.
tools.ietf.org/html/rfc2104.html
[RFC2315]
IETF, PKCS #7: Cryptographic Message Syntax Version 1.5, March 1998.
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.
tools.ietf.org/html/rfc3279.html
continues on next page
IHI 0086
Page x
1.1.2
Non-confidential
Table 3 - continued from previous page
Ref
Title
[RFC3610]
IETF, Counter with CBC-MAC (CCM), September 2003. tools.ietf.org/html/rfc3610
[RFC3713]
IETF, A Description of the Camellia Encryption Algorithm, April 2004.
tools.ietf.org/html/rfc3713
[RFC4279]
IETF, Pre-Shared Key Ciphersuites for Transport Layer Security (TLS), December 2005.
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. tools.ietf.org/html/rfc4615.html
[RFC5116]
IETF, An Interface and Algorithms for Authenticated Encryption, January 2008.
tools.ietf.org/html/rfc5116.html
[RFC5246]
IETF, The Transport Layer Security (TLS) Protocol Version 1.2, August 2008.
tools.ietf.org/html/rfc5246.html
[RFC5489]
IETF, ECDHE_PSK Cipher Suites for Transport Layer Security (TLS), March 2009.
tools.ietf.org/html/rfc5489.html
[RFC5639]
IETF, Elliptic Curve Cryptography (ECC) Brainpool Standard Curves and Curve
Generation, March 2010. tools.ietf.org/html/rfc5639.html
[RFC5794]
IETF, A Description of the ARIA Encryption Algorithm, March 2010.
datatracker.ietf.org/doc/html/rfc5794
[RFC5869]
IETF, HMAC-based Extract-and-Expand Key Derivation Function (HKDF), May 2010.
tools.ietf.org/html/rfc5869.html
[RFC5915]
IETF, Elliptic Curve Private Key Structure, June 2010. 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. tools.ietf.org/html/rfc6979.html
[RFC7539]
IETF, ChaCha20 and Poly1305 for IETF Protocols, May 2015.
tools.ietf.org/html/rfc7539.html
[RFC7748]
IETF, Elliptic Curves for Security, January 2016. tools.ietf.org/html/rfc7748.html
[RFC7919]
IETF, Negotiated Finite Field Diffie-Hellman Ephemeral Parameters for Transport Layer
Security (TLS), August 2016. tools.ietf.org/html/rfc7919.html
[RFC8017]
IETF, PKCS #1: RSA Cryptography Specifications Version 2.2, November 2016.
tools.ietf.org/html/rfc8017.html
[RFC8018]
IETF, PKCS #5: Password-Based Cryptography Specification Version 2.1, January 2017.
tools.ietf.org/html/rfc8018.html
[RFC8032]
IRTF, Edwards-Curve Digital Signature Algorithm (EdDSA), January 2017.
tools.ietf.org/html/rfc8032.html
[RIPEMD]
Dobbertin, Bosselaers and Preneel, RIPEMD-160: A Strengthened Version of RIPEMD,
April 1996. homes.esat.kuleuven.be/~bosselae/ripemd160.html
continues on next page
IHI 0086
Page xi
1.1.2
Non-confidential
Table 3 - continued from previous page
Ref
Title
[SEC1]
Standards for Efficient Cryptography, SEC 1: Elliptic Curve Cryptography, May 2009.
[SEC2]
Standards for Efficient Cryptography, SEC 2: Recommended Elliptic Curve Domain
Parameters, January 2010. www.secg.org/sec2-v2.pdf
[SEC2v1]
Standards for Efficient Cryptography, SEC 2: Recommended Elliptic Curve Domain
Parameters, Version 1.0, September 2000. 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. 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.
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.
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.
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.
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. 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).
standards.globalspec.com/std/1955141/ANSI%20X9.62
Terms and abbreviations
This document uses the following terms and abbreviations.
Table 4 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.
continues on next page
IHI 0086
Page xii
1.1.2
Non-confidential
Table 4 - continued from previous page
Term
Meaning
API
Application Programming Interface.
Asymmetric
See Public-key cryptography.
Authenticated
A type of encryption that provides confidentiality and authenticity of data
Encryption with
using symmetric keys.
Associated Data
(AEAD)
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 on page 18.
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
Property of an implementation in which there is a security boundary
isolation
between the application and the cryptoprocessor, but the cryptoprocessor
does not communicate with other applications.
See Optional isolation on page 18.
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 on page 18.
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
Key Derivation Function. An algorithm for deriving keys from secret material.
Function (KDF)
continues on next page
IHI 0086
Page xiii
1.1.2
Non-confidential
Table 4 - continued from previous page
Term
Meaning
Key identifier
A reference to a cryptographic key. Key identifiers in the 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
A short piece of information used to authenticate a message. It is created and
Authentication Code
verified using a symmetric key.
(MAC)
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 on page 18.
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 on page 72.
PSA
Platform Security Architecture
Public-key
A type of cryptographic system that uses key pairs. A keypair consists of a
cryptography
(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.
continues on next page
IHI 0086
Page xiv
1.1.2
Non-confidential
Table 4 - continued from previous page
Term
Meaning
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 on page 72.
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.
monospace
Used 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 example.com
IHI 0086
Page xv
1.1.2
Non-confidential
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.
Feedback
We welcome feedback on the PSA Certified API documentation.
If you have comments on the content of this book, visit github.com/arm-software/psa-api/issues to create
a new issue at the PSA Certified API GitHub project. Give:
∙ The title (Crypto API).
∙ The number and issue (IHI 0086 1.1.2).
∙ The location in the document to which your comments apply.
∙ A concise explanation of your comments.
We also welcome general suggestions for additions and improvements.
IHI 0086
Page xvi
1.1.2
Non-confidential
1 Introduction
1.1 About Platform Security Architecture
This document is one of a set of resources provided by Arm that can help organizations develop products
that meet the security requirements of PSA Certified on Arm-based platforms. The PSA Certified scheme
provides a framework and methodology that helps silicon manufacturers, system software providers and
OEMs to develop more secure products. Arm resources that support PSA Certified range from threat
models, standard architectures that simplify development and increase portability, and open-source
partnerships that provide ready-to-use software. You can read more about PSA Certified here at
developer.arm.com/platform-security-resources.
1.2 About the Crypto API
The interface described in this document is a PSA Certified API, that provides a portable programming
interface to cryptographic operations, and key storage functionality, on a wide range of hardware.
The interface is user-friendly, while still providing access to the low-level primitives used in modern
cryptography. It does not require that the user has access to the key material. Instead, it uses opaque key
identifiers.
You can find additional resources relating to the Crypto API here at arm-software.github.io/psa-api/crypto,
and find other PSA Certified APIs here at arm-software.github.io/psa-api.
This document includes:
∙ A rationale for the design. See Design goals on page 18.
∙ A high-level overview of the functionality provided by the interface. See Functionality overview on
page 21.
∙ A description of typical architectures of implementations for this specification. See Sample
architectures on page 27.
∙ General considerations for implementers of this specification, and for applications that use the
interface defined in this specification. See Implementation considerations on page 36 and Usage
considerations on page 40.
∙ A detailed definition of the API. See Library management reference on page 41, Key management
reference on page 46, and Cryptographic operation reference on page 107.
PSA Certified Crypto API 1.1 PAKE Extension [PSA-PAKE] is a companion document for version 1.1 of this
specification. [PSA-PAKE] defines a new API for Password Authenticated Key Establishment (PAKE)
algorithms. The PAKE API is an initial proposal at BETA status. The API defined by [PSA-PAKE] is provided
in a separate specification to reflect the different status of this API, and indicate that a future version can
include incompatible changes to the PAKE API. When the PAKE API is stable, it will be included in a future
version of the Crypto API specification.
In future, other companion documents will define profiles for this specification. A profile is a minimum
mandatory subset of the interface that a compliant implementation must provide.
IHI 0086
Page 17
1.1.2
Non-confidential
2 Design goals
2.1 Suitable for constrained devices
The interface is suitable for a vast range of devices: from special-purpose cryptographic processors that
process data with a built-in key, to constrained devices running custom application code, such as
microcontrollers, and multi-application devices, such as servers. Consequentially, the interface is scalable
and modular.
∙ Scalable: devices only need to implement the functionality that they will use.
∙ Modular: larger devices implement larger subsets of the same interface, rather than different
interfaces.
In this interface, all operations on unbounded amounts of data allow multi-part processing, as long as the
calculations on the data are performed in a streaming manner. This means that the application does not
need to store the whole message in memory at one time. As a result, this specification is suitable for very
constrained devices, including those where memory is very limited.
Memory outside the keystore boundary is managed by the application. An implementation of the interface
is not required to retain any state between function calls, apart from the content of the keystore and other
data that must be kept inside the keystore security boundary.
The interface does not expose the representation of keys and intermediate data, except when required for
interchange. This allows each implementation to choose optimal data representations. Implementations
with multiple components are also free to choose which memory area to use for internal data.
2.2 A keystore interface
The specification allows cryptographic operations to be performed on a key to which the application does
not have direct access. Except where required for interchange, applications access all keys indirectly, by an
identifier. The key material corresponding to that identifier can reside inside a security boundary that
prevents it from being extracted, except as permitted by a policy that is defined when the key is created.
2.3 Optional isolation
Implementations can isolate the cryptoprocessor from the calling application, and can further isolate
multiple calling applications. The interface allows the implementation to be separated between a frontend
and a backend. In an isolated implementation, the frontend is the part of the implementation that is
located in the same isolation boundary as the application, which the application accesses by function calls.
The backend is the part of the implementation that is located in a different environment, which is
protected from the frontend. Various technologies can provide protection, for example:
∙ Process isolation in an operating system.
∙ Partition isolation, either with a virtual machine or a partition manager.
∙ Physical separation between devices.
Communication between the frontend and backend is beyond the scope of this specification.
IHI 0086
Page 18
1.1.2
Non-confidential
In an isolated implementation, the backend can serve more than one implementation instance. In this case,
a single backend communicates with multiple instances of the frontend. The backend must enforce caller
isolation: it must ensure that assets of one frontend are not visible to any other frontend. The mechanism
for identifying callers is beyond the scope of this specification. An implementation that provides caller
isolation must document the identification mechanism. An implementation that provides caller isolation
must document any implementation-specific extension of the API that enables frontend instances to share
data in any form.
An isolated implementation that only has a single frontend provides cryptoprocessor isolation.
In summary, there are three types of implementation:
∙ No isolation: there is no security boundary between the application and the cryptoprocessor. For
example, a statically or dynamically linked library is an implementation with no isolation.
∙ Cryptoprocessor isolation: there is a security boundary between the application and the
cryptoprocessor, but the cryptoprocessor does not communicate with other applications. For
example, a cryptoprocessor chip that is a companion to an application processor is an
implementation with cryptoprocessor isolation.
∙ Caller isolation: there are multiple application instances, with a security boundary between the
application instances among themselves, as well as between the cryptoprocessor and the application
instances. For example, a cryptography service in a multiprocess environment is an implementation
with caller and cryptoprocessor isolation.
2.4 Choice of algorithms
The specification defines a low-level cryptographic interface, where the caller explicitly chooses which
algorithm and which security parameters they use. This is necessary to implement protocols that are
inescapable in various use cases. The design of the interface enables applications to implement
widely-used protocols and data exchange formats, as well as custom ones.
As a consequence, all cryptographic functionality operates according to the precise algorithm specified by
the caller. However, this does not apply to device-internal functionality, which does not involve any form
of interoperability, such as random number generation. The specification does not include generic
higher-level interfaces, where the implementation chooses the best algorithm for a purpose. However,
higher-level libraries can be built on top of the Crypto API.
Another consequence is that the specification permits the use of algorithms, key sizes and other
parameters that, while known to be insecure, might be necessary to support legacy protocols or legacy
data. Where major weaknesses are known, the algorithm descriptions give applicable warnings. However,
the lack of a warning both does not and cannot indicate that an algorithm is secure in all circumstances.
Application developers need to research the security of the protocols and algorithms that they plan to use
to determine if these meet their requirements.
The interface facilitates algorithm agility. As a consequence, cryptographic primitives are presented
through generic functions with a parameter indicating the specific choice of algorithm. For example, there
is a single function to calculate a message digest, which takes a parameter that identifies the specific hash
algorithm.
IHI 0086
Page 19
1.1.2
Non-confidential
2.5 Ease of use
The interface is designed to be as user-friendly as possible, given the aforementioned constraints on
suitability for various types of devices and on the freedom to choose algorithms.
In particular, the code flows are designed to reduce the risk of dangerous misuse. The interface is designed
in part to make it harder to misuse. Where possible, it is designed so that typical mistakes result in test
failures, rather than subtle security issues. Implementations avoid leaking data when a function is called
with invalid parameters, to the extent allowed by the C language and by implementation size constraints.
2.6 Example use cases
This section lists some of the use cases that were considered during the design of the Crypto API. This list
is not exhaustive, nor are all implementations required to support all use cases.
2.6.1 Network Security (TLS)
The API provides all of the cryptographic primitives needed to establish TLS connections.
2.6.2 Secure Storage
The API provides all primitives related to storage encryption, block or file-based, with master encryption
keys stored inside a key store.
2.6.3 Network Credentials
The API provides network credential management inside a key store, for example, for X.509-based
authentication or pre-shared keys on enterprise networks.
2.6.4 Device Pairing
The API provides support for key agreement protocols that are often used for secure pairing of devices
over wireless channels. For example, the pairing of an NFC token or a Bluetooth device might use key
agreement protocols upon first use.
2.6.5 Secure Boot
The API provides primitives for use during firmware integrity and authenticity validation, during a secure
or trusted boot process.
IHI 0086
Page 20
1.1.2
Non-confidential
2.6.6 Attestation
The API provides primitives used in attestation activities. Attestation is the ability for a device to sign an
array of bytes with a device private key and return the result to the caller. There are several use cases;
ranging from attestation of the device state, to the ability to generate a key pair and prove that it has been
generated inside a secure key store. The API provides access to the algorithms commonly used for
attestation.
2.6.7 Factory Provisioning
Most IoT devices receive a unique identity during the factory provisioning process, or once they have been
deployed to the field. This API provides the APIs necessary for populating a device with keys that
represent that identity.
3 Functionality overview
This section provides a high-level overview of the functionality provided by the interface defined in this
specification. Refer to the API definition for a detailed description, which begins with Library management
reference on page 41.
Future additions on page 334 describes features that might be included in future versions of this
specification.
Due to the modularity of the interface, almost every part of the library is optional. The only mandatory
function is psa_crypto_init().
3.1 Library management
Applications must call psa_crypto_init() to initialize the library before using any other function.
3.2 Key management
Applications always access keys indirectly via an identifier, and can perform operations using a key without
accessing the key material. This allows keys to be non-extractable, where an application can use a key but is
not permitted to obtain the key material. Non-extractable keys are bound to the device, can be
rate-limited and can have their usage restricted by policies.
Each key has a set of attributes that describe the key and the policy for using the key. A
psa_key_attributes_t object contains all of the attributes, which is used when creating a key and when
querying key attributes.
The key attributes include:
∙ A type and size that describe the key material. See Key types on page 22.
∙ The key identifier that the application uses to refer to the key. See Key identifiers on page 22.
∙ A lifetime that determines when the key material is destroyed, and where it is stored. See Key
lifetimes on page 22.
∙ A policy that determines how the key can be used. See Key policies on page 23.
IHI 0086
Page 21
1.1.2
Non-confidential
Keys are created using one of the key creation functions:
∙ psa_import_key()
∙ psa_generate_key()
∙ psa_key_derivation_output_key()
∙ psa_copy_key()
These output the key identifier, that is used to access the key in all other parts of the API.
All of the key attributes are set when the key is created and cannot be changed without destroying the key
first. If the original key permits copying, then the application can specify a different lifetime or restricted
policy for the copy of the key.
A call to psa_destroy_key() destroys the key material, and will cause any active operations that are using
the key to fail. Therefore an application must not destroy a key while an operation using that key is in
progress, unless the application is prepared to handle a failure of the operation.
3.2.1 Key types
Each cryptographic algorithm requires a key that has the right form, in terms of the size of the key material
and its numerical properties. The key type and key size encode that information about a key, and
determine whether the key is compatible with a cryptographic algorithm.
Additional non-cryptographic key types enable applications to store other secret values in the keystore.
See Key types on page 50.
3.2.2 Key identifiers
Key identifiers are integral values that act as permanent names for persistent keys, or as transient
references to volatile keys. Key identifiers are defined by the application for persistent keys, and by the
implementation for volatile keys and for built-in keys.
Key identifiers are output from a successful call to one of the key creation functions.
Valid key identifiers must have distinct values within the same application. If the implementation provides
caller isolation, then key identifiers are local to each application.
See Key identifiers on page 80.
3.2.3 Key lifetimes
The lifetime of a key indicates where it is stored and which application and system actions will create and
destroy it.
There are two main types of lifetimes: volatile and persistent.
Volatile keys are automatically destroyed when the application instance terminates or on a power reset of
the device. Volatile key identifiers are allocated by the implementation when the key is created. Volatile
keys can be explicitly destroyed with a call to psa_destroy_key().
Persistent keys are preserved until the application explicitly destroys them or until an
implementation-specific device management event occurs, for example, a factory reset. The key identifier
IHI 0086
Page 22
1.1.2
Non-confidential
for a persistent key is set by the application when creating the key, and remains valid throughout the
lifetime of the key, even if the application instance that created the key terminates.
See Key lifetimes on page 72.
3.2.4 Key policies
All keys have an associated policy that regulates which operations are permitted on the key. Each key
policy is a set of usage flags and a specific algorithm that is permitted with the key. See Key policies on
page 83.
3.2.5 Recommendations of minimum standards for key management
Most implementations provide the following functions:
∙ psa_import_key(). The exceptions are implementations that only give access to a key or keys that are
provisioned by proprietary means, and do not allow the main application to use its own
cryptographic material.
∙ psa_get_key_attributes() and the psa_get_key_xxx() accessor functions. They are easy to implement,
and it is difficult to write applications and to diagnose issues without being able to check the
metadata.
∙ psa_export_public_key(). This function is usually provided if the implementation supports any
asymmetric algorithm, since public-key cryptography often requires the delivery of a public key that
is associated with a protected private key.
∙ psa_export_key(). However, highly constrained implementations that are designed to work only with
short-term keys, or only with long-term non-extractable keys, do not need to provide this function.
3.3 Symmetric cryptography
This specification defines interfaces for the following types of symmetric cryptographic operation:
∙ Message digests, commonly known as hash functions. See Message digests (Hashes) on page 113.
∙ Message authentication codes (MAC). See Message authentication codes (MAC) on page 133.
∙ Symmetric ciphers. See Unauthenticated ciphers on page 149.
∙ Authenticated encryption with associated data (AEAD). See Authenticated encryption with associated
data (AEAD) on page 175.
∙ Key derivation. See Key derivation on page 205.
For each type of symmetric cryptographic operation, the API can include:
∙ A pair of single-part functions. For example, compute and verify, or encrypt and decrypt.
∙ A series of functions that permit multi-part operations.
Key derivation only provides multi-part operation, to support the flexibility required by these type of
algorithms.
IHI 0086
Page 23
1.1.2
Non-confidential
3.3.1 Single-part Functions
Single-part functions are APIs that implement the cryptographic operation in a single function call. This is
the easiest API to use when all of the inputs and outputs fit into the application memory.
Some use cases involve messages that are too large to be assembled in memory, or require non-default
configuration of the algorithm. These use cases require the use of a multi-part operation.
3.3.2 Multi-part operations
Multi-part operations are APIs which split a single cryptographic operation into a sequence of separate
steps. This enables fine control over the configuration of the cryptographic operation, and allows the
message data to be processed in fragments instead of all at once. For example, the following situations
require the use of a multi-part operation:
∙ Processing messages that cannot be assembled in memory.
∙ Using a deterministic IV for unauthenticated encryption.
∙ Providing the IV separately for unauthenticated encryption or decryption.
∙ Separating the AEAD authentication tag from the cipher text.
Each multi-part operation defines a specific object type to maintain the state of the operation. These types
are implementation-defined.
All multi-part operations follow the same pattern of use, which is shown in Figure 1 on page 25.
The typical sequence of actions with a multi-part operation is as follows:
1. Allocate: Allocate memory for an operation object of the appropriate type. The application can use
any allocation strategy: stack, heap, static, etc.
2. Initialize: Initialize or assign the operation object by one of the following methods:
∙ Set it to logical zero. This is automatic for static and global variables. Explicit initialization must
use the associated PSA_xxx_INIT macro as the type is implementation-defined.
∙ Set it to all-bits zero. This is automatic if the object was allocated with calloc().
∙ Assign the value of the associated macro PSA_xxx_INIT.
∙ Assign the result of calling the associated function psa_xxx_init().
The resulting object is now inactive.
It is an error to initialize an operation object that is in active or error states. This can leak memory or
other resources.
3. Setup: Start a new multi-part operation on an inactive operation object. Each operation object will
define one or more setup functions to start a specific operation.
On success, a setup function will put an operation object into an active state. On failure, the
operation object will remain inactive.
4. Update: Update an active operation object. The update function can provide additional parameters,
supply data for processing or generate outputs.
On success, the operation object remains active. On failure, the operation object will enter an error
state.
IHI 0086
Page 24
1.1.2
Non-confidential
Operation object starts as
uninitialised memory
Initialize
Setup
inactive
fails
Setup
Finish Abort
active
Update
Abort
Update
Finish
fails
fails
error
--- Solid lines show successful operation
--- Dashed lines show error flows
……… Dotted lines show operation cancellation
Figure 1 General state model for a multi-part operation
5. Finish: To end the operation, call the applicable finishing function. This will take any final inputs,
produce any final outputs, and then release any resources associated with the operation.
On success, the operation object returns to the inactive state. On failure, the operation object will
enter an error state.
6. Abort: An operation can be aborted at any stage during its use by calling the associated
psa_xxx_abort() function. This will release any resources associated with the operation and return
the operation object to the inactive state.
Any error that occurs to an operation while it is in an active state will result in the operation entering
an error state. The application must call the associated psa_xxx_abort() function to release the
operation resources and return the object to the inactive state.
psa_xxx_abort() can be called on an inactive operation, and this has no effect.
Once an operation object is returned to the inactive state, it can be reused by calling one of the applicable
setup functions again.
If a multi-part operation object is not initialized before use, the behavior is undefined.
If a multi-part operation function determines that the operation object is not in any valid state, it can
return PSA_ERROR_CORRUPTION_DETECTED.
IHI 0086
Page 25
1.1.2
Non-confidential
If a multi-part operation function is called with an operation object in the wrong state, the function will
return PSA_ERROR_BAD_STATE and the operation object will enter the error state.
It is safe to move a multi-part operation object to a different memory location, for example, using a bitwise
copy, and then to use the object in the new location. For example, an application can allocate an operation
object on the stack and return it, or the operation object can be allocated within memory managed by a
garbage collector. However, this does not permit the following behaviors:
∙ Moving the object while a function is being called on the object. This is not safe. See also Concurrent
calls on page 35.
∙ Working with both the original and the copied operation objects. This requires cloning the operation,
which is only available for hash operations using psa_hash_clone().
Each type of multi-part operation can have multiple active states. Documentation for the specific operation
describes the configuration and update functions, and any requirements about their usage and ordering.
3.3.3 Example of the symmetric cryptography API
Here is an example of a use case where a master key is used to generate both a message encryption key
and an IV for the encryption, and the derived key and IV are then used to encrypt a message.
1. Derive the message encryption material from the master key.
a. Initialize a psa_key_derivation_operation_t object to zero or to
PSA_KEY_DERIVATION_OPERATION_INIT.
b. Call psa_key_derivation_setup() with PSA_ALG_HKDF as the algorithm.
c. Call psa_key_derivation_input_key() with the step PSA_KEY_DERIVATION_INPUT_SECRET and the
master key.
d. Call psa_key_derivation_input_bytes() with the step PSA_KEY_DERIVATION_INPUT_INFO and a public
value that uniquely identifies the message.
e. Populate a psa_key_attributes_t object with the derived message encryption key’s attributes.
f. Call psa_key_derivation_output_key() to create the derived message key.
g. Call psa_key_derivation_output_bytes() to generate the derived IV.
h. Call psa_key_derivation_abort() to release the key derivation operation memory.
2. Encrypt the message with the derived material.
a. Initialize a psa_cipher_operation_t object to zero or to PSA_CIPHER_OPERATION_INIT.
b. Call psa_cipher_encrypt_setup() with the derived message encryption key.
c. Call psa_cipher_set_iv() using the derived IV retrieved above.
d. Call psa_cipher_update() one or more times to encrypt the message.
e. Call psa_cipher_finish() at the end of the message.
3. Call psa_destroy_key() to clear the generated key.
IHI 0086
Page 26
1.1.2
Non-confidential
3.4 Asymmetric cryptography
This specification defines interfaces for the following types of asymmetric cryptographic operation:
∙ Asymmetric encryption (also known as public key encryption). See Asymmetric encryption on
page 256.
∙ Asymmetric signature. See Asymmetric signature on page 234.
∙ Two-way key agreement (also known as key establishment). See Key agreement on page 263.
For asymmetric encryption and signature, the API provides single-part functions. For key agreement, the
API provides a single-part function and an additional input method for a key derivation operation.
3.5 Randomness and key generation
We strongly recommended that implementations include a random generator, consisting of a
cryptographically secure pseudo-random generator (CSPRNG), which is adequately seeded with a
cryptographic-quality hardware entropy source, commonly referred to as a true random number generator
(TRNG). Constrained implementations can omit the random generation functionality if they do not
implement any algorithm that requires randomness internally, and they do not provide a key generation
functionality. For example, a special-purpose component for signature verification can omit this.
It is recommended that applications use psa_generate_key(), psa_cipher_generate_iv() or
psa_aead_generate_nonce() to generate suitably-formatted random data, as applicable. In addition, the API
includes a function psa_generate_random() to generate and extract arbitrary random data.
4 Sample architectures
This section describes some example architectures that can be used for implementations of the interface
described in this specification. This list is not exhaustive and the section is entirely non-normative.
4.1 Single-partition architecture
In the single-partition architecture, there is no security boundary inside the system. The application code
can access all the system memory, including the memory used by the cryptographic services described in
this specification. Thus, the architecture provides no isolation.
This architecture does not conform to the Arm Platform Security Architecture Security Model. However, it is
useful for providing cryptographic services that use the same interface, even on devices that cannot
support any security boundary. So, while this architecture is not the primary design goal of the API defined
in the present specification, it is supported.
The functions in this specification simply execute the underlying algorithmic code. Security checks can be
kept to a minimum, since the cryptoprocessor cannot defend against a malicious application. Key import
and export copy data inside the same memory space.
This architecture also describes a subset of some larger systems, where the cryptographic services are
implemented inside a high-security partition, separate from the code of the main application, though it
shares this high-security partition with other platform security services.
IHI 0086
Page 27
1.1.2
Non-confidential
4.2 Cryptographic token and single-application processor
This system is composed of two partitions: one is a cryptoprocessor and the other partition runs an
application. There is a security boundary between the two partitions, so that the application cannot access
the cryptoprocessor, except through its public interface. Thus, the architecture provides cryptoprocessor
isolation. The cryptoprocessor has some non-volatile storage, a TRNG, and possibly, some cryptographic
accelerators.
There are a number of potential physical realizations: the cryptoprocessor might be a separate chip, a
separate processor on the same chip, or a logical partition using a combination of hardware and software
to provide the isolation. These realizations are functionally equivalent in terms of the offered software
interface, but they would typically offer different levels of security guarantees.
The Crypto API in the application processor consists of a thin layer of code that translates function calls to
remote procedure calls in the cryptoprocessor. All cryptographic computations are, therefore, performed
inside the cryptoprocessor. Non-volatile keys are stored inside the cryptoprocessor.
4.3 Cryptoprocessor with no key storage
As in the Cryptographic token and single-application processor architecture, this system is also composed of
two partitions separated by a security boundary and also provides cryptoprocessor isolation. However,
unlike the previous architecture, in this system, the cryptoprocessor does not have any secure, persistent
storage that could be used to store application keys.
If the cryptoprocessor is not capable of storing cryptographic material, then there is little use for a
separate cryptoprocessor, since all data would have to be imported by the application.
The cryptoprocessor can provide useful services if it is able to store at least one key. This might be a
hardware unique key that is burnt to one-time programmable memory during the manufacturing of the
device. This key can be used for one or more purposes:
∙ Encrypt and authenticate data stored in the application processor.
∙ Communicate with a paired device.
∙ Allow the application to perform operations with keys that are derived from the hardware unique key.
4.4 Multi-client cryptoprocessor
This is an expanded variant of Cryptographic token and single-application processor. In this variant, the
cryptoprocessor serves multiple applications that are mutually untrustworthy. This architecture provides
caller isolation.
In this architecture, API calls are translated to remote procedure calls, which encode the identity of the
client application. The cryptoprocessor carefully segments its internal storage to ensure that a client’s data
is never leaked to another client.
IHI 0086
Page 28
1.1.2
Non-confidential
4.5 Multi-cryptoprocessor architecture
This system includes multiple cryptoprocessors. There are several reasons to have multiple
cryptoprocessors:
∙ Different compromises between security and performance for different keys. Typically, this means a
cryptoprocessor that runs on the same hardware as the main application and processes short-term
secrets, a secure element or a similar separate chip that retains long-term secrets.
∙ Independent provisioning of certain secrets.
∙ A combination of a non-removable cryptoprocessor and removable ones, for example, a smartcard or
HSM.
∙ Cryptoprocessors managed by different stakeholders who do not trust each other.
The keystore implementation needs to dispatch each request to the correct processor. For example:
∙ All requests involving a non-extractable key must be processed in the cryptoprocessor that holds
that key.
∙ Requests involving a persistent key must be processed in the cryptoprocessor that corresponds to
the key’s lifetime value.
∙ Requests involving a volatile key might target a cryptoprocessor based on parameters supplied by
the application, or based on considerations such as performance inside the implementation.
5 Library conventions
5.1 Header files
The header file for the Crypto API has the name psa/crypto.h. All of the API elements that are provided by
an implementation must be visible to an application program that includes this header file.
#include "psa/crypto.h"
Implementations must provide their own version of the psa/crypto.h header file. Implementations can
provide a subset of the API defined in this specification and a subset of the available algorithms. Example
header file on page 273 provides an incomplete, example header file which includes all of the API elements.
See also Implementation considerations on page 36.
The Crypto API uses the status code definitions that are shared with the other PSA Certified APIs. PSA
Certified Status code API [PSA-STAT] defines these status codes in the psa/error.h header file. Applications
are not required to explicitly include the psa/error.h header file when using these status codes with the
Crypto API. See Status codes on page 41.
IHI 0086
Page 29
1.1.2
Non-confidential
5.2 API conventions
The interface in this specification is defined in terms of C macros, data types, and functions.
5.2.1 Identifier names
All of the identifiers defined in the Crypto API begin with the prefix psa_, for types and functions, or PSA_
for macros.
Future versions of this specification will use the same prefix for additional API elements. It is
recommended that applications and implementations do not use this prefix for their own identifiers, to
avoid a potential conflict with a future version of the Crypto API.
5.2.2 Basic types
This specification makes use of standard C data types, including the fixed-width integer types from the
ISO C99 specification update [C99]. The following standard C types are used:
int32_t
a 32-bit signed integer
uint8_t
an 8-bit unsigned integer
uint16_t a 16-bit unsigned integer
uint32_t a 32-bit unsigned integer
uint64_t a 64-bit unsigned integer
size_t
an unsigned integer large enough to hold the size of an object in memory
5.2.3 Data types
Integral types are defined for specific API elements to provide clarity in the interface definition, and to
improve code readability. For example, psa_algorithm_t and psa_status_t.
Structure types are declared using typedef instead of a struct tag, also to improve code readability.
Fully-defined types must be declared exactly as defined in this specification. Types that are not fully
defined in this specification must be defined by an implementation. See Implementation-specific types on
page 36.
5.2.4 Constants
Constant values are defined using C macros. Constants defined in this specification have names that are all
upper-case.
A constant macro evaluates to a compile-time constant expression.
IHI 0086
Page 30
1.1.2
Non-confidential
5.2.5 Function-like macros
Function-like macros are C macros that take parameters, providing supporting functionality in the API.
Function-like macros defined in this specification have names that are all upper-case.
Function-like macros are permitted to evaluate each argument multiple times or zero times. Providing
arguments that have side effects will result in IMPLEMENTATION DEFINED behavior, and is non-portable.
If all of the arguments to a function-like macro are compile-time constant expressions, the then result
evaluates to a compile-time constant expression.
If an argument to a function-like macro has an invalid value (for example, a value outside the domain of the
function-like macro), then the result is IMPLEMENTATION DEFINED.
5.2.6 Functions
Functions defined in this specification have names that are all lower-case.
An implementation is permitted to declare any API function with static inline linkage, instead of the
default extern linkage.
An implementation is permitted to also define a function-like macro with the same name as a function in
this specification. If an implementation defines a function-like macro for a function from this specification,
then:
∙ The implementation must also provide a definition of the function. This enables an application to
take the address of a function defined in this specification.
∙ The function-like macro must expand to code that evaluates each of its arguments exactly once, as if
the call was made to a C function. This enables an application to safely use arbitrary expressions as
arguments to a function defined in this specification.
If a non-pointer argument to a function has an invalid value (for example, a value outside the domain of
the function), then the function will normally return an error, as specified in the function definition. See
also Error handling.
If a pointer argument to a function has an invalid value (for example, a pointer outside the address space of
the program, or a null pointer), the result is IMPLEMENTATION DEFINED. See also Pointer conventions on page 33.
5.3 Error handling
5.3.1 Return status
Almost all functions return a status indication of type psa_status_t. This is an enumeration of integer
values, with 0 (PSA_SUCCESS) indicating successful operation and other values indicating errors. The
exceptions are functions which only access objects that are intended to be implemented as simple data
structures. Such functions cannot fail and either return void or a data value.
Unless specified otherwise, if multiple error conditions apply, an implementation is free to return any of
the applicable error codes. The choice of error code is considered an implementation quality issue.
Different implementations can make different choices, for example to favor code size over ease of
debugging or vice versa.
IHI 0086
Page 31
1.1.2
Non-confidential
If the behavior is undefined, for example, if a function receives an invalid pointer as a parameter, this
specification makes no guarantee that the function will return an error. Implementations are encouraged
to return an error or halt the application in a manner that is appropriate for the platform if the undefined
behavior condition can be detected. However, application developers need to be aware that undefined
behavior conditions cannot be detected in general.
5.3.2 Behavior on error
In general, function calls must be implemented atomically:
∙ When a function returns a type other than psa_status_t, the requested action has been carried out.
∙ When a function returns the status PSA_SUCCESS, the requested action has been carried out.
∙ When a function returns another status of type psa_status_t, no action has been carried out. Unless
otherwise documented by the API or the implementation, the content of output parameters is not
defined. The state of the system has not changed, except as described below.
In general, functions that modify the system state, for example, creating or destroying a key, must leave
the system state unchanged if they return an error code. There are specific conditions that can result in
different behavior:
∙ The status PSA_ERROR_BAD_STATE indicates that a parameter was not in a valid state for the requested
action. This parameter might have been modified by the call and is now in an error state. The only
valid action on an object in an error state is to abort it with the appropriate psa_xxx_abort() function.
See Multi-part operations on page 24.
∙ The status PSA_ERROR_INSUFFICIENT_DATA indicates that a key derivation object has reached its
maximum capacity. The key derivation operation might have been modified by the call. Any further
attempt to obtain output from the key derivation operation will return PSA_ERROR_INSUFFICIENT_DATA.
∙ The status PSA_ERROR_COMMUNICATION_FAILURE indicates that the communication between the
application and the cryptoprocessor has broken down. In this case, the cryptoprocessor must either
finish the requested action successfully, or interrupt the action and roll back the system to its original
state. Because it is often impossible to report the outcome to the application after a communication
failure, this specification does not provide a way for the application to determine whether the action
was successful.
∙ The statuses PSA_ERROR_STORAGE_FAILURE, PSA_ERROR_DATA_CORRUPT, PSA_ERROR_HARDWARE_FAILURE and
PSA_ERROR_CORRUPTION_DETECTED might indicate data corruption in the system state. When a function
returns one of these statuses, the system state might have changed from its previous state before
the function call, even though the function call failed.
∙ Some system states cannot be rolled back, for example, the internal state of the random number
generator or the content of access logs.
Implementation note
When a function returns an error status, it is recommended that implementations set output
parameters to safe defaults to avoid leaking confidential data and limit risk, in case an application
does not properly handle all errors.
IHI 0086
Page 32
1.1.2
Non-confidential
5.4 Parameter conventions
5.4.1 Pointer conventions
Unless explicitly stated in the documentation of a function, all pointers must be valid pointers to an object
of the specified type.
A parameter is considered a buffer if it points to an array of bytes. A buffer parameter always has the type
uint8_t * or const uint8_t *, and always has an associated parameter indicating the size of the array. Note
that a parameter of type void * is never considered a buffer.
All parameters of pointer type must be valid non-null pointers, unless the pointer is to a buffer of length 0
or the function’s documentation explicitly describes the behavior when the pointer is null. Passing a null
pointer as a function parameter in other cases is expected to abort the caller on implementations where
this is the normal behavior for a null pointer dereference.
Pointers to input parameters can be in read-only memory. Output parameters must be in writable memory.
Output parameters that are not buffers must also be readable, and the implementation must be able to
write to a non-buffer output parameter and read back the same value, as explained in Stability of
parameters on page 34.
5.4.2 Input buffer sizes
For input buffers, the parameter convention is:
const uint8_t *foo
Pointer to the first byte of the data. The pointer can be invalid if the buffer size is 0.
size_t foo_length
Size of the buffer in bytes.
The interface never uses input-output buffers.
5.4.3 Output buffer sizes
For output buffers, the parameter convention is:
uint8_t *foo
Pointer to the first byte of the data. The pointer can be invalid if the buffer size is 0.
size_t foo_size
The size of the buffer in bytes.
size_t *foo_length
On successful return, contains the length of the output in bytes.
The content of the data buffer and of *foo_length on errors is unspecified, unless explicitly mentioned in
the function description. They might be unmodified or set to a safe default. On successful completion, the
content of the buffer between the offsets *foo_length and foo_size is also unspecified.
Functions return PSA_ERROR_BUFFER_TOO_SMALL if the buffer size is insufficient to carry out the requested
operation. The interface defines macros to calculate a sufficient buffer size for each operation that has an
output buffer. These macros return compile-time constants if their arguments are compile-time constants,
so they are suitable for static or stack allocation. Refer to an individual function’s documentation for the
associated output size macro.
IHI 0086
Page 33
1.1.2
Non-confidential
Some functions always return exactly as much data as the size of the output buffer. In this case, the
parameter convention changes to:
uint8_t *foo
Pointer to the first byte of the output. The pointer can be invalid if the buffer size is 0.
size_t foo_length
The number of bytes to return in foo if successful.
5.4.4 Overlap between parameters
Output parameters that are not buffers must not overlap with any input buffer or with any other output
parameter. Otherwise, the behavior is undefined.
Output buffers can overlap with input buffers. In this event, the implementation must return the same
result as if the buffers did not overlap. The implementation must behave as if it had copied all the inputs
into temporary memory, as far as the result is concerned. However, it is possible that overlap between
parameters will affect the performance of a function call. Overlap might also affect memory management
security if the buffer is located in memory that the caller shares with another security context, as
described in Stability of parameters.
5.4.5 Stability of parameters
In some environments, it is possible for the content of a parameter to change while a function is executing.
It might also be possible for the content of an output parameter to be read before the function terminates.
This can happen if the application is multithreaded. In some implementations, memory can be shared
between security contexts, for example, between tasks in a multitasking operating system, between a user
land task and the kernel, or between the Non-secure world and the Secure world of a trusted execution
environment.
This section describes the assumptions that an implementation can make about function parameters, and
the guarantees that the implementation must provide about how it accesses parameters.
Parameters that are not buffers are assumed to be under the caller’s full control. In a shared memory
environment, this means that the parameter must be in memory that is exclusively accessible by the
application. In a multithreaded environment, this means that the parameter must not be modified during
the execution, and the value of an output parameter is undetermined until the function returns. The
implementation can read an input parameter that is not a buffer multiple times and expect to read the
same data. The implementation can write to an output parameter that is not a buffer and expect to read
back the value that it last wrote. The implementation has the same permissions on buffers that overlap
with a buffer in the opposite direction.
In an environment with multiple threads or with shared memory, the implementation carefully accesses
non-overlapping buffer parameters in order to prevent any security risk resulting from the content of the
buffer being modified or observed during the execution of the function. In an input buffer that does not
overlap with an output buffer, the implementation reads each byte of the input once, at most. The
implementation does not read from an output buffer that does not overlap with an input buffer.
Additionally, the implementation does not write data to a non-overlapping output buffer if this data is
potentially confidential and the implementation has not yet verified that outputting this data is authorized.
Unless otherwise specified, the implementation must not keep a reference to any parameter once a
function call has returned.
IHI 0086
Page 34
1.1.2
Non-confidential
5.5 Key types and algorithms
Types of cryptographic keys and cryptographic algorithms are encoded separately. Each is encoded by
using an integral type: psa_key_type_t and psa_algorithm_t, respectively.
There is some overlap in the information conveyed by key types and algorithms. Both types contain
enough information, so that the meaning of an algorithm type value does not depend on what type of key
it is used with, and vice versa. However, the particular instance of an algorithm might depend on the key
type. For example, the algorithm PSA_ALG_GCM can be instantiated as any AEAD algorithm using the GCM
mode over a block cipher. The underlying block cipher is determined by the key type.
Key types do not encode the key size. For example, AES-128, AES-192 and AES-256 share a key type
PSA_KEY_TYPE_AES.
5.5.1 Structure of key types and algorithms
Both types use a partial bitmask structure, which allows the analysis and building of values from parts.
However, the interface defines constants, so that applications do not need to depend on the encoding,
and an implementation might only care about the encoding for code size optimization.
The encodings follows a few conventions:
∙ The highest bit is a vendor flag. Current and future versions of this specification will only define
values where this bit is clear. Implementations that wish to define additional implementation-specific
values must use values where this bit is set, to avoid conflicts with future versions of this
specification.
∙ The next few highest bits indicate the algorithm or key category: hash, MAC, symmetric cipher,
asymmetric encryption, and so on.
∙ The following bits identify a family of algorithms or keys in a category-dependent manner.
∙ In some categories and algorithm families, the lowest-order bits indicate a variant in a systematic
way. For example, algorithm families that are parametrized around a hash function encode the hash
in the 8 lowest bits.
The Algorithm and key type encoding on page 287 appendix provides a full definition of the encoding of key
types and algorithm identifiers.
5.6 Concurrent calls
In some environments, an application can make calls to the Crypto API in separate threads. In such an
environment, concurrent calls are two or more calls to the API whose execution can overlap in time.
Concurrent calls are performed correctly, as if the calls were executed in sequence, provided that they
obey the following constraints:
∙ There is no overlap between an output parameter of one call and an input or output parameter of
another call. Overlap between input parameters is permitted.
∙ A call to destroy a key must not overlap with a concurrent call to any of the following functions:
- Any call where the same key identifier is a parameter to the call.
IHI 0086
Page 35
1.1.2
Non-confidential
- Any call in a multi-part operation, where the same key identifier was used as a parameter to a
previous step in the multi-part operation.
∙ Concurrent calls must not use the same operation object.
If any of these constraints are violated, the behavior is undefined.
If the application modifies an input parameter while a function call is in progress, the behavior is undefined.
Individual implementations can provide additional guarantees.
6 Implementation considerations
6.1 Implementation-specific aspects of the interface
6.1.1 Implementation profile
Implementations can implement a subset of the API and a subset of the available algorithms. The
implemented subset is known as the implementation’s profile. The documentation for each
implementation must describe the profile that it implements. This specification’s companion documents
also define a number of standard profiles.
6.1.2 Implementation-specific types
This specification defines a number of implementation-specific types, which represent objects whose
content depends on the implementation. These are defined as C typedef types in this specification, with a
comment /* implementation-defined type */ in place of the underlying type definition. For some types the
specification constrains the type, for example, by requiring that the type is a struct, or that it is convertible
to and from an unsigned integer. In the implementation’s version of psa/crypto.h, these types need to be
defined as complete C types so that objects of these types can be instantiated by application code.
Applications that rely on the implementation specific definition of any of these types might not be
portable to other implementations of this specification.
6.1.3 Implementation-specific macros
Some macro constants and function-like macros are precisely defined by this specification. The use of an
exact definition is essential if the definition can appear in more than one header file within a compilation.
Other macros that are defined by this specification have a macro body that is implementation-specific. The
description of an implementation-specific macro can optionally specify each of the following requirements:
∙ Input domains: the macro must be valid for arguments within the input domain.
∙ A return type: the macro result must be compatible with this type.
∙ Output range: the macro result must lie in the output range.
∙ Computed value: A precise mapping of valid input to output values.
Each implementation-specific macro is in one of following categories:
IHI 0086
Page 36
1.1.2
Non-confidential
Specification-defined value
The result type and computed value of the macro expression is defined by this
specification, but the definition of the macro body is provided by the implementation.
These macros are indicated in this specification using the comment:
/* specification-defined value */
For function-like macros with specification-defined values:
∙ Example implementations are provided in an appendix to this specification. See
Example macro implementations on page 298.
∙ The expected computation for valid and supported input arguments will be defined as
pseudo-code in a future version of this specification.
Implementation-defined value
The value of the macro expression is implementation-defined.
For some macros, the computed value is derived from the specification of one or more
cryptographic algorithms. In these cases, the result must exactly match the value in those
external specifications.
These macros are indicated in this specification using the comment:
/* implementation-defined value */
Some of these macros compute a result based on an algorithm or key type. If an implementation defines
vendor-specific algorithms or key types, then it must provide an implementation for such macros that
takes all relevant algorithms and types into account. Conversely, an implementation that does not support
a certain algorithm or key type can define such macros in a simpler way that does not take unsupported
argument values into account.
Some macros define the minimum sufficient output buffer size for certain functions. In some cases, an
implementation is permitted to require a buffer size that is larger than the theoretical minimum. An
implementation must define minimum-size macros in such a way that it guarantees that the buffer of the
resulting size is sufficient for the output of the corresponding function. Refer to each macro’s
documentation for the applicable requirements.
6.2 Porting to a platform
6.2.1 Platform assumptions
This specification is designed for a C99 platform. The interface is defined in terms of C macros, functions
and objects.
The specification assumes 8-bit bytes, and “byte” and “octet” are used synonymously.
IHI 0086
Page 37
1.1.2
Non-confidential
6.2.2 Platform-specific types
The specification makes use of some types defined in C99. These types must be defined in the
implementation version of psa/crypto.h or by a header included in this file. The following C99 types are
used:
uint8_t, uint16_t, uint32_t
Unsigned integer types with 8, 16 and 32 value bits respectively. These types are defined
by the C99 header stdint.h.
6.2.3 Cryptographic hardware support
Implementations are encouraged to make use of hardware accelerators where available. A future version
of this specification will define a function interface that calls drivers for hardware accelerators and external
cryptographic hardware.
6.3 Security requirements and recommendations
6.3.1 Error detection
Implementations that provide isolation between the caller and the cryptography processing environment
must validate parameters to ensure that the cryptography processing environment is protected from
attacks caused by passing invalid parameters.
Even implementations that do not provide isolation are recommended to detect bad parameters and
fail-safe where possible.
6.3.2 Indirect object references
Implementations can use different strategies for allocating key identifiers, and other types of indirect
object reference.
Implementations that provide isolation between the caller and the cryptography processing environment
must consider the threats relating to abuse and misuse of key identifiers and other indirect resource
references. For example, multi-part operations can be implemented as backend state to which the client
only maintains an indirect reference in the application’s multi-part operation object.
An implementation that supports multiple callers must implement strict isolation of API resources between
different callers. For example, a client must not be able to obtain a reference to another client’s key by
guessing the key identifier value. Isolation of key identifiers can be achieved in several ways. For example:
∙ There is a single identifier namespace for all clients, and the implementation verifies that the client is
the owner of the identifier when looking up the key.
∙ Each client has an independent identifier namespace, and the implementation uses a client specific
identifier-to-key mapping when looking up the key.
After a volatile key identifier is destroyed, it is recommended that the implementation does not
immediately reuse the same identifier value for a different key. This reduces the risk of an attack that is
able to exploit a key identifier reuse vulnerability within an application.
IHI 0086
Page 38
1.1.2
Non-confidential
6.3.3 Memory cleanup
Implementations must wipe all sensitive data from memory when it is no longer used. It is recommended
that they wipe this sensitive data as soon as possible. All temporary data used during the execution of a
function, such as stack buffers, must be wiped before the function returns. All data associated with an
object, such as a multi-part operation, must be wiped, at the latest, when the object becomes inactive, for
example, when a multi-part operation is aborted.
The rationale for this non-functional requirement is to minimize impact if the system is compromised. If
sensitive data is wiped immediately after use, only data that is currently in use can be leaked. It does not
compromise past data.
6.3.4 Managing key material
In implementations that have limited volatile memory for keys, the implementation is permitted to store a
volatile key to a temporary location in non-volatile memory. The implementation must delete any
non-volatile copies when the key is destroyed, and it is recommended that these copies are deleted as
soon as the key is reloaded into volatile memory. An implementation that uses this method must clear any
stored volatile key material on startup.
Implementing the memory cleanup rule (see Memory cleanup) for a persistent key can result in inefficiencies
when the same persistent key is used sequentially in multiple cryptographic operations. The inefficiency
stems from loading the key from non-volatile storage on each use of the key. The PSA_KEY_USAGE_CACHE
usage flag in a key policy allows an application to request that the implementation does not cleanup
non-essential copies of persistent key material, effectively suspending the cleanup rules for that key. The
effects of this policy depend on the implementation and the key, for example:
∙ For volatile keys or keys in a secure element with no open/close mechanism, this is likely to have no
effect.
∙ For persistent keys that are not in a secure element, this allows the implementation to keep the key
in a memory cache outside of the memory used by ongoing operations.
∙ For keys in a secure element with an open/close mechanism, this is a hint to keep the key open in the
secure element.
The application can indicate when it has finished using the key by calling psa_purge_key(), to request that
the key material is cleaned from memory.
6.3.5 Safe outputs on error
Implementations must ensure that confidential data is not written to output parameters before validating
that the disclosure of this confidential data is authorized. This requirement is particularly important for
implementations where the caller can share memory with another security context, as described in
Stability of parameters on page 34.
In most cases, the specification does not define the content of output parameters when an error occurs. It
is recommended that implementations try to ensure that the content of output parameters is as safe as
possible, in case an application flaw or a data leak causes it to be used. In particular, Arm recommends that
implementations avoid placing partial output in output buffers when an action is interrupted. The meaning
of “safe as possible” depends on the implementation, as different environments require different
compromises between implementation complexity, overall robustness and performance. Some common
strategies are to leave output parameters unchanged, in case of errors, or zeroing them out.
IHI 0086
Page 39
1.1.2
Non-confidential
6.3.6 Attack resistance
Cryptographic code tends to manipulate high-value secrets, from which other secrets can be unlocked. As
such, it is a high-value target for attacks. There is a vast body of literature on attack types, such as side
channel attacks and glitch attacks. Typical side channels include timing, cache access patterns,
branch-prediction access patterns, power consumption, radio emissions and more.
This specification does not specify particular requirements for attack resistance. Implementers are
encouraged to consider the attack resistance desired in each use case and design their implementation
accordingly. Security standards for attack resistance for particular targets might be applicable in certain
use cases.
6.4 Other implementation considerations
6.4.1 Philosophy of resource management
The specification allows most functions to return PSA_ERROR_INSUFFICIENT_MEMORY. This gives
implementations the freedom to manage memory as they please.
Alternatively, the interface is also designed for conservative strategies of memory management. An
implementation can avoid dynamic memory allocation altogether by obeying certain restrictions:
∙ Pre-allocate memory for a predefined number of keys, each with sufficient memory for all key types
that can be stored.
∙ For multi-part operations, in an implementation with no isolation, place all the data that needs to be
carried over from one step to the next in the operation object. The application is then fully in control
of how memory is allocated for the operation.
∙ In an implementation with isolation, pre-allocate memory for a predefined number of operations
inside the cryptoprocessor.
7 Usage considerations
7.1 Security recommendations
7.1.1 Always check for errors
Most functions in the Crypto API can return errors. All functions that can fail have the return type
psa_status_t. A few functions cannot fail, and thus, return void or some other type.
If an error occurs, unless otherwise specified, the content of the output parameters is undefined and must
not be used.
Some common causes of errors include:
∙ In implementations where the keys are stored and processed in a separate environment from the
application, all functions that need to access the cryptography processing environment might fail due
to an error in the communication between the two environments.
∙ If an algorithm is implemented with a hardware accelerator, which is logically separate from the
application processor, the accelerator might fail, even when the application processor keeps running
normally.
IHI 0086
Page 40
1.1.2
Non-confidential
∙ Most functions might fail due to a lack of resources. However, some implementations guarantee that
certain functions always have sufficient memory.
∙ All functions that access persistent keys might fail due to a storage failure.
∙ All functions that require randomness might fail due to a lack of entropy. Implementations are
encouraged to seed the random generator with sufficient entropy during the execution of
psa_crypto_init(). However, some security standards require periodic reseeding from a hardware
random generator, which can fail.
7.1.2 Shared memory and concurrency
Some environments allow applications to be multithreaded, while others do not. In some environments,
applications can share memory with a different security context. In environments with multithreaded
applications or shared memory, applications must be written carefully to avoid data corruption or leakage.
This specification requires the application to obey certain constraints.
In general, the Crypto API allows either one writer or any number of simultaneous readers, on any given
object. In other words, if two or more calls access the same object concurrently, then the behavior is only
well-defined if all the calls are only reading from the object and do not modify it. Read accesses include
reading memory by input parameters and reading keystore content by using a key. For more details, refer
to Concurrent calls on page 35.
If an application shares memory with another security context, it can pass shared memory blocks as input
buffers or output buffers, but not as non-buffer parameters. For more details, refer to Stability of
parameters on page 34.
7.1.3 Cleaning up after use
To minimize impact if the system is compromised, it is recommended that applications wipe all sensitive
data from memory when it is no longer used. That way, only data that is currently in use can be leaked, and
past data is not compromised.
Wiping sensitive data includes:
∙ Clearing temporary buffers in the stack or on the heap.
∙ Aborting operations if they will not be finished.
∙ Destroying keys that are no longer used.
8 Library management reference
8.1 Status codes
The Crypto API uses the status code definitions that are shared with the other PSA Certified APIs. The
Crypto API also provides some Crypto API-specific status codes, see Error codes specific to the Crypto API
on page 43.
The following elements are defined in psa/error.h from PSA Certified Status code API [PSA-STAT]
(previously defined in [PSA-FFM]):
IHI 0086
Page 41
1.1.2
Non-confidential
typedef int32_t psa_status_t;
#define PSA_SUCCESS ((psa_status_t)0)
#define PSA_ERROR_GENERIC_ERROR
((psa_status_t)-132)
#define PSA_ERROR_NOT_PERMITTED
((psa_status_t)-133)
#define PSA_ERROR_NOT_SUPPORTED
((psa_status_t)-134)
#define PSA_ERROR_INVALID_ARGUMENT
((psa_status_t)-135)
#define PSA_ERROR_INVALID_HANDLE
((psa_status_t)-136)
#define PSA_ERROR_BAD_STATE
((psa_status_t)-137)
#define PSA_ERROR_BUFFER_TOO_SMALL
((psa_status_t)-138)
#define PSA_ERROR_ALREADY_EXISTS
((psa_status_t)-139)
#define PSA_ERROR_DOES_NOT_EXIST
((psa_status_t)-140)
#define PSA_ERROR_INSUFFICIENT_MEMORY
((psa_status_t)-141)
#define PSA_ERROR_INSUFFICIENT_STORAGE
((psa_status_t)-142)
#define PSA_ERROR_INSUFFICIENT_DATA
((psa_status_t)-143)
#define PSA_ERROR_COMMUNICATION_FAILURE ((psa_status_t)-145)
#define PSA_ERROR_STORAGE_FAILURE
((psa_status_t)-146)
#define PSA_ERROR_HARDWARE_FAILURE
((psa_status_t)-147)
#define PSA_ERROR_INVALID_SIGNATURE
((psa_status_t)-149)
#define PSA_ERROR_CORRUPTION_DETECTED
((psa_status_t)-151)
#define PSA_ERROR_DATA_CORRUPT
((psa_status_t)-152)
#define PSA_ERROR_DATA_INVALID
((psa_status_t)-153)
These definitions must be available to an application that includes the psa/crypto.h header file.
Implementation note
An implementation is permitted to define the status code interface elements within the psa/crypto.h
header file, or to define them via inclusion of a psa/error.h header file that is shared with the
implementation of other PSA Certified APIs.
8.1.1 Common error codes
Some of the common status codes have a more precise meaning when returned by a function in the
Crypto API, compared to the definitions in [PSA-STAT].
Error code
Meaning in the Crypto API
PSA_ERROR_INVALID_HANDLE
A key identifier is not valid. See also Key identifiers on page 22.
continues on next page
IHI 0086
Page 42
1.1.2
Non-confidential
Table 5 - continued from previous page
Error code
Meaning in the Crypto API
PSA_ERROR_BAD_STATE
Multi-part operations return this error when one of the functions is
called out of sequence. Refer to the function descriptions for
permitted sequencing of functions.
Implementations can return this error if the caller has not initialized
the library by a call to psa_crypto_init().
PSA_ERROR_BUFFER_TOO_SMALL
Applications can call the PSA_xxx_SIZE macro listed in the function
description to determine a sufficient buffer size.
PSA_ERROR_STORAGE_FAILURE
When a storage failure occurs, it is no longer possible to ensure the
global integrity of the keystore. Depending on the global integrity
guarantees offered by the implementation, access to other data
might fail even if the data is still readable but its integrity cannot be
guaranteed.
PSA_ERROR_CORRUPTION_DETECTED
This error code is intended as a last resort when a security breach is
detected and it is unsure whether the keystore data is still
protected. Implementations must only return this error code to
report an alarm from a tampering detector, to indicate that the
confidentiality of stored data can no longer be guaranteed, or to
indicate that the integrity of previously returned data is now
considered compromised.
PSA_ERROR_DATA_CORRUPT
When a storage failure occurs, it is no longer possible to ensure the
global integrity of the keystore. Depending on the global integrity
guarantees offered by the implementation, access to other data
might fail even if the data is still readable but its integrity cannot be
guaranteed.
8.1.2 Error codes specific to the Crypto API
The following elements are defined in the psa/crypto.h header file.
PSA_ERROR_INSUFFICIENT_ENTROPY (macro)
A status code that indicates that there is not enough entropy to generate random data needed for the
requested action.
#define PSA_ERROR_INSUFFICIENT_ENTROPY ((psa_status_t)-148)
This error indicates a failure of a hardware random generator. Application writers must note that this error
can be returned not only by functions whose purpose is to generate random data, such as key, IV or nonce
generation, but also by functions that execute an algorithm with a randomized result, as well as functions
that use randomization of intermediate computations as a countermeasure to certain attacks.
It is recommended that implementations do not return this error after psa_crypto_init() has succeeded.
This can be achieved if the implementation generates sufficient entropy during initialization and
IHI 0086
Page 43
1.1.2
Non-confidential
subsequently a cryptographically secure pseudorandom generator (PRNG) is used. However,
implementations might return this error at any time, for example, if a policy requires the PRNG to be
reseeded during normal operation.
PSA_ERROR_INVALID_PADDING (macro)
A status code that indicates that the decrypted padding is incorrect.
#define PSA_ERROR_INVALID_PADDING ((psa_status_t)-150)
Warning: In some protocols, when decrypting data, it is essential that the behavior of the application
does not depend on whether the padding is correct, down to precise timing. Protocols that use
authenticated encryption are recommended for use by applications, rather than plain encryption. If the
application must perform a decryption of unauthenticated data, the application writer must take care
not to reveal whether the padding is invalid.
Implementations must handle padding carefully, aiming to make it impossible for an external observer to
distinguish between valid and invalid padding. In particular, it is recommended that the timing of a
decryption operation does not depend on the validity of the padding.
8.2 Crypto API library
8.2.1 API version
PSA_CRYPTO_API_VERSION_MAJOR (macro)
The major version of this implementation of the Crypto API.
#define PSA_CRYPTO_API_VERSION_MAJOR 1
PSA_CRYPTO_API_VERSION_MINOR (macro)
The minor version of this implementation of the Crypto API.
#define PSA_CRYPTO_API_VERSION_MINOR 1
8.2.2 Library initialization
psa_crypto_init (function)
Library initialization.
psa_status_t psa_crypto_init(void);
IHI 0086
Page 44
1.1.2
Non-confidential
Returns: psa_status_t
PSA_SUCCESS
Success.
PSA_ERROR_INSUFFICIENT_ENTROPY
PSA_ERROR_INSUFFICIENT_MEMORY
PSA_ERROR_COMMUNICATION_FAILURE
PSA_ERROR_CORRUPTION_DETECTED
Description
It is recommended that applications call this function before calling any other function in this module.
Applications are permitted to call this function more than once. Once a call succeeds, subsequent calls are
guaranteed to succeed.
If the application calls any function that returns a psa_status_t result code before calling psa_crypto_init(),
the following will occur:
∙ If initialization of the library is essential for secure operation of the function, the implementation
must return PSA_ERROR_BAD_STATE or other appropriate error.
∙ If failure to initialize the library does not compromise the security of the function, the
implementation must either provide the expected result for the function, or return
PSA_ERROR_BAD_STATE or other appropriate error.
Note:
The following scenarios are examples where an implementation can require that the library has been
initialized by calling psa_crypto_init():
∙ A client-server implementation, in which psa_crypto_init() establishes the communication with
the server. No key management or cryptographic operation can be performed until this is done.
∙ An implementation in which psa_crypto_init() initializes the random bit generator, and no
operations that require the RNG can be performed until this is done. For example, random data,
key, IV, or nonce generation; randomized signature or encryption; and algorithms that are
implemented with blinding.
Warning: The set of functions that depend on successful initialization of the library is IMPLEMENTATION
DEFINED. Applications that rely on calling functions before initializing the library might not be portable
to other implementations.
IHI 0086
Page 45
1.1.2
Non-confidential
9 Key management reference
9.1 Key attributes
Key attributes are managed in a psa_key_attributes_t object. These are used when a key is created, after
which the key attributes are fixed. Attributes of an existing key can be queried using
psa_get_key_attributes().
Description of the individual attributes is found in the following sections:
∙ Key types on page 50
∙ Key identifiers on page 80
∙ Key lifetimes on page 72
∙ Key policies on page 83
9.1.1 Managing key attributes
psa_key_attributes_t (typedef)
The type of an object containing key attributes.
typedef /* implementation-defined type */ psa_key_attributes_t;
This is the object that represents the metadata of a key object. Metadata that can be stored in attributes
includes:
∙ The location of the key in storage, indicated by its key identifier and its lifetime.
∙ The key’s policy, comprising usage flags and a specification of the permitted algorithm(s).
∙ Information about the key itself: the key type and its size.
∙ Implementations can define additional attributes.
The actual key material is not considered an attribute of a key. Key attributes do not contain information
that is generally considered highly confidential.
Note:
Implementations are recommended to define the attribute object as a simple data structure, with
fields corresponding to the individual key attributes. In such an implementation, each function
psa_set_key_xxx() sets a field and the corresponding function psa_get_key_xxx() retrieves the value
of the field.
An implementations can report attribute values that are equivalent to the original one, but have a
different encoding. For example, an implementation can use a more compact representation for
types where many bit-patterns are invalid or not supported, and store all values that it does not
support as a special marker value. In such an implementation, after setting an invalid value, the
corresponding get function returns an invalid value which might not be the one that was originally
stored.
IHI 0086
Page 46
1.1.2
Non-confidential
This is an implementation-defined type. Applications that make assumptions about the content of this
object will result in in implementation-specific behavior, and are non-portable.
An attribute object can contain references to auxiliary resources, for example pointers to allocated
memory or indirect references to pre-calculated values. In order to free such resources, the application
must call psa_reset_key_attributes(). As an exception, calling psa_reset_key_attributes() on an attribute
object is optional if the object has only been modified by the following functions since it was initialized or
last reset with psa_reset_key_attributes():
∙ psa_set_key_id()
∙ psa_set_key_lifetime()
∙ psa_set_key_type()
∙ psa_set_key_bits()
∙ psa_set_key_usage_flags()
∙ psa_set_key_algorithm()
Before calling any function on a key attribute object, the application must initialize it by any of the
following means:
∙ Set the object to all-bits-zero, for example:
psa_key_attributes_t attributes;
memset(&attributes, 0, sizeof(attributes));
∙ Initialize the object to logical zero values by declaring the object as static or global without an
explicit initializer, for example:
static psa_key_attributes_t attributes;
∙ Initialize the object to the initializer PSA_KEY_ATTRIBUTES_INIT, for example:
psa_key_attributes_t attributes = PSA_KEY_ATTRIBUTES_INIT;
∙ Assign the result of the function psa_key_attributes_init() to the object, for example:
psa_key_attributes_t attributes;
attributes = psa_key_attributes_init();
A freshly initialized attribute object contains the following values:
IHI 0086
Page 47
1.1.2
Non-confidential
Attribute
Value
lifetime
PSA_KEY_LIFETIME_VOLATILE.
key identifier PSA_KEY_ID_NULL - which is not a valid key identifier.
type
PSA_KEY_TYPE_NONE - meaning that the type is unspecified.
key size
0 - meaning that the size is unspecified.
usage flags
0 - which permits no usage except exporting a public key.
algorithm
PSA_ALG_NONE - which does not permit cryptographic usage, but permits exporting.
Usage
A typical sequence to create a key is as follows:
1. Create and initialize an attribute object.
2. If the key is persistent, call psa_set_key_id(). Also call psa_set_key_lifetime() to place the key in a
non-default location.
3. Set the key policy with psa_set_key_usage_flags() and psa_set_key_algorithm().
4. Set the key type with psa_set_key_type(). Skip this step if copying an existing key with
psa_copy_key().
5. When generating a random key with psa_generate_key() or deriving a key with
psa_key_derivation_output_key(), set the desired key size with psa_set_key_bits().
6. Call a key creation function: psa_import_key(), psa_generate_key(), psa_key_derivation_output_key()
or psa_copy_key(). This function reads the attribute object, creates a key with these attributes, and
outputs an identifier for the newly created key.
7. Optionally call psa_reset_key_attributes(), now that the attribute object is no longer needed.
Currently this call is not required as the attributes defined in this specification do not require
additional resources beyond the object itself.
A typical sequence to query a key’s attributes is as follows:
1. Call psa_get_key_attributes().
2. Call psa_get_key_xxx() functions to retrieve the required attribute(s).
3. Call psa_reset_key_attributes() to free any resources that can be used by the attribute object.
Once a key has been created, it is impossible to change its attributes.
IHI 0086
Page 48
1.1.2
Non-confidential
PSA_KEY_ATTRIBUTES_INIT (macro)
This macro returns a suitable initializer for a key attribute object of type psa_key_attributes_t.
#define PSA_KEY_ATTRIBUTES_INIT /* implementation-defined value */
psa_key_attributes_init (function)
Return an initial value for a key attribute object.
psa_key_attributes_t psa_key_attributes_init(void);
Returns: psa_key_attributes_t
psa_get_key_attributes (function)
Retrieve the attributes of a key.
psa_status_t psa_get_key_attributes(psa_key_id_t key,
psa_key_attributes_t * attributes);
Parameters
key
Identifier of the key to query.
attributes
On entry, *attributes must be in a valid state. On successful return, it
contains the attributes of the key. On failure, it is equivalent to a
freshly-initialized attribute object.
Returns: psa_status_t
PSA_SUCCESS
Success. attributes contains the attributes of the key.
PSA_ERROR_BAD_STATE
The library requires initializing by a call to psa_crypto_init().
PSA_ERROR_INVALID_HANDLE
key is not a valid key identifier.
PSA_ERROR_INSUFFICIENT_MEMORY
PSA_ERROR_COMMUNICATION_FAILURE
PSA_ERROR_CORRUPTION_DETECTED
PSA_ERROR_STORAGE_FAILURE
PSA_ERROR_DATA_CORRUPT
PSA_ERROR_DATA_INVALID
Description
This function first resets the attribute object as with psa_reset_key_attributes(). It then copies the
attributes of the given key into the given attribute object.
Note:
IHI 0086
Page 49
1.1.2
Non-confidential
This function clears any previous content from the attribute object and therefore expects it to be in
a valid state. In particular, if this function is called on a newly allocated attribute object, the attribute
object must be initialized before calling this function.
Note:
This function might allocate memory or other resources. Once this function has been called on an
attribute object, psa_reset_key_attributes() must be called to free these resources.
psa_reset_key_attributes (function)
Reset a key attribute object to a freshly initialized state.
void psa_reset_key_attributes(psa_key_attributes_t * attributes);
Parameters
attributes
The attribute object to reset.
Returns: void
Description
The attribute object must be initialized as described in the documentation of the type psa_key_attributes_t
before calling this function. Once the object has been initialized, this function can be called at any time.
This function frees any auxiliary resources that the object might contain.
9.2 Key types
9.2.1 Key type encoding
psa_key_type_t (typedef)
Encoding of a key type.
typedef uint16_t psa_key_type_t;
This is a structured bitfield that identifies the category and type of key. The range of key type values is
divided as follows:
PSA_KEY_TYPE_NONE == 0
Reserved as an invalid key type.
0x0001 - 0x7fff
Specification-defined key types. Key types defined by this standard always have bit 15
clear. Unallocated key type values in this range are reserved for future use.
0x8000 - 0xffff
Implementation-defined key types. Implementations that define additional key types must
use an encoding with bit 15 set. The related support macros will be easier to write if these
key encodings also respect the bitwise structure used by standard encodings.
IHI 0086
Page 50
1.1.2
Non-confidential
The Algorithm and key type encoding on page 287 appendix provides a full definition of the key type
encoding.
PSA_KEY_TYPE_NONE (macro)
An invalid key type value.
#define PSA_KEY_TYPE_NONE ((psa_key_type_t)0x0000)
Zero is not the encoding of any key type.
9.2.2 Key categories
PSA_KEY_TYPE_IS_UNSTRUCTURED (macro)
Whether a key type is an unstructured array of bytes.
#define PSA_KEY_TYPE_IS_UNSTRUCTURED(type) /* specification-defined value */
Parameters
type
A key type: a value of type psa_key_type_t.
Description
This encompasses both symmetric keys and non-key data.
See Symmetric keys on page 52 for a list of symmetric key types.
PSA_KEY_TYPE_IS_ASYMMETRIC (macro)
Whether a key type is asymmetric: either a key pair or a public key.
#define PSA_KEY_TYPE_IS_ASYMMETRIC(type) /* specification-defined value */
Parameters
type
A key type: a value of type psa_key_type_t.
Description
See RSA keys on page 59 for a list of asymmetric key types.
PSA_KEY_TYPE_IS_PUBLIC_KEY (macro)
Whether a key type is the public part of a key pair.
#define PSA_KEY_TYPE_IS_PUBLIC_KEY(type) /* specification-defined value */
IHI 0086
Page 51
1.1.2
Non-confidential
Parameters
type
A key type: a value of type psa_key_type_t.
PSA_KEY_TYPE_IS_KEY_PAIR (macro)
Whether a key type is a key pair containing a private part and a public part.
#define PSA_KEY_TYPE_IS_KEY_PAIR(type) /* specification-defined value */
Parameters
type
A key type: a value of type psa_key_type_t.
9.2.3 Symmetric keys
PSA_KEY_TYPE_RAW_DATA (macro)
Raw data.
#define PSA_KEY_TYPE_RAW_DATA ((psa_key_type_t)0x1001)
A “key” of this type cannot be used for any cryptographic operation. Applications can use this type to store
arbitrary data in the keystore.
The bit size of a raw key must be a non-zero multiple of 8. The maximum size of a raw key is
IMPLEMENTATION DEFINED.
Compatible algorithms
PSA_ALG_HKDF (non-secret inputs)
PSA_ALG_HKDF_EXPAND (non-secret inputs)
PSA_ALG_HKDF_EXTRACT (non-secret inputs)
PSA_ALG_TLS12_PRF (non-secret inputs)
PSA_ALG_TLS12_PSK_TO_MS (non-secret inputs)
PSA_KEY_TYPE_HMAC (macro)
HMAC key.
#define PSA_KEY_TYPE_HMAC ((psa_key_type_t)0x1100)
The key policy determines which underlying hash algorithm the key can be used for.
The bit size of an HMAC key must be a non-zero multiple of 8. An HMAC key is typically the same size as
the output of the underlying hash algorithm. An HMAC key that is longer than the block size of the
underlying hash algorithm will be hashed before use.
When an HMAC key is created that is longer than the block size, it is IMPLEMENTATION DEFINED whether the
implementation stores the original HMAC key, or the hash of the HMAC key. If the hash of the key is
stored, the key size reported by psa_get_key_attributes() will be the size of the hashed key.
IHI 0086
Page 52
1.1.2
Non-confidential
Note:
PSA_HASH_LENGTH(alg) provides the output size of hash algorithm alg, in bytes.
PSA_HASH_BLOCK_LENGTH(alg) provides the block size of hash algorithm alg, in bytes.
Compatible algorithms
PSA_ALG_HMAC
PSA_KEY_TYPE_DERIVE (macro)
A secret for key derivation.
#define PSA_KEY_TYPE_DERIVE ((psa_key_type_t)0x1200)
This key type is for high-entropy secrets only. For low-entropy secrets, PSA_KEY_TYPE_PASSWORD should be
used instead.
These keys can be used in the PSA_KEY_DERIVATION_INPUT_SECRET or PSA_KEY_DERIVATION_INPUT_PASSWORD input
step of key derivation algorithms.
The key policy determines which key derivation algorithm the key can be used for.
The bit size of a secret for key derivation must be a non-zero multiple of 8. The maximum size of a secret
for key derivation is IMPLEMENTATION DEFINED.
Compatible algorithms
PSA_ALG_HKDF (secret input)
PSA_ALG_HKDF_EXPAND (secret input)
PSA_ALG_HKDF_EXTRACT (secret input)
PSA_ALG_TLS12_PRF (secret input)
PSA_ALG_TLS12_PSK_TO_MS (secret input)
PSA_KEY_TYPE_PASSWORD (macro)
A low-entropy secret for password hashing or key derivation.
#define PSA_KEY_TYPE_PASSWORD ((psa_key_type_t)0x1203)
This key type is suitable for passwords and passphrases which are typically intended to be memorizable by
humans, and have a low entropy relative to their size. It can be used for randomly generated or derived
keys with maximum or near-maximum entropy, but PSA_KEY_TYPE_DERIVE is more suitable for such keys. It is
not suitable for passwords with extremely low entropy, such as numerical PINs.
These keys can be used in the PSA_KEY_DERIVATION_INPUT_PASSWORD input step of key derivation algorithms.
Algorithms that accept such an input were designed to accept low-entropy secret and are known as
password hashing or key stretching algorithms.
These keys cannot be used in the PSA_KEY_DERIVATION_INPUT_SECRET input step of key derivation algorithms,
as the algorithms expect such an input to have high entropy.
IHI 0086
Page 53
1.1.2
Non-confidential
The key policy determines which key derivation algorithm the key can be used for, among the permissible
subset defined above.
Compatible algorithms
PSA_ALG_PBKDF2_HMAC() (password input)
PSA_ALG_PBKDF2_AES_CMAC_PRF_128 (password input)
PSA_KEY_TYPE_PASSWORD_HASH (macro)
A secret value that can be used to verify a password hash.
#define PSA_KEY_TYPE_PASSWORD_HASH ((psa_key_type_t)0x1205)
The key policy determines which key derivation algorithm the key can be used for, among the same
permissible subset as for PSA_KEY_TYPE_PASSWORD.
Compatible algorithms
PSA_ALG_PBKDF2_HMAC() (key output and verification)
PSA_ALG_PBKDF2_AES_CMAC_PRF_128 (key output and verification)
PSA_KEY_TYPE_PEPPER (macro)
A secret value that can be used when computing a password hash.
#define PSA_KEY_TYPE_PEPPER ((psa_key_type_t)0x1206)
The key policy determines which key derivation algorithm the key can be used for, among the subset of
algorithms that can use pepper.
Compatible algorithms
PSA_ALG_PBKDF2_HMAC() (salt input)
PSA_ALG_PBKDF2_AES_CMAC_PRF_128 (salt input)
PSA_KEY_TYPE_AES (macro)
Key for a cipher, AEAD or MAC algorithm based on the AES block cipher.
#define PSA_KEY_TYPE_AES ((psa_key_type_t)0x2400)
The size of the key is related to the AES algorithm variant. For algorithms except the XTS block cipher
mode, the following key sizes are used:
∙ AES-128 uses a 16-byte key : key_bits = 128
∙ AES-192 uses a 24-byte key : key_bits = 192
∙ AES-256 uses a 32-byte key : key_bits = 256
For the XTS block cipher mode (PSA_ALG_XTS), the following key sizes are used:
IHI 0086
Page 54
1.1.2
Non-confidential
∙ AES-128-XTS uses two 16-byte keys : key_bits = 256
∙ AES-192-XTS uses two 24-byte keys : key_bits = 384
∙ AES-256-XTS uses two 32-byte keys : key_bits = 512
The AES block cipher is defined in FIPS Publication 197: Advanced Encryption Standard (AES) [FIPS197].
Compatible algorithms
PSA_ALG_CBC_MAC
PSA_ALG_CMAC
PSA_ALG_CTR
PSA_ALG_CFB
PSA_ALG_OFB
PSA_ALG_XTS
PSA_ALG_CBC_NO_PADDING
PSA_ALG_CBC_PKCS7
PSA_ALG_ECB_NO_PADDING
PSA_ALG_CCM
PSA_ALG_GCM
PSA_KEY_TYPE_ARIA (macro)
Key for a cipher, AEAD or MAC algorithm based on the ARIA block cipher.
#define PSA_KEY_TYPE_ARIA ((psa_key_type_t)0x2406)
The size of the key is related to the ARIA algorithm variant. For algorithms except the XTS block cipher
mode, the following key sizes are used:
∙ ARIA-128 uses a 16-byte key : key_bits = 128
∙ ARIA-192 uses a 24-byte key : key_bits = 192
∙ ARIA-256 uses a 32-byte key : key_bits = 256
For the XTS block cipher mode (PSA_ALG_XTS), the following key sizes are used:
∙ ARIA-128-XTS uses two 16-byte keys : key_bits = 256
∙ ARIA-192-XTS uses two 24-byte keys : key_bits = 384
∙ ARIA-256-XTS uses two 32-byte keys : key_bits = 512
The ARIA block cipher is defined in A Description of the ARIA Encryption Algorithm [RFC5794].
IHI 0086
Page 55
1.1.2
Non-confidential
Compatible algorithms
PSA_ALG_CBC_MAC
PSA_ALG_CMAC
PSA_ALG_CTR
PSA_ALG_CFB
PSA_ALG_OFB
PSA_ALG_XTS
PSA_ALG_CBC_NO_PADDING
PSA_ALG_CBC_PKCS7
PSA_ALG_ECB_NO_PADDING
PSA_ALG_CCM
PSA_ALG_GCM
PSA_KEY_TYPE_DES (macro)
Key for a cipher or MAC algorithm based on DES or 3DES (Triple-DES).
#define PSA_KEY_TYPE_DES ((psa_key_type_t)0x2301)
The size of the key determines which DES algorithm is used:
∙ Single DES uses an 8-byte key : key_bits = 64
∙ 2-key 3DES uses a 16-byte key : key_bits = 128
∙ 3-key 3DES uses a 24-byte key : key_bits = 192
Warning: Single DES and 2-key 3DES are weak and strongly deprecated and are only recommended
for decrypting legacy data.
3-key 3DES is weak and deprecated and is only recommended for use in legacy applications.
The DES and 3DES block ciphers are defined in NIST Special Publication 800-67: Recommendation for the
Triple Data Encryption Algorithm (TDEA) Block Cipher [SP800-67].
Compatible algorithms
PSA_ALG_CBC_MAC
PSA_ALG_CMAC
PSA_ALG_CTR
PSA_ALG_CFB
PSA_ALG_OFB
PSA_ALG_XTS
PSA_ALG_CBC_NO_PADDING
PSA_ALG_CBC_PKCS7
PSA_ALG_ECB_NO_PADDING
IHI 0086
Page 56
1.1.2
Non-confidential
PSA_KEY_TYPE_CAMELLIA (macro)
Key for a cipher, AEAD or MAC algorithm based on the Camellia block cipher.
#define PSA_KEY_TYPE_CAMELLIA ((psa_key_type_t)0x2403)
The size of the key is related to the Camellia algorithm variant. For algorithms except the XTS block cipher
mode, the following key sizes are used:
∙ Camellia-128 uses a 16-byte key : key_bits = 128
∙ Camellia-192 uses a 24-byte key : key_bits = 192
∙ Camellia-256 uses a 32-byte key : key_bits = 256
For the XTS block cipher mode (PSA_ALG_XTS), the following key sizes are used:
∙ Camellia-128-XTS uses two 16-byte keys : key_bits = 256
∙ Camellia-192-XTS uses two 24-byte keys : key_bits = 384
∙ Camellia-256-XTS uses two 32-byte keys : key_bits = 512
The Camellia block cipher is defined in Specification of Camellia - a 128-bit Block Cipher [NTT-CAM] and
also described in A Description of the Camellia Encryption Algorithm [RFC3713].
Compatible algorithms
PSA_ALG_CBC_MAC
PSA_ALG_CMAC
PSA_ALG_CTR
PSA_ALG_CFB
PSA_ALG_OFB
PSA_ALG_XTS
PSA_ALG_CBC_NO_PADDING
PSA_ALG_CBC_PKCS7
PSA_ALG_ECB_NO_PADDING
PSA_ALG_CCM
PSA_ALG_GCM
PSA_KEY_TYPE_SM4 (macro)
Key for a cipher, AEAD or MAC algorithm based on the SM4 block cipher.
#define PSA_KEY_TYPE_SM4 ((psa_key_type_t)0x2405)
For algorithms except the XTS block cipher mode, the SM4 key size is 128 bits (16 bytes).
For the XTS block cipher mode (PSA_ALG_XTS), the SM4 key size is 256 bits (two 16-byte keys).
The SM4 block cipher is defined in GM/T 0002-2012: SM4 block cipher algorithm [CSTC0002].
IHI 0086
Page 57
1.1.2
Non-confidential
Compatible algorithms
PSA_ALG_CBC_MAC
PSA_ALG_CMAC
PSA_ALG_CTR
PSA_ALG_CFB
PSA_ALG_OFB
PSA_ALG_XTS
PSA_ALG_CBC_NO_PADDING
PSA_ALG_CBC_PKCS7
PSA_ALG_ECB_NO_PADDING
PSA_ALG_CCM
PSA_ALG_GCM
PSA_KEY_TYPE_ARC4 (macro)
Key for the ARC4 stream cipher.
#define PSA_KEY_TYPE_ARC4 ((psa_key_type_t)0x2002)
Warning: The ARC4 cipher is weak and deprecated and is only recommended for use in legacy
applications.
The ARC4 cipher supports key sizes between 40 and 2048 bits, that are multiples of 8. (5 to 256 bytes)
Use algorithm PSA_ALG_STREAM_CIPHER to use this key with the ARC4 cipher.
Compatible algorithms
PSA_ALG_STREAM_CIPHER
PSA_KEY_TYPE_CHACHA20 (macro)
Key for the ChaCha20 stream cipher or the ChaCha20-Poly1305 AEAD algorithm.
#define PSA_KEY_TYPE_CHACHA20 ((psa_key_type_t)0x2004)
The ChaCha20 key size is 256 bits (32 bytes).
∙ Use algorithm PSA_ALG_STREAM_CIPHER to use this key with the ChaCha20 cipher for unauthenticated
encryption. See PSA_ALG_STREAM_CIPHER for details of this algorithm.
∙ Use algorithm PSA_ALG_CHACHA20_POLY1305 to use this key with the ChaCha20 cipher and Poly1305
authenticator for AEAD. See PSA_ALG_CHACHA20_POLY1305 for details of this algorithm.
IHI 0086
Page 58
1.1.2
Non-confidential
Compatible algorithms
PSA_ALG_STREAM_CIPHER
PSA_ALG_CHACHA20_POLY1305
9.2.4 RSA keys
PSA_KEY_TYPE_RSA_KEY_PAIR (macro)
RSA key pair: both the private and public key.
#define PSA_KEY_TYPE_RSA_KEY_PAIR ((psa_key_type_t)0x7001)
The size of an RSA key is the bit size of the modulus.
Compatible algorithms
PSA_ALG_RSA_OAEP
PSA_ALG_RSA_PKCS1V15_CRYPT
PSA_ALG_RSA_PKCS1V15_SIGN
PSA_ALG_RSA_PKCS1V15_SIGN_RAW
PSA_ALG_RSA_PSS
PSA_ALG_RSA_PSS_ANY_SALT
PSA_KEY_TYPE_RSA_PUBLIC_KEY (macro)
RSA public key.
#define PSA_KEY_TYPE_RSA_PUBLIC_KEY ((psa_key_type_t)0x4001)
The size of an RSA key is the bit size of the modulus.
Compatible algorithms
PSA_ALG_RSA_OAEP (encryption only)
PSA_ALG_RSA_PKCS1V15_CRYPT (encryption only)
PSA_ALG_RSA_PKCS1V15_SIGN (signature verification only)
PSA_ALG_RSA_PKCS1V15_SIGN_RAW (signature verification only)
PSA_ALG_RSA_PSS (signature verification only)
PSA_ALG_RSA_PSS_ANY_SALT (signature verification only)
IHI 0086
Page 59
1.1.2
Non-confidential
PSA_KEY_TYPE_IS_RSA (macro)
Whether a key type is an RSA key. This includes both key pairs and public keys.
#define PSA_KEY_TYPE_IS_RSA(type) /* specification-defined value */
Parameters
type
A key type: a value of type psa_key_type_t.
9.2.5 Elliptic Curve keys
psa_ecc_family_t (typedef)
The type of identifiers of an elliptic curve family.
typedef uint8_t psa_ecc_family_t;
The curve identifier is required to create an ECC key using the PSA_KEY_TYPE_ECC_KEY_PAIR() or
PSA_KEY_TYPE_ECC_PUBLIC_KEY() macros.
The specific ECC curve within a family is identified by the key_bits attribute of the key.
The range of Elliptic curve family identifier values is divided as follows:
0x00 - 0x7f ECC family identifiers defined by this standard. Unallocated values in this range are
reserved for future use.
0x80 - 0xff Implementations that define additional families must use an encoding in this range.
PSA_KEY_TYPE_ECC_KEY_PAIR (macro)
Elliptic curve key pair: both the private and public key.
#define PSA_KEY_TYPE_ECC_KEY_PAIR(curve) /* specification-defined value */
Parameters
curve
A value of type psa_ecc_family_t that identifies the ECC curve family
to be used.
Description
The size of an elliptic curve key is the bit size associated with the curve, that is, the bit size of q for a curve
over a field Fq. See the documentation of each Elliptic curve family for details.
Compatible algorithms
Elliptic curve key pairs can be used in Asymmetric signature and Key agreement algorithms.
The set of compatible algorithms depends on the Elliptic curve key family. See the Elliptic curve family for
details.
IHI 0086
Page 60
1.1.2
Non-confidential
PSA_KEY_TYPE_ECC_PUBLIC_KEY (macro)
Elliptic curve public key.
#define PSA_KEY_TYPE_ECC_PUBLIC_KEY(curve) /* specification-defined value */
Parameters
curve
A value of type psa_ecc_family_t that identifies the ECC curve family
to be used.
Description
The size of an elliptic curve public key is the same as the corresponding private key. See
PSA_KEY_TYPE_ECC_KEY_PAIR() and the documentation of each Elliptic curve family for details.
Compatible algorithms
Elliptic curve public keys can be used for verification in Asymmetric signature algorithms.
The set of compatible algorithms depends on the Elliptic curve key family. See each Elliptic curve family for
details.
PSA_ECC_FAMILY_SECP_K1 (macro)
SEC Koblitz curves over prime fields.
#define PSA_ECC_FAMILY_SECP_K1 ((psa_ecc_family_t) 0x17)
This family comprises the following curves:
∙ secp192k1 : key_bits = 192
∙ secp224k1 : key_bits = 225
∙ secp256k1 : key_bits = 256
They are defined in SEC 2: Recommended Elliptic Curve Domain Parameters [SEC2].
Compatible algorithms
PSA_ALG_DETERMINISTIC_ECDSA
PSA_ALG_ECDSA
PSA_ALG_ECDSA_ANY
PSA_ALG_ECDH (key pair only)
PSA_ECC_FAMILY_SECP_R1 (macro)
SEC random curves over prime fields.
#define PSA_ECC_FAMILY_SECP_R1 ((psa_ecc_family_t) 0x12)
This family comprises the following curves:
∙ secp192r1 : key_bits = 192
IHI 0086
Page 61
1.1.2
Non-confidential
∙ secp224r1 : key_bits = 224
∙ secp256r1 : key_bits = 256
∙ secp384r1 : key_bits = 384
∙ secp521r1 : key_bits = 521
They are defined in [SEC2].
Compatible algorithms
PSA_ALG_DETERMINISTIC_ECDSA
PSA_ALG_ECDSA
PSA_ALG_ECDSA_ANY
PSA_ALG_ECDH (key pair only)
PSA_ECC_FAMILY_SECP_R2 (macro)
Warning: This family of curves is weak and deprecated.
#define PSA_ECC_FAMILY_SECP_R2 ((psa_ecc_family_t) 0x1b)
This family comprises the following curves:
∙ secp160r2 : key_bits = 160 (Deprecated)
It is defined in the superseded SEC 2: Recommended Elliptic Curve Domain Parameters, Version 1.0 [SEC2v1].
Compatible algorithms
PSA_ALG_DETERMINISTIC_ECDSA
PSA_ALG_ECDSA
PSA_ALG_ECDSA_ANY
PSA_ALG_ECDH (key pair only)
PSA_ECC_FAMILY_SECT_K1 (macro)
SEC Koblitz curves over binary fields.
#define PSA_ECC_FAMILY_SECT_K1 ((psa_ecc_family_t) 0x27)
This family comprises the following curves:
∙ sect163k1 : key_bits = 163 (Deprecated)
∙ sect233k1 : key_bits = 233
∙ sect239k1 : key_bits = 239
∙ sect283k1 : key_bits = 283
IHI 0086
Page 62
1.1.2
Non-confidential
∙ sect409k1 : key_bits = 409
∙ sect571k1 : key_bits = 571
They are defined in [SEC2].
Warning: The 163-bit curve sect163k1 is weak and deprecated and is only recommended for use in
legacy applications.
Compatible algorithms
PSA_ALG_DETERMINISTIC_ECDSA
PSA_ALG_ECDSA
PSA_ALG_ECDSA_ANY
PSA_ALG_ECDH (key pair only)
PSA_ECC_FAMILY_SECT_R1 (macro)
SEC random curves over binary fields.
#define PSA_ECC_FAMILY_SECT_R1 ((psa_ecc_family_t) 0x22)
This family comprises the following curves:
∙ sect163r1 : key_bits = 163 (Deprecated)
∙ sect233r1 : key_bits = 233
∙ sect283r1 : key_bits = 283
∙ sect409r1 : key_bits = 409
∙ sect571r1 : key_bits = 571
They are defined in [SEC2].
Warning: The 163-bit curve sect163r1 is weak and deprecated and is only recommended for use in
legacy applications.
Compatible algorithms
PSA_ALG_DETERMINISTIC_ECDSA
PSA_ALG_ECDSA
PSA_ALG_ECDSA_ANY
PSA_ALG_ECDH (key pair only)
IHI 0086
Page 63
1.1.2
Non-confidential
PSA_ECC_FAMILY_SECT_R2 (macro)
SEC additional random curves over binary fields.
#define PSA_ECC_FAMILY_SECT_R2 ((psa_ecc_family_t) 0x2b)
This family comprises the following curves:
∙ sect163r2 : key_bits = 163 (Deprecated)
It is defined in [SEC2].
Warning: The 163-bit curve sect163r2 is weak and deprecated and is only recommended for use in
legacy applications.
Compatible algorithms
PSA_ALG_DETERMINISTIC_ECDSA
PSA_ALG_ECDSA
PSA_ALG_ECDSA_ANY
PSA_ALG_ECDH (key pair only)
PSA_ECC_FAMILY_BRAINPOOL_P_R1 (macro)
Brainpool P random curves.
#define PSA_ECC_FAMILY_BRAINPOOL_P_R1 ((psa_ecc_family_t) 0x30)
This family comprises the following curves:
∙ brainpoolP160r1 : key_bits = 160 (Deprecated)
∙ brainpoolP192r1 : key_bits = 192
∙ brainpoolP224r1 : key_bits = 224
∙ brainpoolP256r1 : key_bits = 256
∙ brainpoolP320r1 : key_bits = 320
∙ brainpoolP384r1 : key_bits = 384
∙ brainpoolP512r1 : key_bits = 512
They are defined in Elliptic Curve Cryptography (ECC) Brainpool Standard Curves and Curve Generation
[RFC5639].
Warning: The 160-bit curve brainpoolP160r1 is weak and deprecated and is only recommended for
use in legacy applications.
IHI 0086
Page 64
1.1.2
Non-confidential
Compatible algorithms
PSA_ALG_DETERMINISTIC_ECDSA
PSA_ALG_ECDSA
PSA_ALG_ECDSA_ANY
PSA_ALG_ECDH (key pair only)
PSA_ECC_FAMILY_FRP (macro)
Curve used primarily in France and elsewhere in Europe.
#define PSA_ECC_FAMILY_FRP ((psa_ecc_family_t) 0x33)
This family comprises one 256-bit curve:
∙ FRP256v1 : key_bits = 256
This is defined by Publication d'un paramétrage de courbe elliptique visant des applications de passeport
électronique et de l'administration électronique française [FRP].
Compatible algorithms
PSA_ALG_DETERMINISTIC_ECDSA
PSA_ALG_ECDSA
PSA_ALG_ECDSA_ANY
PSA_ALG_ECDH (key pair only)
PSA_ECC_FAMILY_MONTGOMERY (macro)
Montgomery curves.
#define PSA_ECC_FAMILY_MONTGOMERY ((psa_ecc_family_t) 0x41)
This family comprises the following Montgomery curves:
∙ Curve25519 : key_bits = 255
∙ Curve448 : key_bits = 448
Curve25519 is defined in Curve25519: new Diffie-Hellman speed records [Curve25519]. Curve448 is
defined in Ed448-Goldilocks, a new elliptic curve [Curve448].
Compatible algorithms
PSA_ALG_ECDH (key pair only)
IHI 0086
Page 65
1.1.2
Non-confidential
PSA_ECC_FAMILY_TWISTED_EDWARDS (macro)
Twisted Edwards curves.
#define PSA_ECC_FAMILY_TWISTED_EDWARDS ((psa_ecc_family_t) 0x42)
This family comprises the following twisted Edwards curves:
∙ Edwards25519 : key_bits = 255. This curve is birationally equivalent to Curve25519.
∙ Edwards448 : key_bits = 448. This curve is birationally equivalent to Curve448.
Edwards25519 is defined in Twisted Edwards curves [Ed25519]. Edwards448 is defined in Ed448-Goldilocks,
a new elliptic curve [Curve448].
Compatible algorithms
PSA_ALG_PURE_EDDSA
PSA_ALG_ED25519PH (Edwards25519 only)
PSA_ALG_ED448PH (Edwards448 only)
PSA_KEY_TYPE_IS_ECC (macro)
Whether a key type is an elliptic curve key, either a key pair or a public key.
#define PSA_KEY_TYPE_IS_ECC(type) /* specification-defined value */
Parameters
type
A key type: a value of type psa_key_type_t.
PSA_KEY_TYPE_IS_ECC_KEY_PAIR (macro)
Whether a key type is an elliptic curve key pair.
#define PSA_KEY_TYPE_IS_ECC_KEY_PAIR(type) /* specification-defined value */
Parameters
type
A key type: a value of type psa_key_type_t.
PSA_KEY_TYPE_IS_ECC_PUBLIC_KEY (macro)
Whether a key type is an elliptic curve public key.
#define PSA_KEY_TYPE_IS_ECC_PUBLIC_KEY(type) /* specification-defined value */
IHI 0086
Page 66
1.1.2
Non-confidential
Parameters
type
A key type: a value of type psa_key_type_t.
PSA_KEY_TYPE_ECC_GET_FAMILY (macro)
Extract the curve family from an elliptic curve key type.
#define PSA_KEY_TYPE_ECC_GET_FAMILY(type) /* specification-defined value */
Parameters
type
An elliptic curve key type: a value of type psa_key_type_t such that
PSA_KEY_TYPE_IS_ECC(type) is true.
Returns: psa_ecc_family_t
The elliptic curve family id, if type is a supported elliptic curve key. Unspecified if type is not a supported
elliptic curve key.
9.2.6 Diffie Hellman keys
psa_dh_family_t (typedef)
The type of identifiers of a finite-field Diffie-Hellman group family.
typedef uint8_t psa_dh_family_t;
The group family identifier is required to create a finite-field Diffie-Hellman key using the
PSA_KEY_TYPE_DH_KEY_PAIR() or PSA_KEY_TYPE_DH_PUBLIC_KEY() macros.
The specific Diffie-Hellman group within a family is identified by the key_bits attribute of the key.
The range of Diffie-Hellman group family identifier values is divided as follows:
0x00 - 0x7f DH group family identifiers defined by this standard. Unallocated values in this range are
reserved for future use.
0x80 - 0xff Implementations that define additional families must use an encoding in this range.
PSA_KEY_TYPE_DH_KEY_PAIR (macro)
Finite-field Diffie-Hellman key pair: both the private key and public key.
#define PSA_KEY_TYPE_DH_KEY_PAIR(group) /* specification-defined value */
Parameters
group
A value of type psa_dh_family_t that identifies the Diffie-Hellman
group family to be used.
IHI 0086
Page 67
1.1.2
Non-confidential
Compatible algorithms
PSA_ALG_FFDH
PSA_KEY_TYPE_DH_PUBLIC_KEY (macro)
Finite-field Diffie-Hellman public key.
#define PSA_KEY_TYPE_DH_PUBLIC_KEY(group) /* specification-defined value */
Parameters
group
A value of type psa_dh_family_t that identifies the Diffie-Hellman
group family to be used.
Compatible algorithms
None. Finite-field Diffie-Hellman public keys are exported to use in a key agreement algorithm, and the
peer key is provided to the PSA_ALG_FFDH key agreement algorithm as a buffer of key data.
PSA_DH_FAMILY_RFC7919 (macro)
Finite-field Diffie-Hellman groups defined for TLS in RFC 7919.
#define PSA_DH_FAMILY_RFC7919 ((psa_dh_family_t) 0x03)
This family includes groups with the following key sizes (in bits): 2048, 3072, 4096, 6144, 8192. An
implementation can support all of these sizes or only a subset.
Keys is this group can only be used with the PSA_ALG_FFDH key agreement algorithm.
These groups are defined by Negotiated Finite Field Diffie-Hellman Ephemeral Parameters for Transport Layer
Security (TLS) [RFC7919] Appendix A.
PSA_KEY_TYPE_KEY_PAIR_OF_PUBLIC_KEY (macro)
The key pair type corresponding to a public key type.
#define PSA_KEY_TYPE_KEY_PAIR_OF_PUBLIC_KEY(type) \
/* specification-defined value */
Parameters
type
A public key type or key pair type.
Returns
The corresponding key pair type. If type is not a public key or a key pair, the return value is undefined.
IHI 0086
Page 68
1.1.2
Non-confidential
Description
If type is a key pair type, it will be left unchanged.
PSA_KEY_TYPE_PUBLIC_KEY_OF_KEY_PAIR (macro)
The public key type corresponding to a key pair type.
#define PSA_KEY_TYPE_PUBLIC_KEY_OF_KEY_PAIR(type) \
/* specification-defined value */
Parameters
type
A public key type or key pair type.
Returns
The corresponding public key type. If type is not a public key or a key pair, the return value is undefined.
Description
If type is a public key type, it will be left unchanged.
PSA_KEY_TYPE_IS_DH (macro)
Whether a key type is a Diffie-Hellman key, either a key pair or a public key.
#define PSA_KEY_TYPE_IS_DH(type) /* specification-defined value */
Parameters
type
A key type: a value of type psa_key_type_t.
PSA_KEY_TYPE_IS_DH_KEY_PAIR (macro)
Whether a key type is a Diffie-Hellman key pair.
#define PSA_KEY_TYPE_IS_DH_KEY_PAIR(type) /* specification-defined value */
Parameters
type
A key type: a value of type psa_key_type_t.
PSA_KEY_TYPE_IS_DH_PUBLIC_KEY (macro)
Whether a key type is a Diffie-Hellman public key.
#define PSA_KEY_TYPE_IS_DH_PUBLIC_KEY(type) /* specification-defined value */
IHI 0086
Page 69
1.1.2
Non-confidential
Parameters
type
A key type: a value of type psa_key_type_t.
PSA_KEY_TYPE_DH_GET_FAMILY (macro)
Extract the group family from a Diffie-Hellman key type.
#define PSA_KEY_TYPE_DH_GET_FAMILY(type) /* specification-defined value */
Parameters
type
A Diffie-Hellman key type: a value of type psa_key_type_t such that
PSA_KEY_TYPE_IS_DH(type) is true.
Returns: psa_dh_family_t
The Diffie-Hellman group family id, if type is a supported Diffie-Hellman key. Unspecified if type is not a
supported Diffie-Hellman key.
9.2.7 Attribute accessors
psa_set_key_type (function)
Declare the type of a key.
void psa_set_key_type(psa_key_attributes_t * attributes,
psa_key_type_t type);
Parameters
attributes
The attribute object to write to.
type
The key type to write. If this is PSA_KEY_TYPE_NONE, the key type in
attributes becomes unspecified.
Returns: void
Description
This function overwrites any key type previously set in attributes.
Implementation note
This is a simple accessor function that is not required to validate its inputs. It can be efficiently
implemented as a static inline function or a function-like-macro.
IHI 0086
Page 70
1.1.2
Non-confidential
psa_get_key_type (function)
Retrieve the key type from key attributes.
psa_key_type_t psa_get_key_type(const psa_key_attributes_t * attributes);
Parameters
attributes
The key attribute object to query.
Returns: psa_key_type_t
The key type stored in the attribute object.
Description
Implementation note
This is a simple accessor function that is not required to validate its inputs. It can be efficiently
implemented as a static inline function or a function-like-macro.
psa_get_key_bits (function)
Retrieve the key size from key attributes.
size_t psa_get_key_bits(const psa_key_attributes_t * attributes);
Parameters
attributes
The key attribute object to query.
Returns: size_t
The key size stored in the attribute object, in bits.
Description
Implementation note
This is a simple accessor function that is not required to validate its inputs. It can be efficiently
implemented as a static inline function or a function-like-macro.
psa_set_key_bits (function)
Declare the size of a key.
void psa_set_key_bits(psa_key_attributes_t * attributes,
size_t bits);
IHI 0086
Page 71
1.1.2
Non-confidential
Parameters
attributes
The attribute object to write to.
bits
The key size in bits. If this is 0, the key size in attributes becomes
unspecified. Keys of size 0 are not supported.
Returns: void
Description
This function overwrites any key size previously set in attributes.
Implementation note
This is a simple accessor function that is not required to validate its inputs. It can be efficiently
implemented as a static inline function or a function-like-macro.
9.3 Key lifetimes
The lifetime of a key indicates where it is stored and which application and system actions will create and
destroy it.
Lifetime values are composed from:
∙ A persistence level, which indicates what device management actions can cause it to be destroyed.
In particular, it indicates whether the key is volatile or persistent. See psa_key_persistence_t for more
information.
∙ A location indicator, which indicates where the key is stored and where operations on the key are
performed. See psa_key_location_t for more information.
There are two main types of lifetime, indicated by the persistence level: volatile and persistent.
9.3.1 Volatile keys
Volatile keys are automatically destroyed when the application instance terminates or on a power reset of
the device. Volatile keys can be explicitly destroyed by the application.
Conceptually, a volatile key is stored in RAM. Volatile keys have the lifetime PSA_KEY_LIFETIME_VOLATILE.
To create a volatile key:
1. Populate a psa_key_attributes_t object with the required type, size, policy and other key attributes.
2. Create the key with one of the key creation functions. If successful, these functions output a
transient key identifier.
To destroy a volatile key: call psa_destroy_key() with the key identifier. There must be a matching call to
psa_destroy_key() for each successful call to a create a volatile key.
IHI 0086
Page 72
1.1.2
Non-confidential
9.3.2 Persistent keys
Persistent keys are preserved until the application explicitly destroys them or until an
implementation-specific device management event occurs, for example, a factory reset.
Each persistent key has a permanent key identifier, which acts as a name for the key. Within an
application, the key identifier corresponds to a single key. The application specifies the key identifier when
the key is created and when using the key.
The lifetime attribute of a persistent key indicates how and where it is stored. The default lifetime value
for a persistent key is PSA_KEY_LIFETIME_PERSISTENT, which corresponds to a default storage area. This
specification defines how implementations can provide other lifetime values corresponding to different
storage areas with different retention policies, or to secure elements with different security characteristics.
To create a persistent key:
1. Populate a psa_key_attributes_t object with the key’s type, size, policy and other attributes.
2. In the attributes object, set the desired lifetime and persistent identifier for the key.
3. Create the key with one of the key creation functions. If successful, these functions output the key
identifier that was specified by the application in step 2.
To access an existing persistent key: use the key identifier in any API that requires a key.
To destroy a persistent key: call psa_destroy_key() with the key identifier. Destroying a persistent key
permanently removes it from memory and storage.
By default, persistent key material is removed from volatile memory when not in use. Frequently used
persistent keys can benefit from caching, depending on the implementation and the application. Caching
can be enabled by creating the key with the PSA_KEY_USAGE_CACHE policy. Cached keys can be removed from
volatile memory by calling psa_purge_key(). See also Memory cleanup on page 39 and Managing key material
on page 39.
9.3.3 Lifetime encodings
psa_key_lifetime_t (typedef)
Encoding of key lifetimes.
typedef uint32_t psa_key_lifetime_t;
The lifetime of a key indicates where it is stored and which application and system actions will create and
destroy it.
Lifetime values have the following structure:
Bits[7:0]: Persistence level
This value indicates what device management actions can cause it to be destroyed. In
particular, it indicates whether the key is volatile or persistent. See psa_key_persistence_t for
more information.
PSA_KEY_LIFETIME_GET_PERSISTENCE(lifetime) returns the persistence level for a key lifetime
value.
IHI 0086
Page 73
1.1.2
Non-confidential
Bits[31:8]: Location indicator
This value indicates where the key material is stored (or at least where it is accessible in
cleartext) and where operations on the key are performed. See psa_key_location_t for more
information.
PSA_KEY_LIFETIME_GET_LOCATION(lifetime) returns the location indicator for a key lifetime
value.
Volatile keys are automatically destroyed when the application instance terminates or on a power reset of
the device. Persistent keys are preserved until the application explicitly destroys them or until an
implementation-specific device management event occurs, for example, a factory reset.
Persistent keys have a key identifier of type psa_key_id_t. This identifier remains valid throughout the
lifetime of the key, even if the application instance that created the key terminates.
This specification defines two basic lifetime values:
∙ Keys with the lifetime PSA_KEY_LIFETIME_VOLATILE are volatile. All implementations should support
this lifetime.
∙ Keys with the lifetime PSA_KEY_LIFETIME_PERSISTENT are persistent. All implementations that have
access to persistent storage with appropriate security guarantees should support this lifetime.
psa_key_persistence_t (typedef)
Encoding of key persistence levels.
typedef uint8_t psa_key_persistence_t;
What distinguishes different persistence levels is which device management events can cause keys to be
destroyed. For example, power reset, transfer of device ownership, or a factory reset are device
management events that can affect keys at different persistence levels. The specific management events
which affect persistent keys at different levels is outside the scope of the Crypto API.
Values for persistence levels defined by Crypto API are shown in Table 6.
Table 6 Key persistence level values
Persistence level
Definition
0 = PSA_KEY_PERSISTENCE_VOLATILE
Volatile key.
A volatile key is automatically destroyed by the
implementation when the application instance terminates. In
particular, a volatile key is automatically destroyed on a
power reset of the device.
1 = PSA_KEY_PERSISTENCE_DEFAULT
Persistent key with a default lifetime.
Implementations should support this value if they support
persistent keys at all. Applications should use this value if
they have no specific needs that are only met by
implementation-specific features.
continues on next page
IHI 0086
Page 74
1.1.2
Non-confidential
Table 6 - continued from previous page
Persistence level
Definition
2 - 127
Persistent key with a PSA Certified API-specified lifetime.
The Crypto API does not define the meaning of these values,
but another PSA Certified API may do so.
128 - 254
Persistent key with a vendor-specified lifetime.
No PSA Certified API will define the meaning of these values,
so implementations may choose the meaning freely. As a
guideline, higher persistence levels should cause a key to
survive more management events than lower levels.
255 = PSA_KEY_PERSISTENCE_READ_ONLY
Read-only or write-once key.
A key with this persistence level cannot be destroyed.
Implementations that support such keys may either allow
their creation through the Crypto API, preferably only to
applications with the appropriate privilege, or only expose
keys created through implementation-specific means such as
a factory ROM engraving process.
Note that keys that are read-only due to policy restrictions
rather than due to physical limitations should not have this
persistence level.
Note:
Key persistence levels are 8-bit values. Key management interfaces operate on lifetimes (type
psa_key_lifetime_t), and encode the persistence value as the lower 8 bits of a 32-bit value.
psa_key_location_t (typedef)
Encoding of key location indicators.
typedef uint32_t psa_key_location_t;
If an implementation of the Crypto API can make calls to external cryptoprocessors such as secure
elements, the location of a key indicates which secure element performs the operations on the key. If the
key material is not stored persistently inside the secure element, it must be stored in a wrapped form such
that only the secure element can access the key material in cleartext.
Values for location indicators defined by this specification are shown in Table 7 on page 76.
IHI 0086
Page 75
1.1.2
Non-confidential
Table 7 Key location indicator values
Location indicator
Definition
0
Primary local storage.
All implementations should support this value. The primary local storage is
typically the same storage area that contains the key metadata.
1
Primary secure element.
Implementations should support this value if there is a secure element
attached to the operating environment. As a guideline, secure elements may
provide higher resistance against side channel and physical attacks than the
primary local storage, but may have restrictions on supported key types, sizes,
policies and operations and may have different performance characteristics.
2 - 0x7fffff
Other locations defined by a PSA specification.
The Crypto API does not currently assign any meaning to these locations, but
future versions of this specification or other PSA Certified APIs may do so.
0x800000 - 0xffffff
Vendor-defined locations.
No PSA Certified API will assign a meaning to locations in this range.
Note:
Key location indicators are 24-bit values. Key management interfaces operate on lifetimes (type
psa_key_lifetime_t), and encode the location as the upper 24 bits of a 32-bit value.
9.3.4 Lifetime values
PSA_KEY_LIFETIME_VOLATILE (macro)
The default lifetime for volatile keys.
#define PSA_KEY_LIFETIME_VOLATILE ((psa_key_lifetime_t) 0x00000000)
A volatile key only exists as long as its identifier is not destroyed. The key material is guaranteed to be
erased on a power reset.
A key with this lifetime is typically stored in the RAM area of the Crypto API implementation. However
this is an implementation choice. If an implementation stores data about the key in a non-volatile memory,
it must release all the resources associated with the key and erase the key material if the calling application
terminates.
IHI 0086
Page 76
1.1.2
Non-confidential
PSA_KEY_LIFETIME_PERSISTENT (macro)
The default lifetime for persistent keys.
#define PSA_KEY_LIFETIME_PERSISTENT ((psa_key_lifetime_t) 0x00000001)
A persistent key remains in storage until it is explicitly destroyed or until the corresponding storage area is
wiped. This specification does not define any mechanism to wipe a storage area. Implementations are
permitted to provide their own mechanism, for example, to perform a factory reset, to prepare for device
refurbishment, or to uninstall an application.
This lifetime value is the default storage area for the calling application. Implementations can offer other
storage areas designated by other lifetime values as implementation-specific extensions.
PSA_KEY_PERSISTENCE_VOLATILE (macro)
The persistence level of volatile keys.
#define PSA_KEY_PERSISTENCE_VOLATILE ((psa_key_persistence_t) 0x00)
See psa_key_persistence_t for more information.
PSA_KEY_PERSISTENCE_DEFAULT (macro)
The default persistence level for persistent keys.
#define PSA_KEY_PERSISTENCE_DEFAULT ((psa_key_persistence_t) 0x01)
See psa_key_persistence_t for more information.
PSA_KEY_PERSISTENCE_READ_ONLY (macro)
A persistence level indicating that a key is never destroyed.
#define PSA_KEY_PERSISTENCE_READ_ONLY ((psa_key_persistence_t) 0xff)
See psa_key_persistence_t for more information.
PSA_KEY_LOCATION_LOCAL_STORAGE (macro)
The local storage area for persistent keys.
#define PSA_KEY_LOCATION_LOCAL_STORAGE ((psa_key_location_t) 0x000000)
This storage area is available on all systems that can store persistent keys without delegating the storage
to a third-party cryptoprocessor.
See psa_key_location_t for more information.
IHI 0086
Page 77
1.1.2
Non-confidential
PSA_KEY_LOCATION_PRIMARY_SECURE_ELEMENT (macro)
The default secure element storage area for persistent keys.
#define PSA_KEY_LOCATION_PRIMARY_SECURE_ELEMENT ((psa_key_location_t) 0x000001)
This storage location is available on systems that have one or more secure elements that are able to store
keys.
Vendor-defined locations must be provided by the system for storing keys in additional secure elements.
See psa_key_location_t for more information.
9.3.5 Attribute accessors
psa_set_key_lifetime (function)
Set the location of a persistent key.
void psa_set_key_lifetime(psa_key_attributes_t * attributes,
psa_key_lifetime_t lifetime);
Parameters
attributes
The attribute object to write to.
lifetime
The lifetime for the key. If this is PSA_KEY_LIFETIME_VOLATILE, the key
will be volatile, and the key identifier attribute is reset to
PSA_KEY_ID_NULL.
Returns: void
Description
To make a key persistent, give it a persistent key identifier by using psa_set_key_id(). By default, a key that
has a persistent identifier is stored in the default storage area identifier by PSA_KEY_LIFETIME_PERSISTENT.
Call this function to choose a storage area, or to explicitly declare the key as volatile.
This function does not access storage, it merely stores the given value in the attribute object. The
persistent key will be written to storage when the attribute object is passed to a key creation function
such as psa_import_key(), psa_generate_key(), psa_key_derivation_output_key() or psa_copy_key().
Implementation note
This is a simple accessor function that is not required to validate its inputs. It can be efficiently
implemented as a static inline function or a function-like-macro.
IHI 0086
Page 78
1.1.2
Non-confidential
psa_get_key_lifetime (function)
Retrieve the lifetime from key attributes.
psa_key_lifetime_t psa_get_key_lifetime(const psa_key_attributes_t * attributes);
Parameters
attributes
The key attribute object to query.
Returns: psa_key_lifetime_t
The lifetime value stored in the attribute object.
Description
Implementation note
This is a simple accessor function that is not required to validate its inputs. It can be efficiently
implemented as a static inline function or a function-like-macro.
9.3.6 Support macros
PSA_KEY_LIFETIME_GET_PERSISTENCE (macro)
Extract the persistence level from a key lifetime.
#define PSA_KEY_LIFETIME_GET_PERSISTENCE(lifetime) \
((psa_key_persistence_t) ((lifetime) & 0x000000ff))
Parameters
lifetime
The lifetime value to query: a value of type psa_key_lifetime_t.
PSA_KEY_LIFETIME_GET_LOCATION (macro)
Extract the location indicator from a key lifetime.
#define PSA_KEY_LIFETIME_GET_LOCATION(lifetime) \
((psa_key_location_t) ((lifetime) >> 8))
Parameters
lifetime
The lifetime value to query: a value of type psa_key_lifetime_t.
IHI 0086
Page 79
1.1.2
Non-confidential
PSA_KEY_LIFETIME_IS_VOLATILE (macro)
Whether a key lifetime indicates that the key is volatile.
#define PSA_KEY_LIFETIME_IS_VOLATILE(lifetime) \
(PSA_KEY_LIFETIME_GET_PERSISTENCE(lifetime) == PSA_KEY_PERSISTENCE_VOLATILE)
Parameters
lifetime
The lifetime value to query: a value of type psa_key_lifetime_t.
Returns
1 if the key is volatile, otherwise 0.
Description
A volatile key is automatically destroyed by the implementation when the application instance terminates.
In particular, a volatile key is automatically destroyed on a power reset of the device.
A key that is not volatile is persistent. Persistent keys are preserved until the application explicitly destroys
them or until an implementation-specific device management event occurs, for example, a factory reset.
PSA_KEY_LIFETIME_FROM_PERSISTENCE_AND_LOCATION (macro)
Construct a lifetime from a persistence level and a location.
#define PSA_KEY_LIFETIME_FROM_PERSISTENCE_AND_LOCATION(persistence, location) \
((location) << 8 | (persistence))
Parameters
persistence
The persistence level: a value of type psa_key_persistence_t.
location
The location indicator: a value of type psa_key_location_t.
Returns
The constructed lifetime value.
9.4 Key identifiers
Key identifiers are integral values that act as permanent names for persistent keys, or as transient
references to volatile keys. Key identifiers use the psa_key_id_t type, and the range of identifier values is
divided as follows:
PSA_KEY_ID_NULL = 0
Reserved as an invalid key identifier.
PSA_KEY_ID_USER_MIN - PSA_KEY_ID_USER_MAX
Applications can freely choose persistent key identifiers in this range.
PSA_KEY_ID_VENDOR_MIN - PSA_KEY_ID_VENDOR_MAX
Implementations can define additional persistent key identifiers in this range, and must
allocate any volatile key identifiers from this range.
IHI 0086
Page 80
1.1.2
Non-confidential
Key identifiers outside these ranges are reserved for future use.
Key identifiers are output from a successful call to one of the key creation functions. For persistent keys,
this is the same identifier as the one specified in the key attributes used to create the key. The key
identifier remains valid until it is invalidated by passing it to psa_destroy_key(). A volatile key identifier
must not be used after it has been invalidated.
If an invalid key identifier is provided as a parameter in any function, the function will return
PSA_ERROR_INVALID_HANDLE; except for the special case of calling psa_destroy_key(PSA_KEY_ID_NULL), which
has no effect and always returns PSA_SUCCESS.
Valid key identifiers must have distinct values within the same application. If the implementation provides
caller isolation, then key identifiers are local to each application. That is, the same key identifier in two
applications corresponds to two different keys.
9.4.1 Key identifier type
psa_key_id_t (typedef)
Key identifier.
typedef uint32_t psa_key_id_t;
A key identifier can be a permanent name for a persistent key, or a transient reference to volatile key. See
Key identifiers on page 80.
PSA_KEY_ID_NULL (macro)
The null key identifier.
#define PSA_KEY_ID_NULL ((psa_key_id_t)0)
The null key identifier is always invalid, except when used without in a call to psa_destroy_key() which will
return PSA_SUCCESS.
PSA_KEY_ID_USER_MIN (macro)
The minimum value for a key identifier chosen by the application.
#define PSA_KEY_ID_USER_MIN ((psa_key_id_t)0x00000001)
PSA_KEY_ID_USER_MAX (macro)
The maximum value for a key identifier chosen by the application.
#define PSA_KEY_ID_USER_MAX ((psa_key_id_t)0x3fffffff)
IHI 0086
Page 81
1.1.2
Non-confidential
PSA_KEY_ID_VENDOR_MIN (macro)
The minimum value for a key identifier chosen by the implementation.
#define PSA_KEY_ID_VENDOR_MIN ((psa_key_id_t)0x40000000)
PSA_KEY_ID_VENDOR_MAX (macro)
The maximum value for a key identifier chosen by the implementation.
#define PSA_KEY_ID_VENDOR_MAX ((psa_key_id_t)0x7fffffff)
9.4.2 Attribute accessors
psa_set_key_id (function)
Declare a key as persistent and set its key identifier.
void psa_set_key_id(psa_key_attributes_t * attributes,
psa_key_id_t id);
Parameters
attributes
The attribute object to write to.
id
The persistent identifier for the key.
Returns: void
Description
The application must choose a value for id between PSA_KEY_ID_USER_MIN and PSA_KEY_ID_USER_MAX.
If the attribute object currently declares the key as volatile, which is the default lifetime of an attribute
object, this function sets the lifetime attribute to PSA_KEY_LIFETIME_PERSISTENT.
This function does not access storage, it merely stores the given value in the attribute object. The
persistent key will be written to storage when the attribute object is passed to a key creation function
such as psa_import_key(), psa_generate_key(), psa_key_derivation_output_key() or psa_copy_key().
Implementation note
This is a simple accessor function that is not required to validate its inputs. It can be efficiently
implemented as a static inline function or a function-like-macro.
IHI 0086
Page 82
1.1.2
Non-confidential
psa_get_key_id (function)
Retrieve the key identifier from key attributes.
psa_key_id_t psa_get_key_id(const psa_key_attributes_t * attributes);
Parameters
attributes
The key attribute object to query.
Returns: psa_key_id_t
The persistent identifier stored in the attribute object. This value is unspecified if the attribute object
declares the key as volatile.
Description
Implementation note
This is a simple accessor function that is not required to validate its inputs. It can be efficiently
implemented as a static inline function or a function-like-macro.
9.5 Key policies
All keys have an associated policy that regulates which operations are permitted on the key. A key policy is
composed of two elements:
∙ A set of usage flags. See Key usage flags on page 85.
∙ A specific algorithm that is permitted with the key. See Permitted algorithms.
The policy is part of the key attributes that are managed by a psa_key_attributes_t object.
A highly constrained implementation might not be able to support all the policies that can be expressed
through this interface. If an implementation cannot create a key with the required policy, it must return an
appropriate error code when the key is created.
9.5.1 Permitted algorithms
The permitted algorithm is encoded using a algorithm identifier, as described in Algorithms on page 107.
This specification only defines policies that restrict keys to a single algorithm, which is consistent with
both common practice and security good practice.
The following algorithm policies are supported:
∙ PSA_ALG_NONE does not permit any cryptographic operation with the key. The key can still be used for
non-cryptographic actions such as exporting, if permitted by the usage flags.
∙ A specific algorithm value permits exactly that particular algorithm.
∙ A signature algorithm constructed with PSA_ALG_ANY_HASH permits the specified signature scheme
with any hash algorithm. In addition, PSA_ALG_RSA_PKCS1V15_SIGN(PSA_ALG_ANY_HASH) also permits the
PSA_ALG_RSA_PKCS1V15_SIGN_RAW signature algorithm.
IHI 0086
Page 83
1.1.2
Non-confidential
∙ A raw key agreement algorithm also permits the specified key agreement scheme to be combined
with any key derivation algorithm.
∙ An algorithm built from PSA_ALG_AT_LEAST_THIS_LENGTH_MAC() permits any MAC algorithm from the
same base class (for example, CMAC) which computes or verifies a MAC length greater than or equal
to the length encoded in the wildcard algorithm.
∙ An algorithm built from PSA_ALG_AEAD_WITH_AT_LEAST_THIS_LENGTH_TAG() permits any AEAD algorithm
from the same base class (for example, CCM) which computes or verifies a tag length greater than or
equal to the length encoded in the wildcard algorithm.
When a key is used in a cryptographic operation, the application must supply the algorithm to use for the
operation. This algorithm is checked against the key’s permitted-algorithm policy.
psa_set_key_algorithm (function)
Declare the permitted-algorithm policy for a key.
void psa_set_key_algorithm(psa_key_attributes_t * attributes,
psa_algorithm_t alg);
Parameters
attributes
The attribute object to write to.
alg
The permitted algorithm to write.
Returns: void
Description
The permitted-algorithm policy of a key encodes which algorithm or algorithms are permitted to be used
with this key.
This function overwrites any permitted-algorithm policy previously set in attributes.
Implementation note
This is a simple accessor function that is not required to validate its inputs. It can be efficiently
implemented as a static inline function or a function-like-macro.
psa_get_key_algorithm (function)
Retrieve the permitted-algorithm policy from key attributes.
psa_algorithm_t psa_get_key_algorithm(const psa_key_attributes_t * attributes);
IHI 0086
Page 84
1.1.2
Non-confidential
Parameters
attributes
The key attribute object to query.
Returns: psa_algorithm_t
The algorithm stored in the attribute object.
Description
Implementation note
This is a simple accessor function that is not required to validate its inputs. It can be efficiently
implemented as a static inline function or a function-like-macro.
9.5.2 Key usage flags
The usage flags are encoded in a bitmask, which has the type psa_key_usage_t. Four kinds of usage flag can
be specified:
∙ The extractable flag PSA_KEY_USAGE_EXPORT determines whether the key material can be extracted
from the cryptoprocessor, or copied outside of its current security boundary.
∙ The copyable flag PSA_KEY_USAGE_COPY determines whether the key material can be copied into a new
key, which can have a different lifetime or a more restrictive policy.
∙ The cacheable flag PSA_KEY_USAGE_CACHE determines whether the implementation is permitted to
retain non-essential copies of the key material in RAM. This policy only applies to persistent keys.
See also Managing key material on page 39.
∙ The other usage flags, for example, PSA_KEY_USAGE_ENCRYPT and PSA_KEY_USAGE_SIGN_MESSAGE, determine
whether the corresponding operation is permitted on the key.
psa_key_usage_t (typedef)
Encoding of permitted usage on a key.
typedef uint32_t psa_key_usage_t;
PSA_KEY_USAGE_EXPORT (macro)
Permission to export the key.
#define PSA_KEY_USAGE_EXPORT ((psa_key_usage_t)0x00000001)
This flag permits a key to be moved outside of the security boundary of its current storage location. In
particular:
∙ This flag is required to export a key from the cryptoprocessor using psa_export_key(). A public key or
the public part of a key pair can always be exported regardless of the value of this permission flag.
∙ This flag can also be required to make a copy of a key outside of a secure element using
psa_copy_key(). See also PSA_KEY_USAGE_COPY.
IHI 0086
Page 85
1.1.2
Non-confidential
If a key does not have export permission, implementations must not permit the key to be exported in plain
form from the cryptoprocessor, whether through psa_export_key() or through a proprietary interface. The
key might still be exportable in a wrapped form, i.e. in a form where it is encrypted by another key.
PSA_KEY_USAGE_COPY (macro)
Permission to copy the key.
#define PSA_KEY_USAGE_COPY ((psa_key_usage_t)0x00000002)
This flag is required to make a copy of a key using psa_copy_key().
For a key lifetime that corresponds to a secure element location that enforces the non-exportability of
keys, copying a key outside the secure element also requires the usage flag PSA_KEY_USAGE_EXPORT. Copying
the key within the secure element is permitted with just PSA_KEY_USAGE_COPY, if the secure element
supports it. For keys with the lifetime PSA_KEY_LIFETIME_VOLATILE or PSA_KEY_LIFETIME_PERSISTENT, the usage
flag PSA_KEY_USAGE_COPY is sufficient to permit the copy.
PSA_KEY_USAGE_CACHE (macro)
Permission for the implementation to cache the key.
#define PSA_KEY_USAGE_CACHE ((psa_key_usage_t)0x00000004)
This flag permits the implementation to make additional copies of the key material that are not in storage
and not for the purpose of an ongoing operation. Applications can use it as a hint for the cryptoprocessor,
to keep a copy of the key around for repeated access.
An application can request that cached key material is removed from memory by calling psa_purge_key().
The presence of this usage flag when creating a key is a hint:
∙ An implementation is not required to cache keys that have this usage flag.
∙ An implementation must not report an error if it does not cache keys.
If this usage flag is not present, the implementation must ensure key material is removed from memory as
soon as it is not required for an operation, or for maintenance of a volatile key.
This flag must be preserved when reading back the attributes for all keys, regardless of key type or
implementation behavior.
See also Managing key material on page 39.
PSA_KEY_USAGE_ENCRYPT (macro)
Permission to encrypt a message with the key.
#define PSA_KEY_USAGE_ENCRYPT ((psa_key_usage_t)0x00000100)
This flag is required to use the key in a symmetric encryption operation, in an AEAD
encryption-and-authentication operation, or in an asymmetric encryption operation. The flag must be
present on keys used with the following APIs:
IHI 0086
Page 86
1.1.2
Non-confidential
∙ psa_cipher_encrypt()
∙ psa_cipher_encrypt_setup()
∙ psa_aead_encrypt()
∙ psa_aead_encrypt_setup()
∙ psa_asymmetric_encrypt()
For a key pair, this concerns the public key.
PSA_KEY_USAGE_DECRYPT (macro)
Permission to decrypt a message with the key.
#define PSA_KEY_USAGE_DECRYPT ((psa_key_usage_t)0x00000200)
This flag is required to use the key in a symmetric decryption operation, in an AEAD
decryption-and-verification operation, or in an asymmetric decryption operation. The flag must be present
on keys used with the following APIs:
∙ psa_cipher_decrypt()
∙ psa_cipher_decrypt_setup()
∙ psa_aead_decrypt()
∙ psa_aead_decrypt_setup()
∙ psa_asymmetric_decrypt()
For a key pair, this concerns the private key.
PSA_KEY_USAGE_SIGN_MESSAGE (macro)
Permission to sign a message with the key.
#define PSA_KEY_USAGE_SIGN_MESSAGE ((psa_key_usage_t)0x00000400)
This flag is required to use the key in a MAC calculation operation, or in an asymmetric message signature
operation. The flag must be present on keys used with the following APIs:
∙ psa_mac_compute()
∙ psa_mac_sign_setup()
∙ psa_sign_message()
For a key pair, this concerns the private key.
IHI 0086
Page 87
1.1.2
Non-confidential
PSA_KEY_USAGE_VERIFY_MESSAGE (macro)
Permission to verify a message signature with the key.
#define PSA_KEY_USAGE_VERIFY_MESSAGE ((psa_key_usage_t)0x00000800)
This flag is required to use the key in a MAC verification operation, or in an asymmetric message signature
verification operation. The flag must be present on keys used with the following APIs:
∙ psa_mac_verify()
∙ psa_mac_verify_setup()
∙ psa_verify_message()
For a key pair, this concerns the public key.
PSA_KEY_USAGE_SIGN_HASH (macro)
Permission to sign a message hash with the key.
#define PSA_KEY_USAGE_SIGN_HASH ((psa_key_usage_t)0x00001000)
This flag is required to use the key to sign a message hash in an asymmetric signature operation. The flag
must be present on keys used when calling psa_sign_hash().
This flag automatically sets PSA_KEY_USAGE_SIGN_MESSAGE: if an application sets the flag
PSA_KEY_USAGE_SIGN_HASH when creating a key, then the key always has the permissions conveyed by
PSA_KEY_USAGE_SIGN_MESSAGE, and the flag PSA_KEY_USAGE_SIGN_MESSAGE will also be present when the
application queries the usage flags of the key.
For a key pair, this concerns the private key.
PSA_KEY_USAGE_VERIFY_HASH (macro)
Permission to verify a message hash with the key.
#define PSA_KEY_USAGE_VERIFY_HASH ((psa_key_usage_t)0x00002000)
This flag is required to use the key to verify a message hash in an asymmetric signature verification
operation. The flag must be present on keys used when calling psa_verify_hash().
This flag automatically sets PSA_KEY_USAGE_VERIFY_MESSAGE: if an application sets the flag
PSA_KEY_USAGE_VERIFY_HASH when creating a key, then the key always has the permissions conveyed by
PSA_KEY_USAGE_VERIFY_MESSAGE, and the flag PSA_KEY_USAGE_VERIFY_MESSAGE will also be present when the
application queries the usage flags of the key.
For a key pair, this concerns the public key.
IHI 0086
Page 88
1.1.2
Non-confidential
PSA_KEY_USAGE_DERIVE (macro)
Permission to derive other keys or produce a password hash from this key.
#define PSA_KEY_USAGE_DERIVE ((psa_key_usage_t)0x00004000)
This flag is required to use the key for derivation in a key derivation operation, or in a key agreement
operation.
This flag must be present on keys used with the following APIs:
∙ psa_key_derivation_key_agreement()
∙ psa_raw_key_agreement()
If this flag is present on all keys used in calls to psa_key_derivation_input_key() for a key derivation
operation, then it permits calling psa_key_derivation_output_bytes() or psa_key_derivation_output_key() at
the end of the operation.
PSA_KEY_USAGE_VERIFY_DERIVATION (macro)
Permission to verify the result of a key derivation, including password hashing.
#define PSA_KEY_USAGE_VERIFY_DERIVATION ((psa_key_usage_t)0x00008000)
This flag is required to use the key for verification in a key derivation operation.
This flag must be present on keys used with psa_key_derivation_verify_key().
If this flag is present on all keys used in calls to psa_key_derivation_input_key() for a key derivation
operation, then it permits calling psa_key_derivation_verify_bytes() or psa_key_derivation_verify_key() at
the end of the operation.
psa_set_key_usage_flags (function)
Declare usage flags for a key.
void psa_set_key_usage_flags(psa_key_attributes_t * attributes,
psa_key_usage_t usage_flags);
Parameters
attributes
The attribute object to write to.
usage_flags
The usage flags to write.
Returns: void
Description
Usage flags are part of a key’s policy. They encode what kind of operations are permitted on the key. For
more details, see Key policies on page 83.
This function overwrites any usage flags previously set in attributes.
IHI 0086
Page 89
1.1.2
Non-confidential
Implementation note
This is a simple accessor function that is not required to validate its inputs. It can be efficiently
implemented as a static inline function or a function-like-macro.
psa_get_key_usage_flags (function)
Retrieve the usage flags from key attributes.
psa_key_usage_t psa_get_key_usage_flags(const psa_key_attributes_t * attributes);
Parameters
attributes
The key attribute object to query.
Returns: psa_key_usage_t
The usage flags stored in the attribute object.
Description
Implementation note
This is a simple accessor function that is not required to validate its inputs. It can be efficiently
implemented as a static inline function or a function-like-macro.
9.6 Key management functions
9.6.1 Key creation
New keys can be created in the following ways:
∙ psa_import_key() creates a key from a data buffer provided by the application.
∙ psa_generate_key() creates a key from randomly generated data.
∙ psa_key_derivation_output_key() creates a key from data generated by a pseudorandom derivation
process. See Key derivation on page 205.
∙ psa_copy_key() duplicates an existing key with a different lifetime or with a more restrictive usage
policy.
When creating a key, the attributes for the new key are specified in a psa_key_attributes_t object. Each
key creation function defines how it uses the attributes.
Note:
The attributes for a key are immutable after the key has been created.
The application must set the key algorithm policy and the appropriate key usage flags in the
attributes in order for the key to be used in any cryptographic operations.
IHI 0086
Page 90
1.1.2
Non-confidential
psa_import_key (function)
Import a key in binary format.
psa_status_t psa_import_key(const psa_key_attributes_t * attributes,
const uint8_t * data,
size_t data_length,
psa_key_id_t * key);
Parameters
attributes
The attributes for the new key. This function uses the attributes as
follows:
∙ The key type is required, and determines how the data buffer is
interpreted.
∙ The key size is always determined from the data buffer. If the
key size in attributes is nonzero, it must be equal to the size
determined from data.
∙ The key permitted-algorithm policy is required for keys that will
be used for a cryptographic operation, see Permitted algorithms
on page 83.
∙ The key usage flags define what operations are permitted with
the key, see Key usage flags on page 85.
∙ The key lifetime and identifier are required for a persistent key.
Note:
This is an input parameter: it is not updated with the final key
attributes. The final attributes of the new key can be queried
by calling psa_get_key_attributes() with the key’s identifier.
data
Buffer containing the key data. The content of this buffer is
interpreted according to the type declared in attributes. All
implementations must support at least the format described in Key
formats on page 103 for the chosen type. Implementations can
support other formats, but be conservative in interpreting the key
data: it is recommended that implementations reject content if it
might be erroneous, for example, if it is the wrong type or is
truncated.
data_length
Size of the data buffer in bytes.
key
On success, an identifier for the newly created key. PSA_KEY_ID_NULL
on failure.
IHI 0086
Page 91
1.1.2
Non-confidential
Returns: psa_status_t
PSA_SUCCESS
Success. If the key is persistent, the key material and the key’s
metadata have been saved to persistent storage.
PSA_ERROR_BAD_STATE
The library requires initializing by a call to psa_crypto_init().
PSA_ERROR_NOT_PERMITTED
The implementation does not permit creating a key with the
specified attributes due to some implementation-specific policy.
PSA_ERROR_ALREADY_EXISTS
This is an attempt to create a persistent key, and there is already a
persistent key with the given identifier.
PSA_ERROR_INVALID_ARGUMENT
The following conditions can result in this error:
∙ The key type is invalid.
∙ The key size is nonzero, and is incompatible with the key data in
data.
∙ The key lifetime is invalid.
∙ The key identifier is not valid for the key lifetime.
∙ The key usage flags include invalid values.
∙ The key’s permitted-usage algorithm is invalid.
∙ The key attributes, as a whole, are invalid.
∙ The key data is not correctly formatted for the key type.
PSA_ERROR_NOT_SUPPORTED
The key attributes, as a whole, are not supported, either by the
implementation in general or in the specified storage location.
PSA_ERROR_INSUFFICIENT_MEMORY
PSA_ERROR_INSUFFICIENT_STORAGE
PSA_ERROR_COMMUNICATION_FAILURE
PSA_ERROR_CORRUPTION_DETECTED
PSA_ERROR_STORAGE_FAILURE
PSA_ERROR_DATA_CORRUPT
PSA_ERROR_DATA_INVALID
Description
This function supports any output from psa_export_key(). Refer to Key formats on page 103 for the format
of keys.
The key data determines the key size. The attributes can optionally specify a key size; in this case it must
match the size determined from the key data. A key size of 0 in attributes indicates that the key size is
solely determined by the key data.
Implementations must reject an attempt to import a key of size 0.
This specification defines a single format for each key type. Implementations can optionally support other
formats in addition to the standard format. It is recommended that implementations that support other
formats ensure that the formats are clearly unambiguous, to minimize the risk that an invalid input is
accidentally interpreted according to a different format.
Note:
IHI 0086
Page 92
1.1.2
Non-confidential
The Crypto API does not support asymmetric private key objects outside of a key pair. To import a
private key, the attributes must specify the corresponding key pair type. Depending on the key
type, either the import format contains the public key data or the implementation will reconstruct
the public key from the private key as needed.
psa_generate_key (function)
Generate a key or key pair.
psa_status_t psa_generate_key(const psa_key_attributes_t * attributes,
psa_key_id_t * key);
Parameters
attributes
The attributes for the new key. This function uses the attributes as
follows:
∙ The key type is required. It cannot be an asymmetric public key.
∙ The key size is required. It must be a valid size for the key type.
∙ The key permitted-algorithm policy is required for keys that will
be used for a cryptographic operation, see Permitted algorithms
on page 83.
∙ The key usage flags define what operations are permitted with
the key, see Key usage flags on page 85.
∙ The key lifetime and identifier are required for a persistent key.
Note:
This is an input parameter: it is not updated with the final key
attributes. The final attributes of the new key can be queried
by calling psa_get_key_attributes() with the key’s identifier.
key
On success, an identifier for the newly created key. PSA_KEY_ID_NULL
on failure.
Returns: psa_status_t
PSA_SUCCESS
Success. If the key is persistent, the key material and the key’s
metadata have been saved to persistent storage.
PSA_ERROR_BAD_STATE
The library requires initializing by a call to psa_crypto_init().
PSA_ERROR_NOT_PERMITTED
The implementation does not permit creating a key with the
specified attributes due to some implementation-specific policy.
PSA_ERROR_ALREADY_EXISTS
This is an attempt to create a persistent key, and there is already a
persistent key with the given identifier.
PSA_ERROR_INVALID_ARGUMENT
The following conditions can result in this error:
∙ The key type is invalid, or is an asymmetric public key type.
∙ The key size is not valid for the key type.
IHI 0086
Page 93
1.1.2
Non-confidential
∙ The key lifetime is invalid.
∙ The key identifier is not valid for the key lifetime.
∙ The key usage flags include invalid values.
∙ The key’s permitted-usage algorithm is invalid.
∙ The key attributes, as a whole, are invalid.
PSA_ERROR_NOT_SUPPORTED
The key attributes, as a whole, are not supported, either by the
implementation in general or in the specified storage location.
PSA_ERROR_INSUFFICIENT_ENTROPY
PSA_ERROR_INSUFFICIENT_MEMORY
PSA_ERROR_INSUFFICIENT_STORAGE
PSA_ERROR_COMMUNICATION_FAILURE
PSA_ERROR_CORRUPTION_DETECTED
PSA_ERROR_STORAGE_FAILURE
PSA_ERROR_DATA_CORRUPT
PSA_ERROR_DATA_INVALID
Description
The key is generated randomly. Its location, policy, type and size are taken from attributes.
Implementations must reject an attempt to generate a key of size 0.
The following type-specific considerations apply:
∙ For RSA keys (PSA_KEY_TYPE_RSA_KEY_PAIR), the public exponent is 65537. The modulus is a product of
two probabilistic primes between 2^{n-1} and 2^n where n is the bit size specified in the attributes.
psa_copy_key (function)
Make a copy of a key.
psa_status_t psa_copy_key(psa_key_id_t source_key,
const psa_key_attributes_t * attributes,
psa_key_id_t * target_key);
Parameters
source_key
The key to copy. It must permit the usage PSA_KEY_USAGE_COPY. If a
private or secret key is being copied outside of a secure element it
must also permit PSA_KEY_USAGE_EXPORT.
attributes
The attributes for the new key. This function uses the attributes as
follows:
∙ The key type and size can be 0. If either is nonzero, it must
match the corresponding attribute of the source key.
∙ The key location (the lifetime and, for persistent keys, the key
identifier) is used directly.
IHI 0086
Page 94
1.1.2
Non-confidential
∙ The key policy (usage flags and permitted algorithm) are
combined from the source key and attributes so that both sets
of restrictions apply, as described in the documentation of this
function.
Note:
This is an input parameter: it is not updated with the final key
attributes. The final attributes of the new key can be queried
by calling psa_get_key_attributes() with the key’s identifier.
target_key
On success, an identifier for the newly created key. PSA_KEY_ID_NULL
on failure.
Returns: psa_status_t
PSA_SUCCESS
Success. If the new key is persistent, the key material and the key’s
metadata have been saved to persistent storage.
PSA_ERROR_BAD_STATE
The library requires initializing by a call to psa_crypto_init().
PSA_ERROR_INVALID_HANDLE
source_key is not a valid key identifier.
PSA_ERROR_NOT_PERMITTED
The following conditions can result in this error:
∙ source_key does not have the PSA_KEY_USAGE_COPY usage flag.
∙ source_key does not have the PSA_KEY_USAGE_EXPORT usage flag,
and the location of target_key is outside the security boundary
of the source_key storage location.
∙ The implementation does not permit creating a key with the
specified attributes due to some implementation-specific policy.
PSA_ERROR_ALREADY_EXISTS
This is an attempt to create a persistent key, and there is already a
persistent key with the given identifier.
PSA_ERROR_INVALID_ARGUMENT
The following conditions can result in this error:
∙ attributes specifies a key type or key size which does not match
the attributes of source key.
∙ The lifetime or identifier in attributes are invalid.
∙ The key policies from source_key and those specified in
attributes are incompatible.
PSA_ERROR_NOT_SUPPORTED
The following conditions can result in this error:
∙ The source key storage location does not support copying to the
target key’s storage location.
∙ The key attributes, as a whole, are not supported in the target
key’s storage location.
PSA_ERROR_INSUFFICIENT_MEMORY
PSA_ERROR_INSUFFICIENT_STORAGE
PSA_ERROR_COMMUNICATION_FAILURE
PSA_ERROR_CORRUPTION_DETECTED
IHI 0086
Page 95
1.1.2
Non-confidential
PSA_ERROR_STORAGE_FAILURE
PSA_ERROR_DATA_CORRUPT
PSA_ERROR_DATA_INVALID
Description
Copy key material from one location to another.
This function is primarily useful to copy a key from one location to another, as it populates a key using the
material from another key which can have a different lifetime.
This function can be used to share a key with a different party, subject to implementation-defined
restrictions on key sharing.
The policy on the source key must have the usage flag PSA_KEY_USAGE_COPY set. This flag is sufficient to
permit the copy if the key has the lifetime PSA_KEY_LIFETIME_VOLATILE or PSA_KEY_LIFETIME_PERSISTENT. Some
secure elements do not provide a way to copy a key without making it extractable from the secure element.
If a key is located in such a secure element, then the key must have both usage flags PSA_KEY_USAGE_COPY
and PSA_KEY_USAGE_EXPORT in order to make a copy of the key outside the secure element.
The resulting key can only be used in a way that conforms to both the policy of the original key and the
policy specified in the attributes parameter:
∙ The usage flags on the resulting key are the bitwise-and of the usage flags on the source policy and
the usage flags in attributes.
∙ If both permit the same algorithm or wildcard-based algorithm, the resulting key has the same
permitted algorithm.
∙ If either of the policies permits an algorithm and the other policy permits a wildcard-based permitted
algorithm that includes this algorithm, the resulting key uses this permitted algorithm.
∙ If the policies do not permit any algorithm in common, this function fails with the status
PSA_ERROR_INVALID_ARGUMENT.
The effect of this function on implementation-defined attributes is implementation-defined.
9.6.2 Key destruction
psa_destroy_key (function)
Destroy a key.
psa_status_t psa_destroy_key(psa_key_id_t key);
Parameters
key
Identifier of the key to erase. If this is PSA_KEY_ID_NULL, do nothing
and return PSA_SUCCESS.
IHI 0086
Page 96
1.1.2
Non-confidential
Returns: psa_status_t
PSA_SUCCESS
Success. If key was a valid key identifier, then the key material that it
referred to has been erased. Alternatively, key was PSA_KEY_ID_NULL.
PSA_ERROR_BAD_STATE
The library requires initializing by a call to psa_crypto_init().
PSA_ERROR_INVALID_HANDLE
key is neither a valid key identifier, nor PSA_KEY_ID_NULL.
PSA_ERROR_NOT_PERMITTED
The key cannot be erased because it is read-only, either due to a
policy or due to physical restrictions.
PSA_ERROR_COMMUNICATION_FAILURE There was an failure in communication with the cryptoprocessor. The
key material might still be present in the cryptoprocessor.
PSA_ERROR_CORRUPTION_DETECTED
An unexpected condition which is not a storage corruption or a
communication failure occurred. The cryptoprocessor might have
been compromised.
PSA_ERROR_STORAGE_FAILURE
The storage operation failed. Implementations must make a best
effort to erase key material even in this situation, however, it might
be impossible to guarantee that the key material is not recoverable in
such cases.
PSA_ERROR_DATA_CORRUPT
The storage is corrupted. Implementations must make a best effort to
erase key material even in this situation, however, it might be
impossible to guarantee that the key material is not recoverable in
such cases.
PSA_ERROR_DATA_INVALID
Description
This function destroys a key from both volatile memory and, if applicable, non-volatile storage.
Implementations must make a best effort to ensure that that the key material cannot be recovered.
This function also erases any metadata such as policies and frees resources associated with the key.
Destroying the key makes the key identifier invalid, and the key identifier must not be used again by the
application.
If a key is currently in use in a multi-part operation, then destroying the key will cause the multi-part
operation to fail.
IHI 0086
Page 97
1.1.2
Non-confidential
psa_purge_key (function)
Remove non-essential copies of key material from memory.
psa_status_t psa_purge_key(psa_key_id_t key);
Parameters
key
Identifier of the key to purge.
Returns: psa_status_t
PSA_SUCCESS
Success. The key material has been removed from memory, if the key
material is not currently required.
PSA_ERROR_BAD_STATE
The library requires initializing by a call to psa_crypto_init().
PSA_ERROR_INVALID_HANDLE
key is not a valid key identifier.
PSA_ERROR_COMMUNICATION_FAILURE
PSA_ERROR_CORRUPTION_DETECTED
PSA_ERROR_STORAGE_FAILURE
PSA_ERROR_DATA_CORRUPT
PSA_ERROR_DATA_INVALID
Description
For keys that have been created with the PSA_KEY_USAGE_CACHE usage flag, an implementation is permitted
to make additional copies of the key material that are not in storage and not for the purpose of ongoing
operations.
This function will remove these extra copies of the key material from memory.
This function is not required to remove key material from memory in any of the following situations:
∙ The key is currently in use in a cryptographic operation.
∙ The key is volatile.
See also Managing key material on page 39.
9.6.3 Key export
psa_export_key (function)
Export a key in binary format.
psa_status_t psa_export_key(psa_key_id_t key,
uint8_t * data,
size_t data_size,
size_t * data_length);
IHI 0086
Page 98
1.1.2
Non-confidential
//////////////////////////////////////////