net: tls_credetials: Add TLS Credentials shell

Adds a shell interface for TLS Credentials, allowing management of
credentials via the Zephyr shell

Signed-off-by: Georges Oates_Larsen <georges.larsen@nordicsemi.no>

doc/connectivity/networking/api/system_mgmt.rst

@@ -18,3 +18,4 @@ Network System Management
    traffic-class.rst
    net_pkt_filter.rst
    net_shell.rst
+   tls_credentials_shell.rst

doc/connectivity/networking/api/tls_credentials_shell.rst

@@ -0,0 +1,243 @@
+.. _tls_credentials_shell:
+
+TLS Credentials Shell
+#####################
+
+The TLS Credentials shell provides a command-line interface for managing installed TLS credentials.
+
+Commands
+********
+
+.. _tls_credentials_shell_buf_cred:
+
+Buffer Credential (``buf``)
+===========================
+
+Buffer data incrementaly into the credential buffer so that it can be added using the :ref:`tls_credentials_shell_add_cred` command.
+
+Alternatively, clear the credential buffer.
+
+Usage
+-----
+
+To append ``<DATA>`` to the credential buffer, use:
+
+.. code-block:: shell
+
+   cred buf <DATA>
+
+Use this as many times as needed to load the full credential into the credential buffer, then use the :ref:`tls_credentials_shell_add_cred` command to store it.
+
+To clear the credential buffer, use:
+
+.. code-block:: shell
+
+   cred buf clear
+
+Arguments
+---------
+
+.. csv-table::
+   :header: "Argument", "Description"
+   :widths: 15 85
+
+   "``<DATA>``", "Text data to be appended to credential buffer. It can be either text, or base64-encoded binary. See :ref:`tls_credentials_shell_add_cred` and :ref:`tls_credentials_shell_data_formats` for details."
+
+.. _tls_credentials_shell_add_cred:
+
+Add Credential (``add``)
+=========================
+
+Add a TLS credential to the TLS Credential store.
+
+Credential contents can be provided in-line with the call to ``cred add``, or will otherwise be sourced from the credential buffer.
+
+Usage
+-----
+
+To add a TLS credential using the data from the credential buffer, use:
+
+.. code-block:: shell
+
+   cred add <SECTAG> <TYPE> <BACKEND> <FORMAT>
+
+To add a TLS credential using data provided with the same command, use:
+
+.. code-block:: shell
+
+   cred add <SECTAG> <TYPE> <BACKEND> <FORMAT> <DATA>
+
+
+Arguments
+---------
+
+.. csv-table::
+   :header: "Argument", "Description"
+   :widths: 15 85
+
+   "``<SECTAG>``", "The sectag to use for the new credential. Can be any non-negative integer."
+   "``<TYPE>``", "The type of credential to add. See :ref:`tls_credentials_shell_cred_types` for valid values."
+   "``<BACKEND>``", "Reserved. Must always be ``DEFAULT`` (case-insensitive)."
+   "``<FORMAT>``", "Specifies the storage format of the provided credential. See :ref:`tls_credentials_shell_data_formats` for valid values."
+   "``<DATA>``", "If provided, this argument will be used as the credential data, instead of any data in the credential buffer. Can be either text, or base64-encoded binary."
+
+.. _tls_credentials_shell_del_cred:
+
+Delete Credential (``del``)
+===========================
+
+Delete a specified credential from the credential store.
+
+Usage
+-----
+
+To delete a credential matching a specified sectag and credential type (if it exists), use:
+
+.. code-block:: shell
+
+   cred add <SECTAG> <TYPE>
+
+Arguments
+---------
+
+.. csv-table::
+   :header: "Argument", "Description"
+   :widths: 15 85
+
+   "``<SECTAG>``", "The sectag of the credential to delete. Can be any non-negative integer."
+   "``<TYPE>``", "The type of credential to delete. See :ref:`tls_credentials_shell_cred_types` for valid values."
+
+.. _tls_credentials_shell_get_cred:
+
+Get Credential Contents (``get``)
+=================================
+
+Retrieve and print the contents of a specified credential.
+
+Usage
+-----
+
+To retrieve and print a credential matching a specified sectag and credential type (of it exists), use:
+
+.. code-block:: shell
+
+   cred get <SECTAG> <TYPE> <FORMAT>
+
+Arguments
+---------
+
+.. csv-table::
+   :header: "Argument", "Description"
+   :widths: 15 85
+
+   "``<SECTAG>``", "The sectag of the credential to get. Can be any non-negative integer."
+   "``<TYPE>``", "The type of credential to get. See :ref:`tls_credentials_shell_cred_types` for valid values."
+   "``<FORMAT>``", "Specifies the retrieval format for the provided credential. See :ref:`tls_credentials_shell_data_formats` for valid values."
+
+.. _tls_credentials_shell_list_cred:
+
+List Credentials (``list``)
+===========================
+
+List TLS credentials in the credential store.
+
+Usage
+-----
+
+To list all available credentials, use:
+
+.. code-block:: shell
+
+   cred list
+
+To list all credentials with a specified sectag, use:
+
+.. code-block:: shell
+
+   cred list <SECTAG>
+
+To list all credentials with a specified credential type, use:
+
+.. code-block:: shell
+
+   cred list any <TYPE>
+
+To list all credentials with a specified credential type and sectag, use:
+
+.. code-block:: shell
+
+   cred list <SECTAG> <TYPE>
+
+
+Arguments
+---------
+
+.. csv-table::
+   :header: "Argument", "Description"
+   :widths: 15 85
+
+   "``<SECTAG>``", "Optional. If provided, only list credentials with this sectag. Pass ``any`` or omit to allow any sectag. Otherwise, can be any non-negative integer."
+   "``<TYPE>``", "Optional. If provided, only list credentials with this credential type. Pass ``any`` or omit to allow any credential type. Otherwise, see :ref:`tls_credentials_shell_cred_types` for valid values."
+
+
+Output
+------
+
+The command outputs all matching credentials in the following (CSV-compliant) format:
+
+.. code-block:: shell
+
+   <SECTAG>,<TYPE>,<DIGEST>,<STATUS>
+
+Where:
+
+.. csv-table::
+   :header: "Symbol", "Value"
+   :widths: 15 85
+
+   "``<SECTAG>``", "The sectag of the listed credential. A non-negative integer."
+   "``<TYPE>``", "Credential type short-code (see :ref:`tls_credentials_shell_cred_types` for details) of the listed credential."
+   "``<DIGEST>``", "A string digest representing the credential contents. The exact nature of this digest may vary depending on credentials storage backend, but currently for all backends this is a base64 encoded SHA256 hash of the raw credential contents (so different storage formats for essentially identical credentials will have different digests)."
+   "``<STATUS>``", "Status code indicating success or failure with generating a digest of the listed credential. 0 if successful, negative error code specific to the storage backend otherwise. Lines for which status is not zero will be printed with error formatting."
+
+After the list is printed, a final summary of the found credentials will be printed in the form:
+
+.. code-block:: shell
+
+   <N> credentials found.
+
+Where `<N>` is the number of credentials found, and is zero if none are found.
+
+.. _tls_credentials_shell_cred_types:
+
+Credential Types
+****************
+
+The following keywords (case-insensitive) may be used to specify a credential type:
+
+.. csv-table::
+   :header: "Keyword(s)", "Meaning"
+   :widths: 15 85
+
+   "``CA_CERT``, ``CA``", "A trusted CA certificate."
+   "``SERVER_CERT``, ``SELF_CERT``, ``SELF``, ``SERV``", "Self or server certificate."
+   "``PRIVATE_KEY``, ``PK``", "A private key."
+   "``PRE_SHARED_KEY``, ``PSK``", "A pre-shared key."
+   "``PRE_SHARED_KEY_ID``, ``PSK_ID``", "ID for pre-shared key."
+
+.. _tls_credentials_shell_data_formats:
+
+Storage/Retrieval Formats
+*************************
+
+The following keywords (case-insensitive) specify how credential data is stored and retrieved.
+
+
+.. csv-table::
+   :header: "Keyword", "Meaning", "Behavior during storage (``cred add``)", "Behavior during retrieval (``cred get``)"
+   :widths: 3, 15, 41, 41
+
+   "``BIN``", "Credential is treated as non-terminated base64.", "Provided data will be decoded from base64 into raw binary before storage. No terminator will be appended.", "Stored data will be encoded into base64 before being printed."
+   "``BINT``", "Credential is treated as NULL-terminated base64.", "Provided data will be decoded from base64 into raw binary and a NULL terminator will be appended before storage.", "NULL terminator will be truncated from stored data before said data is encoded into base64 and then printed."
+   "``STR``", "Credential is treated as non-terminated string.", "Provided text data will be passed into storage as-written, without a NULL terminator.", "Stored data will be printed as text. Non-printable characters will be printed as ``?``"
+   "``STRT``", "Credential is treated as NULL-terminated string.", "Provided text data will be passed into storage as-written, including NULL terminator.", "NULL terminator will be truncated from stored data before said data is printed as text. Non-printable characters will be printed as ``?``"

subsys/net/lib/tls_credentials/CMakeLists.txt

@@ -10,3 +10,6 @@ zephyr_sources_ifdef(CONFIG_TLS_CREDENTIALS_BACKEND_PROTECTED_STORAGE
   tls_credentials_trusted.c
   tls_credentials_digest_raw.c
 )
+zephyr_sources_ifdef(CONFIG_TLS_CREDENTIALS_SHELL
+  tls_credentials_shell.c
+)

subsys/net/lib/tls_credentials/Kconfig

@@ -54,4 +54,6 @@ config TLS_CREDENTIAL_FILENAMES
 	  This option is currently only available for secure
 	  socket offload devices.
 
+source "subsys/net/lib/tls_credentials/Kconfig.shell"
+
 endif # TLS_CREDENTIALS

subsys/net/lib/tls_credentials/Kconfig.shell

@@ -0,0 +1,35 @@
+# Copyright (c) 2023 Nordic Semiconductor ASA
+# SPDX-License-Identifier: Apache-2.0
+
+menuconfig TLS_CREDENTIALS_SHELL
+	bool "TLS credentials management shell"
+	depends on TLS_CREDENTIALS
+	depends on SHELL
+	depends on BASE64
+	help
+	  Enable shell commands to manage TLS credentials.
+
+if TLS_CREDENTIALS_SHELL
+
+config TLS_CREDENTIALS_SHELL_CRED_BUF_SIZE
+	int "Size of buffer used for storing and retrieving credentials, measured in bytes."
+	default 1024
+	help
+	  The amount of preallocated buffer (in bytes) used for storing and retrieving credentials.
+
+config TLS_CREDENTIALS_SHELL_CRED_OUTPUT_WIDTH
+	int "Credential output line width (characters)"
+	default 32
+	help
+	   This setting specifies how long (in characters) contiguous lines of base64 credential
+	   output should be. Must be a multiple of 4. Applies only to ??? mode.
+
+config TLS_CREDENTIALS_SHELL_DIGEST_BUF_SIZE
+	int "Buffer for generating credentials digests"
+	default 48
+	help
+	   The amount of preallocated buffer (in bytes) for temporarily storing credential digests.
+
+	   Also used to print error messages if digest generation fails.
+
+endif # TLS_CREDENTIALS