| blob | fd3d46ebd12821fbed62196e76b87ef25be6802e |
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 client.
15 #
16 # @client: the network endpoint is acting as the client
17 #
18 # @server: the network endpoint is acting as the server
19 #
20 # Since: 2.5
21 ##
22 { 'enum': 'QCryptoTLSCredsEndpoint',
23 'prefix': 'QCRYPTO_TLS_CREDS_ENDPOINT',
24 'data': ['client', 'server']}
26 ##
27 # @QCryptoSecretFormat:
28 #
29 # The data format that the secret is provided in
30 #
31 # @raw: raw bytes. When encoded in JSON only valid UTF-8 sequences
32 # can be used
33 #
34 # @base64: arbitrary base64 encoded binary data
35 #
36 # Since: 2.6
37 ##
38 { 'enum': 'QCryptoSecretFormat',
39 'prefix': 'QCRYPTO_SECRET_FORMAT',
40 '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 #
49 # @sha1: SHA-1. Should not be used in any new code, legacy compat only
50 #
51 # @sha224: SHA-224. (since 2.7)
52 #
53 # @sha256: SHA-256. Current recommended strong hash.
54 #
55 # @sha384: SHA-384. (since 2.7)
56 #
57 # @sha512: SHA-512. (since 2.7)
58 #
59 # @ripemd160: RIPEMD-160. (since 2.7)
60 #
61 # Since: 2.6
62 ##
63 { 'enum': 'QCryptoHashAlgorithm',
64 'prefix': 'QCRYPTO_HASH_ALG',
65 'data': ['md5', 'sha1', 'sha224', 'sha256', 'sha384', 'sha512', 'ripemd160']}
67 ##
68 # @QCryptoCipherAlgorithm:
69 #
70 # The supported algorithms for content encryption ciphers
71 #
72 # @aes-128: AES with 128 bit / 16 byte keys
73 #
74 # @aes-192: AES with 192 bit / 24 byte keys
75 #
76 # @aes-256: AES with 256 bit / 32 byte keys
77 #
78 # @des: DES with 56 bit / 8 byte keys. Do not use except in VNC.
79 # (since 6.1)
80 #
81 # @3des: 3DES(EDE) with 192 bit / 24 byte keys (since 2.9)
82 #
83 # @cast5-128: Cast5 with 128 bit / 16 byte keys
84 #
85 # @serpent-128: Serpent with 128 bit / 16 byte keys
86 #
87 # @serpent-192: Serpent with 192 bit / 24 byte keys
88 #
89 # @serpent-256: Serpent with 256 bit / 32 byte keys
90 #
91 # @twofish-128: Twofish with 128 bit / 16 byte keys
92 #
93 # @twofish-192: Twofish with 192 bit / 24 byte keys
94 #
95 # @twofish-256: Twofish with 256 bit / 32 byte keys
96 #
97 # Since: 2.6
98 ##
99 { 'enum': 'QCryptoCipherAlgorithm',
100 'prefix': 'QCRYPTO_CIPHER_ALG',
101 'data': ['aes-128', 'aes-192', 'aes-256',
102 'des', '3des',
103 'cast5-128',
104 'serpent-128', 'serpent-192', 'serpent-256',
105 'twofish-128', 'twofish-192', 'twofish-256']}
107 ##
108 # @QCryptoCipherMode:
109 #
110 # The supported modes for content encryption ciphers
111 #
112 # @ecb: Electronic Code Book
113 #
114 # @cbc: Cipher Block Chaining
115 #
116 # @xts: XEX with tweaked code book and ciphertext stealing
117 #
118 # @ctr: Counter (Since 2.8)
119 #
120 # Since: 2.6
121 ##
122 { 'enum': 'QCryptoCipherMode',
123 'prefix': 'QCRYPTO_CIPHER_MODE',
124 'data': ['ecb', 'cbc', 'xts', 'ctr']}
126 ##
127 # @QCryptoIVGenAlgorithm:
128 #
129 # The supported algorithms for generating initialization vectors for
130 # full disk encryption. The 'plain' generator should not be used for
131 # disks with sector numbers larger than 2^32, except where
132 # compatibility with pre-existing Linux dm-crypt volumes is required.
133 #
134 # @plain: 64-bit sector number truncated to 32-bits
135 #
136 # @plain64: 64-bit sector number
137 #
138 # @essiv: 64-bit sector number encrypted with a hash of the encryption
139 # key
140 #
141 # Since: 2.6
142 ##
143 { 'enum': 'QCryptoIVGenAlgorithm',
144 'prefix': 'QCRYPTO_IVGEN_ALG',
145 'data': ['plain', 'plain64', 'essiv']}
147 ##
148 # @QCryptoBlockFormat:
149 #
150 # The supported full disk encryption formats
151 #
152 # @qcow: QCow/QCow2 built-in AES-CBC encryption. Use only for
153 # liberating data from old images.
154 #
155 # @luks: LUKS encryption format. Recommended for new images
156 #
157 # Since: 2.6
158 ##
159 { 'enum': 'QCryptoBlockFormat',
160 # 'prefix': 'QCRYPTO_BLOCK_FORMAT',
161 'data': ['qcow', 'luks']}
163 ##
164 # @QCryptoBlockOptionsBase:
165 #
166 # The common options that apply to all full disk encryption formats
167 #
168 # @format: the encryption format
169 #
170 # Since: 2.6
171 ##
172 { 'struct': 'QCryptoBlockOptionsBase',
173 'data': { 'format': 'QCryptoBlockFormat' }}
175 ##
176 # @QCryptoBlockOptionsQCow:
177 #
178 # The options that apply to QCow/QCow2 AES-CBC encryption format
179 #
180 # @key-secret: the ID of a QCryptoSecret object providing the
181 # decryption key. Mandatory except when probing image for
182 # metadata only.
183 #
184 # Since: 2.6
185 ##
186 { 'struct': 'QCryptoBlockOptionsQCow',
187 'data': { '*key-secret': 'str' }}
189 ##
190 # @QCryptoBlockOptionsLUKS:
191 #
192 # The options that apply to LUKS encryption format
193 #
194 # @key-secret: the ID of a QCryptoSecret object providing the
195 # decryption key. Mandatory except when probing image for
196 # metadata only.
197 #
198 # Since: 2.6
199 ##
200 { 'struct': 'QCryptoBlockOptionsLUKS',
201 'data': { '*key-secret': 'str' }}
203 ##
204 # @QCryptoBlockCreateOptionsLUKS:
205 #
206 # The options that apply to LUKS encryption format initialization
207 #
208 # @cipher-alg: the cipher algorithm for data encryption Currently
209 # defaults to 'aes-256'.
210 #
211 # @cipher-mode: the cipher mode for data encryption Currently defaults
212 # to 'xts'
213 #
214 # @ivgen-alg: the initialization vector generator Currently defaults
215 # to 'plain64'
216 #
217 # @ivgen-hash-alg: the initialization vector generator hash Currently
218 # defaults to 'sha256'
219 #
220 # @hash-alg: the master key hash algorithm Currently defaults to
221 # 'sha256'
222 #
223 # @iter-time: number of milliseconds to spend in PBKDF passphrase
224 # processing. Currently defaults to 2000. (since 2.8)
225 #
226 # Since: 2.6
227 ##
228 { 'struct': 'QCryptoBlockCreateOptionsLUKS',
229 'base': 'QCryptoBlockOptionsLUKS',
230 'data': { '*cipher-alg': 'QCryptoCipherAlgorithm',
231 '*cipher-mode': 'QCryptoCipherMode',
232 '*ivgen-alg': 'QCryptoIVGenAlgorithm',
233 '*ivgen-hash-alg': 'QCryptoHashAlgorithm',
234 '*hash-alg': 'QCryptoHashAlgorithm',
235 '*iter-time': 'int'}}
237 ##
238 # @QCryptoBlockOpenOptions:
239 #
240 # The options that are available for all encryption formats when
241 # opening an existing volume
242 #
243 # Since: 2.6
244 ##
245 { 'union': 'QCryptoBlockOpenOptions',
246 'base': 'QCryptoBlockOptionsBase',
247 'discriminator': 'format',
248 'data': { 'qcow': 'QCryptoBlockOptionsQCow',
249 'luks': 'QCryptoBlockOptionsLUKS' } }
251 ##
252 # @QCryptoBlockCreateOptions:
253 #
254 # The options that are available for all encryption formats when
255 # initializing a new volume
256 #
257 # Since: 2.6
258 ##
259 { 'union': 'QCryptoBlockCreateOptions',
260 'base': 'QCryptoBlockOptionsBase',
261 'discriminator': 'format',
262 'data': { 'qcow': 'QCryptoBlockOptionsQCow',
263 'luks': 'QCryptoBlockCreateOptionsLUKS' } }
265 ##
266 # @QCryptoBlockInfoBase:
267 #
268 # The common information that applies to all full disk encryption
269 # formats
270 #
271 # @format: the encryption format
272 #
273 # Since: 2.7
274 ##
275 { 'struct': 'QCryptoBlockInfoBase',
276 'data': { 'format': 'QCryptoBlockFormat' }}
278 ##
279 # @QCryptoBlockInfoLUKSSlot:
280 #
281 # Information about the LUKS block encryption key slot options
282 #
283 # @active: whether the key slot is currently in use
284 #
285 # @key-offset: offset to the key material in bytes
286 #
287 # @iters: number of PBKDF2 iterations for key material
288 #
289 # @stripes: number of stripes for splitting key material
290 #
291 # Since: 2.7
292 ##
293 { 'struct': 'QCryptoBlockInfoLUKSSlot',
294 'data': {'active': 'bool',
295 '*iters': 'int',
296 '*stripes': 'int',
297 'key-offset': 'int' } }
299 ##
300 # @QCryptoBlockInfoLUKS:
301 #
302 # Information about the LUKS block encryption options
303 #
304 # @cipher-alg: the cipher algorithm for data encryption
305 #
306 # @cipher-mode: the cipher mode for data encryption
307 #
308 # @ivgen-alg: the initialization vector generator
309 #
310 # @ivgen-hash-alg: the initialization vector generator hash
311 #
312 # @hash-alg: the master key hash algorithm
313 #
314 # @payload-offset: offset to the payload data in bytes
315 #
316 # @master-key-iters: number of PBKDF2 iterations for key material
317 #
318 # @uuid: unique identifier for the volume
319 #
320 # @slots: information about each key slot
321 #
322 # Since: 2.7
323 ##
324 { 'struct': 'QCryptoBlockInfoLUKS',
325 'data': {'cipher-alg': 'QCryptoCipherAlgorithm',
326 'cipher-mode': 'QCryptoCipherMode',
327 'ivgen-alg': 'QCryptoIVGenAlgorithm',
328 '*ivgen-hash-alg': 'QCryptoHashAlgorithm',
329 'hash-alg': 'QCryptoHashAlgorithm',
330 'payload-offset': 'int',
331 'master-key-iters': 'int',
332 'uuid': 'str',
333 'slots': [ 'QCryptoBlockInfoLUKSSlot' ] }}
335 ##
336 # @QCryptoBlockInfo:
337 #
338 # Information about the block encryption options
339 #
340 # Since: 2.7
341 ##
342 { 'union': 'QCryptoBlockInfo',
343 'base': 'QCryptoBlockInfoBase',
344 'discriminator': 'format',
345 'data': { 'luks': 'QCryptoBlockInfoLUKS' } }
347 ##
348 # @QCryptoBlockLUKSKeyslotState:
349 #
350 # Defines state of keyslots that are affected by the update
351 #
352 # @active: The slots contain the given password and marked as active
353 #
354 # @inactive: The slots are erased (contain garbage) and marked as
355 # inactive
356 #
357 # Since: 5.1
358 ##
359 { 'enum': 'QCryptoBlockLUKSKeyslotState',
360 'data': [ 'active', 'inactive' ] }
362 ##
363 # @QCryptoBlockAmendOptionsLUKS:
364 #
365 # This struct defines the update parameters that activate/de-activate
366 # set of keyslots
367 #
368 # @state: the desired state of the keyslots
369 #
370 # @new-secret: The ID of a QCryptoSecret object providing the password
371 # to be written into added active keyslots
372 #
373 # @old-secret: Optional (for deactivation only) If given will
374 # deactivate all keyslots that match password located in
375 # QCryptoSecret with this ID
376 #
377 # @iter-time: Optional (for activation only) Number of milliseconds to
378 # spend in PBKDF passphrase processing for the newly activated
379 # keyslot. Currently defaults to 2000.
380 #
381 # @keyslot: Optional. ID of the keyslot to activate/deactivate. For
382 # keyslot activation, keyslot should not be active already (this
383 # is unsafe to update an active keyslot), but possible if 'force'
384 # parameter is given. If keyslot is not given, first free keyslot
385 # will be written.
386 #
387 # For keyslot deactivation, this parameter specifies the exact
388 # keyslot to deactivate
389 #
390 # @secret: Optional. The ID of a QCryptoSecret object providing the
391 # password to use to retrieve current master key. Defaults to the
392 # same secret that was used to open the image
393 #
394 # Since: 5.1
395 ##
396 { 'struct': 'QCryptoBlockAmendOptionsLUKS',
397 'data': { 'state': 'QCryptoBlockLUKSKeyslotState',
398 '*new-secret': 'str',
399 '*old-secret': 'str',
400 '*keyslot': 'int',
401 '*iter-time': 'int',
402 '*secret': 'str' } }
404 ##
405 # @QCryptoBlockAmendOptions:
406 #
407 # The options that are available for all encryption formats when
408 # amending encryption settings
409 #
410 # Since: 5.1
411 ##
412 { 'union': 'QCryptoBlockAmendOptions',
413 'base': 'QCryptoBlockOptionsBase',
414 'discriminator': 'format',
415 'data': {
416 'luks': 'QCryptoBlockAmendOptionsLUKS' } }
418 ##
419 # @SecretCommonProperties:
420 #
421 # Properties for objects of classes derived from secret-common.
422 #
423 # @loaded: if true, the secret is loaded immediately when applying
424 # this option and will probably fail when processing the next
425 # option. Don't use; only provided for compatibility.
426 # (default: false)
427 #
428 # @format: the data format that the secret is provided in
429 # (default: raw)
430 #
431 # @keyid: the name of another secret that should be used to decrypt
432 # the provided data. If not present, the data is assumed to be
433 # unencrypted.
434 #
435 # @iv: the random initialization vector used for encryption of this
436 # particular secret. Should be a base64 encrypted string of the
437 # 16-byte IV. Mandatory if @keyid is given. Ignored if @keyid is
438 # absent.
439 #
440 # Features:
441 #
442 # @deprecated: Member @loaded is deprecated. Setting true doesn't
443 # make sense, and false is already the default.
444 #
445 # Since: 2.6
446 ##
447 { 'struct': 'SecretCommonProperties',
448 'data': { '*loaded': { 'type': 'bool', 'features': ['deprecated'] },
449 '*format': 'QCryptoSecretFormat',
450 '*keyid': 'str',
451 '*iv': 'str' } }
453 ##
454 # @SecretProperties:
455 #
456 # Properties for secret objects.
457 #
458 # Either @data or @file must be provided, but not both.
459 #
460 # @data: the associated with the secret from
461 #
462 # @file: the filename to load the data associated with the secret from
463 #
464 # Since: 2.6
465 ##
466 { 'struct': 'SecretProperties',
467 'base': 'SecretCommonProperties',
468 'data': { '*data': 'str',
469 '*file': 'str' } }
471 ##
472 # @SecretKeyringProperties:
473 #
474 # Properties for secret_keyring objects.
475 #
476 # @serial: serial number that identifies a key to get from the kernel
477 #
478 # Since: 5.1
479 ##
480 { 'struct': 'SecretKeyringProperties',
481 'base': 'SecretCommonProperties',
482 'data': { 'serial': 'int32' } }
484 ##
485 # @TlsCredsProperties:
486 #
487 # Properties for objects of classes derived from tls-creds.
488 #
489 # @verify-peer: if true the peer credentials will be verified once the
490 # handshake is completed. This is a no-op for anonymous
491 # credentials. (default: true)
492 #
493 # @dir: the path of the directory that contains the credential files
494 #
495 # @endpoint: whether the QEMU network backend that uses the
496 # credentials will be acting as a client or as a server
497 # (default: client)
498 #
499 # @priority: a gnutls priority string as described at
500 # https://gnutls.org/manual/html_node/Priority-Strings.html
501 #
502 # Since: 2.5
503 ##
504 { 'struct': 'TlsCredsProperties',
505 'data': { '*verify-peer': 'bool',
506 '*dir': 'str',
507 '*endpoint': 'QCryptoTLSCredsEndpoint',
508 '*priority': 'str' } }
510 ##
511 # @TlsCredsAnonProperties:
512 #
513 # Properties for tls-creds-anon objects.
514 #
515 # @loaded: if true, the credentials are loaded immediately when
516 # applying this option and will ignore options that are processed
517 # later. Don't use; only provided for compatibility.
518 # (default: false)
519 #
520 # Features:
521 #
522 # @deprecated: Member @loaded is deprecated. Setting true doesn't
523 # make sense, and false is already the default.
524 #
525 # Since: 2.5
526 ##
527 { 'struct': 'TlsCredsAnonProperties',
528 'base': 'TlsCredsProperties',
529 'data': { '*loaded': { 'type': 'bool', 'features': ['deprecated'] } } }
531 ##
532 # @TlsCredsPskProperties:
533 #
534 # Properties for tls-creds-psk objects.
535 #
536 # @loaded: if true, the credentials are loaded immediately when
537 # applying this option and will ignore options that are processed
538 # later. Don't use; only provided for compatibility.
539 # (default: false)
540 #
541 # @username: the username which will be sent to the server. For
542 # clients only. If absent, "qemu" is sent and the property will
543 # read back as an empty string.
544 #
545 # Features:
546 #
547 # @deprecated: Member @loaded is deprecated. Setting true doesn't
548 # make sense, and false is already the default.
549 #
550 # Since: 3.0
551 ##
552 { 'struct': 'TlsCredsPskProperties',
553 'base': 'TlsCredsProperties',
554 'data': { '*loaded': { 'type': 'bool', 'features': ['deprecated'] },
555 '*username': 'str' } }
557 ##
558 # @TlsCredsX509Properties:
559 #
560 # Properties for tls-creds-x509 objects.
561 #
562 # @loaded: if true, the credentials are loaded immediately when
563 # applying this option and will ignore options that are processed
564 # later. Don't use; only provided for compatibility.
565 # (default: false)
566 #
567 # @sanity-check: if true, perform some sanity checks before using the
568 # credentials (default: true)
569 #
570 # @passwordid: For the server-key.pem and client-key.pem files which
571 # contain sensitive private keys, it is possible to use an
572 # encrypted version by providing the @passwordid parameter. This
573 # provides the ID of a previously created secret object containing
574 # the password for decryption.
575 #
576 # Features:
577 #
578 # @deprecated: Member @loaded is deprecated. Setting true doesn't
579 # make sense, and false is already the default.
580 #
581 # Since: 2.5
582 ##
583 { 'struct': 'TlsCredsX509Properties',
584 'base': 'TlsCredsProperties',
585 'data': { '*loaded': { 'type': 'bool', 'features': ['deprecated'] },
586 '*sanity-check': 'bool',
587 '*passwordid': 'str' } }
588 ##
589 # @QCryptoAkCipherAlgorithm:
590 #
591 # The supported algorithms for asymmetric encryption ciphers
592 #
593 # @rsa: RSA algorithm
594 #
595 # Since: 7.1
596 ##
597 { 'enum': 'QCryptoAkCipherAlgorithm',
598 'prefix': 'QCRYPTO_AKCIPHER_ALG',
599 'data': ['rsa']}
601 ##
602 # @QCryptoAkCipherKeyType:
603 #
604 # The type of asymmetric keys.
605 #
606 # Since: 7.1
607 ##
608 { 'enum': 'QCryptoAkCipherKeyType',
609 'prefix': 'QCRYPTO_AKCIPHER_KEY_TYPE',
610 'data': ['public', 'private']}
612 ##
613 # @QCryptoRSAPaddingAlgorithm:
614 #
615 # The padding algorithm for RSA.
616 #
617 # @raw: no padding used
618 #
619 # @pkcs1: pkcs1#v1.5
620 #
621 # Since: 7.1
622 ##
623 { 'enum': 'QCryptoRSAPaddingAlgorithm',
624 'prefix': 'QCRYPTO_RSA_PADDING_ALG',
625 'data': ['raw', 'pkcs1']}
627 ##
628 # @QCryptoAkCipherOptionsRSA:
629 #
630 # Specific parameters for RSA algorithm.
631 #
632 # @hash-alg: QCryptoHashAlgorithm
633 #
634 # @padding-alg: QCryptoRSAPaddingAlgorithm
635 #
636 # Since: 7.1
637 ##
638 { 'struct': 'QCryptoAkCipherOptionsRSA',
639 'data': { 'hash-alg':'QCryptoHashAlgorithm',
640 'padding-alg': 'QCryptoRSAPaddingAlgorithm'}}
642 ##
643 # @QCryptoAkCipherOptions:
644 #
645 # The options that are available for all asymmetric key algorithms
646 # when creating a new QCryptoAkCipher.
647 #
648 # Since: 7.1
649 ##
650 { 'union': 'QCryptoAkCipherOptions',
651 'base': { 'alg': 'QCryptoAkCipherAlgorithm' },
652 'discriminator': 'alg',
653 'data': { 'rsa': 'QCryptoAkCipherOptionsRSA' }}