Further clarifications on the use of key attributes when creating keys

doc/crypto/api/keys/management.rst

@@ -36,20 +36,33 @@ When creating a key, the attributes for the new key are specified in a `psa_key_
 
     .. param:: const psa_key_attributes_t * attributes
         The attributes for the new key.
-        This function uses the attributes as follows:
 
-        *   The key type is required, and determines how the ``data`` buffer is interpreted.
-        *   The key size is always determined from the ``data`` buffer. If the key size in ``attributes`` is nonzero, it must be equal to the size determined from ``data``.
-        *   The key permitted-algorithm policy is required for keys that will be used for a cryptographic operation, see :secref:`permitted-algorithms`.
-        *   The key usage flags define what operations are permitted with the key, see :secref:`key-usage-flags`.
-        *   The key lifetime and identifier are required for a persistent key.
+        The following attributes are required for all keys:
+
+        *   The key type determines how the ``data`` buffer is interpreted.
+
+        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`.
+
+        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.
+            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:: 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
@@ -88,12 +101,14 @@ When creating a key, the attributes for the new key are specified in a `psa_key_
     .. retval:: PSA_ERROR_BAD_STATE
         The library requires initializing by a call to `psa_crypto_init()`.
 
-    This function supports any output from `psa_export_key()`. Each key type in :secref:`key-types` describes the expected format of keys.
+    The key is extracted from the provided ``data`` buffer. Its location, policy, and type are taken from ``attributes``.
 
-    The 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`` indicates that the key size is solely determined by the key data.
+    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``.
 
+    This function supports any output from `psa_export_key()`. Each key type in :secref:`key-types` describes the expected format of keys.
+
     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.
 
     .. note::
@@ -106,16 +121,25 @@ When creating a key, the attributes for the new key are specified in a `psa_key_
 
     .. param:: const psa_key_attributes_t * attributes
         The attributes for the new key.
-        This function uses the attributes as follows:
 
-        *   The key type is required. It cannot be an asymmetric public key.
-        *   The key size is required. It must be a valid size for the key type.
-        *   The key permitted-algorithm policy is required for keys that will be used for a cryptographic operation, see :secref:`permitted-algorithms`.
-        *   The key usage flags define what operations are permitted with the key, see :secref:`key-usage-flags`.
-        *   The key lifetime and identifier are required for a persistent key.
+        The following attributes are required for all keys:
+
+        *   The key type. It must not be an asymmetric public key.
+        *   The key size. It must be a valid size for the 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`.
+
+        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`.
 
         .. 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.
+            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_id_t * key
         On success, an identifier for the newly created key. `PSA_KEY_ID_NULL` on failure.
@@ -169,14 +193,28 @@ When creating a key, the attributes for the new key are specified in a `psa_key_
         It must permit the usage `PSA_KEY_USAGE_COPY`.
         If a private or secret key is being copied outside of a secure element it must also permit `PSA_KEY_USAGE_EXPORT`.
     .. param:: const psa_key_attributes_t * attributes
-        The attributes for the new key. This function uses the attributes as follows:
+        The attributes for the new key.
+
+        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`.
 
-        *   The key type and size can be ``0``. If either is nonzero, it must match the corresponding attribute of the source key.
-        *   The key location (the lifetime and, for persistent keys, the key identifier) is used directly.
-        *   The key policy (usage flags and permitted algorithm) are combined from the source key and ``attributes`` so that both sets of restrictions apply, as described in the documentation of this function.
+        These flags are combined with the source key policy so that both sets of restrictions apply, as described in the documentation of this function.
+
+        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 type has a non-default value, it must be equal to the source key type.
+        *   If the key size is nonzero, it must be equal to the source key size.
 
         .. 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.
+            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_id_t * target_key
         On success, an identifier for the newly created key. `PSA_KEY_ID_NULL` on failure.
@@ -216,7 +254,7 @@ When creating a key, the attributes for the new key are specified in a `psa_key_
     .. retval:: PSA_ERROR_BAD_STATE
         The library requires initializing by a call to `psa_crypto_init()`.
 
-    Copy key material from one location to another.
+    Copy key material from one location to another. Its location is taken from ``attributes``, its policy is the intersection of the policy in ``attributes`` and the source key policy, and its type and size are taken from the source key.
 
     This function is primarily useful to copy a key from one location to another, as it populates a key using the material from another key which can have a different lifetime.
 
@@ -231,8 +269,9 @@ When creating a key, the attributes for the new key are specified in a `psa_key_
     *   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`.
 
-    The effect of this function on implementation-defined attributes is implementation-defined.
+    As a result, the new key cannot be used for operations that were not permitted on the source key.
 
+    The effect of this function on implementation-defined attributes is implementation-defined.
 
 .. _key-destruction:
 

doc/crypto/api/ops/key-agreement.rst

@@ -138,22 +138,33 @@ Standalone key agreement
         The standalone key agreement algorithm to compute: a value of type `psa_algorithm_t` such that :code:`PSA_ALG_IS_STANDALONE_KEY_AGREEMENT(alg)` is true.
     .. param:: const psa_key_attributes_t * attributes
         The attributes for the new key.
-        This function uses the attributes as follows:
 
-        *   The key type must be one of `PSA_KEY_TYPE_DERIVE`, `PSA_KEY_TYPE_RAW_DATA`, `PSA_KEY_TYPE_HMAC`, or `PSA_KEY_TYPE_PASSWORD`.
+        The following attributes are required for all keys:
+
+        *   The key type, which must be one of `PSA_KEY_TYPE_DERIVE`, `PSA_KEY_TYPE_RAW_DATA`, `PSA_KEY_TYPE_HMAC`, or `PSA_KEY_TYPE_PASSWORD`.
 
             Implementations must support the `PSA_KEY_TYPE_DERIVE` and `PSA_KEY_TYPE_RAW_DATA` key types.
 
-        *   The size of the returned key is always the bit-size of the shared secret, rounded up to a whole number of bytes. The key size in ``attributes`` can be zero; if it is nonzero, it must be equal to the output size of the key agreement, in bits.
+        The following attributes must be set for keys used in cryptographic operations:
 
-            The output size, in bits, of the key agreement is :code:`8 * PSA_RAW_KEY_AGREEMENT_OUTPUT_SIZE(type, bits)`, where ``type`` and ``bits`` are the type and bit-size of ``private_key``.
+        *   The key permitted-algorithm policy, see :secref:`permitted-algorithms`.
+        *   The key usage flags, see :secref:`key-usage-flags`.
+
+        The following attributes must be set for keys that do not use the default volatile lifetime:
 
-        *   The key permitted-algorithm policy is required for keys that will be used for a cryptographic operation, see :secref:`permitted-algorithms`.
-        *   The key usage flags define what operations are permitted with the key, see :secref:`key-usage-flags`.
-        *   The key lifetime and identifier are required for a persistent key.
+        *   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 output size of the key agreement, in bits.
+
+            The output size, in bits, of the key agreement is :code:`8 * PSA_RAW_KEY_AGREEMENT_OUTPUT_SIZE(type, bits)`, where ``type`` and ``bits`` are the type and bit-size of ``private_key``.
 
         .. 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.
+            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_id_t * key
         On success, an identifier for the newly created key. `PSA_KEY_ID_NULL` on failure.
 
@@ -203,7 +214,14 @@ Standalone key agreement
     .. retval:: PSA_ERROR_BAD_STATE
         The library requires initializing by a call to `psa_crypto_init()`.
 
-    A key agreement algorithm takes two inputs: a private key ``private_key``, and a public key ``peer_key``. The result of this function is a shared secret, returned as a derivation key. This key can be input to a key derivation operation using `psa_key_derivation_input_key()`.
+    A key agreement algorithm takes two inputs: a private key ``private_key``, and a public key ``peer_key``.
+    The result of this function is a shared secret, returned as a derivation key.
+
+    The new key's location, policy, and type are taken from ``attributes``.
+
+    The size of the returned key is always the bit-size of the shared secret, rounded up to a whole number of bytes.
+
+    This key can be used as input to a key derivation operation using `psa_key_derivation_input_key()`.
 
     .. warning::
         The shared secret resulting from a key agreement algorithm such as finite-field Diffie-Hellman or elliptic curve Diffie-Hellman has biases. This makes it unsuitable for use as key material, for example, as an AES key. Instead, it is recommended that a key derivation algorithm is applied to the result, to derive unbiased cryptographic keys.

doc/crypto/api/ops/key-derivation.rst

@@ -847,19 +847,27 @@ Key derivation functions
 
     .. param:: const psa_key_attributes_t * attributes
         The attributes for the new key.
-        This function uses the attributes as follows:
 
-        *   The key type is required. It cannot be an asymmetric public key.
-        *   The key size is required. It must be a valid size for the key type.
-        *   The key permitted-algorithm policy is required for keys that will be used for a cryptographic operation, see :secref:`permitted-algorithms`.
+        The following attributes are required for all keys:
 
-            If the key type to be created is `PSA_KEY_TYPE_PASSWORD_HASH`, then the permitted-algorithm policy must be the same as the current operation's algorithm.
+        *   The key type. It must not be an asymmetric public key.
+        *   The key size. It must be a valid size for the key type.
 
-        *   The key usage flags define what operations are permitted with the key, see :secref:`key-usage-flags`.
-        *   The key lifetime and identifier are required for a persistent key.
+        The following attributes must be set for keys used in cryptographic operations:
+
+        *   The key permitted-algorithm policy, see :secref:`permitted-algorithms`.
+
+            If the key type to be created is `PSA_KEY_TYPE_PASSWORD_HASH`, then the permitted-algorithm policy must be either the same as the current operation's algorithm, or `PSA_ALG_NONE`.
+        *   The key usage flags, see :secref:`key-usage-flags`.
+
+        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`.
 
         .. 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.
+            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_derivation_operation_t * operation
         The key derivation operation object to read from.

doc/crypto/api/ops/pake.rst

@@ -954,23 +954,32 @@ Multi-part PAKE operations
         Active PAKE operation.
     .. param:: const psa_key_attributes_t * attributes
         The attributes for the new key.
-        This function uses the attributes as follows:
 
-        *   The key type is required.
+        The following attributes are required for all keys:
+
+        *   The key type.
             All PAKE algorithms can output a key of type :code:`PSA_KEY_TYPE_DERIVE` or :code:`PSA_KEY_TYPE_HMAC`.
             PAKE algorithms that produce a pseudo-random shared secret, can also output block-cipher key types, for example :code:`PSA_KEY_TYPE_AES`.
             Refer to the documentation of individual PAKE algorithms for more information.
-        *   The key size in ``attributes`` must be zero.
-            The returned key size is always determined from the PAKE shared secret.
-        *   The key permitted-algorithm policy is required for keys that will be used for a cryptographic operation.
-            See :secref:`permitted-algorithms`.
-        *   The key usage flags define what operations are permitted with the key.
-            See :secref:`key-usage-flags`.
-        *   The key lifetime and identifier are required for a persistent key.
+
+        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`.
+
+        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 size of the PAKE shared secret.
 
         .. 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 :code:`psa_get_key_attributes()` with the key's identifier.
+            The final attributes of the new key can be queried by calling `psa_get_key_attributes()` with the key's identifier.
+
     .. param:: psa_key_id_t * key
         On success, an identifier for the newly created key. :code:`PSA_KEY_ID_NULL` on failure.
 
@@ -1010,6 +1019,11 @@ Multi-part PAKE operations
     .. retval:: PSA_ERROR_DATA_CORRUPT
     .. retval:: PSA_ERROR_DATA_INVALID
 
+    The shared secret is retrieved as a key.
+    Its location, policy, and type are taken from ``attributes``.
+
+    The size of the returned key is always the bit-size of the PAKE shared secret, rounded up to a whole number of bytes. The size is of the shared secret is dependent on the PAKE algorithm and cipher suite.
+
     This is the final call in a PAKE operation, which retrieves the shared secret as a key.
     It is recommended that this key is used as an input to a key derivation operation to produce additional cryptographic keys.
     For some PAKE algorithms, the shared secret is also suitable for use as a key in cryptographic operations such as encryption.