doc: crypto: updates to crypto samples, part 3

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
 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
 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
 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
 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
 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
 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
 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!
+   [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

samples/crypto/ecjpake/src/main.c

@@ -170,6 +170,8 @@ int main(void)
 {
 	psa_status_t status = psa_crypto_init();
 
+	LOG_INF("Starting EC J-PAKE example...");
+
 	if (status != PSA_SUCCESS) {
 		LOG_INF("psa_crypto_init failed. (Error: %d)", status);
 	}
@@ -187,11 +189,13 @@ int main(void)
 
 	psa_key_id_t key;
 
+	LOG_INF("Importing password key...");
 	status = psa_import_key(&key_attributes, "password", 8, &key);
 	if (status != PSA_SUCCESS) {
 		LOG_INF("psa_import_key failed. (Error: %d)", status);
 		goto error;
 	}
+	LOG_INF("Password key imported successfully!");
 
 	/* Initialize PAKE operation object for the client.*/
 	psa_pake_operation_t client = PSA_PAKE_OPERATION_INIT;
@@ -210,13 +214,16 @@ int main(void)
 	}
 
 	/* Perform the data exchange rounds */
+	LOG_INF("Performing EC J-PAKE key exchange rounds...");
 	status = do_rounds(&server, &client);
 	if (status != PSA_SUCCESS) {
 		LOG_INF("EC J-PAKE rounds failed. (Error: %d)", status);
 		goto error;
 	}
+	LOG_INF("EC J-PAKE key exchange completed successfully!");
 
 	/* Retrieve keys from J-PAKE results. */
+	LOG_INF("Deriving shared secrets...");
 	uint8_t server_secret[32];
 	uint8_t client_secret[32];
 
@@ -229,6 +236,7 @@ int main(void)
 	if (status != PSA_SUCCESS) {
 		goto error;
 	}
+	LOG_INF("Shared secrets derived successfully!");
 
 	PRINT_HEX("server_secret", server_secret, sizeof(server_secret));
 	PRINT_HEX("client_secret", client_secret, sizeof(client_secret));
@@ -246,6 +254,7 @@ int main(void)
 		goto error;
 	}
 
+	LOG_INF("Shared secrets match!");
 	LOG_INF(APP_SUCCESS_MESSAGE);
 	return APP_SUCCESS;
 

samples/crypto/eddsa/README.rst

@@ -7,7 +7,7 @@ Crypto: EdDSA
    :local:
    :depth: 2
 
-The EdDSA sample shows how to sign and verify messages using the Edwards25519 curve.
+The EdDSA sample demonstrates how to use the :ref:`PSA Crypto API <ug_psa_certified_api_overview_crypto>` to sign and verify messages using the EdDSA algorithm with a 255-bit ECC key pair on the Edwards25519 curve.
 
 Requirements
 ************
@@ -21,23 +21,36 @@ 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:
+
+* :kconfig:option:`CONFIG_PSA_WANT_KEY_TYPE_ECC_KEY_PAIR_GENERATE`, :kconfig:option:`CONFIG_PSA_WANT_KEY_TYPE_ECC_KEY_PAIR_IMPORT`, :kconfig:option:`CONFIG_PSA_WANT_KEY_TYPE_ECC_KEY_PAIR_EXPORT` - Used to enable support for ECC key pair types from among the supported cryptographic operations for :ref:`ug_crypto_supported_features_ecc_key_pair`.
+* :kconfig:option:`CONFIG_PSA_WANT_ALG_PURE_EDDSA` - Used to enable support for the EdDSA signature algorithm from among the supported cryptographic operations for :ref:`ug_crypto_supported_features_signature_algorithms`.
+* :kconfig:option:`CONFIG_PSA_WANT_ECC_TWISTED_EDWARDS_255` - Used to enable support for the Edwards25519 curve from among the supported cryptographic operations for :ref:`ug_crypto_supported_features_ecc_curve_types`.
+* :kconfig:option:`CONFIG_PSA_WANT_ALG_SHA_512` - Used to enable support for the SHA-512 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 Platform Security Architecture (PSA) API is initialized.
-   #. A random Elliptic Curve Cryptography (ECC) key pair is generated in the PSA crypto keystore for signing purposes.
-   #. The public key of the ECC key pair is exported to the application.
-   #. The exported public key is imported into the PSA crypto key storage to be used for verification.
+   a. The PSA Crypto API is initialized using :c:func:`psa_crypto_init`.
+   #. A random 255-bit ECC key pair is generated using :c:func:`psa_generate_key` and stored in the PSA crypto keystore.
+      The key pair is configured with usage flags for signing.
+   #. The public key is exported using :c:func:`psa_export_public_key`.
+   #. The exported public key is imported using :c:func:`psa_import_key` for verification purposes.
+      The public key is configured with usage flags for verification.
 
 #. EdDSA signing and verification:
 
-   a. Signing is performed using the private key of the ECC key pair.
-   #. The signature is verified using the exported public key.
+   a. The message is signed using :c:func:`psa_sign_message` with the ``PSA_ALG_PURE_EDDSA`` algorithm.
+   #. The signature is verified using :c:func:`psa_verify_message` with the imported public key.
 
 #. Cleanup:
 
-   a. The key pair and public key are removed from the PSA crypto keystore.
+   a. The ECC key pair and public key are removed from the PSA crypto keystore using :c:func:`psa_destroy_key`.
 
 Building and running
 ********************
@@ -49,8 +62,30 @@ Building and running
 Testing
 =======
 
-After programming the sample to your development kit, complete the following steps to test it:
-
-1. |connect_terminal|
-#. Compile and program the application.
-#. Observe the logs from the application using a terminal emulator.
+.. include:: /samples/crypto/aes_cbc/README.rst
+   :start-after: crypto_sample_testing_start
+   :end-before: crypto_sample_testing_end
+
+.. code-block:: text
+
+   *** Booting nRF Connect SDK v3.1.0-6c6e5b32496e ***
+   *** Using Zephyr OS v4.1.99-1612683d4010 ***
+   [00:00:00.251,159] <inf> eddsa: Starting EdDSA example...
+   [00:00:00.251,190] <inf> eddsa: Generating random EdDSA key pair...
+   [00:00:00.251,342] <inf> eddsa: EdDSA key pair generated successfully!
+   [00:00:00.251,373] <inf> eddsa: Signing a message using the EdDSA algorithm...
+   [00:00:00.251,708] <inf> eddsa: Message signed successfully!
+   [00:00:00.251,739] <inf> eddsa: ---- Plaintext (len: 100): ----
+   [00:00:00.251,770] <inf> eddsa: Content:
+                                    Example string to demonstrate basic usage of EdDSA.
+   [00:00:00.251,800] <inf> eddsa: ---- Plaintext end  ----
+   [00:00:00.251,831] <inf> eddsa: ---- Signature (len: 64): ----
+   [00:00:00.251,861] <inf> eddsa: Content:
+                                    cc 7d c0 ed 63 5b df 28  08 2b 03 33 a4 3c dc 1d |.}..c[.( .+.3.<..
+                                    76 9d a9 cb 1c 49 4f 6d  ef b8 a2 aa 11 2c fc bd |v....IOm .....,..
+                                    39 56 54 b5 96 6e 13 e2  7d 22 26 1e 3c 7c 3e eb |9VT..n.. }"&.<|>.
+                                    15 60 31 d3 58 02 b6 85  98 63 2c e6 ad dc aa 19 |.`1.X... .c,.....
+   [00:00:00.251,892] <inf> eddsa: ---- Signature end  ----
+   [00:00:00.251,922] <inf> eddsa: Verifying the EdDSA signature...
+   [00:00:00.252,045] <inf> eddsa: Signature verification was successful!
+   [00:00:00.252,075] <inf> eddsa: Example finished successfully!

samples/crypto/eddsa/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
 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_TWISTED_EDWARDS_255=y
 CONFIG_PSA_WANT_ALG_SHA_512=y
 CONFIG_PSA_WANT_ALG_PURE_EDDSA=y
-
-# For key generation
 CONFIG_PSA_WANT_GENERATE_RANDOM=y

samples/crypto/eddsa/sample.yaml

@@ -1,7 +1,7 @@
 sample:
   description: |
-    This app provides an example of signing/verifying using EdDSA signatures
-  name: EdDSA example
+    This sample demonstrates EdDSA signing and verification using the EdDSA signature algorithm.
+  name: EdDSA sample
 tests:
   sample.eddsa.cc3xx:
     sysbuild: true