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