| |
| <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" |
| "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> |
| |
| <html xmlns="http://www.w3.org/1999/xhtml"> |
| <head> |
| <meta http-equiv="X-UA-Compatible" content="IE=Edge" /> |
| <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> |
| <title>Introduction — psa_crypto_api 1.0 beta3 documentation</title> |
| <link rel="stylesheet" href="_static/alabaster.css" type="text/css" /> |
| <link rel="stylesheet" href="_static/pygments.css" type="text/css" /> |
| <script type="text/javascript" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script> |
| <script type="text/javascript" src="_static/jquery.js"></script> |
| <script type="text/javascript" src="_static/underscore.js"></script> |
| <script type="text/javascript" src="_static/doctools.js"></script> |
| <script type="text/javascript" src="_static/language_data.js"></script> |
| <link rel="index" title="Index" href="genindex.html" /> |
| <link rel="search" title="Search" href="search.html" /> |
| <link rel="next" title="Implementation-specific definitions" href="from_doxygen.html" /> |
| <link rel="prev" title="PSA Cryptography API Specification" href="index.html" /> |
| |
| <link rel="stylesheet" href="_static/custom.css" type="text/css" /> |
| |
| |
| <meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9" /> |
| |
| </head><body> |
| |
| |
| <div class="document"> |
| <div class="documentwrapper"> |
| <div class="bodywrapper"> |
| |
| |
| <div class="body" role="main"> |
| |
| <div class="section" id="introduction"> |
| <h1>Introduction</h1> |
| <p>Arm’s Platform Security Architecture (PSA) is a holistic set of threat |
| models, security analyses, hardware and firmware architecture |
| specifications, and an open source firmware reference implementation. |
| PSA provides a recipe, based on industry best practice, that allows |
| security to be consistently designed in, at both a hardware and firmware |
| level.</p> |
| <p>The PSA Cryptographic API (Crypto API) described in this document is an |
| important PSA component that provides an interface to modern |
| cryptographic primitives on resource-constrained devices. The interface |
| is user-friendly, while still providing access to the primitives used in |
| modern cryptography. It does not require that the user have access to |
| the key material. Instead, it uses opaque key handles.</p> |
| <p>This document is part of the PSA family of specifications. It defines an |
| interface for cryptographic services, including cryptography primitives |
| and a key storage functionality.</p> |
| <p>This document includes:</p> |
| <ul class="simple"> |
| <li>A <a class="reference external" href="#design-goals">rationale</a> for the design.</li> |
| <li>A <a class="reference external" href="#functionality-overview">high-level overview of the |
| functionality</a> provided by the interface.</li> |
| <li>A <a class="reference external" href="#sample-architectures">description of typical architectures</a> of |
| implementations for this specification.</li> |
| <li>General considerations <a class="reference external" href="#implementation-considerations">for |
| implementers</a> of this |
| specification and <a class="reference external" href="#usage-considerations">for applications</a> that |
| use the interface defined in this specification.</li> |
| <li>A detailed definition of the API.</li> |
| </ul> |
| <p>Companion documents will define <em>profiles</em> for this specification. A |
| profile is a minimum mandatory subset of the interface that a compliant |
| implementation must provide.</p> |
| </div> |
| <div class="section" id="design-goals"> |
| <h1>Design goals</h1> |
| <div class="section" id="suitable-for-constrained-devices"> |
| <h2>Suitable for constrained devices</h2> |
| <p>The interface is suitable for a vast range of devices: from |
| special-purpose cryptographic processors that process data with a |
| built-in key, to constrained devices running custom application code, |
| such as microcontrollers, and multi-application devices, such as |
| servers. Consequentially, the interface is scalable and modular.</p> |
| <ul class="simple"> |
| <li><em>Scalable</em>: you shouldn’t pay for functionality that you don’t need.</li> |
| <li><em>Modular</em>: larger devices implement larger subsets of the same |
| interface, rather than different interfaces.</li> |
| </ul> |
| <p>Because this specification is suitable for very constrained devices, |
| including those where memory is very limited, all operations on |
| unbounded amounts of data allow <em>multipart</em> processing, as long as the |
| calculations on the data are performed in a streaming manner. This means |
| that the application does not need to store the whole message in memory |
| at one time.</p> |
| <p>Memory outside the keystore boundary is managed by the application. An |
| implementation of the interface is not required to retain any state |
| between function calls, apart from the content of the keystore and other |
| data that must be kept inside the keystore security boundary.</p> |
| <p>The interface does not expose the representation of keys and |
| intermediate data, except when required for interchange. This allows |
| each implementation to choose optimal data representations. |
| Implementations with multiple components are also free to choose which |
| memory area to use for internal data.</p> |
| </div> |
| <div class="section" id="a-keystore-interface"> |
| <h2>A keystore interface</h2> |
| <p>The specification allows cryptographic operations to be performed on a |
| key to which the application does not have direct access. Except where |
| required for interchange, applications access all keys indirectly, by a |
| handle. The key material corresponding to that handle can reside inside |
| a security boundary that prevents it from being extracted, except as |
| permitted by a policy that is defined when the key is created.</p> |
| </div> |
| <div class="section" id="optional-isolation"> |
| <h2>Optional isolation</h2> |
| <p>Implementations can isolate the cryptoprocessor from the calling |
| application, and can further isolate multiple calling applications. The |
| interface allows the implementation to be separated between a frontend |
| and a backend. In an isolated implementation, the frontend is the part |
| of the implementation that is located in the same isolation boundary as |
| the application, which the application accesses by function calls. The |
| backend is the part of the implementation that is located in a different |
| environment, which is protected from the frontend. Various technologies |
| can provide protection, for example:</p> |
| <ul class="simple"> |
| <li>Process isolation in an operating system.</li> |
| <li>Partition isolation, either with a virtual machine or a partition |
| manager.</li> |
| <li>Physical separation between devices.</li> |
| </ul> |
| <p>Communication between the frontend and backend is beyond the scope of |
| this specification.</p> |
| <p>In an isolated implementation, the backend can serve more than one |
| implementation instance. In this case, a single backend communicates |
| with multiple instances of the frontend. The backend must enforce |
| <strong>caller isolation</strong>: it must ensure that assets of one frontend are not |
| visible to any other frontend. How callers are identified is beyond the |
| scope of this specification. An implementation that provides caller |
| isolation must document how callers are identified. An implementation |
| that provides isolation must document any implementation-specific |
| extension of the API that enables frontend instances to share data in |
| any form.</p> |
| <p>In summary, there are three types of implementations:</p> |
| <ul class="simple"> |
| <li>No isolation: there is no security boundary between the application |
| and the cryptoprocessor. For example, a statically or dynamically |
| linked library is an implementation with no isolation.</li> |
| <li>Cryptoprocessor isolation: there is a security boundary between the |
| application and the cryptoprocessor, but the cryptoprocessor does not |
| communicate with other applications. For example, a cryptoprocessor |
| chip that is a companion to an application processor is an |
| implementation with cryptoprocessor isolation.</li> |
| <li>Caller isolation: there are multiple application instances, with a |
| security boundary between the application instances among themselves, |
| as well as between the cryptoprocessor and the application instances. |
| For example, a cryptography service in a multiprocess environment is |
| an implementation with caller and cryptoprocessor isolation.</li> |
| </ul> |
| </div> |
| <div class="section" id="choice-of-algorithms"> |
| <h2>Choice of algorithms</h2> |
| <p>The specification defines a low-level cryptographic interface, where the |
| caller explicitly chooses which algorithm and which security parameters |
| they use. This is necessary to implement protocols that are inescapable |
| in various use cases. The design of the interface enables applications |
| to implement widely-used protocols and data exchange formats, as well as |
| custom ones.</p> |
| <p>As a consequence, all cryptographic functionality operates according to |
| the precise algorithm specified by the caller. However, this does not |
| apply to device-internal functionality, which does not involve any form |
| of interoperability, such as random number generation. The specification |
| does not include generic higher-level interfaces, where the |
| implementation chooses the best algorithm for a purpose. However, |
| higher-level libraries can be built on top of the PSA Crypto API.</p> |
| <p>Another consequence is that the specification permits the use of |
| algorithms, key sizes and other parameters that, while known to be |
| insecure, may be necessary to support legacy protocols or legacy data. |
| Where major weaknesses are known, the algorithm description give |
| applicable warnings. However, the lack of a warning does not and cannot |
| indicate that an algorithm is secure in all circumstances. Application |
| developers should research the security of the algorithms that they plan |
| to use to determine if the algorithms meet their requirements.</p> |
| <p>The interface facilitates algorithm agility. As a consequence, |
| cryptographic primitives are presented through generic functions with a |
| parameter indicating the specific choice of algorithm. For example, |
| there is a single function to calculate a message digest, which takes a |
| parameter that identifies the specific hash algorithm.</p> |
| </div> |
| <div class="section" id="ease-of-use"> |
| <h2>Ease of use</h2> |
| <p>The interface is designed to be as user-friendly as possible, given the |
| aforementioned constraints on suitability for various types of devices |
| and on the freedom to choose algorithms.</p> |
| <p>In particular, the code flows are designed to reduce the chance of |
| dangerous misuse. The interface makes it harder to misuse than to use |
| correctly, and typical mistakes result in test failures, rather than |
| subtle security issues. Implementations avoid leaking data when a |
| function is called with invalid parameters, to the extent allowed by the |
| C language and by implementation size constraints.</p> |
| </div> |
| <div class="section" id="example-use-cases"> |
| <h2>Example use cases</h2> |
| <p>This section lists some of the use cases that were considered while |
| designing this API. This list is not exhaustive, nor are all |
| implementations required to support all use cases.</p> |
| <div class="section" id="network-security-tls"> |
| <h3>Network Security (TLS)</h3> |
| <p>The API provides everything needed to establish TLS connections on the |
| device side: asymmetric key management inside a key store, symmetric |
| ciphers, MAC, HMAC, message digests, and AEAD.</p> |
| </div> |
| <div class="section" id="secure-storage"> |
| <h3>Secure Storage</h3> |
| <p>The API provides all primitives related to storage encryption, block or |
| file-based, with master encryption keys stored inside a key store.</p> |
| </div> |
| <div class="section" id="network-credentials"> |
| <h3>Network Credentials</h3> |
| <p>The API provides network credential management inside a key store, for |
| example, for X.509-based authentication or pre-shared keys on enterprise |
| networks.</p> |
| </div> |
| <div class="section" id="device-pairing"> |
| <h3>Device Pairing</h3> |
| <p>The API provides support for key agreement protocols that are often used |
| for secure pairing of devices over wireless channels. For example, the |
| pairing of an NFC token or a Bluetooth device could make use of key |
| agreement protocols upon first use.</p> |
| </div> |
| <div class="section" id="secure-boot"> |
| <h3>Secure Boot</h3> |
| <p>The API provides primitives for use during firmware integrity and |
| authenticity validation, during a secure or trusted boot process.</p> |
| </div> |
| <div class="section" id="attestation"> |
| <h3>Attestation</h3> |
| <p>The API provides primitives used in attestation activities. Attestation |
| is the ability for a device to sign an array of bytes with a device |
| private key and return the result to the caller. There are several use |
| cases: from attestation of the device state to the ability to generate a |
| key pair and prove that it has been generated inside a secure key store. |
| The API provides access to the algorithms commonly used for attestation.</p> |
| </div> |
| <div class="section" id="factory-provisioning"> |
| <h3>Factory Provisioning</h3> |
| <p>Most IoT devices receive a unique identity during the factory |
| provisioning process, or once deployed to the field. This API provides |
| the APIs necessary for populating a device with keys that represent that |
| identity.</p> |
| </div> |
| </div> |
| </div> |
| <div class="section" id="functionality-overview"> |
| <h1>Functionality overview</h1> |
| <p>This section provides a high-level overview of the functionality |
| provided by the interface defined in this specification. Refer to the |
| API definition for a detailed description.</p> |
| <p>Due to the modularity of the interface, almost every part of the library |
| is optional. The only mandatory function is <code class="docutils literal notranslate"><span class="pre">psa_crypto_init</span></code>.</p> |
| <div class="section" id="library-management"> |
| <h2>Library management</h2> |
| <p>Before any use, applications must call <code class="docutils literal notranslate"><span class="pre">psa_crypto_init</span></code> to initialize |
| the library.</p> |
| </div> |
| <div class="section" id="key-management"> |
| <h2>Key management</h2> |
| <p>Applications always access keys via a handle. This allows keys to be |
| non-extractable, that is, an application can perform operations using a |
| key without having access to the key material. Non-extractable keys are |
| bound to the device, can be rate-limited and can have their usage |
| restricted by policies.</p> |
| <p>Each key has a set of attributes that describe the key and the policy |
| for using the key. A <code class="docutils literal notranslate"><span class="pre">psa_key_attributes_t</span></code> object contains all of the |
| attributes, which is used when creating a key and when querying key |
| attibutes.</p> |
| <p>Each key has a <em>lifetime</em> that determines when the key material is |
| destroyed. There are two types of lifetimes: |
| <a class="reference external" href="#volatile-keys">volatile</a> and <a class="reference external" href="#persistent-keys">persistent</a>.</p> |
| <div class="section" id="volatile-keys"> |
| <h3>Volatile keys</h3> |
| <p>A <em>volatile</em> key is destroyed as soon as the application closes the |
| handle to the key. When the application terminates, it conceptually |
| closes all of its key handles. Conceptually, a volatile key is stored in |
| RAM. Volatile keys have the lifetime <code class="docutils literal notranslate"><span class="pre">PSA_KEY_LIFETIME_VOLATILE</span></code>.</p> |
| <p>To create a volatile key:</p> |
| <ol class="arabic simple"> |
| <li>Populate a <code class="docutils literal notranslate"><span class="pre">psa_key_attributes_t</span></code> object with the key’s type, size, |
| policy and other attributes.</li> |
| <li>Create the key with <code class="docutils literal notranslate"><span class="pre">psa_import_key</span></code>, <code class="docutils literal notranslate"><span class="pre">psa_generate_key</span></code>, |
| <code class="docutils literal notranslate"><span class="pre">psa_key_derivation_output_key</span></code> or <code class="docutils literal notranslate"><span class="pre">psa_copy_key</span></code>.</li> |
| </ol> |
| <p>To destroy a volatile key, call <code class="docutils literal notranslate"><span class="pre">psa_close_key</span></code> or <code class="docutils literal notranslate"><span class="pre">psa_destroy_key</span></code> |
| (these functions are equivalent when called on a volatile key).</p> |
| </div> |
| <div class="section" id="persistent-keys"> |
| <h3>Persistent keys</h3> |
| <p>A <em>persistent</em> key exists until it explicitly destroyed with |
| <code class="docutils literal notranslate"><span class="pre">psa_destroy_key</span></code> or until it is wiped by the reset or destruction of |
| the device.</p> |
| <p>Each persistent key has a key identifier, which acts as a name for the |
| key. Within an application, the key identifier corresponds to a single |
| key. The application specifies the key identifier when the key is |
| created, and uses the key identifier to obtain a handle to a persistent |
| key that has already been created. If the implementation provides |
| <a class="reference external" href="#optional-isolation">caller isolation</a>, then key identifiers are |
| local to each application: the same key identifier in two applications |
| corresponds to different keys.</p> |
| <p>Persistent keys may be stored in different storage areas; this is |
| indicated through different lifetime values. This specification defines |
| a single lifetime value <code class="docutils literal notranslate"><span class="pre">PSA_KEY_LIFETIME_PERSISTENT</span></code> which |
| corresponds to a default storage area. Implementations may define |
| alternative lifetime values corresponding to different storage areas |
| with different retention policies, or to secure elements with different |
| security characteristics.</p> |
| <p>To create a persistent key:</p> |
| <ol class="arabic simple"> |
| <li>Populate a <code class="docutils literal notranslate"><span class="pre">psa_key_attributes_t</span></code> object with the key’s type, size, |
| policy and other attributes.</li> |
| <li>In the attributes object, set the desired lifetime and persistent |
| identifier for the key.</li> |
| <li>Create the key with <code class="docutils literal notranslate"><span class="pre">psa_import_key</span></code>, <code class="docutils literal notranslate"><span class="pre">psa_generate_key</span></code>, |
| <code class="docutils literal notranslate"><span class="pre">psa_key_derivation_output_key</span></code> or <code class="docutils literal notranslate"><span class="pre">psa_copy_key</span></code>.</li> |
| </ol> |
| <p>To release memory resources associated with a key but keep the key in |
| storage, call <code class="docutils literal notranslate"><span class="pre">psa_close_key</span></code>. To access an existing persistent key, |
| call <code class="docutils literal notranslate"><span class="pre">psa_open_key</span></code> with the same key identifier used when creating |
| the key.</p> |
| <p>To destroy a persistent key, open it (if it isn’t already open) and call |
| <code class="docutils literal notranslate"><span class="pre">psa_destroy_key</span></code>.</p> |
| <p>The key lifetime and identifier are set when the key is created and |
| cannot be changed without destroying the key first. If the original key |
| permits copying, then the application can specify a different lifetime |
| for the copy of the key.</p> |
| </div> |
| <div class="section" id="recommendations-of-minimum-standards-for-key-management"> |
| <h3>Recommendations of minimum standards for key management</h3> |
| <p>Most implementations provide the function <code class="docutils literal notranslate"><span class="pre">psa_import_key</span></code>. The only |
| exceptions are implementations that only give access to a key or keys |
| that are provisioned by proprietary means, and do not allow the main |
| application to use its own cryptographic material.</p> |
| <p>Most implementations provide <code class="docutils literal notranslate"><span class="pre">psa_get_key_attributes</span></code> and the |
| <code class="docutils literal notranslate"><span class="pre">psa_get_key_xxx</span></code> accessor functions, as they are easy to implement, |
| and it is difficult to write applications and to diagnose issues without |
| being able to check the metadata.</p> |
| <p>Most implementations also provide <code class="docutils literal notranslate"><span class="pre">psa_export_public_key</span></code> if they |
| support any asymmetric algorithm, since public-key cryptography often |
| requires the delivery of a public key that is associated with a |
| protected private key.</p> |
| <p>Most implementations provide <code class="docutils literal notranslate"><span class="pre">psa_export_key</span></code>. However, highly |
| constrained implementations that are designed to work only with |
| short-term keys (no non-volatile storage), or only with long-term |
| non-extractable keys, may omit this function.</p> |
| </div> |
| </div> |
| <div class="section" id="usage-policies"> |
| <h2>Usage policies</h2> |
| <p>All keys have an associated policy that regulates which operations are |
| permitted on the key. Each key policy is a set of usage flags and a |
| specific algorithm that is permitted with the key. The policy is part of |
| the key attributes that are managed by a <code class="docutils literal notranslate"><span class="pre">psa_key_attributes_t</span></code> |
| object.</p> |
| <p>The usage flags are encoded in a bitmask, which has the type |
| <code class="docutils literal notranslate"><span class="pre">psa_key_usage_t</span></code>. Three kinds of usage flag can be specified: * The |
| extractable flag <code class="docutils literal notranslate"><span class="pre">PSA_KEY_USAGE_EXPORT</span></code> determines whether the key |
| material can be extracted. * The copyable flag <code class="docutils literal notranslate"><span class="pre">PSA_KEY_USAGE_COPY</span></code> |
| determines whether the key material can be copied into a new key, which |
| can have a different lifetime or a more restrictive policy. * The usage |
| flags <code class="docutils literal notranslate"><span class="pre">PSA_KEY_USAGE_ENCRYPT</span></code>, <code class="docutils literal notranslate"><span class="pre">PSA_KEY_USAGE_SIGN</span></code>, and so on |
| determine whether the corresponding operation is permitted on the key.</p> |
| <p>In addition to the usage bitmask, a policy specifies which algorithm is |
| permitted with the key. This specification only defines policies that |
| restrict keys to a single algorithm, which is in keeping with common |
| practice and with security good practice.</p> |
| <p>A highly constrained implementation may not be able to support all the |
| policies that can be expressed through this interface. If an |
| implementation cannot create a key with the required policy, it must |
| return an appropriate error code when the key is created.</p> |
| </div> |
| <div class="section" id="symmetric-cryptography"> |
| <h2>Symmetric cryptography</h2> |
| <p>This specification defines interfaces for message digests (hash |
| functions), MAC (message authentication codes), symmetric ciphers and |
| authenticated encryption with associated data (AEAD). For each type of |
| primitive, the API includes two standalone functions (compute and |
| verify, or encrypt and decrypt) as well as a series of functions that |
| permit <a class="reference external" href="#multipart-operations">multipart operations</a>.</p> |
| <p>The standalone functions are:</p> |
| <ul class="simple"> |
| <li><code class="docutils literal notranslate"><span class="pre">psa_hash_compute</span></code> and <code class="docutils literal notranslate"><span class="pre">psa_hash_compare</span></code> to calculate the hash |
| of a message or compare the hash of a message with a reference value.</li> |
| <li><code class="docutils literal notranslate"><span class="pre">psa_mac_compute</span></code> and <code class="docutils literal notranslate"><span class="pre">psa_mac_verify</span></code> to calculate the MAC of a |
| message of compare the MAC with a reference value.</li> |
| <li><code class="docutils literal notranslate"><span class="pre">psa_cipher_encrypt</span></code> and <code class="docutils literal notranslate"><span class="pre">psa_cipher_decrypt</span></code> to encrypt or |
| decrypt a message using an unauthenticated symmetric cipher. The |
| encryption function generates a random IV; to use a deterministic IV |
| (which is not secure in general, but can be secure in some conditions |
| that depend on the algorithm), use the multipart API.</li> |
| <li><code class="docutils literal notranslate"><span class="pre">psa_aead_encrypt</span></code> and <code class="docutils literal notranslate"><span class="pre">psa_aead_decrypt</span></code> to encrypt/decrypt and |
| authenticate a message using an AEAD algorithm. These functions |
| follow the interface recommended by RFC 5116.</li> |
| </ul> |
| <div class="section" id="multipart-operations"> |
| <h3>Multipart operations</h3> |
| <p>The API provides a multipart interface to hash, MAC, symmetric cipher |
| and AEAD primitives. These interfaces process messages one chunk at a |
| time, with the size of chunks determined by the caller. This allows the |
| processing of messages that cannot be assembled in memory. To perform a |
| multipart operation:</p> |
| <ol class="arabic simple"> |
| <li>Allocate an operation object of the appropriate type. You can use any |
| allocation strategy: stack, heap, static, etc.</li> |
| <li>Initialize the operation object by one of the following methods:<ul> |
| <li>Set it to all-bits-zero.</li> |
| <li>Initialize it to logical zero.</li> |
| <li>Assign the value of the associated macro <code class="docutils literal notranslate"><span class="pre">PSA_xxx_INIT</span></code>.</li> |
| <li>Assign the result of calling the associated function |
| <code class="docutils literal notranslate"><span class="pre">psa_xxx_init</span></code>.</li> |
| </ul> |
| </li> |
| <li>Specify a key for the operation using the associated setup function: |
| <code class="docutils literal notranslate"><span class="pre">psa_hash_setup</span></code>, <code class="docutils literal notranslate"><span class="pre">psa_mac_sign_setup</span></code>, <code class="docutils literal notranslate"><span class="pre">psa_mac_verify_setup</span></code>, |
| <code class="docutils literal notranslate"><span class="pre">psa_cipher_encrypt_setup</span></code>, <code class="docutils literal notranslate"><span class="pre">psa_cipher_decrypt_setup</span></code>, |
| <code class="docutils literal notranslate"><span class="pre">psa_aead_encrypt_setup</span></code> or <code class="docutils literal notranslate"><span class="pre">psa_aead_decrypt_setup</span></code>.</li> |
| <li>Provide additional parameters:<ul> |
| <li>When encrypting data, generate or set an initialization vector |
| (IV), nonce, or similar initial value such as an initial counter |
| value.</li> |
| <li>When decrypting, set the IV or nonce.</li> |
| <li>For a symmetric cipher, to generate a random IV, which is |
| recommended in most protocols, call <code class="docutils literal notranslate"><span class="pre">psa_cipher_generate_iv</span></code>. To |
| set the IV, call <code class="docutils literal notranslate"><span class="pre">psa_cipher_set_iv</span></code>.</li> |
| <li>For AEAD, call <code class="docutils literal notranslate"><span class="pre">psa_aead_generate_nonce</span></code> or |
| <code class="docutils literal notranslate"><span class="pre">psa_aead_set_nonce</span></code>.</li> |
| </ul> |
| </li> |
| <li>Call the associated update function on successive chunks of the |
| message: <code class="docutils literal notranslate"><span class="pre">psa_hash_update</span></code>, <code class="docutils literal notranslate"><span class="pre">psa_mac_update</span></code>, |
| <code class="docutils literal notranslate"><span class="pre">psa_cipher_update</span></code>, <code class="docutils literal notranslate"><span class="pre">psa_aead_update_ad</span></code> or <code class="docutils literal notranslate"><span class="pre">psa_aead_update</span></code>.</li> |
| <li>At the end of the message, call the applicable finishing function. |
| There are three kinds of finishing function, depending on what to do |
| with the verification tag.<ul> |
| <li>Unauthenticated encryption and decryption does not involve a |
| verification tag. Call <code class="docutils literal notranslate"><span class="pre">psa_cipher_finish</span></code>.</li> |
| <li>To calculate the digest or MAC or authentication tag of a message, |
| call the associated function to calculate and output the |
| verification tag: <code class="docutils literal notranslate"><span class="pre">psa_hash_finish</span></code>, <code class="docutils literal notranslate"><span class="pre">psa_mac_sign_finish</span></code> or |
| <code class="docutils literal notranslate"><span class="pre">psa_aead_finish</span></code>.</li> |
| <li>To verify the digest or MAC of a message against a reference value |
| or to verify the authentication tag at the end of AEAD decryption, |
| call the associated function to compare the verification tag with |
| the reference value: <code class="docutils literal notranslate"><span class="pre">psa_hash_verify</span></code>, |
| <code class="docutils literal notranslate"><span class="pre">psa_mac_verify_finish</span></code> or <code class="docutils literal notranslate"><span class="pre">psa_aead_verify</span></code>.</li> |
| </ul> |
| </li> |
| </ol> |
| <p>Calling the setup function allocates resources inside the |
| implementation. These resources are freed when calling the associated |
| finishing function. In addition, each family of functions defines a |
| function <code class="docutils literal notranslate"><span class="pre">psa_xxx_abort</span></code>, which can be called at any time to free the |
| resources associated with an operation.</p> |
| </div> |
| <div class="section" id="authenticated-encryption"> |
| <h3>Authenticated encryption</h3> |
| <p>Having a multipart interface to authenticated encryption raises specific |
| issues.</p> |
| <p>Multipart authenticated decryption produces partial results that are not |
| authenticated. Applications must not use or expose partial results of |
| authenticated decryption until <code class="docutils literal notranslate"><span class="pre">psa_aead_verify</span></code> has returned a |
| success status, and must destroy all partial results without revealing |
| them if <code class="docutils literal notranslate"><span class="pre">psa_aead_verify</span></code> returns a failure status. Revealing partial |
| results (directly, or indirectly through the application’s behavior) can |
| compromise the confidentiality of all inputs that are encrypted with the |
| same key.</p> |
| <p>For encryption, some common algorithms cannot be processed in a |
| streaming fashion. For SIV mode, the whole plaintext must be known |
| before the encryption can start; the multipart AEAD API is not meant to |
| be usable with SIV mode. For CCM mode, the length of the plaintext must |
| be known before the encryption can start; the application can call the |
| function <code class="docutils literal notranslate"><span class="pre">psa_aead_set_lengths</span></code> to provide these lengths before |
| providing input.</p> |
| </div> |
| </div> |
| <div class="section" id="key-derivation"> |
| <h2>Key derivation</h2> |
| <p>The specification defines a mechanism for key derivation that allows the |
| output of the derivation to be split into multiple keys, as well as |
| non-key outputs.</p> |
| <p>In an implementation with <a class="reference external" href="#optional-isolation">isolation</a>, the |
| intermediate state of the key derivation is not visible to the caller, |
| and if an output of the derivation is a non-exportable key, then this |
| output cannot be recovered outside the isolation boundary.</p> |
| <div class="section" id="key-derivation-operations"> |
| <h3>Key derivation operations</h3> |
| <p>A key derivation operation encodes a deterministic method to generate a |
| finite stream of bytes. This data stream is computed by the |
| cryptoprocessor and extracted in chunks. If two key derivation |
| operations are constructed with the same parameters, then they should |
| produce the same outputs.</p> |
| <p>Some example uses of key derivation operations are:</p> |
| <ul class="simple"> |
| <li>A key derivation function: initialized with a secret, a salt and |
| other parameters.</li> |
| <li>A key agreement function: initialized with a public key (peer key), a |
| key pair (own key) and other parameters.</li> |
| </ul> |
| <p>Applications use the <code class="docutils literal notranslate"><span class="pre">psa_key_derivation_operation_t</span></code> type to create |
| key derivation operations.</p> |
| <p>The lifecycle of a key derivation operation is as follows:</p> |
| <ol class="arabic simple"> |
| <li>Setup: construct a <code class="docutils literal notranslate"><span class="pre">psa_key_derivation_operation_t</span></code> object, and set |
| its parameters and inputs. The setup phase determines the key |
| derivation operation’s capacity, which is the maximum number of bytes |
| that can be output from this key derivation operation.</li> |
| <li>Output: read bytes from the stream defined by the key derivation |
| operation. This can be done any number of times, until the stream is |
| exhausted when its capacity has been reached. Each output step can |
| either be used to populate a key object |
| (<code class="docutils literal notranslate"><span class="pre">psa_key_derivation_output_key</span></code>), or to read some bytes and |
| extract them as cleartext (<code class="docutils literal notranslate"><span class="pre">psa_key_derivation_output_bytes</span></code>).</li> |
| <li>Terminate: clear the key derivation operation and release associated |
| resources (<code class="docutils literal notranslate"><span class="pre">psa_key_derivation_abort</span></code>).</li> |
| </ol> |
| <p>A key derivation operation cannot be rewound. Once a part of the stream |
| has been output, it cannot be output again. This ensures that the same |
| part of the output will not be used for different purposes.</p> |
| </div> |
| <div class="section" id="key-derivation-function"> |
| <h3>Key derivation function</h3> |
| <p>This specification defines functions to set up a key derivation. A key |
| derivation consists of two parts:</p> |
| <ol class="arabic simple"> |
| <li>Input collection. This is sometimes known as <em>extraction</em>: the |
| operation “extracts” information from the inputs to generate a |
| pseudorandom intermediate secret value.</li> |
| <li>Output generation. This is sometimes known as <em>expansion</em>: the |
| operation “expands” the intermediate secret value to the desired |
| output length.</li> |
| </ol> |
| <p>To perform a key derivation:</p> |
| <ol class="arabic simple"> |
| <li>Initialize a <code class="docutils literal notranslate"><span class="pre">psa_key_derivation_operation_t</span></code> object to zero or to |
| <code class="docutils literal notranslate"><span class="pre">PSA_KEY_DERIVATION_OPERAITON_INIT</span></code>.</li> |
| <li>Call <code class="docutils literal notranslate"><span class="pre">psa_key_derivation_setup</span></code> to select a key derivation |
| algorithm.</li> |
| <li>Call the functions <code class="docutils literal notranslate"><span class="pre">psa_key_derivation_input_bytes</span></code> and |
| <code class="docutils literal notranslate"><span class="pre">psa_key_derivation_input_key</span></code>, or |
| <code class="docutils literal notranslate"><span class="pre">psa_key_derivation_key_agreement</span></code> to provide the inputs to the key |
| derivation algorithm. Many key derivation algorithms take multiple |
| inputs; the “step” parameter to these functions indicates which input |
| is being passed. The documentation for each key derivation algorithm |
| describes the expected inputs for that algorithm.</li> |
| <li>Call <code class="docutils literal notranslate"><span class="pre">psa_key_derivation_output_key</span></code> to create a derived key, or |
| <code class="docutils literal notranslate"><span class="pre">psa_key_derivation_output_bytes</span></code> to export the derived data. These |
| functions may be called multiple times to read successive output from |
| the key derivation.</li> |
| <li>Call <code class="docutils literal notranslate"><span class="pre">psa_key_derivation_abort</span></code> to release the key derivation |
| operation memory.</li> |
| </ol> |
| <p>Here is an example of a use case where a master key is used to generate |
| both a message encryption key and an IV for the encryption, and the |
| derived key and IV are then used to encrypt a message.</p> |
| <ol class="arabic simple"> |
| <li>Derive the message encryption material from the master key.<ol class="arabic"> |
| <li>Initialize a <code class="docutils literal notranslate"><span class="pre">psa_key_derivation_operation_t</span></code> object to zero or |
| to <code class="docutils literal notranslate"><span class="pre">PSA_KEY_DERIVATION_OPERATION_INIT</span></code>.</li> |
| <li>Call <code class="docutils literal notranslate"><span class="pre">psa_key_derivation_setup</span></code> with <code class="docutils literal notranslate"><span class="pre">PSA_ALG_HKDF</span></code> as the |
| algorithm.</li> |
| <li>Call <code class="docutils literal notranslate"><span class="pre">psa_key_derivation_input_key</span></code> with the step |
| <code class="docutils literal notranslate"><span class="pre">PSA_KEY_DERIVATION_INPUT_SECRET</span></code> and the master key.</li> |
| <li>Call <code class="docutils literal notranslate"><span class="pre">psa_key_derivation_input_bytes</span></code> with the step |
| <code class="docutils literal notranslate"><span class="pre">PSA_KEY_DERIVATION_INPUT_INFO</span></code> and a public value that uniquely |
| identifies the message.</li> |
| <li>Populate a <code class="docutils literal notranslate"><span class="pre">psa_key_attributes_t</span></code> object with the derived |
| message encryption key’s attributes.</li> |
| <li>Call <code class="docutils literal notranslate"><span class="pre">psa_key_derivation_output_key</span></code> to create the derived |
| message key.</li> |
| <li>Call <code class="docutils literal notranslate"><span class="pre">psa_key_derivation_output_bytes</span></code> to generate the derived |
| IV.</li> |
| <li>Call <code class="docutils literal notranslate"><span class="pre">psa_key_derivation_abort</span></code> to release the key derivation |
| operation memory.</li> |
| </ol> |
| </li> |
| <li>Encrypt the message with the derived material.<ol class="arabic"> |
| <li>Initialize a <code class="docutils literal notranslate"><span class="pre">psa_cipher_operation_t</span></code> object to zero or to |
| <code class="docutils literal notranslate"><span class="pre">PSA_CIPHER_OPERATION_INIT</span></code>.</li> |
| <li>Call <code class="docutils literal notranslate"><span class="pre">psa_cipher_encrypt_setup</span></code> with the derived message |
| encryption key.</li> |
| <li>Call <code class="docutils literal notranslate"><span class="pre">psa_cipher_set_iv</span></code> using the derived IV retrieved above.</li> |
| <li>Call <code class="docutils literal notranslate"><span class="pre">psa_cipher_update</span></code> one or more times to encrypt the |
| message.</li> |
| <li>Call <code class="docutils literal notranslate"><span class="pre">psa_cipher_finish</span></code> at the end of the message.</li> |
| </ol> |
| </li> |
| <li>Call <code class="docutils literal notranslate"><span class="pre">psa_destroy_key</span></code> to clear the generated key.</li> |
| </ol> |
| </div> |
| </div> |
| <div class="section" id="asymmetric-cryptography"> |
| <h2>Asymmetric cryptography</h2> |
| <p>The asymmetric cryptography part of this interface defines functions for |
| asymmetric encryption, asymmetric signature and two-way key agreement.</p> |
| <div class="section" id="asymmetric-encryption"> |
| <h3>Asymmetric encryption</h3> |
| <p>Asymmetric encryption is provided through the functions |
| <code class="docutils literal notranslate"><span class="pre">psa_asymmetric_encrypt</span></code> and <code class="docutils literal notranslate"><span class="pre">psa_asymmetric_decrypt</span></code>.</p> |
| </div> |
| <div class="section" id="hash-and-sign"> |
| <h3>Hash-and-sign</h3> |
| <p>The signature and verification functions <code class="docutils literal notranslate"><span class="pre">psa_asymmetric_sign</span></code> and |
| <code class="docutils literal notranslate"><span class="pre">psa_asymmetric_verify</span></code> take a hash as one of their inputs. This hash |
| should be calculated with <code class="docutils literal notranslate"><span class="pre">psa_hash_setup</span></code>, <code class="docutils literal notranslate"><span class="pre">psa_hash_update</span></code> and |
| <code class="docutils literal notranslate"><span class="pre">psa_hash_finish</span></code> before calling <code class="docutils literal notranslate"><span class="pre">psa_asymmetric_sign</span></code> or |
| <code class="docutils literal notranslate"><span class="pre">psa_asymmetric_verify</span></code>. To determine which hash algorithm to use, |
| call the macro <code class="docutils literal notranslate"><span class="pre">PSA_ALG_SIGN_GET_HASH</span></code> on the corresponding signature |
| algorithm.</p> |
| </div> |
| <div class="section" id="key-agreement"> |
| <h3>Key agreement</h3> |
| <p>This specification defines two functions for a Diffie-Hellman-style key |
| agreement where each party combines its own private key with the peer’s |
| public key.</p> |
| <p>The recommended approach is to use a <a class="reference external" href="#key-derivation">key derivation |
| operation</a> with the |
| <code class="docutils literal notranslate"><span class="pre">psa_key_derivation_key_agreement</span></code> input function, which calculates a |
| shared secret for the key derivation function.</p> |
| <p>In case an application needs direct access to the shared secret, it can |
| call <code class="docutils literal notranslate"><span class="pre">psa_raw_key_agreement</span></code> instead. Note that in general the shared |
| secret is not directly suitable for use as a key because it is biased.</p> |
| </div> |
| </div> |
| <div class="section" id="randomness-and-key-generation"> |
| <h2>Randomness and key generation</h2> |
| <p>We strongly recommended that implementations include a random generator, |
| consisting of a cryptographically secure pseudo-random generator |
| (CSPRNG), which is adequately seeded with a cryptographic-quality |
| hardware entropy source, commonly referred to as a true random number |
| generator (TRNG). Constrained implementations may omit the random |
| generation functionality if they do not implement any algorithm that |
| requires randomness internally, and they do not provide a key generation |
| functionality. For example, a special-purpose component for signature |
| verification can omit this.</p> |
| <p>Applications should use <code class="docutils literal notranslate"><span class="pre">psa_generate_key</span></code>, |
| <code class="docutils literal notranslate"><span class="pre">psa_encrypt_generate_iv</span></code> or <code class="docutils literal notranslate"><span class="pre">psa_aead_generate_iv</span></code> to generate |
| suitably-formatted random data, as applicable. In addition, the API |
| includes a function <code class="docutils literal notranslate"><span class="pre">psa_generate_random</span></code> to generate and extract |
| arbitrary random data.</p> |
| </div> |
| <div class="section" id="future-additions"> |
| <h2>Future additions</h2> |
| <p>We plan to cover the following features in future drafts and editions of |
| this specification:</p> |
| <ul class="simple"> |
| <li>Single-shot functions for symmetric operations.</li> |
| <li>Multi-part operations for hybrid cryptography. For example, this |
| includes hash-and-sign for EdDSA, and hybrid encryption for ECIES.</li> |
| <li>Key exchange and a more general interface to key derivation. This |
| would enable an application to derive a non-extractable session key |
| from non-extractable secrets, without leaking the intermediate |
| material.</li> |
| <li>Key wrapping mechanisms to extract and import keys in a protected |
| form (encrypted and authenticated).</li> |
| <li>Key discovery mechanisms. This would enable an application to locate |
| a key by its name or attributes.</li> |
| <li>Implementation capability description. This would enable an |
| application to determine the algorithms, key types and storage |
| lifetimes that the implementation provides.</li> |
| <li>An ownership and access control mechanism allowing a multi-client |
| implementation to have privileged clients that are able to manage |
| keys of other clients.</li> |
| </ul> |
| </div> |
| </div> |
| <div class="section" id="sample-architectures"> |
| <h1>Sample architectures</h1> |
| <p>This section describes some example architectures that can be used for |
| implementations of the interface described in this specification. This |
| list is not exhaustive and the section is entirely non-normative.</p> |
| <div class="section" id="single-partition-architecture"> |
| <h2>Single-partition architecture</h2> |
| <p>In this architecture, there is no security boundary inside the system. |
| The application code may access all the system memory, including the |
| memory used by the cryptographic services described in this |
| specification. Thus, the architecture provides <a class="reference external" href="#optional-isolation">no |
| isolation</a>.</p> |
| <p>This architecture does not conform to the Arm <em>Platform Security |
| Architecture Security Model</em>. However, it may be useful for providing |
| cryptographic services that use the same interface, even on devices that |
| cannot support any security boundary. So, while this architecture is not |
| the primary design goal of the API defined in the present specification, |
| it is supported.</p> |
| <p>The functions in this specification simply execute the underlying |
| algorithmic code. Security checks can be kept to a minimum, since the |
| cryptoprocessor cannot defend against a malicious application. Key |
| import and export copy data inside the same memory space.</p> |
| <p>This architecture also describes a subset of some larger systems, where |
| the cryptographic services are implemented inside a high-security |
| partition, separate from the code of the main application, though it |
| shares this high-security partition with other platform security |
| services.</p> |
| </div> |
| <div class="section" id="cryptographic-token-and-single-application-processor"> |
| <h2>Cryptographic token and single-application processor</h2> |
| <p>This system is composed of two partitions: one is a cryptoprocessor and |
| the other partition runs an application. There is a security boundary |
| between the two partitions, so that the application cannot access the |
| cryptoprocessor, except through its public interface. Thus, the |
| architecture provides <a class="reference external" href="#optional-isolation">cryptoprocessor |
| isolation</a>. The cryptoprocessor has some |
| nonvolatile storage, a TRNG, and possibly, some cryptographic |
| accelerators.</p> |
| <p>There are a number of potential physical realizations: the |
| cryptoprocessor may be a separate chip, a separate processor on the same |
| chip, or a logical partition using a combination of hardware and |
| software to provide the isolation. These realizations are functionally |
| equivalent in terms of the offered software interface, but they would |
| typically offer different levels of security guarantees.</p> |
| <p>The PSA crypto API in the application processor consists of a thin layer |
| of code that translates function calls to remote procedure calls in the |
| cryptoprocessor. All cryptographic computations are, therefore, |
| performed inside the cryptoprocessor. Non-volatile keys are stored |
| inside the cryptoprocessor.</p> |
| </div> |
| <div class="section" id="cryptoprocessor-with-no-key-storage"> |
| <h2>Cryptoprocessor with no key storage</h2> |
| <p>As in the <a class="reference external" href="#cryptographic-token-and-single-application-processor">previous |
| example</a>, this |
| system is also composed of two partitions separated by a security |
| boundary. Thus, this architecture also provides <a class="reference external" href="#optional-isolation">cryptoprocessor |
| isolation</a>. However, unlike the previous |
| architecture, in this system, the cryptoprocessor does not have any |
| secure, persistent storage that could be used to store application keys.</p> |
| <p>If the cryptoprocessor is not capable of storing cryptographic material, |
| then there is little use for a separate cryptoprocessor, since all data |
| would have to be imported by the application.</p> |
| <p>The cryptoprocessor can provide useful services if it is able to store |
| at least one key. This may be a hardware unique key that is burnt to |
| one-time programmable memory during the manufacturing of the device. |
| This key can be used for one or more purposes:</p> |
| <ul class="simple"> |
| <li>Encrypt and authenticate data stored in the application processor.</li> |
| <li>Communicate with a paired device.</li> |
| <li>Allow the application to perform operations with keys that are |
| derived from the hardware unique key.</li> |
| </ul> |
| </div> |
| <div class="section" id="multi-client-cryptoprocessor"> |
| <h2>Multi-client cryptoprocessor</h2> |
| <p>This is an expanded variant of the <a class="reference external" href="#cryptographic-token-and-single-application-processor">cryptographic token plus application |
| architecture</a>. |
| In this variant, the cryptoprocessor serves multiple applications that |
| are mutually untrustworthy. This architecture provides <a class="reference external" href="#optional-isolation">caller |
| isolation</a>.</p> |
| <p>In this architecture, API calls are translated to remote procedure |
| calls, which encode the identity of the client application. The |
| cryptoprocessor carefully segments its internal storage to ensure that a |
| client’s data is never leaked to another client.</p> |
| </div> |
| <div class="section" id="multi-cryptoprocessor-architecture"> |
| <h2>Multi-cryptoprocessor architecture</h2> |
| <p>This system includes multiple cryptoprocessors. There are several |
| reasons to have multiple cryptoprocessors:</p> |
| <ul class="simple"> |
| <li>Different compromises between security and performance for different |
| keys. Typically, this means a cryptoprocessor that runs on the same |
| hardware as the main application and processes short-term secrets, a |
| secure element or a similar separate chip that retains long-term |
| secrets.</li> |
| <li>Independent provisioning of certain secrets.</li> |
| <li>A combination of a non-removable cryptoprocessor and removable ones, |
| for example, a smartcard or HSM.</li> |
| <li>Cryptoprocessors managed by different stakeholders who do not trust |
| each other.</li> |
| </ul> |
| <p>The keystore implementation needs to dispatch each request to the |
| correct processor. For example: * All requests involving a |
| non-extractable key must be processed in the cryptoprocessor that holds |
| that key. * Requests involving a persistent key must be processed in |
| the cryptoprocessor that corresponds to the key’s lifetime value. * |
| Requests involving a volatile key may target a cryptoprocessor based on |
| parameters supplied by the application, or based on considerations such |
| as performance inside the implementation.</p> |
| </div> |
| </div> |
| <div class="section" id="library-conventions"> |
| <h1>Library conventions</h1> |
| <div class="section" id="error-handling"> |
| <h2>Error handling</h2> |
| <div class="section" id="return-status"> |
| <h3>Return status</h3> |
| <p>Almost all functions return a status indication of type |
| <code class="docutils literal notranslate"><span class="pre">psa_status_t</span></code>. This is an enumeration of integer values, with 0 |
| (<code class="docutils literal notranslate"><span class="pre">PSA_SUCCESS</span></code>) indicating successful operation and other values |
| indicating errors. The exception is data structure accessor functions, |
| which cannot fail. Such functions may return <code class="docutils literal notranslate"><span class="pre">void</span></code> or a data value.</p> |
| <p>Unless specified otherwise, if multiple error conditions apply, an |
| implementation is free to return any of the applicable error codes. The |
| choice of error code is considered an implementation quality issue. |
| Different implementations may make different choices, for example to |
| favor code size over ease of debugging or vice versa.</p> |
| <p>Note that if the behavior is undefined (for example, if a function |
| receives an invalid pointer as a parameter), this specification makes no |
| guarantee that the function will return an error. Implementations are |
| encouraged to return an error or halt the application in a manner that |
| is appropriate for the platform if the undefined behavior condition can |
| be detected. However, application programmers should be aware that |
| undefined behavior conditions cannot be detected in general.</p> |
| </div> |
| <div class="section" id="behavior-on-error"> |
| <h3>Behavior on error</h3> |
| <p>All function calls must be implemented atomically:</p> |
| <ul class="simple"> |
| <li>When a function returns a type other than <code class="docutils literal notranslate"><span class="pre">psa_status_t</span></code>, the |
| requested action has been carried out.</li> |
| <li>When a function returns the status <code class="docutils literal notranslate"><span class="pre">PSA_SUCCESS</span></code>, the requested |
| action has been carried out.</li> |
| <li>When a function returns another status of type <code class="docutils literal notranslate"><span class="pre">psa_status_t</span></code>, no |
| action has been carried out. The content of the output parameters is |
| undefined, but otherwise the state of the system has not changed, |
| except as described below.</li> |
| </ul> |
| <p>In general, functions that modify the system state, for example, |
| creating or destroying a key, must leave the system state unchanged if |
| they return an error code. There are specific conditions that can result |
| in different behavior:</p> |
| <ul class="simple"> |
| <li>The status <code class="docutils literal notranslate"><span class="pre">PSA_ERROR_BAD_STATE</span></code> indicates that a parameter was not |
| in a valid state for the requested action. This parameter may have |
| been modified by the call and is now in an undefined state. The only |
| valid action on an object in an undefined state is to abort it with |
| the appropriate <code class="docutils literal notranslate"><span class="pre">psa_abort_xxx</span></code> function.</li> |
| <li>The status <code class="docutils literal notranslate"><span class="pre">PSA_ERROR_INSUFFICIENT_CAPACITY</span></code> indicates that a key |
| derivation object has reached its maximum capacity. The key |
| derivation operation may have been modified by the call. Any further |
| attempt to obtain output from the key derivation operation will |
| return <code class="docutils literal notranslate"><span class="pre">PSA_ERROR_INSUFFICIENT_CAPACITY</span></code>.</li> |
| <li>The status <code class="docutils literal notranslate"><span class="pre">PSA_ERROR_COMMUNICATION_FAILURE</span></code> indicates that the |
| communication between the application and the cryptoprocessor has |
| broken down. In this case, the cryptoprocessor must either finish the |
| requested action successfully, or interrupt the action and roll back |
| the system to its original state. Because it is often impossible to |
| report the outcome to the application after a communication failure, |
| this specification does not provide a way for the application to |
| determine whether the action was successful.</li> |
| <li>The statuses <code class="docutils literal notranslate"><span class="pre">PSA_ERROR_STORAGE_FAILURE</span></code>, |
| <code class="docutils literal notranslate"><span class="pre">PSA_ERROR_HARDWARE_FAILURE</span></code> and <code class="docutils literal notranslate"><span class="pre">PSA_ERROR_TAMPERING_DETECTED</span></code> |
| may indicate data corruption in the system state. When a function |
| returns one of these statuses, the system state may have changed from |
| its previous state before the function call, even though the function |
| call failed.</li> |
| <li>Some system states cannot be rolled back, for example, the internal |
| state of the random number generator or the content of access logs.</li> |
| </ul> |
| <p>Unless otherwise documented, the content of output parameters is not |
| defined when a function returns a status other than <code class="docutils literal notranslate"><span class="pre">PSA_SUCCESS</span></code>. |
| Implementations should set output parameters to safe defaults to avoid |
| leaking confidential data and limit risk, in case an application does |
| not properly handle all errors.</p> |
| </div> |
| </div> |
| <div class="section" id="parameter-conventions"> |
| <h2>Parameter conventions</h2> |
| <div class="section" id="pointer-conventions"> |
| <h3>Pointer conventions</h3> |
| <p>Unless explicitly stated in the documentation of a function, all |
| pointers must be valid pointers to an object of the specified type.</p> |
| <p>A parameter is considered a <strong>buffer</strong> if it points to an array of |
| bytes. A buffer parameter always has the type <code class="docutils literal notranslate"><span class="pre">uint8_t</span> <span class="pre">*</span></code> or |
| <code class="docutils literal notranslate"><span class="pre">const</span> <span class="pre">uint8_t</span> <span class="pre">*</span></code>, and always has an associated parameter indicating |
| the size of the array. Note that a parameter of type <code class="docutils literal notranslate"><span class="pre">void</span> <span class="pre">*</span></code> is never |
| considered a buffer.</p> |
| <p>All parameters of pointer type must be valid non-null pointers, unless |
| the pointer is to a buffer of length 0 or the function’s documentation |
| explicitly describes the behavior when the pointer is null. |
| Implementations where a null pointer dereference usually aborts the |
| application, passing <code class="docutils literal notranslate"><span class="pre">NULL</span></code> as a function parameter where a null |
| pointer is not allowed, should abort the caller in the habitual manner.</p> |
| <p>Pointers to input parameters may be in read-only memory. Output |
| parameters must be in writable memory. Output parameters that are not |
| buffers must also be readable, and the implementation must be able to |
| write to a non-buffer output parameter and read back the same value, as |
| explained in the <a class="reference external" href="#stability-of-parameters">“Stability of |
| parameters”</a> section.</p> |
| </div> |
| <div class="section" id="input-buffer-sizes"> |
| <h3>Input buffer sizes</h3> |
| <p>For input buffers, the parameter convention is:</p> |
| <ul class="simple"> |
| <li><code class="docutils literal notranslate"><span class="pre">const</span> <span class="pre">uint8_t</span> <span class="pre">*foo</span></code>: pointer to the first byte of the data. The |
| pointer may be invalid if the buffer size is 0.</li> |
| <li><code class="docutils literal notranslate"><span class="pre">size_t</span> <span class="pre">foo_length</span></code>: size of the buffer in bytes.</li> |
| </ul> |
| <p>The interface never uses input-output buffers.</p> |
| </div> |
| <div class="section" id="output-buffer-sizes"> |
| <h3>Output buffer sizes</h3> |
| <p>For output buffers, the parameter convention is:</p> |
| <ul class="simple"> |
| <li><code class="docutils literal notranslate"><span class="pre">uint8_t</span> <span class="pre">*foo</span></code>: pointer to the first byte of the data. The pointer |
| may be invalid if the buffer size is 0.</li> |
| <li><code class="docutils literal notranslate"><span class="pre">size_t</span> <span class="pre">foo_size</span></code>: the size of the buffer in bytes.</li> |
| <li><code class="docutils literal notranslate"><span class="pre">size_t</span> <span class="pre">*foo_length</span></code>: on successful return, contains the length of |
| the output in bytes.</li> |
| </ul> |
| <p>The content of the data buffer and of <code class="docutils literal notranslate"><span class="pre">*foo_length</span></code> on errors is |
| unspecified, unless explicitly mentioned in the function description. |
| They may be unmodified or set to a safe default. On successful |
| completion, the content of the buffer between the offsets |
| <code class="docutils literal notranslate"><span class="pre">*foo_length</span></code> and <code class="docutils literal notranslate"><span class="pre">foo_size</span></code> is also unspecified.</p> |
| <p>Functions return <code class="docutils literal notranslate"><span class="pre">PSA_ERROR_BUFFER_TOO_SMALL</span></code> if the buffer size is |
| insufficient to carry out the requested operation. The interface defines |
| macros to calculate a sufficient buffer size for each operation that has |
| an output buffer. These macros return compile-time constants if their |
| arguments are compile-time constants, so they are suitable for static or |
| stack allocation. Refer to an individual function’s documentation for |
| the associated output size macro.</p> |
| <p>Some functions always return exactly as much data as the size of the |
| output buffer. In this case, the parameter convention changes to:</p> |
| <ul class="simple"> |
| <li><code class="docutils literal notranslate"><span class="pre">uint8_t</span> <span class="pre">*foo</span></code>: pointer to the first byte of the output. The |
| pointer may be invalid if the buffer size is 0.</li> |
| <li><code class="docutils literal notranslate"><span class="pre">size_t</span> <span class="pre">foo_length</span></code>: the number of bytes to return in <code class="docutils literal notranslate"><span class="pre">foo</span></code> if |
| successful.</li> |
| </ul> |
| </div> |
| <div class="section" id="overlap-between-parameters"> |
| <h3>Overlap between parameters</h3> |
| <p>Output parameters that are not buffers must not overlap with any input |
| buffer or with any other output parameter. Otherwise, the behavior is |
| undefined.</p> |
| <p>Output buffers may overlap with input buffers. If this happens, the |
| implementation must return the same result, as if the buffers did not |
| overlap. In other words, the implementation must behave as if it had |
| copied all the inputs into temporary memory, as far as the result is |
| concerned. However, application developers should note that overlap |
| between parameters may affect the performance of a function call. |
| Overlap may also affect memory management security if the buffer is |
| located in memory that the caller shares with another security context, |
| as described in the <a class="reference external" href="#stability-of-parameters">“Stability of |
| parameters”</a> section.</p> |
| </div> |
| <div class="section" id="stability-of-parameters"> |
| <h3>Stability of parameters</h3> |
| <p>In some environments, it is possible for the content of a parameter to |
| change while a function is executing. It may also be possible for the |
| content of an output parameter to be read before the function |
| terminates. This can happen if the application is multithreaded. In some |
| implementations, memory can be shared between security contexts, for |
| example, between tasks in a multitasking operating system, between a |
| user land task and the kernel, or between the non-secure world and the |
| secure world of a trusted execution environment. This section describes |
| what implementations need or need not guarantee in such cases.</p> |
| <p>Parameters that are not buffers are assumed to be under the caller’s |
| full control. In a shared memory environment, this means that the |
| parameter must be in memory that is exclusively accessible by the |
| application. In a multithreaded environment, this means that the |
| parameter may not be modified during the execution, and the value of an |
| output parameter is undetermined until the function returns. The |
| implementation may read an input parameter that is not a buffer multiple |
| times and expect to read the same data. The implementation may write to |
| an output parameter that is not a buffer and expect to read back the |
| value that it last wrote. The implementation has the same permissions on |
| buffers that overlap with a buffer in the opposite direction.</p> |
| <p>In an environment with multiple threads or with shared memory, the |
| implementation carefully accesses non-overlapping buffer parameters in |
| order to prevent any security risk resulting from the content of the |
| buffer being modified or observed during the execution of the function. |
| In an input buffer that does not overlap with an output buffer, the |
| implementation reads each byte of the input once, at most. The |
| implementation does not read from an output buffer that does not overlap |
| with an input buffer. Additionally, the implementation does not write |
| data to a non-overlapping output buffer if this data is potentially |
| confidential and the implementation has not yet verified that outputting |
| this data is authorized.</p> |
| </div> |
| </div> |
| <div class="section" id="key-types-and-algorithms"> |
| <h2>Key types and algorithms</h2> |
| <p>Types of cryptographic keys and cryptographic algorithms are encoded |
| separately. Each is encoded by using an integral type: |
| <code class="docutils literal notranslate"><span class="pre">psa_key_type_t</span></code> and <code class="docutils literal notranslate"><span class="pre">psa_algorithm_t</span></code>, respectively.</p> |
| <p>There is some overlap in the information conveyed by key types and |
| algorithms. Both types contain enough information, so that the meaning |
| of an algorithm type value does not depend on what type of key it is |
| used with, and vice versa. However, the particular instance of an |
| algorithm may depend on the key type. For example, the algorithm |
| <code class="docutils literal notranslate"><span class="pre">PSA_ALG_GCM</span></code> can be instantiated as any AEAD algorithm using the GCM |
| mode over a block cipher. The underlying block cipher is determined by |
| the key type.</p> |
| <p>Key types do not encode the key size. For example, AES-128, AES-192 and |
| AES-256 share a key type <code class="docutils literal notranslate"><span class="pre">PSA_KEY_TYPE_AES</span></code>.</p> |
| <div class="section" id="structure-of-key-and-algorithm-types"> |
| <h3>Structure of key and algorithm types</h3> |
| <p>Both types use a partial bitmask structure, which allows the analysis |
| and building of values from parts. However, the interface defines |
| constants, so that applications do not need to depend on the encoding, |
| and an implementation may only care about the encoding for code size |
| optimization.</p> |
| <p>The encodings follows a few conventions:</p> |
| <ul class="simple"> |
| <li>The highest bit is a vendor flag. Current and future versions of this |
| specification will only define values where this bit is clear. |
| Implementations that wish to define additional |
| implementation-specific values must use values where this bit is set, |
| to avoid conflicts with future versions of this specification.</li> |
| <li>The next few highest bits indicate the corresponding algorithm |
| category: hash, MAC, symmetric cipher, asymmetric encryption, and so |
| on.</li> |
| <li>The following bits identify a family of algorithms in a |
| category-dependent manner.</li> |
| <li>In some categories and algorithm families, the lowest-order bits |
| indicate a variant in a systematic way. For example, algorithm |
| families that are parametrized around a hash function encode the hash |
| in the 8 lowest bits.</li> |
| </ul> |
| </div> |
| </div> |
| <div class="section" id="concurrent-calls"> |
| <h2>Concurrent calls</h2> |
| <p>In some environments, an application can make calls to the PSA crypto |
| API in separate threads. In such an environment, concurrent calls are |
| performed correctly, as if the calls were executed in sequence, provided |
| that they obey the following constraints:</p> |
| <ul class="simple"> |
| <li>There is no overlap between an output parameter of one call and an |
| input or output parameter of another call. Overlap between input |
| parameters is permitted.</li> |
| <li>If a call modifies a key, then no other call must modify or use that |
| key. <em>Using</em>, in this context, includes all functions of multipart |
| operations using the key. Concurrent calls that merely use the same |
| key are permitted.</li> |
| <li>Concurrent calls must not use the same operation object.</li> |
| </ul> |
| <p>If any of these constraints are violated, the behavior is undefined.</p> |
| <p>Individual implementations may provide additional guarantees.</p> |
| </div> |
| </div> |
| <div class="section" id="implementation-considerations"> |
| <h1>Implementation considerations</h1> |
| <div class="section" id="implementation-specific-aspects-of-the-interface"> |
| <h2>Implementation-specific aspects of the interface</h2> |
| <div class="section" id="implementation-profile"> |
| <h3>Implementation profile</h3> |
| <p>Implementations may implement a subset of the API and a subset of the |
| available algorithms. The implemented subset is known as the |
| implementation’s profile. The documentation for each implementation must |
| describe the profile that it implements. This specification’s companion |
| documents also define a number of standard profiles.</p> |
| </div> |
| <div class="section" id="implementation-specific-types"> |
| <h3>Implementation-specific types</h3> |
| <p>This specification defines a number of platform-specific types, which |
| represent data structures whose content depends on the implementation. |
| These are C <code class="docutils literal notranslate"><span class="pre">struct</span></code> types. In the associated header files, |
| <code class="docutils literal notranslate"><span class="pre">crypto.h</span></code> declares the <code class="docutils literal notranslate"><span class="pre">struct</span></code> tags and <code class="docutils literal notranslate"><span class="pre">crypto_struct.h</span></code> |
| provides a definition for the structures.</p> |
| </div> |
| <div class="section" id="implementation-specific-macros"> |
| <h3>Implementation-specific macros</h3> |
| <p>Some macros compute a result based on an algorithm or key type. This |
| specification provides a sample implementation of these macros, which |
| works for all standard types. If an implementation defines |
| vendor-specific algorithms or key types, then it must provide an |
| implementation for such macros that takes all relevant algorithms and |
| types into account. Conversely, an implementation that does not support |
| a certain algorithm or key type can define such macros in a simpler way |
| that does not take unsupported argument values into account.</p> |
| <p>Some macros define the minimum sufficient output buffer size for certain |
| functions. In some cases, an implementation is allowed to require a |
| buffer size that is larger than the theoretical minimum. An |
| implementation must define minimum-size macros in such a way that it |
| guarantees that the buffer of the resulting size is sufficient for the |
| output of the corresponding function. Refer to each macro’s |
| documentation for the applicable requirements.</p> |
| </div> |
| </div> |
| <div class="section" id="porting-to-a-platform"> |
| <h2>Porting to a platform</h2> |
| <div class="section" id="platform-assumptions"> |
| <h3>Platform assumptions</h3> |
| <p>This specification is designed for a C89 platform. The interface is |
| defined in terms of C macros, functions and objects.</p> |
| <p>The specification assumes 8-bit bytes, and “byte” and “octet” are used |
| synonymously.</p> |
| </div> |
| <div class="section" id="platform-specific-types"> |
| <h3>Platform-specific types</h3> |
| <p>The specification makes use of some platform-specific types, which |
| should be defined in <code class="docutils literal notranslate"><span class="pre">crypto_platform.h</span></code> or by a header included in |
| this file. <code class="docutils literal notranslate"><span class="pre">crypto_platform.h</span></code> must define the following types:</p> |
| <ul class="simple"> |
| <li><code class="docutils literal notranslate"><span class="pre">uint8_t</span></code>, <code class="docutils literal notranslate"><span class="pre">uint16_t</span></code>, <code class="docutils literal notranslate"><span class="pre">uint32_t</span></code>: unsigned integer types with |
| 8, 16 and 32 value bits respectively. These may be the types defined |
| by the C99 header <code class="docutils literal notranslate"><span class="pre">stdint.h</span></code>.</li> |
| <li><code class="docutils literal notranslate"><span class="pre">psa_key_handle_t</span></code>: an unsigned integer type of the |
| implementation’s choice.</li> |
| </ul> |
| </div> |
| <div class="section" id="cryptographic-hardware-support"> |
| <h3>Cryptographic hardware support</h3> |
| <p>Implementations are encouraged to make use of hardware accelerators |
| where available. A future version of this specification will define a |
| function interface that calls drivers for hardware accelerators and |
| external cryptographic hardware.</p> |
| </div> |
| </div> |
| <div class="section" id="security-requirements-and-recommendations"> |
| <h2>Security requirements and recommendations</h2> |
| <div class="section" id="error-detection"> |
| <h3>Error detection</h3> |
| <p>Implementations that provide isolation between the caller and the |
| cryptography processing environment must validate parameters to ensure |
| that the cryptography processing environment is protected from attacks |
| caused by passing invalid parameters.</p> |
| <p>Even implementations that do not provide isolation should strive to |
| detect bad parameters and fail-safe as much as possible.</p> |
| </div> |
| <div class="section" id="memory-cleanup"> |
| <h3>Memory cleanup</h3> |
| <p>Implementations must wipe all sensitive data from memory when it is no |
| longer used. They should wipe this sensitive data as soon as possible. |
| In any case, all temporary data used during the execution of a function, |
| such as stack buffers, must be wiped before the function returns. All |
| data associated with an object, such as a multipart operation, must be |
| wiped, at the latest, when the object becomes inactive, for example, |
| when a multipart operation is aborted.</p> |
| <p>The rationale for this non-functional requirement is to minimize impact |
| if the system is compromised. If sensitive data is wiped immediately |
| after use, only data that is currently in use can be leaked. It does not |
| compromise past data.</p> |
| </div> |
| <div class="section" id="safe-outputs-on-error"> |
| <h3>Safe outputs on error</h3> |
| <p>Implementations must ensure that confidential data is not written to |
| output parameters before validating that the disclosure of this |
| confidential data is authorized. This requirement is especially |
| important for implementations where the caller may share memory with |
| another security context, as described in the <a class="reference external" href="#stability-of-parameters">“Stability of |
| parameters”</a> section.</p> |
| <p>In most cases, the specification does not define the content of output |
| parameters when an error occurs. Implementations should try to ensure |
| that the content of output parameters is as safe as possible, in case an |
| application flaw or a data leak causes it to be used. In particular, Arm |
| recommends that implementations avoid placing partial output in output |
| buffers when an action is interrupted. The meaning of “safe as possible” |
| depends on the implementation, as different environments require |
| different compromises between implementation complexity, overall |
| robustness and performance. Some common strategies are to leave output |
| parameters unchanged, in case of errors, or zeroing them out.</p> |
| </div> |
| <div class="section" id="attack-resistance"> |
| <h3>Attack resistance</h3> |
| <p>Cryptographic code tends to manipulate high-value secrets, from which |
| other secrets can be unlocked. As such, it is a high-value target for |
| attacks. There is a vast body of literature on attack types, such as |
| side channel attacks and glitch attacks. Typical side channels include |
| timing, cache access patterns, branch-prediction access patterns, power |
| consumption, radio emissions and more.</p> |
| <p>This specification does not specify particular requirements for attack |
| resistance. Therefore, implementers should consider the attack |
| resistance desired in each use case and design their implementation |
| accordingly. Security standards for attack resistance for particular |
| targets may be applicable in certain use cases.</p> |
| </div> |
| </div> |
| <div class="section" id="other-implementation-considerations"> |
| <h2>Other implementation considerations</h2> |
| <div class="section" id="philosophy-of-resource-management"> |
| <h3>Philosophy of resource management</h3> |
| <p>The specification allows most functions to return |
| <code class="docutils literal notranslate"><span class="pre">PSA_ERROR_INSUFFICIENT_MEMORY</span></code>. This gives implementations the |
| freedom to manage memory as they please.</p> |
| <p>Alternatively, the interface is also designed for conservative |
| strategies of memory management. An implementation may avoid dynamic |
| memory allocation altogether by obeying certain restrictions:</p> |
| <ul class="simple"> |
| <li>Pre-allocate memory for a predefined number of keys, each with |
| sufficient memory for all key types that can be stored.</li> |
| <li>For multipart operations, in an implementation without isolation, |
| place all the data that needs to be carried over from one step to the |
| next in the operation object. The application is then fully in |
| control of how memory is allocated for the operation.</li> |
| <li>In an implementation with isolation, pre-allocate memory for a |
| predefined number of operations inside the cryptoprocessor.</li> |
| </ul> |
| <!-- |
| #### Inclusion of algorithms |
| |
| Inline algorithm-generic functions into specialized functions at compile/link time |
| --></div> |
| </div> |
| </div> |
| <div class="section" id="usage-considerations"> |
| <h1>Usage considerations</h1> |
| <div class="section" id="security-recommendations"> |
| <h2>Security recommendations</h2> |
| <div class="section" id="always-check-for-errors"> |
| <h3>Always check for errors</h3> |
| <p>Most functions in this API can return errors. All functions that can |
| fail have the return type <code class="docutils literal notranslate"><span class="pre">psa_status_t</span></code>. A few functions cannot fail, |
| and thus, return <code class="docutils literal notranslate"><span class="pre">void</span></code> or some other type.</p> |
| <p>If an error occurs, unless otherwise specified, the content of the |
| output parameters is undefined and must not be used.</p> |
| <p>Some common causes of errors include:</p> |
| <ul class="simple"> |
| <li>In implementations where the keys are stored and processed in a |
| separate environment from the application, all functions that need to |
| access the cryptography processing environment may fail due to an |
| error in the communication between the two environments.</li> |
| <li>If an algorithm is implemented with a hardware accelerator, which is |
| logically separate from the application processor, the accelerator |
| may fail, even when the application processor keeps running normally.</li> |
| <li>All functions may fail due to a lack of resources. However, some |
| implementations guarantee that certain functions always have |
| sufficient memory.</li> |
| <li>All functions that access persistent keys may fail due to a storage |
| failure.</li> |
| <li>All functions that require randomness may fail due to a lack of |
| entropy. Implementations are encouraged to seed the random generator |
| with sufficient entropy during the execution of <code class="docutils literal notranslate"><span class="pre">psa_crypto_init</span></code>. |
| However, some security standards require periodic reseeding from a |
| hardware random generator, which can fail.</li> |
| </ul> |
| </div> |
| <div class="section" id="shared-memory-and-concurrency"> |
| <h3>Shared memory and concurrency</h3> |
| <p>Some environments allow applications to be multithreaded, while others |
| do not. In some environments, applications may share memory with a |
| different security context. In environments with multithreaded |
| applications or shared memory, applications must be written carefully to |
| avoid data corruption or leakage. This specification requires the |
| application to obey certain constraints.</p> |
| <p>In general, this API allows either one writer or any number of |
| simultaneous readers, on any given object. In other words, if two or |
| more calls access the same object concurrently, then the behavior is |
| only well-defined if all the calls are only reading from the object and |
| do not modify it. Read accesses include reading memory by input |
| parameters and reading keystore content by using a key. For more |
| details, refer to the <a class="reference external" href="#concurrent-calls">“Concurrent calls”</a> |
| section.</p> |
| <p>If an application shares memory with another security context, it may |
| pass shared memory blocks as input buffers or output buffers, but not as |
| non-buffer parameters. For more details, refer to the <a class="reference external" href="#stability-of-parameters">“Stability of |
| parameters”</a> section.</p> |
| </div> |
| <div class="section" id="cleaning-up-after-use"> |
| <h3>Cleaning up after use</h3> |
| <p>To minimize impact if the system is compromised, applications should |
| wipe all sensitive data from memory when it is no longer used. That way, |
| only data that is currently in use may be leaked, and past data is not |
| compromised.</p> |
| <p>Wiping sensitive data includes:</p> |
| <ul class="simple"> |
| <li>Clearing temporary buffers in the stack or on the heap.</li> |
| <li>Aborting operations if they will not be finished.</li> |
| <li>Destroying keys that are no longer used.</li> |
| </ul> |
| </div> |
| </div> |
| </div> |
| |
| |
| </div> |
| |
| </div> |
| </div> |
| <div class="sphinxsidebar" role="navigation" aria-label="main navigation"> |
| <div class="sphinxsidebarwrapper"> |
| <h1 class="logo"><a href="index.html">psa_crypto_api</a></h1> |
| |
| |
| |
| |
| |
| |
| |
| |
| <h3>Navigation</h3> |
| <ul class="current"> |
| <li class="toctree-l1 current"><a class="current reference internal" href="#">Introduction</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="#design-goals">Design goals</a><ul> |
| <li class="toctree-l2"><a class="reference internal" href="#suitable-for-constrained-devices">Suitable for constrained devices</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="#a-keystore-interface">A keystore interface</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="#optional-isolation">Optional isolation</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="#choice-of-algorithms">Choice of algorithms</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="#ease-of-use">Ease of use</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="#example-use-cases">Example use cases</a><ul> |
| <li class="toctree-l3"><a class="reference internal" href="#network-security-tls">Network Security (TLS)</a></li> |
| <li class="toctree-l3"><a class="reference internal" href="#secure-storage">Secure Storage</a></li> |
| <li class="toctree-l3"><a class="reference internal" href="#network-credentials">Network Credentials</a></li> |
| <li class="toctree-l3"><a class="reference internal" href="#device-pairing">Device Pairing</a></li> |
| <li class="toctree-l3"><a class="reference internal" href="#secure-boot">Secure Boot</a></li> |
| <li class="toctree-l3"><a class="reference internal" href="#attestation">Attestation</a></li> |
| <li class="toctree-l3"><a class="reference internal" href="#factory-provisioning">Factory Provisioning</a></li> |
| </ul> |
| </li> |
| </ul> |
| </li> |
| <li class="toctree-l1"><a class="reference internal" href="#functionality-overview">Functionality overview</a><ul> |
| <li class="toctree-l2"><a class="reference internal" href="#library-management">Library management</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="#key-management">Key management</a><ul> |
| <li class="toctree-l3"><a class="reference internal" href="#volatile-keys">Volatile keys</a></li> |
| <li class="toctree-l3"><a class="reference internal" href="#persistent-keys">Persistent keys</a></li> |
| <li class="toctree-l3"><a class="reference internal" href="#recommendations-of-minimum-standards-for-key-management">Recommendations of minimum standards for key management</a></li> |
| </ul> |
| </li> |
| <li class="toctree-l2"><a class="reference internal" href="#usage-policies">Usage policies</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="#symmetric-cryptography">Symmetric cryptography</a><ul> |
| <li class="toctree-l3"><a class="reference internal" href="#multipart-operations">Multipart operations</a></li> |
| <li class="toctree-l3"><a class="reference internal" href="#authenticated-encryption">Authenticated encryption</a></li> |
| </ul> |
| </li> |
| <li class="toctree-l2"><a class="reference internal" href="#key-derivation">Key derivation</a><ul> |
| <li class="toctree-l3"><a class="reference internal" href="#key-derivation-operations">Key derivation operations</a></li> |
| <li class="toctree-l3"><a class="reference internal" href="#key-derivation-function">Key derivation function</a></li> |
| </ul> |
| </li> |
| <li class="toctree-l2"><a class="reference internal" href="#asymmetric-cryptography">Asymmetric cryptography</a><ul> |
| <li class="toctree-l3"><a class="reference internal" href="#asymmetric-encryption">Asymmetric encryption</a></li> |
| <li class="toctree-l3"><a class="reference internal" href="#hash-and-sign">Hash-and-sign</a></li> |
| <li class="toctree-l3"><a class="reference internal" href="#key-agreement">Key agreement</a></li> |
| </ul> |
| </li> |
| <li class="toctree-l2"><a class="reference internal" href="#randomness-and-key-generation">Randomness and key generation</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="#future-additions">Future additions</a></li> |
| </ul> |
| </li> |
| <li class="toctree-l1"><a class="reference internal" href="#sample-architectures">Sample architectures</a><ul> |
| <li class="toctree-l2"><a class="reference internal" href="#single-partition-architecture">Single-partition architecture</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="#cryptographic-token-and-single-application-processor">Cryptographic token and single-application processor</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="#cryptoprocessor-with-no-key-storage">Cryptoprocessor with no key storage</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="#multi-client-cryptoprocessor">Multi-client cryptoprocessor</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="#multi-cryptoprocessor-architecture">Multi-cryptoprocessor architecture</a></li> |
| </ul> |
| </li> |
| <li class="toctree-l1"><a class="reference internal" href="#library-conventions">Library conventions</a><ul> |
| <li class="toctree-l2"><a class="reference internal" href="#error-handling">Error handling</a><ul> |
| <li class="toctree-l3"><a class="reference internal" href="#return-status">Return status</a></li> |
| <li class="toctree-l3"><a class="reference internal" href="#behavior-on-error">Behavior on error</a></li> |
| </ul> |
| </li> |
| <li class="toctree-l2"><a class="reference internal" href="#parameter-conventions">Parameter conventions</a><ul> |
| <li class="toctree-l3"><a class="reference internal" href="#pointer-conventions">Pointer conventions</a></li> |
| <li class="toctree-l3"><a class="reference internal" href="#input-buffer-sizes">Input buffer sizes</a></li> |
| <li class="toctree-l3"><a class="reference internal" href="#output-buffer-sizes">Output buffer sizes</a></li> |
| <li class="toctree-l3"><a class="reference internal" href="#overlap-between-parameters">Overlap between parameters</a></li> |
| <li class="toctree-l3"><a class="reference internal" href="#stability-of-parameters">Stability of parameters</a></li> |
| </ul> |
| </li> |
| <li class="toctree-l2"><a class="reference internal" href="#key-types-and-algorithms">Key types and algorithms</a><ul> |
| <li class="toctree-l3"><a class="reference internal" href="#structure-of-key-and-algorithm-types">Structure of key and algorithm types</a></li> |
| </ul> |
| </li> |
| <li class="toctree-l2"><a class="reference internal" href="#concurrent-calls">Concurrent calls</a></li> |
| </ul> |
| </li> |
| <li class="toctree-l1"><a class="reference internal" href="#implementation-considerations">Implementation considerations</a><ul> |
| <li class="toctree-l2"><a class="reference internal" href="#implementation-specific-aspects-of-the-interface">Implementation-specific aspects of the interface</a><ul> |
| <li class="toctree-l3"><a class="reference internal" href="#implementation-profile">Implementation profile</a></li> |
| <li class="toctree-l3"><a class="reference internal" href="#implementation-specific-types">Implementation-specific types</a></li> |
| <li class="toctree-l3"><a class="reference internal" href="#implementation-specific-macros">Implementation-specific macros</a></li> |
| </ul> |
| </li> |
| <li class="toctree-l2"><a class="reference internal" href="#porting-to-a-platform">Porting to a platform</a><ul> |
| <li class="toctree-l3"><a class="reference internal" href="#platform-assumptions">Platform assumptions</a></li> |
| <li class="toctree-l3"><a class="reference internal" href="#platform-specific-types">Platform-specific types</a></li> |
| <li class="toctree-l3"><a class="reference internal" href="#cryptographic-hardware-support">Cryptographic hardware support</a></li> |
| </ul> |
| </li> |
| <li class="toctree-l2"><a class="reference internal" href="#security-requirements-and-recommendations">Security requirements and recommendations</a><ul> |
| <li class="toctree-l3"><a class="reference internal" href="#error-detection">Error detection</a></li> |
| <li class="toctree-l3"><a class="reference internal" href="#memory-cleanup">Memory cleanup</a></li> |
| <li class="toctree-l3"><a class="reference internal" href="#safe-outputs-on-error">Safe outputs on error</a></li> |
| <li class="toctree-l3"><a class="reference internal" href="#attack-resistance">Attack resistance</a></li> |
| </ul> |
| </li> |
| <li class="toctree-l2"><a class="reference internal" href="#other-implementation-considerations">Other implementation considerations</a><ul> |
| <li class="toctree-l3"><a class="reference internal" href="#philosophy-of-resource-management">Philosophy of resource management</a></li> |
| </ul> |
| </li> |
| </ul> |
| </li> |
| <li class="toctree-l1"><a class="reference internal" href="#usage-considerations">Usage considerations</a><ul> |
| <li class="toctree-l2"><a class="reference internal" href="#security-recommendations">Security recommendations</a><ul> |
| <li class="toctree-l3"><a class="reference internal" href="#always-check-for-errors">Always check for errors</a></li> |
| <li class="toctree-l3"><a class="reference internal" href="#shared-memory-and-concurrency">Shared memory and concurrency</a></li> |
| <li class="toctree-l3"><a class="reference internal" href="#cleaning-up-after-use">Cleaning up after use</a></li> |
| </ul> |
| </li> |
| </ul> |
| </li> |
| <li class="toctree-l1"><a class="reference internal" href="from_doxygen.html">Implementation-specific definitions</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="from_doxygen.html#library-initialization">Library initialization</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="from_doxygen.html#key-attributes">Key attributes</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="from_doxygen.html#key-management">Key management</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="from_doxygen.html#key-import-and-export">Key import and export</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="from_doxygen.html#message-digests">Message digests</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="from_doxygen.html#message-authentication-codes">Message authentication codes</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="from_doxygen.html#symmetric-ciphers">Symmetric ciphers</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="from_doxygen.html#authenticated-encryption-with-associated-data-aead">Authenticated encryption with associated data (AEAD)</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="from_doxygen.html#asymmetric-cryptography">Asymmetric cryptography</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="from_doxygen.html#key-derivation-and-pseudorandom-generation">Key derivation and pseudorandom generation</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="from_doxygen.html#random-generation">Random generation</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="from_doxygen.html#error-codes">Error codes</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="from_doxygen.html#key-and-algorithm-types">Key and algorithm types</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="from_doxygen.html#key-lifetimes">Key lifetimes</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="from_doxygen.html#key-policies">Key policies</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="from_doxygen.html#key-derivation">Key derivation</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="from_doxygen.html#other-definitions">Other definitions</a></li> |
| </ul> |
| |
| <div class="relations"> |
| <h3>Related Topics</h3> |
| <ul> |
| <li><a href="index.html">Documentation overview</a><ul> |
| <li>Previous: <a href="index.html" title="previous chapter">PSA Cryptography API Specification</a></li> |
| <li>Next: <a href="from_doxygen.html" title="next chapter">Implementation-specific definitions</a></li> |
| </ul></li> |
| </ul> |
| </div> |
| <div id="searchbox" style="display: none" role="search"> |
| <h3>Quick search</h3> |
| <div class="searchformwrapper"> |
| <form class="search" action="search.html" method="get"> |
| <input type="text" name="q" /> |
| <input type="submit" value="Go" /> |
| <input type="hidden" name="check_keywords" value="yes" /> |
| <input type="hidden" name="area" value="default" /> |
| </form> |
| </div> |
| </div> |
| <script type="text/javascript">$('#searchbox').show(0);</script> |
| |
| |
| |
| |
| |
| |
| |
| |
| </div> |
| </div> |
| <div class="clearer"></div> |
| </div> |
| <div class="footer"> |
| ©2019, Arm. |
| |
| | |
| Powered by <a href="http://sphinx-doc.org/">Sphinx 1.8.5</a> |
| & <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.12</a> |
| |
| | |
| <a href="_sources/general.rst.txt" |
| rel="nofollow">Page source</a> |
| </div> |
| |
| |
| |
| |
| </body> |
| </html> |