psa_key_derivation_key_agreement() function

The key derivation operation object to use. It must have been set up with psa_key_derivation_setup() with a key agreement and derivation algorithm \c alg (\c PSA_ALG_XXX value such that #PSA_ALG_IS_KEY_AGREEMENT(\c alg) is true and #PSA_ALG_IS_RAW_KEY_AGREEMENT(\c alg) is false). The operation must be ready for an input of the type given by \p step.

Which step the input data is for.

Identifier of the private key to use. It must allow the usage #PSA_KEY_USAGE_DERIVE.

Public key of the peer. The peer key must be in the same format that psa_import_key() accepts for the public key type corresponding to the type of private_key. That is, this function performs the equivalent of #psa_import_key(..., `peer_key`, `peer_key_length`) where with key attributes indicating the public key type corresponding to the type of `private_key`. For example, for EC keys, this means that peer_key is interpreted as a point on the curve that the private key is on. The standard formats for public keys are documented in the documentation of psa_export_public_key().

Size of \p peer_key in bytes.

Abort a key derivation operation. Aborting an operation frees all associated resources except for the \c operation structure itself. Once aborted, the operation object can be reused for another operation by calling psa_key_derivation_setup() again. This function may be called at any time after the operation object has been initialized as described in #psa_key_derivation_operation_t. In particular, it is valid to call psa_key_derivation_abort() twice, or to call psa_key_derivation_abort() on an operation that has not been set up.

Read some data from a key derivation operation. This function calculates output bytes from a key derivation algorithm and return those bytes. If you view the key derivation's output as a stream of bytes, this function destructively reads the requested number of bytes from the stream. The operation's capacity decreases by the number of bytes read. If this function returns an error status other than #PSA_ERROR_INSUFFICIENT_DATA, the operation enters an error state and must be aborted by calling psa_key_derivation_abort().

Derive a key from an ongoing key derivation operation with custom production parameters. See the description of psa_key_derivation_out_key() for the operation of this function with the default production parameters. Mbed TLS currently does not currently support any non-default production parameters.

Provide an input for key derivation or key agreement. Which inputs are required and in what order depends on the algorithm. Refer to the documentation of each key derivation or key agreement algorithm for information. This function passes direct inputs, which is usually correct for non-secret inputs. To pass a secret input, which should be in a key object, call psa_key_derivation_input_key() instead of this function. Refer to the documentation of individual step types (`PSA_KEY_DERIVATION_INPUT_xxx` values of type ::psa_key_derivation_step_t) for more information. If this function returns an error status, the operation enters an error state and must be aborted by calling psa_key_derivation_abort().

Set up a key derivation operation. A key derivation algorithm takes some inputs and uses them to generate a byte stream in a deterministic way. This byte stream can be used to produce keys and other cryptographic material. To derive a key: -# Start with an initialized object of type #psa_key_derivation_operation_t. -# Call psa_key_derivation_setup() to select the algorithm. -# Provide the inputs for the key derivation by calling psa_key_derivation_input_bytes() or psa_key_derivation_input_key() as appropriate. Which inputs are needed, in what order, and whether they may be keys and if so of what type depends on the algorithm. -# Optionally set the operation's maximum capacity with psa_key_derivation_set_capacity(). You may do this before, in the middle of or after providing inputs. For some algorithms, this step is mandatory because the output depends on the maximum capacity. -# To derive a key, call psa_key_derivation_output_key() or psa_key_derivation_output_key_custom(). To derive a byte string for a different purpose, call psa_key_derivation_output_bytes(). Successive calls to these functions use successive output bytes calculated by the key derivation algorithm. -# Clean up the key derivation operation object with psa_key_derivation_abort(). If this function returns an error, the key derivation operation object is not changed. If an error occurs at any step after a call to psa_key_derivation_setup(), the operation will need to be reset by a call to psa_key_derivation_abort(). Implementations must reject an attempt to derive a key of size 0.

Retrieve the current capacity of a key derivation operation. The capacity of a key derivation is the maximum number of bytes that it can return. When you get *N* bytes of output from a key derivation operation, this reduces its capacity by *N*.

Set the maximum capacity of a key derivation operation. The capacity of a key derivation operation is the maximum number of bytes that the key derivation operation can return from this point onwards.

Provide a numeric input for key derivation or key agreement. Which inputs are required and in what order depends on the algorithm. However, when an algorithm requires a particular order, numeric inputs usually come first as they tend to be configuration parameters. Refer to the documentation of each key derivation or key agreement algorithm for information. This function is used for inputs which are fixed-size non-negative integers. If this function returns an error status, the operation enters an error state and must be aborted by calling psa_key_derivation_abort().

Provide an input for key derivation in the form of a key. Which inputs are required and in what order depends on the algorithm. Refer to the documentation of each key derivation or key agreement algorithm for information. This function obtains input from a key object, which is usually correct for secret inputs or for non-secret personalization strings kept in the key store. To pass a non-secret parameter which is not in the key store, call psa_key_derivation_input_bytes() instead of this function. Refer to the documentation of individual step types (`PSA_KEY_DERIVATION_INPUT_xxx` values of type ::psa_key_derivation_step_t) for more information. If this function returns an error status, the operation enters an error state and must be aborted by calling psa_key_derivation_abort().

Derive a key from an ongoing key derivation operation. This function calculates output bytes from a key derivation algorithm and uses those bytes to generate a key deterministically. The key's location, usage policy, type and size are taken from \p attributes. If you view the key derivation's output as a stream of bytes, this function destructively reads as many bytes as required from the stream. The operation's capacity decreases by the number of bytes read. If this function returns an error status other than #PSA_ERROR_INSUFFICIENT_DATA, the operation enters an error state and must be aborted by calling psa_key_derivation_abort(). How much output is produced and consumed from the operation, and how the key is derived, depends on the key type and on the key size (denoted \c bits below): - For key types for which the key is an arbitrary sequence of bytes of a given size, this function is functionally equivalent to calling #psa_key_derivation_output_bytes and passing the resulting output to #psa_import_key. However, this function has a security benefit: if the implementation provides an isolation boundary then the key material is not exposed outside the isolation boundary. As a consequence, for these key types, this function always consumes exactly (\c bits / 8) bytes from the operation. The following key types defined in this specification follow this scheme: - #PSA_KEY_TYPE_AES; - #PSA_KEY_TYPE_ARIA; - #PSA_KEY_TYPE_CAMELLIA; - #PSA_KEY_TYPE_DERIVE; - #PSA_KEY_TYPE_HMAC; - #PSA_KEY_TYPE_PASSWORD_HASH. - For ECC keys on a Montgomery elliptic curve (#PSA_KEY_TYPE_ECC_KEY_PAIR(\c curve) where \c curve designates a Montgomery curve), this function always draws a byte string whose length is determined by the curve, and sets the mandatory bits accordingly. That is: - Curve25519 (#PSA_ECC_FAMILY_MONTGOMERY, 255 bits): draw a 32-byte string and process it as specified in RFC 7748 §5. - Curve448 (#PSA_ECC_FAMILY_MONTGOMERY, 448 bits): draw a 56-byte string and process it as specified in RFC 7748 §5. - For key types for which the key is represented by a single sequence of \c bits bits with constraints as to which bit sequences are acceptable, this function draws a byte string of length (\c bits / 8) bytes rounded up to the nearest whole number of bytes. If the resulting byte string is acceptable, it becomes the key, otherwise the drawn bytes are discarded. This process is repeated until an acceptable byte string is drawn. The byte string drawn from the operation is interpreted as specified for the output produced by psa_export_key(). The following key types defined in this specification follow this scheme: - #PSA_KEY_TYPE_DES. Force-set the parity bits, but discard forbidden weak keys. For 2-key and 3-key triple-DES, the three keys are generated successively (for example, for 3-key triple-DES, if the first 8 bytes specify a weak key and the next 8 bytes do not, discard the first 8 bytes, use the next 8 bytes as the first key, and continue reading output from the operation to derive the other two keys). - Finite-field Diffie-Hellman keys (#PSA_KEY_TYPE_DH_KEY_PAIR(\c group) where \c group designates any Diffie-Hellman group) and ECC keys on a Weierstrass elliptic curve (#PSA_KEY_TYPE_ECC_KEY_PAIR(\c curve) where \c curve designates a Weierstrass curve). For these key types, interpret the byte string as integer in big-endian order. Discard it if it is not in the range [0, *N* - 2] where *N* is the boundary of the private key domain (the prime *p* for Diffie-Hellman, the subprime *q* for DSA, or the order of the curve's base point for ECC). Add 1 to the resulting integer and use this as the private key *x*. This method allows compliance to NIST standards, specifically the methods titled "key-pair generation by testing candidates" in NIST SP 800-56A §5.6.1.1.4 for Diffie-Hellman, in FIPS 186-4 §B.1.2 for DSA, and in NIST SP 800-56A §5.6.1.2.2 or FIPS 186-4 §B.4.2 for elliptic curve keys. - For other key types, including #PSA_KEY_TYPE_RSA_KEY_PAIR, the way in which the operation output is consumed is implementation-defined. In all cases, the data that is read is discarded from the operation. The operation's capacity is decreased by the number of bytes read. For algorithms that take an input step #PSA_KEY_DERIVATION_INPUT_SECRET, the input to that step must be provided with psa_key_derivation_input_key(). Future versions of this specification may include additional restrictions on the derived key based on the attributes and strength of the secret key.

Derive a key from an ongoing key derivation operation with custom production parameters.

Get implicitly confirmed shared secret from a PAKE. At this point there is a cryptographic guarantee that only the authenticated party who used the same password is able to compute the key. But there is no guarantee that the peer is the party it claims to be and was able to do so. That is, the authentication is only implicit. Since the peer is not authenticated yet, no action should be taken yet that assumes that the peer is who it claims to be. For example, do not access restricted files on the peer's behalf until an explicit authentication has succeeded. This function can be called after the key exchange phase of the operation has completed. It imports the shared secret output of the PAKE into the provided derivation operation. The input step #PSA_KEY_DERIVATION_INPUT_SECRET is used when placing the shared key material in the key derivation operation. The exact sequence of calls to perform a password-authenticated key exchange depends on the algorithm in use. Refer to the documentation of individual PAKE algorithm types (`PSA_ALG_XXX` values of type ::psa_algorithm_t such that #PSA_ALG_IS_PAKE(\c alg) is true) for more information. When this function returns successfully, \p operation becomes inactive. If this function returns an error status, both \p operation and \c key_derivation operations enter an error state and must be aborted by calling psa_pake_abort() and psa_key_derivation_abort() respectively.

Compare output data from a key derivation operation to an expected value. This function calculates output bytes from a key derivation algorithm and compares those bytes to an expected value in constant time. If you view the key derivation's output as a stream of bytes, this function destructively reads the expected number of bytes from the stream before comparing them. The operation's capacity decreases by the number of bytes read. This is functionally equivalent to the following code: except (1) it works even if the key's policy does not allow outputting the bytes, and (2) the comparison will be done in constant time. If this function returns an error status other than #PSA_ERROR_INSUFFICIENT_DATA or #PSA_ERROR_INVALID_SIGNATURE, the operation enters an error state and must be aborted by calling psa_key_derivation_abort().

Compare output data from a key derivation operation to an expected value stored in a key object. This function calculates output bytes from a key derivation algorithm and compares those bytes to an expected value, provided as key of type #PSA_KEY_TYPE_PASSWORD_HASH. If you view the key derivation's output as a stream of bytes, this function destructively reads the number of bytes corresponding to the length of the expected value from the stream before comparing them. The operation's capacity decreases by the number of bytes read. This is functionally equivalent to exporting the key and calling psa_key_derivation_verify_bytes() on the result, except that it works even if the key cannot be exported. If this function returns an error status other than #PSA_ERROR_INSUFFICIENT_DATA or #PSA_ERROR_INVALID_SIGNATURE, the operation enters an error state and must be aborted by calling psa_key_derivation_abort().