Add new key agreement function

doc/crypto/api.db/psa/crypto.h

@@ -96,7 +96,8 @@ typedef /* implementation-defined type */ psa_mac_operation_t;
 #define PSA_ALG_IS_MAC(alg) /* specification-defined value */
 #define PSA_ALG_IS_PBKDF2_HMAC(alg) /* specification-defined value */
 #define PSA_ALG_IS_RANDOMIZED_ECDSA(alg) /* specification-defined value */
-#define PSA_ALG_IS_RAW_KEY_AGREEMENT(alg) /* specification-defined value */
+#define PSA_ALG_IS_RAW_KEY_AGREEMENT(alg) \
+    PSA_ALG_IS_STANDALONE_KEY_AGREEMENT(alg)
 #define PSA_ALG_IS_RSA_OAEP(alg) /* specification-defined value */
 #define PSA_ALG_IS_RSA_PKCS1V15_SIGN(alg) /* specification-defined value */
 #define PSA_ALG_IS_RSA_PSS(alg) /* specification-defined value */
@@ -105,6 +106,8 @@ typedef /* implementation-defined type */ psa_mac_operation_t;
 #define PSA_ALG_IS_SIGN(alg) /* specification-defined value */
 #define PSA_ALG_IS_SIGN_HASH(alg) /* specification-defined value */
 #define PSA_ALG_IS_SIGN_MESSAGE(alg) /* specification-defined value */
+#define PSA_ALG_IS_STANDALONE_KEY_AGREEMENT(alg) \
+    /* specification-defined value */
 #define PSA_ALG_IS_STREAM_CIPHER(alg) /* specification-defined value */
 #define PSA_ALG_IS_TLS12_PRF(alg) /* specification-defined value */
 #define PSA_ALG_IS_TLS12_PSK_TO_MS(alg) /* specification-defined value */
@@ -485,6 +488,12 @@ psa_status_t psa_import_key(const psa_key_attributes_t * attributes,
                             const uint8_t * data,
                             size_t data_length,
                             psa_key_id_t * key);
+psa_status_t psa_key_agreement(psa_key_id_t private_key,
+                               const uint8_t * peer_key,
+                               size_t peer_key_length,
+                               psa_algorithm_t alg,
+                               const psa_key_attributes_t * attributes,
+                               psa_key_id_t * key);
 psa_key_attributes_t psa_key_attributes_init(void);
 psa_status_t psa_key_derivation_abort(psa_key_derivation_operation_t * operation);
 psa_status_t psa_key_derivation_get_capacity(const psa_key_derivation_operation_t * operation,

doc/crypto/api/keys/management.rst

@@ -523,7 +523,7 @@ Key export
 Key formats
 -----------
 
-This section defines the format of the key data that an implementation is required to support when importing and exporting keys. Keys can be imported using `psa_import_key()`, and exported using `psa_export_key()` or `psa_export_public_key()`.
+This section defines the format of the key data that an implementation is required to support when importing and exporting keys. Keys can be imported using `psa_import_key()`, and exported using `psa_export_key()` or `psa_export_public_key()`. The public key formats are also used for the key agreement functions, see :secref:`key-agreement`.
 
 .. list-table:: Standard key formats
     :name: std-key-formats

doc/crypto/api/keys/policy.rst

@@ -33,7 +33,7 @@ The following algorithm policies are supported:
 *   `PSA_ALG_NONE` does not permit any cryptographic operation with the key. The key can still be used for non-cryptographic actions such as exporting, if permitted by the usage flags.
 *   A specific algorithm value permits exactly that particular algorithm.
 *   A signature algorithm constructed with `PSA_ALG_ANY_HASH` permits the specified signature scheme with any hash algorithm. In addition, :code:`PSA_ALG_RSA_PKCS1V15_SIGN(PSA_ALG_ANY_HASH)` also permits the `PSA_ALG_RSA_PKCS1V15_SIGN_RAW` signature algorithm.
-*   A raw key agreement algorithm also permits the specified key agreement scheme to be combined with any key derivation algorithm.
+*   A standalone key agreement algorithm also permits the specified key agreement scheme to be combined with any key derivation algorithm.
 *   An algorithm built from `PSA_ALG_AT_LEAST_THIS_LENGTH_MAC()` permits any MAC algorithm from the same base class (for example, CMAC) which computes or verifies a MAC length greater than or equal to the length encoded in the wildcard algorithm.
 *   An algorithm built from `PSA_ALG_AEAD_WITH_AT_LEAST_THIS_LENGTH_TAG()` permits any AEAD algorithm from the same base class (for example, CCM) which computes or verifies a tag length greater than or equal to the length encoded in the wildcard algorithm.
 
@@ -231,6 +231,7 @@ The usage flags are encoded in a bitmask, which has the type `psa_key_usage_t`.
 
     This flag must be present on keys used with the following APIs:
 
+    *   `psa_key_agreement()`
     *   `psa_key_derivation_key_agreement()`
     *   `psa_raw_key_agreement()`
 

doc/crypto/api/ops/kdf.rst

@@ -218,7 +218,7 @@ Key derivation algorithms
     *   The other secret depends on the key exchange specified in the cipher suite:
 
         -   For a plain PSK cipher suite (:RFC:`4279#2`), omit `PSA_KEY_DERIVATION_INPUT_OTHER_SECRET`.
-        -   For a DHE-PSK (:RFC:`4279#3`) or ECDHE-PSK cipher suite (:RFC-title:`5489#2`), the other secret should be the output of the `PSA_ALG_FFDH` or `PSA_ALG_ECDH` key agreement performed with the peer. The recommended way to pass this input is to use a key derivation algorithm constructed as :code:`PSA_ALG_KEY_AGREEMENT(ka_alg, PSA_ALG_TLS12_PSK_TO_MS(hash_alg))` and to call `psa_key_derivation_key_agreement()`. Alternatively, this input may be an output of `psa_raw_key_agreement()` passed with `psa_key_derivation_input_bytes()`, or an equivalent input passed with `psa_key_derivation_input_bytes()` or `psa_key_derivation_input_key()`.
+        -   For a DHE-PSK (:RFC:`4279#3`) or ECDHE-PSK cipher suite (:RFC-title:`5489#2`), the other secret should be the output of the `PSA_ALG_FFDH` or `PSA_ALG_ECDH` key agreement performed with the peer. The recommended way to pass this input is to use a key derivation algorithm constructed as :code:`PSA_ALG_KEY_AGREEMENT(ka_alg, PSA_ALG_TLS12_PSK_TO_MS(hash_alg))` and to call `psa_key_derivation_key_agreement()`. Alternatively, this input may be an output of `psa_key_agreement()` passed with `psa_key_derivation_input_key()`, or an equivalent input passed with `psa_key_derivation_input_bytes()` or `psa_key_derivation_input_key()`.
         -   For a RSA-PSK cipher suite (:RFC:`4279#4`), the other secret should be the 48-byte client challenge (the ``PreMasterSecret`` of :RFC:`5246#7.4.7.1`) concatenation of the TLS version and a 46-byte random string chosen by the client. On the server, this is typically an output of `psa_asymmetric_decrypt()` using `PSA_ALG_RSA_PKCS1V15_CRYPT`, passed to the key derivation operation with `psa_key_derivation_input_bytes()`.
 
     *   The label is ``"master secret"`` or ``"extended master secret"``.

doc/crypto/appendix/encodings.rst

@@ -348,14 +348,14 @@ a.  ``hh`` is the HASH-TYPE for the hash algorithm, ``hash_alg``, used to constr
 Key agreement algorithm encoding
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-A key agreement algorithm identifier can either be for the raw key agreement algorithm, or for a combined key agreement with key derivation algorithm. The former can only be used with `psa_raw_key_agreement()`, while the latter are used with `psa_key_derivation_key_agreement()` and the shared secret is not exposed to the client.
+A key agreement algorithm identifier can either be for the standalone key agreement algorithm, or for a combined key agreement with key derivation algorithm. The former can only be used with `psa_key_agreement()` and `psa_raw_key_agreement()`, while the latter are used with `psa_key_derivation_key_agreement()`.
 
-The algorithm identifier for raw key agreement algorithms defined in this specification are encoded as shown in :numref:`fig-ka-raw-fields`.
+The algorithm identifier for standalone key agreement algorithms defined in this specification are encoded as shown in :numref:`fig-ka-raw-fields`.
 
 .. figure:: ../figure/encoding/ka_raw.*
     :name: fig-ka-raw-fields
 
-    Raw key agreement algorithm encoding
+    Standalone key agreement algorithm encoding
 
 The defined values for KA-TYPE are shown in :numref:`table-ka-type`.
 
@@ -369,13 +369,13 @@ The defined values for KA-TYPE are shown in :numref:`table-ka-type`.
     FFDH, ``0x01``, `PSA_ALG_FFDH`, ``0x09010000``
     ECDH, ``0x02``, `PSA_ALG_ECDH`, ``0x09020000``
 
-A combined key agreement is constructed by a bitwise OR of the raw key agreement algorithm identifier and the key derivation algorithm identifier. This operation is provided by the `PSA_ALG_KEY_AGREEMENT()` macro.
+A combined key agreement is constructed by a bitwise OR of the standalone key agreement algorithm identifier and the key derivation algorithm identifier. This operation is provided by the `PSA_ALG_KEY_AGREEMENT()` macro.
 
 .. figure:: ../figure/encoding/ka_combined.*
 
     Combined key agreement algorithm encoding
 
-The underlying raw key agreement algorithm can be extracted from the KA-TYPE field, and the key derivation algorithm from the KDF-TYPE and HASH-TYPE fields.
+The underlying standalone key agreement algorithm can be extracted from the KA-TYPE field, and the key derivation algorithm from the KDF-TYPE and HASH-TYPE fields.
 
 
 .. _key-type-encoding:

doc/crypto/appendix/history.rst

@@ -21,12 +21,16 @@ Changes to the API
 *   Changed the policy for `psa_key_derivation_verify_bytes()` and `psa_key_derivation_verify_key()`, so that these functions are also permitted when an input key has the `PSA_KEY_USAGE_DERIVE` usage flag.
 *   Removed the special treatment of :code:`PSA_ERROR_INVALID_SIGNATURE` for key derivation operations. A verification failure in `psa_key_derivation_verify_bytes()` and `psa_key_derivation_verify_key()` now puts the operation into an error state.
 
+*   Added `psa_key_agreement()` for standalone key agreement that outputs to a new key object. Also added `PSA_ALG_IS_STANDALONE_KEY_AGREEMENT()` as a synonym for `PSA_ALG_IS_RAW_KEY_AGREEMENT()`.
+
 Clarifications and fixes
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
 *   Clarified the behavior of a key derivation operation when there is insufficient capacity for a call to `psa_key_derivation_output_bytes()`, `psa_key_derivation_output_key()`, `psa_key_derivation_verify_bytes()`, or `psa_key_derivation_verify_key()`.
 *   Reserved the value ``0`` for most enum-like integral types.
 
+*   Changed terminology for clarification: a 'raw key agreement' algorithm is now a 'standalone key agreement', and a 'full key agreement' is a 'combined key agreement'.
+
 Other changes
 ~~~~~~~~~~~~~
 

doc/crypto/appendix/specdef_values.rst

@@ -127,9 +127,6 @@ Algorithm macros
     #define PSA_ALG_IS_RANDOMIZED_ECDSA(alg) \
         (((alg) & ~0x000000ff) == 0x06000600)
 
-    #define PSA_ALG_IS_RAW_KEY_AGREEMENT(alg) \
-        (((alg) & 0x7f00ffff) == 0x09000000)
-
     #define PSA_ALG_IS_RSA_OAEP(alg) \
         (((alg) & ~0x000000ff) == 0x07000300)
 
@@ -155,6 +152,9 @@ Algorithm macros
         (PSA_ALG_IS_SIGN(alg) && \
          (alg) != PSA_ALG_ECDSA_ANY && (alg) != PSA_ALG_RSA_PKCS1V15_SIGN_RAW)
 
+    #define PSA_ALG_IS_STANDALONE_KEY_AGREEMENT(alg) \
+        (((alg) & 0x7f00ffff) == 0x09000000)
+
     #define PSA_ALG_IS_STREAM_CIPHER(alg) \
         (((alg) & 0x7f800000) == 0x04800000)
 

doc/crypto/overview/functionality.rst

@@ -339,7 +339,7 @@ This specification defines interfaces for the following types of asymmetric cryp
 *   Asymmetric signature. See :secref:`sign`.
 *   Two-way key agreement (also known as key establishment). See :secref:`key-agreement`.
 
-For asymmetric encryption and signature, the API provides *single-part* functions. For key agreement, the API provides a single-part function and an additional input method for a key derivation operation.
+For asymmetric encryption and signature, the API provides *single-part* functions. For key agreement, the API provides single-part functions and an additional input method for a key derivation operation.
 
 
 Randomness and key generation