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