PSA Certified
Crypto API 1.3

Document number:	IHI 0086
Release Quality:	Final
Issue Number:	0
Confidentiality:	Non-confidential
Date of Issue:	31/03/2025

Abstract

This document is part of the PSA Certified API specifications. It defines interfaces to provide cryptographic operations and key storage services.

Contents

• About this document
  • Release information
  • License
  • References
  • Terms and abbreviations
  • Potential for change
  • Conventions
  • Feedback

• 1 Introduction
  • 1.1 About Platform Security Architecture
  • 1.2 About the Crypto API
• 2 Design goals
  • 2.1 Suitable for constrained devices
  • 2.2 A keystore interface
  • 2.3 Optional isolation
  • 2.4 Choice of algorithms
  • 2.5 Ease of use
  • 2.6 Example use cases
    • 2.6.1 Network Security (TLS)
    • 2.6.2 Secure Storage
    • 2.6.3 Network Credentials
    • 2.6.4 Device Pairing
    • 2.6.5 Secure Boot
    • 2.6.6 Attestation
    • 2.6.7 Factory Provisioning
• 3 Functionality overview
  • 3.1 Library management
  • 3.2 Key management
    • 3.2.1 Key types
    • 3.2.2 Key identifiers
    • 3.2.3 Key lifetimes
    • 3.2.4 Key policies
    • 3.2.5 Recommendations of minimum standards for key management
  • 3.3 Cryptographic operations
    • 3.3.1 Single-part Functions
    • 3.3.2 Multi-part operations
    • 3.3.3 Symmetric cryptography
    • 3.3.4 Asymmetric cryptography
  • 3.4 Randomness and key generation
• 4 Sample architectures
  • 4.1 Single-partition architecture
  • 4.2 Cryptographic token and single-application processor
  • 4.3 Cryptoprocessor with no key storage
  • 4.4 Multi-client cryptoprocessor
  • 4.5 Multi-cryptoprocessor architecture
• 5 Library conventions
  • 5.1 Header files
  • 5.2 API conventions
    • 5.2.1 Identifier names
    • 5.2.2 Basic types
    • 5.2.3 Data types
    • 5.2.4 Constants
    • 5.2.5 Function-like macros
    • 5.2.6 Functions
  • 5.3 Error handling
    • 5.3.1 Return status
    • 5.3.2 Behavior on error
  • 5.4 Parameter conventions
    • 5.4.1 Pointer conventions
    • 5.4.2 Input buffer sizes
    • 5.4.3 Output buffer sizes
    • 5.4.4 Overlap between parameters
    • 5.4.5 Stability of parameters
  • 5.5 Key types and algorithms
    • 5.5.1 Structure of key types and algorithms
  • 5.6 Concurrent calls
• 6 Implementation considerations
  • 6.1 Implementation-specific aspects of the interface
    • 6.1.1 Implementation profile
    • 6.1.2 Implementation-specific types
    • 6.1.3 Implementation-specific macros
  • 6.2 Porting to a platform
    • 6.2.1 Platform assumptions
    • 6.2.2 Platform-specific types
    • 6.2.3 Cryptographic hardware support
  • 6.3 Security requirements and recommendations
    • 6.3.1 Error detection
    • 6.3.2 Indirect object references
    • 6.3.3 Memory cleanup
    • 6.3.4 Managing key material
    • 6.3.5 Safe outputs on error
    • 6.3.6 Attack resistance
  • 6.4 Other implementation considerations
    • 6.4.1 Philosophy of resource management
• 7 Usage considerations
  • 7.1 Security recommendations
    • 7.1.1 Always check for errors
    • 7.1.2 Shared memory and concurrency
    • 7.1.3 Cleaning up after use
• 8 Library management reference
  • 8.1 Status codes
    • 8.1.1 Common error codes
    • 8.1.2 Error codes specific to the Crypto API
  • 8.2 Crypto API library
    • 8.2.1 API version
    • 8.2.2 Library initialization
• 9 Key management reference
  • 9.1 Key attributes
    • 9.1.1 Managing key attributes
  • 9.2 Key types
    • 9.2.1 Key type encoding
    • 9.2.2 Key categories
    • 9.2.3 Symmetric keys
    • 9.2.4 Asymmetric keys
    • 9.2.5 RSA keys
    • 9.2.6 Elliptic Curve keys
    • 9.2.7 Diffie Hellman keys
    • 9.2.8 Attribute accessors
  • 9.3 Key lifetimes
    • 9.3.1 Volatile keys
    • 9.3.2 Persistent keys
    • 9.3.3 Lifetime encodings
    • 9.3.4 Lifetime values
    • 9.3.5 Attribute accessors
    • 9.3.6 Support macros
  • 9.4 Key identifiers
    • 9.4.1 Key identifier type
    • 9.4.2 Attribute accessors
  • 9.5 Key policies
    • 9.5.1 Permitted algorithms
    • 9.5.2 Key usage flags
  • 9.6 Key management functions
    • 9.6.1 Key creation
    • 9.6.2 Key destruction
    • 9.6.3 Key export
• 10 Cryptographic operation reference
  • 10.1 Algorithms
    • 10.1.1 Algorithm encoding
    • 10.1.2 Algorithm categories
    • 10.1.3 Support macros
  • 10.2 Message digests (Hashes)
    • 10.2.1 Hash algorithms
    • 10.2.2 Single-part hashing functions
    • 10.2.3 Multi-part hashing operations
    • 10.2.4 Support macros
    • 10.2.5 Hash suspend state
  • 10.3 Message authentication codes (MAC)
    • 10.3.1 MAC algorithms
    • 10.3.2 Single-part MAC functions
    • 10.3.3 Multi-part MAC operations
    • 10.3.4 Support macros
  • 10.4 Unauthenticated ciphers
    • 10.4.1 Cipher algorithms
    • 10.4.2 Single-part cipher functions
    • 10.4.3 Multi-part cipher operations
    • 10.4.4 Support macros
  • 10.5 Authenticated encryption with associated data (AEAD)
    • 10.5.1 AEAD algorithms
    • 10.5.2 Single-part AEAD functions
    • 10.5.3 Multi-part AEAD operations
    • 10.5.4 Support macros
  • 10.6 Key derivation
    • 10.6.1 Key-derivation algorithms
    • 10.6.2 Input step types
    • 10.6.3 Key-derivation functions
    • 10.6.4 Support macros
  • 10.7 Asymmetric signature
    • 10.7.1 RSA signature algorithms
    • 10.7.2 ECDSA signature algorithms
    • 10.7.3 EdDSA signature algorithms
    • 10.7.4 Asymmetric signature functions
    • 10.7.5 Support macros
  • 10.8 Asymmetric encryption
    • 10.8.1 Asymmetric encryption algorithms
    • 10.8.2 Asymmetric encryption functions
    • 10.8.3 Support macros
  • 10.9 Key agreement
    • 10.9.1 Key-agreement algorithms
    • 10.9.2 Standalone key agreement
    • 10.9.3 Combining key agreement and key derivation
    • 10.9.4 Support macros
  • 10.10 Key encapsulation
    • 10.10.1 Elliptic Curve Integrated Encryption Scheme
    • 10.10.2 Key-encapsulation functions
    • 10.10.3 Support macros
  • 10.11 Password-authenticated key exchange (PAKE)
    • 10.11.1 Common API for PAKE
    • 10.11.2 PAKE primitives
    • 10.11.3 PAKE cipher suites
    • 10.11.4 PAKE roles
    • 10.11.5 PAKE step types
    • 10.11.6 Multi-part PAKE operations
    • 10.11.7 PAKE support macros
    • 10.11.8 The J-PAKE protocol
    • 10.11.9 J-PAKE algorithms
    • 10.11.10 The SPAKE2+ protocol
    • 10.11.11 SPAKE2+ algorithms
  • 10.12 Other cryptographic services
    • 10.12.1 Random number generation

• A Example header file
  • A.1 psa/crypto.h
• B Algorithm and key type encoding
  • B.1 Algorithm identifier encoding
    • B.1.1 Algorithm categories
    • B.1.2 Hash algorithm encoding
    • B.1.3 MAC algorithm encoding
    • B.1.4 Cipher algorithm encoding
    • B.1.5 AEAD algorithm encoding
    • B.1.6 Key-derivation algorithm encoding
    • B.1.7 Asymmetric signature algorithm encoding
    • B.1.8 Asymmetric encryption algorithm encoding
    • B.1.9 Key-agreement algorithm encoding
    • B.1.10 Key-encapsulation algorithm encoding
    • B.1.11 PAKE algorithm encoding
  • B.2 Key type encoding
    • B.2.1 Key type categories
    • B.2.2 Raw key encoding
    • B.2.3 Symmetric key encoding
    • B.2.4 Asymmetric key encoding
• C Example macro implementations
  • C.1 Algorithm macros
  • C.2 Key type macros
  • C.3 Hash suspend state macros
• D Security Risk Assessment
  • D.1 Architecture
    • D.1.1 System definition
    • D.1.2 Assets and stakeholders
    • D.1.3 Security goals
  • D.2 Threat Model
    • D.2.1 Adversarial models
    • D.2.2 Threats and attacks
    • D.2.3 Risk assessment
  • D.3 Mitigations
    • D.3.1 Objectives
    • D.3.2 Requirements
  • D.4 Remediation & residual risk
    • D.4.1 Implementation remediations
    • D.4.2 Residual risk
• E Changes to the API
  • E.1 Document change history
    • E.1.1 Changes between 1.2.1 and 1.3.0
    • E.1.2 Changes between 1.2.0 and 1.2.1
    • E.1.3 Changes between 1.1.2 and 1.2.0
    • E.1.4 Changes between 1.1.1 and 1.1.2
    • E.1.5 Changes between 1.1.0 and 1.1.1
    • E.1.6 Changes between 1.0.1 and 1.1.0
    • E.1.7 Changes between 1.0.0 and 1.0.1
    • E.1.8 Changes between 1.0 beta 3 and 1.0.0
    • E.1.9 Changes between 1.0 beta 2 and 1.0 beta 3
    • E.1.10 Changes between 1.0 beta 1 and 1.0 beta 2
  • E.2 Planned changes for version 1.2.x
  • E.3 Future additions