PSA Certified Crypto API 1.1 (2023) - page 4
C.1 Algorithm macros
#define PSA_ALG_AEAD_WITH_DEFAULT_LENGTH_TAG(aead_alg) \
((((aead_alg) & ~0x003f8000) == 0x05400100) ? PSA_ALG_CCM : \
(((aead_alg) & ~0x003f8000) == 0x05400200) ? PSA_ALG_GCM : \
(((aead_alg) & ~0x003f8000) == 0x05000500) ? PSA_ALG_CHACHA20_POLY1305 : \
PSA_ALG_NONE)
#define PSA_ALG_AEAD_WITH_AT_LEAST_THIS_LENGTH_TAG(aead_alg, min_tag_length) \
( PSA_ALG_AEAD_WITH_SHORTENED_TAG(aead_alg, min_tag_length) | 0x00008000 )
#define PSA_ALG_AEAD_WITH_SHORTENED_TAG(aead_alg, tag_length) \
((psa_algorithm_t) (((aead_alg) & ~0x003f8000) | (((tag_length) & 0x3f) << 16)))
#define PSA_ALG_AT_LEAST_THIS_LENGTH_MAC(mac_alg, min_mac_length) \
( PSA_ALG_TRUNCATED_MAC(mac_alg, min_mac_length) | 0x00008000 )
#define PSA_ALG_DETERMINISTIC_ECDSA(hash_alg) \
((psa_algorithm_t) (0x06000700 | ((hash_alg) & 0x000000ff)))
#define PSA_ALG_ECDSA(hash_alg) \
((psa_algorithm_t) (0x06000600 | ((hash_alg) & 0x000000ff)))
#define PSA_ALG_FULL_LENGTH_MAC(mac_alg) \
((psa_algorithm_t) ((mac_alg) & ~0x003f8000))
#define PSA_ALG_GET_HASH(alg) \
(((alg) & 0x000000ff) == 0 ? PSA_ALG_NONE : 0x02000000 | ((alg) & 0x000000ff))
#define PSA_ALG_HKDF(hash_alg) \
((psa_algorithm_t) (0x08000100 | ((hash_alg) & 0x000000ff)))
#define PSA_ALG_HKDF_EXPAND(hash_alg) \
((psa_algorithm_t) (0x08000500 | ((hash_alg) & 0x000000ff)))
#define PSA_ALG_HKDF_EXTRACT(hash_alg) \
((psa_algorithm_t) (0x08000400 | ((hash_alg) & 0x000000ff)))
#define PSA_ALG_HMAC(hash_alg) \
((psa_algorithm_t) (0x03800000 | ((hash_alg) & 0x000000ff)))
#define PSA_ALG_IS_AEAD(alg) \
(((alg) & 0x7f000000) == 0x05000000)
#define PSA_ALG_IS_AEAD_ON_BLOCK_CIPHER(alg) \
(((alg) & 0x7f400000) == 0x05400000)
(continues on next page)
IHI 0086
Page 299
1.1.2
Non-confidential
(continued from previous page)
#define PSA_ALG_IS_ASYMMETRIC_ENCRYPTION(alg) \
(((alg) & 0x7f000000) == 0x07000000)
#define PSA_ALG_IS_BLOCK_CIPHER_MAC(alg) \
(((alg) & 0x7fc00000) == 0x03c00000)
#define PSA_ALG_IS_CIPHER(alg) \
(((alg) & 0x7f000000) == 0x04000000)
#define PSA_ALG_IS_DETERMINISTIC_ECDSA(alg) \
(((alg) & ~0x000000ff) == 0x06000700)
#define PSA_ALG_IS_ECDH(alg) \
(((alg) & 0x7fff0000) == 0x09020000)
#define PSA_ALG_IS_ECDSA(alg) \
(((alg) & ~0x000001ff) == 0x06000600)
#define PSA_ALG_IS_FFDH(alg) \
(((alg) & 0x7fff0000) == 0x09010000)
#define PSA_ALG_IS_HASH(alg) \
(((alg) & 0x7f000000) == 0x02000000)
#define PSA_ALG_IS_HASH_AND_SIGN(alg) \
(PSA_ALG_IS_RSA_PSS(alg) || PSA_ALG_IS_RSA_PKCS1V15_SIGN(alg) || \
PSA_ALG_IS_ECDSA(alg) || PSA_ALG_IS_HASH_EDDSA(alg))
#define PSA_ALG_IS_HASH_EDDSA(alg) \
(((alg) & ~0x000000ff) == 0x06000900)
#define PSA_ALG_IS_HKDF(alg) \
(((alg) & ~0x000000ff) == 0x08000100)
#define PSA_ALG_IS_HKDF_EXPAND(alg) \
(((alg) & ~0x000000ff) == 0x08000500)
#define PSA_ALG_IS_HKDF_EXTRACT(alg) \
(((alg) & ~0x000000ff) == 0x08000400)
#define PSA_ALG_IS_HMAC(alg) \
(((alg) & 0x7fc0ff00) == 0x03800000)
#define PSA_ALG_IS_KEY_AGREEMENT(alg) \
(((alg) & 0x7f000000) == 0x09000000)
(continues on next page)
IHI 0086
Page 300
1.1.2
Non-confidential
(continued from previous page)
#define PSA_ALG_IS_KEY_DERIVATION(alg) \
(((alg) & 0x7f000000) == 0x08000000)
#define PSA_ALG_IS_KEY_DERIVATION_STRETCHING(alg) \
(((alg) & 0x7f800000) == 0x08800000)
#define PSA_ALG_IS_MAC(alg) \
(((alg) & 0x7f000000) == 0x03000000)
#define PSA_ALG_IS_PBKDF2_HMAC(alg) \
(((alg) & ~0x000000ff) == 0x08800100)
#define PSA_ALG_IS_RANDOMIZED_ECDSA(alg) \
(((alg) & ~0x000000ff) == 0x06000600)
#define PSA_ALG_IS_RAW_KEY_AGREEMENT(alg) \
(((alg) & 0x7f00ffff) == 0x09000000)
#define PSA_ALG_IS_RSA_OAEP(alg) \
(((alg) & ~0x000000ff) == 0x07000300)
#define PSA_ALG_IS_RSA_PKCS1V15_SIGN(alg) \
(((alg) & ~0x000000ff) == 0x06000200)
#define PSA_ALG_IS_RSA_PSS(alg) \
(((alg) & ~0x000010ff) == 0x06000300)
#define PSA_ALG_IS_RSA_PSS_ANY_SALT(alg) \
(((alg) & ~0x000000ff) == 0x06001300)
#define PSA_ALG_IS_RSA_PSS_STANDARD_SALT(alg) \
(((alg) & ~0x000000ff) == 0x06000300)
#define PSA_ALG_IS_SIGN(alg) \
(((alg) & 0x7f000000) == 0x06000000)
#define PSA_ALG_IS_SIGN_HASH(alg) \
PSA_ALG_IS_SIGN(alg)
#define PSA_ALG_IS_SIGN_MESSAGE(alg) \
(PSA_ALG_IS_SIGN(alg) && \
(alg) != PSA_ALG_ECDSA_ANY && (alg) != PSA_ALG_RSA_PKCS1V15_SIGN_RAW)
#define PSA_ALG_IS_STREAM_CIPHER(alg) \
(((alg) & 0x7f800000) == 0x04800000)
(continues on next page)
IHI 0086
Page 301
1.1.2
Non-confidential
(continued from previous page)
#define PSA_ALG_IS_TLS12_PRF(alg) \
(((alg) & ~0x000000ff) == 0x08000200)
#define PSA_ALG_IS_TLS12_PSK_TO_MS(alg) \
(((alg) & ~0x000000ff) == 0x08000300)
#define PSA_ALG_IS_WILDCARD(alg) \
((PSA_ALG_GET_HASH(alg) == PSA_ALG_ANY_HASH) || \
(((alg) & 0x7f008000) == 0x03008000) || \
(((alg) & 0x7f008000) == 0x05008000))
#define PSA_ALG_KEY_AGREEMENT(ka_alg, kdf_alg) \
((ka_alg) | (kdf_alg))
#define PSA_ALG_KEY_AGREEMENT_GET_BASE(alg) \
((psa_algorithm_t)((alg) & 0xffff0000))
#define PSA_ALG_KEY_AGREEMENT_GET_KDF(alg) \
((psa_algorithm_t)((alg) & 0xfe00ffff))
#define PSA_ALG_PBKDF2_HMAC(hash_alg) \
((psa_algorithm_t)(0x08800100 | ((hash_alg) & 0x000000ff)))
#define PSA_ALG_RSA_OAEP(hash_alg) \
((psa_algorithm_t)(0x07000300 | ((hash_alg) & 0x000000ff)))
#define PSA_ALG_RSA_PKCS1V15_SIGN(hash_alg) \
((psa_algorithm_t)(0x06000200 | ((hash_alg) & 0x000000ff)))
#define PSA_ALG_RSA_PSS(hash_alg) \
((psa_algorithm_t)(0x06000300 | ((hash_alg) & 0x000000ff)))
#define PSA_ALG_RSA_PSS_ANY_SALT(hash_alg) \
((psa_algorithm_t)(0x06001300 | ((hash_alg) & 0x000000ff)))
#define PSA_ALG_TLS12_PRF(hash_alg) \
((psa_algorithm_t) (0x08000200 | ((hash_alg) & 0x000000ff)))
#define PSA_ALG_TLS12_PSK_TO_MS(hash_alg) \
((psa_algorithm_t) (0x08000300 | ((hash_alg) & 0x000000ff)))
#define PSA_ALG_TRUNCATED_MAC(mac_alg, mac_length) \
((psa_algorithm_t) (((mac_alg) & ~0x003f8000) | (((mac_length) & 0x3f) << 16)))
IHI 0086
Page 302
1.1.2
Non-confidential
C.2 Key type macros
#define PSA_BLOCK_CIPHER_BLOCK_LENGTH(type) \
(1u << (((type) >> 8) & 7))
#define PSA_KEY_TYPE_DH_GET_FAMILY(type) \
((psa_dh_family_t) ((type) & 0x00ff))
#define PSA_KEY_TYPE_DH_KEY_PAIR(group) \
((psa_key_type_t) (0x7200 | (group)))
#define PSA_KEY_TYPE_DH_PUBLIC_KEY(group) \
((psa_key_type_t) (0x4200 | (group)))
#define PSA_KEY_TYPE_ECC_GET_FAMILY(type) \
((psa_ecc_family_t) ((type) & 0x00ff))
#define PSA_KEY_TYPE_ECC_KEY_PAIR(curve) \
((psa_key_type_t) (0x7100 | (curve)))
#define PSA_KEY_TYPE_ECC_PUBLIC_KEY(curve) \
((psa_key_type_t) (0x4100 | (curve)))
#define PSA_KEY_TYPE_IS_ASYMMETRIC(type) \
(((type) & 0x4000) == 0x4000)
#define PSA_KEY_TYPE_IS_DH(type) \
((PSA_KEY_TYPE_PUBLIC_KEY_OF_KEY_PAIR(type) & 0xff00) == 0x4200)
#define PSA_KEY_TYPE_IS_DH_KEY_PAIR(type) \
(((type) & 0xff00) == 0x7200)
#define PSA_KEY_TYPE_IS_DH_PUBLIC_KEY(type) \
(((type) & 0xff00) == 0x4200)
#define PSA_KEY_TYPE_IS_ECC(type) \
((PSA_KEY_TYPE_PUBLIC_KEY_OF_KEY_PAIR(type) & 0xff00) == 0x4100)
#define PSA_KEY_TYPE_IS_ECC_KEY_PAIR(type) \
(((type) & 0xff00) == 0x7100)
#define PSA_KEY_TYPE_IS_ECC_PUBLIC_KEY(type) \
(((type) & 0xff00) == 0x4100)
#define PSA_KEY_TYPE_IS_KEY_PAIR(type) \
(((type) & 0x7000) == 0x7000)
(continues on next page)
IHI 0086
Page 303
1.1.2
Non-confidential
(continued from previous page)
#define PSA_KEY_TYPE_IS_PUBLIC_KEY(type) \
(((type) & 0x7000) == 0x4000)
#define PSA_KEY_TYPE_IS_RSA(type) \
(PSA_KEY_TYPE_PUBLIC_KEY_OF_KEY_PAIR(type) == 0x4001)
#define PSA_KEY_TYPE_IS_UNSTRUCTURED(type) \
(((type) & 0x7000) == 0x1000 || ((type) & 0x7000) == 0x2000)
#define PSA_KEY_TYPE_KEY_PAIR_OF_PUBLIC_KEY(type) \
((psa_key_type_t) ((type) | 0x3000))
#define PSA_KEY_TYPE_PUBLIC_KEY_OF_KEY_PAIR(type) \
((psa_key_type_t) ((type) & ~0x3000))
C.3 Hash suspend state macros
#define PSA_HASH_SUSPEND_HASH_STATE_FIELD_LENGTH(alg) \
((alg)==PSA_ALG_MD2 ? 64 : \
(alg)==PSA_ALG_MD4 || (alg)==PSA_ALG_MD5 ? 16 : \
(alg)==PSA_ALG_RIPEMD160 || (alg)==PSA_ALG_SHA_1 ? 20 : \
(alg)==PSA_ALG_SHA_224 || (alg)==PSA_ALG_SHA_256 ? 32 : \
(alg)==PSA_ALG_SHA_512 || (alg)==PSA_ALG_SHA_384 || \
(alg)==PSA_ALG_SHA_512_224 || (alg)==PSA_ALG_SHA_512_256 ? 64 : \
0)
#define PSA_HASH_SUSPEND_INPUT_LENGTH_FIELD_LENGTH(alg) \
((alg)==PSA_ALG_MD2 ? 1 : \
(alg)==PSA_ALG_MD4 || (alg)==PSA_ALG_MD5 || (alg)==PSA_ALG_RIPEMD160 || \
(alg)==PSA_ALG_SHA_1 || (alg)==PSA_ALG_SHA_224 || (alg)==PSA_ALG_SHA_256 ? 8 : \
(alg)==PSA_ALG_SHA_512 || (alg)==PSA_ALG_SHA_384 || \
(alg)==PSA_ALG_SHA_512_224 || (alg)==PSA_ALG_SHA_512_256 ? 16 : \
0)
#define PSA_HASH_SUSPEND_OUTPUT_SIZE(alg) \
(PSA_HASH_SUSPEND_ALGORITHM_FIELD_LENGTH + \
PSA_HASH_SUSPEND_INPUT_LENGTH_FIELD_LENGTH(alg) + \
PSA_HASH_SUSPEND_HASH_STATE_FIELD_LENGTH(alg) + \
PSA_HASH_BLOCK_LENGTH(alg) - 1)
IHI 0086
Page 304
1.1.2
Non-confidential
Appendix D: Security Risk Assessment
This Security Risk Assessment (SRA) analyses the security of the Crypto API itself, not of any specific
implementation of the API, or any specific use of the API. However, the security of an implementation of
the Crypto API depends on the implementation design, the capabilities of the system in which it is
deployed, and the need to address some of the threats identified in this assessment.
To enable the Crypto API to be suitable for a wider range of security use cases, this SRA considers a broad
range of adversarial models and threats to the application and the implementation, as well as to the API.
This approach allows the assessment to identify API design requirements that affect the ability for an
implementation to mitigate threats that do not directly attack the API.
The scope is described in Adversarial models on page 308.
D.1 Architecture
D.1.1 System definition
Figure 19 shows the Crypto API as the defined interface that an Application uses to interact with the
Cryptoprocessor.
call
Application
Cryptoprocessor
Crypto API
Figure 19 Crypto API
Assumptions, constraints, and interacting entities
This SRA makes the following assumptions about the Crypto API design:
∙ The API does not provide arguments that identify the caller, because they can be spoofed easily, and
cannot be relied upon. It is assumed that the implementation of the API can determine the caller
identity, where this is required. See Optional isolation on page 18.
∙ The API does not prevent the use of mitigations that are required by an implementation of the API.
See Implementation remediations on page 317.
∙ The API follows best-practices for C interface design, reducing the risk of exploitable errors in the
application and implementation code. See Ease of use on page 20.
Trust boundaries and information flow
The Crypto API is the interface available to the programmer, and is the main attack surface that is analyzed
here. However, to ensure that the API enables the mitigation of other threats to an implementation, we
also consider the system context in which the Crypto API is used.
Figure 20 on page 306 shows the data flow for a typical application usage of the Crypto API, for example,
to exchange ciphertext with an external system, or for at rest protection in system non-volatile storage.
The Application uses the Crypto API to interact with the Cryptoprocessor. The Cryptoprocessor stores
persistent keys in a Key Store.
IHI 0086
Page 305
1.1.2
Non-confidential
«System boundary»
ciphertext
Crypto API call
store key
External system
Application
Cryptoprocessor
response
load key
Key Store
ciphertext
NVM
Figure 20 Crypto API dataflow diagram for an implementation with no isolation
For some adversarial models, Cryptoprocessor isolation or Caller isolation is required in the implementation
to achieve the security goals. See Security goals on page 308, and remediations R.1 and R.2 in
Implementation remediations on page 317.
The Cryptoprocessor can optionally include a trust boundary within its implementation of the API. The
trust boundary shown in Figure 21 corresponds to Cryptoprocessor isolation. The Cryptoprocessor
boundary protects the confidentiality and integrity of the Cryptoprocessor and Key Store state from
system components that are outside of the boundary.
«System boundary»
«Cryptoprocessor boundary»
ciphertext
Crypto API call
store key
External system
Application
Cryptoprocessor
response
load key
Key Store
ciphertext
NVM
Figure 21 Crypto API dataflow diagram for an implementation with cryptoprocessor isolation
If the implementation supports multiple, independent client Applications within the system, each
Application has its own view of the Cryptoprocessor and key store. The additional trust boundaries
required for a caller isolated implementation are shown in Figure 22 on page 307. The Application
boundary restricts the capabilities of the Application, and protects the confidentiality and integrity of
system state from the Application.
IHI 0086
Page 306
1.1.2
Non-confidential
«System boundary»
«Application boundary»
ciphertext
External system
Application
Crypto API
ciphertext
response
call
«Cryptoprocessor boundary»
store key
Cryptoprocessor
NVM
load key
Key Store
Crypto API
ciphertext
response
call
«Application boundary»
ciphertext
External system
Other application
Figure 22 Crypto API dataflow diagram for an implementation with caller isolation
D.1.2 Assets and stakeholders
1. Cryptographic keys and key-related assets. This includes the key properties, such as the key type,
identity and policies.
Stakeholders can include the SiP, the OEM, the system or application owner. Owners of a key need
to be able to use the key for cryptographic operations, such as encryption or signature, and where
permitted, delete, copy or extract the key.
Disclosure of the cryptographic key material to an attacker defeats the protection that the use of
cryptography provides. Modification of cryptographic key material or key properties by an attacker
has the same end result. These allow an attacker access to the assets that are protected by the key.
2. Other cryptographic assets, for example, intermediate calculation values and RNG state.
Disclosure or modification of these assets can enable recovery of cryptographic keys, and loss of
cryptographic protection.
3. Application input/output data and cryptographic operation state.
Application data is only provided to the Cryptoprocessor for cryptographic operations, and its
stakeholder is the application owner.
Disclosure of this data - whether it is plaintext, or other data or state - to an attacker defeats the
protection that the use of cryptography provides. Modification of this data can have the same effect.
IHI 0086
Page 307
1.1.2
Non-confidential
D.1.3 Security goals
Cryptography is used as a mitigation to the risk of disclosure or tampering with data assets that require
protection, where isolation of the attacker from the data asset is unavailable or inadequate. Using
cryptography introduces new threats related to the incorrect use of cryptography and mismanagement of
cryptographic keys. Table 28 lists the security goals for the Crypto API to address these threats.
Table 28 Security goals
Id
Description
G.1
An attacker shall not be able to disclose the plaintext corresponding to a ciphertext for which
they do not own the correct key.
G.2
An attacker shall not be able to generate authenticated material for which they do not own
the correct key.
G.3
An attacker shall not be able to exfiltrate keys or other private information stored by the
Crypto API.
G.4
An attacker shall not be able to alter any state held by the implementation of the Crypto API,
such as internal keys or other private information (for example, certificates, signatures, etc.).
D.2 Threat Model
D.2.1 Adversarial models
The API itself has limited ability to mitigate threats. However, mitigation of some of the threats within the
cryptoprocessor can place requirements on the API design. This analysis considers a broad attack surface,
to also identify requirements that enable the mitigation of specific threats within a cryptoprocessor
implementation.
Table 29 on page 309 describes the adversarial models that are considered in this assessment.
A specific implementation of the Crypto API might not include all of these adversarial models within its
own threat model. In this case, the related threats, risks, and mitigations might not be required for that
implementation.
IHI 0086
Page 308
1.1.2
Non-confidential
Table 29 Adversarial models
Id
Description
M.0
The Adversary is capable of accessing data that is outside the Security Perimeter of the
system and on commonly accessible channels, such as messages in transit or data in storage.
This includes, but is not limited to:
∙ Read any input and output.
∙ Provide, forge, replay or modify input.
∙ Attempt to gain read/write access to external storage devices.
∙ Perform timings on the operations being done by the target machine, either in normal
operation or as a response to crafted inputs. For example, timing attacks on web
servers.
Once access to data is obtained, we do not make a further case distinction of the Adversarial
Model depending on other capabilities. For example, the ability to perform cryptanalysis on
intercepted ciphertext.
M.1
The Adversary is capable of mounting attacks from software.
This includes, but is not limited to:
∙ Software exploitation.
∙ Side channel analysis that that relies on software-exposed, built-in hardware features to
perform physical unit and time measurements.
∙ Attacks that exploit access to any memory mapped configuration, monitoring, debug
register.
∙ Software-induced glitching of resources, for example Row hammer, or crashing the
CPU by running intensive tasks.
M.2
The Adversary is capable of mounting simple, passive hardware attacks. This Adversary has
physical access to the hardware.
This includes, but is not limited to:
∙ Side channel analyses that require external measurement devices. For example, this can
utilize leakage sources such as EM emissions, power consumption, photonic emission,
or acoustic channels.
∙ Plugging malicious hardware into an unmodified system.
∙ Passive SoC or memory interposition.
Adversarial models that are outside the scope of this assessment are shown in Table 30 on page 310.
IHI 0086
Page 309
1.1.2
Non-confidential
Table 30 Adversarial models that are outside the scope of this SRA
Id
Description
M.3
The Adversary is capable of mounting sophisticated and active physical attacks.
This includes, but is not limited to:
∙ Interposing memory and blocking, replaying, and injecting transactions, this requires a
much more precise timing than passive eavesdropping.
∙ Replacing or adding chips on the motherboard.
M.4
The Adversary is capable of performing invasive silicon microsurgery.
D.2.2 Threats and attacks
Table 31 describes threats to the Security Goals, and provides examples of corresponding attacks. This
table identifies which Security goals are affected by the attacks, and which Adversarial model or models
are required to execute the attack.
See Risk assessment on page 312 for an evaluation of the risks posed by these threats, Mitigations on
page 313 for mitigation requirements in the API design, and Implementation remediations on page 317 for
mitigation recommendations in the cryptoprocessor implementation.
Table 31 Threats and attacks
Threat
Attack (Examples)
Id
Description
Goals
Mod-
Id: Description
els
T.1
Use of insecure or
G.1
M.0
A.C1: Using a cryptographic algorithm that is not
incorrectly
G.2
adequately secure for the application use case can
implemented
permit an attacker to recover the application plaintext
cryptography
from attacker-accessible data.
A.C2: Using a cryptographic algorithm that is not
adequately secure for the application use case can
permit an attacker to inject forged authenticated
material into application data in transit or in storage.
A.C3: Using an insecure cryptographic algorithm, or one
that is incorrectly implemented can permit an attacker to
recover the cryptographic key. Key recovery enables the
attacker to reveal encrypted plaintexts, and inject forged
authenticated data.
continues on next page
IHI 0086
Page 310
1.1.2
Non-confidential
Table
31 - continued from previous page
Threat
Attack (Examples)
Id
Description
Goals
Mod-
Id: Description
els
T.2
Misuse of
G.1
M.0
A.C4: Reusing a cryptographic key with different
cryptographic
G.2
algorithms can result in cryptanalysis attacks on the
algorithms
ciphertexts or signatures which enable an attacker to
recover the plaintext, or the key itself.
T.3
Recover
G.3
M.1
A.C5: The attacker uses an indirect mechanism provided
non-extractable
by the API to extract a key that is not intended to be
key through the
extractable.
API
A.C6: The attacker uses a mechanism provided by the
API to enable brute-force recovery of a non-extractable
key. For example, On the Security of PKCS #11 [CLULOW]
describes various flaws in the design of the PKCS #11
interface standard that enable an attacker to recover
secret and non-extractable keys.
T.4
Illegal inputs to
G.3
M.1
A.60: Using a pointer to memory that does not belong to
the API
G.4
the application, in an attempt to make the
cryptoprocessor read or write memory that is
inaccessible to the application.
A.70: Passing out-of-range values, or incorrectly
formatted data, to provoke incorrect behavior in the
cryptoprocessor.
A.61: Providing invalid buffer lengths to cause
out-of-bounds read or write access within the
cryptoprocessor.
A.62: Call API functions in an invalid sequence to
provoke incorrect operation of the cryptoprocessor.
T.5
Direct access to
G.3
M.1
A.C7: Without a cryptoprocessor boundary, an attacker
cryptoprocessor
G.4
can directly access the cryptoprocessor state from an
state
application. See Figure 20 on page 306.
A.C8: A misconfigured cryptoprocessor boundary can
allow an attacker to directly access the cryptoprocessor
state from an Application.
T.6
Access and use
G.1
M.1
A.C9: Without application boundaries, the
another
G.2
cryptoprocessor provides a unified view of the
application’s
application assets. All keys are accessible to all callers of
assets
the Crypto API. See Figure 22 on page 307.
A.C10: The attacker can spoof the application identity
within a caller-isolated implementation to gain access to
another application’s assets.
continues on next page
IHI 0086
Page 311
1.1.2
Non-confidential
Table 31 - continued from previous page
Threat
Attack (Examples)
Id
Description
Goals
Mod-
Id: Description
els
T.7
Data-dependent
G.1
M.1
A.C11 Measuring the time for operations in the
timing
G.3
cryptoprocessor or the application, and using the
differential in results to assist in recovery of the key or
plaintext.
T.8
Memory
G.4
M.2
A.19: Corrupt application or cryptoprocessor state via a
manipulation
fault, causing incorrect operation of the cryptoprocessor.
M.1
A.59: Modifying function parameters in memory, while
the cryptoprocessor is accessing the parameter memory,
to cause incorrect operation of the cryptoprocessor.
T.9
Side channels
G.1
M.2
A.C12 Taking measurements from physical side-channels
G.3
during cryptoprocessor operation, and using this data to
recover keys or plaintext. For example, using power or
EM measurements.
M.1
A.C13 Taking measurements from shared-resource
side-channels during cryptoprocessor operation, and
using this data to recover keys or plaintext. For example,
attacks using a shared cache.
D.2.3 Risk assessment
The risk ratings in Table 32 follow a version of the risk assessment scheme in NIST Special Publication
800-30 Revision 1: Guide for Conducting Risk Assessments [SP800-30]. Likelihood of an attack and its impact
are evaluated independently, and then they are combined to obtain the overall risk of the attack.
The risk assessment is used to prioritize the threats that require mitigation. This helps to identify the
mitigations that have the highest priority for implementation. Mitigations are described in Mitigations on
page 313 and Implementation remediations on page 317.
It is recommended that this assessment is repeated for a specific implementation or product, taking into
consideration the Adversarial models that are within scope, and re-evaluating the impact based on the
assets at risk. Table 32 repeats the association in Table 31 on page 310 between an Adversarial model and
the Threats that it enables. This aids filtering of the assessment based on the models that are in scope for a
specific implementation.
Table 32 Risk assessment
Adversarial Model
Threat/Attack
Likelihood
Impacta
Risk
M.0
T.1
High
Medium
Medium
M.0
T.2
High
Medium
Medium
continues on next page
IHI 0086
Page 312
1.1.2
Non-confidential
Table 32 - continued from previous page
Adversarial Model
Threat/Attack
Likelihood
Impacta
Risk
M.1
T.3
Medium
High
Medium
M.1
T.4
High
Medium
Medium
M.1
T.5
High
Very high
Very high
M.1
T.6
High
High
High
M.1
T.7
Medium
Medium
Medium
M.1
T.8/A.59
Medium
Medium
Medium
M.2
T.8/A.19
Low
Medium
Low
M.2
T.9/A.C12
Low
High
Medium
M.1
T.9/A.C13
Medium
High
Medium
a. The impact of an attack is dependent on the impact of the disclosure or modification of the
application data that is cryptographically protected. This is ultimately determined by the
requirements and risk assessment for the product which is using the Crypto API. Table 32 on
page 312 allocates the impact as follows:
∙ ‘Medium’ if unspecified cryptoprocessor state or application data assets are affected.
∙ ‘High’ if an application’s cryptographic assets are affected.
∙ ‘Very High’ if all cryptoprocessor assets are affected.
D.3 Mitigations
D.3.1 Objectives
The objectives in Table 33 are a high-level description of what the design must achieve in order to mitigate
the threats. Detailed requirements that describe how the API or cryptoprocessor implementation can
deliver the objectives are provided in Requirements on page 314 and Implementation remediations on
page 317.
Table 33 Mitigation objectives
Id
Description
Threats addressed
O.1
Hide keys from the application
Keys are never directly manipulated by application
T.1 T.2 T.3 - see A keystore interface
software. Instead keys are referred to by handle,
on page 18.
removing the need to deal with sensitive key material
T.5 T.6 - to mitigate T.5 and T.6, the
inside applications. This form of API is also suitable for
implementation must provide some
secure elements, based on tamper-resistant hardware,
form of isolation. See Optional
that never reveal cryptographic keys.
isolation on page 18.
continues on next page
IHI 0086
Page 313
1.1.2
Non-confidential
Table 33 - continued from previous page
Id
Description
Threats addressed
O.2
Limit key usage
Associate each key with a policy that limits the use of
T.2 T.3 - see Key policies on page 83.
the key. The policy is defined by the application when
the key is created, after which it is immutable.
O.3
Best-practice cryptography
An application developer-oriented API to achieve
T.1 T.2 T.7 T.8 - see Ease of use on
practical cryptography: the Crypto API offers services
page 20.
that are oriented towards the application of
cryptographic methods like encrypt, sign, verify. This
enables the implementation to focus on best-practice
implementation of the cryptographic primitive, and the
application developer on correct selection and use of
those primitives.
O.4
Algorithm agility
Cryptographic functions are not tied to a specific
T.1 - see Choice of algorithms on
cryptographic algorithm. Primitives are designated at
page 19.
run-time. This simplifies updating an application to use
a more secure algorithm, and makes it easier to
implement dynamic selection of cryptographic
algorithms within an application.
D.3.2 Requirements
The design of the API can mitigate, or enable a cryptoprocessor to mitigate, some of the identified attacks.
Table 34 describes these mitigations. Mitigations that are delegated to the cryptoprocessor or application
are described in Implementation remediations on page 317.
Table 34 Security requirements
Id
Description
API impact
Threats/attacks addressed
SR.1
Key values are not exposed
The full key policy must be
T.3/A.C5 - key values are
(O.1)
by the API, except when
provided at the time a key is
hidden by the API.
importing or exporting a key.
created. See Key management
on page 21.
continues on next page
IHI 0086
Page 314
1.1.2
Non-confidential
Table 34 - continued from previous page
Id
Description
API impact
Threats/attacks addressed
SR.2
The policy for a key must be
The full key policy must be
T.3/A.C5 - once created, the
(O.2)
set when the key is created,
provided at the time a key is
key usage permissions cannot
and be immutable afterward.
created. See
be changed to permit export.
psa_key_attributes_t.
T.2/A.C4- once created, a
key cannot be repurposed by
changing its policy.
SR.3
The key policy must control
The key policy must include
T.2/A.C4 - a key cannot be
(O.2)
the algorithms that the key
usage permissions, and
reused with different
can be used with, and the
permitted-algorithm
algorithms.
functions of the API that the
attributes. See Key policies on
key can be used with.
page 83.
SR.4
Key export must be controlled
See PSA_KEY_USAGE_EXPORT.
T.3/A.C5 - a key can only be
(O.1)
by the key policy.
extracted from the
cryptoprocessor if explicitly
permitted by the key creator.
SR.5
The policy of a copied key
See psa_copy_key().
T.3/A.C5 - a copy of a key
(O.1)
must not provide rights that
cannot be exported if the
are not permitted by the
original could not be
original key policy.
exported.
T.3/A.C4 - a copy of a key
cannot be used in different
algorithm to the original.
SR.6
Unless explicitly required by
Algorithm inclusion is based
T.1/A.C1 A.C2 A.C3
(O.3)
the use case, the API must
on use cases. Warnings are
not define cryptographic
provided for algorithms and
algorithms with known
operations with known
security weaknesses. If
security weaknesses, and
possible, deprecated
recommendations made to
algorithms should not be
use alternative algorithms.
included.
SR.7
The API design must make it
Cryptographic operation
T.1/A.C1 A.C2 A.C3
(O.4)
easy to change to a different
functions select the specific
algorithm of the same type.
algorithm based on
parameters passed at runtime.
See Key types on page 50 and
Algorithms on page 107.
SR.8
Key derivation functions that
T.3/A.C6
(O.1)
expose part of the key value,
or make part of the key value
easily recoverable, must not
be provided in the API.
continues on next page
IHI 0086
Page 315
1.1.2
Non-confidential
Table
34 - continued from previous page
Id
Description
API impact
Threats/attacks addressed
SR.9
Constant values defined by
Key type values explicitly
T.8/A.19 - enablement only,
(O.3)
the API must be designed to
consider single-bit faults, see
mitigation is delegated to the
resist bit faults.
Key type encoding on
implementation.
page 294.a
Success and error status
codes differ by multiple bits,
see Status codes on page 41.b
SR.10
The API design must permit
Provision of comparison
T.7/A.C11 - enablement
(O.3)
the implementation of
functions for MAC, hash and
only, mitigation is delegated
operations with
key derivation operations.
to the implementation.
data-independent timing.
SR.11
Specify behavior for memory
Standardize the result when
T.8/A.59 - enablement only,
(O.3)
shared between the
parameters overlap, see
mitigation is delegated to the
application and
Overlap between parameters
implementation.
cryptoprocessor, including
on page 34.
where multiple parameters
overlap.
SR.12
The API must permit the
No use of shared memory
T.5/A.C7 - enablement only,
(O.1)
implementation to isolate the
between application and
mitigation is delegated to the
(O.2)
cryptoprocessor, to prevent
cryptoprocessor, except as
implementation.
access to keys without using
function parameters.
the API.
SR.13
The API design must permit
Operations that use random
T.9 - enablement only,
(O.3)
the implementation of
blinding to resist side-channel
mitigation is delegated to the
operations using mitigation
attacks, can return
implementation.
techniques that resist
RNG-specific error codes.
side-channel attacks.
See also SR.12, which enables
the cryptoprocessor to be
fully isolated, and
implemented within a
separate security processor.
a. Limited resistance to bit faults is still valuable in systems where memory may be susceptible to
single-bit flip attacks, for example, Rowhammer on some types of DRAM.
b. Unlike key type values, algorithm identifiers used in cryptographic operations are verified against a
the permitted-algorithm in the key policy. This provides a mitigation for a bit fault in an algorithm
identifier value, without requiring error detection within the algorithm identifier itself.
IHI 0086
Page 316
1.1.2
Non-confidential
D.4 Remediation & residual risk
D.4.1 Implementation remediations
Table 35 includes all recommended remediations for an implementation, assuming the full adversarial
model described in Adversarial models on page 308. When an implementation has a subset of the
adversarial models, then individual remediations can be excluded from an implementation, if the
associated threat is not relevant for that implementation.
Table 35 Implementation remediations
Id
Identified gap
Suggested remediation
R.1
T.5 - direct access to
The cryptoprocessor implementation provides cryptoprocessor
(O.1)
cryptoprocessor state.
isolation or caller isolation, to isolate the application from the
(O.3)
cryptoprocessor state, and from volatile and persistent key
material.
R.2
T.6 - access and use another
The cryptoprocessor implementation provides caller isolation,
(O.1)
application’s assets.
and maintains separate cryptoprocessor state for each
(O.3)
application. Each application must only be able to access its
own keys and ongoing operations.
Caller isolation requires that the implementation can securely
identify the caller of the Crypto API.
R.3
T.4/A.60 A.61 - using illegal
The cryptoprocessor implementation validates that memory
(O.3)
memory inputs.
buffers provided by the application are accessible by the
application.
R.4
T.4/A.70 - providing invalid
The cryptoprocessor implementation checks that imported key
(O.3)
formatted data.
data is valid before use.
R.5
T.4/A.62 - call the API in an
The cryptoprocessor implementation enforces the correct
(O.3)
invalid operation sequence.
sequencing of calls in multi-part operations. See Multi-part
operations on page 24.
R.6
T.3/A.C5 A.C6 - indirect key
Cryptoprocessor implementation-specific extensions to the
(O.1)
disclosure via the API.
API must avoid providing mechanisms that can extract or
(O.3)
recover key values, such as trivial key derivation algorithms.
R.8
T.8/A.59 - concurrent
The cryptoprocessor implementation treats application
(O.3)
modification of parameter
memory as untrusted and volatile, typically by not reading the
memory.
same memory location twice. See Stability of parameters on
page 34.
R.9
T.2/A.C4 - incorrect
The cryptoprocessor implementation validates the key
(O.3)
cryptographic parameters.
attributes and other parameters used for a cryptographic
operation, to ensure these conform to the API specification
and to the specification of the algorithm itself.
continues on next page
IHI 0086
Page 317
1.1.2
Non-confidential
Table 35 - continued from previous page
Id
Identified gap
Suggested remediation
R.10
T.1/A.C1 A.C2 A.C3 -
The cryptoprocessor does not support deprecated
(O.3)
insecure cryptographic
cryptographic algorithms, unless justified by specific use case
algorithms.
requirements.
R.11
T.7/A.C11 -
The cryptoprocessor implements cryptographic operations
(O.3)
data-independent timing.
with data-independent timing.
R.12
T.9 - side-channels.
The cryptoprocessor implements resistance to side-channels.
(O.3)
D.4.2 Residual risk
Threats T.2-T.4, and T.7-T.9 are fully mitigated in the API design, as described in Mitigations on page 313,
or the cryptoprocessor implementation, as described in Implementation remediations on page 317.
Table 36 describes the remaining risks related to T.1, T.5, and T.6 that cannot be mitigated fully by the API
or cryptoprocessor implementation. Responsibility for managing these risks lies with the application
developers and system integrators.
Table 36 Residual risk
Id
Threat/attack
Suggested remediations
RR.1
T.1
Selection of appropriately secure protocols, algorithms and key
sizes is the responsibility of the application developer.
RR.2
T.5
Correct isolation of the cryptoprocessor is the responsibility of
the cryptoprocessor and system implementation.
RR.3
T.6
Correct identification of the application client is the
responsibility of the cryptoprocessor and system
implementation.
Appendix E: Changes to the API
E.1 Document change history
This section provides the detailed changes made between published version of the document.
IHI 0086
Page 318
1.1.2
Non-confidential
E.1.1 Changes between 1.1.1 and 1.1.2
Clarifications and fixes
∙ Clarified the requirements on the hash parameter in the psa_sign_hash() and psa_verify_hash()
functions.
∙ Explicitly described the handling of input and output in psa_cipher_update(), consistent with the
documentation of psa_aead_update().
∙ Clarified the behavior of operation objects following a call to a setup function. Provided a diagram to
illustrate multi-part operation states.
∙ Clarified the key policy requirement for PSA_ALG_ECDSA_ANY.
∙ Clarified PSA_KEY_USAGE_EXPORT: “it permits moving a key outside of its current security boundary”.
This improves understanding of why it is not only required for psa_export_key(), but can also be
required for psa_copy_key() in some situations.
Other changes
∙ Moved the documentation of supported key import/export formats to a separate section of the
specification. See Key formats on page 103.
E.1.2 Changes between 1.1.0 and 1.1.1
Changes to the API
∙ Extended PSA_ALG_TLS12_PSK_TO_MS to support TLS cipher suites that mix a key exchange with a
pre-shared key.
∙ Added a new key derivation input step PSA_KEY_DERIVATION_INPUT_OTHER_SECRET.
∙ Added new algorithm families PSA_ALG_HKDF_EXTRACT and PSA_ALG_HKDF_EXPAND for protocols that
require the two parts of HKDF separately.
Other changes
∙ Relicensed the document under Attribution-ShareAlike 4.0 International with a patent license
derived from Apache License 2.0. See License on page viii.
∙ Adopted a standard set of Adversarial models for the Security Risk Assessment. See Adversarial
models on page 308.
E.1.3 Changes between 1.0.1 and 1.1.0
Changes to the API
∙ Relaxation when a raw key agreement is used as a key’s permitted-algorithm policy. This now also
permits the key agreement to be combined with any key derivation algorithm. See PSA_ALG_FFDH and
PSA_ALG_ECDH.
∙ Provide wildcard permitted-algorithm polices for MAC and AEAD that can specify a minimum MAC
or tag length. The following elements are added to the API:
IHI 0086
Page 319
1.1.2
Non-confidential
- PSA_ALG_AT_LEAST_THIS_LENGTH_MAC()
- PSA_ALG_AEAD_WITH_AT_LEAST_THIS_LENGTH_TAG()
∙ Added support for password-hashing and key-stretching algorithms, as key derivation operations.
- Added key types PSA_KEY_TYPE_PASSWORD, PSA_KEY_TYPE_PASSWORD_HASH and PSA_KEY_TYPE_PEPPER, to
support use of these new types of algorithm.
- Add key derivation input steps PSA_KEY_DERIVATION_INPUT_PASSWORD and
PSA_KEY_DERIVATION_INPUT_COST.
- Added psa_key_derivation_input_integer() to support numerical inputs to a key derivation
operation.
- Added functions psa_key_derivation_verify_bytes() and psa_key_derivation_verify_key() to
compare derivation output data within the cryptoprocessor.
- Added usage flag PSA_KEY_USAGE_VERIFY_DERIVATION for using keys with the new verification
functions.
- Modified the description of existing key derivation APIs to enable the use of key derivation
functionality.
∙ Added algorithms PSA_ALG_PBKDF2_HMAC() and PSA_ALG_PBKDF2_AES_CMAC_PRF_128 to implement the
PBKDF2 password-hashing algorithm.
∙ Add support for twisted Edwards Elliptic curve keys, and the associated EdDSA signature algorithms.
The following elements are added to the API:
- PSA_ECC_FAMILY_TWISTED_EDWARDS
- PSA_ALG_PURE_EDDSA
- PSA_ALG_ED25519PH
- PSA_ALG_ED448PH
- PSA_ALG_SHAKE256_512
- PSA_ALG_IS_HASH_EDDSA()
∙ Added an identifier for PSA_KEY_TYPE_ARIA.
∙ Added PSA_ALG_RSA_PSS_ANY_SALT(), which creates the same signatures as PSA_ALG_RSA_PSS(), but
permits any salt length when verifying a signature. Also added the helper macros
PSA_ALG_IS_RSA_PSS_ANY_SALT() and PSA_ALG_IS_RSA_PSS_STANDARD_SALT(), and extended
PSA_ALG_IS_RSA_PSS() to detect both variants of the RSA-PSS algorithm.
Clarifications and fixes
∙ Described the use of header files and the general API conventions. See Library conventions on
page 29.
∙ Added details for SHA-512/224 to the hash suspend state. See Hash suspend state on page 131.
∙ Removed ambiguities from support macros that provide buffer sizes, and improved consistency of
parameter domain definition.
∙ Clarified the length of salt used for creating PSA_ALG_RSA_PSS() signatures, and that verification
requires the same length of salt in the signature.
∙ Documented the use of PSA_ERROR_INVALID_ARGUMENT when the input data to an operation exceeds the
limit specified by the algorithm.
IHI 0086
Page 320
1.1.2
Non-confidential
∙ Clarified how the PSA_ALG_RSA_OAEP() algorithm uses the hash algorithm parameter.
∙ Fixed error in psa_key_derivation_setup() documentation: combined key agreement and key
derivation algorithms are valid for the Crypto API.
∙ Added and clarified documentation for error conditions across the API.
∙ Clarified the distinction between PSA_ALG_IS_HASH_AND_SIGN() and PSA_ALG_IS_SIGN_HASH().
∙ Clarified the behavior of PSA_ALG_IS_HASH_AND_SIGN() with a wildcard algorithm policy parameter.
∙ Documented the use of PSA_ALG_RSA_PKCS1V15_SIGN_RAW with the
PSA_ALG_RSA_PKCS1V15_SIGN(PSA_ALG_ANY_HASH) wildcard policy.
∙ Clarified the way that PSA_ALG_CCM determines the value of the CCM configuration parameter L.
Clarified that nonces generated by psa_aead_generate_nonce() can be shorter than the default nonce
length provided by PSA_AEAD_NONCE_LENGTH().
Other changes
∙ Add new appendix describing the encoding of algorithm identifiers and key types. See Algorithm and
key type encoding on page 287.
∙ Migrated cryptographic operation summaries to the start of the appropriate operation section, and
out of the Functionality overview on page 21.
∙ Included a Security Risk Assessment for the Crypto API.
E.1.4 Changes between 1.0.0 and 1.0.1
Changes to the API
∙ Added subtypes psa_key_persistence_t and psa_key_location_t for key lifetimes, and defined
standard values for these attributes.
∙ Added identifiers for PSA_ALG_SM3 and PSA_KEY_TYPE_SM4.
Clarifications and fixes
∙ Provided citation references for all cryptographic algorithms in the specification.
∙ Provided precise key size information for all key types.
∙ Permitted implementations to store and export long HMAC keys in hashed form.
∙ Provided details for initialization vectors in all unauthenticated cipher algorithms.
∙ Provided details for nonces in all AEAD algorithms.
∙ Clarified the input steps for HKDF.
∙ Provided details of signature algorithms, include requirements when using with psa_sign_hash() and
psa_verify_hash().
∙ Provided details of key agreement algorithms, and how to use them.
∙ Aligned terminology relating to key policies, to clarify the combination of the usage flags and
permitted algorithm in the policy.
IHI 0086
Page 321
1.1.2
Non-confidential
∙ Clarified the use of the individual key attributes for all of the key creation functions.
∙ Restructured the description for psa_key_derivation_output_key(), to clarify the handling of the
excess bits in ECC key generation when needing a string of bits whose length is not a multiple of 8.
∙ Referenced the correct buffer size macros for psa_export_key().
∙ Removed the use of the PSA_ERROR_DOES_NOT_EXIST error.
∙ Clarified concurrency rules.
∙ Document that psa_key_derivation_output_key() does not return PSA_ERROR_NOT_PERMITTED if the
secret input is the result of a key agreement. This matches what was already documented for
PSA_KEY_DERIVATION_INPUT_SECRET.
∙ Relax the requirement to use the defined key derivation methods in
psa_key_derivation_output_key(): implementation-specific KDF algorithms can use
implementation-defined methods to derive the key material.
Other changes
∙ Provided a glossary of terms.
∙ Provided a table of references.
∙ Restructured the Key management reference on page 46 chapter.
- Moved individual attribute types, values and accessor functions into their own sections.
- Placed permitted algorithms and usage flags into Key policies on page 83.
- Moved most introductory material from the Functionality overview on page 21 into the relevant
API sections.
E.1.5 Changes between 1.0 beta 3 and 1.0.0
Changes to the API
∙ Added PSA_CRYPTO_API_VERSION_MAJOR and PSA_CRYPTO_API_VERSION_MINOR to report the Crypto API
version.
∙ Removed PSA_ALG_GMAC algorithm identifier.
∙ Removed internal implementation macros from the API specification:
- PSA_AEAD_TAG_LENGTH_OFFSET
- PSA_ALG_AEAD_FROM_BLOCK_FLAG
- PSA_ALG_AEAD_TAG_LENGTH_MASK
- PSA__ALG_AEAD_WITH_DEFAULT_TAG_LENGTH__CASE
- PSA_ALG_CATEGORY_AEAD
- PSA_ALG_CATEGORY_ASYMMETRIC_ENCRYPTION
- PSA_ALG_CATEGORY_CIPHER
- PSA_ALG_CATEGORY_HASH
- PSA_ALG_CATEGORY_KEY_AGREEMENT
- PSA_ALG_CATEGORY_KEY_DERIVATION
- PSA_ALG_CATEGORY_MAC
IHI 0086
Page 322
1.1.2
Non-confidential
- PSA_ALG_CATEGORY_MASK
- PSA_ALG_CATEGORY_SIGN
- PSA_ALG_CIPHER_FROM_BLOCK_FLAG
- PSA_ALG_CIPHER_MAC_BASE
- PSA_ALG_CIPHER_STREAM_FLAG
- PSA_ALG_DETERMINISTIC_ECDSA_BASE
- PSA_ALG_ECDSA_BASE
- PSA_ALG_ECDSA_IS_DETERMINISTIC
- PSA_ALG_HASH_MASK
- PSA_ALG_HKDF_BASE
- PSA_ALG_HMAC_BASE
- PSA_ALG_IS_KEY_DERIVATION_OR_AGREEMENT
- PSA_ALG_IS_VENDOR_DEFINED
- PSA_ALG_KEY_AGREEMENT_MASK
- PSA_ALG_KEY_DERIVATION_MASK
- PSA_ALG_MAC_SUBCATEGORY_MASK
- PSA_ALG_MAC_TRUNCATION_MASK
- PSA_ALG_RSA_OAEP_BASE
- PSA_ALG_RSA_PKCS1V15_SIGN_BASE
- PSA_ALG_RSA_PSS_BASE
- PSA_ALG_TLS12_PRF_BASE
- PSA_ALG_TLS12_PSK_TO_MS_BASE
- PSA_ALG_VENDOR_FLAG
- PSA_BITS_TO_BYTES
- PSA_BYTES_TO_BITS
- PSA_ECDSA_SIGNATURE_SIZE
- PSA_HMAC_MAX_HASH_BLOCK_SIZE
- PSA_KEY_EXPORT_ASN1_INTEGER_MAX_SIZE
- PSA_KEY_EXPORT_DSA_KEY_PAIR_MAX_SIZE
- PSA_KEY_EXPORT_DSA_PUBLIC_KEY_MAX_SIZE
- PSA_KEY_EXPORT_ECC_KEY_PAIR_MAX_SIZE
- PSA_KEY_EXPORT_ECC_PUBLIC_KEY_MAX_SIZE
- PSA_KEY_EXPORT_RSA_KEY_PAIR_MAX_SIZE
- PSA_KEY_EXPORT_RSA_PUBLIC_KEY_MAX_SIZE
- PSA_KEY_TYPE_CATEGORY_FLAG_PAIR
- PSA_KEY_TYPE_CATEGORY_KEY_PAIR
- PSA_KEY_TYPE_CATEGORY_MASK
- PSA_KEY_TYPE_CATEGORY_PUBLIC_KEY
- PSA_KEY_TYPE_CATEGORY_RAW
- PSA_KEY_TYPE_CATEGORY_SYMMETRIC
- PSA_KEY_TYPE_DH_GROUP_MASK
- PSA_KEY_TYPE_DH_KEY_PAIR_BASE
IHI 0086
Page 323
1.1.2
Non-confidential
- PSA_KEY_TYPE_DH_PUBLIC_KEY_BASE
- PSA_KEY_TYPE_ECC_CURVE_MASK
- PSA_KEY_TYPE_ECC_KEY_PAIR_BASE
- PSA_KEY_TYPE_ECC_PUBLIC_KEY_BASE
- PSA_KEY_TYPE_IS_VENDOR_DEFINED
- PSA_KEY_TYPE_VENDOR_FLAG
- PSA_MAC_TRUNCATED_LENGTH
- PSA_MAC_TRUNCATION_OFFSET
- PSA_ROUND_UP_TO_MULTIPLE
- PSA_RSA_MINIMUM_PADDING_SIZE
- PSA_VENDOR_ECC_MAX_CURVE_BITS
- PSA_VENDOR_RSA_MAX_KEY_BITS
∙ Remove the definition of implementation-defined macros from the specification, and clarified the
implementation requirements for these macros in Implementation-specific macros on page 36.
- Macros with implementation-defined values are indicated by /* implementation-defined value
*/ in the API prototype. The implementation must provide the implementation.
- Macros for algorithm and key type construction and inspection have specification-defined
values. This is indicated by /* specification-defined value */ in the API prototype. Example
definitions of these macros is provided in Example macro implementations on page 298.
∙ Changed the semantics of multi-part operations.
- Formalize the standard pattern for multi-part operations.
- Require all errors to result in an error state, requiring a call to psa_xxx_abort() to reset the object.
- Define behavior in illegal and impossible operation states, and for copying and reusing
operation objects.
Although the API signatures have not changed, this change requires modifications to application
flows that handle error conditions in multi-part operations.
∙ Merge the key identifier and key handle concepts in the API.
- Replaced all references to key handles with key identifiers, or something similar.
- Replaced all uses of psa_key_handle_t with psa_key_id_t in the API, and removes the
psa_key_handle_t type.
- Removed psa_open_key and psa_close_key.
- Added PSA_KEY_ID_NULL for the never valid zero key identifier.
- Document rules related to destroying keys whilst in use.
- Added the PSA_KEY_USAGE_CACHE usage flag and the related psa_purge_key() API.
- Added clarification about caching keys to non-volatile memory.
∙ Renamed PSA_ALG_TLS12_PSK_TO_MS_MAX_PSK_LEN to PSA_TLS12_PSK_TO_MS_PSK_MAX_SIZE.
∙ Relax definition of implementation-defined types.
- This is indicated in the specification by /* implementation-defined type */ in the type definition.
- The specification only defines the name of implementation-defined types, and does not require
that the implementation is a C struct.
∙ Zero-length keys are not permitted. Attempting to create one will now result in an error.
IHI 0086
Page 324
1.1.2
Non-confidential
∙ Relax the constraints on inputs to key derivation:
- psa_key_derivation_input_bytes() can be used for secret input steps. This is necessary if a
zero-length input is required by the application.
- psa_key_derivation_input_key() can be used for non-secret input steps.
∙ Multi-part cipher operations now require that the IV is passed using psa_cipher_set_iv(), the option
to provide this as part of the input to psa_cipher_update() has been removed.
The format of the output from psa_cipher_encrypt(), and input to psa_cipher_decrypt(), is
documented.
∙ Support macros to calculate the size of output buffers, IVs and nonces.
- Macros to calculate a key and/or algorithm specific result are provided for all output buffers.
The new macros are:
∘ PSA_AEAD_NONCE_LENGTH()
∘ PSA_CIPHER_ENCRYPT_OUTPUT_SIZE()
∘ PSA_CIPHER_DECRYPT_OUTPUT_SIZE()
∘ PSA_CIPHER_UPDATE_OUTPUT_SIZE()
∘ PSA_CIPHER_FINISH_OUTPUT_SIZE()
∘ PSA_CIPHER_IV_LENGTH()
∘ PSA_EXPORT_PUBLIC_KEY_OUTPUT_SIZE()
∘ PSA_RAW_KEY_AGREEMENT_OUTPUT_SIZE()
- Macros that evaluate to a maximum type-independent buffer size are provided. The new
macros are:
∘ PSA_AEAD_ENCRYPT_OUTPUT_MAX_SIZE()
∘ PSA_AEAD_DECRYPT_OUTPUT_MAX_SIZE()
∘ PSA_AEAD_UPDATE_OUTPUT_MAX_SIZE()
∘ PSA_AEAD_FINISH_OUTPUT_MAX_SIZE
∘ PSA_AEAD_VERIFY_OUTPUT_MAX_SIZE
∘ PSA_AEAD_NONCE_MAX_SIZE
∘ PSA_AEAD_TAG_MAX_SIZE
∘ PSA_ASYMMETRIC_ENCRYPT_OUTPUT_MAX_SIZE
∘ PSA_ASYMMETRIC_DECRYPT_OUTPUT_MAX_SIZE
∘ PSA_CIPHER_ENCRYPT_OUTPUT_MAX_SIZE()
∘ PSA_CIPHER_DECRYPT_OUTPUT_MAX_SIZE()
∘ PSA_CIPHER_UPDATE_OUTPUT_MAX_SIZE()
∘ PSA_CIPHER_FINISH_OUTPUT_MAX_SIZE
∘ PSA_CIPHER_IV_MAX_SIZE
∘ PSA_EXPORT_KEY_PAIR_MAX_SIZE
∘ PSA_EXPORT_PUBLIC_KEY_MAX_SIZE
∘ PSA_RAW_KEY_AGREEMENT_OUTPUT_MAX_SIZE
- AEAD output buffer size macros are now parameterized on the key type as well as the
algorithm:
∘ PSA_AEAD_ENCRYPT_OUTPUT_SIZE()
∘ PSA_AEAD_DECRYPT_OUTPUT_SIZE()
IHI 0086
Page 325
1.1.2
Non-confidential
∘ PSA_AEAD_UPDATE_OUTPUT_SIZE()
∘ PSA_AEAD_FINISH_OUTPUT_SIZE()
∘ PSA_AEAD_TAG_LENGTH()
∘ PSA_AEAD_VERIFY_OUTPUT_SIZE()
- Some existing macros have been renamed to ensure that the name of the support macros are
consistent. The following macros have been renamed:
∘ PSA_ALG_AEAD_WITH_DEFAULT_TAG_LENGTH() → PSA_ALG_AEAD_WITH_DEFAULT_LENGTH_TAG()
∘ PSA_ALG_AEAD_WITH_TAG_LENGTH() → PSA_ALG_AEAD_WITH_SHORTENED_TAG()
∘ PSA_KEY_EXPORT_MAX_SIZE() → PSA_EXPORT_KEY_OUTPUT_SIZE()
∘ PSA_HASH_SIZE() → PSA_HASH_LENGTH()
∘ PSA_MAC_FINAL_SIZE() → PSA_MAC_LENGTH()
∘ PSA_BLOCK_CIPHER_BLOCK_SIZE() → PSA_BLOCK_CIPHER_BLOCK_LENGTH()
∘ PSA_MAX_BLOCK_CIPHER_BLOCK_SIZE → PSA_BLOCK_CIPHER_BLOCK_MAX_SIZE
- Documentation of the macros and of related APIs has been updated to reference the related
API elements.
∙ Provide hash-and-sign operations as well as sign-the-hash operations. The API for asymmetric
signature has been changed to clarify the use of the new functions.
- The existing asymmetric signature API has been renamed to clarify that this is for signing a hash
that is already computed:
∘ PSA_KEY_USAGE_SIGN → PSA_KEY_USAGE_SIGN_HASH
∘ PSA_KEY_USAGE_VERIFY → PSA_KEY_USAGE_VERIFY_HASH
∘ psa_asymmetric_sign() → psa_sign_hash()
∘ psa_asymmetric_verify() → psa_verify_hash()
- New APIs added to provide the complete message signing operation:
∘ PSA_KEY_USAGE_SIGN_MESSAGE
∘ PSA_KEY_USAGE_VERIFY_MESSAGE
∘ psa_sign_message()
∘ psa_verify_message()
- New Support macros to identify which algorithms can be used in which signing API:
∘ PSA_ALG_IS_SIGN_HASH()
∘ PSA_ALG_IS_SIGN_MESSAGE()
- Renamed support macros that apply to both signing APIs:
∘ PSA_ASYMMETRIC_SIGN_OUTPUT_SIZE() → PSA_SIGN_OUTPUT_SIZE()
∘ PSA_ASYMMETRIC_SIGNATURE_MAX_SIZE → PSA_SIGNATURE_MAX_SIZE
- The usage flag values have been changed, including for PSA_KEY_USAGE_DERIVE.
∙ Restructure psa_key_type_t and reassign all key type values.
- psa_key_type_t changes from 32-bit to 16-bit integer.
- Reassigned the key type categories.
- Add a parity bit to the key type to ensure that valid key type values differ by at least 2 bits.
- 16-bit elliptic curve ids (psa_ecc_curve_t) replaced by 8-bit ECC curve family ids
(psa_ecc_family_t). 16-bit Diffie-Hellman group ids (psa_dh_group_t) replaced by 8-bit DH group
family ids (psa_dh_family_t).
IHI 0086
Page 326
1.1.2
Non-confidential
∘ These ids are no longer related to the IANA Group Registry specification.
∘ The new key type values do not encode the key size for ECC curves or DH groups. The key
bit size from the key attributes identify a specific ECC curve or DH group within the family.
- The following macros have been removed:
∘ PSA_DH_GROUP_FFDHE2048
∘ PSA_DH_GROUP_FFDHE3072
∘ PSA_DH_GROUP_FFDHE4096
∘ PSA_DH_GROUP_FFDHE6144
∘ PSA_DH_GROUP_FFDHE8192
∘ PSA_ECC_CURVE_BITS
∘ PSA_ECC_CURVE_BRAINPOOL_P256R1
∘ PSA_ECC_CURVE_BRAINPOOL_P384R1
∘ PSA_ECC_CURVE_BRAINPOOL_P512R1
∘ PSA_ECC_CURVE_CURVE25519
∘ PSA_ECC_CURVE_CURVE448
∘ PSA_ECC_CURVE_SECP160K1
∘ PSA_ECC_CURVE_SECP160R1
∘ PSA_ECC_CURVE_SECP160R2
∘ PSA_ECC_CURVE_SECP192K1
∘ PSA_ECC_CURVE_SECP192R1
∘ PSA_ECC_CURVE_SECP224K1
∘ PSA_ECC_CURVE_SECP224R1
∘ PSA_ECC_CURVE_SECP256K1
∘ PSA_ECC_CURVE_SECP256R1
∘ PSA_ECC_CURVE_SECP384R1
∘ PSA_ECC_CURVE_SECP521R1
∘ PSA_ECC_CURVE_SECT163K1
∘ PSA_ECC_CURVE_SECT163R1
∘ PSA_ECC_CURVE_SECT163R2
∘ PSA_ECC_CURVE_SECT193R1
∘ PSA_ECC_CURVE_SECT193R2
∘ PSA_ECC_CURVE_SECT233K1
∘ PSA_ECC_CURVE_SECT233R1
∘ PSA_ECC_CURVE_SECT239K1
∘ PSA_ECC_CURVE_SECT283K1
∘ PSA_ECC_CURVE_SECT283R1
∘ PSA_ECC_CURVE_SECT409K1
∘ PSA_ECC_CURVE_SECT409R1
∘ PSA_ECC_CURVE_SECT571K1
∘ PSA_ECC_CURVE_SECT571R1
∘ PSA_KEY_TYPE_GET_CURVE
∘ PSA_KEY_TYPE_GET_GROUP
IHI 0086
Page 327
1.1.2
Non-confidential
- The following macros have been added:
∘ PSA_DH_FAMILY_RFC7919
∘ PSA_ECC_FAMILY_BRAINPOOL_P_R1
∘ PSA_ECC_FAMILY_SECP_K1
∘ PSA_ECC_FAMILY_SECP_R1
∘ PSA_ECC_FAMILY_SECP_R2
∘ PSA_ECC_FAMILY_SECT_K1
∘ PSA_ECC_FAMILY_SECT_R1
∘ PSA_ECC_FAMILY_SECT_R2
∘ PSA_ECC_FAMILY_MONTGOMERY
∘ PSA_KEY_TYPE_DH_GET_FAMILY
∘ PSA_KEY_TYPE_ECC_GET_FAMILY
- The following macros have new values:
∘ PSA_KEY_TYPE_AES
∘ PSA_KEY_TYPE_ARC4
∘ PSA_KEY_TYPE_CAMELLIA
∘ PSA_KEY_TYPE_CHACHA20
∘ PSA_KEY_TYPE_DERIVE
∘ PSA_KEY_TYPE_DES
∘ PSA_KEY_TYPE_HMAC
∘ PSA_KEY_TYPE_NONE
∘ PSA_KEY_TYPE_RAW_DATA
∘ PSA_KEY_TYPE_RSA_KEY_PAIR
∘ PSA_KEY_TYPE_RSA_PUBLIC_KEY
- The following macros with specification-defined values have new example implementations:
∘ PSA_BLOCK_CIPHER_BLOCK_LENGTH
∘ PSA_KEY_TYPE_DH_KEY_PAIR
∘ PSA_KEY_TYPE_DH_PUBLIC_KEY
∘ PSA_KEY_TYPE_ECC_KEY_PAIR
∘ PSA_KEY_TYPE_ECC_PUBLIC_KEY
∘ PSA_KEY_TYPE_IS_ASYMMETRIC
∘ PSA_KEY_TYPE_IS_DH
∘ PSA_KEY_TYPE_IS_DH_KEY_PAIR
∘ PSA_KEY_TYPE_IS_DH_PUBLIC_KEY
∘ PSA_KEY_TYPE_IS_ECC
∘ PSA_KEY_TYPE_IS_ECC_KEY_PAIR
∘ PSA_KEY_TYPE_IS_ECC_PUBLIC_KEY
∘ PSA_KEY_TYPE_IS_KEY_PAIR
∘ PSA_KEY_TYPE_IS_PUBLIC_KEY
∘ PSA_KEY_TYPE_IS_RSA
∘ PSA_KEY_TYPE_IS_UNSTRUCTURED
∘ PSA_KEY_TYPE_KEY_PAIR_OF_PUBLIC_KEY
IHI 0086
Page 328
1.1.2
Non-confidential
∘ PSA_KEY_TYPE_PUBLIC_KEY_OF_KEY_PAIR
∙ Add ECC family PSA_ECC_FAMILY_FRP for the FRP256v1 curve.
∙ Restructure psa_algorithm_t encoding, to increase consistency across algorithm categories.
- Algorithms that include a hash operation all use the same structure to encode the hash
algorithm. The following PSA_ALG_XXXX_GET_HASH() macros have all been replaced by a single
macro PSA_ALG_GET_HASH():
∘ PSA_ALG_HKDF_GET_HASH()
∘ PSA_ALG_HMAC_GET_HASH()
∘ PSA_ALG_RSA_OAEP_GET_HASH()
∘ PSA_ALG_SIGN_GET_HASH()
∘ PSA_ALG_TLS12_PRF_GET_HASH()
∘ PSA_ALG_TLS12_PSK_TO_MS_GET_HASH()
- Stream cipher algorithm macros have been removed; the key type indicates which cipher to use.
Instead of PSA_ALG_ARC4 and PSA_ALG_CHACHA20, use PSA_ALG_STREAM_CIPHER.
All of the other PSA_ALG_XXX macros have updated values or updated example implementations.
- The following macros have new values:
∘ PSA_ALG_ANY_HASH
∘ PSA_ALG_CBC_MAC
∘ PSA_ALG_CBC_NO_PADDING
∘ PSA_ALG_CBC_PKCS7
∘ PSA_ALG_CCM
∘ PSA_ALG_CFB
∘ PSA_ALG_CHACHA20_POLY1305
∘ PSA_ALG_CMAC
∘ PSA_ALG_CTR
∘ PSA_ALG_ECDH
∘ PSA_ALG_ECDSA_ANY
∘ PSA_ALG_FFDH
∘ PSA_ALG_GCM
∘ PSA_ALG_MD2
∘ PSA_ALG_MD4
∘ PSA_ALG_MD5
∘ PSA_ALG_OFB
∘ PSA_ALG_RIPEMD160
∘ PSA_ALG_RSA_PKCS1V15_CRYPT
∘ PSA_ALG_RSA_PKCS1V15_SIGN_RAW
∘ PSA_ALG_SHA_1
∘ PSA_ALG_SHA_224
∘ PSA_ALG_SHA_256
∘ PSA_ALG_SHA_384
∘ PSA_ALG_SHA_512
IHI 0086
Page 329
1.1.2
Non-confidential
∘ PSA_ALG_SHA_512_224
∘ PSA_ALG_SHA_512_256
∘ PSA_ALG_SHA3_224
∘ PSA_ALG_SHA3_256
∘ PSA_ALG_SHA3_384
∘ PSA_ALG_SHA3_512
∘ PSA_ALG_XTS
- The following macros with specification-defined values have new example implementations:
∘ PSA_ALG_AEAD_WITH_DEFAULT_LENGTH_TAG()
∘ PSA_ALG_AEAD_WITH_SHORTENED_TAG()
∘ PSA_ALG_DETERMINISTIC_ECDSA()
∘ PSA_ALG_ECDSA()
∘ PSA_ALG_FULL_LENGTH_MAC()
∘ PSA_ALG_HKDF()
∘ PSA_ALG_HMAC()
∘ PSA_ALG_IS_AEAD()
∘ PSA_ALG_IS_AEAD_ON_BLOCK_CIPHER()
∘ PSA_ALG_IS_ASYMMETRIC_ENCRYPTION()
∘ PSA_ALG_IS_BLOCK_CIPHER_MAC()
∘ PSA_ALG_IS_CIPHER()
∘ PSA_ALG_IS_DETERMINISTIC_ECDSA()
∘ PSA_ALG_IS_ECDH()
∘ PSA_ALG_IS_ECDSA()
∘ PSA_ALG_IS_FFDH()
∘ PSA_ALG_IS_HASH()
∘ PSA_ALG_IS_HASH_AND_SIGN()
∘ PSA_ALG_IS_HKDF()
∘ PSA_ALG_IS_HMAC()
∘ PSA_ALG_IS_KEY_AGREEMENT()
∘ PSA_ALG_IS_KEY_DERIVATION()
∘ PSA_ALG_IS_MAC()
∘ PSA_ALG_IS_RANDOMIZED_ECDSA()
∘ PSA_ALG_IS_RAW_KEY_AGREEMENT()
∘ PSA_ALG_IS_RSA_OAEP()
∘ PSA_ALG_IS_RSA_PKCS1V15_SIGN()
∘ PSA_ALG_IS_RSA_PSS()
∘ PSA_ALG_IS_SIGN()
∘ PSA_ALG_IS_SIGN_MESSAGE()
∘ PSA_ALG_IS_STREAM_CIPHER()
∘ PSA_ALG_IS_TLS12_PRF()
∘ PSA_ALG_IS_TLS12_PSK_TO_MS()
∘ PSA_ALG_IS_WILDCARD()
IHI 0086
Page 330
1.1.2
Non-confidential
∘ PSA_ALG_KEY_AGREEMENT()
∘ PSA_ALG_KEY_AGREEMENT_GET_BASE()
∘ PSA_ALG_KEY_AGREEMENT_GET_KDF()
∘ PSA_ALG_RSA_OAEP()
∘ PSA_ALG_RSA_PKCS1V15_SIGN()
∘ PSA_ALG_RSA_PSS()
∘ PSA_ALG_TLS12_PRF()
∘ PSA_ALG_TLS12_PSK_TO_MS()
∘ PSA_ALG_TRUNCATED_MAC()
∙ Added ECB block cipher mode, with no padding, as PSA_ALG_ECB_NO_PADDING.
∙ Add functions to suspend and resume hash operations:
- psa_hash_suspend() halts the current operation and outputs a hash suspend state.
- psa_hash_resume() continues a previously suspended hash operation.
The format of the hash suspend state is documented in Hash suspend state on page 131, and
supporting macros are provided for using the Crypto API:
- PSA_HASH_SUSPEND_OUTPUT_SIZE()
- PSA_HASH_SUSPEND_OUTPUT_MAX_SIZE
- PSA_HASH_SUSPEND_ALGORITHM_FIELD_LENGTH
- PSA_HASH_SUSPEND_INPUT_LENGTH_FIELD_LENGTH()
- PSA_HASH_SUSPEND_HASH_STATE_FIELD_LENGTH()
- PSA_HASH_BLOCK_LENGTH()
∙ Complement PSA_ERROR_STORAGE_FAILURE with new error codes PSA_ERROR_DATA_CORRUPT and
PSA_ERROR_DATA_INVALID. These permit an implementation to distinguish different causes of failure
when reading from key storage.
∙ Added input step PSA_KEY_DERIVATION_INPUT_CONTEXT for key derivation, supporting obvious mapping
from the step identifiers to common KDF constructions.
Clarifications
∙ Clarified rules regarding modification of parameters in concurrent environments.
∙ Guarantee that psa_destroy_key(PSA_KEY_ID_NULL) always returns PSA_SUCCESS.
∙ Clarified the TLS PSK to MS key agreement algorithm.
∙ Document the key policy requirements for all APIs that accept a key parameter.
∙ Document more of the error codes for each function.
IHI 0086
Page 331
1.1.2
Non-confidential
Other changes
∙ Require C99 for this specification instead of C89.
∙ Removed references to non-standard mbed-crypto header files. The only header file that
applications need to include is psa/crypto.h.
∙ Reorganized the API reference, grouping the elements in a more natural way.
∙ Improved the cross referencing between all of the document sections, and from code snippets to API
element descriptions.
E.1.6 Changes between 1.0 beta 2 and 1.0 beta 3
Changes to the API
∙ Change the value of error codes, and some names, to align with other PSA Certified APIs. The name
changes are:
- PSA_ERROR_UNKNOWN_ERROR → PSA_ERROR_GENERIC_ERROR
- PSA_ERROR_OCCUPIED_SLOT → PSA_ERROR_ALREADY_EXISTS
- PSA_ERROR_EMPTY_SLOT → PSA_ERROR_DOES_NOT_EXIST
- PSA_ERROR_INSUFFICIENT_CAPACITY → PSA_ERROR_INSUFFICIENT_DATA
- PSA_ERROR_TAMPERING_DETECTED → PSA_ERROR_CORRUPTION_DETECTED
∙ Change the way keys are created to avoid “half-filled” handles that contained key metadata, but no
key material. Now, to create a key, first fill in a data structure containing its attributes, then pass this
structure to a function that both allocates resources for the key and fills in the key material. This
affects the following functions:
- psa_import_key(), psa_generate_key(), psa_generator_import_key() and psa_copy_key() now take
an attribute structure, as a pointer to psa_key_attributes_t, to specify key metadata. This
replaces the previous method of passing arguments to psa_create_key() or to the key material
creation function or calling psa_set_key_policy().
- psa_key_policy_t and functions operating on that type no longer exist. A key’s policy is now
accessible as part of its attributes.
- psa_get_key_information() is also replaced by accessing the key’s attributes, retrieved with
psa_get_key_attributes().
- psa_create_key() no longer exists. Instead, set the key id attribute and the lifetime attribute
before creating the key material.
∙ Allow psa_aead_update() to buffer data.
∙ New buffer size calculation macros.
∙ Key identifiers are no longer specific to a given lifetime value. psa_open_key() no longer takes a
lifetime parameter.
∙ Define a range of key identifiers for use by applications and a separate range for use by
implementations.
∙ Avoid the unusual terminology “generator”: call them “key derivation operations” instead. Rename a
number of functions and other identifiers related to for clarity and consistency:
- psa_crypto_generator_t → psa_key_derivation_operation_t
IHI 0086
Page 332
1.1.2
Non-confidential
- PSA_CRYPTO_GENERATOR_INIT → PSA_KEY_DERIVATION_OPERATION_INIT
- psa_crypto_generator_init() → psa_key_derivation_operation_init()
- PSA_GENERATOR_UNBRIDLED_CAPACITY → PSA_KEY_DERIVATION_UNLIMITED_CAPACITY
- psa_set_generator_capacity() → psa_key_derivation_set_capacity()
- psa_get_generator_capacity() → psa_key_derivation_get_capacity()
- psa_key_agreement() → psa_key_derivation_key_agreement()
- psa_generator_read() → psa_key_derivation_output_bytes()
- psa_generate_derived_key() → psa_key_derivation_output_key()
- psa_generator_abort() → psa_key_derivation_abort()
- psa_key_agreement_raw_shared_secret() → psa_raw_key_agreement()
- PSA_KDF_STEP_xxx → PSA_KEY_DERIVATION_INPUT_xxx
- PSA_xxx_KEYPAIR → PSA_xxx_KEY_PAIR
∙ Convert TLS1.2 KDF descriptions to multi-part key derivation.
Clarifications
∙ Specify psa_generator_import_key() for most key types.
∙ Clarify the behavior in various corner cases.
∙ Document more error conditions.
E.1.7 Changes between 1.0 beta 1 and 1.0 beta 2
Changes to the API
∙ Remove obsolete definition PSA_ALG_IS_KEY_SELECTION.
∙ PSA_AEAD_FINISH_OUTPUT_SIZE: remove spurious parameter plaintext_length.
Clarifications
∙ psa_key_agreement(): document alg parameter.
Other changes
∙ Document formatting improvements.
E.2 Planned changes for version 1.1.x
Future versions of this specification that use a 1.1.x version will describe the same API as this
specification. Any changes will not affect application compatibility and will not introduce major features.
These updates are intended to add minor requirements on implementations, introduce optional definitions,
make corrections, clarify potential or actual ambiguities, or improve the documentation.
These are the changes that might be included in a version 1.1.x:
∙ Declare identifiers for additional cryptographic algorithms.
∙ Mandate certain checks when importing some types of asymmetric keys.
IHI 0086
Page 333
1.1.2
Non-confidential
∙ Specify the computation of algorithm and key type values.
∙ Further clarifications on API usage and implementation.
E.3 Future additions
Major additions to the API will be defined in future drafts and editions of a 1.x or 2.x version of this
specification. Features that are being considered include:
∙ Multi-part operations for hybrid cryptography. For example, this includes hash-and-sign for EdDSA,
and hybrid encryption for ECIES.
∙ Key wrapping mechanisms to extract and import keys in an encrypted and authenticated form.
∙ Key discovery mechanisms. This would enable an application to locate a key by its name or attributes.
∙ Implementation capability description. This would enable an application to determine the algorithms,
key types and storage lifetimes that the implementation provides.
∙ An ownership and access control mechanism allowing a multi-client implementation to have
privileged clients that are able to manage keys of other clients.
IHI 0086
Page 334
1.1.2
Non-confidential
Index of API elements
PSA_A
PSA_ALG_HKDF, 206
PSA_ALG_HKDF_EXPAND, 208
PSA_AEAD_DECRYPT_OUTPUT_MAX_SIZE, 201
PSA_ALG_HKDF_EXTRACT, 207
PSA_AEAD_DECRYPT_OUTPUT_SIZE, 200
PSA_ALG_HMAC, 134
PSA_AEAD_ENCRYPT_OUTPUT_MAX_SIZE, 200
PSA_ALG_IS_AEAD, 110
PSA_AEAD_ENCRYPT_OUTPUT_SIZE, 199
PSA_ALG_IS_AEAD_ON_BLOCK_CIPHER, 199
PSA_AEAD_FINISH_OUTPUT_MAX_SIZE, 203
PSA_ALG_IS_ASYMMETRIC_ENCRYPTION, 110
PSA_AEAD_FINISH_OUTPUT_SIZE, 203
PSA_ALG_IS_BLOCK_CIPHER_MAC, 148
PSA_AEAD_NONCE_LENGTH, 201
PSA_ALG_IS_CIPHER, 109
PSA_AEAD_NONCE_MAX_SIZE, 202
PSA_ALG_IS_DETERMINISTIC_ECDSA, 252
PSA_AEAD_OPERATION_INIT, 185
PSA_ALG_IS_ECDH, 271
PSA_AEAD_TAG_LENGTH, 204
PSA_ALG_IS_ECDSA, 252
PSA_AEAD_TAG_MAX_SIZE, 204
PSA_ALG_IS_FFDH, 270
PSA_AEAD_UPDATE_OUTPUT_MAX_SIZE, 203
PSA_ALG_IS_HASH, 108
PSA_AEAD_UPDATE_OUTPUT_SIZE, 202
PSA_ALG_IS_HASH_AND_SIGN, 253
PSA_AEAD_VERIFY_OUTPUT_MAX_SIZE, 205
PSA_ALG_IS_HASH_EDDSA, 253
PSA_AEAD_VERIFY_OUTPUT_SIZE, 204
PSA_ALG_IS_HKDF, 232
PSA_ALG_AEAD_WITH_AT_LEAST_THIS_LENGTH_TAG, 179
PSA_ALG_IS_HKDF_EXPAND, 232
PSA_ALG_AEAD_WITH_DEFAULT_LENGTH_TAG, 178
PSA_ALG_IS_HKDF_EXTRACT, 232
PSA_ALG_AEAD_WITH_SHORTENED_TAG, 178
PSA_ALG_IS_HMAC, 147
PSA_ALG_ANY_HASH, 254
PSA_ALG_IS_KEY_AGREEMENT, 111
PSA_ALG_AT_LEAST_THIS_LENGTH_MAC, 137
PSA_ALG_IS_KEY_DERIVATION, 111
PSA_ALG_CBC_MAC, 134
PSA_ALG_IS_KEY_DERIVATION_STRETCHING, 231
PSA_ALG_CBC_NO_PADDING, 155
PSA_ALG_IS_MAC, 109
PSA_ALG_CBC_PKCS7, 155
PSA_ALG_IS_PBKDF2_HMAC, 233
PSA_ALG_CCM, 176
PSA_ALG_IS_RANDOMIZED_ECDSA, 253
PSA_ALG_CFB, 152
PSA_ALG_IS_RAW_KEY_AGREEMENT, 270
PSA_ALG_CHACHA20_POLY1305, 177
PSA_ALG_IS_RSA_OAEP, 261
PSA_ALG_CMAC, 135
PSA_ALG_IS_RSA_PKCS1V15_SIGN, 250
PSA_ALG_CTR, 151
PSA_ALG_IS_RSA_PSS, 251
PSA_ALG_DETERMINISTIC_ECDSA, 240
PSA_ALG_IS_RSA_PSS_ANY_SALT, 251
PSA_ALG_ECB_NO_PADDING, 154
PSA_ALG_IS_RSA_PSS_STANDARD_SALT, 252
PSA_ALG_ECDH, 264
PSA_ALG_IS_SIGN, 110
PSA_ALG_ECDSA, 238
PSA_ALG_IS_SIGN_HASH, 250
PSA_ALG_ECDSA_ANY, 239
PSA_ALG_IS_SIGN_MESSAGE, 250
PSA_ALG_ED25519PH, 241
PSA_ALG_IS_STREAM_CIPHER, 169
PSA_ALG_ED448PH, 242
PSA_ALG_IS_TLS12_PRF, 233
PSA_ALG_FFDH, 263
PSA_ALG_IS_TLS12_PSK_TO_MS, 233
PSA_ALG_FULL_LENGTH_MAC, 136
PSA_ALG_IS_WILDCARD, 111
PSA_ALG_GCM, 177
PSA_ALG_KEY_AGREEMENT, 265
PSA_ALG_GET_HASH, 112
IHI 0086
Page 335
1.1.2
Non-confidential
PSA_ALG_KEY_AGREEMENT_GET_BASE, 269
psa_aead_set_lengths, 188
PSA_ALG_KEY_AGREEMENT_GET_KDF, 269
psa_aead_set_nonce, 190
PSA_ALG_MD2, 113
psa_aead_update, 193
PSA_ALG_MD4, 113
psa_aead_update_ad, 192
PSA_ALG_MD5, 114
psa_aead_verify, 197
PSA_ALG_NONE, 108
psa_algorithm_t, 108
PSA_ALG_OFB, 153
psa_asymmetric_decrypt, 259
PSA_ALG_PBKDF2_AES_CMAC_PRF_128, 213
psa_asymmetric_encrypt, 257
PSA_ALG_PBKDF2_HMAC, 212
PSA_B
PSA_ALG_PURE_EDDSA, 241
PSA_ALG_RIPEMD160, 114
PSA_BLOCK_CIPHER_BLOCK_LENGTH, 174
PSA_ALG_RSA_OAEP, 256
PSA_BLOCK_CIPHER_BLOCK_MAX_SIZE, 174
PSA_ALG_RSA_PKCS1V15_CRYPT, 256
PSA_C
PSA_ALG_RSA_PKCS1V15_SIGN, 235
PSA_ALG_RSA_PKCS1V15_SIGN_RAW, 235
PSA_CIPHER_DECRYPT_OUTPUT_MAX_SIZE, 171
PSA_ALG_RSA_PSS, 236
PSA_CIPHER_DECRYPT_OUTPUT_SIZE, 170
PSA_ALG_RSA_PSS_ANY_SALT, 237
PSA_CIPHER_ENCRYPT_OUTPUT_MAX_SIZE, 170
PSA_ALG_SHA3_224, 115
PSA_CIPHER_ENCRYPT_OUTPUT_SIZE, 169
PSA_ALG_SHA3_256, 116
PSA_CIPHER_FINISH_OUTPUT_MAX_SIZE, 174
PSA_ALG_SHA3_384, 116
PSA_CIPHER_FINISH_OUTPUT_SIZE, 173
PSA_ALG_SHA3_512, 116
PSA_CIPHER_IV_LENGTH, 171
PSA_ALG_SHAKE256_512, 116
PSA_CIPHER_IV_MAX_SIZE, 172
PSA_ALG_SHA_1, 114
PSA_CIPHER_OPERATION_INIT, 160
PSA_ALG_SHA_224, 114
PSA_CIPHER_UPDATE_OUTPUT_MAX_SIZE, 173
PSA_ALG_SHA_256, 115
PSA_CIPHER_UPDATE_OUTPUT_SIZE, 172
PSA_ALG_SHA_384, 115
PSA_CRYPTO_API_VERSION_MAJOR, 44
PSA_ALG_SHA_512, 115
PSA_CRYPTO_API_VERSION_MINOR, 44
PSA_ALG_SHA_512_224, 115
psa_cipher_abort, 168
PSA_ALG_SHA_512_256, 115
psa_cipher_decrypt, 158
PSA_ALG_SM3, 116
psa_cipher_decrypt_setup, 162
PSA_ALG_STREAM_CIPHER, 150
psa_cipher_encrypt, 156
PSA_ALG_TLS12_PRF, 209
psa_cipher_encrypt_setup, 160
PSA_ALG_TLS12_PSK_TO_MS, 210
psa_cipher_finish, 167
PSA_ALG_TRUNCATED_MAC, 135
psa_cipher_generate_iv, 163
PSA_ALG_XTS, 153
psa_cipher_operation_init, 160
PSA_ASYMMETRIC_DECRYPT_OUTPUT_MAX_SIZE, 262
psa_cipher_operation_t, 159
PSA_ASYMMETRIC_DECRYPT_OUTPUT_SIZE, 262
psa_cipher_set_iv, 164
PSA_ASYMMETRIC_ENCRYPT_OUTPUT_MAX_SIZE, 262
psa_cipher_update, 166
PSA_ASYMMETRIC_ENCRYPT_OUTPUT_SIZE, 261
psa_copy_key, 94
psa_aead_abort, 198
psa_crypto_init, 44
psa_aead_decrypt, 182
PSA_D
psa_aead_decrypt_setup, 187
psa_aead_encrypt, 180
PSA_DH_FAMILY_RFC7919, 68
psa_aead_encrypt_setup, 185
psa_destroy_key, 96
psa_aead_finish, 195
psa_dh_family_t, 67
psa_aead_generate_nonce, 189
psa_aead_operation_init, 185
PSA_E
psa_aead_operation_t, 184
PSA_ECC_FAMILY_BRAINPOOL_P_R1, 64
IHI 0086
Page 336
1.1.2
Non-confidential
PSA_ECC_FAMILY_FRP, 65
psa_hash_setup, 120
PSA_ECC_FAMILY_MONTGOMERY, 65
psa_hash_suspend, 124
PSA_ECC_FAMILY_SECP_K1, 61
psa_hash_update, 121
PSA_ECC_FAMILY_SECP_R1, 61
psa_hash_verify, 123
PSA_ECC_FAMILY_SECP_R2, 62
PSA_I
PSA_ECC_FAMILY_SECT_K1, 62
PSA_ECC_FAMILY_SECT_R1, 63
psa_import_key, 91
PSA_ECC_FAMILY_SECT_R2, 64
PSA_K
PSA_ECC_FAMILY_TWISTED_EDWARDS, 66
PSA_ERROR_INSUFFICIENT_ENTROPY, 43
PSA_KEY_ATTRIBUTES_INIT, 49
PSA_ERROR_INVALID_PADDING, 44
PSA_KEY_DERIVATION_INPUT_CONTEXT, 214
PSA_EXPORT_KEY_OUTPUT_SIZE, 101
PSA_KEY_DERIVATION_INPUT_COST, 215
PSA_EXPORT_KEY_PAIR_MAX_SIZE, 103
PSA_KEY_DERIVATION_INPUT_INFO, 214
PSA_EXPORT_PUBLIC_KEY_MAX_SIZE, 103
PSA_KEY_DERIVATION_INPUT_LABEL, 214
PSA_EXPORT_PUBLIC_KEY_OUTPUT_SIZE, 102
PSA_KEY_DERIVATION_INPUT_OTHER_SECRET, 213
psa_ecc_family_t, 60
PSA_KEY_DERIVATION_INPUT_PASSWORD, 214
psa_export_key, 98
PSA_KEY_DERIVATION_INPUT_SALT, 214
psa_export_public_key, 100
PSA_KEY_DERIVATION_INPUT_SECRET, 213
PSA_KEY_DERIVATION_INPUT_SEED, 215
PSA_G
PSA_KEY_DERIVATION_OPERATION_INIT, 216
psa_generate_key, 93
PSA_KEY_DERIVATION_UNLIMITED_CAPACITY, 234
psa_generate_random, 272
PSA_KEY_ID_NULL, 81
psa_get_key_algorithm, 84
PSA_KEY_ID_USER_MAX, 81
psa_get_key_attributes, 49
PSA_KEY_ID_USER_MIN, 81
psa_get_key_bits, 71
PSA_KEY_ID_VENDOR_MAX, 82
psa_get_key_id, 83
PSA_KEY_ID_VENDOR_MIN, 82
psa_get_key_lifetime, 79
PSA_KEY_LIFETIME_FROM_PERSISTENCE_AND_LOCATION, 80
psa_get_key_type, 71
PSA_KEY_LIFETIME_GET_LOCATION, 79
psa_get_key_usage_flags, 90
PSA_KEY_LIFETIME_GET_PERSISTENCE, 79
PSA_KEY_LIFETIME_IS_VOLATILE, 80
PSA_H
PSA_KEY_LIFETIME_PERSISTENT, 77
PSA_HASH_BLOCK_LENGTH, 130
PSA_KEY_LIFETIME_VOLATILE, 76
PSA_HASH_LENGTH, 128
PSA_KEY_LOCATION_LOCAL_STORAGE, 77
PSA_HASH_MAX_SIZE, 128
PSA_KEY_LOCATION_PRIMARY_SECURE_ELEMENT, 78
PSA_HASH_OPERATION_INIT, 119
PSA_KEY_PERSISTENCE_DEFAULT, 77
PSA_HASH_SUSPEND_ALGORITHM_FIELD_LENGTH, 129
PSA_KEY_PERSISTENCE_READ_ONLY, 77
PSA_HASH_SUSPEND_HASH_STATE_FIELD_LENGTH, 130
PSA_KEY_PERSISTENCE_VOLATILE, 77
PSA_HASH_SUSPEND_INPUT_LENGTH_FIELD_LENGTH, 129
PSA_KEY_TYPE_AES, 54
PSA_HASH_SUSPEND_OUTPUT_MAX_SIZE, 129
PSA_KEY_TYPE_ARC4, 58
PSA_HASH_SUSPEND_OUTPUT_SIZE, 128
PSA_KEY_TYPE_ARIA, 55
psa_hash_abort, 124
PSA_KEY_TYPE_CAMELLIA, 57
psa_hash_clone, 127
PSA_KEY_TYPE_CHACHA20, 58
psa_hash_compare, 118
PSA_KEY_TYPE_DERIVE, 53
psa_hash_compute, 117
PSA_KEY_TYPE_DES, 56
psa_hash_finish, 121
PSA_KEY_TYPE_DH_GET_FAMILY, 70
psa_hash_operation_init, 119
PSA_KEY_TYPE_DH_KEY_PAIR, 67
psa_hash_operation_t, 119
PSA_KEY_TYPE_DH_PUBLIC_KEY, 68
psa_hash_resume, 126
PSA_KEY_TYPE_ECC_GET_FAMILY, 67
IHI 0086
Page 337
1.1.2
Non-confidential
PSA_KEY_TYPE_ECC_KEY_PAIR, 60
psa_key_derivation_setup, 216
PSA_KEY_TYPE_ECC_PUBLIC_KEY, 61
psa_key_derivation_step_t, 213
PSA_KEY_TYPE_HMAC, 52
psa_key_derivation_verify_bytes, 228
PSA_KEY_TYPE_IS_ASYMMETRIC, 51
psa_key_derivation_verify_key, 229
PSA_KEY_TYPE_IS_DH, 69
psa_key_id_t, 81
PSA_KEY_TYPE_IS_DH_KEY_PAIR, 69
psa_key_lifetime_t, 73
PSA_KEY_TYPE_IS_DH_PUBLIC_KEY, 69
psa_key_location_t, 75
PSA_KEY_TYPE_IS_ECC, 66
psa_key_persistence_t, 74
PSA_KEY_TYPE_IS_ECC_KEY_PAIR, 66
psa_key_type_t, 50
PSA_KEY_TYPE_IS_ECC_PUBLIC_KEY, 66
psa_key_usage_t, 85
PSA_KEY_TYPE_IS_KEY_PAIR, 52
PSA_M
PSA_KEY_TYPE_IS_PUBLIC_KEY, 51
PSA_KEY_TYPE_IS_RSA, 60
PSA_MAC_LENGTH, 148
PSA_KEY_TYPE_IS_UNSTRUCTURED, 51
PSA_MAC_MAX_SIZE, 149
PSA_KEY_TYPE_KEY_PAIR_OF_PUBLIC_KEY, 68
PSA_MAC_OPERATION_INIT, 141
PSA_KEY_TYPE_NONE, 51
psa_mac_abort, 147
PSA_KEY_TYPE_PASSWORD, 53
psa_mac_compute, 137
PSA_KEY_TYPE_PASSWORD_HASH, 54
psa_mac_operation_init, 141
PSA_KEY_TYPE_PEPPER, 54
psa_mac_operation_t, 140
PSA_KEY_TYPE_PUBLIC_KEY_OF_KEY_PAIR, 69
psa_mac_sign_finish, 145
PSA_KEY_TYPE_RAW_DATA, 52
psa_mac_sign_setup, 141
PSA_KEY_TYPE_RSA_KEY_PAIR, 59
psa_mac_update, 144
PSA_KEY_TYPE_RSA_PUBLIC_KEY, 59
psa_mac_verify, 139
PSA_KEY_TYPE_SM4, 57
psa_mac_verify_finish, 146
PSA_KEY_USAGE_CACHE, 86
psa_mac_verify_setup, 142
PSA_KEY_USAGE_COPY, 86
PSA_P
PSA_KEY_USAGE_DECRYPT, 87
PSA_KEY_USAGE_DERIVE, 89
psa_purge_key, 98
PSA_KEY_USAGE_ENCRYPT, 86
PSA_R
PSA_KEY_USAGE_EXPORT, 85
PSA_KEY_USAGE_SIGN_HASH, 88
PSA_RAW_KEY_AGREEMENT_OUTPUT_MAX_SIZE, 272
PSA_RAW_KEY_AGREEMENT_OUTPUT_SIZE, 271
PSA_KEY_USAGE_SIGN_MESSAGE, 87
PSA_KEY_USAGE_VERIFY_DERIVATION, 89
psa_raw_key_agreement, 266
PSA_KEY_USAGE_VERIFY_HASH, 88
psa_reset_key_attributes, 50
PSA_KEY_USAGE_VERIFY_MESSAGE, 88
PSA_S
psa_key_attributes_init, 49
PSA_SIGNATURE_MAX_SIZE, 256
psa_key_attributes_t, 46
PSA_SIGN_OUTPUT_SIZE, 255
psa_key_derivation_abort, 231
psa_set_key_algorithm, 84
psa_key_derivation_get_capacity, 217
psa_set_key_bits, 71
psa_key_derivation_input_bytes, 219
psa_set_key_id, 82
psa_key_derivation_input_integer, 220
psa_set_key_lifetime, 78
psa_key_derivation_input_key, 221
psa_set_key_type, 70
psa_key_derivation_key_agreement, 267
psa_set_key_usage_flags, 89
psa_key_derivation_operation_init, 216
psa_sign_hash, 246
psa_key_derivation_operation_t, 215
psa_sign_message, 243
psa_key_derivation_output_bytes, 223
psa_key_derivation_output_key, 224
PSA_T
psa_key_derivation_set_capacity, 218
PSA_TLS12_PSK_TO_MS_PSK_MAX_SIZE, 234
IHI 0086
Page 338
1.1.2
Non-confidential
PSA_V
psa_verify_hash, 248
psa_verify_message, 245
IHI 0086
Page 339
1.1.2
Non-confidential