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