About this document

Release information

The change history table lists the changes that have been made to this document.

Date Version Confidentiality Change
February 2022 Beta 0 Non-confidential Initial release of the 1.1 PAKE Extension specification

PSA Cryptography API

Copyright © 2022, Arm Limited or its affiliates. All rights reserved. The copyright statement reflects the fact that some draft issues of this document have been released, to a limited circulation.

Arm Non-Confidential Document Licence (“Licence”)

This Licence is a legal agreement between you and Arm Limited (“Arm”) for the use of Arm’s intellectual property (including, without limitation, any copyright) embodied in the document accompanying this Licence (“Document”). Arm licenses its intellectual property in the Document to you on condition that you agree to the terms of this Licence. By using or copying the Document you indicate that you agree to be bound by the terms of this Licence.

Subsidiary” means any company the majority of whose voting shares is now or hereafter owner or controlled, directly or indirectly, by you. A company shall be a Subsidiary only for the period during which such control exists.

This Document is NON-CONFIDENTIAL and any use by you and your Subsidiaries (“Licensee”) is subject to the terms of this Licence between you and Arm.

Subject to the terms and conditions of this Licence, Arm hereby grants to Licensee under the intellectual property in the Document owned or controlled by Arm, a non-exclusive, non-transferable, non-sub-licensable, royalty-free, worldwide licence to:

  1. use and copy the Document for the purpose of designing and having designed products that comply with the Document;
  2. manufacture and have manufactured products which have been created under the licence granted in (i) above; and
  3. sell, supply and distribute products which have been created under the licence granted in (i) above.

Licensee hereby agrees that the licences granted above shall not extend to any portion or function of a product that is not itself compliant with part of the Document.

Except as expressly licensed above, Licensee acquires no right, title or interest in any Arm technology or any intellectual property embodied therein.

THE DOCUMENT IS PROVIDED “AS IS”. ARM PROVIDES NO REPRESENTATIONS AND NO WARRANTIES, EXPRESS, IMPLIED OR STATUTORY, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTABILITY, SATISFACTORY QUALITY, NON-INFRINGEMENT OR FITNESS FOR A PARTICULAR PURPOSE WITH RESPECT TO THE DOCUMENT. Arm may make changes to the Document at any time and without notice. For the avoidance of doubt, Arm makes no representation with respect to, and has undertaken no analysis to identify or understand the scope and content of, third party patents, copyrights, trade secrets, or other rights.

NOTWITHSTANDING ANYTHING TO THE CONTRARY CONTAINED IN THIS LICENCE, TO THE FULLEST EXTENT PERMITTED BY LAW, IN NO EVENT WILL ARM BE LIABLE FOR ANY DAMAGES, IN CONTRACT, TORT OR OTHERWISE, IN CONNECTION WITH THE SUBJECT MATTER OF THIS LICENCE (INCLUDING WITHOUT LIMITATION) (I) LICENSEE’S USE OF THE DOCUMENT; AND (II) THE IMPLEMENTATION OF THE DOCUMENT IN ANY PRODUCT CREATED BY LICENSEE UNDER THIS LICENCE). THE EXISTENCE OF MORE THAN ONE CLAIM OR SUIT WILL NOT ENLARGE OR EXTEND THE LIMIT. LICENSEE RELEASES ARM FROM ALL OBLIGATIONS, LIABILITY, CLAIMS OR DEMANDS IN EXCESS OF THIS LIMITATION.

This Licence shall remain in force until terminated by Licensee or by Arm. Without prejudice to any of its other rights, if Licensee is in breach of any of the terms and conditions of this Licence then Arm may terminate this Licence immediately upon giving written notice to Licensee. Licensee may terminate this Licence at any time. Upon termination of this Licence by Licensee or by Arm, Licensee shall stop using the Document and destroy all copies of the Document in its possession. Upon termination of this Licence, all terms shall survive except for the licence grants.

Any breach of this Licence by a Subsidiary shall entitle Arm to terminate this Licence as if you were the party in breach. Any termination of this Licence shall be effective in respect of all Subsidiaries. Any rights granted to any Subsidiary hereunder shall automatically terminate upon such Subsidiary ceasing to be a Subsidiary.

The Document consists solely of commercial items. Licensee shall be responsible for ensuring that any use, duplication or disclosure of the Document complies fully with any relevant export laws and regulations to assure that the Document or any portion thereof is not exported, directly or indirectly, in violation of such export laws.

This Licence may be translated into other languages for convenience, and Licensee agrees that if there is any conflict between the English version of this Licence and any translation, the terms of the English version of this Licence shall prevail.

The Arm corporate logo and words marked with ® or ™ are registered trademarks or trademarks of Arm Limited (or its subsidiaries) in the US and/or elsewhere. All rights reserved. Other brands and names mentioned in this document may be the trademarks of their respective owners. No licence, express, implied or otherwise, is granted to Licensee under this Licence, to use the Arm trade marks in connection with the Document or any products based thereon. Visit Arm’s website at https://www.arm.com/company/policies/trademarks for more information about Arm’s trademarks.

The validity, construction and performance of this Licence shall be governed by English Law.

Copyright © 2022, Arm Limited or its affiliates. All rights reserved.

Arm Limited. Company 02557590 registered in England.
110 Fulbourn Road, Cambridge, England CB1 9NJ.

Arm document reference: LES-PRE-21585 version 4.0

References

This document refers to the following documents.

Ref Document Number Title
[PSA-CRYPT] IHI 0086 PSA Cryptography API. https://developer.arm.com/documentation/ihi0086/latest
[MBED-TLS]   Arm Ltd, Mbed TLS. https://github.com/ARMmbed/mbedtls
[SEC1]   Standards for Efficient Cryptography, SEC 1: Elliptic Curve Cryptography, May 2009. https://www.secg.org/sec1-v2.pdf
[RFC8235]   IETF, Schnorr Non-interactive Zero-Knowledge Proof, September 2017. https://tools.ietf.org/html/rfc8235.html
[RFC8236]   IETF, J-PAKE: Password-Authenticated Key Exchange by Juggling, September 2017. https://tools.ietf.org/html/rfc8236.html

Terms and abbreviations

This document uses the following terms and abbreviations.

Term Meaning
AEAD See Authenticated Encryption with Associated Data.
Algorithm

A finite sequence of steps to perform a particular operation.

In this specification, an algorithm is a cipher or a related function. Other texts call this a cryptographic mechanism.

API Application Programming Interface.
Asymmetric See Public-key cryptography.
Authenticated Encryption with Associated Data (AEAD) A type of encryption that provides confidentiality and authenticity of data using symmetric keys.
Byte In this specification, a unit of storage comprising eight bits, also called an octet.
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 PSA Crypto API are 32-bit integers.
Key policy Key metadata that describes and restricts what a key can be used for.
Key size

The size of a key as defined by common conventions for each key type. For keys that are built from several numbers of strings, this is the size of a particular one of these numbers or strings.

This specification expresses key sizes in bits.

Key type Key metadata that describes the structure and content of a key.
Keystore A hardware or software component that protects, stores, and manages cryptographic keys.
Lifetime Key metadata that describes when a key is destroyed.
MAC See Message Authentication Code.
Message Authentication Code (MAC) A short piece of information used to authenticate a message. It is created and verified using a symmetric key.
Message digest A hash of a message. Used to determine if a message has been tampered.
Multi-part operation An API which splits a single cryptographic operation into a sequence of separate steps.
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.

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

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 Beta quality status which has a particular meaning to Arm of which the recipient must be aware. A Beta quality specification will be sufficiently stable & committed for initial product development, however all aspects of the architecture described herein remain SUBJECT TO CHANGE. Please ensure that you have the latest revision.

Feedback

Arm welcomes feedback on its documentation.

Feedback on this book

If you have comments on the content of this book, send an e-mail to arm.psa-feedback@arm.com. Give:

  • The title (PSA Cryptography API).
  • The number and issue (AES 0058 1.1 PAKE Extension Beta (Issue 0)).
  • The page numbers to which your comments apply.
  • The rule identifiers to which your comments apply, if applicable.
  • A concise explanation of your comments.

Arm also welcomes general suggestions for additions and improvements.