Add new key agreement function

[athoelke]

Add psa_key_agreement() as a standalone function that outputs to a new derivation key.

Fixes #85

[athoelke]

After some further consideration on the open issues:

1. Is it acceptable for the function to be required to return a key of type PSA_KEY_TYPE_DERIVE? Should we require, or even permit, the caller to specify a key type?

In alignment with the other APIs that return a key, this one should require that caller does set the key type in the attributes.

• An implementation must permit PSA_KEY_TYPE_DERIVE and PSA_KEY_TYPE_RAW
• All asymmetric keys (both public-keys and key-pairs) are not permitted (INVALID_ARGUMENT)
• It is reasonably safe to use the output as an HMAC key or as a PASSWORD (for input to PAKE or password-stretching algorithms). Should we universally permit such key types?
• Use of the output as a symmetric block-cipher or stream-cipher keys is strongly discouraged (for some ciphers this could lead to key discovery). Should we universally deny such key types?

2. Is it acceptable for the function to be required to return the entire shared secret as the key value? Should we require, or even permit, the caller to specify a key size?

Truncating the output is unnecessary, and risks making the shared secret discoverable. This function should always return the entire shared secret. In alignment with psa_import_key() and psa_copy_key() where the key size can be determined from other inputs, the caller should be permitted to either provide attributes with a bit size of zero, or with a bit size that exactly matches the key agreement output size (in bits).

[MarcusJGStreets]

The latter, I would even think about deprecating psa_raw_key_agreement() and replace it with a new function with the canonical argument order. Sent from Outlook for Android<https://aka.ms/AAb9ysg>

________________________________ From: Andrew Thoelke ***@***.***> Sent: Tuesday, October 31, 2023 9:18:55 PM To: ARM-software/psa-api ***@***.***> Cc: Marcus Streets ***@***.***>; Review requested ***@***.***> Subject: Re: [ARM-software/psa-api] Add new key agreement function (PR #101) @athoelke commented on this pull request.

________________________________ In doc/crypto/api/ops/ka.rst<#101 (comment)>:

@@ -114,6 +122,91 @@ Key agreement algorithms

Standalone key agreement ------------------------ +.. function:: psa_key_agreement + + .. summary:: + Perform a key agreement and return the shared secret as a derivation key. + + .. param:: psa_algorithm_t alg So that narrows it to two options: parameter consistency with psa_raw_key_agreement() or with 'all the other APIs'? - do I detect a preference for the latter? (That is my preference and leave raw key agreement as the odd one out) — Reply to this email directly, view it on GitHub<#101 (comment)>, or unsubscribe<https://github.com/notifications/unsubscribe-auth/AIU75VSHY63CXANLMOHDHNTYCFTL7AVCNFSM6AAAAAA4Z7SP2WVHI2DSMVQWIX3LMV43YUDVNRWFEZLROVSXG5CSMV3GSZLXHMYTOMBXGI2TMMRXGI>. You are receiving this because your review was requested.Message ID: ***@***.***> IMPORTANT NOTICE: The contents of this email and any attachments are confidential and may also be privileged. If you are not the intended recipient, please notify the sender immediately and do not disclose the contents to any other person, use it for any purpose, or store or copy the information in any medium. Thank you.

[gilles-peskine-arm]

The overall design looks good to me, but there are editorial mistakes and some places are unclear.

[gilles-peskine-arm]

LGTM except for one problem with shared secret size vs key size.

Reviewer is happy for the PR to now be merged