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 <[email protected]>

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,259 @@
+.. _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 del <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 (if 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``, ``CLIENT_CERT``, ``CLIENT``, ``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 :ref:`tls_credentials <sockets_tls_credentials_subsys>` module treats stored credentials as arbitrary binary buffers.
+
+For convenience, the TLS credentials shell offers four formats for providing and later retrieving these buffers using the shell.
+
+These formats and their (case-insensitive) keywords are as follows:
+
+.. csv-table::
+   :header: "Keyword", "Meaning", "Behavior during storage (``cred add``)", "Behavior during retrieval (``cred get``)"
+   :widths: 3, 32, 34, 34
+
+   "``BIN``", "Credential is handled by shell as base64 and stored without NULL termination.", "Data entered into shell 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 handled by shell as base64 and stored with NULL termination.", "Data entered into shell 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 handled by shell as literal string and stored without NULL termination.", "Text data entered into shell 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 handled by shell as literal string and stored with NULL-termination.", "Text data entered into shell will be passed into storage as-written, with a NULL terminator.", "NULL terminator will be truncated from stored data before said data is printed as text. Non-printable characters will be printed as ``?``"
+
+The ``BIN`` format can be used to install credentials of any type, since base64 can be used to encode any concievable binary buffer.
+The remaining three formats are provided for convenience in special use-cases.
+
+For example:
+
+- To install printable pre-shared-keys, use ``STR`` to enter the PSK without first encoding it.
+  This ensures it is stored without a NULL terminator.
+- To install DER-formatted X.509 certificates (or other raw-binary credentials, such as non-printable PSKs) base64-encode the binary and use the ``BIN`` format.
+- To install PEM-formatted X.509 certificates or certificate chains, base64 encode the full PEM string (including new-lines and ``----BEGIN X ----`` / ``----END X----`` markers), and then use the ``BINT`` format to make sure the stored string is NULL-terminated.
+  This is required because Zephyr does not support multi-line strings in the shell.
+  Otherwise, the ``STRT`` format could be used for this purpose without base64 encoding.
+  It is possible to use ``BIN`` instead if you manually encode a NULL terminator into the base64.

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_SHELL