PSA Certified
Crypto API 1.1

Document number:	IHI 0086
Release Quality:	Final
Issue Number:	2
Confidentiality:	Non-confidential
Date of Issue:	23/03/2023

Abstract

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

Contents

• About this document
  • 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. Symmetric cryptography
    • 3.3.1. Single-part Functions
    • 3.3.2. Multi-part operations
    • 3.3.3. Example of the symmetric cryptography API
  • 3.4. Asymmetric cryptography
  • 3.5. 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. RSA keys
    • 9.2.5. Elliptic Curve keys
    • 9.2.6. Diffie Hellman keys
    • 9.2.7. 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
    • 9.6.4. Key formats
• 10. Cryptographic operation reference
  • 10.1. Algorithms
    • 10.1.1. Algorithm encoding
    • 10.1.2. Algorithm categories
  • 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. Asymmetric signature algorithms
    • 10.7.2. Asymmetric signature functions
    • 10.7.3. 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. Other cryptographic services
    • 10.10.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.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.1.1 and 1.1.2
    • E.1.2. Changes between 1.1.0 and 1.1.1
    • E.1.3. Changes between 1.0.1 and 1.1.0
    • E.1.4. Changes between 1.0.0 and 1.0.1
    • E.1.5. Changes between 1.0 beta 3 and 1.0.0
    • E.1.6. Changes between 1.0 beta 2 and 1.0 beta 3
    • E.1.7. Changes between 1.0 beta 1 and 1.0 beta 2
  • E.2. Planned changes for version 1.1.x
  • E.3. Future additions