From eaac3f2863c604bf093da806551b6fff07bf92b9 Mon Sep 17 00:00:00 2001 From: Kusumit Ghoderao Date: Tue, 27 Jun 2023 11:42:06 +0530 Subject: [PATCH 1/4] Address comments from PR #65 Signed-off-by: Kusumit Ghoderao --- doc/ext-pake/proposed/SPAKE2PLUS.svg | 4 ++ .../proposed/spake2plus_proposal_draft.md | 67 +++++++++++++++++++ 2 files changed, 71 insertions(+) create mode 100644 doc/ext-pake/proposed/SPAKE2PLUS.svg create mode 100644 doc/ext-pake/proposed/spake2plus_proposal_draft.md diff --git a/doc/ext-pake/proposed/SPAKE2PLUS.svg b/doc/ext-pake/proposed/SPAKE2PLUS.svg new file mode 100644 index 00000000..6fd84152 --- /dev/null +++ b/doc/ext-pake/proposed/SPAKE2PLUS.svg @@ -0,0 +1,4 @@ + + + +
Prover(A)
Prover(A)
Verifier(B)
Verifier(B)
Shared Information : cipher suite, ProverID, VerifierID, Context(ADDITIONAL_DATA)
Prover : W0, W1
Verifier : W0, L
Shared Information : cipher suite, ProverID, VerifierID, Context(ADDITIONAL_DATA)...
Registration
Registration

Inputs              : secret S
Intermediate
Output             : w0s || w1s
Outputs           : W0, W1 (Prover)
                          W0, L    (Verifier)

Inputs              : secret S...
psa_pake_setup()
psa_pake_set_user()
psa_pake_set_peer()
psa_pake_set_role(PSA_PAKE_ROLE_CLIENT)
psa_pake_input_key({w0s||w1s} / {W0||W1})
psa_pake_input(PSA_PAKE_STEP_ADDITIONAL_DATA)
psa_pake_setup()...
Compute X 
Compute X 
psa_pake_setup()
psa_pake_set_user()
psa_pake_set_peer()
psa_pake_set_role(PSA_PAKE_ROLE_SERVER)
psa_pake_input_key(W0||L)
psa_pake_input(PSA_PAKE_STEP_ADDITIONAL_DATA)
psa_pake_setup()...
psa_pake_output() for X
psa_pake_output() for X
(X = pA)
(X = pA)
Compute Z, V, TT
Kae, KcA, KcB
Compute Z, V, TT...
Compute Y, Z, V, TT
Kae, KcA, KcB
Compute Y, Z, V, TT...
psa_pake_output() for cA
psa_pake_output() for cA
psa_pake_output() for Y, cB
psa_pake_output() for Y, cB
(cA)
(cA)
(Y = pB, cB)
(Y = pB, cB)
psa_pake_input() for Y, cB
psa_pake_input() for Y, cB
psa_pake_input() for cA
psa_pake_input() for cA
Verify cB
Verify cB
Verify cA
Verify cA
psa_pake_get_explicit_key() to extract Ke
psa_pake_get_explicit_key() to extract Ke
psa_pake_get_explicit_key() to extract Ke
psa_pake_get_explicit_key() to extract Ke
psa_pake_input() for X
psa_pake_input() for XText is not SVG - cannot display \ No newline at end of file diff --git a/doc/ext-pake/proposed/spake2plus_proposal_draft.md b/doc/ext-pake/proposed/spake2plus_proposal_draft.md new file mode 100644 index 00000000..13170cc8 --- /dev/null +++ b/doc/ext-pake/proposed/spake2plus_proposal_draft.md @@ -0,0 +1,67 @@ +Introduction +------------ + +This document proposes protocol flow and high-level API changes required in PSA Cryptography API 1.1 PAKE Extension, to support the SPAKE2+ protocol. + +SPAKE2+ Version +--------------- + +SPAKE2+, an Augmented PAKE Draft 02, 10 December 2020 is considered for proposal. + +Link : [https://tools.ietf.org/pdf/draft-bar-cfrg-spake2plus-02.pdf](https://tools.ietf.org/pdf/draft-bar-cfrg-spake2plus-02.pdf) + +Remarks + +* SPAKE2+, an Augmented PAKE Draft 08, 5 May 2022 is the latest draft version. Link : [https://datatracker.ietf.org/doc/pdf/draft-bar-cfrg-spake2plus-08](https://datatracker.ietf.org/doc/pdf/draft-bar-cfrg-spake2plus-08) +* Shared Secret Key generation is not compatible between Draft 02 and 08. +* As most SPAKE2+ implementations e.g. Matter Specification Version 1.0 are based on Draft 02, this version is being considered for better interoperability. + +Expected PAKE API Flow : +------------------------------------ +![](SPAKE2PLUS.svg) + + +### Ciphersuite + +The current PAKE ciphersuite does not have encoding for MAC. The SPAKE2+ draft recommends HMAC and CMAC for the MAC operation, therefore we should add MAC field in the ciphersuite. +### Out of band set up + +SPAKE2+ has an offline initialization step where both parties may share parties identities and additional data (the context). This step is considered out of scope but these shared information may be required for SPAKE2+ protocol execution. + +**Shared Information** : ProverID, VerifierID and Context. + +**Input methods** : + +* Existing API's (when user is Prover) + * `psa_pake_set_user()` to input ProverID + * `psa_pake_set_peer()` to input VerifierID + * `psa_pake_set_role()` to set role as client/server + * `psa_pake_input()` with *(new)* `PSA_PAKE_STEP_ADDITIONAL_DATA` step to input context (additional data). + +### Password, PBKDF Output and Verification value (W0, W1, L) + +SPAKE2+ requires PBKDF Output and Verification value (W0, W1, L) generated from password as below : + + `w0s || w1s = PBKDF(len(pw) || pw || len(A) || A || len(B) || B)` + `W0 = w0s mod p` + `W1 = w1s mod p` + `L = w1*P` + +Computing these values is considered Out of Scope for PAKE API as this a registration phase which could happen out of actual protocol flow. + +Since W0 & W1 and L serve as registartion records and verification value, these values can be treated as secrets. + +**Input methods** : Proposing two different approaches, protocol flow diagram has approach 2 mentioned below + +1. Given secret nature of these values, we can use current `psa_pake_set_password_key()` to input these secrets. + 1. `W0||W1` as secret key on Prover side. + 2. `W0||L` as secret key on Verifier side. +2. Rename `psa_pake_set_password_key()` as `psa_pake_input_key()` to input mutiple secret keys and define steps for different keys + 1. For W0 and W1 on Prover side + 2. For W0 and L on Verifier side + +### Key confirmation + +Key confirmation is part of the SPAKE2+ protocol. Current PSA Cryptography API 1.1 PAKE Extension only supports implicit key confirmation. + +* New API `psa_pake_get_explicit_key()` is required to provide keys with explicit key confirmation. \ No newline at end of file From 828c19bc20f838191a8130fe844bd57a35a04a6f Mon Sep 17 00:00:00 2001 From: Kusumit Ghoderao Date: Fri, 1 Sep 2023 12:03:25 +0530 Subject: [PATCH 2/4] Add psa_pake_registration Signed-off-by: Kusumit Ghoderao --- doc/ext-pake/proposed/SPAKE2PLUS.svg | 2 +- .../proposed/spake2plus_proposal_draft.md | 43 +++++++++---------- 2 files changed, 21 insertions(+), 24 deletions(-) diff --git a/doc/ext-pake/proposed/SPAKE2PLUS.svg b/doc/ext-pake/proposed/SPAKE2PLUS.svg index 6fd84152..a89a20e0 100644 --- a/doc/ext-pake/proposed/SPAKE2PLUS.svg +++ b/doc/ext-pake/proposed/SPAKE2PLUS.svg @@ -1,4 +1,4 @@ -
Prover(A)
Prover(A)
Verifier(B)
Verifier(B)
Shared Information : cipher suite, ProverID, VerifierID, Context(ADDITIONAL_DATA)
Prover : W0, W1
Verifier : W0, L
Shared Information : cipher suite, ProverID, VerifierID, Context(ADDITIONAL_DATA)...
Registration
Registration

Inputs              : secret S
Intermediate
Output             : w0s || w1s
Outputs           : W0, W1 (Prover)
                          W0, L    (Verifier)

Inputs              : secret S...
psa_pake_setup()
psa_pake_set_user()
psa_pake_set_peer()
psa_pake_set_role(PSA_PAKE_ROLE_CLIENT)
psa_pake_input_key({w0s||w1s} / {W0||W1})
psa_pake_input(PSA_PAKE_STEP_ADDITIONAL_DATA)
psa_pake_setup()...
Compute X 
Compute X 
psa_pake_setup()
psa_pake_set_user()
psa_pake_set_peer()
psa_pake_set_role(PSA_PAKE_ROLE_SERVER)
psa_pake_input_key(W0||L)
psa_pake_input(PSA_PAKE_STEP_ADDITIONAL_DATA)
psa_pake_setup()...
psa_pake_output() for X
psa_pake_output() for X
(X = pA)
(X = pA)
Compute Z, V, TT
Kae, KcA, KcB
Compute Z, V, TT...
Compute Y, Z, V, TT
Kae, KcA, KcB
Compute Y, Z, V, TT...
psa_pake_output() for cA
psa_pake_output() for cA
psa_pake_output() for Y, cB
psa_pake_output() for Y, cB
(cA)
(cA)
(Y = pB, cB)
(Y = pB, cB)
psa_pake_input() for Y, cB
psa_pake_input() for Y, cB
psa_pake_input() for cA
psa_pake_input() for cA
Verify cB
Verify cB
Verify cA
Verify cA
psa_pake_get_explicit_key() to extract Ke
psa_pake_get_explicit_key() to extract Ke
psa_pake_get_explicit_key() to extract Ke
psa_pake_get_explicit_key() to extract Ke
psa_pake_input() for X
psa_pake_input() for XText is not SVG - cannot display \ No newline at end of file +
Prover(A)
Prover(A)
Verifier(B)
Verifier(B)
Shared Information : cipher suite, ProverID, VerifierID, Context
Prover : W0, W1
Verifier : W0, L
Shared Information : cipher suite, ProverID, VerifierID, Context...
Registration
Registration

Inputs                        : secret S
Intermediate Output  : w0s || w1s
Outputs                     : W0, W1 (Prover)
                                    W0, L    (Verifier)

Inputs                        : secret S...
psa_pake_setup()
psa_pake_set_user()
psa_pake_set_peer()
psa_pake_set_role(PSA_PAKE_ROLE_CLIENT)
psa_pake_set_context()
psa_pake_registration()
psa_pake_setup()...
Compute X 
Compute X 
psa_pake_setup()
psa_pake_set_user()
psa_pake_set_peer()
psa_pake_set_role(PSA_PAKE_ROLE_SERVER)
psa_pake_set_context()
psa_pake_setup()...
psa_pake_output() for X
psa_pake_output() for X
(X = pA)
(X = pA)
Compute Z, V, TT
Kae, KcA, KcB
Compute Z, V, TT...
Compute Y, Z, V, TT
Kae, KcA, KcB
Compute Y, Z, V, TT...
psa_pake_output() for cA
psa_pake_output() for cA
psa_pake_output() for Y, cB
psa_pake_output() for Y, cB
(cA)
(cA)
(Y = pB, cB)
(Y = pB, cB)
psa_pake_input() for Y, cB
psa_pake_input() for Y, cB
psa_pake_input() for cA
psa_pake_input() for cA
Verify cB
Verify cB
Verify cA
Verify cA
psa_pake_get_explicit_key() to extract Ke
psa_pake_get_explicit_key() to extract Ke
psa_pake_get_explicit_key() to extract Ke
psa_pake_get_explicit_key() to extract Ke
psa_pake_input() for X
psa_pake_input() for XText is not SVG - cannot display \ No newline at end of file diff --git a/doc/ext-pake/proposed/spake2plus_proposal_draft.md b/doc/ext-pake/proposed/spake2plus_proposal_draft.md index 13170cc8..83e9d28c 100644 --- a/doc/ext-pake/proposed/spake2plus_proposal_draft.md +++ b/doc/ext-pake/proposed/spake2plus_proposal_draft.md @@ -23,10 +23,11 @@ Expected PAKE API Flow : ### Ciphersuite -The current PAKE ciphersuite does not have encoding for MAC. The SPAKE2+ draft recommends HMAC and CMAC for the MAC operation, therefore we should add MAC field in the ciphersuite. -### Out of band set up +The current PAKE ciphersuite does not have encoding for MAC. The SPAKE2+ draft recommends HMAC and CMAC for the MAC operation, therefore MAC field should be added to the ciphersuite. -SPAKE2+ has an offline initialization step where both parties may share parties identities and additional data (the context). This step is considered out of scope but these shared information may be required for SPAKE2+ protocol execution. +### Key types + +Define a new asymmetric key type for SPAKE2+ with `w0 || w1` as private key and `w0 || L` as public key. **Shared Information** : ProverID, VerifierID and Context. @@ -36,32 +37,28 @@ SPAKE2+ has an offline initialization step where both parties may share parties * `psa_pake_set_user()` to input ProverID * `psa_pake_set_peer()` to input VerifierID * `psa_pake_set_role()` to set role as client/server - * `psa_pake_input()` with *(new)* `PSA_PAKE_STEP_ADDITIONAL_DATA` step to input context (additional data). - -### Password, PBKDF Output and Verification value (W0, W1, L) - -SPAKE2+ requires PBKDF Output and Verification value (W0, W1, L) generated from password as below : +* Additional proposed API + * `psa_pake_set_context()` to input context (additional data) - `w0s || w1s = PBKDF(len(pw) || pw || len(A) || A || len(B) || B)` - `W0 = w0s mod p` - `W1 = w1s mod p` - `L = w1*P` +### Registration -Computing these values is considered Out of Scope for PAKE API as this a registration phase which could happen out of actual protocol flow. +Propose a new API `psa_pake_registration()` which will take as input: +* PAKE operation with user and peer IDs +* PBKDF operation which is initialized with the key attributes, PBKDF parameters and password received OOB +* key attributes for the output -Since W0 & W1 and L serve as registartion records and verification value, these values can be treated as secrets. +The function will compute `w0 || w1` if role is set as prover or `w0 || L` if role is set as verifier and store the result as a key. -**Input methods** : Proposing two different approaches, protocol flow diagram has approach 2 mentioned below - -1. Given secret nature of these values, we can use current `psa_pake_set_password_key()` to input these secrets. - 1. `W0||W1` as secret key on Prover side. - 2. `W0||L` as secret key on Verifier side. -2. Rename `psa_pake_set_password_key()` as `psa_pake_input_key()` to input mutiple secret keys and define steps for different keys - 1. For W0 and W1 on Prover side - 2. For W0 and L on Verifier side +``` +psa_status_t psa_pake_registration(psa_pake_operation_t *pake, psa_key_derivation_operation_t *pbkdf, psa_key_attributes_t *attributes); +``` ### Key confirmation Key confirmation is part of the SPAKE2+ protocol. Current PSA Cryptography API 1.1 PAKE Extension only supports implicit key confirmation. -* New API `psa_pake_get_explicit_key()` is required to provide keys with explicit key confirmation. \ No newline at end of file +* New API `psa_pake_get_explicit_key()` which will take as input the current PAKE operation and the attributes for the explicit key and return the key id of the explicit key. + ``` + psa_pake_get_explicit_key(psa_pake_operation_t *pake, psa_key_attributes_t *attributes, psa_key_id_t *explicit_key); + ``` + From 785d4e8e55a2dd8170c5ac866b1cb53b6b49c8d2 Mon Sep 17 00:00:00 2001 From: Kusumit Ghoderao Date: Fri, 1 Sep 2023 12:04:39 +0530 Subject: [PATCH 3/4] Add example Matter implementation Signed-off-by: Kusumit Ghoderao --- .../proposed/spake2plus_proposal_draft.md | 99 +++++++++++++++++++ 1 file changed, 99 insertions(+) diff --git a/doc/ext-pake/proposed/spake2plus_proposal_draft.md b/doc/ext-pake/proposed/spake2plus_proposal_draft.md index 83e9d28c..1511a663 100644 --- a/doc/ext-pake/proposed/spake2plus_proposal_draft.md +++ b/doc/ext-pake/proposed/spake2plus_proposal_draft.md @@ -62,3 +62,102 @@ Key confirmation is part of the SPAKE2+ protocol. Current PSA Cryptography API 1 psa_pake_get_explicit_key(psa_pake_operation_t *pake, psa_key_attributes_t *attributes, psa_key_id_t *explicit_key); ``` +### PSA PAKE API Flow for SPAKE2+ with Matter as example + +``` +// Prover +psa_pake_operation_t spakeP = psa_pake_operation_init(); +psa_pake_cipher_suite_t pake_cs_P = psa_pake_cipher_suite_init(); +psa_pake_cs_set_algorithm(&pake_cs_P, PSA_PAKE_SPAKE2_PLUS); +psa_pake_cs_set_primitive(&pake_cs_P, PSA_PAKE_PRIMITIVE(PSA_PAKE_PRIMITIVE_TYPE_ECC, PSA_ECC_FAMILY_SECP_R1, 256)); +psa_pake_cs_set_hash(&pake_cs_P, PSA_ALG_SHA_256); +psa_pake_cs_set_mac(&pake_cs_P, PSA_ALG_HMAC(PSA_ALG_SHA_256)); + +psa_pake_setup(&spakeP, &pake_cs_P); + +psa_pake_set_user(&spakeP, const uint8_t *user_id, size_t user_id_len); +psa_pake_set_peer(&spakeP, const uint8_t *peer_id, size_t peer_id_len); +psa_pake_set_role(&spakeP, PSA_PAKE_ROLE_CLIENT); +psa_pake_set_context(&spakeP, const uint8_t *context, size_t context_len); + +psa_key_derivation_operation_t pbkdf = psa_key_derivation_operation_init(); +psa_key_derivation_setup(&pbkdf, PSA_ALG_PBKDF2_HMAC(PSA_ALG_SHA_256)); +psa_key_derivation_input_bytes(&pbkdf, PSA_KEY_DERIVATION_INPUT_SALT, *salt, salt_len); +psa_key_derivation_input_integer(&pbkdf, PSA_KEY_DERIVATION_INPUT_COST, input_cost); +psa_key_derivation_input_bytes(&pbkdf, PSA_KEY_DERIVATION_INPUT_PASSWORD, *setupPin, setupPin_len); + +psa_key_attributes_t w0_w1_att = PSA_KEY_ATTRIBUTES_INIT; +psa_set_key_type(&w0_w1_att, PSA_KEY_TYPE_ECC_KEY_PAIR(PSA_ECC_FAMILY_SECP_R1)); +psa_set_key_bits(&w0_w1_att, 1024); +psa_set_key_usage_flags(&w0_w1_att, PSA_KEY_USAGE_DERIVE); \\ Not sure about this +psa_set_key_algorithm(&w0_w1_att, PSA_ALG_HMAC(PSA_ALG_SHA_256)); \\ Not sure about this + +psa_pake_registration(&spakeP, &pbkdf, &w0_w1_att); + +psa_pake_output(&spakeP, PSA_PAKE_STEP_PUBLIC_SHARE_R1, *pA_shareP, sizeof(pA_shareP), *output_length); \\ size is mostly 65 bytes + +// Verifier + +psa_key_attributes_t w0_L_att = PSA_KEY_ATTRIBUTES_INIT; +psa_set_key_type(&w0_L_att, PSA_KEY_TYPE_ECC_KEY_PAIR(PSA_ECC_FAMILY_SECP_R1)); +psa_set_key_bits(&w0_L_att, 1024); +psa_set_key_usage_flags(&w0_L_att, PSA_KEY_USAGE_DERIVE); \\ Not sure about this +psa_set_key_algorithm(&w0_L_att, PSA_ALG_HMAC(PSA_ALG_SHA_256)); \\ Not sure about this + +psa_import_key(&w0_L_att, w0_L_data, 65, w0_L); + +psa_pake_operation_t spakeV = psa_pake_operation_init(); +psa_pake_cipher_suite_t pake_cs_V = psa_pake_cipher_suite_init(); +psa_pake_cs_set_algorithm(&pake_cs_V, PSA_PAKE_SPAKE2_PLUS); +psa_pake_cs_set_primitive(&pake_cs_V, PSA_PAKE_PRIMITIVE(PSA_PAKE_PRIMITIVE_TYPE_ECC, PSA_ECC_FAMILY_SECP_R1, 256)); +psa_pake_cs_set_hash(&pake_cs_V, PSA_ALG_SHA_256); +psa_pake_cs_set_mac(&pake_cs_V, PSA_ALG_HMAC(PSA_ALG_SHA_256)); + +psa_pake_setup(&spakeV, &pake_cs_V); + +psa_pake_set_user(&spakeV, const uint8_t *user_id, size_t user_id_len); +psa_pake_set_peer(&spakeV, const uint8_t *peer_id, size_t peer_id_len); +psa_pake_set_role(&spakeV, PSA_PAKE_ROLE_SERVER); +psa_pake_set_context(&spakeV, const uint8_t *context, size_t context_len); + +psa_pake_input(&spakeV, PSA_PAKE_STEP_PUBLIC_SHARE_R1, pA_shareP, input_length); + +psa_pake_output(&spakeV, PSA_PAKE_STEP_PUBLIC_SHARE_R1, pB_shareV, sizeof(pB_shareV), *output_length); + +psa_pake_output(&spakeV, PSA_PAKE_STEP_KEY_CONFIRM_R2, cB_confirmV, sizeof(cB_confirmV), *output_length); + +// Prover + +psa_pake_input(&spakeP, PSA_PAKE_STEP_PUBLIC_SHARE_R1, pB_shareV, input_length); + +psa_pake_input(&spakeP, PSA_PAKE_STEP_KEY_CONFIRM_R2, cB_confirmV, input_length); + +psa_pake_output(&spakeP, PSA_PAKE_STEP_KEY_CONFIRM_R2, cA_confirmP, sizeof(cA_confirmP), *output_length); + +psa_key_id_t Ke; +Ke_att = PSA_KEY_ATTRIBUTES_INIT; +psa_set_key_type(&Ke_att, PSA_KEY_TYPE_DERIVE); +psa_set_key_bits(&Ke_att, PSA_HASH_LENGTH(PSA_ALG_SHA256)*8/2); +psa_set_key_usage_flags(&Ke_att, PSA_KEY_USAGE_DERIVE); +psa_set_key_algorithm(&Ke_att, PSA_ALG_HKDF(PSA_ALG_SHA256)); + +psa_pake_get_explicit_key(&spakeP, &Ke_att, &Ke); + +psa_pake_abort(&spakeP); + +// Verifier + +psa_pake_input(&spakeV, PSA_PAKE_STEP_KEY_CONFIRM_R2, cA_confirmP, input_length); + +psa_key_id_t Ke; +Ke_att = PSA_KEY_ATTRIBUTES_INIT; +psa_set_key_type(&Ke_att, PSA_KEY_TYPE_DERIVE); +psa_set_key_bits(&Ke_att, PSA_HASH_LENGTH(PSA_ALG_SHA256)*8/2); +psa_set_key_usage_flags(&Ke_att, PSA_KEY_USAGE_DERIVE); +psa_set_key_algorithm(&Ke_att, PSA_ALG_HKDF(PSA_ALG_SHA256)); + +psa_pake_get_explicit_key(&spakeV, &Ke_att, &Ke); + +psa_pake_abort(&spakeV); + +``` \ No newline at end of file From f2a667e3350011edd3ea2c73e59fdcaebde0e6fb Mon Sep 17 00:00:00 2001 From: Kusumit Ghoderao Date: Mon, 25 Sep 2023 16:10:44 +0530 Subject: [PATCH 4/4] Remove pake_registration and change get_explicit_key to get_shared_key Signed-off-by: Kusumit Ghoderao --- doc/ext-pake/proposed/SPAKE2PLUS.svg | 2 +- .../proposed/spake2plus_proposal_draft.md | 61 ++++++++++--------- 2 files changed, 34 insertions(+), 29 deletions(-) diff --git a/doc/ext-pake/proposed/SPAKE2PLUS.svg b/doc/ext-pake/proposed/SPAKE2PLUS.svg index a89a20e0..6f89ee3e 100644 --- a/doc/ext-pake/proposed/SPAKE2PLUS.svg +++ b/doc/ext-pake/proposed/SPAKE2PLUS.svg @@ -1,4 +1,4 @@ -
Prover(A)
Prover(A)
Verifier(B)
Verifier(B)
Shared Information : cipher suite, ProverID, VerifierID, Context
Prover : W0, W1
Verifier : W0, L
Shared Information : cipher suite, ProverID, VerifierID, Context...
Registration
Registration

Inputs                        : secret S
Intermediate Output  : w0s || w1s
Outputs                     : W0, W1 (Prover)
                                    W0, L    (Verifier)

Inputs                        : secret S...
psa_pake_setup()
psa_pake_set_user()
psa_pake_set_peer()
psa_pake_set_role(PSA_PAKE_ROLE_CLIENT)
psa_pake_set_context()
psa_pake_registration()
psa_pake_setup()...
Compute X 
Compute X 
psa_pake_setup()
psa_pake_set_user()
psa_pake_set_peer()
psa_pake_set_role(PSA_PAKE_ROLE_SERVER)
psa_pake_set_context()
psa_pake_setup()...
psa_pake_output() for X
psa_pake_output() for X
(X = pA)
(X = pA)
Compute Z, V, TT
Kae, KcA, KcB
Compute Z, V, TT...
Compute Y, Z, V, TT
Kae, KcA, KcB
Compute Y, Z, V, TT...
psa_pake_output() for cA
psa_pake_output() for cA
psa_pake_output() for Y, cB
psa_pake_output() for Y, cB
(cA)
(cA)
(Y = pB, cB)
(Y = pB, cB)
psa_pake_input() for Y, cB
psa_pake_input() for Y, cB
psa_pake_input() for cA
psa_pake_input() for cA
Verify cB
Verify cB
Verify cA
Verify cA
psa_pake_get_explicit_key() to extract Ke
psa_pake_get_explicit_key() to extract Ke
psa_pake_get_explicit_key() to extract Ke
psa_pake_get_explicit_key() to extract Ke
psa_pake_input() for X
psa_pake_input() for XText is not SVG - cannot display \ No newline at end of file +
Prover(A)
Prover(A)
Verifier(B)
Verifier(B)
Shared Information : cipher suite, ProverID, VerifierID, Context
Prover : W0, W1
Verifier : W0, L
Shared Information : cipher suite, ProverID, VerifierID, Context...
Registration
Registration

Inputs                        : secret S
Intermediate Output  : w0s || w1s
Outputs                     : W0, W1 (Prover)
                                    W0, L    (Verifier)

Inputs                        : secret S...
psa_pake_setup()
psa_pake_set_user()
psa_pake_set_peer()
psa_pake_set_role(PSA_PAKE_ROLE_CLIENT)
psa_pake_set_context()
psa_pake_set_password_key(w0||w1)
psa_pake_setup()...
Compute X 
Compute X 
psa_pake_setup()
psa_pake_set_user()
psa_pake_set_peer()
psa_pake_set_role(PSA_PAKE_ROLE_SERVER)
psa_pake_set_context()
psa_pake_set_passowrd_key(w0||L)
psa_pake_setup()...
psa_pake_output() for X
psa_pake_output() for X
(X = pA)
(X = pA)
Compute Z, V, TT
Kae, KcA, KcB
Compute Z, V, TT...
Compute Y, Z, V, TT
Kae, KcA, KcB
Compute Y, Z, V, TT...
psa_pake_output() for cA
psa_pake_output() for cA
psa_pake_output() for Y, cB
psa_pake_output() for Y, cB
(cA)
(cA)
(Y = pB, cB)
(Y = pB, cB)
psa_pake_input() for Y, cB
psa_pake_input() for Y, cB
psa_pake_input() for cA
psa_pake_input() for cA
Verify cB
Verify cB
Verify cA
Verify cA
psa_pake_get_shared_key() to extract Ke
psa_pake_get_shared_key() to extract Ke
psa_pake_get_shared_key() to extract Ke
psa_pake_get_shared_key() to extract Ke
psa_pake_input() for X
psa_pake_input() for XText is not SVG - cannot display \ No newline at end of file diff --git a/doc/ext-pake/proposed/spake2plus_proposal_draft.md b/doc/ext-pake/proposed/spake2plus_proposal_draft.md index 1511a663..bf2cd6ba 100644 --- a/doc/ext-pake/proposed/spake2plus_proposal_draft.md +++ b/doc/ext-pake/proposed/spake2plus_proposal_draft.md @@ -24,10 +24,14 @@ Expected PAKE API Flow : ### Ciphersuite The current PAKE ciphersuite does not have encoding for MAC. The SPAKE2+ draft recommends HMAC and CMAC for the MAC operation, therefore MAC field should be added to the ciphersuite. +A flag `PSA_PAKE_PERMIT_UNCONFIRMED_SECRET` needs to be defined in the ciphersuite which denotes if extraction of unconfirmed secret is permitted by the algorithm. This flag can also be implicit based on the presence of the MAC algorithm. ### Key types -Define a new asymmetric key type for SPAKE2+ with `w0 || w1` as private key and `w0 || L` as public key. +Define a new asymmetric key type for SPAKE2+. + +`#define PSA_KEY_TYPE_SPAKE2P_KEY_PAIR(psa_pake_primitive_t primitive)` : `w0 || w1` as private key. +`#define PSA_KEY_TYPE_SPAKE2P_PUBLIC_KEY(psa_pake_primitive_t primitive)` : `w0 || L` as public key. **Shared Information** : ProverID, VerifierID and Context. @@ -37,34 +41,39 @@ Define a new asymmetric key type for SPAKE2+ with `w0 || w1` as private key and * `psa_pake_set_user()` to input ProverID * `psa_pake_set_peer()` to input VerifierID * `psa_pake_set_role()` to set role as client/server + * `psa_pake_set_password_key()` to input `w0 || w1` for prover and `w0 || L` for verifier * Additional proposed API * `psa_pake_set_context()` to input context (additional data) -### Registration - -Propose a new API `psa_pake_registration()` which will take as input: -* PAKE operation with user and peer IDs -* PBKDF operation which is initialized with the key attributes, PBKDF parameters and password received OOB -* key attributes for the output - -The function will compute `w0 || w1` if role is set as prover or `w0 || L` if role is set as verifier and store the result as a key. - -``` -psa_status_t psa_pake_registration(psa_pake_operation_t *pake, psa_key_derivation_operation_t *pbkdf, psa_key_attributes_t *attributes); -``` - ### Key confirmation Key confirmation is part of the SPAKE2+ protocol. Current PSA Cryptography API 1.1 PAKE Extension only supports implicit key confirmation. -* New API `psa_pake_get_explicit_key()` which will take as input the current PAKE operation and the attributes for the explicit key and return the key id of the explicit key. +* New API `psa_pake_get_shared_key()` which will replace `psa_pake_get_implicit_key()` and output the shared secret(confirmed/unconfirmed) as a key. The key usage policy of this key will be `PSA_KEY_USAGE_DERIVE`. +* The algorithm will differentiate whether extraction of unconfirmed secret is permitted based on the flag `PSA_PAKE_PERMIT_UNCONFIRMED_SECRET` defined in the ciphersuite. ``` - psa_pake_get_explicit_key(psa_pake_operation_t *pake, psa_key_attributes_t *attributes, psa_key_id_t *explicit_key); + psa_pake_get_shared_key(psa_pake_operation_t *pake, psa_key_attributes_t *attributes, psa_key_id_t *shared_key); ``` ### PSA PAKE API Flow for SPAKE2+ with Matter as example ``` +//Verifier + +psa_key_derivation_operation_t pbkdf = psa_key_derivation_operation_init(); +psa_key_derivation_setup(&pbkdf, PSA_ALG_PBKDF2_HMAC(PSA_ALG_SHA_256)); +psa_key_derivation_input_bytes(&pbkdf, PSA_KEY_DERIVATION_INPUT_SALT, *salt, salt_len); +psa_key_derivation_input_integer(&pbkdf, PSA_KEY_DERIVATION_INPUT_COST, input_cost); +psa_key_derivation_input_bytes(&pbkdf, PSA_KEY_DERIVATION_INPUT_PASSWORD, *setupPin, setupPin_len); + +psa_key_attributes_t w0_L_att = PSA_KEY_ATTRIBUTES_INIT; +psa_set_key_type(&w0_L_att, PSA_KEY_TYPE_SPAKE2P_PUBLIC_KEY); +psa_set_key_bits(&w0_L_att, 1024); +psa_set_key_usage_flags(&w0_L_att, PSA_KEY_USAGE_DERIVE); \\ Not sure about this +psa_set_key_algorithm(&w0_L_att, PSA_ALG_HMAC(PSA_ALG_SHA_256)); \\ Not sure about this + +psa_key_derivation_output_key(&w0_L_att, &pbkdf, w0_L); + // Prover psa_pake_operation_t spakeP = psa_pake_operation_init(); psa_pake_cipher_suite_t pake_cs_P = psa_pake_cipher_suite_init(); @@ -87,25 +96,19 @@ psa_key_derivation_input_integer(&pbkdf, PSA_KEY_DERIVATION_INPUT_COST, input_co psa_key_derivation_input_bytes(&pbkdf, PSA_KEY_DERIVATION_INPUT_PASSWORD, *setupPin, setupPin_len); psa_key_attributes_t w0_w1_att = PSA_KEY_ATTRIBUTES_INIT; -psa_set_key_type(&w0_w1_att, PSA_KEY_TYPE_ECC_KEY_PAIR(PSA_ECC_FAMILY_SECP_R1)); +psa_set_key_type(&w0_w1_att, PSA_KEY_TYPE_SPAKE2P_KEY_PAIR); psa_set_key_bits(&w0_w1_att, 1024); psa_set_key_usage_flags(&w0_w1_att, PSA_KEY_USAGE_DERIVE); \\ Not sure about this psa_set_key_algorithm(&w0_w1_att, PSA_ALG_HMAC(PSA_ALG_SHA_256)); \\ Not sure about this -psa_pake_registration(&spakeP, &pbkdf, &w0_w1_att); +psa_key_derivation_output_key(&w0_w1_att, &pbkdf, w0_w1); + +psa_pake_set_passowrd_key(&spakeP, w0_w1); psa_pake_output(&spakeP, PSA_PAKE_STEP_PUBLIC_SHARE_R1, *pA_shareP, sizeof(pA_shareP), *output_length); \\ size is mostly 65 bytes // Verifier -psa_key_attributes_t w0_L_att = PSA_KEY_ATTRIBUTES_INIT; -psa_set_key_type(&w0_L_att, PSA_KEY_TYPE_ECC_KEY_PAIR(PSA_ECC_FAMILY_SECP_R1)); -psa_set_key_bits(&w0_L_att, 1024); -psa_set_key_usage_flags(&w0_L_att, PSA_KEY_USAGE_DERIVE); \\ Not sure about this -psa_set_key_algorithm(&w0_L_att, PSA_ALG_HMAC(PSA_ALG_SHA_256)); \\ Not sure about this - -psa_import_key(&w0_L_att, w0_L_data, 65, w0_L); - psa_pake_operation_t spakeV = psa_pake_operation_init(); psa_pake_cipher_suite_t pake_cs_V = psa_pake_cipher_suite_init(); psa_pake_cs_set_algorithm(&pake_cs_V, PSA_PAKE_SPAKE2_PLUS); @@ -120,6 +123,8 @@ psa_pake_set_peer(&spakeV, const uint8_t *peer_id, size_t peer_id_len); psa_pake_set_role(&spakeV, PSA_PAKE_ROLE_SERVER); psa_pake_set_context(&spakeV, const uint8_t *context, size_t context_len); +psa_pake_set_password_key(&spakeV, w0_L); + psa_pake_input(&spakeV, PSA_PAKE_STEP_PUBLIC_SHARE_R1, pA_shareP, input_length); psa_pake_output(&spakeV, PSA_PAKE_STEP_PUBLIC_SHARE_R1, pB_shareV, sizeof(pB_shareV), *output_length); @@ -141,7 +146,7 @@ psa_set_key_bits(&Ke_att, PSA_HASH_LENGTH(PSA_ALG_SHA256)*8/2); psa_set_key_usage_flags(&Ke_att, PSA_KEY_USAGE_DERIVE); psa_set_key_algorithm(&Ke_att, PSA_ALG_HKDF(PSA_ALG_SHA256)); -psa_pake_get_explicit_key(&spakeP, &Ke_att, &Ke); +psa_pake_get_shared_key(&spakeP, &Ke_att, &Ke); psa_pake_abort(&spakeP); @@ -156,7 +161,7 @@ psa_set_key_bits(&Ke_att, PSA_HASH_LENGTH(PSA_ALG_SHA256)*8/2); psa_set_key_usage_flags(&Ke_att, PSA_KEY_USAGE_DERIVE); psa_set_key_algorithm(&Ke_att, PSA_ALG_HKDF(PSA_ALG_SHA256)); -psa_pake_get_explicit_key(&spakeV, &Ke_att, &Ke); +psa_pake_get_shared_key(&spakeV, &Ke_att, &Ke); psa_pake_abort(&spakeV);