* [PATCH 0/4] docs: add user facing docs for secret passing and authorization controls
@ 2021-05-14 17:31 Daniel P. Berrangé
2021-05-14 17:31 ` [PATCH 1/4] docs: document how to pass secret data to QEMU Daniel P. Berrangé
` (4 more replies)
0 siblings, 5 replies; 8+ messages in thread
From: Daniel P. Berrangé @ 2021-05-14 17:31 UTC (permalink / raw)
To: qemu-devel; +Cc: Daniel P. Berrangé
These are an important of the overall QEMU network backend security
controls but never previously documented aside from in blog posts.
Daniel P. Berrangé (4):
docs: document how to pass secret data to QEMU
docs: document usage of the authorization framework
docs: recommend SCRAM-SHA-256 SASL mech instead of SHA-1 variant
sasl: remove comment about obsolete kerberos versions
docs/system/authz.rst | 263 +++++++++++++++++++++++++++++++++++
docs/system/index.rst | 2 +
docs/system/secrets.rst | 162 +++++++++++++++++++++
docs/system/vnc-security.rst | 7 +-
qemu.sasl | 15 +-
5 files changed, 437 insertions(+), 12 deletions(-)
create mode 100644 docs/system/authz.rst
create mode 100644 docs/system/secrets.rst
--
2.31.1
^ permalink raw reply [flat|nested] 8+ messages in thread
* [PATCH 1/4] docs: document how to pass secret data to QEMU
2021-05-14 17:31 [PATCH 0/4] docs: add user facing docs for secret passing and authorization controls Daniel P. Berrangé
@ 2021-05-14 17:31 ` Daniel P. Berrangé
2021-05-14 17:31 ` [PATCH 2/4] docs: document usage of the authorization framework Daniel P. Berrangé
` (3 subsequent siblings)
4 siblings, 0 replies; 8+ messages in thread
From: Daniel P. Berrangé @ 2021-05-14 17:31 UTC (permalink / raw)
To: qemu-devel; +Cc: Daniel P. Berrangé
Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
---
docs/system/index.rst | 1 +
docs/system/secrets.rst | 162 ++++++++++++++++++++++++++++++++++++++++
2 files changed, 163 insertions(+)
create mode 100644 docs/system/secrets.rst
diff --git a/docs/system/index.rst b/docs/system/index.rst
index b05af716a9..6aa2f8c05c 100644
--- a/docs/system/index.rst
+++ b/docs/system/index.rst
@@ -30,6 +30,7 @@ Contents:
guest-loader
vnc-security
tls
+ secrets
gdb
managed-startup
cpu-hotplug
diff --git a/docs/system/secrets.rst b/docs/system/secrets.rst
new file mode 100644
index 0000000000..4a177369b6
--- /dev/null
+++ b/docs/system/secrets.rst
@@ -0,0 +1,162 @@
+.. _secret data:
+
+Providing secret data to QEMU
+-----------------------------
+
+There are a variety of objects in QEMU which require secret data to be provided
+by the administrator or management application. For example, network block
+devices often require a password, LUKS block devices require a passphrase to
+unlock key material, remote desktop services require an access password.
+QEMU has a general purpose mechanism for providing secret data to QEMU in a
+secure manner, using the ``secret`` object type.
+
+At startup this can be done using the ``-object secret,...`` command line
+argument. At runtime this can be done using the ``object_add`` QMP / HMP
+monitor commands. The examples that follow will illustrate use of ``-object``
+command lines, but they all apply equivalentely in QMP / HMP. When creating
+a ``secret`` object it must be given a unique ID string. This ID is then
+used to identify the object when configuring the thing which need the data.
+
+
+INSECURE: Passing secrets as clear text inline
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+**The following should never be done in a production environment or on a
+multi-user host. Command line arguments are usually visible in the process
+listings and are often collected in log files by system monitoring agents
+or bug reporting tools. QMP/HMP commands and their arguments are also often
+logged and attached to bug reports. This all risks compromising secrets that
+are passed inline.**
+
+For the convenience of people debugging / developing with QEMU, it is possible
+to pass secret data inline on the command line.
+
+::
+
+ -object secret,id=secvnc0,data=87539319
+
+
+Again it is possible to provide the data in base64 encoded format, which is
+particularly useful if the data contains binary characters that would clash
+with argument parsing.
+
+::
+
+ -object secret,id=secvnc0,data=ODc1MzkzMTk=,format=base64
+
+
+**Note: base64 encoding does not provide any security benefit.**
+
+Passing secrets as clear text via a file
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The simplest approach to providing data securely is to use a file to store
+the secret:
+
+::
+
+ -object secret,id=secvnc0,file=vnc-password.txt
+
+
+In this example the file ``vnc-password.txt`` contains the plain text secret
+data. It is important to note that the contents of the file are treated as an
+opaque blob. The entire raw file contents is used as the value, thus it is
+important not to mistakenly add any trailing newline character in the file if
+this newline is not intended to be part of the secret data.
+
+In some cases it might be more convenient to pass the secret data in base64
+format and have QEMU decode to get the raw bytes before use:
+
+::
+
+ -object secret,id=sec0,file=vnc-password.txt,format=base64
+
+
+The file should generally be given mode ``0600`` or ``0400`` permissions, and
+have its user/group ownership set to the same account that the QEMU process
+will be launched under. If using mandatory access control such as SELinux, then
+the file should be labelled to only grant access to the specific QEMU process
+that needs access. This will prevent other processes/users from compromising the
+secret data.
+
+
+Passing secrets as cipher text inline
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To address the insecurity of passing secrets inline as clear text, it is
+possible to configure a second secret as an AES key to use for decrypting
+the data.
+
+The secret used as the AES key must always be configured using the file based
+storage mechanism:
+
+::
+
+ -object secret,id=secmaster,file=masterkey.data,format=base64
+
+
+In this case the ``masterkey.data`` file would be initialized with 32
+cryptographically secure random bytes, which are then base64 encoded.
+The contents of this file will by used as an AES-256 key to encrypt the
+real secret that can now be safely passed to QEMU inline as cipher text
+
+::
+
+ -object secret,id=secvnc0,keyid=secmaster,data=BASE64-CIPHERTEXT,iv=BASE64-IV,format=base64
+
+
+In this example ``BASE64-CIPHERTEXT`` is the result of AES-256-CBC encrypting
+the secret with ``masterkey.data`` and then base64 encoding the ciphertext.
+The ``BASE64-IV`` data is 16 random bytes which have been base64 encrypted.
+These bytes are used as the initialization vector for the AES-256-CBC value.
+
+A single master key can be used to encrypt all subsequent secrets, **but it is
+critical that a different initialization vector is used for every secret**.
+
+Passing secrets via the Linux keyring
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The earlier mechanisms described are platform agnostic. If using QEMU on a Linux
+host, it is further possible to pass secrets to QEMU using the Linux keyring:
+
+::
+
+ -object secret_keyring,id=secvnc0,serial=1729
+
+
+This instructs QEMU to load data from the Linux keyring secret identified by
+the serial number ``1729``. It is possible to combine use of the keyring with
+other features mentioned earlier such as base64 encoding:
+
+::
+
+ -object secret_keyring,id=secvnc0,serial=1729,format=base64
+
+
+and also encryption with a master key:
+
+::
+
+ -object secret_keyring,id=secvnc0,keyid=secmaster,serial=1729,iv=BASE64-IV
+
+
+Best practice
+~~~~~~~~~~~~~
+
+It is recommended for production deployments to use a master key secret, and
+then pass all subsequent inline secrets encrypted with the master key.
+
+Each QEMU instance must have a distinct master key, and that must be generated
+from a cryptographically secure random data source. The master key should be
+deleted immediately upon QEMU shutdown. If passing the master key as a file,
+the key file must have access control rules applied that restrict access to
+just the one QEMU process that is intended to use it. Alternatively the Linux
+keyring can be used to pass the master key to QEMU.
+
+The secrets for individual QEMU device backends must all then be encrypted
+with this master key.
+
+This procedure helps ensure that the individual secrets for QEMU backends will
+not be compromised, even if ``-object`` CLI args or ``object_add`` monitor
+commands are collected in log files and attached to public bug support tickets.
+The only item that needs strongly protecting is the master key file.
--
2.31.1
^ permalink raw reply related [flat|nested] 8+ messages in thread
* [PATCH 2/4] docs: document usage of the authorization framework
2021-05-14 17:31 [PATCH 0/4] docs: add user facing docs for secret passing and authorization controls Daniel P. Berrangé
2021-05-14 17:31 ` [PATCH 1/4] docs: document how to pass secret data to QEMU Daniel P. Berrangé
@ 2021-05-14 17:31 ` Daniel P. Berrangé
2021-06-04 11:26 ` Marc-André Lureau
2021-05-14 17:31 ` [PATCH 3/4] docs: recommend SCRAM-SHA-256 SASL mech instead of SHA-1 variant Daniel P. Berrangé
` (2 subsequent siblings)
4 siblings, 1 reply; 8+ messages in thread
From: Daniel P. Berrangé @ 2021-05-14 17:31 UTC (permalink / raw)
To: qemu-devel; +Cc: Daniel P. Berrangé
The authorization framework provides a way to control access to network
services after a client has been authenticated. This documents how to
actually use it.
Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
---
docs/system/authz.rst | 263 ++++++++++++++++++++++++++++++++++++++++++
docs/system/index.rst | 1 +
2 files changed, 264 insertions(+)
create mode 100644 docs/system/authz.rst
diff --git a/docs/system/authz.rst b/docs/system/authz.rst
new file mode 100644
index 0000000000..2276546d23
--- /dev/null
+++ b/docs/system/authz.rst
@@ -0,0 +1,263 @@
+.. _client authorization:
+
+Client authorization
+--------------------
+
+When configuring a QEMU network backend with either TLS certificates or SASL
+authentication, access will be granted if the client successfully proves
+their identity. If the authorization identity database is scoped to the QEMU
+client this may be sufficient. It is common, however, for the identity database
+to be much broader and thus authentication alone does not enable sufficient
+access control. In this case QEMU provides a flexible system for enforcing
+finer grained authorization on clients post-authentication.
+
+Identity providers
+~~~~~~~~~~~~~~~~~~
+
+At the time of writing there are two authentication frameworks used by QEMU
+that emit an identity upon completion.
+
+ * TLS x509 certificate distinguished name.
+
+ When configuring the QEMU backend as a network server with TLS, there
+ are a choice of credentials to use. The most common scenario is to utilize
+ x509 certificates. The simplest configuration only involves issuing
+ certificates to the servers, allowing the client to avoid a MITM attack
+ against their intended server.
+
+ It is possible, however, to enable mutual verification by requiring that
+ the client provide a certificate to the server to prove its own identity.
+ This is done by setting the property ``verify-peer=yes`` on the
+ ``tls-creds-x509`` object, which is in fact the default.
+
+ When peer verification is enabled, client will need to be issued with a
+ certificate by the same certificate authority as the server. If this is
+ still not sufficiently strong access control the Distinguished Name of
+ the certificate can be used as an identity in the QEMU authorization
+ framework.
+
+ * SASL username.
+
+ When configuring the QEMU backend as a network server with SASL, upon
+ completion of the SASL authentication mechanism, a username will be
+ provided. The format of this username will vary depending on the choice
+ of mechanism configured for SASL. It might be a simple UNIX style user
+ ``joebloggs``, while if using Kerberos/GSSAPI it can have a realm
+ attached ``joebloggs@QEMU.ORG``. Whatever format the username is presented
+ in, it can be used with the QEMU authorization framework.
+
+Authorization drivers
+~~~~~~~~~~~~~~~~~~~~~
+
+The QEMU authorization framework is a general purpose design with choice of
+user customizable drivers. These are provided as objects that can be
+created at startup using the ``-object`` argument, or at runtime using the
+``object_add`` monitor command.
+
+Simple
+^^^^^^
+
+This authorization driver provides a simple mechanism for granting access
+based on an exact match against a single identity. This is useful when it is
+known that only a single client is to be allowed access.
+
+A possible use case would be when configuring QEMU for an incoming live
+migration. It is known exactly which source QEMU the migration is expected
+to arrive from. The x509 certificate associated with this source QEMU would
+thus be used as the identity to match against. Alternatively if the virtual
+machine is dedicated to a specific tenant, then the VNC server would be
+configured with SASL and the username of only that tenant listed.
+
+To create an instance of this driver via QMP:
+
+::
+
+ {
+ "execute": "object-add",
+ "arguments": {
+ "qom-type": "authz-simple",
+ "id": "authz0",
+ "props": {
+ "identity": "fred"
+ }
+ }
+ }
+
+
+Or via the command line
+
+::
+
+ -object authz-simple,id=authz0,identity=fred
+
+
+List
+^^^^
+
+In some network backends it will be desirable to grant access to a range of
+clients. This authorization driver provides a list mechanism for granting
+access by matching identities against a list of permitted one. Each match
+rule has an associated policy and a catch all policy applies if no rule
+matches. The match can either be done as an exact string comparison, or can
+use the shell-like glob syntax, which allows for use of wildcards.
+
+To create an instance of this class via QMP:
+
+::
+
+ {
+ "execute": "object-add",
+ "arguments": {
+ "qom-type": "authz-list",
+ "id": "authz0",
+ "props": {
+ "rules": [
+ { "match": "fred", "policy": "allow", "format": "exact" },
+ { "match": "bob", "policy": "allow", "format": "exact" },
+ { "match": "danb", "policy": "deny", "format": "exact" },
+ { "match": "dan*", "policy": "allow", "format": "glob" }
+ ],
+ "policy": "deny"
+ }
+ }
+ }
+
+
+Due to the way this driver requires setting nested properties, creating
+it on the command line will require use of the JSON syntax for ``-object``.
+In most cases, however, the next driver will be more suitable.
+
+List file
+^^^^^^^^^
+
+This is a variant on the previous driver that allows for a more dynamic
+access control policy by storing the match rules in a standalone file
+that can be reloaded automatically upon change.
+
+To create an instance of this class via QMP:
+
+::
+
+ {
+ "execute": "object-add",
+ "arguments": {
+ "qom-type": "authz-list-file",
+ "id": "authz0",
+ "props": {
+ "filename": "/etc/qemu/myvm-vnc.acl",
+ "refresh": true
+ }
+ }
+ }
+
+
+If ``refresh`` is ``yes``, inotify is used to monitor for changes
+to the file and auto-reload the rules.
+
+The ``myvm-vnc.acl`` file should contain the match rules in a format that
+closely matches the previous driver:
+
+::
+
+ {
+ "rules": [
+ { "match": "fred", "policy": "allow", "format": "exact" },
+ { "match": "bob", "policy": "allow", "format": "exact" },
+ { "match": "danb", "policy": "deny", "format": "exact" },
+ { "match": "dan*", "policy": "allow", "format": "glob" }
+ ],
+ "policy": "deny"
+ }
+
+
+The object can be created on the command line using
+
+::
+
+ -object authz-list-file,id=authz0,\
+ filename=/etc/qemu/myvm-vnc.acl,refresh=on
+
+
+PAM
+^^^
+
+In some scenarios it might be desirable to integrate with authorization
+mechanisms that are implemented outside of QEMU. In order to allow maximum
+flexibility, QEMU provides a driver that uses the ``PAM`` framework.
+
+To create an instance of this class via QMP:
+
+::
+
+ {
+ "execute": "object-add",
+ "arguments": {
+ "qom-type": "authz-pam",
+ "id": "authz0",
+ "parameters": {
+ "service": "qemu-vnc-tls"
+ }
+ }
+ }
+
+
+The driver only uses the PAM "account" verification
+subsystem. The above config would require a config
+file /etc/pam.d/qemu-vnc-tls. For a simple file
+lookup it would contain
+
+::
+
+ account requisite pam_listfile.so item=user sense=allow \
+ file=/etc/qemu/vnc.allow
+
+
+The external file would then contain a list of usernames.
+If x509 cert was being used as the username, a suitable
+entry would match the distinguished name:
+
+::
+
+ CN=laptop.berrange.com,O=Berrange Home,L=London,ST=London,C=GB
+
+
+On the command line it can be created using
+
+::
+
+ -object authz-pam,id=authz0,service=qemu-vnc-tls
+
+
+There are a variety of PAM plugins that can be used which are not illustrated
+here, and it is possible to implement brand new plugins using the PAM API.
+
+
+Connecting backends
+~~~~~~~~~~~~~~~~~~~
+
+The authorization driver is created using the ``-object`` argument and then
+needs to be associated with a network service. The authorization driver object
+will be given a unique ID that needs to be referenced.
+
+The property to set in the network service will vary depending on the type of
+identity to verify. By convention, any network server backend that uses TLS
+will provide ``tls-authz`` property, while any server using SASL will provide
+a ``sasl-authz`` property.
+
+Thus a example using SASL and authorization for the VNC server would look
+like:
+
+::
+
+ $QEMU --object authz-simple,id=authz0,identity=fred \
+ --vnc 0.0.0.0:1,sasl,sasl-authz=authz0
+
+While to validate both the x509 certificate and SASL username:
+
+::
+
+ echo "CN=laptop.qemu.org,O=QEMU Project,L=London,ST=London,C=GB" >> tls.acl
+ $QEMU --object authz-simple,id=authz0,identity=fred \
+ --object authz-list-file,id=authz1,filename=tls.acl \
+ --object tls-creds-x509,id=tls0,dir=/etc/qemu/tls,verify-peer=yes \
+ --vnc 0.0.0.0:1,sasl,sasl-authz=auth0,tls-creds=tls0,tls-authz=authz1
diff --git a/docs/system/index.rst b/docs/system/index.rst
index 6aa2f8c05c..6092eb2d91 100644
--- a/docs/system/index.rst
+++ b/docs/system/index.rst
@@ -31,6 +31,7 @@ Contents:
vnc-security
tls
secrets
+ authz
gdb
managed-startup
cpu-hotplug
--
2.31.1
^ permalink raw reply related [flat|nested] 8+ messages in thread
* [PATCH 3/4] docs: recommend SCRAM-SHA-256 SASL mech instead of SHA-1 variant
2021-05-14 17:31 [PATCH 0/4] docs: add user facing docs for secret passing and authorization controls Daniel P. Berrangé
2021-05-14 17:31 ` [PATCH 1/4] docs: document how to pass secret data to QEMU Daniel P. Berrangé
2021-05-14 17:31 ` [PATCH 2/4] docs: document usage of the authorization framework Daniel P. Berrangé
@ 2021-05-14 17:31 ` Daniel P. Berrangé
2021-05-14 17:31 ` [PATCH 4/4] sasl: remove comment about obsolete kerberos versions Daniel P. Berrangé
2021-06-04 8:43 ` [PATCH 0/4] docs: add user facing docs for secret passing and authorization controls Daniel P. Berrangé
4 siblings, 0 replies; 8+ messages in thread
From: Daniel P. Berrangé @ 2021-05-14 17:31 UTC (permalink / raw)
To: qemu-devel; +Cc: Daniel P. Berrangé
The SHA-256 variant better meats modern security expectations.
Also warn that the password file is storing entries in clear
text.
Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
---
docs/system/vnc-security.rst | 7 ++++---
qemu.sasl | 11 ++++++-----
2 files changed, 10 insertions(+), 8 deletions(-)
diff --git a/docs/system/vnc-security.rst b/docs/system/vnc-security.rst
index 830f6acc73..4c1769eeb8 100644
--- a/docs/system/vnc-security.rst
+++ b/docs/system/vnc-security.rst
@@ -168,7 +168,7 @@ used is drastically reduced. In fact only the GSSAPI SASL mechanism
provides an acceptable level of security by modern standards. Previous
versions of QEMU referred to the DIGEST-MD5 mechanism, however, it has
multiple serious flaws described in detail in RFC 6331 and thus should
-never be used any more. The SCRAM-SHA-1 mechanism provides a simple
+never be used any more. The SCRAM-SHA-256 mechanism provides a simple
username/password auth facility similar to DIGEST-MD5, but does not
support session encryption, so can only be used in combination with TLS.
@@ -191,11 +191,12 @@ reasonable configuration is
::
- mech_list: scram-sha-1
+ mech_list: scram-sha-256
sasldb_path: /etc/qemu/passwd.db
The ``saslpasswd2`` program can be used to populate the ``passwd.db``
-file with accounts.
+file with accounts. Note that the ``passwd.db`` file stores passwords
+in clear text.
Other SASL configurations will be left as an exercise for the reader.
Note that all mechanisms, except GSSAPI, should be combined with use of
diff --git a/qemu.sasl b/qemu.sasl
index fb8a92ba58..abdfc686be 100644
--- a/qemu.sasl
+++ b/qemu.sasl
@@ -19,15 +19,15 @@ mech_list: gssapi
# If using TLS with VNC, or a UNIX socket only, it is possible to
# enable plugins which don't provide session encryption. The
-# 'scram-sha-1' plugin allows plain username/password authentication
+# 'scram-sha-256' plugin allows plain username/password authentication
# to be performed
#
-#mech_list: scram-sha-1
+#mech_list: scram-sha-256
# You can also list many mechanisms at once, and the VNC server will
# negotiate which to use by considering the list enabled on the VNC
# client.
-#mech_list: scram-sha-1 gssapi
+#mech_list: scram-sha-256 gssapi
# Some older builds of MIT kerberos on Linux ignore this option &
# instead need KRB5_KTNAME env var.
@@ -38,7 +38,8 @@ mech_list: gssapi
# mechanism this can be commented out.
keytab: /etc/qemu/krb5.tab
-# If using scram-sha-1 for username/passwds, then this is the file
+# If using scram-sha-256 for username/passwds, then this is the file
# containing the passwds. Use 'saslpasswd2 -a qemu [username]'
-# to add entries, and 'sasldblistusers2 -f [sasldb_path]' to browse it
+# to add entries, and 'sasldblistusers2 -f [sasldb_path]' to browse it.
+# Note that this file stores passwords in clear text.
#sasldb_path: /etc/qemu/passwd.db
--
2.31.1
^ permalink raw reply related [flat|nested] 8+ messages in thread
* [PATCH 4/4] sasl: remove comment about obsolete kerberos versions
2021-05-14 17:31 [PATCH 0/4] docs: add user facing docs for secret passing and authorization controls Daniel P. Berrangé
` (2 preceding siblings ...)
2021-05-14 17:31 ` [PATCH 3/4] docs: recommend SCRAM-SHA-256 SASL mech instead of SHA-1 variant Daniel P. Berrangé
@ 2021-05-14 17:31 ` Daniel P. Berrangé
2021-06-04 8:43 ` [PATCH 0/4] docs: add user facing docs for secret passing and authorization controls Daniel P. Berrangé
4 siblings, 0 replies; 8+ messages in thread
From: Daniel P. Berrangé @ 2021-05-14 17:31 UTC (permalink / raw)
To: qemu-devel; +Cc: Daniel P. Berrangé
This is not relevant to any OS distro that QEMU currently targets.
Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
---
qemu.sasl | 4 ----
1 file changed, 4 deletions(-)
diff --git a/qemu.sasl b/qemu.sasl
index abdfc686be..851acc7e8f 100644
--- a/qemu.sasl
+++ b/qemu.sasl
@@ -29,10 +29,6 @@ mech_list: gssapi
# client.
#mech_list: scram-sha-256 gssapi
-# Some older builds of MIT kerberos on Linux ignore this option &
-# instead need KRB5_KTNAME env var.
-# For modern Linux, and other OS, this should be sufficient
-#
# This file needs to be populated with the service principal that
# was created on the Kerberos v5 server. If switching to a non-gssapi
# mechanism this can be commented out.
--
2.31.1
^ permalink raw reply related [flat|nested] 8+ messages in thread
* Re: [PATCH 0/4] docs: add user facing docs for secret passing and authorization controls
2021-05-14 17:31 [PATCH 0/4] docs: add user facing docs for secret passing and authorization controls Daniel P. Berrangé
` (3 preceding siblings ...)
2021-05-14 17:31 ` [PATCH 4/4] sasl: remove comment about obsolete kerberos versions Daniel P. Berrangé
@ 2021-06-04 8:43 ` Daniel P. Berrangé
2021-06-04 11:26 ` Marc-André Lureau
4 siblings, 1 reply; 8+ messages in thread
From: Daniel P. Berrangé @ 2021-06-04 8:43 UTC (permalink / raw)
To: qemu-devel
ping for any reviewers for docs
On Fri, May 14, 2021 at 06:31:06PM +0100, Daniel P. Berrangé wrote:
> These are an important of the overall QEMU network backend security
> controls but never previously documented aside from in blog posts.
>
> Daniel P. Berrangé (4):
> docs: document how to pass secret data to QEMU
> docs: document usage of the authorization framework
> docs: recommend SCRAM-SHA-256 SASL mech instead of SHA-1 variant
> sasl: remove comment about obsolete kerberos versions
>
> docs/system/authz.rst | 263 +++++++++++++++++++++++++++++++++++
> docs/system/index.rst | 2 +
> docs/system/secrets.rst | 162 +++++++++++++++++++++
> docs/system/vnc-security.rst | 7 +-
> qemu.sasl | 15 +-
> 5 files changed, 437 insertions(+), 12 deletions(-)
> create mode 100644 docs/system/authz.rst
> create mode 100644 docs/system/secrets.rst
>
> --
> 2.31.1
>
>
Regards,
Daniel
--
|: https://berrange.com -o- https://www.flickr.com/photos/dberrange :|
|: https://libvirt.org -o- https://fstop138.berrange.com :|
|: https://entangle-photo.org -o- https://www.instagram.com/dberrange :|
^ permalink raw reply [flat|nested] 8+ messages in thread
* Re: [PATCH 2/4] docs: document usage of the authorization framework
2021-05-14 17:31 ` [PATCH 2/4] docs: document usage of the authorization framework Daniel P. Berrangé
@ 2021-06-04 11:26 ` Marc-André Lureau
0 siblings, 0 replies; 8+ messages in thread
From: Marc-André Lureau @ 2021-06-04 11:26 UTC (permalink / raw)
To: Daniel P. Berrangé; +Cc: QEMU
[-- Attachment #1: Type: text/plain, Size: 10463 bytes --]
On Fri, May 14, 2021 at 9:36 PM Daniel P. Berrangé <berrange@redhat.com>
wrote:
> The authorization framework provides a way to control access to network
> services after a client has been authenticated. This documents how to
> actually use it.
>
> Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
> ---
> docs/system/authz.rst | 263 ++++++++++++++++++++++++++++++++++++++++++
> docs/system/index.rst | 1 +
> 2 files changed, 264 insertions(+)
> create mode 100644 docs/system/authz.rst
>
> diff --git a/docs/system/authz.rst b/docs/system/authz.rst
> new file mode 100644
> index 0000000000..2276546d23
> --- /dev/null
> +++ b/docs/system/authz.rst
> @@ -0,0 +1,263 @@
> +.. _client authorization:
> +
> +Client authorization
> +--------------------
> +
> +When configuring a QEMU network backend with either TLS certificates or
> SASL
> +authentication, access will be granted if the client successfully proves
> +their identity. If the authorization identity database is scoped to the
> QEMU
> +client this may be sufficient. It is common, however, for the identity
> database
> +to be much broader and thus authentication alone does not enable
> sufficient
> +access control. In this case QEMU provides a flexible system for enforcing
> +finer grained authorization on clients post-authentication.
> +
> +Identity providers
> +~~~~~~~~~~~~~~~~~~
> +
> +At the time of writing there are two authentication frameworks used by
> QEMU
> +that emit an identity upon completion.
> +
> + * TLS x509 certificate distinguished name.
> +
> + When configuring the QEMU backend as a network server with TLS, there
> + are a choice of credentials to use. The most common scenario is to
> utilize
> + x509 certificates. The simplest configuration only involves issuing
> + certificates to the servers, allowing the client to avoid a MITM attack
> + against their intended server.
> +
> + It is possible, however, to enable mutual verification by requiring
> that
> + the client provide a certificate to the server to prove its own
> identity.
> + This is done by setting the property ``verify-peer=yes`` on the
> + ``tls-creds-x509`` object, which is in fact the default.
> +
> + When peer verification is enabled, client will need to be issued with a
> + certificate by the same certificate authority as the server. If this is
> + still not sufficiently strong access control the Distinguished Name of
> + the certificate can be used as an identity in the QEMU authorization
> + framework.
> +
> + * SASL username.
> +
> + When configuring the QEMU backend as a network server with SASL, upon
> + completion of the SASL authentication mechanism, a username will be
> + provided. The format of this username will vary depending on the choice
> + of mechanism configured for SASL. It might be a simple UNIX style user
> + ``joebloggs``, while if using Kerberos/GSSAPI it can have a realm
> + attached ``joebloggs@QEMU.ORG``. Whatever format the username is
> presented
> + in, it can be used with the QEMU authorization framework.
> +
> +Authorization drivers
> +~~~~~~~~~~~~~~~~~~~~~
> +
> +The QEMU authorization framework is a general purpose design with choice
> of
> +user customizable drivers. These are provided as objects that can be
> +created at startup using the ``-object`` argument, or at runtime using the
> +``object_add`` monitor command.
> +
> +Simple
> +^^^^^^
> +
> +This authorization driver provides a simple mechanism for granting access
> +based on an exact match against a single identity. This is useful when it
> is
> +known that only a single client is to be allowed access.
> +
> +A possible use case would be when configuring QEMU for an incoming live
> +migration. It is known exactly which source QEMU the migration is expected
> +to arrive from. The x509 certificate associated with this source QEMU
> would
> +thus be used as the identity to match against. Alternatively if the
> virtual
> +machine is dedicated to a specific tenant, then the VNC server would be
> +configured with SASL and the username of only that tenant listed.
> +
> +To create an instance of this driver via QMP:
> +
> +::
> +
> + {
> + "execute": "object-add",
> + "arguments": {
> + "qom-type": "authz-simple",
> + "id": "authz0",
> + "props": {
> + "identity": "fred"
> + }
> + }
> + }
> +
> +
> +Or via the command line
> +
> +::
> +
> + -object authz-simple,id=authz0,identity=fred
> +
> +
> +List
> +^^^^
> +
> +In some network backends it will be desirable to grant access to a range
> of
> +clients. This authorization driver provides a list mechanism for granting
> +access by matching identities against a list of permitted one. Each match
> +rule has an associated policy and a catch all policy applies if no rule
> +matches. The match can either be done as an exact string comparison, or
> can
> +use the shell-like glob syntax, which allows for use of wildcards.
> +
> +To create an instance of this class via QMP:
> +
> +::
> +
> + {
> + "execute": "object-add",
> + "arguments": {
> + "qom-type": "authz-list",
> + "id": "authz0",
> + "props": {
> + "rules": [
> + { "match": "fred", "policy": "allow", "format": "exact" },
> + { "match": "bob", "policy": "allow", "format": "exact" },
> + { "match": "danb", "policy": "deny", "format": "exact" },
> + { "match": "dan*", "policy": "allow", "format": "glob" }
> + ],
> + "policy": "deny"
> + }
> + }
> + }
> +
> +
> +Due to the way this driver requires setting nested properties, creating
> +it on the command line will require use of the JSON syntax for
> ``-object``.
> +In most cases, however, the next driver will be more suitable.
> +
> +List file
> +^^^^^^^^^
> +
> +This is a variant on the previous driver that allows for a more dynamic
> +access control policy by storing the match rules in a standalone file
> +that can be reloaded automatically upon change.
> +
> +To create an instance of this class via QMP:
> +
> +::
> +
> + {
> + "execute": "object-add",
> + "arguments": {
> + "qom-type": "authz-list-file",
> + "id": "authz0",
> + "props": {
> + "filename": "/etc/qemu/myvm-vnc.acl",
> + "refresh": true
> + }
> + }
> + }
> +
> +
> +If ``refresh`` is ``yes``, inotify is used to monitor for changes
> +to the file and auto-reload the rules.
> +
> +The ``myvm-vnc.acl`` file should contain the match rules in a format that
> +closely matches the previous driver:
> +
> +::
> +
> + {
> + "rules": [
> + { "match": "fred", "policy": "allow", "format": "exact" },
> + { "match": "bob", "policy": "allow", "format": "exact" },
> + { "match": "danb", "policy": "deny", "format": "exact" },
> + { "match": "dan*", "policy": "allow", "format": "glob" }
> + ],
> + "policy": "deny"
> + }
> +
> +
> +The object can be created on the command line using
> +
> +::
> +
> + -object authz-list-file,id=authz0,\
> + filename=/etc/qemu/myvm-vnc.acl,refresh=on
> +
> +
> +PAM
> +^^^
> +
> +In some scenarios it might be desirable to integrate with authorization
> +mechanisms that are implemented outside of QEMU. In order to allow maximum
> +flexibility, QEMU provides a driver that uses the ``PAM`` framework.
> +
> +To create an instance of this class via QMP:
> +
> +::
> +
> + {
> + "execute": "object-add",
> + "arguments": {
> + "qom-type": "authz-pam",
> + "id": "authz0",
> + "parameters": {
> + "service": "qemu-vnc-tls"
> + }
> + }
> + }
> +
> +
> +The driver only uses the PAM "account" verification
> +subsystem. The above config would require a config
> +file /etc/pam.d/qemu-vnc-tls. For a simple file
> +lookup it would contain
> +
> +::
> +
> + account requisite pam_listfile.so item=user sense=allow \
> + file=/etc/qemu/vnc.allow
> +
> +
> +The external file would then contain a list of usernames.
> +If x509 cert was being used as the username, a suitable
> +entry would match the distinguished name:
> +
> +::
> +
> + CN=laptop.berrange.com,O=Berrange Home,L=London,ST=London,C=GB
> +
> +
> +On the command line it can be created using
> +
> +::
> +
> + -object authz-pam,id=authz0,service=qemu-vnc-tls
> +
> +
> +There are a variety of PAM plugins that can be used which are not
> illustrated
> +here, and it is possible to implement brand new plugins using the PAM API.
> +
> +
> +Connecting backends
> +~~~~~~~~~~~~~~~~~~~
> +
> +The authorization driver is created using the ``-object`` argument and
> then
> +needs to be associated with a network service. The authorization driver
> object
> +will be given a unique ID that needs to be referenced.
> +
> +The property to set in the network service will vary depending on the
> type of
> +identity to verify. By convention, any network server backend that uses
> TLS
> +will provide ``tls-authz`` property, while any server using SASL will
> provide
> +a ``sasl-authz`` property.
> +
> +Thus a example using SASL and authorization for the VNC server would look
>
"an example"
+like:
> +
> +::
> +
> + $QEMU --object authz-simple,id=authz0,identity=fred \
> + --vnc 0.0.0.0:1,sasl,sasl-authz=authz0
> +
> +While to validate both the x509 certificate and SASL username:
> +
> +::
> +
> + echo "CN=laptop.qemu.org,O=QEMU Project,L=London,ST=London,C=GB" >>
> tls.acl
> + $QEMU --object authz-simple,id=authz0,identity=fred \
> + --object authz-list-file,id=authz1,filename=tls.acl \
> + --object tls-creds-x509,id=tls0,dir=/etc/qemu/tls,verify-peer=yes
> \
> + --vnc 0.0.0.0:1
> ,sasl,sasl-authz=auth0,tls-creds=tls0,tls-authz=authz1
> diff --git a/docs/system/index.rst b/docs/system/index.rst
> index 6aa2f8c05c..6092eb2d91 100644
> --- a/docs/system/index.rst
> +++ b/docs/system/index.rst
> @@ -31,6 +31,7 @@ Contents:
> vnc-security
> tls
> secrets
> + authz
> gdb
> managed-startup
> cpu-hotplug
> --
> 2.31.1
>
>
>
--
Marc-André Lureau
[-- Attachment #2: Type: text/html, Size: 13196 bytes --]
^ permalink raw reply [flat|nested] 8+ messages in thread
* Re: [PATCH 0/4] docs: add user facing docs for secret passing and authorization controls
2021-06-04 8:43 ` [PATCH 0/4] docs: add user facing docs for secret passing and authorization controls Daniel P. Berrangé
@ 2021-06-04 11:26 ` Marc-André Lureau
0 siblings, 0 replies; 8+ messages in thread
From: Marc-André Lureau @ 2021-06-04 11:26 UTC (permalink / raw)
To: Daniel P. Berrangé; +Cc: QEMU
[-- Attachment #1: Type: text/plain, Size: 1465 bytes --]
On Fri, Jun 4, 2021 at 12:44 PM Daniel P. Berrangé <berrange@redhat.com>
wrote:
> ping for any reviewers for docs
>
> On Fri, May 14, 2021 at 06:31:06PM +0100, Daniel P. Berrangé wrote:
> > These are an important of the overall QEMU network backend security
> > controls but never previously documented aside from in blog posts.
> >
> > Daniel P. Berrangé (4):
> > docs: document how to pass secret data to QEMU
> > docs: document usage of the authorization framework
> > docs: recommend SCRAM-SHA-256 SASL mech instead of SHA-1 variant
> > sasl: remove comment about obsolete kerberos versions
> >
> > docs/system/authz.rst | 263 +++++++++++++++++++++++++++++++++++
> > docs/system/index.rst | 2 +
> > docs/system/secrets.rst | 162 +++++++++++++++++++++
> > docs/system/vnc-security.rst | 7 +-
> > qemu.sasl | 15 +-
> > 5 files changed, 437 insertions(+), 12 deletions(-)
> > create mode 100644 docs/system/authz.rst
> > create mode 100644 docs/system/secrets.rst
>
lgtm
Reviewed-by: Marc-André Lureau <marcandre.lureau@redhat.com>
>
> > --
> > 2.31.1
> >
> >
>
> Regards,
> Daniel
> --
> |: https://berrange.com -o-
> https://www.flickr.com/photos/dberrange :|
> |: https://libvirt.org -o-
> https://fstop138.berrange.com :|
> |: https://entangle-photo.org -o-
> https://www.instagram.com/dberrange :|
>
>
>
--
Marc-André Lureau
[-- Attachment #2: Type: text/html, Size: 2742 bytes --]
^ permalink raw reply [flat|nested] 8+ messages in thread
end of thread, other threads:[~2021-06-04 11:27 UTC | newest]
Thread overview: 8+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2021-05-14 17:31 [PATCH 0/4] docs: add user facing docs for secret passing and authorization controls Daniel P. Berrangé
2021-05-14 17:31 ` [PATCH 1/4] docs: document how to pass secret data to QEMU Daniel P. Berrangé
2021-05-14 17:31 ` [PATCH 2/4] docs: document usage of the authorization framework Daniel P. Berrangé
2021-06-04 11:26 ` Marc-André Lureau
2021-05-14 17:31 ` [PATCH 3/4] docs: recommend SCRAM-SHA-256 SASL mech instead of SHA-1 variant Daniel P. Berrangé
2021-05-14 17:31 ` [PATCH 4/4] sasl: remove comment about obsolete kerberos versions Daniel P. Berrangé
2021-06-04 8:43 ` [PATCH 0/4] docs: add user facing docs for secret passing and authorization controls Daniel P. Berrangé
2021-06-04 11:26 ` Marc-André Lureau
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).