| blob | 7116ae9a46a767e5727c458b330c9c2edeca2aaf |
1 # -*- Mode: Python -*-
2 # vim: filetype=python
3 #
5 ##
6 # = Cryptography
7 ##
9 ##
10 # @QCryptoTLSCredsEndpoint:
11 #
12 # The type of network endpoint that will be using the credentials.
13 # Most types of credential require different setup / structures
14 # depending on whether they will be used in a server versus a
15 # client.
16 #
17 # @client: the network endpoint is acting as the client
18 #
19 # @server: the network endpoint is acting as the server
20 #
21 # Since: 2.5
22 ##
23 { 'enum': 'QCryptoTLSCredsEndpoint',
24 'prefix': 'QCRYPTO_TLS_CREDS_ENDPOINT',
25 'data': ['client', 'server']}
28 ##
29 # @QCryptoSecretFormat:
30 #
31 # The data format that the secret is provided in
32 #
33 # @raw: raw bytes. When encoded in JSON only valid UTF-8 sequences can be used
34 # @base64: arbitrary base64 encoded binary data
35 # Since: 2.6
36 ##
37 { 'enum': 'QCryptoSecretFormat',
38 'prefix': 'QCRYPTO_SECRET_FORMAT',
39 'data': ['raw', 'base64']}
42 ##
43 # @QCryptoHashAlgorithm:
44 #
45 # The supported algorithms for computing content digests
46 #
47 # @md5: MD5. Should not be used in any new code, legacy compat only
48 # @sha1: SHA-1. Should not be used in any new code, legacy compat only
49 # @sha224: SHA-224. (since 2.7)
50 # @sha256: SHA-256. Current recommended strong hash.
51 # @sha384: SHA-384. (since 2.7)
52 # @sha512: SHA-512. (since 2.7)
53 # @ripemd160: RIPEMD-160. (since 2.7)
54 # Since: 2.6
55 ##
56 { 'enum': 'QCryptoHashAlgorithm',
57 'prefix': 'QCRYPTO_HASH_ALG',
58 'data': ['md5', 'sha1', 'sha224', 'sha256', 'sha384', 'sha512', 'ripemd160']}
61 ##
62 # @QCryptoCipherAlgorithm:
63 #
64 # The supported algorithms for content encryption ciphers
65 #
66 # @aes-128: AES with 128 bit / 16 byte keys
67 # @aes-192: AES with 192 bit / 24 byte keys
68 # @aes-256: AES with 256 bit / 32 byte keys
69 # @des-rfb: RFB specific variant of single DES. Do not use except in VNC.
70 # @3des: 3DES(EDE) with 192 bit / 24 byte keys (since 2.9)
71 # @cast5-128: Cast5 with 128 bit / 16 byte keys
72 # @serpent-128: Serpent with 128 bit / 16 byte keys
73 # @serpent-192: Serpent with 192 bit / 24 byte keys
74 # @serpent-256: Serpent with 256 bit / 32 byte keys
75 # @twofish-128: Twofish with 128 bit / 16 byte keys
76 # @twofish-192: Twofish with 192 bit / 24 byte keys
77 # @twofish-256: Twofish with 256 bit / 32 byte keys
78 # Since: 2.6
79 ##
80 { 'enum': 'QCryptoCipherAlgorithm',
81 'prefix': 'QCRYPTO_CIPHER_ALG',
82 'data': ['aes-128', 'aes-192', 'aes-256',
83 'des-rfb', '3des',
84 'cast5-128',
85 'serpent-128', 'serpent-192', 'serpent-256',
86 'twofish-128', 'twofish-192', 'twofish-256']}
89 ##
90 # @QCryptoCipherMode:
91 #
92 # The supported modes for content encryption ciphers
93 #
94 # @ecb: Electronic Code Book
95 # @cbc: Cipher Block Chaining
96 # @xts: XEX with tweaked code book and ciphertext stealing
97 # @ctr: Counter (Since 2.8)
98 # Since: 2.6
99 ##
100 { 'enum': 'QCryptoCipherMode',
101 'prefix': 'QCRYPTO_CIPHER_MODE',
102 'data': ['ecb', 'cbc', 'xts', 'ctr']}
105 ##
106 # @QCryptoIVGenAlgorithm:
107 #
108 # The supported algorithms for generating initialization
109 # vectors for full disk encryption. The 'plain' generator
110 # should not be used for disks with sector numbers larger
111 # than 2^32, except where compatibility with pre-existing
112 # Linux dm-crypt volumes is required.
113 #
114 # @plain: 64-bit sector number truncated to 32-bits
115 # @plain64: 64-bit sector number
116 # @essiv: 64-bit sector number encrypted with a hash of the encryption key
117 # Since: 2.6
118 ##
119 { 'enum': 'QCryptoIVGenAlgorithm',
120 'prefix': 'QCRYPTO_IVGEN_ALG',
121 'data': ['plain', 'plain64', 'essiv']}
123 ##
124 # @QCryptoBlockFormat:
125 #
126 # The supported full disk encryption formats
127 #
128 # @qcow: QCow/QCow2 built-in AES-CBC encryption. Use only
129 # for liberating data from old images.
130 # @luks: LUKS encryption format. Recommended for new images
131 #
132 # Since: 2.6
133 ##
134 { 'enum': 'QCryptoBlockFormat',
135 # 'prefix': 'QCRYPTO_BLOCK_FORMAT',
136 'data': ['qcow', 'luks']}
138 ##
139 # @QCryptoBlockOptionsBase:
140 #
141 # The common options that apply to all full disk
142 # encryption formats
143 #
144 # @format: the encryption format
145 #
146 # Since: 2.6
147 ##
148 { 'struct': 'QCryptoBlockOptionsBase',
149 'data': { 'format': 'QCryptoBlockFormat' }}
151 ##
152 # @QCryptoBlockOptionsQCow:
153 #
154 # The options that apply to QCow/QCow2 AES-CBC encryption format
155 #
156 # @key-secret: the ID of a QCryptoSecret object providing the
157 # decryption key. Mandatory except when probing image for
158 # metadata only.
159 #
160 # Since: 2.6
161 ##
162 { 'struct': 'QCryptoBlockOptionsQCow',
163 'data': { '*key-secret': 'str' }}
165 ##
166 # @QCryptoBlockOptionsLUKS:
167 #
168 # The options that apply to LUKS encryption format
169 #
170 # @key-secret: the ID of a QCryptoSecret object providing the
171 # decryption key. Mandatory except when probing image for
172 # metadata only.
173 # Since: 2.6
174 ##
175 { 'struct': 'QCryptoBlockOptionsLUKS',
176 'data': { '*key-secret': 'str' }}
179 ##
180 # @QCryptoBlockCreateOptionsLUKS:
181 #
182 # The options that apply to LUKS encryption format initialization
183 #
184 # @cipher-alg: the cipher algorithm for data encryption
185 # Currently defaults to 'aes-256'.
186 # @cipher-mode: the cipher mode for data encryption
187 # Currently defaults to 'xts'
188 # @ivgen-alg: the initialization vector generator
189 # Currently defaults to 'plain64'
190 # @ivgen-hash-alg: the initialization vector generator hash
191 # Currently defaults to 'sha256'
192 # @hash-alg: the master key hash algorithm
193 # Currently defaults to 'sha256'
194 # @iter-time: number of milliseconds to spend in
195 # PBKDF passphrase processing. Currently defaults
196 # to 2000. (since 2.8)
197 # Since: 2.6
198 ##
199 { 'struct': 'QCryptoBlockCreateOptionsLUKS',
200 'base': 'QCryptoBlockOptionsLUKS',
201 'data': { '*cipher-alg': 'QCryptoCipherAlgorithm',
202 '*cipher-mode': 'QCryptoCipherMode',
203 '*ivgen-alg': 'QCryptoIVGenAlgorithm',
204 '*ivgen-hash-alg': 'QCryptoHashAlgorithm',
205 '*hash-alg': 'QCryptoHashAlgorithm',
206 '*iter-time': 'int'}}
209 ##
210 # @QCryptoBlockOpenOptions:
211 #
212 # The options that are available for all encryption formats
213 # when opening an existing volume
214 #
215 # Since: 2.6
216 ##
217 { 'union': 'QCryptoBlockOpenOptions',
218 'base': 'QCryptoBlockOptionsBase',
219 'discriminator': 'format',
220 'data': { 'qcow': 'QCryptoBlockOptionsQCow',
221 'luks': 'QCryptoBlockOptionsLUKS' } }
224 ##
225 # @QCryptoBlockCreateOptions:
226 #
227 # The options that are available for all encryption formats
228 # when initializing a new volume
229 #
230 # Since: 2.6
231 ##
232 { 'union': 'QCryptoBlockCreateOptions',
233 'base': 'QCryptoBlockOptionsBase',
234 'discriminator': 'format',
235 'data': { 'qcow': 'QCryptoBlockOptionsQCow',
236 'luks': 'QCryptoBlockCreateOptionsLUKS' } }
239 ##
240 # @QCryptoBlockInfoBase:
241 #
242 # The common information that applies to all full disk
243 # encryption formats
244 #
245 # @format: the encryption format
246 #
247 # Since: 2.7
248 ##
249 { 'struct': 'QCryptoBlockInfoBase',
250 'data': { 'format': 'QCryptoBlockFormat' }}
253 ##
254 # @QCryptoBlockInfoLUKSSlot:
255 #
256 # Information about the LUKS block encryption key
257 # slot options
258 #
259 # @active: whether the key slot is currently in use
260 # @key-offset: offset to the key material in bytes
261 # @iters: number of PBKDF2 iterations for key material
262 # @stripes: number of stripes for splitting key material
263 #
264 # Since: 2.7
265 ##
266 { 'struct': 'QCryptoBlockInfoLUKSSlot',
267 'data': {'active': 'bool',
268 '*iters': 'int',
269 '*stripes': 'int',
270 'key-offset': 'int' } }
273 ##
274 # @QCryptoBlockInfoLUKS:
275 #
276 # Information about the LUKS block encryption options
277 #
278 # @cipher-alg: the cipher algorithm for data encryption
279 # @cipher-mode: the cipher mode for data encryption
280 # @ivgen-alg: the initialization vector generator
281 # @ivgen-hash-alg: the initialization vector generator hash
282 # @hash-alg: the master key hash algorithm
283 # @payload-offset: offset to the payload data in bytes
284 # @master-key-iters: number of PBKDF2 iterations for key material
285 # @uuid: unique identifier for the volume
286 # @slots: information about each key slot
287 #
288 # Since: 2.7
289 ##
290 { 'struct': 'QCryptoBlockInfoLUKS',
291 'data': {'cipher-alg': 'QCryptoCipherAlgorithm',
292 'cipher-mode': 'QCryptoCipherMode',
293 'ivgen-alg': 'QCryptoIVGenAlgorithm',
294 '*ivgen-hash-alg': 'QCryptoHashAlgorithm',
295 'hash-alg': 'QCryptoHashAlgorithm',
296 'payload-offset': 'int',
297 'master-key-iters': 'int',
298 'uuid': 'str',
299 'slots': [ 'QCryptoBlockInfoLUKSSlot' ] }}
301 ##
302 # @QCryptoBlockInfo:
303 #
304 # Information about the block encryption options
305 #
306 # Since: 2.7
307 ##
308 { 'union': 'QCryptoBlockInfo',
309 'base': 'QCryptoBlockInfoBase',
310 'discriminator': 'format',
311 'data': { 'luks': 'QCryptoBlockInfoLUKS' } }
313 ##
314 # @QCryptoBlockLUKSKeyslotState:
315 #
316 # Defines state of keyslots that are affected by the update
317 #
318 # @active: The slots contain the given password and marked as active
319 # @inactive: The slots are erased (contain garbage) and marked as inactive
320 #
321 # Since: 5.1
322 ##
323 { 'enum': 'QCryptoBlockLUKSKeyslotState',
324 'data': [ 'active', 'inactive' ] }
327 ##
328 # @QCryptoBlockAmendOptionsLUKS:
329 #
330 # This struct defines the update parameters that activate/de-activate set
331 # of keyslots
332 #
333 # @state: the desired state of the keyslots
334 #
335 # @new-secret: The ID of a QCryptoSecret object providing the password to be
336 # written into added active keyslots
337 #
338 # @old-secret: Optional (for deactivation only)
339 # If given will deactivate all keyslots that
340 # match password located in QCryptoSecret with this ID
341 #
342 # @iter-time: Optional (for activation only)
343 # Number of milliseconds to spend in
344 # PBKDF passphrase processing for the newly activated keyslot.
345 # Currently defaults to 2000.
346 #
347 # @keyslot: Optional. ID of the keyslot to activate/deactivate.
348 # For keyslot activation, keyslot should not be active already
349 # (this is unsafe to update an active keyslot),
350 # but possible if 'force' parameter is given.
351 # If keyslot is not given, first free keyslot will be written.
352 #
353 # For keyslot deactivation, this parameter specifies the exact
354 # keyslot to deactivate
355 #
356 # @secret: Optional. The ID of a QCryptoSecret object providing the
357 # password to use to retrieve current master key.
358 # Defaults to the same secret that was used to open the image
359 #
360 #
361 # Since 5.1
362 ##
363 { 'struct': 'QCryptoBlockAmendOptionsLUKS',
364 'data': { 'state': 'QCryptoBlockLUKSKeyslotState',
365 '*new-secret': 'str',
366 '*old-secret': 'str',
367 '*keyslot': 'int',
368 '*iter-time': 'int',
369 '*secret': 'str' } }
371 ##
372 # @QCryptoBlockAmendOptions:
373 #
374 # The options that are available for all encryption formats
375 # when amending encryption settings
376 #
377 # Since: 5.1
378 ##
379 { 'union': 'QCryptoBlockAmendOptions',
380 'base': 'QCryptoBlockOptionsBase',
381 'discriminator': 'format',
382 'data': {
383 'luks': 'QCryptoBlockAmendOptionsLUKS' } }
385 ##
386 # @SecretCommonProperties:
387 #
388 # Properties for objects of classes derived from secret-common.
389 #
390 # @loaded: if true, the secret is loaded immediately when applying this option
391 # and will probably fail when processing the next option. Don't use;
392 # only provided for compatibility. (default: false)
393 #
394 # @format: the data format that the secret is provided in (default: raw)
395 #
396 # @keyid: the name of another secret that should be used to decrypt the
397 # provided data. If not present, the data is assumed to be unencrypted.
398 #
399 # @iv: the random initialization vector used for encryption of this particular
400 # secret. Should be a base64 encrypted string of the 16-byte IV. Mandatory
401 # if @keyid is given. Ignored if @keyid is absent.
402 #
403 # Features:
404 # @deprecated: Member @loaded is deprecated. Setting true doesn't make sense,
405 # and false is already the default.
406 #
407 # Since: 2.6
408 ##
409 { 'struct': 'SecretCommonProperties',
410 'data': { '*loaded': { 'type': 'bool', 'features': ['deprecated'] },
411 '*format': 'QCryptoSecretFormat',
412 '*keyid': 'str',
413 '*iv': 'str' } }
415 ##
416 # @SecretProperties:
417 #
418 # Properties for secret objects.
419 #
420 # Either @data or @file must be provided, but not both.
421 #
422 # @data: the associated with the secret from
423 #
424 # @file: the filename to load the data associated with the secret from
425 #
426 # Since: 2.6
427 ##
428 { 'struct': 'SecretProperties',
429 'base': 'SecretCommonProperties',
430 'data': { '*data': 'str',
431 '*file': 'str' } }
433 ##
434 # @SecretKeyringProperties:
435 #
436 # Properties for secret_keyring objects.
437 #
438 # @serial: serial number that identifies a key to get from the kernel
439 #
440 # Since: 5.1
441 ##
442 { 'struct': 'SecretKeyringProperties',
443 'base': 'SecretCommonProperties',
444 'data': { 'serial': 'int32' } }
446 ##
447 # @TlsCredsProperties:
448 #
449 # Properties for objects of classes derived from tls-creds.
450 #
451 # @verify-peer: if true the peer credentials will be verified once the
452 # handshake is completed. This is a no-op for anonymous
453 # credentials. (default: true)
454 #
455 # @dir: the path of the directory that contains the credential files
456 #
457 # @endpoint: whether the QEMU network backend that uses the credentials will be
458 # acting as a client or as a server (default: client)
459 #
460 # @priority: a gnutls priority string as described at
461 # https://gnutls.org/manual/html_node/Priority-Strings.html
462 #
463 # Since: 2.5
464 ##
465 { 'struct': 'TlsCredsProperties',
466 'data': { '*verify-peer': 'bool',
467 '*dir': 'str',
468 '*endpoint': 'QCryptoTLSCredsEndpoint',
469 '*priority': 'str' } }
471 ##
472 # @TlsCredsAnonProperties:
473 #
474 # Properties for tls-creds-anon objects.
475 #
476 # @loaded: if true, the credentials are loaded immediately when applying this
477 # option and will ignore options that are processed later. Don't use;
478 # only provided for compatibility. (default: false)
479 #
480 # Features:
481 # @deprecated: Member @loaded is deprecated. Setting true doesn't make sense,
482 # and false is already the default.
483 #
484 # Since: 2.5
485 ##
486 { 'struct': 'TlsCredsAnonProperties',
487 'base': 'TlsCredsProperties',
488 'data': { '*loaded': { 'type': 'bool', 'features': ['deprecated'] } } }
490 ##
491 # @TlsCredsPskProperties:
492 #
493 # Properties for tls-creds-psk objects.
494 #
495 # @loaded: if true, the credentials are loaded immediately when applying this
496 # option and will ignore options that are processed later. Don't use;
497 # only provided for compatibility. (default: false)
498 #
499 # @username: the username which will be sent to the server. For clients only.
500 # If absent, "qemu" is sent and the property will read back as an
501 # empty string.
502 #
503 # Features:
504 # @deprecated: Member @loaded is deprecated. Setting true doesn't make sense,
505 # and false is already the default.
506 #
507 # Since: 3.0
508 ##
509 { 'struct': 'TlsCredsPskProperties',
510 'base': 'TlsCredsProperties',
511 'data': { '*loaded': { 'type': 'bool', 'features': ['deprecated'] },
512 '*username': 'str' } }
514 ##
515 # @TlsCredsX509Properties:
516 #
517 # Properties for tls-creds-x509 objects.
518 #
519 # @loaded: if true, the credentials are loaded immediately when applying this
520 # option and will ignore options that are processed later. Don't use;
521 # only provided for compatibility. (default: false)
522 #
523 # @sanity-check: if true, perform some sanity checks before using the
524 # credentials (default: true)
525 #
526 # @passwordid: For the server-key.pem and client-key.pem files which contain
527 # sensitive private keys, it is possible to use an encrypted
528 # version by providing the @passwordid parameter. This provides
529 # the ID of a previously created secret object containing the
530 # password for decryption.
531 #
532 # Features:
533 # @deprecated: Member @loaded is deprecated. Setting true doesn't make sense,
534 # and false is already the default.
535 #
536 # Since: 2.5
537 ##
538 { 'struct': 'TlsCredsX509Properties',
539 'base': 'TlsCredsProperties',
540 'data': { '*loaded': { 'type': 'bool', 'features': ['deprecated'] },
541 '*sanity-check': 'bool',
542 '*passwordid': 'str' } }