1.. _tls_credentials_shell:
2
3TLS Credentials Shell
4#####################
5
6The TLS Credentials shell provides a command-line interface for managing installed TLS credentials.
7
8Commands
9********
10
11.. _tls_credentials_shell_buf_cred:
12
13Buffer Credential (``buf``)
14===========================
15
16Buffer data incrementally into the credential buffer so that it can be added using the :ref:`tls_credentials_shell_add_cred` command.
17
18Alternatively:
19
20   - Clear the credential buffer.
21
22   - Load credential directly to the credential buffer, ending with ``Ctrl + c``.
23
24Usage
25-----
26
27To append ``<DATA>`` to the credential buffer, use:
28
29.. code-block:: shell
30
31   cred buf <DATA>
32
33Use 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.
34
35To load ``<DATA>`` directly to the credential buffer, use:
36
37.. code-block:: shell
38
39   cred buf load
40   <DATA>
41   Ctrl + c
42
43To clear the credential buffer, use:
44
45.. code-block:: shell
46
47   cred buf clear
48
49Arguments
50---------
51
52.. csv-table::
53   :header: "Argument", "Description"
54   :widths: 15 85
55
56   "``<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."
57
58.. _tls_credentials_shell_add_cred:
59
60Add Credential (``add``)
61=========================
62
63Add a TLS credential to the TLS Credential store.
64
65Credential contents can be provided in-line with the call to ``cred add``, or will otherwise be sourced from the credential buffer.
66
67Usage
68-----
69
70To add a TLS credential using the data from the credential buffer, use:
71
72.. code-block:: shell
73
74   cred add <SECTAG> <TYPE> <BACKEND> <FORMAT>
75
76To add a TLS credential using data provided with the same command, use:
77
78.. code-block:: shell
79
80   cred add <SECTAG> <TYPE> <BACKEND> <FORMAT> <DATA>
81
82
83Arguments
84---------
85
86.. csv-table::
87   :header: "Argument", "Description"
88   :widths: 15 85
89
90   "``<SECTAG>``", "The sectag to use for the new credential. Can be any non-negative integer."
91   "``<TYPE>``", "The type of credential to add. See :ref:`tls_credentials_shell_cred_types` for valid values."
92   "``<BACKEND>``", "Reserved. Must always be ``DEFAULT`` (case-insensitive)."
93   "``<FORMAT>``", "Specifies the storage format of the provided credential. See :ref:`tls_credentials_shell_data_formats` for valid values."
94   "``<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."
95
96.. _tls_credentials_shell_del_cred:
97
98Delete Credential (``del``)
99===========================
100
101Delete a specified credential from the credential store.
102
103Usage
104-----
105
106To delete a credential matching a specified sectag and credential type (if it exists), use:
107
108.. code-block:: shell
109
110   cred del <SECTAG> <TYPE>
111
112Arguments
113---------
114
115.. csv-table::
116   :header: "Argument", "Description"
117   :widths: 15 85
118
119   "``<SECTAG>``", "The sectag of the credential to delete. Can be any non-negative integer."
120   "``<TYPE>``", "The type of credential to delete. See :ref:`tls_credentials_shell_cred_types` for valid values."
121
122.. _tls_credentials_shell_get_cred:
123
124Get Credential Contents (``get``)
125=================================
126
127Retrieve and print the contents of a specified credential.
128
129Usage
130-----
131
132To retrieve and print a credential matching a specified sectag and credential type (if it exists), use:
133
134.. code-block:: shell
135
136   cred get <SECTAG> <TYPE> <FORMAT>
137
138Arguments
139---------
140
141.. csv-table::
142   :header: "Argument", "Description"
143   :widths: 15 85
144
145   "``<SECTAG>``", "The sectag of the credential to get. Can be any non-negative integer."
146   "``<TYPE>``", "The type of credential to get. See :ref:`tls_credentials_shell_cred_types` for valid values."
147   "``<FORMAT>``", "Specifies the retrieval format for the provided credential. See :ref:`tls_credentials_shell_data_formats` for valid values."
148
149.. _tls_credentials_shell_list_cred:
150
151List Credentials (``list``)
152===========================
153
154List TLS credentials in the credential store.
155
156Usage
157-----
158
159To list all available credentials, use:
160
161.. code-block:: shell
162
163   cred list
164
165To list all credentials with a specified sectag, use:
166
167.. code-block:: shell
168
169   cred list <SECTAG>
170
171To list all credentials with a specified credential type, use:
172
173.. code-block:: shell
174
175   cred list any <TYPE>
176
177To list all credentials with a specified credential type and sectag, use:
178
179.. code-block:: shell
180
181   cred list <SECTAG> <TYPE>
182
183
184Arguments
185---------
186
187.. csv-table::
188   :header: "Argument", "Description"
189   :widths: 15 85
190
191   "``<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."
192   "``<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."
193
194
195Output
196------
197
198The command outputs all matching credentials in the following (CSV-compliant) format:
199
200.. code-block:: shell
201
202   <SECTAG>,<TYPE>,<DIGEST>,<STATUS>
203
204Where:
205
206.. csv-table::
207   :header: "Symbol", "Value"
208   :widths: 15 85
209
210   "``<SECTAG>``", "The sectag of the listed credential. A non-negative integer."
211   "``<TYPE>``", "Credential type short-code (see :ref:`tls_credentials_shell_cred_types` for details) of the listed credential."
212   "``<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)."
213   "``<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."
214
215After the list is printed, a final summary of the found credentials will be printed in the form:
216
217.. code-block:: shell
218
219   <N> credentials found.
220
221Where ``<N>`` is the number of credentials found, and is zero if none are found.
222
223.. _tls_credentials_shell_cred_types:
224
225Credential Types
226****************
227
228The following keywords (case-insensitive) may be used to specify a credential type:
229
230.. csv-table::
231   :header: "Keyword(s)", "Meaning"
232   :widths: 15 85
233
234   "``CA_CERT``, ``CA``", "A trusted CA certificate."
235   "``SERVER_CERT``, ``SELF_CERT``, ``CLIENT_CERT``, ``CLIENT``, ``SELF``, ``SERV``", "Self or server certificate."
236   "``PRIVATE_KEY``, ``PK``", "A private key."
237   "``PRE_SHARED_KEY``, ``PSK``", "A pre-shared key."
238   "``PRE_SHARED_KEY_ID``, ``PSK_ID``", "ID for pre-shared key."
239
240.. _tls_credentials_shell_data_formats:
241
242Storage/Retrieval Formats
243*************************
244
245The :ref:`tls_credentials <sockets_tls_credentials_subsys>` module treats stored credentials as arbitrary binary buffers.
246
247For convenience, the TLS credentials shell offers four formats for providing and later retrieving these buffers using the shell.
248
249These formats and their (case-insensitive) keywords are as follows:
250
251.. csv-table::
252   :header: "Keyword", "Meaning", "Behavior during storage (``cred add``)", "Behavior during retrieval (``cred get``)"
253   :widths: 3, 32, 34, 34
254
255   "``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."
256   "``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."
257   "``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 ``?``"
258   "``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 ``?``"
259
260The ``BIN`` format can be used to install credentials of any type, since base64 can be used to encode any concievable binary buffer.
261The remaining three formats are provided for convenience in special use-cases.
262
263For example:
264
265- To install printable pre-shared-keys, use ``STR`` to enter the PSK without first encoding it.
266  This ensures it is stored without a NULL terminator.
267- 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.
268- 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.
269  This is required because Zephyr does not support multi-line strings in the shell.
270  Otherwise, the ``STRT`` format could be used for this purpose without base64 encoding.
271  It is possible to use ``BIN`` instead if you manually encode a NULL terminator into the base64.
272