PSA Cryptography API 1.0

Document number:	IHI 0086
Release Quality:	Final
Issue Number:	1
Confidentiality:	Non-confidential
Date of Issue:	27/08/2020

Copyright © 2018-2020, Arm Limited. All rights reserved.

Contents

• About this document
  • Release information
  • Arm Non-Confidential Document Licence (“Licence”)
  • References
  • Terms and abbreviations
  • Potential for change
  • Conventions
  • Pseudocode descriptions
  • Assembler syntax descriptions
  • Feedback

• 1. Introduction
• 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 identifiers
    • 3.2.2. Key lifetimes
    • 3.2.3. Key policies
    • 3.2.4. 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. Message digests (Hashes)
    • 3.3.4. Message authentication codes (MACs)
    • 3.3.5. Encryption and decryption
    • 3.3.6. Authenticated encryption (AEAD)
    • 3.3.7. Key derivation
    • 3.3.8. Example of the symmetric cryptography API
  • 3.4. Asymmetric cryptography
    • 3.4.1. Asymmetric encryption
    • 3.4.2. Hash-and-sign
    • 3.4.3. Key agreement
  • 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. Error handling
    • 5.1.1. Return status
    • 5.1.2. Behavior on error
  • 5.2. Parameter conventions
    • 5.2.1. Pointer conventions
    • 5.2.2. Input buffer sizes
    • 5.2.3. Output buffer sizes
    • 5.2.4. Overlap between parameters
    • 5.2.5. Stability of parameters
  • 5.3. Key types and algorithms
    • 5.3.1. Structure of key and algorithm types
  • 5.4. 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. PSA status codes
    • 8.1.1. Status type
    • 8.1.2. Success codes
    • 8.1.3. Error codes
  • 8.2. PSA Crypto 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
• 10. Cryptographic operation reference
  • 10.1. Algorithms
    • 10.1.1. Algorithm encoding
    • 10.1.2. Algorithm categories
  • 10.2. Message digests
    • 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

• Example header file
  • psa/crypto.h
• Example macro implementations
  • Algorithm macros
  • Key type macros
  • Hash suspend state macros
• Changes to the API
  • Document change history
    • Changes between 1.0.0 and 1.0.1
    • Changes between 1.0 beta 3 and 1.0.0
    • Changes between 1.0 beta 2 and 1.0 beta 3
    • Changes between 1.0 beta 1 and 1.0 beta 2
  • Planned changes for version 1.0.x
  • Future additions