Added psa_import_formatted_key()

* Open issue regarding handling of encoded policy in key data

Author: athoelke

doc/crypto/api/keys/management.rst

@@ -180,11 +180,11 @@ Implementations are permitted to define additional key formats and options.
     .. summary::
         The *OneAsymmetricKey* key format for RSA and elliptic curve key-pairs.
 
-    .. todo:: Should this be named ``PSA_KEY_FORMAT_PKCS8`` instead?
+        .. todo:: Should this be named ``PSA_KEY_FORMAT_PKCS8`` instead?
 
-        Technically I think not: PKCS#8 defines both *PrivateKeyInfo* and *EncryptedPrivateKeyInfo*, OneAsymmetricKey (version 1) is synonymous with PrivateKeyInfo.
+            Technically I think not: PKCS#8 defines both *PrivateKeyInfo* and *EncryptedPrivateKeyInfo*, OneAsymmetricKey (version 1) is synonymous with PrivateKeyInfo.
 
-        Perhaps ``PSA_KEY_FORMAT_PRIVATE_KEY_INFO`` could be a synonym of OneAsymmetricKey?
+            Perhaps ``PSA_KEY_FORMAT_PRIVATE_KEY_INFO`` could be a synonym of OneAsymmetricKey?
 
     OneAsymmetricKey is defined by :RFC-title:`5958#2`.
     OneAsymmetricKey is an update to the PKCS#8 *PrivateKeyInfo* format defined by :RFC-title:`5208`.
@@ -311,7 +311,7 @@ Key creation
 
 New keys can be created in the following ways:
 
-*   `psa_import_key()` creates a key from a data buffer provided by the application.
+*   `psa_import_key()` and `psa_import_formatted_key()` create a key from a data buffer provided by the application.
 *   `psa_generate_key()` creates a key from randomly generated data.
 *   `psa_key_derivation_output_key()` creates a key from data generated by a pseudorandom derivation process. See :secref:`kdf`.
 *   `psa_key_agreement()` creates a key from the shared secret result of a key agreement process. See :secref:`key-agreement`.
@@ -359,9 +359,6 @@ When creating a key, the attributes for the new key are specified in a `psa_key_
     .. param:: const uint8_t * data
         Buffer containing the key data.
         The content of this buffer is interpreted according to the type declared in ``attributes``.
-
-        All implementations must support at least the format described in the *Key format* section of the chosen key type.
-        Implementations can support other formats, but be conservative in interpreting the key data: it is recommended that implementations reject content if it might be erroneous, for example, if it is the wrong type or is truncated.
     .. param:: size_t data_length
         Size of the ``data`` buffer in bytes.
     .. param:: psa_key_id_t * key
@@ -400,17 +397,151 @@ When creating a key, the attributes for the new key are specified in a `psa_key_
 
     The key is extracted from the provided ``data`` buffer. Its location, policy, and type are taken from ``attributes``.
 
-    The provided key data determines the key size. The attributes can optionally specify a key size; in this case it must match the size determined from the key data. A key size of ``0`` in ``attributes`` --- the default value --- indicates that the key size is solely determined by the key data.
-
-    Implementations must reject an attempt to import a key of size ``0``.
+    The key data determines the key size. :code:``psa_get_key_bits(attributes)`` must either match the determined key size or be ``0``. Implementations must reject an attempt to import a key of size zero.
 
-    This function supports any output from `psa_export_key()`. Each key type in :secref:`key-types` describes the expected format of keys.
+    This function supports any output from `psa_export_key()`.
+    The default format is defined in the *Key format* section for each key type.
+    Other key formats can be imported using `psa_import_formatted_key()`.
 
-    This specification defines a single format for each key type. Implementations can optionally support other formats in addition to the standard format. It is recommended that implementations that support other formats ensure that the formats are clearly unambiguous, to minimize the risk that an invalid input is accidentally interpreted according to a different format.
+    Implementations can optionally support other formats in calls to `psa_import_key()`, in addition to the default format.
 
     .. note::
         The |API| does not support asymmetric private key objects outside of a key pair. To import a private key, the ``attributes`` must specify the corresponding key pair type. Depending on the key type, either the import format contains the public key data or the implementation will reconstruct the public key from the private key as needed.
 
+    .. admonition:: Implementation note
+
+        It is recommended that implementations that support other formats ensure that the formats are clearly unambiguous, to minimize the risk that an invalid input is accidentally interpreted according to a different format.
+
+        It is recommended that implementations reject key data if it might be erroneous, for example, if it is the wrong type or is truncated.
+
+.. function:: psa_import_formatted_key
+
+    .. summary::
+        Import a key in a specified format.
+        *   The key type can be `PSA_KEY_TYPE_NONE`. If either is nonzero, it must match the corresponding attribute of the source key.
+
+    .. param:: const psa_key_attributes_t * attributes
+        The attributes for the new key.
+
+        Depending on the specified key format, and the attributes encoded in the key data, some of the key attributes can be optional.
+
+        The following attributes are required for formats that do not specify a key type:
+
+        *   When the format does not specify a key type: the key type in ``attributes`` determines how the ``data`` buffer is interpreted.
+        *   When the format does specify a key type: if the key type in ``attributes`` has a non-default value, it must be equal to the determined key type.
+
+        The following attributes must be set for keys used in cryptographic operations:
+
+        *   The key permitted-algorithm policy, see :secref:`permitted-algorithms`.
+        *   The key usage flags, see :secref:`key-usage-flags`.
+
+        These attributes are combined with any policy that is encoded in the key data, so that both sets of restrictions apply :issue:`(this needs further thought & discussion)`.
+
+        The following attributes must be set for keys that do not use the default volatile lifetime:
+
+        *   The key lifetime, see :secref:`key-lifetimes`.
+        *   The key identifier is required for a key with a persistent lifetime, see :secref:`key-identifiers`.
+
+        The following attributes are optional:
+
+        *   If the key size is nonzero, it must be equal to the key size determined from ``data``.
+
+        .. note::
+            This is an input parameter: it is not updated with the final key attributes.
+            The final attributes of the new key can be queried by calling `psa_get_key_attributes()` with the key's identifier.
+    .. param:: psa_key_format_t format
+        The format of the key data.
+        One of the ``PSA_KEY_FORMAT_XXX`` values, or an implementation-specific format.
+    .. param:: const uint8_t * data
+        Buffer containing the key data.
+        The content of this buffer is interpreted according to the key format ``format``.
+        The type declared in ``attributes`` is used if the format and key data do not specify a key type.
+    .. param:: size_t data_length
+        Size of the ``data`` buffer in bytes.
+    .. param:: psa_key_id_t * key
+        On success, an identifier for the newly created key. `PSA_KEY_ID_NULL` on failure.
+
+    .. return:: psa_status_t
+    .. retval:: PSA_SUCCESS
+        Success.
+        If the key is persistent, the key material and the key's metadata have been saved to persistent storage.
+    .. retval:: PSA_ERROR_ALREADY_EXISTS
+        This is an attempt to create a persistent key, and there is already a persistent key with the given identifier.
+    .. retval:: PSA_ERROR_NOT_SUPPORTED
+        The following conditions can result in this error:
+
+        *   The key format is not supported by the implementation.
+        *   The key attributes, as a whole, are not supported, either by the implementation in general or in the specified storage location.
+    .. retval:: PSA_ERROR_INVALID_ARGUMENT
+        The following conditions can result in this error:
+
+        *   The key type is invalid, or is `PSA_KEY_TYPE_NONE` when a type is required.
+        *   The key size is nonzero, and is incompatible with the key data in ``data``.
+        *   The key lifetime is invalid.
+        *   The key identifier is not valid for the key lifetime.
+        *   The key usage flags include invalid values.
+        *   The key's permitted-usage algorithm is invalid.
+        *   The key attributes, as a whole, are invalid.
+        *   The key format is invalid.
+        *   The key data is not correctly formatted for the key format or the key type.
+    .. retval:: PSA_ERROR_NOT_PERMITTED
+        The implementation does not permit creating a key with the specified attributes due to some implementation-specific policy.
+    .. retval:: PSA_ERROR_INSUFFICIENT_MEMORY
+    .. retval:: PSA_ERROR_INSUFFICIENT_STORAGE
+    .. retval:: PSA_ERROR_COMMUNICATION_FAILURE
+    .. retval:: PSA_ERROR_STORAGE_FAILURE
+    .. retval:: PSA_ERROR_DATA_CORRUPT
+    .. retval:: PSA_ERROR_DATA_INVALID
+    .. retval:: PSA_ERROR_CORRUPTION_DETECTED
+    .. retval:: PSA_ERROR_BAD_STATE
+        The library requires initializing by a call to `psa_crypto_init()`.
+
+    The key is extracted from the provided ``data`` buffer, which is interpreted according to the specified key format. Its location is taken from ``attributes``, its type and policy are determined by the ``format``, the ``data``, and the ``attributes``.
+
+    If the format is `PSA_KEY_FORMAT_DEFAULT`, this is equivalent to call to `psa_import_key()`.
+
+    For non-default key formats, the key format either specifies the key type, or the formatted data encodes the key type.
+    For example, `PSA_KEY_FORMAT_RSA_PRIVATE_KEY` is always an RSA key pair, while the `PSA_KEY_FORMAT_ONE_ASYMMETRIC_KEY` format includes a data element that specifies whether it is an RSA or elliptic curve key-pair.
+    If the key type is determined by the format and the data, then :code:``psa_get_key_type(attributes)`` must either match the determined key type or be `PSA_KEY_TYPE_NONE`.
+
+    The key data determines the key size.
+    :code:``psa_get_key_bits(attributes)`` must either match the determined key size or be ``0``.
+    Implementations must reject an attempt to import a key of size zero.
+
+    The resulting key can only be used in a way that conforms to both the policy included in the key data, and the policy specified in the ``attributes`` parameter :issue:`(the following is place-holder cut and paste from psa_copy_key())`:
+
+    *   The usage flags on the resulting key are the bitwise-and of the usage flags on the source policy and the usage flags in ``attributes``.
+    *   If both permit the same algorithm or wildcard-based algorithm, the resulting key has the same permitted algorithm.
+    *   If either of the policies permits an algorithm and the other policy permits a wildcard-based permitted algorithm that includes this algorithm, the resulting key uses this permitted algorithm.
+    *   If the policies do not permit any algorithm in common, this function fails with the status :code:`PSA_ERROR_INVALID_ARGUMENT`.
+
+    As a result, the new key cannot be used for operations that were not permitted by the imported key data.
+
+    .. todo:: The proposed constraints on key policy are probably too strict.
+
+        *   Most of the X.509 formats include a mandatory *AlgorithmIdentifier* element which does constrain the algorithm, *almost* well enough to match a |API| permitted algorithm encoding.
+        *   Many of the formats include an optional *KeyUsage* element that defines a set of permitted uses.
+            These partially map onto |API| usage flags.
+
+        1.  What to do if the format does not include a algorithm identifier?
+        2.  What to do if the algorithm identifier is too general for the algorithm encodings in |API|?
+        3.  If a *KeyUsage* is provided, do we take an intersection with the ``attributes`` usage flags? - what about when there is no 1:1 mapping?
+        4.  If a *KeyUsage* is **not** provided, do we just use the ``attributes`` usage flags?
+        5.  Are some |API| usage flags specific to the |API|, or to the application use of the key store. For example USAGE_EXPORT, USAGE_COPY, USAGE_CACHE?
+
+    Implementations can define implementation-specific formats that may have other behaviors relating to ``attributes``.
+
+    .. note::
+        The |API| does not support asymmetric private key objects outside of a key pair.
+        When importing a private key, the corresponding key-pair type is created.
+        If the imported key data does not contain the public key, then the implementation will reconstruct the public key from the private key as needed.
+
+    .. admonition:: Implementation note
+
+        It is recommended that implementation-specific formats are clearly unambiguous, to minimize the risk that an invalid input is accidentally interpreted according to a different format.
+
+        It is recommended that implementations reject key data if it might be erroneous, for example, if it is the wrong type or is truncated.
+
 .. function:: psa_generate_key
 
     .. summary::

doc/crypto/appendix/history.rst

@@ -21,8 +21,11 @@ Changes to the API
 
 *   Added `PSA_EXPORT_ASYMMETRIC_KEY_MAX_SIZE` to evaluate the export buffer size for any asymmetric key pair or public key.
 
-*   Added key data formats and formatting options for key export and import.
-    See :secref:`key-formats`.
+*   Added support for non-default key formats:
+
+    -   Added definitions for key formats and and formatting options.
+        See :secref:`key-formats`.
+    -   Added `psa_import_formatted_key()` to import keys in other formats.
 
 Clarifications and fixes
 ~~~~~~~~~~~~~~~~~~~~~~~~