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