Unify the sections on key creation

Now that transparent drivers have an "import_key" entry point, the key
creation interfaces for transparent drivers and opaque drivers are
very similar. Unify the sections that describe their behavior,
including key validation and key size determination.

Signed-off-by: Gilles Peskine <Gilles.Peskine@arm.com>

docs/proposed/psa-driver-interface.md

@@ -5,7 +5,7 @@ This document describes an interface for cryptoprocessor drivers in the PSA cryp
 
 This specification is work in progress and should be considered to be in a beta stage. There is ongoing work to implement this interface in Mbed TLS, which is the reference implementation of the PSA Cryptography API. At this stage, Arm does not expect major changes, but minor changes are expected based on experience from the first implementation and on external feedback.
 
-Time-stamp: "2020/10/26 16:54:57 GMT"
+Time-stamp: "2020/10/27 17:31:13 GMT"
 
 ## Introduction
 
@@ -189,6 +189,11 @@ The signature of a driver entry point generally looks like the signature of the
 
 * For entry points that involve a multi-part operation, the operation state type (`psa_XXX_operation_t`) is replaced by a driver-specific operation state type (*prefix*`_XXX_operation_t`).
 
+* For entry points that are involved in key creation, the `psa_key_id_t *` output parameter is replaced by a sequence of parameters that convey the key context:
+    1. `const uint8_t *key_buffer`: a buffer for the key material or key context.
+    2. `size_t key_buffer_size`: the size of the key buffer in bytes.
+    2. `size_t *key_buffer_length`: the length of the data written to the key buffer in bytes.
+
 Some entry points are grouped in families that must be implemented as a whole. If a driver supports an entry point family, it must provide all the entry points in the family.
 
 #### General considerations on driver entry point parameters
@@ -311,7 +316,63 @@ TODO
 
 ### Driver entry points for key management
 
-The driver entry points for key management differs significantly between [transparent drivers](#key-management-with-transparent-drivers) and [opaque drivers](#key-management-with-transparent-drivers). Refer to the applicable section for each driver type.
+The driver entry points for key management differ significantly between [transparent drivers](#key-management-with-transparent-drivers) and [opaque drivers](#key-management-with-transparent-drivers). This section describes common elements. Refer to the applicable section for each driver type for more information.
+
+The entry points that create or format key data have the following prototypes for a driver with the prefix `"acme"`:
+
+```
+psa_status_t acme_import_key(const psa_key_attributes_t *attributes,
+                             const uint8_t *data,
+                             size_t data_length,
+                             uint8_t *key_buffer,
+                             size_t key_buffer_size,
+                             size_t *key_buffer_length,
+                             size_t *bits);
+psa_status_t acme_generate_key(const psa_key_attributes_t *attributes,
+                               uint8_t *key_buffer,
+                               size_t key_buffer_size,
+                               size_t *key_buffer_length);
+```
+
+TODO: derivation, copy
+
+* The key attributes (`attributes`) have the same semantics as in the PSA Cryptography application interface.
+* For the `"import_key"` entry point, the input in the `data` buffer is either the export format or an implementation-specific format that the core documents as an acceptable input format for `psa_import_key()`.
+* The size of the key data buffer is sufficient for the internal representation of the key. For a transparent driver, this is the key's [export format](#key-format-for-transparent-drivers). For an opaque driver, this is the size determined from the driver description and the key attributes, as specified in the section [“Key format for opaque drivers”](#key-format-for-opaque-drivers).
+* For an opaque driver with an `"allocate_key"` entry point, the content of the key data buffer on entry is the output of that entry point.
+* The `"import_key"` entry point must determine or validate the key size and set `*bits` as described in the section [“Key size determination on import”](#key-size-determination-on-import) below.
+
+All key creation entry points must ensure that the resulting key is valid as specified in the section [“Key validation”](#key-validation) below. This is primarily important for import entry points since the key data comes from the application.
+
+#### Key size determination on import
+
+The `"import_key"` entry point may need to determine the key size.
+The PSA Cryptography API exposes the key size as part of the key attributes.
+When importing a key, the key size recorded in the key attributes may be `0`, which indicates that the size must be calculated from the data.
+In this case, the core will call the `"import_key"` entry point with an `attributes` structure such that `psa_get_key_bits(attributes)` returns 0, and the `"import_key"` entry point must return the actual key size in the `bits` output parameter. The semantics of `bits` is as follows:
+
+* The core sets `*bits` to `psa_get_key_bits(attributes)` before calling the `"import_key"` entry point.
+* If `*bits == 0`, the driver must determine the key size from the data and set `*bits` to this size. If the key size cannot be determined from the data, the driver must return `PSA_ERROR_INVALID_ARGUMENT` (as of version 1.0 of the PSA Cryptography API specification, it is possible to determine the key size for all standard key types).
+* If `*bits != 0`, the driver must check the value of `*bits` against the data and return an error if it does not match. If the driver entry point changes `*bits` to a different value but returns `PSA_SUCCESS`, the core will consider the key as invalid and the import will fail.
+
+#### Key validation
+
+Key creation entry points must produce valid key data. Key data is _valid_ if operations involving the key are guaranteed to work functionally and not to cause indirect security loss. Operation functions are supposed to receive valid keys, and should not have to check and report invalid keys. For example:
+
+* If a cryptographic mechanism is defined as having keying material of a certain size, or if the keying material involves integers that have to be in a certain range, key creation must ensure that the keying material has an appropriate size and falls within an appropriate range.
+* If a cryptographic operation involves a division by an integer which is provided as part of a key, key creation must ensure that this integer is nonzero.
+* If a cryptographic operation involves two keys A and B (or more), then the creation of A must ensure that using it does not risk compromising B. This applies even if A's policy does not explicitly allow a problematic operation, but A is exportable. In particular, public keys that can potentially be used for key agreement are considered invalid and must not be created if they risk compromising the private key..
+* On the other hand, it is acceptable for import to accept a key that cannot be verified as valid if using this key would at most compromise the key itself and material that is secured with this key. For example, RSA key import does not need to verify that the primes are actually prime. Key import may accept an insecure key if the consequences of the insecurity are no worse than a leak of the key prior to its import.
+
+With opaque drivers, the key context can only be used by code from the same driver, so key validity is primarily intended to report key creation errors at creation time rather than during an operation. With transparent drivers, the key context can potentially be used by code from a different provider, so key validity is critical for interoperability.
+
+This section describes some minimal validity requirements for standard key types.
+
+* For symmetric key types, check that the key size is suitable for the type.
+* For DES (`PSA_KEY_TYPE_DES`), additionally verify the parity bits.
+* For RSA (`PSA_KEY_TYPE_RSA_PUBLIC_KEY`, `PSA_KEY_TYPE_RSA_KEY_PAIR`), check the syntax of the key and make sanity checks on its components. TODO: what sanity checks? Value ranges (e.g. p < n), sanity checks such as parity, minimum and maximum size, what else?
+* For elliptic curve private keys (`PSA_KEY_TYPE_ECC_KEY_PAIR`), check the size and range. TODO: what else?
+* For elliptic curve public keys (`PSA_KEY_TYPE_ECC_PUBLIC_KEY`), check the size and range, and that the point is on the curve. TODO: what else?
 
 ### Miscellaneous driver entry points
 
@@ -366,32 +427,6 @@ This entry point has several roles:
 3. [Determine the key size](#key-size-determination-on-import) and output it through `*bits`.
 4. Copy the validated key data from `data` to `key_buffer`. The output must be in the canonical format documented for [`psa_export_key()`](https://armmbed.github.io/mbed-crypto/html/api/keys/management.html#c.psa_export_key) or [`psa_export_public_key()`](https://armmbed.github.io/mbed-crypto/html/api/keys/management.html#c.psa_export_public_key), so if the input is not in this format, the entry point must convert it.
 
-#### Key size determination on import
-
-The PSA Cryptography API exposes the key size as part of the key attributes.
-When importing a key, the key size recorded in the key attributes may be `0`, which indicates that the size must be calculated from the data.
-In this case, the core will call the `"import_key"` entry point with an `attributes` structure such that `psa_get_key_bits(attributes)` returns 0, and the `"import_key"` entry point must return the actual key size in the `bits` output parameter.
-The semantics of `bits` is as follows:
-
-* The core sets `*bits` to `psa_get_key_bits(attributes)` before calling the `"import_key"` entry point.
-* If `*bits == 0`, the driver must determine the key size from the data, and return `PSA_ERROR_INVALID_ARGUMENT` if this is not possible.
-* If `*bits != 0`, the driver may either determine the key size from the data and store it in `*bits`, or check the value of `*bits*` against the data and return an error if it does not match.
-* If the `"import_key"` entry point returns `PSA_SUCCESS`, but `psa_get_key_bits(attributes) != 0` and `psa_get_key_bits(attributes) != *bits` on output, the core considers the key as invalid due to the size mismatch.
-
-#### Key validation with transparent drivers
-
-When a driver creates a key, it is responsible for ensuring that the key is valid. But when a key is imported, no processing of the key happens: the PSA Cryptography implementation just stores the key material. (It may store it in an encoded form, but this is an implementation choice which is not visible at the level of PSA specifications.) It is important to validate the incoming key material, to avoid storing a key that will later be unacceptable for operations or that could even cause functional or security issues during operations.
-
-To avoid delayed problems caused by imported invalid keys, a PSA Cryptography implementation that supports transparent drivers must validate transparent keys on import. For supported key types, this means:
-
-* For symmetric key types, check that the key size is suitable for the type.
-* For DES (`PSA_KEY_TYPE_DES`), additionally verify the parity bits.
-* For RSA (`PSA_KEY_TYPE_RSA_PUBLIC_KEY`, `PSA_KEY_TYPE_RSA_KEY_PAIR`), check the syntax of the key and make sanity checks on its components. TODO: what sanity checks? Value ranges (e.g. p < n), sanity checks such as parity, minimum and maximum size, what else?
-* For elliptic curve private keys (`PSA_KEY_TYPE_ECC_KEY_PAIR`), check the size and range. TODO: what else?
-* For elliptic curve public keys (``), check the size and range, and that the point is on the curve. TODO: what else?
-
-A driver can provide code to perform the required validation by providing an `"import_key"` entry point. This entry point returns `PSA_SUCCESS` if the key is valid or an applicable error code if it isn't.
-
 ### Fallback
 
 Sometimes cryptographic accelerators only support certain cryptographic mechanisms partially. The capability description language allows specifying some restrictions, including restrictions on key sizes, but it cannot cover all the possibilities that may arise in practice. Furthermore, it may be desirable to deploy the same binary image on different devices, only some of which have a cryptographic accelerators.
@@ -563,21 +598,6 @@ If the driver has an [`"allocate_key"` entry point](#key-management-in-a-secure-
 
 TODO: derivation, copy
 
-#### Key validation and size on import
-
-The `"import_key"` entry point must validate the key so that if a key is imported successfully, permitted operations on the key will succeed if the input data is valid and enough resources are available. For key types that are defined in the PSA Cryptography specification, opaque drivers must guarantee the properties that transparent drivers guarantee if [`"import_key"`](#key-validation-with-transparent-drivers) succeeds.
-
-Rationale: The key must be validated on import to provide in-time feedback when attempting to inject a bad key. The minimum requirement for validation sets a minimum security baseline (especially for operations such as key agreement where accepting an invalid key could result in leaking secret material).
-
-The `"import_key"` entry point may need to determine the key size.
-The PSA Cryptography API exposes the key size as part of the key attributes.
-When importing a key, the key size recorded in the key attributes may be `0`, which indicates that the size must be calculated from the data.
-In this case, the core will call the `"import_key"` entry point with an `attributes` structure such that `psa_get_key_bits(attributes)` returns 0, and the `"import_key"` entry point must return the actual key size in the `bits` output parameter. The semantics of `bits` is as follows:
-
-* The core sets `*bits` to `psa_get_key_bits(attributes)` before calling the `"import_key"` entry point.
-* If `*bits == 0`, the driver must determine the key size from the data, and return `PSA_ERROR_INVALID_ARGUMENT` if this is not possible.
-* If `*bits != 0`, the driver must check the value of `*bits*` against the data and return an error if it does not match.
-
 #### Key export entry points in opaque drivers
 
 The key export entry points have the following prototypes for a driver with the prefix `"acme"`: