qemu/qapi/crypto.json

# -*- Mode: Python -*-
# vim: filetype=python
#

##
# ************
# Cryptography
# ************
##

##
# @QCryptoTLSCredsEndpoint:
#
# The type of network endpoint that will be using the credentials.
# Most types of credential require different setup / structures
# depending on whether they will be used in a server versus a client.
#
# @client: the network endpoint is acting as the client
#
# @server: the network endpoint is acting as the server
#
# Since: 2.5
##
{ 'enum': 'QCryptoTLSCredsEndpoint',
  'data': ['client', 'server']}

##
# @QCryptoSecretFormat:
#
# The data format that the secret is provided in
#
# @raw: raw bytes.  When encoded in JSON only valid UTF-8 sequences
#     can be used
#
# @base64: arbitrary base64 encoded binary data
#
# Since: 2.6
##
{ 'enum': 'QCryptoSecretFormat',
  'data': ['raw', 'base64']}

##
# @QCryptoHashAlgo:
#
# The supported algorithms for computing content digests
#
# @md5: MD5.  Should not be used in any new code, legacy compat only
#
# @sha1: SHA-1.  Should not be used in any new code, legacy compat only
#
# @sha224: SHA-224.  (since 2.7)
#
# @sha256: SHA-256.  Current recommended strong hash.
#
# @sha384: SHA-384.  (since 2.7)
#
# @sha512: SHA-512.  (since 2.7)
#
# @ripemd160: RIPEMD-160.  (since 2.7)
#
# @sm3: SM3.  (since 9.2.0)
#
# Since: 2.6
##
{ 'enum': 'QCryptoHashAlgo',
  'data': ['md5', 'sha1', 'sha224', 'sha256', 'sha384', 'sha512', 'ripemd160', 'sm3']}

##
# @QCryptoCipherAlgo:
#
# The supported algorithms for content encryption ciphers
#
# @aes-128: AES with 128 bit / 16 byte keys
#
# @aes-192: AES with 192 bit / 24 byte keys
#
# @aes-256: AES with 256 bit / 32 byte keys
#
# @des: DES with 56 bit / 8 byte keys.  Do not use except in VNC.
#     (since 6.1)
#
# @3des: 3DES(EDE) with 192 bit / 24 byte keys (since 2.9)
#
# @cast5-128: Cast5 with 128 bit / 16 byte keys
#
# @serpent-128: Serpent with 128 bit / 16 byte keys
#
# @serpent-192: Serpent with 192 bit / 24 byte keys
#
# @serpent-256: Serpent with 256 bit / 32 byte keys
#
# @twofish-128: Twofish with 128 bit / 16 byte keys
#
# @twofish-192: Twofish with 192 bit / 24 byte keys
#
# @twofish-256: Twofish with 256 bit / 32 byte keys
#
# @sm4: SM4 with 128 bit / 16 byte keys (since 9.0)
#
# Since: 2.6
##
{ 'enum': 'QCryptoCipherAlgo',
  'data': ['aes-128', 'aes-192', 'aes-256',
           'des', '3des',
           'cast5-128',
           'serpent-128', 'serpent-192', 'serpent-256',
           'twofish-128', 'twofish-192', 'twofish-256',
           'sm4']}

##
# @QCryptoCipherMode:
#
# The supported modes for content encryption ciphers
#
# @ecb: Electronic Code Book
#
# @cbc: Cipher Block Chaining
#
# @xts: XEX with tweaked code book and ciphertext stealing
#
# @ctr: Counter (Since 2.8)
#
# Since: 2.6
##
{ 'enum': 'QCryptoCipherMode',
  'data': ['ecb', 'cbc', 'xts', 'ctr']}

##
# @QCryptoIVGenAlgo:
#
# The supported algorithms for generating initialization vectors for
# full disk encryption.  The 'plain' generator should not be used for
# disks with sector numbers larger than 2^32, except where
# compatibility with pre-existing Linux dm-crypt volumes is required.
#
# @plain: 64-bit sector number truncated to 32-bits
#
# @plain64: 64-bit sector number
#
# @essiv: 64-bit sector number encrypted with a hash of the encryption
#     key
#
# Since: 2.6
##
{ 'enum': 'QCryptoIVGenAlgo',
  'data': ['plain', 'plain64', 'essiv']}

##
# @QCryptoBlockFormat:
#
# The supported full disk encryption formats
#
# @qcow: QCow/QCow2 built-in AES-CBC encryption.  Use only for
#     liberating data from old images.
#
# @luks: LUKS encryption format.  Recommended for new images
#
# Since: 2.6
##
{ 'enum': 'QCryptoBlockFormat',
  'data': ['qcow', 'luks']}

##
# @QCryptoBlockOptionsBase:
#
# The common options that apply to all full disk encryption formats
#
# @format: the encryption format
#
# Since: 2.6
##
{ 'struct': 'QCryptoBlockOptionsBase',
  'data': { 'format': 'QCryptoBlockFormat' }}

##
# @QCryptoBlockOptionsQCow:
#
# The options that apply to QCow/QCow2 AES-CBC encryption format
#
# @key-secret: the ID of a QCryptoSecret object providing the
#     decryption key.  Mandatory except when probing image for
#     metadata only.
#
# Since: 2.6
##
{ 'struct': 'QCryptoBlockOptionsQCow',
  'data': { '*key-secret': 'str' }}

##
# @QCryptoBlockOptionsLUKS:
#
# The options that apply to LUKS encryption format
#
# @key-secret: the ID of a QCryptoSecret object providing the
#     decryption key.  Mandatory except when probing image for
#     metadata only.
#
# Since: 2.6
##
{ 'struct': 'QCryptoBlockOptionsLUKS',
  'data': { '*key-secret': 'str' }}

##
# @QCryptoBlockCreateOptionsLUKS:
#
# The options that apply to LUKS encryption format initialization
#
# @cipher-alg: the cipher algorithm for data encryption.  Currently
#     defaults to 'aes-256'.
#
# @cipher-mode: the cipher mode for data encryption.  Currently
#     defaults to 'xts'
#
# @ivgen-alg: the initialization vector generator.  Currently defaults
#     to 'plain64'
#
# @ivgen-hash-alg: the initialization vector generator hash.
#     Currently defaults to 'sha256'
#
# @hash-alg: the master key hash algorithm.  Currently defaults to
#     'sha256'
#
# @iter-time: number of milliseconds to spend in PBKDF passphrase
#     processing.  Currently defaults to 2000.  (since 2.8)
#
# Since: 2.6
##
{ 'struct': 'QCryptoBlockCreateOptionsLUKS',
  'base': 'QCryptoBlockOptionsLUKS',
  'data': { '*cipher-alg': 'QCryptoCipherAlgo',
            '*cipher-mode': 'QCryptoCipherMode',
            '*ivgen-alg': 'QCryptoIVGenAlgo',
            '*ivgen-hash-alg': 'QCryptoHashAlgo',
            '*hash-alg': 'QCryptoHashAlgo',
            '*iter-time': 'int' }}

##
# @QCryptoBlockOpenOptions:
#
# The options that are available for all encryption formats when
# opening an existing volume
#
# Since: 2.6
##
{ 'union': 'QCryptoBlockOpenOptions',
  'base': 'QCryptoBlockOptionsBase',
  'discriminator': 'format',
  'data': { 'qcow': 'QCryptoBlockOptionsQCow',
            'luks': 'QCryptoBlockOptionsLUKS' } }

##
# @QCryptoBlockCreateOptions:
#
# The options that are available for all encryption formats when
# initializing a new volume
#
# Since: 2.6
##
{ 'union': 'QCryptoBlockCreateOptions',
  'base': 'QCryptoBlockOptionsBase',
  'discriminator': 'format',
  'data': { 'qcow': 'QCryptoBlockOptionsQCow',
            'luks': 'QCryptoBlockCreateOptionsLUKS' } }

##
# @QCryptoBlockInfoBase:
#
# The common information that applies to all full disk encryption
# formats
#
# @format: the encryption format
#
# Since: 2.7
##
{ 'struct': 'QCryptoBlockInfoBase',
  'data': { 'format': 'QCryptoBlockFormat' }}

##
# @QCryptoBlockInfoLUKSSlot:
#
# Information about the LUKS block encryption key slot options
#
# @active: whether the key slot is currently in use
#
# @key-offset: offset to the key material in bytes
#
# @iters: number of PBKDF2 iterations for key material
#
# @stripes: number of stripes for splitting key material
#
# Since: 2.7
##
{ 'struct': 'QCryptoBlockInfoLUKSSlot',
  'data': {'active': 'bool',
           '*iters': 'int',
           '*stripes': 'int',
           'key-offset': 'int' } }

##
# @QCryptoBlockInfoLUKS:
#
# Information about the LUKS block encryption options
#
# @cipher-alg: the cipher algorithm for data encryption
#
# @cipher-mode: the cipher mode for data encryption
#
# @ivgen-alg: the initialization vector generator
#
# @ivgen-hash-alg: the initialization vector generator hash
#
# @hash-alg: the master key hash algorithm
#
# @detached-header: whether the LUKS header is detached (Since 9.0)
#
# @payload-offset: offset to the payload data in bytes
#
# @master-key-iters: number of PBKDF2 iterations for key material
#
# @uuid: unique identifier for the volume
#
# @slots: information about each key slot
#
# Since: 2.7
##
{ 'struct': 'QCryptoBlockInfoLUKS',
  'data': {'cipher-alg': 'QCryptoCipherAlgo',
           'cipher-mode': 'QCryptoCipherMode',
           'ivgen-alg': 'QCryptoIVGenAlgo',
           '*ivgen-hash-alg': 'QCryptoHashAlgo',
           'hash-alg': 'QCryptoHashAlgo',
           'detached-header': 'bool',
           'payload-offset': 'int',
           'master-key-iters': 'int',
           'uuid': 'str',
           'slots': [ 'QCryptoBlockInfoLUKSSlot' ] }}

##
# @QCryptoBlockInfo:
#
# Information about the block encryption options
#
# Since: 2.7
##
{ 'union': 'QCryptoBlockInfo',
  'base': 'QCryptoBlockInfoBase',
  'discriminator': 'format',
  'data': { 'luks': 'QCryptoBlockInfoLUKS' } }

##
# @QCryptoBlockLUKSKeyslotState:
#
# Defines state of keyslots that are affected by the update
#
# @active: The slots contain the given password and marked as active
#
# @inactive: The slots are erased (contain garbage) and marked as
#     inactive
#
# Since: 5.1
##
{ 'enum': 'QCryptoBlockLUKSKeyslotState',
  'data': [ 'active', 'inactive' ] }

##
# @QCryptoBlockAmendOptionsLUKS:
#
# This struct defines the update parameters that activate/de-activate
# set of keyslots
#
# @state: the desired state of the keyslots
#
# @new-secret: The ID of a QCryptoSecret object providing the password
#     to be written into added active keyslots
#
# @old-secret: Optional (for deactivation only).  If given will
#     deactivate all keyslots that match password located in
#     QCryptoSecret with this ID
#
# @iter-time: Optional (for activation only).  Number of milliseconds to
#     spend in PBKDF passphrase processing for the newly activated
#     keyslot.  Currently defaults to 2000.
#
# @keyslot: Optional.  ID of the keyslot to activate/deactivate.  For
#     keyslot activation, keyslot should not be active already (this
#     is unsafe to update an active keyslot), but possible if 'force'
#     parameter is given.  If keyslot is not given, first free keyslot
#     will be written.
#
#     For keyslot deactivation, this parameter specifies the exact
#     keyslot to deactivate
#
# @secret: Optional.  The ID of a QCryptoSecret object providing the
#     password to use to retrieve current master key.  Defaults to the
#     same secret that was used to open the image
#
# Since: 5.1
##
{ 'struct': 'QCryptoBlockAmendOptionsLUKS',
  'data': { 'state': 'QCryptoBlockLUKSKeyslotState',
            '*new-secret': 'str',
            '*old-secret': 'str',
            '*keyslot': 'int',
            '*iter-time': 'int',
            '*secret': 'str' } }

##
# @QCryptoBlockAmendOptions:
#
# The options that are available for all encryption formats when
# amending encryption settings
#
# Since: 5.1
##
{ 'union': 'QCryptoBlockAmendOptions',
  'base': 'QCryptoBlockOptionsBase',
  'discriminator': 'format',
  'data': {
          'luks': 'QCryptoBlockAmendOptionsLUKS' } }

##
# @SecretCommonProperties:
#
# Properties for objects of classes derived from secret-common.
#
# @format: the data format that the secret is provided in
#     (default: raw)
#
# @keyid: the name of another secret that should be used to decrypt
#     the provided data.  If not present, the data is assumed to be
#     unencrypted.
#
# @iv: the random initialization vector used for encryption of this
#     particular secret.  Should be a base64 encrypted string of the
#     16-byte IV.  Mandatory if @keyid is given.  Ignored if @keyid is
#     absent.
#
# Since: 2.6
##
{ 'struct': 'SecretCommonProperties',
  'data': { '*format': 'QCryptoSecretFormat',
            '*keyid': 'str',
            '*iv': 'str' } }

##
# @SecretProperties:
#
# Properties for secret objects.
#
# Either @data or @file must be provided, but not both.
#
# @data: the associated with the secret from
#
# @file: the filename to load the data associated with the secret from
#
# Since: 2.6
##
{ 'struct': 'SecretProperties',
  'base': 'SecretCommonProperties',
  'data': { '*data': 'str',
            '*file': 'str' } }

##
# @SecretKeyringProperties:
#
# Properties for secret_keyring objects.
#
# @serial: serial number that identifies a key to get from the kernel
#
# Since: 5.1
##
{ 'struct': 'SecretKeyringProperties',
  'base': 'SecretCommonProperties',
  'data': { 'serial': 'int32' },
  'if': 'CONFIG_SECRET_KEYRING' }

##
# @TlsCredsProperties:
#
# Properties for objects of classes derived from tls-creds.
#
# @verify-peer: if true the peer credentials will be verified once the
#     handshake is completed.  This is a no-op for anonymous
#     credentials.  (default: true)
#
# @dir: the path of the directory that contains the credential files
#
# @endpoint: whether the QEMU network backend that uses the
#     credentials will be acting as a client or as a server
#     (default: client)
#
# @priority: a gnutls priority string as described at
#     https://gnutls.org/manual/html_node/Priority-Strings.html
#
# Since: 2.5
##
{ 'struct': 'TlsCredsProperties',
  'data': { '*verify-peer': 'bool',
            '*dir': 'str',
            '*endpoint': 'QCryptoTLSCredsEndpoint',
            '*priority': 'str' } }

##
# @TlsCredsAnonProperties:
#
# Properties for tls-creds-anon objects.
#
# Since: 2.5
##
{ 'struct': 'TlsCredsAnonProperties',
  'base': 'TlsCredsProperties',
  'data': { } }

##
# @TlsCredsPskProperties:
#
# Properties for tls-creds-psk objects.
#
# @username: the username which will be sent to the server.  For
#     clients only.  If absent, "qemu" is sent and the property will
#     read back as an empty string.
#
# Since: 3.0
##
{ 'struct': 'TlsCredsPskProperties',
  'base': 'TlsCredsProperties',
  'data': { '*username': 'str' } }

##
# @TlsCredsX509Properties:
#
# Properties for tls-creds-x509 objects.
#
# @sanity-check: if true, perform some sanity checks before using the
#     credentials (default: true)
#
# @passwordid: For the server-key.pem and client-key.pem files which
#     contain sensitive private keys, it is possible to use an
#     encrypted version by providing the @passwordid parameter.  This
#     provides the ID of a previously created secret object containing
#     the password for decryption.
#
# Since: 2.5
##
{ 'struct': 'TlsCredsX509Properties',
  'base': 'TlsCredsProperties',
  'data': { '*sanity-check': 'bool',
            '*passwordid': 'str' } }
##
# @QCryptoAkCipherAlgo:
#
# The supported algorithms for asymmetric encryption ciphers
#
# @rsa: RSA algorithm
#
# Since: 7.1
##
{ 'enum': 'QCryptoAkCipherAlgo',
  'data': ['rsa']}

##
# @QCryptoAkCipherKeyType:
#
# The type of asymmetric keys.
#
# @public: public key
#
# @private: private key
#
# Since: 7.1
##
{ 'enum': 'QCryptoAkCipherKeyType',
  'data': ['public', 'private']}

##
# @QCryptoRSAPaddingAlgo:
#
# The padding algorithm for RSA.
#
# @raw: no padding used
#
# @pkcs1: pkcs1#v1.5
#
# Since: 7.1
##
{ 'enum': 'QCryptoRSAPaddingAlgo',
  'data': ['raw', 'pkcs1']}

##
# @QCryptoAkCipherOptionsRSA:
#
# Specific parameters for RSA algorithm.
#
# @hash-alg: `QCryptoHashAlgo`
#
# @padding-alg: `QCryptoRSAPaddingAlgo`
#
# Since: 7.1
##
{ 'struct': 'QCryptoAkCipherOptionsRSA',
  'data': { 'hash-alg':'QCryptoHashAlgo',
            'padding-alg': 'QCryptoRSAPaddingAlgo'}}

##
# @QCryptoAkCipherOptions:
#
# The options that are available for all asymmetric key algorithms
# when creating a new QCryptoAkCipher.
#
# @alg: encryption cipher algorithm
#
# Since: 7.1
##
{ 'union': 'QCryptoAkCipherOptions',
  'base': { 'alg': 'QCryptoAkCipherAlgo' },
  'discriminator': 'alg',
  'data': { 'rsa': 'QCryptoAkCipherOptionsRSA' }}