PSA Cryptography API 1.0
Total Page:16
File Type:pdf, Size:1020Kb
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 vii Release information vii Arm Non-Confidential Document Licence (“Licence”) viii References x Terms and abbreviations xiii Potential for change xv Conventions xv Typographical conventions xv Numbers xv Pseudocode descriptions xvi Assembler syntax descriptions xvi Feedback xvi Feedback on this book xvi 1 Introduction 17 2 Design goals 17 2.1 Suitable for constrained devices 17 2.2 A keystore interface 18 2.3 Optional isolation 18 2.4 Choice of algorithms 19 2.5 Ease of use 19 2.6 Example use cases 19 2.6.1 Network Security (TLS) 19 2.6.2 Secure Storage 19 2.6.3 Network Credentials 20 2.6.4 Device Pairing 20 2.6.5 Secure Boot 20 2.6.6 Attestation 20 2.6.7 Factory Provisioning 20 3 Functionality overview 20 3.1 Library management 20 IHI 0086 Copyright © 2018-2020, Arm Limited or its affiliates. All rights reserved. Page i 1.0.1 Non-confidential 3.2 Key management 21 3.2.1 Key identifiers 21 3.2.2 Key lifetimes 22 3.2.3 Key policies 22 3.2.4 Recommendations of minimum standards for key management 22 3.3 Symmetric cryptography 22 3.3.1 Single-part Functions 23 3.3.2 Multi-part operations 23 3.3.3 Message digests (Hashes) 24 3.3.4 Message authentication codes (MACs) 25 3.3.5 Encryption and decryption 25 3.3.6 Authenticated encryption (AEAD) 26 3.3.7 Key derivation 27 3.3.8 Example of the symmetric cryptography API 28 3.4 Asymmetric cryptography 28 3.4.1 Asymmetric encryption 29 3.4.2 Hash-and-sign 29 3.4.3 Key agreement 29 3.5 Randomness and key generation 29 4 Sample architectures 29 4.1 Single-partition architecture 30 4.2 Cryptographic token and single-application processor 30 4.3 Cryptoprocessor with no key storage 30 4.4 Multi-client cryptoprocessor 31 4.5 Multi-cryptoprocessor architecture 31 5 Library conventions 31 5.1 Error handling 31 5.1.1 Return status 31 5.1.2 Behavior on error 32 5.2 Parameter conventions 33 5.2.1 Pointer conventions 33 5.2.2 Input buffer sizes 33 5.2.3 Output buffer sizes 33 5.2.4 Overlap between parameters 34 5.2.5 Stability of parameters 34 5.3 Key types and algorithms 35 5.3.1 Structure of key and algorithm types 35 5.4 Concurrent calls 35 IHI 0086 Copyright © 2018-2020, Arm Limited or its affiliates. All rights reserved. Page ii 1.0.1 Non-confidential 6 Implementation considerations 36 6.1 Implementation-specific aspects of the interface 36 6.1.1 Implementation profile 36 6.1.2 Implementation-specific types 36 6.1.3 Implementation-specific macros 36 6.2 Porting to a platform 37 6.2.1 Platform assumptions 37 6.2.2 Platform-specific types 37 6.2.3 Cryptographic hardware support 38 6.3 Security requirements and recommendations 38 6.3.1 Error detection 38 6.3.2 Indirect object references 38 6.3.3 Memory cleanup 38 6.3.4 Managing key material 39 6.3.5 Safe outputs on error 39 6.3.6 Attack resistance 40 6.4 Other implementation considerations 40 6.4.1 Philosophy of resource management 40 7 Usage considerations 40 7.1 Security recommendations 40 7.1.1 Always check for errors 40 7.1.2 Shared memory and concurrency 41 7.1.3 Cleaning up after use 41 8 Library management reference 41 8.1 PSA status codes 41 8.1.1 Status type 41 8.1.2 Success codes 42 8.1.3 Error codes 42 8.2 PSA Crypto library 48 8.2.1 API version 48 8.2.2 Library initialization 48 9 Key management reference 49 9.1 Key attributes 49 9.1.1 Managing key attributes 49 9.2 Key types 53 9.2.1 Key type encoding 53 9.2.2 Key categories 54 9.2.3 Symmetric keys 55 9.2.4 RSA keys 58 IHI 0086 Copyright © 2018-2020, Arm Limited or its affiliates. All rights reserved. Page iii 1.0.1 Non-confidential 9.2.5 Elliptic Curve keys 58 9.2.6 Diffie Hellman keys 63 9.2.7 Attribute accessors 65 9.3 Key lifetimes 68 9.3.1 Volatile keys 68 9.3.2 Persistent keys 68 9.3.3 Lifetime encodings 69 9.3.4 Lifetime values 72 9.3.5 Attribute accessors 73 9.3.6 Support macros 74 9.4 Key identifiers 75 9.4.1 Key identifier type 76 9.4.2 Attribute accessors 77 9.5 Key policies 78 9.5.1 Permitted algorithms 78 9.5.2 Key usage flags 80 9.6 Key management functions 84 9.6.1 Key creation 84 9.6.2 Key destruction 90 9.6.3 Key export 92 10 Cryptographic operation reference 98 10.1 Algorithms 98 10.1.1 Algorithm encoding 99 10.1.2 Algorithm categories 100 10.2 Message digests 103 10.2.1 Hash algorithms 103 10.2.2 Single-part hashing functions 106 10.2.3 Multi-part hashing operations 108 10.2.4 Support macros 117 10.2.5 Hash suspend state 120 10.3 Message authentication codes (MAC) 122 10.3.1 MAC algorithms 122 10.3.2 Single-part MAC functions 123 10.3.3 Multi-part MAC operations 126 10.3.4 Support macros 133 10.4 Unauthenticated ciphers 135 10.4.1 Cipher algorithms 135 10.4.2 Single-part cipher functions 139 10.4.3 Multi-part cipher operations 142 10.4.4 Support macros 151 10.5 Authenticated encryption with associated data (AEAD) 157 10.5.1 AEAD algorithms 157 IHI 0086 Copyright © 2018-2020, Arm Limited or its affiliates. All rights reserved. Page iv 1.0.1 Non-confidential 10.5.2 Single-part AEAD functions 158 10.5.3 Multi-part AEAD operations 162 10.5.4 Support macros 176 10.6 Key derivation 181 10.6.1 Key derivation algorithms 181 10.6.2 Input step types 184 10.6.3 Key derivation functions 185 10.6.4 Support macros 196 10.7 Asymmetric signature 198 10.7.1 Asymmetric signature algorithms 198 10.7.2 Asymmetric signature functions 201 10.7.3 Support macros 207 10.8 Asymmetric encryption 211 10.8.1 Asymmetric encryption algorithms 211 10.8.2 Asymmetric encryption functions 212 10.8.3 Support macros 215 10.9 Key agreement 217 10.9.1 Key agreement algorithms 217 10.9.2 Standalone key agreement 218 10.9.3 Combining key agreement and key derivation 220 10.9.4 Support macros 221 10.10 Other cryptographic services 224 10.10.1 Random number generation 224 A Example header file 226 A.1 psa/crypto.h 226 B Example macro implementations 237 B.1 Algorithm macros 237 B.2 Key type macros 240 B.3 Hash suspend state macros 241 C Changes to the API 242 C.1 Document change history 242 C.1.1 Changes between 1.0.0 and 1.0.1 242 C.1.2 Changes between 1.0 beta 3 and 1.0.0 243 C.1.3 Changes between 1.0 beta 2 and 1.0 beta 3 253 C.1.4 Changes between 1.0 beta 1 and 1.0 beta 2 254 C.2 Planned changes for version 1.0.x 254 C.3 Future additions 254 IHI 0086 Copyright © 2018-2020, Arm Limited or its affiliates. All rights reserved. Page v 1.0.1 Non-confidential Index of API elements 256 IHI 0086 Copyright © 2018-2020, Arm Limited or its affiliates. All rights reserved. Page vi 1.0.1 Non-confidential About this document Release information The change history table lists the changes that have been made to this document. Date Version Confidentiality Change January 2019 1.0 Beta 1 Non-confidential First public beta release. February 2019 1.0 Beta 2 Non-confidential Update for release with other PSA Dev API specifications. May 2019 1.0 Beta 3 Non-confidential Update for release with other PSA API specifications. February 2020 1.0 Final Non-confidential 1.0 API finalized. August 2020 1.0.1 Final Non-confidential Update to fix errors and provide clarifications. The detailed changes in each release are described in Document change history on page 242. IHI 0086 Copyright © 2018-2020, Arm Limited or its affiliates. All rights reserved. Page vii 1.0.1 Non-confidential PSA Cryptography API Copyright © 2018-2020, 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.