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
February 2022	Beta 0	Non-confidential	Initial release of the 1.1 PAKE Extension specification
October 2022	Beta 1	Non-confidential	Relicensed as open source under CC BY-SA 4.0.
February 2024	Final	Non-confidential	Add support for the SPAKE2+ protocol. Rework the API to support augmented PAKE protocols, improve ease of use and implementation. API status is now Final/Release.
March 2024	Final 1	Non-confidential	Clarifications and fixes

The detailed changes in each release are described in Document change history.

PSA Certified Crypto API

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:

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”).
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.

References¶

This document refers to the following documents.

Table 2 Documents referenced by this document¶
Ref	Document Number	Title
[PSA-CRYPT]	IHI 0086	PSA Certified Crypto API. arm-software.github.io/psa-api/crypto
[MATTER]		CSA, Matter Specification, Version 1.2, October 2023. csa-iot.org/all-solutions/matter/
[RFC8235]		IETF, Schnorr Non-interactive Zero-Knowledge Proof, September 2017. tools.ietf.org/html/rfc8235.html
[RFC8236]		IETF, J-PAKE: Password-Authenticated Key Exchange by Juggling, September 2017. tools.ietf.org/html/rfc8236.html
[RFC9383]		IETF, SPAKE2+, an Augmented Password-Authenticated Key Exchange (PAKE) Protocol, September 2023. tools.ietf.org/html/rfc9383.html
[SEC1]		Standards for Efficient Cryptography, SEC 1: Elliptic Curve Cryptography, May 2009. www.secg.org/sec1-v2.pdf
[SPAKE2P-2]		IETF, SPAKE2+, an Augmented PAKE (Draft 02), December 2020. datatracker.ietf.org/doc/draft-bar-cfrg-spake2plus-02
[THREAD]		Thread Group, Thread Specification 1.3.0, July 2022. www.threadgroup.org/ThreadSpec

Terms and abbreviations¶

This document uses the following terms and abbreviations.

Table 3 Terms and abbreviations¶
Term	Meaning
AEAD	See Authenticated Encryption with Associated Data.
Algorithm	A finite sequence of steps to perform a particular operation. In this specification, an algorithm is a cipher or a related function. Other texts call this a cryptographic mechanism.
API	Application Programming Interface.
Asymmetric	See Public-key cryptography.
Authenticated Encryption with Associated Data (AEAD)	A type of encryption that provides confidentiality and authenticity of data using symmetric keys.
Byte	In this specification, a unit of storage comprising eight bits, also called an octet.
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.
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.
IV	See Initialization vector.
KDF	See Key Derivation Function.
Key agreement	An algorithm for two or more parties to establish a common secret key.
Key Derivation Function (KDF)	Key Derivation Function. An algorithm for deriving keys from secret material.
Key identifier	A reference to a cryptographic key. Key identifiers in the Crypto API are 32-bit integers.
Key policy	Key metadata that describes and restricts what a key can be used for.
Key size	The size of a key as defined by common conventions for each key type. For keys that are built from several numbers of strings, this is the size of a particular one of these numbers or strings. This specification expresses key sizes in bits.
Key type	Key metadata that describes the structure and content of a key.
Keystore	A hardware or software component that protects, stores, and manages cryptographic keys.
Lifetime	Key metadata that describes when a key is destroyed.
MAC	See Message Authentication Code.
Message Authentication Code (MAC)	A short piece of information used to authenticate a message. It is created and verified using a symmetric key.
Message digest	A hash of a message. Used to determine if a message has been tampered.
Multi-part operation	An API which splits a single cryptographic operation into a sequence of separate steps.
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.
PAKE	See Password-authenticated key exchange.
Password-authenticated key exchange (PAKE)	An interactive method for two or more parties to establish cryptographic keys based on knowledge of a low entropy secret, such as a password. This can provide strong security for communication from a weak password, because the password is not directly communicated as part of the key exchange.
Persistent key	A key that is stored in protected non-volatile memory.
PSA	Platform Security Architecture
Public-key cryptography	A type of cryptographic system that uses key pairs. A keypair consists of a (secret) private key and a public key (not secret). A public key cryptographic algorithm can be used for key distribution and for digital signatures.
Salt	Used as an input for certain algorithms, such as key derivations.
Signature	The output of a digital signature scheme that uses an asymmetric keypair. Used to establish who produced a message.
Single-part function	An API that implements the cryptographic operation in a single function call.
Specification defined	Behavior that is defined by this specification.
Symmetric	A type of cryptographic algorithm that uses a single key. A symmetric key can be used with a block cipher or a stream cipher.
Volatile key	A key that has a short lifespan and is guaranteed not to exist after a restart of an application instance.

Potential for change¶

The contents of this specification are stable for version 1.2 PAKE Extension.

The following may change in updates to the version 1.2 PAKE Extension 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

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.

Current status and anticipated changes¶

This document is at Release/Final quality status.

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 (AES 0058 1.2 PAKE Extension.1).
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.