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 ##
  29 # @QCryptoSecretFormat:
  30 #
  31 # The data format that the secret is provided in
  32 #
  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
  36 ##
  37 { 'enum': 'QCryptoSecretFormat',
  38   'prefix': 'QCRYPTO_SECRET_FORMAT',
  39   'data': ['raw', 'base64']}
  40
  41
  42 ##
  43 # @QCryptoHashAlgorithm:
  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 # @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
  55 ##
  56 { 'enum': 'QCryptoHashAlgorithm',
  57   'prefix': 'QCRYPTO_HASH_ALG',
  58   'data': ['md5', 'sha1', 'sha224', 'sha256', 'sha384', 'sha512', 'ripemd160']}
  59
  60
  61 ##
  62 # @QCryptoCipherAlgorithm:
  63 #
  64 # The supported algorithms for content encryption ciphers
  65 #
  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: DES with 56 bit / 8 byte keys. Do not use except in VNC. (since 6.1)
  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
  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 ##
  90 # @QCryptoCipherMode:
  91 #
  92 # The supported modes for content encryption ciphers
  93 #
  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
  99 ##
 100 { 'enum': 'QCryptoCipherMode',
 101   'prefix': 'QCRYPTO_CIPHER_MODE',
 102   'data': ['ecb', 'cbc', 'xts', 'ctr']}
 103
 104
 105 ##
 106 # @QCryptoIVGenAlgorithm:
 107 #
 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.
 113 #
 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
 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 # Since: 2.6
 174 ##
 175 { 'struct': 'QCryptoBlockOptionsLUKS',
 176   'data': { '*key-secret': 'str' }}
 177
 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 # Since: 2.6
 198 ##
 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'}}
 207
 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 ##
 225 # @QCryptoBlockCreateOptions:
 226 #
 227 # The options that are available for all encryption formats
 228 # when initializing a new volume
 229 #
 230 # Since: 2.6
 231 ##
 232 { 'union': 'QCryptoBlockCreateOptions',
 233   'base': 'QCryptoBlockOptionsBase',
 234   'discriminator': 'format',
 235   'data': { 'qcow': 'QCryptoBlockOptionsQCow',
 236             'luks': 'QCryptoBlockCreateOptionsLUKS' } }
 237
 238
 239 ##
 240 # @QCryptoBlockInfoBase:
 241 #
 242 # The common information that applies to all full disk
 243 # encryption formats
 244 #
 245 # @format: the encryption format
 246 #
 247 # Since: 2.7
 248 ##
 249 { 'struct': 'QCryptoBlockInfoBase',
 250   'data': { 'format': 'QCryptoBlockFormat' }}
 251
 252
 253 ##
 254 # @QCryptoBlockInfoLUKSSlot:
 255 #
 256 # Information about the LUKS block encryption key
 257 # slot options
 258 #
 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
 263 #
 264 # Since: 2.7
 265 ##
 266 { 'struct': 'QCryptoBlockInfoLUKSSlot',
 267   'data': {'active': 'bool',
 268            '*iters': 'int',
 269            '*stripes': 'int',
 270            'key-offset': 'int' } }
 271
 272
 273 ##
 274 # @QCryptoBlockInfoLUKS:
 275 #
 276 # Information about the LUKS block encryption options
 277 #
 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
 287 #
 288 # Since: 2.7
 289 ##
 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' ] }}
 300
 301 ##
 302 # @QCryptoBlockInfo:
 303 #
 304 # Information about the block encryption options
 305 #
 306 # Since: 2.7
 307 ##
 308 { 'union': 'QCryptoBlockInfo',
 309   'base': 'QCryptoBlockInfoBase',
 310   'discriminator': 'format',
 311   'data': { 'luks': 'QCryptoBlockInfoLUKS' } }
 312
 313 ##
 314 # @QCryptoBlockLUKSKeyslotState:
 315 #
 316 # Defines state of keyslots that are affected by the update
 317 #
 318 # @active:    The slots contain the given password and marked as active
 319 # @inactive:  The slots are erased (contain garbage) and marked as inactive
 320 #
 321 # Since: 5.1
 322 ##
 323 { 'enum': 'QCryptoBlockLUKSKeyslotState',
 324   'data': [ 'active', 'inactive' ] }
 325
 326
 327 ##
 328 # @QCryptoBlockAmendOptionsLUKS:
 329 #
 330 # This struct defines the update parameters that activate/de-activate set
 331 # of keyslots
 332 #
 333 # @state: the desired state of the keyslots
 334 #
 335 # @new-secret:    The ID of a QCryptoSecret object providing the password to be
 336 #                 written into added active keyslots
 337 #
 338 # @old-secret:    Optional (for deactivation only)
 339 #                 If given will deactivate all keyslots that
 340 #                 match password located in QCryptoSecret with this ID
 341 #
 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.
 346 #
 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.
 352 #
 353 #                 For keyslot deactivation, this parameter specifies the exact
 354 #                 keyslot to deactivate
 355 #
 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
 359 #
 360 #
 361 # Since 5.1
 362 ##
 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' } }
 370
 371 ##
 372 # @QCryptoBlockAmendOptions:
 373 #
 374 # The options that are available for all encryption formats
 375 # when amending encryption settings
 376 #
 377 # Since: 5.1
 378 ##
 379 { 'union': 'QCryptoBlockAmendOptions',
 380   'base': 'QCryptoBlockOptionsBase',
 381   'discriminator': 'format',
 382   'data': {
 383           'luks': 'QCryptoBlockAmendOptionsLUKS' } }
 384
 385 ##
 386 # @SecretCommonProperties:
 387 #
 388 # Properties for objects of classes derived from secret-common.
 389 #
 390 # @loaded: if true, the secret is loaded immediately when applying this option
 391 #          and will probably fail when processing the next option. Don't use;
 392 #          only provided for compatibility. (default: false)
 393 #
 394 # @format: the data format that the secret is provided in (default: raw)
 395 #
 396 # @keyid: the name of another secret that should be used to decrypt the
 397 #         provided data. If not present, the data is assumed to be unencrypted.
 398 #
 399 # @iv: the random initialization vector used for encryption of this particular
 400 #      secret. Should be a base64 encrypted string of the 16-byte IV. Mandatory
 401 #      if @keyid is given. Ignored if @keyid is absent.
 402 #
 403 # Features:
 404 # @deprecated: Member @loaded is deprecated.  Setting true doesn't make sense,
 405 #              and false is already the default.
 406 #
 407 # Since: 2.6
 408 ##
 409 { 'struct': 'SecretCommonProperties',
 410   'data': { '*loaded': { 'type': 'bool', 'features': ['deprecated'] },
 411             '*format': 'QCryptoSecretFormat',
 412             '*keyid': 'str',
 413             '*iv': 'str' } }
 414
 415 ##
 416 # @SecretProperties:
 417 #
 418 # Properties for secret objects.
 419 #
 420 # Either @data or @file must be provided, but not both.
 421 #
 422 # @data: the associated with the secret from
 423 #
 424 # @file: the filename to load the data associated with the secret from
 425 #
 426 # Since: 2.6
 427 ##
 428 { 'struct': 'SecretProperties',
 429   'base': 'SecretCommonProperties',
 430   'data': { '*data': 'str',
 431             '*file': 'str' } }
 432
 433 ##
 434 # @SecretKeyringProperties:
 435 #
 436 # Properties for secret_keyring objects.
 437 #
 438 # @serial: serial number that identifies a key to get from the kernel
 439 #
 440 # Since: 5.1
 441 ##
 442 { 'struct': 'SecretKeyringProperties',
 443   'base': 'SecretCommonProperties',
 444   'data': { 'serial': 'int32' } }
 445
 446 ##
 447 # @TlsCredsProperties:
 448 #
 449 # Properties for objects of classes derived from tls-creds.
 450 #
 451 # @verify-peer: if true the peer credentials will be verified once the
 452 #               handshake is completed.  This is a no-op for anonymous
 453 #               credentials. (default: true)
 454 #
 455 # @dir: the path of the directory that contains the credential files
 456 #
 457 # @endpoint: whether the QEMU network backend that uses the credentials will be
 458 #            acting as a client or as a server (default: client)
 459 #
 460 # @priority: a gnutls priority string as described at
 461 #            https://gnutls.org/manual/html_node/Priority-Strings.html
 462 #
 463 # Since: 2.5
 464 ##
 465 { 'struct': 'TlsCredsProperties',
 466   'data': { '*verify-peer': 'bool',
 467             '*dir': 'str',
 468             '*endpoint': 'QCryptoTLSCredsEndpoint',
 469             '*priority': 'str' } }
 470
 471 ##
 472 # @TlsCredsAnonProperties:
 473 #
 474 # Properties for tls-creds-anon objects.
 475 #
 476 # @loaded: if true, the credentials are loaded immediately when applying this
 477 #          option and will ignore options that are processed later. Don't use;
 478 #          only provided for compatibility. (default: false)
 479 #
 480 # Features:
 481 # @deprecated: Member @loaded is deprecated.  Setting true doesn't make sense,
 482 #              and false is already the default.
 483 #
 484 # Since: 2.5
 485 ##
 486 { 'struct': 'TlsCredsAnonProperties',
 487   'base': 'TlsCredsProperties',
 488   'data': { '*loaded': { 'type': 'bool', 'features': ['deprecated'] } } }
 489
 490 ##
 491 # @TlsCredsPskProperties:
 492 #
 493 # Properties for tls-creds-psk objects.
 494 #
 495 # @loaded: if true, the credentials are loaded immediately when applying this
 496 #          option and will ignore options that are processed later. Don't use;
 497 #          only provided for compatibility. (default: false)
 498 #
 499 # @username: the username which will be sent to the server.  For clients only.
 500 #            If absent, "qemu" is sent and the property will read back as an
 501 #            empty string.
 502 #
 503 # Features:
 504 # @deprecated: Member @loaded is deprecated.  Setting true doesn't make sense,
 505 #              and false is already the default.
 506 #
 507 # Since: 3.0
 508 ##
 509 { 'struct': 'TlsCredsPskProperties',
 510   'base': 'TlsCredsProperties',
 511   'data': { '*loaded': { 'type': 'bool', 'features': ['deprecated'] },
 512             '*username': 'str' } }
 513
 514 ##
 515 # @TlsCredsX509Properties:
 516 #
 517 # Properties for tls-creds-x509 objects.
 518 #
 519 # @loaded: if true, the credentials are loaded immediately when applying this
 520 #          option and will ignore options that are processed later. Don't use;
 521 #          only provided for compatibility. (default: false)
 522 #
 523 # @sanity-check: if true, perform some sanity checks before using the
 524 #                credentials (default: true)
 525 #
 526 # @passwordid: For the server-key.pem and client-key.pem files which contain
 527 #              sensitive private keys, it is possible to use an encrypted
 528 #              version by providing the @passwordid parameter.  This provides
 529 #              the ID of a previously created secret object containing the
 530 #              password for decryption.
 531 #
 532 # Features:
 533 # @deprecated: Member @loaded is deprecated.  Setting true doesn't make sense,
 534 #              and false is already the default.
 535 #
 536 # Since: 2.5
 537 ##
 538 { 'struct': 'TlsCredsX509Properties',
 539   'base': 'TlsCredsProperties',
 540   'data': { '*loaded': { 'type': 'bool', 'features': ['deprecated'] },
 541             '*sanity-check': 'bool',
 542             '*passwordid': 'str' } }