doc: crypto: updates to crypto samples, part 3

Updated the documentation of crypto samples.
Added sample output, cross-links to recently updated docs,
more details in the overview sections.
Edited sample.yaml for term and style consistency.
Future PRs will edit remaining crypto samples.
NCSDK-33435. Follow-up to #25032 and #25157.

Signed-off-by: Grzegorz Ferenc <[email protected]>

Author: greg-fer

doc/nrf/security/crypto/crypto_supported_features.rst

@@ -3002,6 +3002,7 @@ Based on this setting, Oberon PSA Crypto selects the most appropriate driver for
                * - Configuration automatically generated based on the enabled key encapsulation algorithms. Acts as :ref:`software fallback <crypto_drivers_software_fallback>` for the other drivers.
                  - :kconfig:option:`CONFIG_PSA_WANT_ALG_ML_KEM`
 
+.. _ug_crypto_supported_features_kdf_algorithms:
 
 KDF algorithms
 ==============
@@ -5787,6 +5788,8 @@ Based on this setting, Oberon PSA Crypto selects the most appropriate driver for
                  - | :kconfig:option:`CONFIG_PSA_WANT_ALG_RSA_OAEP`
                    | :kconfig:option:`CONFIG_PSA_WANT_ALG_RSA_PKCS1V15_CRYPT` (does not support RSA key pair generation)
 
+.. _ug_crypto_supported_features_ecc_curve_types:
+
 ECC curve types
 ===============
 

samples/crypto/aes_cbc/prj.conf

@@ -13,10 +13,11 @@ CONFIG_HEAP_MEM_POOL_SIZE=4096
 CONFIG_CONSOLE=y
 CONFIG_LOG=y
 
-# Enable nordic security backend and PSA APIs
+# Enable nRF Security backend for PSA Crypto API
 CONFIG_NRF_SECURITY=y
 CONFIG_MBEDTLS_PSA_CRYPTO_C=y
 
+# Enable cryptographic features for compilation
 CONFIG_PSA_WANT_GENERATE_RANDOM=y
 CONFIG_PSA_WANT_KEY_TYPE_AES=y
 CONFIG_PSA_WANT_ALG_CBC_NO_PADDING=y

samples/crypto/aes_ccm/prj.conf

@@ -13,10 +13,11 @@ CONFIG_HEAP_MEM_POOL_SIZE=4096
 CONFIG_CONSOLE=y
 CONFIG_LOG=y
 
-# Enable nordic security backend and PSA APIs
+# Enable nRF Security backend for PSA Crypto API
 CONFIG_NRF_SECURITY=y
 CONFIG_MBEDTLS_PSA_CRYPTO_C=y
 
+# Enable cryptographic features for compilation
 CONFIG_PSA_WANT_GENERATE_RANDOM=y
 CONFIG_PSA_WANT_KEY_TYPE_AES=y
 CONFIG_PSA_WANT_ALG_CCM=y

samples/crypto/aes_ctr/prj.conf

@@ -13,10 +13,11 @@ CONFIG_HEAP_MEM_POOL_SIZE=4096
 CONFIG_CONSOLE=y
 CONFIG_LOG=y
 
-# Enable nordic security backend and PSA APIs
+# Enable nRF Security backend for PSA Crypto API
 CONFIG_NRF_SECURITY=y
 CONFIG_MBEDTLS_PSA_CRYPTO_C=y
 
+# Enable cryptographic features for compilation
 CONFIG_PSA_WANT_GENERATE_RANDOM=y
 CONFIG_PSA_WANT_KEY_TYPE_AES=y
 CONFIG_PSA_WANT_ALG_CTR=y

samples/crypto/aes_gcm/prj.conf

@@ -13,10 +13,11 @@ CONFIG_HEAP_MEM_POOL_SIZE=4096
 CONFIG_CONSOLE=y
 CONFIG_LOG=y
 
-# Enable nordic security backend and PSA APIs
+# Enable nRF Security backend for PSA Crypto API
 CONFIG_NRF_SECURITY=y
 CONFIG_MBEDTLS_PSA_CRYPTO_C=y
 
+# Enable cryptographic features for compilation
 CONFIG_PSA_WANT_GENERATE_RANDOM=y
 CONFIG_PSA_WANT_KEY_TYPE_AES=y
 CONFIG_PSA_WANT_ALG_GCM=y

samples/crypto/chachapoly/prj.conf

@@ -13,10 +13,11 @@ CONFIG_HEAP_MEM_POOL_SIZE=4096
 CONFIG_CONSOLE=y
 CONFIG_LOG=y
 
-# Enable nordic security backend and PSA APIs
+# Enable nRF Security backend for PSA Crypto API
 CONFIG_NRF_SECURITY=y
 CONFIG_MBEDTLS_PSA_CRYPTO_C=y
 
+# Enable cryptographic features for compilation
 CONFIG_PSA_WANT_GENERATE_RANDOM=y
 CONFIG_PSA_WANT_KEY_TYPE_CHACHA20=y
 CONFIG_PSA_WANT_ALG_CHACHA20_POLY1305=y

samples/crypto/ecdh/prj.conf

@@ -13,15 +13,14 @@ CONFIG_HEAP_MEM_POOL_SIZE=4096
 CONFIG_CONSOLE=y
 CONFIG_LOG=y
 
-# Enable nordic security backend and PSA APIs
+# Enable nRF Security backend for PSA Crypto API
 CONFIG_NRF_SECURITY=y
 CONFIG_MBEDTLS_PSA_CRYPTO_C=y
 
+# Enable cryptographic features for compilation
 CONFIG_PSA_WANT_ALG_ECDH=y
 CONFIG_PSA_WANT_KEY_TYPE_ECC_KEY_PAIR_GENERATE=y
 CONFIG_PSA_WANT_KEY_TYPE_ECC_KEY_PAIR_IMPORT=y
 CONFIG_PSA_WANT_KEY_TYPE_ECC_KEY_PAIR_EXPORT=y
 CONFIG_PSA_WANT_ECC_SECP_R1_256=y
-
-# For key generation
 CONFIG_PSA_WANT_GENERATE_RANDOM=y

samples/crypto/ecdsa/prj.conf

@@ -13,16 +13,15 @@ CONFIG_HEAP_MEM_POOL_SIZE=8192
 CONFIG_CONSOLE=y
 CONFIG_LOG=y
 
-# Enable nordic security backend and PSA APIs
+# Enable nRF Security backend for PSA Crypto API
 CONFIG_NRF_SECURITY=y
 CONFIG_MBEDTLS_PSA_CRYPTO_C=y
 
+# Enable cryptographic features for compilation
 CONFIG_PSA_WANT_ALG_ECDSA=y
 CONFIG_PSA_WANT_KEY_TYPE_ECC_KEY_PAIR_GENERATE=y
 CONFIG_PSA_WANT_KEY_TYPE_ECC_KEY_PAIR_IMPORT=y
 CONFIG_PSA_WANT_KEY_TYPE_ECC_KEY_PAIR_EXPORT=y
 CONFIG_PSA_WANT_ECC_SECP_R1_256=y
 CONFIG_PSA_WANT_ALG_SHA_256=y
-
-# For key generation
 CONFIG_PSA_WANT_GENERATE_RANDOM=y

samples/crypto/ecjpake/README.rst

@@ -7,9 +7,8 @@ Crypto: EC J-PAKE
    :local:
    :depth: 2
 
-The EC J-PAKE sample demonstrates how to do password-authenticated key exchange using
-the elliptic curve (EC) version of the password-authenticated key exchange by
-juggling (J-PAKE) protocol.
+The EC J-PAKE sample demonstrates how to use the :ref:`PSA Crypto API <ug_psa_certified_api_overview_crypto>` to perform password-authenticated key exchange using the EC J-PAKE algorithm.
+The sample uses the elliptic curve (EC) version of the password-authenticated key exchange by juggling (J-PAKE) protocol with a shared password.
 
 Requirements
 ************
@@ -21,11 +20,35 @@ The sample supports the following development kits:
 Overview
 ********
 
-The sample performs the following operations:
+The sample :ref:`enables PSA Crypto API <psa_crypto_support_enable>` and configures the following Kconfig options for the cryptographic features:
 
-1. Initializes the Platform Security Architecture (PSA) API.
-#. Goes through the steps for J-PAKE on server and client sides.
-#. Verifies that the derived keys are the same.
+* :kconfig:option:`CONFIG_PSA_WANT_KEY_TYPE_ECC_PUBLIC_KEY` - Used to enable support for ECC public key types from among the supported cryptographic operations for :ref:`ug_crypto_supported_features_key_types`.
+* :kconfig:option:`CONFIG_PSA_WANT_ALG_JPAKE` - Used to enable support for the J-PAKE key agreement algorithm from among the supported cryptographic operations for :ref:`ug_crypto_supported_features_pake_algorithms`.
+* :kconfig:option:`CONFIG_PSA_WANT_ALG_SHA_256` - Used to enable support for the SHA-256 hash algorithm from among the supported cryptographic operations for :ref:`ug_crypto_supported_features_hash_algorithms`.
+
+.. include:: /samples/crypto/aes_cbc/README.rst
+   :start-after: crypto_sample_overview_driver_selection_start
+   :end-before: crypto_sample_overview_driver_selection_end
+
+Once built and run, the sample performs the following operations:
+
+1. Initialization:
+
+   a. The PSA Crypto API is initialized using :c:func:`psa_crypto_init`.
+   #. A password key is imported using :c:func:`psa_import_key` with the ``PSA_KEY_TYPE_PASSWORD`` type.
+      The key is configured with usage flags for key derivation.
+
+#. EC J-PAKE key exchange:
+
+   a. PAKE operations are set up for both client and server using :c:func:`psa_pake_setup`.
+   #. Key exchange rounds are performed using :c:func:`psa_pake_output` and :c:func:`psa_pake_input`.
+      This includes key sharing, zero-knowledge public values, and zero-knowledge proofs.
+   #. Shared secrets are derived using :c:func:`psa_pake_get_shared_key` and key derivation functions.
+   #. The derived secrets are compared to verify that both parties obtained the same shared secret.
+
+#. Cleanup:
+
+   a. The password key is removed from the PSA crypto keystore using :c:func:`psa_destroy_key`.
 
 Building and running
 ********************
@@ -37,8 +60,30 @@ Building and running
 Testing
 =======
 
-After programming the sample to your development kit, complete the following steps to test it:
+.. include:: /samples/crypto/aes_cbc/README.rst
+   :start-after: crypto_sample_testing_start
+   :end-before: crypto_sample_testing_end
+
+.. code-block:: text
 
-1. |connect_terminal|
-#. Compile and program the application.
-#. Observe the logs from the application using a terminal emulator.
+   *** Booting nRF Connect SDK v3.1.0-6c6e5b32496e ***
+   *** Using Zephyr OS v4.1.99-1612683d4010 ***
+   [00:00:00.251,159] <inf> ecjpake: Starting EC J-PAKE example...
+   [00:00:00.251,190] <inf> ecjpake: Importing password key...
+   [00:00:00.251,342] <inf> ecjpake: Password key imported successfully!
+   [00:00:00.251,373] <inf> ecjpake: Performing EC J-PAKE key exchange rounds...
+   [00:00:00.251,708] <inf> ecjpake: EC J-PAKE key exchange completed successfully!
+   [00:00:00.251,739] <inf> ecjpake: Deriving shared secrets...
+   [00:00:00.251,770] <inf> ecjpake: Shared secrets derived successfully!
+   [00:00:00.251,800] <inf> ecjpake: ---- server_secret (len: 32): ----
+   [00:00:00.251,831] <inf> ecjpake: Content:
+                                    c3 1e 5b 35 97 25 ee a3  ef ba 66 c3 f9 81 37 2a |..[5.%.. ..f...7*
+                                    76 9d a9 cb 1c 49 4f 6d  ef b8 a2 aa 11 2c fc bd |v....IOm .....,..
+   [00:00:00.251,861] <inf> ecjpake: ---- server_secret end  ----
+   [00:00:00.251,892] <inf> ecjpake: ---- client_secret (len: 32): ----
+   [00:00:00.251,922] <inf> ecjpake: Content:
+                                    c3 1e 5b 35 97 25 ee a3  ef ba 66 c3 f9 81 37 2a |..[5.%.. ..f...7*
+                                    76 9d a9 cb 1c 49 4f 6d  ef b8 a2 aa 11 2c fc bd |v....IOm .....,..
+   [00:00:00.251,953] <inf> ecjpake: ---- client_secret end  ----
+   [00:00:00.251,984] <inf> ecjpake: Shared secrets match successfully!
+   [00:00:00.252,014] <inf> ecjpake: Example finished successfully!

samples/crypto/ecjpake/sample.yaml

@@ -1,6 +1,7 @@
 sample:
-  description: This app provides an example of EC J-PAKE
-  name: EC J-PAKE example
+  description: |
+    This sample demonstrates EC J-PAKE key exchange using the EC J-PAKE algorithm.
+  name: EC J-PAKE sample
 tests:
   sample.ecjpake.oberon:
     sysbuild: true