File: formatsecret.html.in

package info (click to toggle)
libvirt 5.6.0-2
  • links: PTS, VCS
  • area: main
  • in suites: bullseye
  • size: 240,844 kB
  • sloc: ansic: 584,521; xml: 176,725; sh: 9,912; python: 4,731; perl: 4,343; makefile: 3,321; ml: 465
file content (387 lines) | stat: -rw-r--r-- 13,844 bytes parent folder | download | duplicates (2)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">
  <body>
    <h1>Secret XML format</h1>

    <ul id="toc"></ul>

    <h2><a id="SecretAttributes">Secret XML</a></h2>

    <p>
      Secrets stored by libvirt may have attributes associated with them, using
      the <code>secret</code> element.  The <code>secret</code> element has two
      optional attributes, each with values '<code>yes</code>' and
      '<code>no</code>', and defaulting to '<code>no</code>':
    </p>
    <dl>
      <dt><code>ephemeral</code></dt>
      <dd>This secret must only be kept in memory, never stored persistently.
      </dd>
      <dt><code>private</code></dt>
      <dd>The value of the secret must not be revealed to any caller of libvirt,
        nor to any other node.
      </dd>
    </dl>
    <p>
      The top-level <code>secret</code> element may contain the following
      elements:
    </p>
    <dl>
      <dt><code>uuid</code></dt>
      <dd>
        An unique identifier for this secret (not necessarily in the UUID
        format).  If omitted when defining a new secret, a random UUID is
        generated.
      </dd>
      <dt><code>description</code></dt>
      <dd>A human-readable description of the purpose of the secret.
      </dd>
      <dt><code>usage</code></dt>
      <dd>
        Specifies what this secret is used for.  A mandatory
        <code>type</code> attribute specifies the usage category, currently
        only <code>volume</code>, <code>ceph</code>, <code>iscsi</code>,
        <code>tls</code>, and <code>vtpm</code> are defined. Specific usage
        categories are described below.
      </dd>
    </dl>

    <h3><a id="VolumeUsageType">Usage type "volume"</a></h3>

    <p>
      This secret is associated with a volume, whether the format is either
      for a "luks" encrypted volume. Each volume will have a
      unique secret associated with it and it is safe to delete the
      secret after the volume is deleted. The
      <code>&lt;usage type='volume'&gt;</code> element must contain a
      single <code>volume</code> element that specifies the path of the volume
      this secret is associated with. For example, create a volume-secret.xml
      file as follows:
    </p>

    <pre>
&lt;secret ephemeral='no' private='yes'&gt;
   &lt;description&gt;Super secret name of my first puppy&lt;/description&gt;
   &lt;uuid&gt;0a81f5b2-8403-7b23-c8d6-21ccc2f80d6f&lt;/uuid&gt;
   &lt;usage type='volume'&gt;
      &lt;volume&gt;/var/lib/libvirt/images/puppyname.img&lt;/volume&gt;
   &lt;/usage&gt;
&lt;/secret&gt;
    </pre>

    <p>
      Define the secret and set the passphrase as follows:
    </p>
    <pre>
# virsh secret-define volume-secret.xml
Secret 0a81f5b2-8403-7b23-c8d6-21ccc2f80d6f created
#
# MYSECRET=`printf %s "open sesame" | base64`
# virsh secret-set-value 0a81f5b2-8403-7b23-c8d6-21ccc2f80d6f $MYSECRET
Secret value set
#
    </pre>

    <p>
      The volume type secret can be supplied either in volume XML during
      creation of a <a href="formatstorage.html#StorageVol">storage volume</a>
      in order to provide the passphrase to encrypt the volume or in
      domain XML <a href="formatdomain.html#elementsDisks">disk device</a>
      in order to provide the passphrase to decrypt the volume,
      <span class="since">since 2.1.0</span>. An example follows:
    </p>
    <pre>
# cat luks-secret.xml
&lt;secret ephemeral='no' private='yes'&gt;
   &lt;description&gt;LUKS Sample Secret&lt;/description&gt;
   &lt;uuid&gt;f52a81b2-424e-490c-823d-6bd4235bc57&lt;/uuid&gt;
   &lt;usage type='volume'&gt;
      &lt;volume&gt;/var/lib/libvirt/images/luks-sample.img&lt;/volume&gt;
   &lt;/usage&gt;
&lt;/secret&gt;

# virsh secret-define luks-secret.xml
Secret f52a81b2-424e-490c-823d-6bd4235bc57 created
#
# MYSECRET=`printf %s "letmein" | base64`
# virsh secret-set-value f52a81b2-424e-490c-823d-6bd4235bc57 $MYSECRET
Secret value set
#
    </pre>

    <p>
      The volume type secret can be supplied in domain XML for a luks storage
      volume <a href="formatstorageencryption.html">encryption</a> as follows:
    </p>
    <pre>
&lt;encryption format='luks'&gt;
  &lt;secret type='passphrase' uuid='f52a81b2-424e-490c-823d-6bd4235bc57'/&gt;
&lt;/encryption&gt;
    </pre>

    <h3><a id="CephUsageType">Usage type "ceph"</a></h3>
    <p>
      This secret is associated with a Ceph RBD (rados block device).
      The <code>&lt;usage type='ceph'&gt;</code> element must contain
      a single <code>name</code> element that specifies a usage name
      for the secret.  The Ceph secret can then be used by UUID or by
      this usage name via the <code>&lt;auth&gt;</code> element of
      a <a href="formatdomain.html#elementsDisks">disk device</a> or
      a <a href="formatstorage.html">storage pool (rbd)</a>.
      <span class="since">Since 0.9.7</span>. The following is an example
      of the steps to be taken.  First create a ceph-secret.xml file:
    </p>

    <pre>
&lt;secret ephemeral='no' private='yes'&gt;
   &lt;description&gt;CEPH passphrase example&lt;/description&gt;
   &lt;usage type='ceph'&gt;
      &lt;name&gt;ceph_example&lt;/name&gt;
   &lt;/usage&gt;
&lt;/secret&gt;
    </pre>

    <p>
      Next, use <code>virsh secret-define ceph-secret.xml</code> to define
      the secret and <code>virsh secret-set-value</code> using the generated
      UUID value and a base64 generated secret value in order to define the
      chosen secret pass phrase.
    </p>
    <pre>
# virsh secret-define ceph-secret.xml
Secret 1b40a534-8301-45d5-b1aa-11894ebb1735 created
#
# virsh secret-list
 UUID                                 Usage
-----------------------------------------------------------
 1b40a534-8301-45d5-b1aa-11894ebb1735 cephx ceph_example
#
# CEPHPHRASE=`printf %s "pass phrase" | base64`
# virsh secret-set-value 1b40a534-8301-45d5-b1aa-11894ebb1735 $CEPHPHRASE
Secret value set

#
    </pre>

    <p>
      The ceph secret can then be used by UUID or by the
      usage name via the <code>&lt;auth&gt;</code> element in a domain's
      <a href="formatdomain.html#elementsDisks"><code>&lt;disk&gt;</code></a>
      element as follows:
    </p>
    <pre>
&lt;auth username='myname'&gt;
  &lt;secret type='ceph' usage='ceph_example'/&gt;
&lt;/auth&gt;
    </pre>

    <p>
      As well as the <code>&lt;auth&gt;</code> element in a
      <a href="formatstorage.html">storage pool (rbd)</a>
      <code>&lt;source&gt;</code> element as follows:
    </p>
    <pre>
&lt;auth type='ceph' username='myname'&gt;
  &lt;secret usage='ceph_example'/&gt;
&lt;/auth&gt;
    </pre>

    <h3><a id="iSCSIUsageType">Usage type "iscsi"</a></h3>

    <p>
      This secret is associated with an iSCSI target for CHAP authentication.
      The <code>&lt;usage type='iscsi'&gt;</code> element must contain
      a single <code>target</code> element that specifies a usage name
      for the secret. The iSCSI secret can then be used by UUID or by
      this usage name via the <code>&lt;auth&gt;</code> element of
      a <a href="formatdomain.html#elementsDisks">disk device</a> or
      a <a href="formatstorage.html">storage pool (iscsi)</a>.
      <span class="since">Since 1.0.4</span>. The following is an example
      of the XML that may be used to generate a secret for iSCSI CHAP
      authentication. Assume the following sample entry in an iSCSI
      authentication file:
    </p>
      <pre>
&lt;target iqn.2013-07.com.example:iscsi-pool&gt;
backing-store /home/tgtd/iscsi-pool/disk1
backing-store /home/tgtd/iscsi-pool/disk2
incominguser myname mysecret
&lt;/target&gt;
      </pre>
    <p>
      Define an iscsi-secret.xml file to describe the secret. Use the
      <code>incominguser</code> username used in your iSCSI authentication
      configuration file as the value for the <code>username</code> attribute.
      The <code>description</code> attribute should contain configuration
      specific data. The <code>target</code> name may be any name of your
      choosing to be used as the <code>usage</code> when used in the pool
      or disk XML description.
    </p>
    <pre>
&lt;secret ephemeral='no' private='yes'&gt;
   &lt;description&gt;Passphrase for the iSCSI example.com server&lt;/description&gt;
   &lt;usage type='iscsi'&gt;
      &lt;target&gt;libvirtiscsi&lt;/target&gt;
   &lt;/usage&gt;
&lt;/secret&gt;
    </pre>

    <p>
      Next, use <code>virsh secret-define iscsi-secret.xml</code> to define
      the secret and <code>virsh secret-set-value</code> using the generated
      UUID value and a base64 generated secret value in order to define the
      chosen secret pass phrase.  The pass phrase must match the password
      used in the iSCSI authentication configuration file.
    </p>
    <pre>
# virsh secret-define secret.xml
Secret c4dbe20b-b1a3-4ac1-b6e6-2ac97852ebb6 created

# virsh secret-list
 UUID                                 Usage
-----------------------------------------------------------
 c4dbe20b-b1a3-4ac1-b6e6-2ac97852ebb6 iscsi libvirtiscsi

# MYSECRET=`printf %s "mysecret" | base64`
# virsh secret-set-value c4dbe20b-b1a3-4ac1-b6e6-2ac97852ebb6 $MYSECRET
Secret value set
#
    </pre>

    <p>
      The iSCSI secret can then be used by UUID or by the
      usage name via the <code>&lt;auth&gt;</code> element in a domain's
      <a href="formatdomain.html#elementsDisks"><code>&lt;disk&gt;</code></a>
      element as follows:
    </p>
    <pre>
&lt;auth username='myname'&gt;
  &lt;secret type='iscsi' usage='libvirtiscsi'/&gt;
&lt;/auth&gt;
    </pre>

    <p>
      As well as the <code>&lt;auth&gt;</code> element in a
      <a href="formatstorage.html">storage pool (iscsi)</a>
      <code>&lt;source&gt;</code> element as follows:
    </p>
    <pre>
&lt;auth type='chap' username='myname'&gt;
  &lt;secret usage='libvirtiscsi'/&gt;
&lt;/auth&gt;
    </pre>

    <h3><a id="tlsUsageType">Usage type "tls"</a></h3>

    <p>
      This secret may be used in order to provide the passphrase for the
      private key used to provide TLS credentials.
      The <code>&lt;usage type='tls'&gt;</code> element must contain a
      single <code>name</code> element that specifies a usage name
      for the secret.
      <span class="since">Since 2.3.0</span>.
      The following is an example of the expected XML and processing to
      define the secret:
    </p>

    <pre>
# cat tls-secret.xml
&lt;secret ephemeral='no' private='yes'&gt;
   &lt;description&gt;sample tls secret&lt;/description&gt;
   &lt;usage type='tls'&gt;
      &lt;name&gt;TLS_example&lt;/name&gt;
   &lt;/usage&gt;
&lt;/secret&gt;

# virsh secret-define tls-secret.xml
Secret 718c71bd-67b5-4a2b-87ec-a24e8ca200dc created

# virsh secret-list
 UUID                                 Usage
-----------------------------------------------------------
 718c71bd-67b5-4a2b-87ec-a24e8ca200dc  tls TLS_example
#

    </pre>

    <p>
      A secret may also be defined via the
      <a href="html/libvirt-libvirt-secret.html#virSecretDefineXML">
       <code>virSecretDefineXML</code></a> API.

      Once the secret is defined, a secret value will need to be set. The
      secret would be the passphrase used to access the TLS credentials.
      The following is a simple example of using
      <code>virsh secret-set-value</code> to set the secret value. The
      <a href="html/libvirt-libvirt-secret.html#virSecretSetValue">
      <code>virSecretSetValue</code></a> API may also be used to set
      a more secure secret without using printable/readable characters.
    </p>

    <pre>
# MYSECRET=`printf %s "letmein" | base64`
# virsh secret-set-value 718c71bd-67b5-4a2b-87ec-a24e8ca200dc $MYSECRET
Secret value set

    </pre>

    <h3><a id="vTPMUsageType">Usage type "vtpm"</a></h3>

    <p>
      This secret is associated with a virtualized TPM (vTPM) and serves
      as a passphrase for deriving a key from for encrypting the state
      of the vTPM.
      The <code>&lt;usage type='vtpm'&gt;</code> element must contain
      a single <code>name</code> element that specifies a usage name
      for the secret.  The vTPM secret can then be used by UUID or by
      this usage name via the <code>&lt;encryption&gt;</code> element of
      a <a href="formatdomain.html#elementsTpm">tpm</a> when using an
      emulator.
      <span class="since">Since 5.6.0</span>. The following is an example
      of the steps to be taken.  First create a vtpm-secret.xml file:    </p>

    <pre>
# cat vtpm-secret.xml
&lt;secret ephemeral='no' private='yes'&gt;
   &lt;description&gt;sample vTPM secret&lt;/description&gt;
   &lt;usage type='vtpm'&gt;
      &lt;name&gt;VTPM_example&lt;/name&gt;
   &lt;/usage&gt;
&lt;/secret&gt;

# virsh secret-define vtpm-secret.xml
Secret 6dd3e4a5-1d76-44ce-961f-f119f5aad935 created

# virsh secret-list
 UUID                                   Usage
----------------------------------------------------------------------------------------
 6dd3e4a5-1d76-44ce-961f-f119f5aad935   vtpm VTPM_example

#

    </pre>

    <p>
      A secret may also be defined via the
      <a href="html/libvirt-libvirt-secret.html#virSecretDefineXML">
       <code>virSecretDefineXML</code></a> API.

      Once the secret is defined, a secret value will need to be set. The
      secret would be the passphrase used to decrypt the vTPM state.
      The following is a simple example of using
      <code>virsh secret-set-value</code> to set the secret value. The
      <a href="html/libvirt-libvirt-secret.html#virSecretSetValue">
      <code>virSecretSetValue</code></a> API may also be used to set
      a more secure secret without using printable/readable characters.
    </p>

    <pre>
# MYSECRET=`printf %s "open sesame" | base64`
# virsh secret-set-value 6dd3e4a5-1d76-44ce-961f-f119f5aad935 $MYSECRET
Secret value set

    </pre>

  </body>
</html>