Update PSA API specification to 1.0.0
Generated from the PSA Crypto API Dockerfile at tag psa-crypto-api-1.0.0
diff --git a/docs/html/_sources/overview/conventions.rst.txt b/docs/html/_sources/overview/conventions.rst.txt
new file mode 100644
index 0000000..8baf991
--- /dev/null
+++ b/docs/html/_sources/overview/conventions.rst.txt
@@ -0,0 +1,281 @@
+Library conventions
+-------------------
+
+Error handling
+~~~~~~~~~~~~~~
+
+Return status
+^^^^^^^^^^^^^
+
+Almost all functions return a status indication of type `psa_status_t`. This
+is an enumeration of integer values, with ``0`` (`PSA_SUCCESS`) indicating
+successful operation and other values indicating errors. The exceptions are
+functions which only access objects that are intended to be implemented as
+simple data structures. Such functions cannot fail and either return
+``void`` or a data value.
+
+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 can make different choices, for example to favor code size over
+ease of debugging or vice versa.
+
+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 developers need to be aware that undefined behavior conditions cannot be detected in general.
+
+Behavior on error
+^^^^^^^^^^^^^^^^^
+
+All function calls must be implemented atomically:
+
+- When a function returns a type other than `psa_status_t`, the requested
+ action has been carried out.
+- When a function returns the status `PSA_SUCCESS`, the requested action has
+ been carried out.
+- When a function returns another status of type `psa_status_t`, 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.
+
+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:
+
+- The status `PSA_ERROR_BAD_STATE` indicates that a parameter was not in a
+ valid state for the requested action. This parameter might 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
+ ``psa_abort_xxx()`` function.
+- The status `PSA_ERROR_INSUFFICIENT_DATA` indicates that a key
+ derivation object has reached its maximum capacity. The key derivation
+ operation might have been modified by the call. Any further attempt to obtain
+ output from the key derivation operation will return
+ `PSA_ERROR_INSUFFICIENT_DATA`.
+- The status `PSA_ERROR_COMMUNICATION_FAILURE` 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.
+- The statuses `PSA_ERROR_STORAGE_FAILURE`, `PSA_ERROR_DATA_CORRUPT`, `PSA_ERROR_HARDWARE_FAILURE`
+ and `PSA_ERROR_CORRUPTION_DETECTED` might indicate data corruption in the
+ system state. When a function returns one of these statuses, the system state
+ might have changed from its previous state before the function call, even
+ though the function call failed.
+- Some system states cannot be rolled back, for example, the internal state of
+ the random number generator or the content of access logs.
+
+Unless otherwise documented, the content of output parameters is not defined
+when a function returns a status other than `PSA_SUCCESS`. It is recommended
+that implementations set output parameters to safe defaults to avoid leaking
+confidential data and limit risk, in case an application does not properly
+handle all errors.
+
+Parameter conventions
+~~~~~~~~~~~~~~~~~~~~~
+
+Pointer conventions
+^^^^^^^^^^^^^^^^^^^
+
+Unless explicitly stated in the documentation of a function, all pointers must
+be valid pointers to an object of the specified type.
+
+A parameter is considered a **buffer** if it points to an array of bytes. A
+buffer parameter always has the type ``uint8_t *`` or ``const uint8_t *``, and
+always has an associated parameter indicating the size of the array. Note that a
+parameter of type ``void *`` is never considered a buffer.
+
+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. Passing a null
+pointer as a function parameter in other cases is expected to abort the caller
+on implementations where this is the normal behavior for a null pointer
+dereference.
+
+Pointers to input parameters can 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
+:title:`stability-of-parameters` section.
+
+Input buffer sizes
+^^^^^^^^^^^^^^^^^^
+
+For input buffers, the parameter convention is:
+
+``const uint8_t *foo``
+ Pointer to the first byte of the data. The pointer
+ can be invalid if the buffer size is ``0``.
+
+``size_t foo_length``
+ Size of the buffer in bytes.
+
+The interface never uses input-output buffers.
+
+Output buffer sizes
+^^^^^^^^^^^^^^^^^^^
+
+For output buffers, the parameter convention is:
+
+``uint8_t *foo``
+ Pointer to the first byte of the data. The pointer can be
+ invalid if the buffer size is ``0``.
+
+``size_t foo_size``
+ The size of the buffer in bytes.
+
+``size_t *foo_length``
+ On successful return, contains the length of the
+ output in bytes.
+
+The content of the data buffer and of ``*foo_length`` on errors is unspecified,
+unless explicitly mentioned in the function description. They might be unmodified
+or set to a safe default. On successful completion, the content of the buffer
+between the offsets ``*foo_length`` and ``foo_size`` is also unspecified.
+
+Functions return `PSA_ERROR_BUFFER_TOO_SMALL` 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.
+
+Some functions always return exactly as much data as the size of the output
+buffer. In this case, the parameter convention changes to:
+
+``uint8_t *foo``
+ Pointer to the first byte of the output. The pointer can be
+ invalid if the buffer size is ``0``.
+
+``size_t foo_length``
+ The number of bytes to return in ``foo`` if
+ successful.
+
+Overlap between parameters
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Output parameters that are not buffers must not overlap with any input buffer or
+with any other output parameter. Otherwise, the behavior is undefined.
+
+Output buffers can overlap with input buffers. In this event, the implementation
+must return the same result as if the buffers did not overlap. The
+implementation must behave as if it had copied all the inputs into temporary
+memory, as far as the result is concerned. However, it is possible that overlap
+between parameters will affect the performance of a function call. Overlap might
+also affect memory management security if the buffer is located in memory that
+the caller shares with another security context, as described in the
+:title:`stability-of-parameters` section.
+
+.. _stability-of-parameters:
+
+Stability of parameters
+^^^^^^^^^^^^^^^^^^^^^^^
+
+In some environments, it is possible for the content of a parameter to change
+while a function is executing. It might 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 the assumptions that an implementation can make about
+function parameters, and the guarantees that the implementation must provide
+about how it accesses parameters.
+
+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 must not be modified during the
+execution, and the value of an output parameter is undetermined until the
+function returns. The implementation can read an input parameter that is not a
+buffer multiple times and expect to read the same data. The implementation can
+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.
+
+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.
+
+Unless otherwise specified, the implementation must not keep a reference to any
+parameter once a function call has returned.
+
+Key types and algorithms
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+Types of cryptographic keys and cryptographic algorithms are encoded separately.
+Each is encoded by using an integral type: `psa_key_type_t` and
+`psa_algorithm_t`, respectively.
+
+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 might depend on the key type. For
+example, the algorithm `PSA_ALG_GCM` 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.
+
+Key types do not encode the key size. For example, AES-128, AES-192 and AES-256
+share a key type `PSA_KEY_TYPE_AES`.
+
+Structure of key and algorithm types
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+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 might
+only care about the encoding for code size optimization.
+
+The encodings follows a few conventions:
+
+- 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.
+- The next few highest bits indicate the corresponding algorithm category:
+ hash, MAC, symmetric cipher, asymmetric encryption, and so on.
+- The following bits identify a family of algorithms in a category-dependent
+ manner.
+- 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.
+
+.. _concurrency:
+
+Concurrent calls
+~~~~~~~~~~~~~~~~
+
+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:
+
+- 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.
+- If a call destroys a key, then no other call must destroy or use that key.
+ *Using*, in this context, includes all functions of multi-part operations
+ which have used the key as an input in a previous function.
+- Concurrent calls that use the same key are permitted.
+- Concurrent calls must not use the same operation object.
+
+If any of these constraints are violated, the behavior is undefined.
+
+If the application modifies an input parameter while a function call is in
+progress, the behavior is undefined.
+
+Individual implementations can provide additional guarantees.
diff --git a/docs/html/_sources/overview/functionality.rst.txt b/docs/html/_sources/overview/functionality.rst.txt
new file mode 100644
index 0000000..004f8bc
--- /dev/null
+++ b/docs/html/_sources/overview/functionality.rst.txt
@@ -0,0 +1,647 @@
+.. _functionality-overview:
+
+Functionality overview
+----------------------
+
+This section provides a high-level overview of the functionality provided by the
+interface defined in this specification. Refer to the `API definition
+<api-reference>` for a detailed description.
+
+`future` describes features that might be included in future versions of this
+specification.
+
+Due to the modularity of the interface, almost every part of the library is
+optional. The only mandatory function is `psa_crypto_init()`.
+
+Library management
+~~~~~~~~~~~~~~~~~~
+
+Applications must call `psa_crypto_init()` to initialize the library before
+using any other function.
+
+Key management
+~~~~~~~~~~~~~~
+
+Applications always access keys indirectly via an identifier, and can perform
+operations using a key without accessing the key material. This allows keys to
+be *non-extractable*, where an application can use a key but is not permitted to
+obtain the key material. Non-extractable keys are bound to the device, can be
+rate-limited and can have their usage restricted by policies.
+
+Each key has a set of attributes that describe the key and the policy for using
+the key. A `psa_key_attributes_t` object contains all of the attributes, which
+is used when creating a key and when querying key attributes.
+
+Each key has a *lifetime* that determines when the key material is destroyed.
+There are two types of lifetimes: `volatile <volatile-keys>` and
+`persistent <persistent-keys>`.
+
+.. _volatile-keys:
+
+Volatile keys
+^^^^^^^^^^^^^
+
+A *volatile* key exists until it explicitly destroyed with `psa_destroy_key()`
+or until the application terminates, which conceptually destroys all of its
+volatile keys.
+
+Conceptually, a volatile key is stored in RAM. Volatile keys have the
+lifetime `PSA_KEY_LIFETIME_VOLATILE`.
+
+To create a volatile key:
+
+1. Populate a `psa_key_attributes_t` object with the required type, size, policy
+ and other key attributes.
+2. Create the key with `psa_import_key()`, `psa_generate_key()`,
+ `psa_key_derivation_output_key()` or `psa_copy_key()`. If successful, these
+ functions output a transient `key identifier <key-ids>`.
+
+To destroy a volatile key, call `psa_destroy_key()` with the key identifier.
+
+.. _persistent-keys:
+
+Persistent keys
+^^^^^^^^^^^^^^^
+
+A *persistent* key exists until it explicitly destroyed with `psa_destroy_key()`
+or until it is wiped by the reset or destruction of the device.
+
+Each persistent key has a permanent 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 when
+using the key.
+
+Persistent keys can be stored in different storage areas; this is indicated
+through different lifetime values. This specification defines a single lifetime
+value `PSA_KEY_LIFETIME_PERSISTENT` which corresponds to a default storage
+area. Implementations can define alternative lifetime values corresponding to
+different storage areas with different retention policies, or to secure elements
+with different security characteristics.
+
+To create a persistent key:
+
+1. Populate a `psa_key_attributes_t` object with the key’s type, size, policy
+ and other attributes.
+2. In the attributes object, set the desired lifetime and persistent identifier
+ for the key.
+3. Create the key with one of the *key creation functions*:
+
+ * `psa_import_key()`
+ * `psa_generate_key()`
+ * `psa_key_derivation_output_key()`
+ * `psa_copy_key()`
+
+ If successful, these functions output the `key identifier <key-ids>`
+ that was specified by the application in step 2.
+
+To access an existing persistent key: use the key identifier in any API that
+requires a key.
+
+To remove cached copies of key material for persistent keys created with the
+`PSA_KEY_USAGE_CACHE` policy: call `psa_purge_key()` with the key identifier.
+
+To destroy a persistent key: call `psa_destroy_key()` with the key identifier.
+Destroying a persistent key permanently removes it from memory and storage.
+
+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.
+
+.. _key-ids:
+
+Key identifiers
+^^^^^^^^^^^^^^^
+
+Key identifiers are integral values that act as permanent names for persistent
+keys, or as transient references to volatile keys. Key identifiers use the
+`psa_key_id_t` type, and the range of identifier values is divided as follows:
+
+:code:`PSA_KEY_ID_NULL = 0`
+ Reserved as an invalid key identifier.
+:code:`PSA_KEY_ID_USER_MIN - PSA_KEY_ID_USER_MAX`
+ Applications can freely choose persistent key identifiers in this range.
+:code:`PSA_KEY_ID_VENDOR_MIN - PSA_KEY_ID_VENDOR_MAX`
+ Implementations can define additional persistent key identifiers in this
+ range, and must allocate any volatile key identifiers from this range.
+
+Key identifiers outside these ranges are reserved for future use.
+
+Key identifiers are output from a successful call to one of
+the key creation functions. For persistent keys, this is the same identifier
+as the one specified in the key attributes used to create the key.
+The key identifier remains valid until it is invalidated by passing it to
+`psa_destroy_key()`. A volatile key identifier must not be used after it has been
+invalidated.
+
+Valid key identifiers must have distinct values within the same application. If
+the implementation provides `caller isolation <isolation>`, then key
+identifiers are local to each application. That is, the same key identifier in two
+applications corresponds to two different keys.
+
+If an invalid key identifier is provided as a parameter in any function, the
+function will return `PSA_ERROR_INVALID_HANDLE`; except for the special case of
+calling :code:`psa_destroy_key(PSA_KEY_ID_NULL)`, which has no effect and always
+returns `PSA_SUCCESS`.
+
+There must be a matching call to `psa_destroy_key()` for each successful call
+to a create a volatile key.
+
+A call to `psa_destroy_key()` destroys the key material, and will cause any active
+operations that are using the key to fail. Therefore an application must not
+destroy a key while an operation using that key is in progress, unless the
+application is prepared to handle a failure of the operation.
+
+Recommendations of minimum standards for key management
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Most implementations provide the following functions:
+
+* `psa_import_key()`. The 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.
+
+* `psa_get_key_attributes()` and the ``psa_get_key_xxx()`` accessor functions.
+ They are easy to implement, and it is difficult to write applications and to
+ diagnose issues without being able to check the metadata.
+
+* `psa_export_public_key()`. This function is usually provided if the
+ implementation supports any asymmetric algorithm, since public-key
+ cryptography often requires the delivery of a public key that is associated
+ with a protected private key.
+
+* `psa_export_key()`. However, highly constrained implementations that are
+ designed to work only with short-term keys, or only with long-term
+ non-extractable keys, do not need to provide this function.
+
+Usage policies
+~~~~~~~~~~~~~~
+
+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 `psa_key_attributes_t` object.
+
+The usage flags are encoded in a bitmask, which has the type
+`psa_key_usage_t`. Four kinds of usage flag can be specified:
+
+* The extractable flag `PSA_KEY_USAGE_EXPORT` determines whether the key
+ material can be extracted.
+* The copyable flag `PSA_KEY_USAGE_COPY` determines whether the key material
+ can be copied into a new key, which can have a different lifetime or a more
+ restrictive policy.
+* The cacheable flag `PSA_KEY_USAGE_CACHE` determines whether the
+ implementation is permitted to retain non-essential copies of the
+ key material in RAM. This policy only applies to persistent keys. See also
+ :title:`key-material`.
+* The other usage flags, for example, `PSA_KEY_USAGE_ENCRYPT` and `PSA_KEY_USAGE_SIGN_MESSAGE`,
+ determine whether the corresponding operation is permitted on the key.
+
+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 consistent with both common practice and
+security good practice.
+
+A highly constrained implementation might 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.
+
+Symmetric cryptography
+~~~~~~~~~~~~~~~~~~~~~~
+
+This specification defines interfaces for the following types of symmetric
+cryptographic operation:
+
+* Message digests, commonly known as hash functions.
+* Message authentication codes (MAC).
+* Symmetric ciphers.
+* Authenticated encryption with associated data (AEAD).
+
+For each type of symmetric cryptographic operation, the API includes:
+
+* A pair of *single-part* functions. For example, compute and verify, or
+ encrypt and decrypt.
+* A series of functions that permit *multi-part operations*.
+
+Single-part Functions
+^^^^^^^^^^^^^^^^^^^^^
+
+Single-part functions are APIs that implement the cryptographic operation in a
+single function call. This is the easiest API to use when all of the inputs and
+outputs fit into the application memory.
+
+Some use cases involve messages that are too large to be assembled in memory, or
+require non-default configuration of the algorithm. These use cases require the
+use of a :title:`multi-part operation <multi-part-operations>`.
+
+.. _multi-part-operations:
+
+Multi-part operations
+^^^^^^^^^^^^^^^^^^^^^
+
+Multi-part operations are APIs which split a single cryptographic operation into
+a sequence of separate steps. This enables fine control over the configuration
+of the cryptographic operation, and allows the message data to be processed in
+fragments instead of all at once. For example, the following situations require
+the use of a multi-part operation:
+
+- Processing messages that cannot be assembled in memory.
+- Using a deterministic IV for unauthenticated encryption.
+- Providing the IV separately for unauthenticated encryption or decryption.
+- Separating the AEAD authentication tag from the cipher text.
+
+Each multi-part operation defines a specific object type to maintain the state
+of the operation. These types are implementation-defined. All multi-part
+operations follow the same pattern of use:
+
+1. **Allocate:** Allocate memory for an operation object of the appropriate
+ type. The application can use any allocation strategy: stack, heap, static, etc.
+
+2. **Initialize:** Initialize or assign the operation object by one of the
+ following methods:
+
+ - Set it to logical zero. This is automatic for static and global
+ variables. Explicit initialization must use the associated
+ ``PSA_xxx_INIT`` macro as the type is implementation-defined.
+ - Set it to all-bits zero. This is automatic if the object was
+ allocated with ``calloc()``.
+ - Assign the value of the associated macro ``PSA_xxx_INIT``.
+ - Assign the result of calling the associated function
+ ``psa_xxx_init()``.
+
+ The resulting object is now *inactive*.
+
+ It is an error to initialize an operation object that is in *active* or
+ *error* states. This can leak memory or other resources.
+
+3. **Setup:** Start a new multi-part operation on an *inactive* operation
+ object. Each operation object will define one or more setup functions to
+ start a specific operation.
+
+ On success, a setup function will put an operation object into an *active*
+ state. On failure, the operation object will remain *inactive*.
+
+4. **Update:** Update an *active* operation object. The update function can
+ provide additional parameters, supply data for processing or generate
+ outputs.
+
+ On success, the operation object remains *active*. On failure, the
+ operation object will enter an *error* state.
+
+5. **Finish:** To end the operation, call the applicable finishing function.
+ This will take any final inputs, produce any final outputs, and then
+ release any resources associated with the operation.
+
+ On success, the operation object returns to the *inactive* state. On
+ failure, the operation object will enter an *error* state.
+
+An operation can be aborted at any stage during its use by calling the
+associated ``psa_xxx_abort()`` function. This will release any resources
+associated with the operation and return the operation object to the *inactive*
+state.
+
+Any error that occurs to an operation while it is in an *active* state will
+result in the operation entering an *error* state. The application must call the
+associated ``psa_xxx_abort()`` function to release the operation resources and
+return the object to the *inactive* state.
+
+Once an operation object is returned to the *inactive* state, it can be reused
+by calling one of the applicable setup functions again.
+
+If a multi-part operation object is not initialized before use, the behavior is
+undefined.
+
+If a multi-part operation function determines that the operation object is not in
+any valid state, it can return `PSA_ERROR_CORRUPTION_DETECTED`.
+
+If a multi-part operation function is called with an operation object in the
+wrong state, the function will return `PSA_ERROR_BAD_STATE` and the operation
+object will enter the *error* state.
+
+It is safe to move a multi-part operation object to a different memory location,
+for example, using a bitwise copy, and then to use the object in the new
+location. For example, an application can allocate an operation object on the
+stack and return it, or the operation object can be allocated within memory
+managed by a garbage collector. However, this does not permit the following
+behaviors:
+
+- Moving the object while a function is being called on the object. This is
+ not safe. See also `concurrency`.
+- Working with both the original and the copied operation objects. This
+ requires cloning the operation, which is only available for hash operations
+ using `psa_hash_clone()`.
+
+Each type of multi-part operation can have multiple *active* states.
+Documentation for the specific operation describes the configuration and update
+functions, and any requirements about their usage and ordering.
+
+Message digests (Hashes)
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+The single-part hash functions are:
+
+- `psa_hash_compute()` to calculate the hash of a message.
+- `psa_hash_compare()` to compare the hash of a message with a reference value.
+
+The `psa_hash_operation_t` `multi-part operation <multi-part-operations>`
+allows messages to be processed in fragments:
+
+1. Initialize the `psa_hash_operation_t` object to zero, or by assigning the
+ value of the associated macro `PSA_HASH_OPERATION_INIT`.
+2. Call `psa_hash_setup()` to specify the required hash algorithm, call
+ `psa_hash_clone()` to duplicate the state of *active* `psa_hash_operation_t`
+ object, or call `psa_hash_resume()` to restart a hash operation with the
+ output from a previously suspended hash operation.
+3. Call the `psa_hash_update()` function on successive chunks of the message.
+4. At the end of the message, call the required finishing function:
+
+ - To suspend the hash operation and extract a hash suspend state,
+ call `psa_hash_suspend()`. The output state can subsequently be used
+ to resume the hash operation.
+ - To calculate the digest of a message, call `psa_hash_finish()`.
+ - To verify the digest of a message against a reference value, call
+ `psa_hash_verify()`.
+
+To abort the operation or recover from an error, call `psa_hash_abort()`.
+
+Message authentication codes (MACs)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The single-part MAC functions are:
+
+- `psa_mac_compute()` to calculate the MAC of a message.
+- `psa_mac_verify()` to compare the MAC of a message with a reference value.
+
+The `psa_mac_operation_t` `multi-part operation <multi-part-operations>`
+allows messages to be processed in fragments:
+
+1. Initialize the `psa_mac_operation_t` object to zero, or by assigning the
+ value of the associated macro `PSA_MAC_OPERATION_INIT`.
+2. Call `psa_mac_sign_setup()` or `psa_mac_verify_setup()` to specify the
+ algorithm and key.
+3. Call the `psa_mac_update()` function on successive chunks of the message.
+4. At the end of the message, call the required finishing function:
+
+ - To calculate the MAC of the message, call `psa_mac_sign_finish()`.
+ - To verify the MAC of the message against a reference value, call
+ `psa_mac_verify_finish()`.
+
+To abort the operation or recover from an error, call `psa_mac_abort()`.
+
+Encryption and decryption
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. note::
+
+ The unauthenticated cipher API is provided to implement legacy protocols and
+ for use cases where the data integrity and authenticity is guaranteed by
+ non-cryptographic means. It is recommended that newer protocols use
+ :title:`func-aead`.
+
+The single-part functions for encrypting or decrypting a message using an
+unauthenticated symmetric cipher are:
+
+- `psa_cipher_encrypt()` to encrypt a message using an unauthenticated symmetric
+ cipher. The encryption function generates a random IV. Use the multi-part API
+ to provide a deterministic IV: this is not secure in general, but
+ can be secure in some conditions that depend on the algorithm.
+- `psa_cipher_decrypt()` to decrypt a message using an unauthenticated symmetric
+ cipher.
+
+The `psa_cipher_operation_t` `multi-part operation <multi-part-operations>`
+permits alternative initialization parameters and allows messages to be
+processed in fragments:
+
+1. Initialize the `psa_cipher_operation_t` object to zero, or by assigning the
+ value of the associated macro `PSA_CIPHER_OPERATION_INIT`.
+2. Call `psa_cipher_encrypt_setup()` or `psa_cipher_decrypt_setup()` to specify the
+ algorithm and key.
+3. Provide additional parameters:
+
+ - When encrypting data, generate or set an initialization vector (IV),
+ nonce, or similar initial value such as an initial counter value. To
+ generate a random IV, which is recommended in most protocols, call
+ `psa_cipher_generate_iv()`. To set the IV, call `psa_cipher_set_iv()`.
+ - When decrypting, set the IV or nonce. To set the IV, call
+ `psa_cipher_set_iv()`.
+4. Call the `psa_cipher_update()` function on successive chunks of the message.
+5. Call `psa_cipher_finish()` to complete the operation and return any final
+ output.
+
+To abort the operation or recover from an error, call `psa_cipher_abort()`.
+
+.. _func-aead:
+
+Authenticated encryption (AEAD)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The single-part AEAD functions are:
+
+- `psa_aead_encrypt()` to encrypt a message using an authenticated symmetric
+ cipher.
+- `psa_aead_decrypt()` to decrypt a message using an authenticated symmetric
+ cipher.
+
+These functions follow the interface recommended by :RFC:`5116`.
+
+The encryption function requires a nonce to be provided. To generate a random
+nonce, either call `psa_generate_random()` or use the AEAD multi-part API.
+
+The `psa_aead_operation_t` `multi-part operation <multi-part-operations>`
+permits alternative initialization parameters and allows messages to be
+processed in fragments:
+
+1. Initialize the `psa_aead_operation_t` object to zero, or by assigning the
+ value of the associated macro `PSA_AEAD_OPERATION_INIT`.
+2. Call `psa_aead_encrypt_setup()` or `psa_aead_decrypt_setup()` to specify the
+ algorithm and key.
+3. Provide additional parameters:
+
+ - If the algorithm requires it, call `psa_aead_set_lengths()` to specify the
+ length of the non-encrypted and encrypted inputs to the operation.
+ - When encrypting, call either `psa_aead_generate_nonce()` or
+ `psa_aead_set_nonce()` to generate or set the nonce.
+ - When decrypting, call `psa_aead_set_nonce()` to set the nonce.
+4. Call `psa_aead_update_ad()` zero or more times with fragments of the
+ non-encrypted additional data.
+5. Call `psa_aead_update()` zero or more times with fragments of the plaintext
+ or ciphertext to encrypt or decrypt.
+6. At the end of the message, call the required finishing function:
+
+ - To complete an encryption operation, call `psa_aead_finish()` to compute
+ and return authentication tag.
+ - To complete a decryption operation, call `psa_aead_verify()` to
+ compute the authentication tag and verify it against a reference value.
+
+To abort the operation or recover from an error, call `psa_aead_abort()`.
+
+Having a multi-part interface to authenticated encryption raises specific issues.
+
+Multi-part authenticated decryption produces partial results that are not
+authenticated. Applications must not use or expose partial results of
+authenticated decryption until `psa_aead_verify()` has returned a success
+status and must destroy all partial results without revealing them if
+`psa_aead_verify()` returns a failure status. Revealing partial results, either directly or indirectly through the application’s behavior, can compromise the
+confidentiality of all inputs that are encrypted with the same key.
+
+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 multi-part 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 `psa_aead_set_lengths()` to provide
+these lengths before providing input.
+
+.. _key-derivation:
+
+Key derivation
+^^^^^^^^^^^^^^
+
+A key derivation 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 produce the same output.
+
+A key derivation consists of two phases:
+
+1. Input collection. This is sometimes known as *extraction*: the operation
+ “extracts” information from the inputs to generate a pseudorandom
+ intermediate secret value.
+2. Output generation. This is sometimes known as *expansion*: the operation
+ “expands” the intermediate secret value to the desired output length.
+
+The specification defines a `multi-part operation <multi-part-operations>`
+API for key derivation that allows for multiple key and non-key outputs to be
+extracted from a single derivation operation object.
+
+In an implementation with `isolation <isolation>`, 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 key cannot be recovered
+outside the isolation boundary.
+
+Applications use the `psa_key_derivation_operation_t` type to create key
+derivation operations. The operation object is used as follows:
+
+1. Initialize a `psa_key_derivation_operation_t` object to zero or to
+ `PSA_KEY_DERIVATION_OPERATION_INIT`.
+2. Call `psa_key_derivation_setup()` to select a key derivation algorithm.
+3. Call the functions `psa_key_derivation_input_bytes()` and
+ `psa_key_derivation_input_key()`, or `psa_key_derivation_key_agreement()` 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 provided. The documentation for each key
+ derivation algorithm describes the expected inputs for that algorithm and
+ in what order to pass them.
+4. Optionally, call `psa_key_derivation_set_capacity()` to set a limit on the
+ amount of data that can be output from the key derivation operation.
+5. Call `psa_key_derivation_output_key()` to create a derived key, or
+ `psa_key_derivation_output_bytes()` to export the derived data. These
+ functions can be called multiple times to read successive output from the key
+ derivation, until the stream is exhausted when its capacity has been reached.
+6. Key derivation does not finish in the same way as other multi-part
+ operations. Call `psa_key_derivation_abort()` to release the key derivation
+ operation memory when the object is no longer required.
+
+To recover from an error, call `psa_key_derivation_abort()` to release the key
+derivation operation memory.
+
+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.
+
+Example of the symmetric cryptography API
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+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.
+
+1. Derive the message encryption material from the master key.
+
+ 1. Initialize a `psa_key_derivation_operation_t` object to zero or to
+ `PSA_KEY_DERIVATION_OPERATION_INIT`.
+ 2. Call `psa_key_derivation_setup()` with `PSA_ALG_HKDF` as the algorithm.
+ 3. Call `psa_key_derivation_input_key()` with the step
+ `PSA_KEY_DERIVATION_INPUT_SECRET` and the master key.
+ 4. Call `psa_key_derivation_input_bytes()` with the step
+ `PSA_KEY_DERIVATION_INPUT_INFO` and a public value that uniquely
+ identifies the message.
+ 5. Populate a `psa_key_attributes_t` object with the derived message
+ encryption key’s attributes.
+ 6. Call `psa_key_derivation_output_key()` to create the derived message key.
+ 7. Call `psa_key_derivation_output_bytes()` to generate the derived IV.
+ 8. Call `psa_key_derivation_abort()` to release the key derivation operation
+ memory.
+
+2. Encrypt the message with the derived material.
+
+ 1. Initialize a `psa_cipher_operation_t` object to zero or to
+ `PSA_CIPHER_OPERATION_INIT`.
+ 2. Call `psa_cipher_encrypt_setup()` with the derived message encryption key.
+ 3. Call `psa_cipher_set_iv()` using the derived IV retrieved above.
+ 4. Call `psa_cipher_update()` one or more times to encrypt the message.
+ 5. Call `psa_cipher_finish()` at the end of the message.
+
+3. Call `psa_destroy_key()` to clear the generated key.
+
+Asymmetric cryptography
+~~~~~~~~~~~~~~~~~~~~~~~
+
+This specification defines functions for asymmetric cryptography, including
+asymmetric encryption, asymmetric signature, and two-way key agreement.
+
+Asymmetric encryption
+^^^^^^^^^^^^^^^^^^^^^
+
+Asymmetric encryption is provided through the functions
+`psa_asymmetric_encrypt()` and `psa_asymmetric_decrypt()`.
+
+Hash-and-sign
+^^^^^^^^^^^^^
+
+The signature and verification functions `psa_sign_message()` and
+`psa_verify_message()` take a message as one of their inputs and perform a
+hash-and-sign algorithm.
+
+The functions `psa_sign_hash()` and `psa_verify_hash()` take a message hash as
+one of their inputs. This is useful for signing pre-computed hashes, or for
+implementing hash-and-sign using a :ref:`multi-part hash operation <hash-mp>`
+before signing the resulting hash. To determine which
+hash algorithm to use, call the macro `PSA_ALG_GET_HASH()` on the
+corresponding signature algorithm.
+
+Some hash-and-sign algorithms add padding to the message hash before completing
+the signing operation. The format of the padding that is used depends on the
+algorithm used to construct the signature.
+
+Key agreement
+^^^^^^^^^^^^^
+
+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.
+
+The recommended approach is to use a `key derivation
+operation <key-derivation>` with the `psa_key_derivation_key_agreement()`
+input function, which calculates a shared secret for the key derivation
+function.
+
+Where an application needs direct access to the shared secret, it can call
+`psa_raw_key_agreement()` instead. Note that in general the shared secret is not
+directly suitable for use as a key because it is biased.
+
+Randomness and key generation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+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 can 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.
+
+It is recommended that applications use `psa_generate_key()`,
+`psa_cipher_generate_iv()` or `psa_aead_generate_nonce()` to generate
+suitably-formatted random data, as applicable. In addition, the API includes a
+function `psa_generate_random()` to generate and extract arbitrary random data.
diff --git a/docs/html/_sources/overview/goals.rst.txt b/docs/html/_sources/overview/goals.rst.txt
new file mode 100644
index 0000000..48a2f75
--- /dev/null
+++ b/docs/html/_sources/overview/goals.rst.txt
@@ -0,0 +1,194 @@
+.. _design-goals:
+
+Design goals
+------------
+
+Suitable for constrained devices
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+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.
+
+- *Scalable*: devices only need to implement the functionality that they will
+ use.
+- *Modular*: larger devices implement larger subsets of the same interface,
+ rather than different interfaces.
+
+In this interface, all operations on unbounded amounts of data
+allow *multi-part* 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. As a result, this
+specification is suitable for very constrained devices, including those where
+memory is very limited.
+
+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.
+
+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.
+
+A keystore interface
+~~~~~~~~~~~~~~~~~~~~
+
+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 an identifier. The key
+material corresponding to that identifier 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.
+
+.. _isolation:
+
+Optional isolation
+~~~~~~~~~~~~~~~~~~
+
+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:
+
+- Process isolation in an operating system.
+- Partition isolation, either with a virtual machine or a partition manager.
+- Physical separation between devices.
+
+Communication between the frontend and backend is beyond the scope of this
+specification.
+
+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 **caller
+isolation**: it must ensure that assets of one frontend are not visible to any
+other frontend. The mechanism for identifying callers is beyond the scope of this
+specification. An implementation that provides caller isolation must document
+the identification mechanism. An implementation that provides isolation must
+document any implementation-specific extension of the API that enables frontend
+instances to share data in any form.
+
+In summary, there are three types of implementation:
+
+- 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.
+- 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.
+- 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.
+
+Choice of algorithms
+~~~~~~~~~~~~~~~~~~~~
+
+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.
+
+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.
+
+Another consequence is that the specification permits the use of algorithms, key
+sizes and other parameters that, while known to be insecure, might be necessary to
+support legacy protocols or legacy data. Where major weaknesses are known, the
+algorithm descriptions give applicable warnings. However, the lack of a warning
+both does not and cannot indicate that an algorithm is secure in all circumstances.
+Application developers need to research the security of the protocols and
+algorithms that they plan to use to determine if these meet their requirements.
+
+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.
+
+Ease of use
+~~~~~~~~~~~
+
+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.
+
+In particular, the code flows are designed to reduce the risk of dangerous
+misuse. The interface is designed in part to make it harder to misuse. Where
+possible, it is designed so that
+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.
+
+Example use cases
+~~~~~~~~~~~~~~~~~
+
+This section lists some of the use cases that were considered during the design
+of this API. This list is not exhaustive, nor are all implementations required to
+support all use cases.
+
+Network Security (TLS)
+^^^^^^^^^^^^^^^^^^^^^^
+
+The API provides all of the cryptographic primitives needed to establish TLS
+connections.
+
+Secure Storage
+^^^^^^^^^^^^^^
+
+The API provides all primitives related to storage encryption, block or
+file-based, with master encryption keys stored inside a key store.
+
+Network Credentials
+^^^^^^^^^^^^^^^^^^^
+
+The API provides network credential management inside a key store, for example,
+for X.509-based authentication or pre-shared keys on enterprise networks.
+
+Device Pairing
+^^^^^^^^^^^^^^
+
+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 might use key agreement protocols upon
+first use.
+
+Secure Boot
+^^^^^^^^^^^
+
+The API provides primitives for use during firmware integrity and authenticity
+validation, during a secure or trusted boot process.
+
+Attestation
+^^^^^^^^^^^
+
+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; ranging 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.
+
+Factory Provisioning
+^^^^^^^^^^^^^^^^^^^^
+
+Most IoT devices receive a unique identity during the factory provisioning
+process, or once they have been deployed to the field. This API provides the APIs necessary for
+populating a device with keys that represent that identity.
diff --git a/docs/html/_sources/overview/implementation.rst.txt b/docs/html/_sources/overview/implementation.rst.txt
new file mode 100644
index 0000000..b85ef16
--- /dev/null
+++ b/docs/html/_sources/overview/implementation.rst.txt
@@ -0,0 +1,290 @@
+.. _implementation-considerations:
+
+Implementation considerations
+-----------------------------
+
+Implementation-specific aspects of the interface
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Implementation profile
+^^^^^^^^^^^^^^^^^^^^^^
+
+Implementations can 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.
+
+.. _implementation-defined-type:
+
+Implementation-specific types
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This specification defines a number of implementation-specific types, which
+represent objects whose content depends on the implementation. These are defined
+as C ``typedef`` types in this specification, with a comment
+:code:`/* implementation-defined type */` in place of the underlying type
+definition. For some types the specification constrains the type, for example,
+by requiring that the type is a ``struct``, or that it is convertible to and
+from an unsigned integer. In the implementation's version of **psa/crypto.h**,
+these types need to be defined as complete C types so that objects of these
+types can be instantiated by application code.
+
+Applications that rely on the implementation specific definition of any of these
+types might not be portable to other implementations of this specification.
+
+.. _implementation-specific-macro:
+
+Implementation-specific macros
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Some macro constants and function-like macros are precisely defined by this
+specification. The use of an exact definition is essential if the definition can
+appear in more than one header file within a compilation.
+
+Other macros that are defined by this specification have a macro body that is
+implementation-specific. The description of an implementation-specific macro can
+optionally specify each of the following requirements:
+
+* Input domains: the macro must be valid for arguments within the input domain.
+* A return type: the macro result must be compatible with this type.
+* Output range: the macro result must lie in the output range.
+* Computed value: A precise mapping of valid input to output values.
+
+Each implementation-specific macro is in one of following categories:
+
+.. _specification-defined-value:
+
+*Specification-defined value*
+
+ The result type and computed value of the macro expression is defined by
+ this specification, but the definition of the macro body is provided by the
+ implementation.
+
+ These macros are indicated in this specification using the comment
+ :code:`/* specification-defined value */`.
+
+ .. TODO!!
+ Change this text when we have provided pseudo-code implementations of
+ all the relevant macro expressions.
+
+ For function-like macros with specification-defined values:
+
+ * Example implementations are provided in an appendix to this specification.
+ See :title:`appendix-specdef-values`.
+
+ * The expected computation for valid and supported input arguments will be
+ defined as pseudo-code in a future version of this specification.
+
+.. _implementation-defined-value:
+
+*Implementation-defined value*
+
+ The value of the macro expression is implementation-defined.
+
+ For some macros, the computed value is derived from the specification of one
+ or more cryptographic algorithms. In these cases, the result must exactly
+ match the value in those external specifications.
+
+ These macros are indicated in this specification using the comment
+ :code:`/* implementation-defined value */`.
+
+Some of these macros compute a result based on an algorithm or key type.
+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.
+
+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.
+
+Porting to a platform
+~~~~~~~~~~~~~~~~~~~~~
+
+Platform assumptions
+^^^^^^^^^^^^^^^^^^^^
+
+This specification is designed for a C99 platform. The interface is defined in
+terms of C macros, functions and objects.
+
+The specification assumes 8-bit bytes, and “byte” and “octet” are used
+synonymously.
+
+Platform-specific types
+^^^^^^^^^^^^^^^^^^^^^^^
+
+The specification makes use of some types defined in C99. These types must be
+defined in the implementation version of **psa/crypto.h** or by a header
+included in this file. The following C99 types are used:
+
+``uint8_t``, ``uint16_t``, ``uint32_t``
+ Unsigned integer types with 8, 16 and 32 value bits respectively.
+ These types are defined by the C99 header **stdint.h**.
+
+Cryptographic hardware support
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+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.
+
+Security requirements and recommendations
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Error detection
+^^^^^^^^^^^^^^^
+
+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.
+
+Even implementations that do not provide isolation are recommended to detect bad
+parameters and fail-safe where possible.
+
+Indirect object references
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Implementations can use different strategies for allocating key identifiers,
+and other types of indirect object reference.
+
+Implementations that provide isolation between the caller and the cryptography
+processing environment must consider the threats relating to abuse and misuse
+of key identifiers and other indirect resource references. For example,
+multi-part operations can be implemented as backend state to which the client
+only maintains an indirect reference in the application's multi-part operation
+object.
+
+An implementation that supports multiple callers must implement strict isolation
+of API resources between different callers. For example, a client must not be
+able to obtain a reference to another client's key by guessing the key
+identifier value. Isolation of key identifiers can be achieved in several ways.
+For example:
+
+- There is a single identifier namespace for all clients, and the
+ implementation verifies that the client is the owner of the identifier when
+ looking up the key.
+- Each client has an independent identifier namespace, and the implementation
+ uses a client specific identifier-to-key mapping when looking up the key.
+
+After a volatile key identifier is destroyed, it is recommended that the
+implementation does not immediately reuse the same identifier value for a
+different key. This reduces the risk of an attack that is able to exploit a key
+identifier reuse vulnerability within an application.
+
+.. _memory-cleanup:
+
+Memory cleanup
+^^^^^^^^^^^^^^
+
+Implementations must wipe all sensitive data from memory when it is no longer
+used. It is recommended that they wipe this sensitive data as soon as possible. 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 multi-part operation, must be wiped, at the latest, when the object
+becomes inactive, for example, when a multi-part operation is aborted.
+
+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.
+
+.. _key-material:
+
+Managing key material
+^^^^^^^^^^^^^^^^^^^^^
+
+In implementations that have limited volatile memory for keys, the
+implementation is permitted to store a `volatile key <volatile-keys>` to a
+temporary location in non-volatile memory. The implementation must delete any
+such copies when the key is destroyed, and it is recommended that these copies
+are deleted as soon as the key is reloaded into volatile memory. An
+implementation that uses this method must clear any stored volatile key material
+on startup.
+
+Implementing the `memory cleanup rule <memory-cleanup>` for persistent keys
+can result in inefficiencies when the same persistent key is used sequentially
+in multiple cryptographic operations. The inefficiency stems from loading the
+key from non-volatile storage on each use of the key. The `PSA_KEY_USAGE_CACHE`
+policy allows an application to request that the implementation does not cleanup
+non-essential copies of persistent key material, effectively suspending the
+cleanup rules for that key. The effects of this policy depend on the
+implementation and the key, for example:
+
+- For volatile keys or keys in a secure element with no open/close mechanism,
+ this is likely to have no effect.
+- For persistent keys that are not in a secure element, this allows the
+ implementation to keep the key in a memory cache outside of the memory used
+ by ongoing operations.
+- For keys in a secure element with an open/close mechanism, this is a hint to
+ keep the key open in the secure element.
+
+The application can indicate when it has finished using the key by calling
+`psa_purge_key()`, to request that the key material is cleaned from memory.
+
+Safe outputs on error
+^^^^^^^^^^^^^^^^^^^^^
+
+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 particularly important for implementations where
+the caller can share memory with another security context, as described in the
+`stability-of-parameters` section.
+
+In most cases, the specification does not define the content of output
+parameters when an error occurs. It is recommended that implementations 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.
+
+Attack resistance
+^^^^^^^^^^^^^^^^^
+
+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.
+
+This specification does not specify particular requirements for attack
+resistance. Implementers are encouraged to consider the attack resistance
+desired in each use case and design their implementation accordingly. Security
+standards for attack resistance for particular targets might be applicable in
+certain use cases.
+
+Other implementation considerations
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Philosophy of resource management
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The specification allows most functions to return
+`PSA_ERROR_INSUFFICIENT_MEMORY`. This gives implementations the freedom to
+manage memory as they please.
+
+Alternatively, the interface is also designed for conservative strategies of
+memory management. An implementation can avoid dynamic memory allocation
+altogether by obeying certain restrictions:
+
+- Pre-allocate memory for a predefined number of keys, each with sufficient
+ memory for all key types that can be stored.
+- For multi-part 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.
+- In an implementation with isolation, pre-allocate memory for a predefined
+ number of operations inside the cryptoprocessor.
+
+.. Inclusion of algorithms
+
+ Inline algorithm-generic functions into specialized functions at compile/link time
diff --git a/docs/html/_sources/overview/intro.rst.txt b/docs/html/_sources/overview/intro.rst.txt
new file mode 100644
index 0000000..416cde7
--- /dev/null
+++ b/docs/html/_sources/overview/intro.rst.txt
@@ -0,0 +1,36 @@
+Introduction
+------------
+
+Arm’s Platform Security Architecture (PSA) is a holistic set of threat models,
+security analyses, hardware and firmware architecture specifications, an
+open source firmware reference implementation, and an independent evaluation
+and certification scheme. PSA provides a recipe, based on
+industry best practice, that allows security to be consistently designed in, at
+both a hardware and firmware level.
+
+The PSA Cryptographic API (Crypto API) described in this document is an
+important PSA component that provides an interface to cryptographic operations
+on resource-constrained devices. The interface is user-friendly, while still
+providing access to the low-level primitives used in modern cryptography. It
+does not require that the user has access to the key material. Instead, it uses
+opaque key identifiers.
+
+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.
+
+This document includes:
+
+- A `rationale <design-goals>` for the design.
+- A `high-level overview of the functionality <functionality-overview>`
+ provided by the interface.
+- A `description of typical architectures <architectures>` of
+ implementations for this specification.
+- General considerations `for implementers <implementation-considerations>`
+ of this specification and `for applications <usage-considerations>` that
+ use the interface defined in this specification.
+- A `detailed definition <api-reference>` of the API.
+
+Companion documents will define *profiles* for this specification. A profile is
+a minimum mandatory subset of the interface that a compliant implementation must
+provide.
diff --git a/docs/html/_sources/overview/sample-arch.rst.txt b/docs/html/_sources/overview/sample-arch.rst.txt
new file mode 100644
index 0000000..499283e
--- /dev/null
+++ b/docs/html/_sources/overview/sample-arch.rst.txt
@@ -0,0 +1,121 @@
+.. _architectures:
+
+Sample architectures
+--------------------
+
+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.
+
+Single-partition architecture
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+In the single-partition architecture, there is no security boundary inside the system. The
+application code can access all the system memory, including the memory used by
+the cryptographic services described in this specification. Thus, the
+architecture provides `no isolation <isolation>`.
+
+This architecture does not conform to the Arm *Platform Security Architecture
+Security Model*. However, it is 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.
+
+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.
+
+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.
+
+.. _isolated-cryptoprocessor:
+
+Cryptographic token and single-application processor
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+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
+`cryptoprocessor isolation <isolation>`. The cryptoprocessor has
+some non-volatile storage, a TRNG, and possibly, some cryptographic accelerators.
+
+There are a number of potential physical realizations: the cryptoprocessor might
+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.
+
+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.
+
+Cryptoprocessor with no key storage
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+As in the :title:`isolated-cryptoprocessor` architecture, this system
+is also composed of two partitions separated by a security boundary and also
+provides `cryptoprocessor isolation <isolation>`.
+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.
+
+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.
+
+The cryptoprocessor can provide useful services if it is able to store at least
+one key. This might 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:
+
+- Encrypt and authenticate data stored in the application processor.
+- Communicate with a paired device.
+- Allow the application to perform operations with keys that are derived from
+ the hardware unique key.
+
+Multi-client cryptoprocessor
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This is an expanded variant of the `cryptographic token plus application
+architecture <isolated-cryptoprocessor>`. In this
+variant, the cryptoprocessor serves multiple applications that are mutually
+untrustworthy. This architecture provides `caller
+isolation <isolation>`.
+
+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.
+
+Multi-cryptoprocessor architecture
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This system includes multiple cryptoprocessors. There are several reasons to
+have multiple cryptoprocessors:
+
+- 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.
+- Independent provisioning of certain secrets.
+- A combination of a non-removable cryptoprocessor and removable ones, for
+ example, a smartcard or HSM.
+- Cryptoprocessors managed by different stakeholders who do not trust each
+ other.
+
+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 might target a cryptoprocessor based on
+ parameters supplied by the application, or based on considerations such as
+ performance inside the implementation.
diff --git a/docs/html/_sources/overview/usage.rst.txt b/docs/html/_sources/overview/usage.rst.txt
new file mode 100644
index 0000000..1d1f2c9
--- /dev/null
+++ b/docs/html/_sources/overview/usage.rst.txt
@@ -0,0 +1,71 @@
+.. _usage-considerations:
+
+Usage considerations
+--------------------
+
+Security recommendations
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+Always check for errors
+^^^^^^^^^^^^^^^^^^^^^^^
+
+Most functions in this API can return errors. All functions that can fail have
+the return type `psa_status_t`. A few functions cannot fail, and thus, return
+``void`` or some other type.
+
+If an error occurs, unless otherwise specified, the content of the output
+parameters is undefined and must not be used.
+
+Some common causes of errors include:
+
+- 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 might fail due to an error in the
+ communication between the two environments.
+- If an algorithm is implemented with a hardware accelerator, which is
+ logically separate from the application processor, the accelerator might fail,
+ even when the application processor keeps running normally.
+- Most functions might fail due to a lack of resources. However, some
+ implementations guarantee that certain functions always have sufficient
+ memory.
+- All functions that access persistent keys might fail due to a storage failure.
+- All functions that require randomness might fail due to a lack of entropy.
+ Implementations are encouraged to seed the random generator with sufficient
+ entropy during the execution of `psa_crypto_init()`. However, some security
+ standards require periodic reseeding from a hardware random generator, which
+ can fail.
+
+Shared memory and concurrency
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Some environments allow applications to be multithreaded, while others do not.
+In some environments, applications can 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.
+
+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 `concurrency`
+section.
+
+If an application shares memory with another security context, it can pass
+shared memory blocks as input buffers or output buffers, but not as non-buffer
+parameters. For more details, refer to the :title:`stability-of-parameters` section.
+
+Cleaning up after use
+^^^^^^^^^^^^^^^^^^^^^
+
+To minimize impact if the system is compromised, it is recommended that
+applications wipe all sensitive data from memory when it is no longer used. That
+way, only data that is currently in use can be leaked, and past data is not
+compromised.
+
+Wiping sensitive data includes:
+
+- Clearing temporary buffers in the stack or on the heap.
+- Aborting operations if they will not be finished.
+- Destroying keys that are no longer used.