Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

doc: nrf_security: Improve PSA configuration documentation #11702

Merged
merged 7 commits into from
Jul 6, 2023
Merged

doc: nrf_security: Improve PSA configuration documentation #11702

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
cd46617
doc: nrf_security: Document RSA as PKCS#1 v1.5
joerchan Jul 4, 2023
8515579
doc: nrf_security: Use PSA naming of chachapoly algorithm
joerchan Jul 4, 2023
0bc7df1
doc: nrf_security: Remove AES from cipher documentation
joerchan Jul 5, 2023
0fa8811
doc: nrf_security: Use better naming for cipher names
joerchan Jul 5, 2023
533546b
doc: nrf_security: Use better naming for PRNG names
joerchan Jul 5, 2023
626536e
doc: nrf_security: Add documentation for PSA RNG configuration
joerchan Jul 5, 2023
0f7f9e4
manifest: Update zephyr and nrfxlib for PSA doc and config fixes
joerchan Jul 5, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
153 changes: 78 additions & 75 deletions doc/nrf/libraries/nrf_security/doc/driver_config.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,56 +31,56 @@ If multiple drivers are enabled, the first ordered item in this table takes prec
Enabling or disabling PSA driver specific configurations controls the support for a given algorithm, per driver.


AES cipher configurations
*************************

To enable AES cipher modes, set one or more of the following Kconfig options:

+----------------+------------------------------------------------------+
| Cipher mode | Configuration option |
+================+======================================================+
| ECB_NO_PADDING | :kconfig:option:`CONFIG_PSA_WANT_ALG_ECB_NO_PADDING` |
+----------------+------------------------------------------------------+
| CBC_NO_PADDING | :kconfig:option:`CONFIG_PSA_WANT_ALG_CBC_NO_PADDING` |
+----------------+------------------------------------------------------+
| CBC_PKCS7 | :kconfig:option:`CONFIG_PSA_WANT_ALG_CBC_PKCS7` |
+----------------+------------------------------------------------------+
| CFB | :kconfig:option:`CONFIG_PSA_WANT_ALG_CFB` |
+----------------+------------------------------------------------------+
| CTR | :kconfig:option:`CONFIG_PSA_WANT_ALG_CTR` |
+----------------+------------------------------------------------------+
| OFB | :kconfig:option:`CONFIG_PSA_WANT_ALG_OFB` |
+----------------+------------------------------------------------------+
| XTS | :kconfig:option:`CONFIG_PSA_WANT_ALG_XTS` |
+----------------+------------------------------------------------------+
| Stream cipher | :kconfig:option:`CONFIG_PSA_WANT_ALG_STREAM_CIPHER` |
+----------------+------------------------------------------------------+


AES cipher driver configurations
================================

You can use the following Kconfig options for fine-grained control over which drivers provide AES cipher support:

+----------------+---------------------------------------------------------------------+----------------------------------------------------------------------+
| Cipher mode | nrf_cc3xx driver support | nrf_oberon driver support |
+================+=====================================================================+======================================================================+
| ECB_NO_PADDING | :kconfig:option:`CONFIG_PSA_CRYPTO_DRIVER_ALG_ECB_NO_PADDING_CC3XX` | :kconfig:option:`CONFIG_PSA_CRYPTO_DRIVER_ALG_ECB_NO_PADDING_OBERON` |
+----------------+---------------------------------------------------------------------+----------------------------------------------------------------------+
| CBC_NO_PADDING | :kconfig:option:`CONFIG_PSA_CRYPTO_DRIVER_ALG_CBC_NO_PADDING_CC3XX` | :kconfig:option:`CONFIG_PSA_CRYPTO_DRIVER_ALG_CBC_NO_PADDING_OBERON` |
+----------------+---------------------------------------------------------------------+----------------------------------------------------------------------+
| CBC_PKCS7 | :kconfig:option:`CONFIG_PSA_CRYPTO_DRIVER_ALG_CBC_PKCS7_CC3XX` | :kconfig:option:`CONFIG_PSA_CRYPTO_DRIVER_ALG_CBC_PKCS7_OBERON` |
+----------------+---------------------------------------------------------------------+----------------------------------------------------------------------+
| CFB | Not supported | Not supported |
+----------------+---------------------------------------------------------------------+----------------------------------------------------------------------+
| CTR | :kconfig:option:`CONFIG_PSA_CRYPTO_DRIVER_ALG_CTR_CC3XX` | :kconfig:option:`CONFIG_PSA_CRYPTO_DRIVER_ALG_CTR_OBERON` |
+----------------+---------------------------------------------------------------------+----------------------------------------------------------------------+
| OFB | :kconfig:option:`CONFIG_PSA_CRYPTO_DRIVER_ALG_OFB_CC3XX` | Not supported |
+----------------+---------------------------------------------------------------------+----------------------------------------------------------------------+
| XTS | Not supported | Not supported |
+----------------+---------------------------------------------------------------------+----------------------------------------------------------------------+
| Stream cipher | :kconfig:option:`CONFIG_PSA_CRYPTO_DRIVER_ALG_STREAM_CIPHER_CC3XX` | :kconfig:option:`CONFIG_PSA_CRYPTO_DRIVER_ALG_STREAM_CIPHER_OBERON` |
+----------------+---------------------------------------------------------------------+----------------------------------------------------------------------+
Cipher configurations
*********************

To enable cipher modes, set one or more of the following Kconfig options:

+-----------------------+------------------------------------------------------+
| Cipher mode | Configuration option |
+=======================+======================================================+
| ECB no padding | :kconfig:option:`CONFIG_PSA_WANT_ALG_ECB_NO_PADDING` |
+-----------------------+------------------------------------------------------+
| CBC no padding | :kconfig:option:`CONFIG_PSA_WANT_ALG_CBC_NO_PADDING` |
+-----------------------+------------------------------------------------------+
| CBC PKCS#7 padding | :kconfig:option:`CONFIG_PSA_WANT_ALG_CBC_PKCS7` |
+-----------------------+------------------------------------------------------+
| CFB | :kconfig:option:`CONFIG_PSA_WANT_ALG_CFB` |
+-----------------------+------------------------------------------------------+
| CTR | :kconfig:option:`CONFIG_PSA_WANT_ALG_CTR` |
+-----------------------+------------------------------------------------------+
| OFB | :kconfig:option:`CONFIG_PSA_WANT_ALG_OFB` |
+-----------------------+------------------------------------------------------+
| XTS | :kconfig:option:`CONFIG_PSA_WANT_ALG_XTS` |
+-----------------------+------------------------------------------------------+
| Stream cipher | :kconfig:option:`CONFIG_PSA_WANT_ALG_STREAM_CIPHER` |
+-----------------------+------------------------------------------------------+


Cipher driver configurations
============================

You can use the following Kconfig options for fine-grained control over which drivers provide cipher support:

+-----------------------+---------------------------------------------------------------------+----------------------------------------------------------------------+
| Cipher mode | nrf_cc3xx driver support | nrf_oberon driver support |
+=======================+=====================================================================+======================================================================+
| ECB no padding | :kconfig:option:`CONFIG_PSA_CRYPTO_DRIVER_ALG_ECB_NO_PADDING_CC3XX` | :kconfig:option:`CONFIG_PSA_CRYPTO_DRIVER_ALG_ECB_NO_PADDING_OBERON` |
+-----------------------+---------------------------------------------------------------------+----------------------------------------------------------------------+
| CBC no padding | :kconfig:option:`CONFIG_PSA_CRYPTO_DRIVER_ALG_CBC_NO_PADDING_CC3XX` | :kconfig:option:`CONFIG_PSA_CRYPTO_DRIVER_ALG_CBC_NO_PADDING_OBERON` |
+-----------------------+---------------------------------------------------------------------+----------------------------------------------------------------------+
| CBC PKCS#7 padding | :kconfig:option:`CONFIG_PSA_CRYPTO_DRIVER_ALG_CBC_PKCS7_CC3XX` | :kconfig:option:`CONFIG_PSA_CRYPTO_DRIVER_ALG_CBC_PKCS7_OBERON` |
+-----------------------+---------------------------------------------------------------------+----------------------------------------------------------------------+
| CFB | Not supported | Not supported |
+-----------------------+---------------------------------------------------------------------+----------------------------------------------------------------------+
| CTR | :kconfig:option:`CONFIG_PSA_CRYPTO_DRIVER_ALG_CTR_CC3XX` | :kconfig:option:`CONFIG_PSA_CRYPTO_DRIVER_ALG_CTR_OBERON` |
+-----------------------+---------------------------------------------------------------------+----------------------------------------------------------------------+
| OFB | :kconfig:option:`CONFIG_PSA_CRYPTO_DRIVER_ALG_OFB_CC3XX` | Not supported |
+-----------------------+---------------------------------------------------------------------+----------------------------------------------------------------------+
| XTS | Not supported | Not supported |
+-----------------------+---------------------------------------------------------------------+----------------------------------------------------------------------+
| Stream cipher | :kconfig:option:`CONFIG_PSA_CRYPTO_DRIVER_ALG_STREAM_CIPHER_CC3XX` | :kconfig:option:`CONFIG_PSA_CRYPTO_DRIVER_ALG_STREAM_CIPHER_OBERON` |
+-----------------------+---------------------------------------------------------------------+----------------------------------------------------------------------+

.. note::
* The :ref:`nrf_security_drivers_cc3xx` is limited to AES key sizes of 128 bits on devices with Arm CryptoCell cc310.
Expand Down Expand Up @@ -162,44 +162,44 @@ You can use the following Kconfig options for fine-grained control over which dr
+----------------+-----------------------------------------------------------+------------------------------------------------------------+

.. note::
* The :ref:`nrf_security_drivers_cc3xx` is limited to AES CMAC key sizes of 128 bits on devices with Arm CryptoCell cc310.
* The :ref:`nrf_security_drivers_cc3xx` is limited to HMAC using SHA-1, SHA-224, and SHA-256 on devices with Arm CryptoCell.
* The :ref:`nrf_security_drivers_cc3xx` is limited to CMAC using AES key sizes of 128 bits on devices with Arm CryptoCell cc310.
* The :ref:`nrf_security_drivers_cc3xx` is limited to HMAC using SHA-1, SHA-224, and SHA-256.


AEAD configurations
*******************

To enable Authenticated Encryption with Associated Data (AEAD), set one or more of the following Kconfig options:

+----------------+---------------------------------------------------------+
| AEAD cipher | Configuration option |
+================+=========================================================+
| AES CCM | :kconfig:option:`CONFIG_PSA_WANT_ALG_CCM` |
+----------------+---------------------------------------------------------+
| AES GCM | :kconfig:option:`CONFIG_PSA_WANT_ALG_GCM` |
+----------------+---------------------------------------------------------+
| ChaCha/Poly | :kconfig:option:`CONFIG_PSA_WANT_ALG_CHACHA20_POLY1305` |
+----------------+---------------------------------------------------------+
+-----------------------+---------------------------------------------------------+
| AEAD cipher | Configuration option |
+=======================+=========================================================+
| CCM | :kconfig:option:`CONFIG_PSA_WANT_ALG_CCM` |
+-----------------------+---------------------------------------------------------+
| GCM | :kconfig:option:`CONFIG_PSA_WANT_ALG_GCM` |
+-----------------------+---------------------------------------------------------+
| ChaCha20-Poly1305 | :kconfig:option:`CONFIG_PSA_WANT_ALG_CHACHA20_POLY1305` |
+-----------------------+---------------------------------------------------------+


AEAD driver configurations
==========================

You can use the following Kconfig options for fine-grained control over which drivers provide AEAD support:

+----------------+------------------------------------------------------------------------+-------------------------------------------------------------------------+
| AEAD cipher | nrf_cc3xx driver support | nrf_oberon driver support |
+================+========================================================================+=========================================================================+
| AES CCM | :kconfig:option:`CONFIG_PSA_CRYPTO_DRIVER_ALG_CCM_CC3XX` | :kconfig:option:`CONFIG_PSA_CRYPTO_DRIVER_ALG_CCM_OBERON` |
+----------------+------------------------------------------------------------------------+-------------------------------------------------------------------------+
| AES GCM | :kconfig:option:`CONFIG_PSA_CRYPTO_DRIVER_ALG_GCM_CC3XX` | :kconfig:option:`CONFIG_PSA_CRYPTO_DRIVER_ALG_GCM_OBERON` |
+----------------+------------------------------------------------------------------------+-------------------------------------------------------------------------+
| ChaCha/Poly | :kconfig:option:`CONFIG_PSA_CRYPTO_DRIVER_ALG_CHACHA20_POLY1305_CC3XX` | :kconfig:option:`CONFIG_PSA_CRYPTO_DRIVER_ALG_CHACHA20_POLY1305_OBERON` |
+----------------+------------------------------------------------------------------------+-------------------------------------------------------------------------+
+-----------------------+------------------------------------------------------------------------+-------------------------------------------------------------------------+
| AEAD cipher | nrf_cc3xx driver support | nrf_oberon driver support |
+=======================+========================================================================+=========================================================================+
| CCM | :kconfig:option:`CONFIG_PSA_CRYPTO_DRIVER_ALG_CCM_CC3XX` | :kconfig:option:`CONFIG_PSA_CRYPTO_DRIVER_ALG_CCM_OBERON` |
+-----------------------+------------------------------------------------------------------------+-------------------------------------------------------------------------+
| GCM | :kconfig:option:`CONFIG_PSA_CRYPTO_DRIVER_ALG_GCM_CC3XX` | :kconfig:option:`CONFIG_PSA_CRYPTO_DRIVER_ALG_GCM_OBERON` |
+-----------------------+------------------------------------------------------------------------+-------------------------------------------------------------------------+
| ChaCha20-Poly1305 | :kconfig:option:`CONFIG_PSA_CRYPTO_DRIVER_ALG_CHACHA20_POLY1305_CC3XX` | :kconfig:option:`CONFIG_PSA_CRYPTO_DRIVER_ALG_CHACHA20_POLY1305_OBERON` |
+-----------------------+------------------------------------------------------------------------+-------------------------------------------------------------------------+

.. note::
* The :ref:`nrf_security_drivers_cc3xx` is limited to AES key sizes of 128 bits on devices with Arm CryptoCell cc310.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should AES be removed before GCM in the line below as well?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No, the limitation is still valid. we only support AES, and we only support AES key size of 128 bits

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Just to be sure we're not misunderstanding each other :D I meant in line below (i.e. line 189), with the following text:

  • The :ref:nrf_security_drivers_cc3xx does not provide hardware support for AES GCM on devices with Arm CryptoCell cc310.
    I guess I am not sure why we removed AES from AES GCM in the table above, but we're still keeping it in the limitation in the note below the table.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Oh yeah, my bad, I didn't read your comment properly.

Yeah, we can say don't support GCM at all.

* The :ref:`nrf_security_drivers_cc3xx` does not provide hardware support for AES GCM on devices with Arm CryptoCell cc310.
* The :ref:`nrf_security_drivers_cc3xx` does not provide hardware support for GCM on devices with Arm CryptoCell cc310.


ECC configurations
Expand Down Expand Up @@ -315,20 +315,23 @@ You can use the following Kconfig options for fine-grained control over which dr
RNG configurations
******************

To enable PRNG seeded by entropy (also known as TRNG), set one or more of the following configurations:
Enable RNG using the :kconfig:option:`CONFIG_PSA_WANT_GENERATE_RANDOM` Kconfig option.

RNG uses PRNG seeded by entropy (also known as TRNG).
When RNG is enabled, set at least one of the following configurations:

+---------------------------+-------------------------------------------------+
| PRNG algorithms | Configuration option |
+===========================+=================================================+
| CTR_DRBG | :kconfig:option:`CONFIG_PSA_WANT_ALG_CTR_DRBG` |
| CTR-DRBG | :kconfig:option:`CONFIG_PSA_WANT_ALG_CTR_DRBG` |
+---------------------------+-------------------------------------------------+
| HMAC_DRBG | :kconfig:option:`CONFIG_PSA_WANT_ALG_HMAC_DRBG` |
| HMAC-DRBG | :kconfig:option:`CONFIG_PSA_WANT_ALG_HMAC_DRBG` |
+---------------------------+-------------------------------------------------+

.. note::
* Both PRNG algorithms are NIST qualified Cryptographically Secure Pseudo Random Number Generators (CSPRNG).
* :kconfig:option:`CONFIG_PSA_WANT_ALG_CTR_DRBG` and :kconfig:option:`CONFIG_PSA_WANT_ALG_HMAC_DRBG` are custom configurations not described by the PSA Crypto specification.
* If multiple PRNG algorithms are enabled at the same time, CTR_DRBG will be prioritized for random number generation through the front-end APIs for PSA Crypto.
* If multiple PRNG algorithms are enabled at the same time, CTR-DRBG will be prioritized for random number generation through the front-end APIs for PSA Crypto.


RNG driver configurations
Expand Down
4 changes: 2 additions & 2 deletions subsys/nrf_security/src/drivers/nrf_cc3xx/Kconfig
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -173,13 +173,13 @@ config PSA_CRYPTO_DRIVER_ALG_RSA_OAEP_CC3XX

config PSA_CRYPTO_DRIVER_ALG_RSA_PKCS1V15_CRYPT_CC3XX
bool
prompt "PSA RSA crypt support (PKCS1V15 mode) - cc3xx" if !PSA_PROMPTLESS
prompt "PSA RSA crypt support (PKCS#1 v1.5 mode) - cc3xx" if !PSA_PROMPTLESS
default y if !PSA_DEFAULT_OFF
depends on PSA_WANT_ALG_RSA_PKCS1V15_CRYPT

config PSA_CRYPTO_DRIVER_ALG_RSA_PKCS1V15_SIGN_CC3XX
bool
prompt "PSA RSA signature support (PKCS1V15 mode) - cc3xx" if !PSA_PROMPTLESS
prompt "PSA RSA signature support (PKCS#1 v1.5 mode) - cc3xx" if !PSA_PROMPTLESS
default y if !PSA_DEFAULT_OFF
depends on PSA_WANT_ALG_RSA_PKCS1V15_SIGN

Expand Down
4 changes: 2 additions & 2 deletions subsys/nrf_security/src/drivers/nrf_oberon/Kconfig
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -218,13 +218,13 @@ config PSA_CRYPTO_DRIVER_ALG_RSA_OAEP_OBERON

config PSA_CRYPTO_DRIVER_ALG_RSA_PKCS1V15_CRYPT_OBERON
bool
prompt "PSA RSA crypt support (PKCS1V15 mode) - oberon" if !PSA_PROMPTLESS
prompt "PSA RSA crypt support (PKCS#1 v1.5 mode) - oberon" if !PSA_PROMPTLESS
default y if !PSA_DEFAULT_OFF
depends on PSA_WANT_ALG_RSA_PKCS1V15_CRYPT

config PSA_CRYPTO_DRIVER_ALG_RSA_PKCS1V15_SIGN_OBERON
bool
prompt "PSA RSA signature support (PKCS1V15 mode) - oberon" if !PSA_PROMPTLESS
prompt "PSA RSA signature support (PKCS#1 v1.5 mode) - oberon" if !PSA_PROMPTLESS
default y if !PSA_DEFAULT_OFF
depends on PSA_WANT_ALG_RSA_PKCS1V15_SIGN

Expand Down
4 changes: 2 additions & 2 deletions west.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -59,7 +59,7 @@ manifest:
# https://developer.nordicsemi.com/nRF_Connect_SDK/doc/latest/zephyr/guides/modules.html
- name: zephyr
repo-path: sdk-zephyr
revision: 52222dc79450304fe4a32e5e0e77b9a460a93a86
revision: 01e2e4c9ce8294d74032a2d33e0dcb1b74802568
import:
# In addition to the zephyr repository itself, NCS also
# imports the contents of zephyr/west.yml at the above
Expand Down Expand Up @@ -140,7 +140,7 @@ manifest:
- name: nrfxlib
repo-path: sdk-nrfxlib
path: nrfxlib
revision: dc8c95a8f5e7b7fe102632172b923849b17f0a33
revision: 4eca399cc6e8a095f320aafdd272606ee1294a13
- name: trusted-firmware-m
repo-path: sdk-trusted-firmware-m
path: modules/tee/tf-m/trusted-firmware-m
Expand Down