qapi/crypto.json

   1 # -*- Mode: Python -*-
   2 #
   3
   4 ##
   5 # = Cryptography
   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-256'.
 185 # @cipher-mode: the cipher mode for data encryption
 186 #               Currently defaults to 'xts'
 187 # @ivgen-alg: the initialization vector generator
 188 #             Currently defaults to 'plain64'
 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 # @QCryptoBlockInfo:
 302 #
 303 # Information about the block encryption options
 304 #
 305 # Since: 2.7
 306 ##
 307 { 'union': 'QCryptoBlockInfo',
 308   'base': 'QCryptoBlockInfoBase',
 309   'discriminator': 'format',
 310   'data': { 'luks': 'QCryptoBlockInfoLUKS' } }
 311
 312 ##
 313 # @QCryptoBlockLUKSKeyslotState:
 314 #
 315 # Defines state of keyslots that are affected by the update
 316 #
 317 # @active:    The slots contain the given password and marked as active
 318 # @inactive:  The slots are erased (contain garbage) and marked as inactive
 319 #
 320 # Since: 5.1
 321 ##
 322 { 'enum': 'QCryptoBlockLUKSKeyslotState',
 323   'data': [ 'active', 'inactive' ] }
 324
 325
 326 ##
 327 # @QCryptoBlockAmendOptionsLUKS:
 328 #
 329 # This struct defines the update parameters that activate/de-activate set
 330 # of keyslots
 331 #
 332 # @state: the desired state of the keyslots
 333 #
 334 # @new-secret:    The ID of a QCryptoSecret object providing the password to be
 335 #                 written into added active keyslots
 336 #
 337 # @old-secret:    Optional (for deactivation only)
 338 #                 If given will deactive all keyslots that
 339 #                 match password located in QCryptoSecret with this ID
 340 #
 341 # @iter-time:     Optional (for activation only)
 342 #                 Number of milliseconds to spend in
 343 #                 PBKDF passphrase processing for the newly activated keyslot.
 344 #                 Currently defaults to 2000.
 345 #
 346 # @keyslot:       Optional. ID of the keyslot to activate/deactivate.
 347 #                 For keyslot activation, keyslot should not be active already
 348 #                 (this is unsafe to update an active keyslot),
 349 #                 but possible if 'force' parameter is given.
 350 #                 If keyslot is not given, first free keyslot will be written.
 351 #
 352 #                 For keyslot deactivation, this parameter specifies the exact
 353 #                 keyslot to deactivate
 354 #
 355 # @secret:        Optional. The ID of a QCryptoSecret object providing the
 356 #                 password to use to retrive current master key.
 357 #                 Defaults to the same secret that was used to open the image
 358 #
 359 #
 360 # Since 5.1
 361 ##
 362 { 'struct': 'QCryptoBlockAmendOptionsLUKS',
 363   'data': { 'state': 'QCryptoBlockLUKSKeyslotState',
 364             '*new-secret': 'str',
 365             '*old-secret': 'str',
 366             '*keyslot': 'int',
 367             '*iter-time': 'int',
 368             '*secret': 'str' } }
 369
 370 ##
 371 # @QCryptoBlockAmendOptions:
 372 #
 373 # The options that are available for all encryption formats
 374 # when amending encryption settings
 375 #
 376 # Since: 5.1
 377 ##
 378 { 'union': 'QCryptoBlockAmendOptions',
 379   'base': 'QCryptoBlockOptionsBase',
 380   'discriminator': 'format',
 381   'data': {
 382           'luks': 'QCryptoBlockAmendOptionsLUKS' } }