Merge remote-tracking branch 'remotes/armbru/tags/pull-qapi-2017-03-16' into staging
[qemu.git] / qapi / crypto.json
1 # -*- Mode: Python -*-
2 #
3
4 ##
5 # = QAPI crypto definitions
6 ##
7
8 ##
9 # @QCryptoTLSCredsEndpoint:
10 #
11 # The type of network endpoint that will be using the credentials.
12 # Most types of credential require different setup / structures
13 # depending on whether they will be used in a server versus a
14 # 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']}
25
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 # Since: 2.6
35 ##
36 { 'enum': 'QCryptoSecretFormat',
37   'prefix': 'QCRYPTO_SECRET_FORMAT',
38   'data': ['raw', 'base64']}
39
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 # Since: 2.6
54 ##
55 { 'enum': 'QCryptoHashAlgorithm',
56   'prefix': 'QCRYPTO_HASH_ALG',
57   'data': ['md5', 'sha1', 'sha224', 'sha256', 'sha384', 'sha512', 'ripemd160']}
58
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-rfb: RFB specific variant of single DES. Do not use except in VNC.
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 # Since: 2.6
78 ##
79 { 'enum': 'QCryptoCipherAlgorithm',
80   'prefix': 'QCRYPTO_CIPHER_ALG',
81   'data': ['aes-128', 'aes-192', 'aes-256',
82            'des-rfb', '3des',
83            'cast5-128',
84            'serpent-128', 'serpent-192', 'serpent-256',
85            'twofish-128', 'twofish-192', 'twofish-256']}
86
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 # Since: 2.6
98 ##
99 { 'enum': 'QCryptoCipherMode',
100   'prefix': 'QCRYPTO_CIPHER_MODE',
101   'data': ['ecb', 'cbc', 'xts', 'ctr']}
102
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 # Since: 2.6
117 ##
118 { 'enum': 'QCryptoIVGenAlgorithm',
119   'prefix': 'QCRYPTO_IVGEN_ALG',
120   'data': ['plain', 'plain64', 'essiv']}
121
122 ##
123 # @QCryptoBlockFormat:
124 #
125 # The supported full disk encryption formats
126 #
127 # @qcow: QCow/QCow2 built-in AES-CBC encryption. Use only
128 #        for liberating data from old images.
129 # @luks: LUKS encryption format. Recommended for new images
130 #
131 # Since: 2.6
132 ##
133 { 'enum': 'QCryptoBlockFormat',
134 #  'prefix': 'QCRYPTO_BLOCK_FORMAT',
135   'data': ['qcow', 'luks']}
136
137 ##
138 # @QCryptoBlockOptionsBase:
139 #
140 # The common options that apply to all full disk
141 # encryption formats
142 #
143 # @format: the encryption format
144 #
145 # Since: 2.6
146 ##
147 { 'struct': 'QCryptoBlockOptionsBase',
148   'data': { 'format': 'QCryptoBlockFormat' }}
149
150 ##
151 # @QCryptoBlockOptionsQCow:
152 #
153 # The options that apply to QCow/QCow2 AES-CBC encryption format
154 #
155 # @key-secret: the ID of a QCryptoSecret object providing the
156 #              decryption key. Mandatory except when probing image for
157 #              metadata only.
158 #
159 # Since: 2.6
160 ##
161 { 'struct': 'QCryptoBlockOptionsQCow',
162   'data': { '*key-secret': 'str' }}
163
164 ##
165 # @QCryptoBlockOptionsLUKS:
166 #
167 # The options that apply to LUKS encryption format
168 #
169 # @key-secret: the ID of a QCryptoSecret object providing the
170 #              decryption key. Mandatory except when probing image for
171 #              metadata only.
172 # Since: 2.6
173 ##
174 { 'struct': 'QCryptoBlockOptionsLUKS',
175   'data': { '*key-secret': 'str' }}
176
177
178 ##
179 # @QCryptoBlockCreateOptionsLUKS:
180 #
181 # The options that apply to LUKS encryption format initialization
182 #
183 # @cipher-alg: the cipher algorithm for data encryption
184 #              Currently defaults to 'aes'.
185 # @cipher-mode: the cipher mode for data encryption
186 #               Currently defaults to 'cbc'
187 # @ivgen-alg: the initialization vector generator
188 #             Currently defaults to 'essiv'
189 # @ivgen-hash-alg: the initialization vector generator hash
190 #                  Currently defaults to 'sha256'
191 # @hash-alg: the master key hash algorithm
192 #            Currently defaults to 'sha256'
193 # @iter-time: number of milliseconds to spend in
194 #             PBKDF passphrase processing. Currently defaults
195 #             to 2000. (since 2.8)
196 # Since: 2.6
197 ##
198 { 'struct': 'QCryptoBlockCreateOptionsLUKS',
199   'base': 'QCryptoBlockOptionsLUKS',
200   'data': { '*cipher-alg': 'QCryptoCipherAlgorithm',
201             '*cipher-mode': 'QCryptoCipherMode',
202             '*ivgen-alg': 'QCryptoIVGenAlgorithm',
203             '*ivgen-hash-alg': 'QCryptoHashAlgorithm',
204             '*hash-alg': 'QCryptoHashAlgorithm',
205             '*iter-time': 'int'}}
206
207
208 ##
209 # @QCryptoBlockOpenOptions:
210 #
211 # The options that are available for all encryption formats
212 # when opening an existing volume
213 #
214 # Since: 2.6
215 ##
216 { 'union': 'QCryptoBlockOpenOptions',
217   'base': 'QCryptoBlockOptionsBase',
218   'discriminator': 'format',
219   'data': { 'qcow': 'QCryptoBlockOptionsQCow',
220             'luks': 'QCryptoBlockOptionsLUKS' } }
221
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 ##
239 # @QCryptoBlockInfoBase:
240 #
241 # The common information that applies to all full disk
242 # encryption formats
243 #
244 # @format: the encryption format
245 #
246 # Since: 2.7
247 ##
248 { 'struct': 'QCryptoBlockInfoBase',
249   'data': { 'format': 'QCryptoBlockFormat' }}
250
251
252 ##
253 # @QCryptoBlockInfoLUKSSlot:
254 #
255 # Information about the LUKS block encryption key
256 # slot options
257 #
258 # @active: whether the key slot is currently in use
259 # @key-offset: offset to the key material in bytes
260 # @iters: number of PBKDF2 iterations for key material
261 # @stripes: number of stripes for splitting key material
262 #
263 # Since: 2.7
264 ##
265 { 'struct': 'QCryptoBlockInfoLUKSSlot',
266   'data': {'active': 'bool',
267            '*iters': 'int',
268            '*stripes': 'int',
269            'key-offset': 'int' } }
270
271
272 ##
273 # @QCryptoBlockInfoLUKS:
274 #
275 # Information about the LUKS block encryption options
276 #
277 # @cipher-alg: the cipher algorithm for data encryption
278 # @cipher-mode: the cipher mode for data encryption
279 # @ivgen-alg: the initialization vector generator
280 # @ivgen-hash-alg: the initialization vector generator hash
281 # @hash-alg: the master key hash algorithm
282 # @payload-offset: offset to the payload data in bytes
283 # @master-key-iters: number of PBKDF2 iterations for key material
284 # @uuid: unique identifier for the volume
285 # @slots: information about each key slot
286 #
287 # Since: 2.7
288 ##
289 { 'struct': 'QCryptoBlockInfoLUKS',
290   'data': {'cipher-alg': 'QCryptoCipherAlgorithm',
291            'cipher-mode': 'QCryptoCipherMode',
292            'ivgen-alg': 'QCryptoIVGenAlgorithm',
293            '*ivgen-hash-alg': 'QCryptoHashAlgorithm',
294            'hash-alg': 'QCryptoHashAlgorithm',
295            'payload-offset': 'int',
296            'master-key-iters': 'int',
297            'uuid': 'str',
298            'slots': [ 'QCryptoBlockInfoLUKSSlot' ] }}
299
300 ##
301 # @QCryptoBlockInfoQCow:
302 #
303 # Information about the QCow block encryption options
304 #
305 # Since: 2.7
306 ##
307 { 'struct': 'QCryptoBlockInfoQCow',
308   'data': { }}
309
310
311 ##
312 # @QCryptoBlockInfo:
313 #
314 # Information about the block encryption options
315 #
316 # Since: 2.7
317 ##
318 { 'union': 'QCryptoBlockInfo',
319   'base': 'QCryptoBlockInfoBase',
320   'discriminator': 'format',
321   'data': { 'qcow': 'QCryptoBlockInfoQCow',
322             'luks': 'QCryptoBlockInfoLUKS' } }