Skip to content

Commit 321b685

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

File tree

9 files changed

+193
-44
lines changed

9 files changed

+193
-44
lines changed

‎doc/nrf/samples/tfm.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33
Trusted Firmware-M (TF-M) samples
44
#################################
55

6-
This section lists the available |NCS| samples and tests for :ref:`ug_tfm`, one of the :ref:`security` features of the |NCS|.
6+
This section lists the available |NCS| samples and tests for :ref:`Trusted Firmware-M <ug_tfm>`, one of the :ref:`security` features of the |NCS|.
77

88
You can start by checking the :ref:`tfm_hello_world` sample, which demonstrates how to add TF-M to an application.
99

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

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6599,6 +6599,8 @@ Based on this setting, Oberon PSA Crypto selects the most appropriate driver for
65996599
| :kconfig:option:`CONFIG_PSA_WANT_ECC_SECP_R1_256`
66006600
| :kconfig:option:`CONFIG_PSA_WANT_ECC_SECP_R1_384`
66016601
6602+
.. _ug_crypto_supported_features_rng_algorithms:
6603+
66026604
RNG algorithms
66036605
==============
66046606

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

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -69,6 +69,8 @@ Hardware drivers take precedence over software drivers, which provide fallback o
6969

7070
.. psa_crypto_driver_table_end
7171
72+
.. _crypto_drivers_driver_selection:
73+
7274
Driver selection
7375
****************
7476

‎samples/crypto/aes_cbc/README.rst‎

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

10-
The AES CBC sample shows how to perform AES encryption and decryption operations using the CBC block cipher mode without padding and a 128-bit AES key.
10+
The AES CBC sample demonstrates how to use the :ref:`PSA Crypto API <ug_psa_certified_api_overview_crypto>` to perform AES encryption and decryption operations using the CBC block cipher mode without padding and a 128-bit AES key.
1111

1212
Requirements
1313
************
@@ -21,22 +21,38 @@ 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_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`.
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+
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.
34+
35+
Once built and run, the sample performs the following operations:
2536

2637
1. Initialization:
2738

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

3143
#. Encryption and decryption of a sample plaintext:
3244

33-
a. A random initialization vector (IV) is generated.
34-
#. Encryption is performed.
35-
#. Decryption is performed.
45+
a. An encryption operation is set up using :c:func:`psa_cipher_encrypt_setup` with the ``PSA_ALG_CBC_NO_PADDING`` algorithm.
46+
#. A random initialization vector (IV) is generated using :c:func:`psa_cipher_generate_iv`.
47+
#. Encryption is performed using :c:func:`psa_cipher_update` and finalized with :c:func:`psa_cipher_finish`.
48+
#. A decryption operation is set up using :c:func:`psa_cipher_decrypt_setup`.
49+
#. The IV from the encryption step is set using :c:func:`psa_cipher_set_iv`.
50+
#. Decryption is performed using :c:func:`psa_cipher_update` and finalized with :c:func:`psa_cipher_finish`.
51+
#. The decrypted text is compared with the original plaintext to verify correctness.
3652

3753
#. Cleanup:
3854

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

4157
Building and running
4258
********************
@@ -50,6 +66,49 @@ Testing
5066

5167
After programming the sample to your development kit, complete the following steps to test it:
5268

69+
.. crypto_sample_testing_start
70+
5371
1. |connect_terminal|
54-
#. Compile and program the application.
55-
#. Observe the logs from the application using a terminal emulator.
72+
#. Build and program the application.
73+
#. Observe the logs from the application using the terminal emulator.
74+
For example, the log output should look like this:
75+
76+
.. crypto_sample_testing_end
77+
78+
.. code-block:: text
79+
80+
*** Booting nRF Connect SDK v3.1.0-6c6e5b32496e ***
81+
*** Using Zephyr OS v4.1.99-1612683d4010 ***
82+
[00:00:00.251,159] <inf> aes_cbc: Starting AES-CBC-NO-PADDING example...
83+
[00:00:00.251,190] <inf> aes_cbc: Generating random AES key...
84+
[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...
86+
[00:00:00.251,708] <inf> aes_cbc: Encryption successful!
87+
[00:00:00.251,708] <inf> aes_cbc: ---- IV (len: 16): ----
88+
[00:00:00.251,739] <inf> aes_cbc: Content:
89+
c3 1e 5b 35 97 25 ee a3 ef ba 66 c3 f9 81 37 2a |..[5.%.. ..f...7*
90+
[00:00:00.251,770] <inf> aes_cbc: ---- IV end ----
91+
[00:00:00.251,800] <inf> aes_cbc: ---- Plaintext (len: 64): ----
92+
[00:00:00.251,831] <inf> aes_cbc: Content:
93+
45 78 61 6d 70 6c 65 20 73 74 72 69 6e 67 20 74 |Example string t
94+
6f 20 64 65 6d 6f 6e 73 74 72 61 74 65 20 62 61 |o demons trate ba
95+
73 69 63 20 75 73 61 67 65 20 6f 66 20 41 45 53 |sic usag e of AES
96+
20 43 42 43 20 6d 6f 64 65 2e 00 00 00 00 00 00 | CBC mod e.......
97+
[00:00:00.251,831] <inf> aes_cbc: ---- Plaintext end ----
98+
[00:00:00.251,861] <inf> aes_cbc: ---- Encrypted text (len: 64): ----
99+
[00:00:00.251,892] <inf> aes_cbc: Content:
100+
cc 7d c0 ed 63 5b df 28 08 2b 03 33 a4 3c dc 1d |.}..c[.( .+.3.<..
101+
76 9d a9 cb 1c 49 4f 6d ef b8 a2 aa 11 2c fc bd |v....IOm .....,..
102+
39 56 54 b5 96 6e 13 e2 7d 22 26 1e 3c 7c 3e eb |9VT..n.. }"&.<|>.
103+
15 60 31 d3 58 02 b6 85 98 63 2c e6 ad dc aa 19 |.`1.X... .c,.....
104+
[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...
106+
[00:00:00.252,166] <inf> aes_cbc: ---- Decrypted text (len: 64): ----
107+
[00:00:00.252,197] <inf> aes_cbc: Content:
108+
45 78 61 6d 70 6c 65 20 73 74 72 69 6e 67 20 74 |Example string t
109+
6f 20 64 65 6d 6f 6e 73 74 72 61 74 65 20 62 61 |o demons trate ba
110+
73 69 63 20 75 73 61 67 65 20 6f 66 20 41 45 53 |sic usag e of AES
111+
20 43 42 43 20 6d 6f 64 65 2e 00 00 00 00 00 00 | CBC mod e.......
112+
[00:00:00.252,227] <inf> aes_cbc: ---- Decrypted text end ----
113+
[00:00:00.252,258] <inf> aes_cbc: Decryption successful!
114+
[00:00:00.252,288] <inf> aes_cbc: Example finished successfully!

‎samples/crypto/aes_cbc/sample.yaml‎

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

‎samples/crypto/aes_ccm/README.rst‎

Lines changed: 58 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -7,8 +7,8 @@ Crypto: AES CCM
77
:local:
88
:depth: 2
99

10-
The AES CCM sample shows how to perform authenticated encryption and decryption operations using the CCM algorithm and a 128-bit key.
11-
The sample uses additional data and a random nonce.
10+
The AES CCM 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 CCM AEAD algorithm with a 128-bit AES key.
11+
The sample uses additional authenticated data (AAD) and a random nonce.
1212

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

25-
The sample performs the following operations:
25+
The sample :ref:`enables PSA Crypto API <psa_crypto_support_enable>` and configures the following Kconfig options for the cryptographic features:
26+
27+
* :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`.
28+
* :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`.
29+
* :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`.
30+
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.
35+
36+
Once built and run, the sample performs the following operations:
2637

2738
1. Initialization:
2839

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

32-
#. Encryption and decryption of a sample plaintext:
44+
#. Authenticated encryption and decryption of a sample plaintext:
3345

34-
a. A random nonce is generated.
35-
#. Authenticated encryption is performed.
36-
#. Authenticated decryption is performed.
46+
a. Authenticated encryption is performed using :c:func:`psa_aead_encrypt` with the ``PSA_ALG_CCM`` algorithm.
47+
This function encrypts the plaintext with the provided nonce and additional authenticated data, and appends an authentication tag to the ciphertext.
48+
#. Authenticated decryption is performed using :c:func:`psa_aead_decrypt`.
49+
This function decrypts the ciphertext, verifies the authentication tag, and authenticates the additional data.
50+
#. The decrypted text is compared with the original plaintext to verify correctness.
3751

3852
#. Cleanup:
3953

40-
a. The AES key is removed from the PSA crypto keystore.
54+
a. The AES key is removed from the PSA crypto keystore using :c:func:`psa_destroy_key`.
4155

4256
Building and running
4357
********************
@@ -51,6 +65,37 @@ Testing
5165

5266
After programming the sample to your development kit, complete the following steps to test it:
5367

54-
1. |connect_terminal|
55-
#. Compile and program the application.
56-
#. 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::
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_ccm: Starting AES CCM example...
77+
[00:00:00.251,190] <inf> aes_ccm: Generating random AES key...
78+
[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...
80+
[00:00:00.251,708] <inf> aes_ccm: Encryption successful!
81+
[00:00:00.251,708] <inf> aes_ccm: ---- Nonce (len: 13): ----
82+
[00:00:00.251,739] <inf> aes_ccm: Content:
83+
SAMPLE NONCE
84+
[00:00:00.251,770] <inf> aes_ccm: ---- Nonce end ----
85+
[00:00:00.251,800] <inf> aes_ccm: ---- Additional data (len: 35): ----
86+
[00:00:00.251,831] <inf> aes_ccm: Content:
87+
Example string of additional data
88+
[00:00:00.251,831] <inf> aes_ccm: ---- Additional data end ----
89+
[00:00:00.251,861] <inf> aes_ccm: ---- Encrypted text (len: 115): ----
90+
[00:00:00.251,892] <inf> aes_ccm: Content:
91+
c4 36 60 2b 45 59 5b 12 35 00 00 00 00 00 00 00 |.6.+EY[..5.......
92+
b3 5d 47 06 89 a5 08 3b e6 54 57 25 b9 49 02 50 |.]G....;.TW%.I.P
93+
d1 55 49 58 11 00 00 00 00 00 00 00 00 00 00 00 |.UX.............
94+
[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...
96+
[00:00:00.252,166] <inf> aes_ccm: ---- Decrypted text (len: 100): ----
97+
[00:00:00.252,197] <inf> aes_ccm: Content:
98+
Example string to demonstrate basic usage of AES CCM mode.
99+
[00:00:00.252,227] <inf> aes_ccm: ---- Decrypted text end ----
100+
[00:00:00.252,258] <inf> aes_ccm: Decryption and authentication successful!
101+
[00:00:00.252,288] <inf> aes_ccm: Example finished successfully!

‎samples/crypto/aes_ccm/sample.yaml‎

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

‎samples/crypto/aes_ctr/README.rst‎

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

10-
The AES CTR sample shows how to perform AES encryption and decryption operations using the CTR block cipher mode without padding and a 128-bit AES key.
10+
The AES CTR sample demonstrates how to use the :ref:`PSA Crypto API <ug_psa_certified_api_overview_crypto>` to perform AES encryption and decryption operations using the CTR block cipher mode and a 128-bit AES key.
1111

1212
Requirements
1313
************
@@ -21,22 +21,38 @@ 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_CTR` - Used to enable support for the CTR cipher mode from among the supported cryptographic operations for :ref:`ug_crypto_supported_features_cipher_modes`.
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+
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.
34+
35+
Once built and run, the sample performs the following operations:
2536

2637
1. Initialization:
2738

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

3143
#. Encryption and decryption of a sample plaintext:
3244

33-
a. A random initialization vector (IV) is generated.
34-
#. Encryption is performed.
35-
#. Decryption is performed.
45+
a. An encryption operation is set up using :c:func:`psa_cipher_encrypt_setup` with the ``PSA_ALG_CTR`` algorithm.
46+
#. A random initialization vector (IV) is generated using :c:func:`psa_cipher_generate_iv`.
47+
#. Encryption is performed using :c:func:`psa_cipher_update` and finalized with :c:func:`psa_cipher_finish`.
48+
#. A decryption operation is set up using :c:func:`psa_cipher_decrypt_setup`.
49+
#. The IV from the encryption step is set using :c:func:`psa_cipher_set_iv`.
50+
#. Decryption is performed using :c:func:`psa_cipher_update` and finalized with :c:func:`psa_cipher_finish`.
51+
#. The decrypted text is compared with the original plaintext to verify correctness.
3652

3753
#. Cleanup:
3854

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

4157
Building and running
4258
********************
@@ -51,6 +67,34 @@ Testing
5167

5268
After programming the sample to your development kit, complete the following steps to test it:
5369

54-
1. |connect_terminal|
55-
#. Compile and program the application.
56-
#. Observe the logs from the application using a terminal emulator.
70+
.. include:: /samples/crypto/aes_cbc/README.rst
71+
:start-after: crypto_sample_testing_start
72+
:end-before: crypto_sample_testing_end
73+
74+
.. code-block:: text
75+
76+
*** Booting nRF Connect SDK v3.1.0-6c6e5b32496e ***
77+
*** Using Zephyr OS v4.1.99-1612683d4010 ***
78+
[00:00:00.123,456] <inf> aes_ctr: Starting AES CTR example...
79+
[00:00:00.123,489] <inf> aes_ctr: Generating random AES key...
80+
[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...
82+
[00:00:00.123,567] <inf> aes_ctr: Encryption successful!
83+
[00:00:00.123,589] <inf> aes_ctr: ---- IV (len: 16): ----
84+
[00:00:00.123,611] <inf> aes_ctr: Content:
85+
01 02 03 04 05 06 07 08 09 0a 0b 0c 0d 0e 0f 10 |................
86+
[00:00:00.123,633] <inf> aes_ctr: ---- IV end ----
87+
[00:00:00.123,655] <inf> aes_ctr: ---- Encrypted text (len: 56): ----
88+
[00:00:00.123,677] <inf> aes_ctr: Content:
89+
5e 3a a2 c6 2f 8d 57 89 3c 90 1e a0 b2 d5 6c 48 |^:../.W.<.....lH
90+
d8 61 aa 35 4b da 09 83 a4 f6 18 e3 0b dd 92 0c |.a.5K...........
91+
7b 61 95 44 09 64 ea ef ad b8 72 59 65 4f 6a 7c |{a.D.d....rYeOj|
92+
7f 81 f4 2a 3b 9d 3e 66 42 e5 db 87 4c 16 |...*;..fB...L.
93+
[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...
95+
[00:00:00.123,743] <inf> aes_ctr: ---- Decrypted text (len: 56): ----
96+
[00:00:00.123,765] <inf> aes_ctr: Content:
97+
Example string to demonstrate basic usage of AES CTR mode.
98+
[00:00:00.123,787] <inf> aes_ctr: ---- Decrypted text end ----
99+
[00:00:00.123,809] <inf> aes_ctr: Decryption successful!
100+
[00:00:00.123,831] <inf> aes_ctr: Example finished successfully!

‎samples/crypto/aes_ctr/sample.yaml‎

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

0 commit comments

Comments
 (0)