1.. _secret data: 2 3Providing secret data to QEMU 4----------------------------- 5 6There are a variety of objects in QEMU which require secret data to be provided 7by the administrator or management application. For example, network block 8devices often require a password, LUKS block devices require a passphrase to 9unlock key material, remote desktop services require an access password. 10QEMU has a general purpose mechanism for providing secret data to QEMU in a 11secure manner, using the ``secret`` object type. 12 13At startup this can be done using the ``-object secret,...`` command line 14argument. At runtime this can be done using the ``object_add`` QMP / HMP 15monitor commands. The examples that follow will illustrate use of ``-object`` 16command lines, but they all apply equivalentely in QMP / HMP. When creating 17a ``secret`` object it must be given a unique ID string. This ID is then 18used to identify the object when configuring the thing which need the data. 19 20 21INSECURE: Passing secrets as clear text inline 22~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 23 24**The following should never be done in a production environment or on a 25multi-user host. Command line arguments are usually visible in the process 26listings and are often collected in log files by system monitoring agents 27or bug reporting tools. QMP/HMP commands and their arguments are also often 28logged and attached to bug reports. This all risks compromising secrets that 29are passed inline.** 30 31For the convenience of people debugging / developing with QEMU, it is possible 32to pass secret data inline on the command line. 33 34:: 35 36 -object secret,id=secvnc0,data=87539319 37 38 39Again it is possible to provide the data in base64 encoded format, which is 40particularly useful if the data contains binary characters that would clash 41with argument parsing. 42 43:: 44 45 -object secret,id=secvnc0,data=ODc1MzkzMTk=,format=base64 46 47 48**Note: base64 encoding does not provide any security benefit.** 49 50Passing secrets as clear text via a file 51~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 52 53The simplest approach to providing data securely is to use a file to store 54the secret: 55 56:: 57 58 -object secret,id=secvnc0,file=vnc-password.txt 59 60 61In this example the file ``vnc-password.txt`` contains the plain text secret 62data. It is important to note that the contents of the file are treated as an 63opaque blob. The entire raw file contents is used as the value, thus it is 64important not to mistakenly add any trailing newline character in the file if 65this newline is not intended to be part of the secret data. 66 67In some cases it might be more convenient to pass the secret data in base64 68format and have QEMU decode to get the raw bytes before use: 69 70:: 71 72 -object secret,id=sec0,file=vnc-password.txt,format=base64 73 74 75The file should generally be given mode ``0600`` or ``0400`` permissions, and 76have its user/group ownership set to the same account that the QEMU process 77will be launched under. If using mandatory access control such as SELinux, then 78the file should be labelled to only grant access to the specific QEMU process 79that needs access. This will prevent other processes/users from compromising the 80secret data. 81 82 83Passing secrets as cipher text inline 84~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 85 86To address the insecurity of passing secrets inline as clear text, it is 87possible to configure a second secret as an AES key to use for decrypting 88the data. 89 90The secret used as the AES key must always be configured using the file based 91storage mechanism: 92 93:: 94 95 -object secret,id=secmaster,file=masterkey.data,format=base64 96 97 98In this case the ``masterkey.data`` file would be initialized with 32 99cryptographically secure random bytes, which are then base64 encoded. 100The contents of this file will by used as an AES-256 key to encrypt the 101real secret that can now be safely passed to QEMU inline as cipher text 102 103:: 104 105 -object secret,id=secvnc0,keyid=secmaster,data=BASE64-CIPHERTEXT,iv=BASE64-IV,format=base64 106 107 108In this example ``BASE64-CIPHERTEXT`` is the result of AES-256-CBC encrypting 109the secret with ``masterkey.data`` and then base64 encoding the ciphertext. 110The ``BASE64-IV`` data is 16 random bytes which have been base64 encrypted. 111These bytes are used as the initialization vector for the AES-256-CBC value. 112 113A single master key can be used to encrypt all subsequent secrets, **but it is 114critical that a different initialization vector is used for every secret**. 115 116Passing secrets via the Linux keyring 117~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 118 119The earlier mechanisms described are platform agnostic. If using QEMU on a Linux 120host, it is further possible to pass secrets to QEMU using the Linux keyring: 121 122:: 123 124 -object secret_keyring,id=secvnc0,serial=1729 125 126 127This instructs QEMU to load data from the Linux keyring secret identified by 128the serial number ``1729``. It is possible to combine use of the keyring with 129other features mentioned earlier such as base64 encoding: 130 131:: 132 133 -object secret_keyring,id=secvnc0,serial=1729,format=base64 134 135 136and also encryption with a master key: 137 138:: 139 140 -object secret_keyring,id=secvnc0,keyid=secmaster,serial=1729,iv=BASE64-IV 141 142 143Best practice 144~~~~~~~~~~~~~ 145 146It is recommended for production deployments to use a master key secret, and 147then pass all subsequent inline secrets encrypted with the master key. 148 149Each QEMU instance must have a distinct master key, and that must be generated 150from a cryptographically secure random data source. The master key should be 151deleted immediately upon QEMU shutdown. If passing the master key as a file, 152the key file must have access control rules applied that restrict access to 153just the one QEMU process that is intended to use it. Alternatively the Linux 154keyring can be used to pass the master key to QEMU. 155 156The secrets for individual QEMU device backends must all then be encrypted 157with this master key. 158 159This procedure helps ensure that the individual secrets for QEMU backends will 160not be compromised, even if ``-object`` CLI args or ``object_add`` monitor 161commands are collected in log files and attached to public bug support tickets. 162The only item that needs strongly protecting is the master key file. 163