docs/system/vnc-security.rst

   1 .. _VNC security:
   2
   3 VNC security
   4 ------------
   5
   6 The VNC server capability provides access to the graphical console of
   7 the guest VM across the network. This has a number of security
   8 considerations depending on the deployment scenarios.
   9
  10 .. _vnc_005fsec_005fnone:
  11
  12 Without passwords
  13 ~~~~~~~~~~~~~~~~~
  14
  15 The simplest VNC server setup does not include any form of
  16 authentication. For this setup it is recommended to restrict it to
  17 listen on a UNIX domain socket only. For example
  18
  19 .. parsed-literal::
  20
  21    |qemu_system| [...OPTIONS...] -vnc unix:/home/joebloggs/.qemu-myvm-vnc
  22
  23 This ensures that only users on local box with read/write access to that
  24 path can access the VNC server. To securely access the VNC server from a
  25 remote machine, a combination of netcat+ssh can be used to provide a
  26 secure tunnel.
  27
  28 .. _vnc_005fsec_005fpassword:
  29
  30 With passwords
  31 ~~~~~~~~~~~~~~
  32
  33 The VNC protocol has limited support for password based authentication.
  34 Since the protocol limits passwords to 8 characters it should not be
  35 considered to provide high security. The password can be fairly easily
  36 brute-forced by a client making repeat connections. For this reason, a
  37 VNC server using password authentication should be restricted to only
  38 listen on the loopback interface or UNIX domain sockets. Password
  39 authentication is not supported when operating in FIPS 140-2 compliance
  40 mode as it requires the use of the DES cipher. Password authentication
  41 is requested with the ``password`` option, and then once QEMU is running
  42 the password is set with the monitor. Until the monitor is used to set
  43 the password all clients will be rejected.
  44
  45 .. parsed-literal::
  46
  47    |qemu_system| [...OPTIONS...] -vnc :1,password=on -monitor stdio
  48    (qemu) change vnc password
  49    Password: ********
  50    (qemu)
  51
  52 .. _vnc_005fsec_005fcertificate:
  53
  54 With x509 certificates
  55 ~~~~~~~~~~~~~~~~~~~~~~
  56
  57 The QEMU VNC server also implements the VeNCrypt extension allowing use
  58 of TLS for encryption of the session, and x509 certificates for
  59 authentication. The use of x509 certificates is strongly recommended,
  60 because TLS on its own is susceptible to man-in-the-middle attacks.
  61 Basic x509 certificate support provides a secure session, but no
  62 authentication. This allows any client to connect, and provides an
  63 encrypted session.
  64
  65 .. parsed-literal::
  66
  67    |qemu_system| [...OPTIONS...] \
  68      -object tls-creds-x509,id=tls0,dir=/etc/pki/qemu,endpoint=server,verify-peer=off \
  69      -vnc :1,tls-creds=tls0 -monitor stdio
  70
  71 In the above example ``/etc/pki/qemu`` should contain at least three
  72 files, ``ca-cert.pem``, ``server-cert.pem`` and ``server-key.pem``.
  73 Unprivileged users will want to use a private directory, for example
  74 ``$HOME/.pki/qemu``. NB the ``server-key.pem`` file should be protected
  75 with file mode 0600 to only be readable by the user owning it.
  76
  77 .. _vnc_005fsec_005fcertificate_005fverify:
  78
  79 With x509 certificates and client verification
  80 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  81
  82 Certificates can also provide a means to authenticate the client
  83 connecting. The server will request that the client provide a
  84 certificate, which it will then validate against the CA certificate.
  85 This is a good choice if deploying in an environment with a private
  86 internal certificate authority. It uses the same syntax as previously,
  87 but with ``verify-peer`` set to ``on`` instead.
  88
  89 .. parsed-literal::
  90
  91    |qemu_system| [...OPTIONS...] \
  92      -object tls-creds-x509,id=tls0,dir=/etc/pki/qemu,endpoint=server,verify-peer=on \
  93      -vnc :1,tls-creds=tls0 -monitor stdio
  94
  95 .. _vnc_005fsec_005fcertificate_005fpw:
  96
  97 With x509 certificates, client verification and passwords
  98 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  99
 100 Finally, the previous method can be combined with VNC password
 101 authentication to provide two layers of authentication for clients.
 102
 103 .. parsed-literal::
 104
 105    |qemu_system| [...OPTIONS...] \
 106      -object tls-creds-x509,id=tls0,dir=/etc/pki/qemu,endpoint=server,verify-peer=on \
 107      -vnc :1,tls-creds=tls0,password=on -monitor stdio
 108    (qemu) change vnc password
 109    Password: ********
 110    (qemu)
 111
 112 .. _vnc_005fsec_005fsasl:
 113
 114 With SASL authentication
 115 ~~~~~~~~~~~~~~~~~~~~~~~~
 116
 117 The SASL authentication method is a VNC extension, that provides an
 118 easily extendable, pluggable authentication method. This allows for
 119 integration with a wide range of authentication mechanisms, such as PAM,
 120 GSSAPI/Kerberos, LDAP, SQL databases, one-time keys and more. The
 121 strength of the authentication depends on the exact mechanism
 122 configured. If the chosen mechanism also provides a SSF layer, then it
 123 will encrypt the datastream as well.
 124
 125 Refer to the later docs on how to choose the exact SASL mechanism used
 126 for authentication, but assuming use of one supporting SSF, then QEMU
 127 can be launched with:
 128
 129 .. parsed-literal::
 130
 131    |qemu_system| [...OPTIONS...] -vnc :1,sasl=on -monitor stdio
 132
 133 .. _vnc_005fsec_005fcertificate_005fsasl:
 134
 135 With x509 certificates and SASL authentication
 136 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 137
 138 If the desired SASL authentication mechanism does not supported SSF
 139 layers, then it is strongly advised to run it in combination with TLS
 140 and x509 certificates. This provides securely encrypted data stream,
 141 avoiding risk of compromising of the security credentials. This can be
 142 enabled, by combining the 'sasl' option with the aforementioned TLS +
 143 x509 options:
 144
 145 .. parsed-literal::
 146
 147    |qemu_system| [...OPTIONS...] \
 148      -object tls-creds-x509,id=tls0,dir=/etc/pki/qemu,endpoint=server,verify-peer=on \
 149      -vnc :1,tls-creds=tls0,sasl=on -monitor stdio
 150
 151 .. _vnc_005fsetup_005fsasl:
 152
 153 Configuring SASL mechanisms
 154 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 155
 156 The following documentation assumes use of the Cyrus SASL implementation
 157 on a Linux host, but the principles should apply to any other SASL
 158 implementation or host. When SASL is enabled, the mechanism
 159 configuration will be loaded from system default SASL service config
 160 /etc/sasl2/qemu.conf. If running QEMU as an unprivileged user, an
 161 environment variable SASL_CONF_PATH can be used to make it search
 162 alternate locations for the service config file.
 163
 164 If the TLS option is enabled for VNC, then it will provide session
 165 encryption, otherwise the SASL mechanism will have to provide
 166 encryption. In the latter case the list of possible plugins that can be
 167 used is drastically reduced. In fact only the GSSAPI SASL mechanism
 168 provides an acceptable level of security by modern standards. Previous
 169 versions of QEMU referred to the DIGEST-MD5 mechanism, however, it has
 170 multiple serious flaws described in detail in RFC 6331 and thus should
 171 never be used any more. The SCRAM-SHA-256 mechanism provides a simple
 172 username/password auth facility similar to DIGEST-MD5, but does not
 173 support session encryption, so can only be used in combination with TLS.
 174
 175 When not using TLS the recommended configuration is
 176
 177 ::
 178
 179    mech_list: gssapi
 180    keytab: /etc/qemu/krb5.tab
 181
 182 This says to use the 'GSSAPI' mechanism with the Kerberos v5 protocol,
 183 with the server principal stored in /etc/qemu/krb5.tab. For this to work
 184 the administrator of your KDC must generate a Kerberos principal for the
 185 server, with a name of 'qemu/somehost.example.com@EXAMPLE.COM' replacing
 186 'somehost.example.com' with the fully qualified host name of the machine
 187 running QEMU, and 'EXAMPLE.COM' with the Kerberos Realm.
 188
 189 When using TLS, if username+password authentication is desired, then a
 190 reasonable configuration is
 191
 192 ::
 193
 194    mech_list: scram-sha-256
 195    sasldb_path: /etc/qemu/passwd.db
 196
 197 The ``saslpasswd2`` program can be used to populate the ``passwd.db``
 198 file with accounts. Note that the ``passwd.db`` file stores passwords
 199 in clear text.
 200
 201 Other SASL configurations will be left as an exercise for the reader.
 202 Note that all mechanisms, except GSSAPI, should be combined with use of
 203 TLS to ensure a secure data channel.