diff --git a/doc/ext-pake/api/pake.rst b/doc/ext-pake/api/pake.rst index 039a11e7..fbab33dc 100644 --- a/doc/ext-pake/api/pake.rst +++ b/doc/ext-pake/api/pake.rst @@ -1,4 +1,4 @@ -.. SPDX-FileCopyrightText: Copyright 2022-2023 Arm Limited and/or its affiliates +.. SPDX-FileCopyrightText: Copyright 2022-2024 Arm Limited and/or its affiliates .. SPDX-License-Identifier: CC-BY-SA-4.0 AND LicenseRef-Patent-license Password-authenticated key exchange (PAKE) @@ -1263,8 +1263,7 @@ J-PAKE does not assign roles to the participants, so it is not necessary to call J-PAKE requires both an application and a peer identity. If the peer identity provided to `psa_pake_set_peer()` does not match the data received from the peer, then the call to `psa_pake_input()` for the `PSA_PAKE_STEP_ZK_PROOF` step will fail with :code:`PSA_ERROR_INVALID_SIGNATURE`. -The following steps demonstrate the application code for 'User' in :numref:`fig-jpake`. -The input and output steps must be carried out in exactly the same sequence as shown. +The following steps demonstrate the application code for 'User' in :numref:`fig-jpake`. The code flow for the 'Peer' is the same as for 'User', as J-PAKE is a balanced PAKE. 1. To prepare a J-PAKE operation, initialize and set up a :code:`psa_pake_operation_t` object by calling the following functions: @@ -1287,61 +1286,69 @@ Key exchange After setup, the key exchange flow for J-PAKE is as follows: -2. To get the first round data that needs to be sent to the peer, call: +2. Round one. - .. code-block:: xref + The application can either extract the round one output values first, and then provide the round one inputs that are received from the Peer; or provide the peer inputs first, and then extract the outputs. - // Get g1 - psa_pake_output(&jpake, PSA_PAKE_STEP_KEY_SHARE, ...); - // Get V1, the ZKP public key for x1 - psa_pake_output(&jpake, PSA_PAKE_STEP_ZK_PUBLIC, ...); - // Get r1, the ZKP proof for x1 - psa_pake_output(&jpake, PSA_PAKE_STEP_ZK_PROOF, ...); - // Get g2 - psa_pake_output(&jpake, PSA_PAKE_STEP_KEY_SHARE, ...); - // Get V2, the ZKP public key for x2 - psa_pake_output(&jpake, PSA_PAKE_STEP_ZK_PUBLIC, ...); - // Get r2, the ZKP proof for x2 - psa_pake_output(&jpake, PSA_PAKE_STEP_ZK_PROOF, ...); - -#. To provide the first round data received from the peer to the operation, call: + * To get the first round data that needs to be sent to the peer, make the following calls to `psa_pake_output()`, in the order shown: - .. code-block:: xref + .. code-block:: xref - // Set g3 - psa_pake_input(&jpake, PSA_PAKE_STEP_KEY_SHARE, ...); - // Set V3, the ZKP public key for x3 - psa_pake_input(&jpake, PSA_PAKE_STEP_ZK_PUBLIC, ...); - // Set r3, the ZKP proof for x3 - psa_pake_input(&jpake, PSA_PAKE_STEP_ZK_PROOF, ...); - // Set g4 - psa_pake_input(&jpake, PSA_PAKE_STEP_KEY_SHARE, ...); - // Set V4, the ZKP public key for x4 - psa_pake_input(&jpake, PSA_PAKE_STEP_ZK_PUBLIC, ...); - // Set r4, the ZKP proof for x4 - psa_pake_input(&jpake, PSA_PAKE_STEP_ZK_PROOF, ...); - -#. To get the second round data that needs to be sent to the peer, call: + // Get g1 + psa_pake_output(&jpake, PSA_PAKE_STEP_KEY_SHARE, ...); + // Get V1, the ZKP public key for x1 + psa_pake_output(&jpake, PSA_PAKE_STEP_ZK_PUBLIC, ...); + // Get r1, the ZKP proof for x1 + psa_pake_output(&jpake, PSA_PAKE_STEP_ZK_PROOF, ...); + // Get g2 + psa_pake_output(&jpake, PSA_PAKE_STEP_KEY_SHARE, ...); + // Get V2, the ZKP public key for x2 + psa_pake_output(&jpake, PSA_PAKE_STEP_ZK_PUBLIC, ...); + // Get r2, the ZKP proof for x2 + psa_pake_output(&jpake, PSA_PAKE_STEP_ZK_PROOF, ...); + + * To provide the first round data received from the peer to the operation, make the following calls to `psa_pake_input()`, in the order shown: - .. code-block:: xref + .. code-block:: xref - // Get A - psa_pake_output(&jpake, PSA_PAKE_STEP_KEY_SHARE, ...); - // Get V5, the ZKP public key for x2*s - psa_pake_output(&jpake, PSA_PAKE_STEP_ZK_PUBLIC, ...); - // Get r5, the ZKP proof for x2*s - psa_pake_output(&jpake, PSA_PAKE_STEP_ZK_PROOF, ...); + // Set g3 + psa_pake_input(&jpake, PSA_PAKE_STEP_KEY_SHARE, ...); + // Set V3, the ZKP public key for x3 + psa_pake_input(&jpake, PSA_PAKE_STEP_ZK_PUBLIC, ...); + // Set r3, the ZKP proof for x3 + psa_pake_input(&jpake, PSA_PAKE_STEP_ZK_PROOF, ...); + // Set g4 + psa_pake_input(&jpake, PSA_PAKE_STEP_KEY_SHARE, ...); + // Set V4, the ZKP public key for x4 + psa_pake_input(&jpake, PSA_PAKE_STEP_ZK_PUBLIC, ...); + // Set r4, the ZKP proof for x4 + psa_pake_input(&jpake, PSA_PAKE_STEP_ZK_PROOF, ...); -#. To provide the second round data received from the peer to the operation call: +#. Round two. - .. code-block:: xref + The application can either extract the round two output values first, and then provide the round two inputs that are received from the Peer; or provide the peer inputs first, and then extract the outputs. + + * To get the second round data that needs to be sent to the peer, make the following calls to `psa_pake_output()`, in the order shown: + + .. code-block:: xref - // Set B - psa_pake_input(&jpake, PSA_PAKE_STEP_KEY_SHARE, ...); - // Set V6, the ZKP public key for x4*s - psa_pake_input(&jpake, PSA_PAKE_STEP_ZK_PUBLIC, ...); - // Set r6, the ZKP proof for x4*s - psa_pake_input(&jpake, PSA_PAKE_STEP_ZK_PROOF, ...); + // Get A + psa_pake_output(&jpake, PSA_PAKE_STEP_KEY_SHARE, ...); + // Get V5, the ZKP public key for x2*s + psa_pake_output(&jpake, PSA_PAKE_STEP_ZK_PUBLIC, ...); + // Get r5, the ZKP proof for x2*s + psa_pake_output(&jpake, PSA_PAKE_STEP_ZK_PROOF, ...); + + * To provide the second round data received from the peer to the operation, make the following calls to `psa_pake_input()`, in the order shown: + + .. code-block:: xref + + // Set B + psa_pake_input(&jpake, PSA_PAKE_STEP_KEY_SHARE, ...); + // Set V6, the ZKP public key for x4*s + psa_pake_input(&jpake, PSA_PAKE_STEP_ZK_PUBLIC, ...); + // Set r6, the ZKP proof for x4*s + psa_pake_input(&jpake, PSA_PAKE_STEP_ZK_PROOF, ...); #. To use the shared secret, extract it as a key-derivation key. For example, to extract a derivation key for HKDF-SHA-256: @@ -1650,7 +1657,11 @@ The following steps demonstrate the application code for both Prover and Verifie Key exchange ^^^^^^^^^^^^ -After setup, the key exchange and confirmation flow for SPAKE2+ is as follows: +After setup, the key exchange and confirmation flow for SPAKE2+ is as follows. + +.. note:: + + The sequence of calls for the Prover, and the sequence for the Verifier, must be in exactly this order. **Prover** To get the key share to send to the Verifier, call: @@ -1661,7 +1672,7 @@ After setup, the key exchange and confirmation flow for SPAKE2+ is as follows: psa_pake_output(&spake2p_p, PSA_PAKE_STEP_KEY_SHARE, ...); **Verifier** - To provide and validate the Prover key share, call: + To provide and validate the key share received from the Prover, call: .. code-block:: xref @@ -1679,7 +1690,7 @@ After setup, the key exchange and confirmation flow for SPAKE2+ is as follows: psa_pake_output(&spake2p_v, PSA_PAKE_STEP_CONFIRM, ...); **Prover** - To provide and validate the Verifier key share, and confirm the Verifier key, call: + To provide and validate the key share and verify the confirmation value received from the Verifier, call: .. code-block:: xref @@ -1693,15 +1704,15 @@ After setup, the key exchange and confirmation flow for SPAKE2+ is as follows: .. code-block:: xref - // Get confirmV + // Get confirmP psa_pake_output(&spake2p_p, PSA_PAKE_STEP_CONFIRM, ...); **Verifier** - To confirm the Prover key, call: + To verify the confirmation value received from the Prover, call: .. code-block:: xref - // Set shareP + // Set confirmP psa_pake_input(&spake2p_v, PSA_PAKE_STEP_CONFIRM, ...); **Prover** diff --git a/doc/ext-pake/figure/spake2plus.pdf b/doc/ext-pake/figure/spake2plus.pdf index 3ada1f96..581501be 100644 Binary files a/doc/ext-pake/figure/spake2plus.pdf and b/doc/ext-pake/figure/spake2plus.pdf differ diff --git a/doc/ext-pake/figure/spake2plus.pdf.license b/doc/ext-pake/figure/spake2plus.pdf.license index 9a9052df..22ae5f88 100644 --- a/doc/ext-pake/figure/spake2plus.pdf.license +++ b/doc/ext-pake/figure/spake2plus.pdf.license @@ -1,2 +1,2 @@ -SPDX-FileCopyrightText: Copyright 2023 Arm Limited and/or its affiliates +SPDX-FileCopyrightText: Copyright 2023-2024 Arm Limited and/or its affiliates SPDX-License-Identifier: CC-BY-SA-4.0 AND LicenseRef-Patent-license diff --git a/doc/ext-pake/figure/spake2plus.puml b/doc/ext-pake/figure/spake2plus.puml index b706c8b3..4766300d 100644 --- a/doc/ext-pake/figure/spake2plus.puml +++ b/doc/ext-pake/figure/spake2plus.puml @@ -1,4 +1,4 @@ -' SPDX-FileCopyrightText: Copyright 2023 Arm Limited and/or its affiliates +' SPDX-FileCopyrightText: Copyright 2023-2024 Arm Limited and/or its affiliates ' SPDX-License-Identifier: CC-BY-SA-4.0 AND LicenseRef-Patent-license @startuml @@ -22,11 +22,11 @@ Verifier -> Verifier: ""psa_pake_input()"" for //shareP// note left: Validate //shareP// - Verifier -> Verifier: ""psa_pake_output()"" for //shareV// = //Y// and //confirmV// + Verifier -> Verifier: ""psa_pake_output()"" for //shareV// = //Y// + note left: Generate key share //Y// + Verifier -> Verifier: ""psa_pake_output()"" for //confirmV// note left - Generate key share //Y// - Compute //K_shared//, - //confirmP'// and //confirmV// + Compute //K_shared//, //confirmP'// and //confirmV// end note Verifier ->> Prover: (//shareV//, //confirmV//) @@ -34,24 +34,20 @@ Prover -> Prover: ""psa_pake_input()"" for //shareV// note left: Validate //shareV// - Prover -> Prover: ""psa_pake_output()"" for //confirmP// + Prover -> Prover: ""psa_pake_input()"" for //confirmV// note left Compute //K_shared//, - //confirmP// and //confirmV'// + //confirmP// and //confirmV'// + Verify //confirmV'// = //confirmV// end note + Prover -> Prover: ""psa_pake_output()"" for //confirmP// Prover ->> Verifier: (//confirmP//) - Prover -> Prover: ""psa_pake_input()"" for //confirmV// - note left - Verify that - //confirmV'// = //confirmV// - end note Prover -> Prover: ""psa_pake_get_shared_key()"" to extract //K_shared// Verifier -> Verifier: ""psa_pake_input()"" for //confirmP// note left - Verify that - //confirmP'// = //confirmP// + Verify //confirmP'// = //confirmP// end note Verifier -> Verifier: ""psa_pake_get_shared_key()"" to extract //K_shared// diff --git a/doc/ext-pake/figure/spake2plus.svg b/doc/ext-pake/figure/spake2plus.svg index ac1bfc49..2937fc5a 100644 --- a/doc/ext-pake/figure/spake2plus.svg +++ b/doc/ext-pake/figure/spake2plus.svg @@ -1 +1 @@ -Prover(Client role)Verifier(Server role)Shared information : cipher suite,ProverId,VerifierId, andContextRegistration record (w0,L) derived from passwordProver 'key pair' (w0,w1) derived from passwordpsa_pake_setup()with key (w0,w1)psa_pake_set_role(PSA_PAKE_ROLE_CLIENT)psa_pake_set_user(ProverId)psa_pake_set_peer(VerifierId)psa_pake_set_context(Context)psa_pake_output()forshareP=XGenerate key shareX(shareP)psa_pake_setup()with key (w0,L) or key (w0,w1)psa_pake_set_role(PSA_PAKE_ROLE_SERVER)psa_pake_set_user(VerifierId)psa_pake_set_peer(ProverId)psa_pake_set_context(Context)psa_pake_input()forsharePValidatesharePpsa_pake_output()forshareV=YandconfirmVGenerate key shareYComputeK_shared,confirmP'andconfirmV(shareV,confirmV)psa_pake_input()forshareVValidateshareVpsa_pake_output()forconfirmPComputeK_shared,confirmPandconfirmV'(confirmP)psa_pake_input()forconfirmVVerify thatconfirmV'=confirmVpsa_pake_get_shared_key()to extractK_sharedpsa_pake_input()forconfirmPVerify thatconfirmP'=confirmPpsa_pake_get_shared_key()to extractK_shared \ No newline at end of file +Prover(Client role)Verifier(Server role)Shared information : cipher suite,ProverId,VerifierId, andContextRegistration record (w0,L) derived from passwordProver 'key pair' (w0,w1) derived from passwordpsa_pake_setup()with key (w0,w1)psa_pake_set_role(PSA_PAKE_ROLE_CLIENT)psa_pake_set_user(ProverId)psa_pake_set_peer(VerifierId)psa_pake_set_context(Context)psa_pake_output()forshareP=XGenerate key shareX(shareP)psa_pake_setup()with key (w0,L) or key (w0,w1)psa_pake_set_role(PSA_PAKE_ROLE_SERVER)psa_pake_set_user(VerifierId)psa_pake_set_peer(ProverId)psa_pake_set_context(Context)psa_pake_input()forsharePValidatesharePpsa_pake_output()forshareV=YGenerate key shareYpsa_pake_output()forconfirmVComputeK_shared,confirmP'andconfirmV(shareV,confirmV)psa_pake_input()forshareVValidateshareVpsa_pake_input()forconfirmVComputeK_shared,    confirmPandconfirmV'VerifyconfirmV'=confirmVpsa_pake_output()forconfirmP(confirmP)psa_pake_get_shared_key()to extractK_sharedpsa_pake_input()forconfirmPVerifyconfirmP'=confirmPpsa_pake_get_shared_key()to extractK_shared \ No newline at end of file diff --git a/doc/ext-pake/figure/spake2plus.svg.license b/doc/ext-pake/figure/spake2plus.svg.license index 9a9052df..22ae5f88 100644 --- a/doc/ext-pake/figure/spake2plus.svg.license +++ b/doc/ext-pake/figure/spake2plus.svg.license @@ -1,2 +1,2 @@ -SPDX-FileCopyrightText: Copyright 2023 Arm Limited and/or its affiliates +SPDX-FileCopyrightText: Copyright 2023-2024 Arm Limited and/or its affiliates SPDX-License-Identifier: CC-BY-SA-4.0 AND LicenseRef-Patent-license