Skip to content

Commit 637ca7c

Browse files
greg-ferrlubos
greg-fer
authored and
rlubos
committed
doc: crypto: updates to crypto samples, part 2
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. Signed-off-by: Grzegorz Ferenc <[email protected]>
1 parent 52462bd commit 637ca7c

File tree

19 files changed

+279
-105
lines changed

19 files changed

+279
-105
lines changed

‎doc/nrf/security/crypto/crypto_supported_features.rst‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2503,6 +2503,7 @@ Based on this setting, Oberon PSA Crypto selects the most appropriate driver for
25032503
| :kconfig:option:`CONFIG_PSA_WANT_ALG_CCM_STAR_NO_TAG`
25042504
| :kconfig:option:`CONFIG_PSA_WANT_ALG_STREAM_CIPHER`
25052505
2506+
.. _ug_crypto_supported_features_key_agreement_algorithms:
25062507

25072508
Key agreement algorithms
25082509
========================
@@ -4455,6 +4456,8 @@ Based on this setting, Oberon PSA Crypto selects the most appropriate driver for
44554456
| :kconfig:option:`CONFIG_PSA_WANT_ALG_CHACHA20_POLY1305`
44564457
| :kconfig:option:`CONFIG_PSA_WANT_ALG_XCHACHA20_POLY1305`
44574458
4459+
.. _ug_crypto_supported_features_signature_algorithms:
4460+
44584461
Asymmetric signature algorithms
44594462
===============================
44604463

@@ -7240,6 +7243,8 @@ Based on this setting, Oberon PSA Crypto selects the most appropriate driver for
72407243
- | :kconfig:option:`CONFIG_PSA_WANT_ALG_CTR_DRBG`
72417244
| :kconfig:option:`CONFIG_PSA_WANT_ALG_HMAC_DRBG` (software implementation, entropy provided by the hardware RNG peripheral)
72427245
7246+
.. _ug_crypto_supported_features_hash_algorithms:
7247+
72437248
Hash algorithms
72447249
===============
72457250

‎samples/crypto/aes_cbc/README.rst‎

Lines changed: 10 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -27,10 +27,14 @@ The sample :ref:`enables PSA Crypto API <psa_crypto_support_enable>` and configu
2727
* :kconfig:option:`CONFIG_PSA_WANT_ALG_CBC_NO_PADDING` - Used to enable support for the CBC cipher mode without padding from among the supported cryptographic operations for :ref:`ug_crypto_supported_features_cipher_modes`.
2828
* :kconfig:option:`CONFIG_PSA_WANT_GENERATE_RANDOM` - Used to enable random number generation for key and IV generation from among the supported cryptographic operations for :ref:`ug_crypto_supported_features_rng_algorithms`.
2929

30+
.. crypto_sample_overview_driver_selection_start
31+
3032
The sample also configures the cryptographic drivers for each board target using Kconfig options in the overlay files in the :file:`boards` directory.
3133

32-
These Kconfig options are then used by Oberon PSA Crypto to compile the required cryptographic PSA directives and select the cryptographic drivers.
33-
See :ref:`crypto_drivers_driver_selection` for more information about the driver selection process.
34+
These Kconfig options are then used by the build system to compile the required cryptographic PSA directives and make the configured cryptographic drivers available at runtime.
35+
See :ref:`crypto_drivers_driver_selection` for more information about this process.
36+
37+
.. crypto_sample_overview_driver_selection_end
3438
3539
Once built and run, the sample performs the following operations:
3640

@@ -64,10 +68,10 @@ Building and running
6468
Testing
6569
=======
6670

67-
After programming the sample to your development kit, complete the following steps to test it:
68-
6971
.. crypto_sample_testing_start
7072
73+
After programming the sample to your development kit, complete the following steps to test it:
74+
7175
1. |connect_terminal|
7276
#. Build and program the application.
7377
#. Observe the logs from the application using the terminal emulator.
@@ -82,7 +86,7 @@ After programming the sample to your development kit, complete the following ste
8286
[00:00:00.251,159] <inf> aes_cbc: Starting AES-CBC-NO-PADDING example...
8387
[00:00:00.251,190] <inf> aes_cbc: Generating random AES key...
8488
[00:00:00.251,342] <inf> aes_cbc: AES key generated successfully!
85-
[00:00:00.251,373] <inf> aes_cbc: Encrypting using AES CBC MODE...
89+
[00:00:00.251,373] <inf> aes_cbc: Encrypting using the AES CBC mode...
8690
[00:00:00.251,708] <inf> aes_cbc: Encryption successful!
8791
[00:00:00.251,708] <inf> aes_cbc: ---- IV (len: 16): ----
8892
[00:00:00.251,739] <inf> aes_cbc: Content:
@@ -102,7 +106,7 @@ After programming the sample to your development kit, complete the following ste
102106
39 56 54 b5 96 6e 13 e2 7d 22 26 1e 3c 7c 3e eb |9VT..n.. }"&.<|>.
103107
15 60 31 d3 58 02 b6 85 98 63 2c e6 ad dc aa 19 |.`1.X... .c,.....
104108
[00:00:00.251,922] <inf> aes_cbc: ---- Encrypted text end ----
105-
[00:00:00.251,953] <inf> aes_cbc: Decrypting using AES CBC MODE...
109+
[00:00:00.251,953] <inf> aes_cbc: Decrypting using the AES CBC mode...
106110
[00:00:00.252,166] <inf> aes_cbc: ---- Decrypted text (len: 64): ----
107111
[00:00:00.252,197] <inf> aes_cbc: Content:
108112
45 78 61 6d 70 6c 65 20 73 74 72 69 6e 67 20 74 |Example string t

‎samples/crypto/aes_cbc/src/main.c‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -112,7 +112,7 @@ int encrypt_cbc_aes(void)
112112
psa_status_t status;
113113
psa_cipher_operation_t operation = PSA_CIPHER_OPERATION_INIT;
114114

115-
LOG_INF("Encrypting using AES CBC MODE...");
115+
LOG_INF("Encrypting using the AES CBC mode...");
116116

117117
/* Setup the encryption operation */
118118
status = psa_cipher_encrypt_setup(&operation, key_id, PSA_ALG_CBC_NO_PADDING);
@@ -163,7 +163,7 @@ int decrypt_cbc_aes(void)
163163
psa_status_t status;
164164
psa_cipher_operation_t operation = PSA_CIPHER_OPERATION_INIT;
165165

166-
LOG_INF("Decrypting using AES CBC MODE...");
166+
LOG_INF("Decrypting using the AES CBC mode...");
167167

168168
/* Setup the decryption operation */
169169
status = psa_cipher_decrypt_setup(&operation, key_id, PSA_ALG_CBC_NO_PADDING);

‎samples/crypto/aes_ccm/README.rst‎

Lines changed: 5 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -28,10 +28,9 @@ The sample :ref:`enables PSA Crypto API <psa_crypto_support_enable>` and configu
2828
* :kconfig:option:`CONFIG_PSA_WANT_ALG_CCM` - Used to enable support for the CCM AEAD algorithm from among the supported cryptographic operations for :ref:`ug_crypto_supported_features_aead_algorithms`.
2929
* :kconfig:option:`CONFIG_PSA_WANT_GENERATE_RANDOM` - Used to enable random number generation for key generation from among the supported cryptographic operations for :ref:`ug_crypto_supported_features_rng_algorithms`.
3030

31-
The sample also configures the cryptographic drivers for each board target using Kconfig options in the overlay files in the :file:`boards` directory.
32-
33-
These Kconfig options are then used by Oberon PSA Crypto to compile the required cryptographic PSA directives and select the cryptographic drivers.
34-
See :ref:`crypto_drivers_driver_selection` for more information about the driver selection process.
31+
.. include:: /samples/crypto/aes_cbc/README.rst
32+
:start-after: crypto_sample_overview_driver_selection_start
33+
:end-before: crypto_sample_overview_driver_selection_end
3534

3635
Once built and run, the sample performs the following operations:
3736

@@ -63,8 +62,6 @@ Building and running
6362
Testing
6463
=======
6564

66-
After programming the sample to your development kit, complete the following steps to test it:
67-
6865
.. include:: /samples/crypto/aes_cbc/README.rst
6966
:start-after: crypto_sample_testing_start
7067
:end-before: crypto_sample_testing_end
@@ -76,7 +73,7 @@ After programming the sample to your development kit, complete the following ste
7673
[00:00:00.251,159] <inf> aes_ccm: Starting AES CCM example...
7774
[00:00:00.251,190] <inf> aes_ccm: Generating random AES key...
7875
[00:00:00.251,342] <inf> aes_ccm: AES key generated successfully!
79-
[00:00:00.251,373] <inf> aes_ccm: Encrypting using AES CCM MODE...
76+
[00:00:00.251,373] <inf> aes_ccm: Encrypting using the AES CCM mode...
8077
[00:00:00.251,708] <inf> aes_ccm: Encryption successful!
8178
[00:00:00.251,708] <inf> aes_ccm: ---- Nonce (len: 13): ----
8279
[00:00:00.251,739] <inf> aes_ccm: Content:
@@ -92,7 +89,7 @@ After programming the sample to your development kit, complete the following ste
9289
b3 5d 47 06 89 a5 08 3b e6 54 57 25 b9 49 02 50 |.]G....;.TW%.I.P
9390
d1 55 49 58 11 00 00 00 00 00 00 00 00 00 00 00 |.UX.............
9491
[00:00:00.251,922] <inf> aes_ccm: ---- Encrypted text end ----
95-
[00:00:00.251,953] <inf> aes_ccm: Decrypting using AES CCM MODE...
92+
[00:00:00.251,953] <inf> aes_ccm: Decrypting using the AES CCM mode...
9693
[00:00:00.252,166] <inf> aes_ccm: ---- Decrypted text (len: 100): ----
9794
[00:00:00.252,197] <inf> aes_ccm: Content:
9895
Example string to demonstrate basic usage of AES CCM mode.

‎samples/crypto/aes_ccm/src/main.c‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -124,7 +124,7 @@ int encrypt_ccm_aes(void)
124124
uint32_t output_len;
125125
psa_status_t status;
126126

127-
LOG_INF("Encrypting using AES CCM MODE...");
127+
LOG_INF("Encrypting using the AES CCM mode...");
128128

129129
/* Encrypt the plaintext and create the authentication tag */
130130
status = psa_aead_encrypt(key_id,
@@ -160,7 +160,7 @@ int decrypt_ccm_aes(void)
160160
uint32_t output_len;
161161
psa_status_t status;
162162

163-
LOG_INF("Decrypting using AES CCM MODE...");
163+
LOG_INF("Decrypting using the AES CCM mode...");
164164

165165
/* Decrypt the encrypted data and authenticate the tag */
166166
status = psa_aead_decrypt(key_id,

‎samples/crypto/aes_ctr/README.rst‎

Lines changed: 5 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -27,10 +27,9 @@ The sample :ref:`enables PSA Crypto API <psa_crypto_support_enable>` and configu
2727
* :kconfig:option:`CONFIG_PSA_WANT_ALG_CTR` - Used to enable support for the CTR cipher mode from among the supported cryptographic operations for :ref:`ug_crypto_supported_features_cipher_modes`.
2828
* :kconfig:option:`CONFIG_PSA_WANT_GENERATE_RANDOM` - Used to enable random number generation for key and IV generation from among the supported cryptographic operations for :ref:`ug_crypto_supported_features_rng_algorithms`.
2929

30-
The sample also configures the cryptographic drivers for each board target using Kconfig options in the overlay files in the :file:`boards` directory.
31-
32-
These Kconfig options are then used by Oberon PSA Crypto to compile the required cryptographic PSA directives and select the cryptographic drivers.
33-
See :ref:`crypto_drivers_driver_selection` for more information about the driver selection process.
30+
.. include:: /samples/crypto/aes_cbc/README.rst
31+
:start-after: crypto_sample_overview_driver_selection_start
32+
:end-before: crypto_sample_overview_driver_selection_end
3433

3534
Once built and run, the sample performs the following operations:
3635

@@ -65,8 +64,6 @@ Building and running
6564
Testing
6665
=======
6766

68-
After programming the sample to your development kit, complete the following steps to test it:
69-
7067
.. include:: /samples/crypto/aes_cbc/README.rst
7168
:start-after: crypto_sample_testing_start
7269
:end-before: crypto_sample_testing_end
@@ -78,7 +75,7 @@ After programming the sample to your development kit, complete the following ste
7875
[00:00:00.123,456] <inf> aes_ctr: Starting AES CTR example...
7976
[00:00:00.123,489] <inf> aes_ctr: Generating random AES key...
8077
[00:00:00.123,512] <inf> aes_ctr: AES key generated successfully!
81-
[00:00:00.123,545] <inf> aes_ctr: Encrypting using AES CTR MODE...
78+
[00:00:00.123,545] <inf> aes_ctr: Encrypting using the AES CTR mode...
8279
[00:00:00.123,567] <inf> aes_ctr: Encryption successful!
8380
[00:00:00.123,589] <inf> aes_ctr: ---- IV (len: 16): ----
8481
[00:00:00.123,611] <inf> aes_ctr: Content:
@@ -91,7 +88,7 @@ After programming the sample to your development kit, complete the following ste
9188
7b 61 95 44 09 64 ea ef ad b8 72 59 65 4f 6a 7c |{a.D.d....rYeOj|
9289
7f 81 f4 2a 3b 9d 3e 66 42 e5 db 87 4c 16 |...*;..fB...L.
9390
[00:00:00.123,699] <inf> aes_ctr: ---- Encrypted text end ----
94-
[00:00:00.123,721] <inf> aes_ctr: Decrypting using AES CTR MODE...
91+
[00:00:00.123,721] <inf> aes_ctr: Decrypting using the AES CTR mode...
9592
[00:00:00.123,743] <inf> aes_ctr: ---- Decrypted text (len: 56): ----
9693
[00:00:00.123,765] <inf> aes_ctr: Content:
9794
Example string to demonstrate basic usage of AES CTR mode.

‎samples/crypto/aes_ctr/src/main.c‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -114,7 +114,7 @@ int encrypt_ctr_aes(void)
114114
psa_status_t status;
115115
psa_cipher_operation_t operation = PSA_CIPHER_OPERATION_INIT;
116116

117-
LOG_INF("Encrypting using AES CTR MODE...");
117+
LOG_INF("Encrypting using the AES CTR mode...");
118118

119119
/* Setup the encryption operation */
120120
status = psa_cipher_encrypt_setup(&operation, key_id, PSA_ALG_CTR);
@@ -174,7 +174,7 @@ int decrypt_ctr_aes(void)
174174
psa_status_t status;
175175
psa_cipher_operation_t operation = PSA_CIPHER_OPERATION_INIT;
176176

177-
LOG_INF("Decrypting using AES CTR MODE...");
177+
LOG_INF("Decrypting using the AES CTR mode...");
178178

179179
/* Setup the decryption operation */
180180
status = psa_cipher_decrypt_setup(&operation, key_id, PSA_ALG_CTR);

‎samples/crypto/aes_gcm/README.rst‎

Lines changed: 63 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ Crypto: AES GCM
77
:local:
88
:depth: 2
99

10-
The AES GCM sample shows how to perform authenticated encryption and decryption operations using the GCM algorithm and a 128-bit key.
10+
The AES GCM sample demonstrates how to use the :ref:`PSA Crypto API <ug_psa_certified_api_overview_crypto>` to perform authenticated encryption and decryption operations using the GCM AEAD algorithm with a 128-bit AES key.
1111

1212
Requirements
1313
************
@@ -21,22 +21,36 @@ The sample supports the following development kits:
2121
Overview
2222
********
2323

24-
The sample performs the following operations:
24+
The sample :ref:`enables PSA Crypto API <psa_crypto_support_enable>` and configures the following Kconfig options for the cryptographic features:
25+
26+
* :kconfig:option:`CONFIG_PSA_WANT_KEY_TYPE_AES` - Used to enable support for AES key types from among the supported cryptographic operations for :ref:`ug_crypto_supported_features_key_types`.
27+
* :kconfig:option:`CONFIG_PSA_WANT_ALG_GCM` - Used to enable support for the GCM AEAD algorithm from among the supported cryptographic operations for :ref:`ug_crypto_supported_features_aead_algorithms`.
28+
* :kconfig:option:`CONFIG_PSA_WANT_GENERATE_RANDOM` - Used to enable random number generation for key and IV generation from among the supported cryptographic operations for :ref:`ug_crypto_supported_features_rng_algorithms`.
29+
30+
.. include:: /samples/crypto/aes_cbc/README.rst
31+
:start-after: crypto_sample_overview_driver_selection_start
32+
:end-before: crypto_sample_overview_driver_selection_end
33+
34+
Once built and run, the sample performs the following operations:
2535

2636
1. Initialization:
2737

28-
a. The Platform Security Architecture (PSA) API is initialized.
29-
#. A random AES key is generated and imported into the PSA crypto keystore.
38+
a. The PSA Crypto API is initialized using :c:func:`psa_crypto_init`.
39+
#. A random 128-bit AES key is generated using :c:func:`psa_generate_key` and stored in the PSA crypto keystore.
40+
The key is configured with usage flags for both encryption and decryption.
3041

31-
#. Encryption and decryption of a sample plaintext:
42+
#. Authenticated encryption and decryption of a sample plaintext:
3243

33-
a. A random initialization vector (IV) is generated.
34-
#. Authenticated encryption is performed.
35-
#. Authenticated decryption is performed.
44+
a. A random initialization vector (IV) is generated using :c:func:`psa_generate_random`.
45+
#. Authenticated encryption is performed using :c:func:`psa_aead_encrypt` with the ``PSA_ALG_GCM`` algorithm.
46+
This function encrypts the plaintext with the provided IV and additional authenticated data, and appends an authentication tag to the ciphertext.
47+
#. Authenticated decryption is performed using :c:func:`psa_aead_decrypt`.
48+
This function decrypts the ciphertext, verifies the authentication tag, and authenticates the additional data.
49+
#. The decrypted text is compared with the original plaintext to verify correctness.
3650

3751
#. Cleanup:
3852

39-
a. The AES key is removed from the PSA crypto keystore.
53+
a. The AES key is removed from the PSA crypto keystore using :c:func:`psa_destroy_key`.
4054

4155
.. note::
4256
The CRACEN driver only supports a 96-bit IV for :ref:`AES GCM<ug_crypto_supported_features_key_size>`.
@@ -51,8 +65,43 @@ Building and running
5165
Testing
5266
=======
5367

54-
After programming the sample to your development kit, complete the following steps to test it:
55-
56-
1. |connect_terminal|
57-
#. Compile and program the application.
58-
#. Observe the logs from the application using a terminal emulator.
68+
.. include:: /samples/crypto/aes_cbc/README.rst
69+
:start-after: crypto_sample_testing_start
70+
:end-before: crypto_sample_testing_end
71+
72+
.. code-block:: text
73+
74+
*** Booting nRF Connect SDK v3.1.0-6c6e5b32496e ***
75+
*** Using Zephyr OS v4.1.99-1612683d4010 ***
76+
[00:00:00.251,159] <inf> aes_gcm: Starting AES GCM example...
77+
[00:00:00.251,190] <inf> aes_gcm: Generating random AES key...
78+
[00:00:00.251,342] <inf> aes_gcm: AES key generated successfully!
79+
[00:00:00.251,373] <inf> aes_gcm: Encrypting using the AES GCM mode...
80+
[00:00:00.251,708] <inf> aes_gcm: Encryption successful!
81+
[00:00:00.251,708] <inf> aes_gcm: ---- IV (len: 12): ----
82+
[00:00:00.251,739] <inf> aes_gcm: Content:
83+
c3 1e 5b 35 97 25 ee a3 ef ba 66 c3 |..[5.%.. ..f.
84+
[00:00:00.251,770] <inf> aes_gcm: ---- IV end ----
85+
[00:00:00.251,800] <inf> aes_gcm: ---- Additional data (len: 35): ----
86+
[00:00:00.251,831] <inf> aes_gcm: Content:
87+
Example string of additional data
88+
[00:00:00.251,831] <inf> aes_gcm: ---- Additional data end ----
89+
[00:00:00.251,861] <inf> aes_gcm: ---- Plaintext (len: 100): ----
90+
[00:00:00.251,892] <inf> aes_gcm: Content:
91+
Example string to demonstrate basic usage of AES GCM mode.
92+
[00:00:00.251,922] <inf> aes_gcm: ---- Plaintext end ----
93+
[00:00:00.251,953] <inf> aes_gcm: ---- Encrypted text (len: 116): ----
94+
[00:00:00.251,984] <inf> aes_gcm: Content:
95+
cc 7d c0 ed 63 5b df 28 08 2b 03 33 a4 3c dc 1d |.}..c[.( .+.3.<..
96+
76 9d a9 cb 1c 49 4f 6d ef b8 a2 aa 11 2c fc bd |v....IOm .....,..
97+
39 56 54 b5 96 6e 13 e2 7d 22 26 1e 3c 7c 3e eb |9VT..n.. }"&.<|>.
98+
15 60 31 d3 58 02 b6 85 98 63 2c e6 ad dc aa 19 |.`1.X... .c,.....
99+
4a 2b 3c 1d 5e 6f 7a 8b 9c ad be cf d0 e1 f2 03 |J+<.^oz. ........
100+
[00:00:00.252,014] <inf> aes_gcm: ---- Encrypted text end ----
101+
[00:00:00.252,045] <inf> aes_gcm: Decrypting using the AES GCM mode...
102+
[00:00:00.252,166] <inf> aes_gcm: ---- Decrypted text (len: 100): ----
103+
[00:00:00.252,197] <inf> aes_gcm: Content:
104+
Example string to demonstrate basic usage of AES GCM mode.
105+
[00:00:00.252,227] <inf> aes_gcm: ---- Decrypted text end ----
106+
[00:00:00.252,258] <inf> aes_gcm: Decryption and authentication successful!
107+
[00:00:00.252,288] <inf> aes_gcm: Example finished successfully!

‎samples/crypto/aes_gcm/sample.yaml‎

Lines changed: 3 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,7 @@
11
sample:
2-
description: >
3-
This app provides an example of performing authenticated
4-
AES encryption and decryption using AES GCM mode
5-
name: AES GCM example
2+
description: |
3+
This sample demonstrates AES encryption and decryption using the AES GCM mode.
4+
name: AES GCM sample
65
tests:
76
sample.aes_gcm.cc312:
87
sysbuild: true

‎samples/crypto/aes_gcm/src/main.c‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -124,7 +124,7 @@ int encrypt_aes_gcm(void)
124124
uint32_t output_len;
125125
psa_status_t status;
126126

127-
LOG_INF("Encrypting using AES GCM MODE...");
127+
LOG_INF("Encrypting using the AES GCM mode...");
128128

129129
/* Generate a random IV */
130130
status = psa_generate_random(m_iv, NRF_CRYPTO_EXAMPLE_AES_IV_SIZE);
@@ -164,7 +164,7 @@ int decrypt_aes_gcm(void)
164164
uint32_t output_len;
165165
psa_status_t status;
166166

167-
LOG_INF("Decrypting using AES GCM MODE...");
167+
LOG_INF("Decrypting using the AES GCM mode...");
168168

169169
/* Decrypt and authenticate the encrypted data */
170170
status = psa_aead_decrypt(key_id,
@@ -200,7 +200,7 @@ int main(void)
200200
{
201201
int status;
202202

203-
LOG_INF("Starting AES-GCM example...");
203+
LOG_INF("Starting AES GCM example...");
204204

205205
status = crypto_init();
206206
if (status != APP_SUCCESS) {

0 commit comments

Comments
 (0)