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