migration: Make save_snapshot() return bool, not 0/-1
[qemu/ar7.git] / qapi / crypto.json
blob2aebe6fa20fd8051667a2e57d8ce37eec4c4de13
1 # -*- Mode: Python -*-
2 # vim: filetype=python
5 ##
6 # = Cryptography
7 ##
9 ##
10 # @QCryptoTLSCredsEndpoint:
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.
17 # @client: the network endpoint is acting as the client
19 # @server: the network endpoint is acting as the server
21 # Since: 2.5
23 { 'enum': 'QCryptoTLSCredsEndpoint',
24   'prefix': 'QCRYPTO_TLS_CREDS_ENDPOINT',
25   'data': ['client', 'server']}
29 # @QCryptoSecretFormat:
31 # The data format that the secret is provided in
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
37 { 'enum': 'QCryptoSecretFormat',
38   'prefix': 'QCRYPTO_SECRET_FORMAT',
39   'data': ['raw', 'base64']}
43 # @QCryptoHashAlgorithm:
45 # The supported algorithms for computing content digests
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
56 { 'enum': 'QCryptoHashAlgorithm',
57   'prefix': 'QCRYPTO_HASH_ALG',
58   'data': ['md5', 'sha1', 'sha224', 'sha256', 'sha384', 'sha512', 'ripemd160']}
62 # @QCryptoCipherAlgorithm:
64 # The supported algorithms for content encryption ciphers
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
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']}
90 # @QCryptoCipherMode:
92 # The supported modes for content encryption ciphers
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
100 { 'enum': 'QCryptoCipherMode',
101   'prefix': 'QCRYPTO_CIPHER_MODE',
102   'data': ['ecb', 'cbc', 'xts', 'ctr']}
106 # @QCryptoIVGenAlgorithm:
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.
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
119 { 'enum': 'QCryptoIVGenAlgorithm',
120   'prefix': 'QCRYPTO_IVGEN_ALG',
121   'data': ['plain', 'plain64', 'essiv']}
124 # @QCryptoBlockFormat:
126 # The supported full disk encryption formats
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
132 # Since: 2.6
134 { 'enum': 'QCryptoBlockFormat',
135 #  'prefix': 'QCRYPTO_BLOCK_FORMAT',
136   'data': ['qcow', 'luks']}
139 # @QCryptoBlockOptionsBase:
141 # The common options that apply to all full disk
142 # encryption formats
144 # @format: the encryption format
146 # Since: 2.6
148 { 'struct': 'QCryptoBlockOptionsBase',
149   'data': { 'format': 'QCryptoBlockFormat' }}
152 # @QCryptoBlockOptionsQCow:
154 # The options that apply to QCow/QCow2 AES-CBC encryption format
156 # @key-secret: the ID of a QCryptoSecret object providing the
157 #              decryption key. Mandatory except when probing image for
158 #              metadata only.
160 # Since: 2.6
162 { 'struct': 'QCryptoBlockOptionsQCow',
163   'data': { '*key-secret': 'str' }}
166 # @QCryptoBlockOptionsLUKS:
168 # The options that apply to LUKS encryption format
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
175 { 'struct': 'QCryptoBlockOptionsLUKS',
176   'data': { '*key-secret': 'str' }}
180 # @QCryptoBlockCreateOptionsLUKS:
182 # The options that apply to LUKS encryption format initialization
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
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'}}
210 # @QCryptoBlockOpenOptions:
212 # The options that are available for all encryption formats
213 # when opening an existing volume
215 # Since: 2.6
217 { 'union': 'QCryptoBlockOpenOptions',
218   'base': 'QCryptoBlockOptionsBase',
219   'discriminator': 'format',
220   'data': { 'qcow': 'QCryptoBlockOptionsQCow',
221             'luks': 'QCryptoBlockOptionsLUKS' } }
225 # @QCryptoBlockCreateOptions:
227 # The options that are available for all encryption formats
228 # when initializing a new volume
230 # Since: 2.6
232 { 'union': 'QCryptoBlockCreateOptions',
233   'base': 'QCryptoBlockOptionsBase',
234   'discriminator': 'format',
235   'data': { 'qcow': 'QCryptoBlockOptionsQCow',
236             'luks': 'QCryptoBlockCreateOptionsLUKS' } }
240 # @QCryptoBlockInfoBase:
242 # The common information that applies to all full disk
243 # encryption formats
245 # @format: the encryption format
247 # Since: 2.7
249 { 'struct': 'QCryptoBlockInfoBase',
250   'data': { 'format': 'QCryptoBlockFormat' }}
254 # @QCryptoBlockInfoLUKSSlot:
256 # Information about the LUKS block encryption key
257 # slot options
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
264 # Since: 2.7
266 { 'struct': 'QCryptoBlockInfoLUKSSlot',
267   'data': {'active': 'bool',
268            '*iters': 'int',
269            '*stripes': 'int',
270            'key-offset': 'int' } }
274 # @QCryptoBlockInfoLUKS:
276 # Information about the LUKS block encryption options
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
288 # Since: 2.7
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' ] }}
302 # @QCryptoBlockInfo:
304 # Information about the block encryption options
306 # Since: 2.7
308 { 'union': 'QCryptoBlockInfo',
309   'base': 'QCryptoBlockInfoBase',
310   'discriminator': 'format',
311   'data': { 'luks': 'QCryptoBlockInfoLUKS' } }
314 # @QCryptoBlockLUKSKeyslotState:
316 # Defines state of keyslots that are affected by the update
318 # @active:    The slots contain the given password and marked as active
319 # @inactive:  The slots are erased (contain garbage) and marked as inactive
321 # Since: 5.1
323 { 'enum': 'QCryptoBlockLUKSKeyslotState',
324   'data': [ 'active', 'inactive' ] }
328 # @QCryptoBlockAmendOptionsLUKS:
330 # This struct defines the update parameters that activate/de-activate set
331 # of keyslots
333 # @state: the desired state of the keyslots
335 # @new-secret:    The ID of a QCryptoSecret object providing the password to be
336 #                 written into added active keyslots
338 # @old-secret:    Optional (for deactivation only)
339 #                 If given will deactivate all keyslots that
340 #                 match password located in QCryptoSecret with this ID
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.
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.
353 #                 For keyslot deactivation, this parameter specifies the exact
354 #                 keyslot to deactivate
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
361 # Since 5.1
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' } }
372 # @QCryptoBlockAmendOptions:
374 # The options that are available for all encryption formats
375 # when amending encryption settings
377 # Since: 5.1
379 { 'union': 'QCryptoBlockAmendOptions',
380   'base': 'QCryptoBlockOptionsBase',
381   'discriminator': 'format',
382   'data': {
383           'luks': 'QCryptoBlockAmendOptionsLUKS' } }