Skip to content

Change the PAKE output function to return a key #114

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
athoelke merged 10 commits into from
Nov 29, 2023
Merged

Change the PAKE output function to return a key #114

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
ad7ef6a
pake: change the key output function
athoelke Oct 30, 2023
6478ed5
Update J-PAKE flow graphic
athoelke Oct 31, 2023
bcc76cf
Reversed the definitions for PAKE key confirmation values
athoelke Oct 31, 2023
311ae2c
Fix typo
athoelke Nov 1, 2023
79c0d7c
Tidy up resolved issues.
athoelke Nov 1, 2023
ad84a2b
Removed uncertainty about behavior or psa_pake_get_shared_key()
athoelke Nov 13, 2023
91e841b
Removed redundant (legacy) paragraph
athoelke Nov 13, 2023
cdf041c
Specify key types output by psa_pake_get_shared_key()
athoelke Nov 14, 2023
afeddf7
Remove unwanted blank line
athoelke Nov 21, 2023
1be1896
Correct statement about cipher suite attributes
athoelke Nov 29, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 8 additions & 2 deletions doc/ext-pake/api.db/psa/crypto-pake.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,7 @@ typedef uint8_t psa_pake_step_t;
#define PSA_ALG_IS_PAKE(alg) /* specification-defined value */
#define PSA_ALG_JPAKE(hash_alg) /* specification-defined value */
#define PSA_PAKE_CIPHER_SUITE_INIT /* implementation-defined value */
#define PSA_PAKE_CONFIRMED_KEY 0
#define PSA_PAKE_INPUT_MAX_SIZE /* implementation-defined value */
#define PSA_PAKE_INPUT_SIZE(alg, primitive, input_step) \
/* implementation-defined value */
Expand All @@ -32,16 +33,21 @@ typedef uint8_t psa_pake_step_t;
#define PSA_PAKE_STEP_KEY_SHARE ((psa_pake_step_t)0x01)
#define PSA_PAKE_STEP_ZK_PROOF ((psa_pake_step_t)0x03)
#define PSA_PAKE_STEP_ZK_PUBLIC ((psa_pake_step_t)0x02)
#define PSA_PAKE_UNCONFIRMED_KEY 1
psa_status_t psa_pake_abort(psa_pake_operation_t * operation);
psa_pake_cipher_suite_t psa_pake_cipher_suite_init(void);
psa_algorithm_t psa_pake_cs_get_algorithm(const psa_pake_cipher_suite_t* cipher_suite);
uint32_t psa_pake_cs_get_key_confirmation(const psa_pake_cipher_suite_t* cipher_suite);
psa_pake_primitive_t psa_pake_cs_get_primitive(const psa_pake_cipher_suite_t* cipher_suite);
void psa_pake_cs_set_algorithm(psa_pake_cipher_suite_t* cipher_suite,
psa_algorithm_t alg);
void psa_pake_cs_set_key_confirmation(psa_pake_cipher_suite_t* cipher_suite,
uint32_t key_confirmation);
void psa_pake_cs_set_primitive(psa_pake_cipher_suite_t* cipher_suite,
psa_pake_primitive_t primitive);
psa_status_t psa_pake_get_implicit_key(psa_pake_operation_t *operation,
psa_key_derivation_operation_t *output);
psa_status_t psa_pake_get_shared_key(psa_pake_operation_t *operation,
const psa_key_attributes_t * attributes,
psa_key_id_t * key);
Copy link
Copy Markdown
Contributor

@yanesca yanesca Nov 6, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The situation here is very similar to the case of key agreement schemes. There we have two APIs: psa_raw_key_agreement() and psa_key_derivation_key_agreement(). Outputing a key derivation object achieves the same as the latter. Outputing a key instead is somewhere between the two: the Crypto API implementation doesn't have full control over the use of the output, but doesn't release the output to the user either.

Outputting a key derivation object has the advantage that the implementation knows about the PAKE when inputting the key to the derivation object and can prevent misuse better or even adjust serialisation format if needed. If the PAKE output is released as a key, the only information the implementation can rely on is the length.

Why do we need to switch to outputting a key?

Copy link
Copy Markdown
Contributor Author

@athoelke athoelke Nov 6, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why do we need to switch to outputting a key?

See #86. Use cases that use separate derivations to create multiple keys from the output of the PAKE. The existing API cannot be used in such systems, and maintaining the existing API alongside a new one to return a key does not appear to deliver substantial benefit for the application or implementation.

Copy link
Copy Markdown
Contributor Author

@athoelke athoelke Nov 6, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The situation here is very similar to the case of key agreement schemes. There we have two APIs: psa_raw_key_agreement() and psa_key_derivation_key_agreement().

But see also the recent discussions: #85 and #101. One of the conclusions there is that with more time and review when v1.0 was published, psa_key_agreement() would probably be the only key agreement interface, enabling access (via export) to the raw material, but defaulting to keeping the output protected, for use in one (or more) KDF operations. This would also have reduced the algorithm identifier complexity created by combined key agreement and key derivation algorithms.

psa_status_t psa_pake_input(psa_pake_operation_t *operation,
psa_pake_step_t step,
const uint8_t *input,
Expand Down
241 changes: 199 additions & 42 deletions doc/ext-pake/api/pake.rst
View file
Open in desktop

Large diffs are not rendered by default.

3 changes: 3 additions & 0 deletions doc/ext-pake/appendix/history.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,9 @@ API changes
* Add the `PSA_PAKE_STEP_CONFIRM` PAKE step for input and output of key confirmation values.
* Add `psa_pake_set_context()` to set context data for a PAKE operation.

* Replaced :code:`psa_pake_get_implicit_key()` with :code:`psa_pake_get_shared_key()`. This returns a new key containing the shared secret, instead of injecting the shared secret into a key derivation operation.
* Added a key confirmation attribute to the PAKE cipher suite. This indicates whether the application wants to extract the shared secret before, or after, key confirmation. See :secref:`pake-cipher-suite`.

Clarifications
~~~~~~~~~~~~~~

Expand Down
Binary file modified doc/ext-pake/figure/j-pake.pdf
View file
Open in desktop
Binary file not shown.
2 changes: 1 addition & 1 deletion doc/ext-pake/figure/j-pake.pdf.license
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,2 +1,2 @@
SPDX-FileCopyrightText: Copyright 2022 Arm Limited and/or its affiliates <open-source-office@arm.com>
SPDX-FileCopyrightText: Copyright 2022-2023 Arm Limited and/or its affiliates <open-source-office@arm.com>
SPDX-License-Identifier: CC-BY-SA-4.0 AND LicenseRef-Patent-license
4 changes: 2 additions & 2 deletions doc/ext-pake/figure/j-pake.puml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
' SPDX-FileCopyrightText: Copyright 2022 Arm Limited and/or its affiliates <open-source-office@arm.com>
' SPDX-FileCopyrightText: Copyright 2022-2023 Arm Limited and/or its affiliates <open-source-office@arm.com>
' SPDX-License-Identifier: CC-BY-SA-4.0 AND LicenseRef-Patent-license

@startuml
Expand Down Expand Up @@ -39,6 +39,6 @@

note over User, Peer: If both sides used the same secret //s//, then //Ka// = //Kb//

User -> User: ""psa_pake_get_implicit_key()"" to extract //Ka//
User -> User: ""psa_pake_get_shared_key()"" to extract //Ka//

@enduml
2 changes: 1 addition & 1 deletion doc/ext-pake/figure/j-pake.svg
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
2 changes: 1 addition & 1 deletion doc/ext-pake/figure/j-pake.svg.license
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,2 +1,2 @@
SPDX-FileCopyrightText: Copyright 2022 Arm Limited and/or its affiliates <open-source-office@arm.com>
SPDX-FileCopyrightText: Copyright 2022-2023 Arm Limited and/or its affiliates <open-source-office@arm.com>
SPDX-License-Identifier: CC-BY-SA-4.0 AND LicenseRef-Patent-license