| 1 | .. _client authorization: |
| 2 | |
| 3 | Client authorization |
| 4 | -------------------- |
| 5 | |
| 6 | When configuring a QEMU network backend with either TLS certificates or SASL |
| 7 | authentication, access will be granted if the client successfully proves |
| 8 | their identity. If the authorization identity database is scoped to the QEMU |
| 9 | client this may be sufficient. It is common, however, for the identity database |
| 10 | to be much broader and thus authentication alone does not enable sufficient |
| 11 | access control. In this case QEMU provides a flexible system for enforcing |
| 12 | finer grained authorization on clients post-authentication. |
| 13 | |
| 14 | Identity providers |
| 15 | ~~~~~~~~~~~~~~~~~~ |
| 16 | |
| 17 | At the time of writing there are two authentication frameworks used by QEMU |
| 18 | that emit an identity upon completion. |
| 19 | |
| 20 | * TLS x509 certificate distinguished name. |
| 21 | |
| 22 | When configuring the QEMU backend as a network server with TLS, there |
| 23 | are a choice of credentials to use. The most common scenario is to utilize |
| 24 | x509 certificates. The simplest configuration only involves issuing |
| 25 | certificates to the servers, allowing the client to avoid a MITM attack |
| 26 | against their intended server. |
| 27 | |
| 28 | It is possible, however, to enable mutual verification by requiring that |
| 29 | the client provide a certificate to the server to prove its own identity. |
| 30 | This is done by setting the property ``verify-peer=yes`` on the |
| 31 | ``tls-creds-x509`` object, which is in fact the default. |
| 32 | |
| 33 | When peer verification is enabled, client will need to be issued with a |
| 34 | certificate by the same certificate authority as the server. If this is |
| 35 | still not sufficiently strong access control the Distinguished Name of |
| 36 | the certificate can be used as an identity in the QEMU authorization |
| 37 | framework. |
| 38 | |
| 39 | * SASL username. |
| 40 | |
| 41 | When configuring the QEMU backend as a network server with SASL, upon |
| 42 | completion of the SASL authentication mechanism, a username will be |
| 43 | provided. The format of this username will vary depending on the choice |
| 44 | of mechanism configured for SASL. It might be a simple UNIX style user |
| 45 | ``joebloggs``, while if using Kerberos/GSSAPI it can have a realm |
| 46 | attached ``joebloggs@QEMU.ORG``. Whatever format the username is presented |
| 47 | in, it can be used with the QEMU authorization framework. |
| 48 | |
| 49 | Authorization drivers |
| 50 | ~~~~~~~~~~~~~~~~~~~~~ |
| 51 | |
| 52 | The QEMU authorization framework is a general purpose design with choice of |
| 53 | user customizable drivers. These are provided as objects that can be |
| 54 | created at startup using the ``-object`` argument, or at runtime using the |
| 55 | ``object_add`` monitor command. |
| 56 | |
| 57 | Simple |
| 58 | ^^^^^^ |
| 59 | |
| 60 | This authorization driver provides a simple mechanism for granting access |
| 61 | based on an exact match against a single identity. This is useful when it is |
| 62 | known that only a single client is to be allowed access. |
| 63 | |
| 64 | A possible use case would be when configuring QEMU for an incoming live |
| 65 | migration. It is known exactly which source QEMU the migration is expected |
| 66 | to arrive from. The x509 certificate associated with this source QEMU would |
| 67 | thus be used as the identity to match against. Alternatively if the virtual |
| 68 | machine is dedicated to a specific tenant, then the VNC server would be |
| 69 | configured with SASL and the username of only that tenant listed. |
| 70 | |
| 71 | To create an instance of this driver via QMP: |
| 72 | |
| 73 | :: |
| 74 | |
| 75 | { |
| 76 | "execute": "object-add", |
| 77 | "arguments": { |
| 78 | "qom-type": "authz-simple", |
| 79 | "id": "authz0", |
| 80 | "identity": "fred" |
| 81 | } |
| 82 | } |
| 83 | |
| 84 | |
| 85 | Or via the command line |
| 86 | |
| 87 | :: |
| 88 | |
| 89 | -object authz-simple,id=authz0,identity=fred |
| 90 | |
| 91 | |
| 92 | List |
| 93 | ^^^^ |
| 94 | |
| 95 | In some network backends it will be desirable to grant access to a range of |
| 96 | clients. This authorization driver provides a list mechanism for granting |
| 97 | access by matching identities against a list of permitted one. Each match |
| 98 | rule has an associated policy and a catch all policy applies if no rule |
| 99 | matches. The match can either be done as an exact string comparison, or can |
| 100 | use the shell-like glob syntax, which allows for use of wildcards. |
| 101 | |
| 102 | To create an instance of this class via QMP: |
| 103 | |
| 104 | :: |
| 105 | |
| 106 | { |
| 107 | "execute": "object-add", |
| 108 | "arguments": { |
| 109 | "qom-type": "authz-list", |
| 110 | "id": "authz0", |
| 111 | "rules": [ |
| 112 | { "match": "fred", "policy": "allow", "format": "exact" }, |
| 113 | { "match": "bob", "policy": "allow", "format": "exact" }, |
| 114 | { "match": "danb", "policy": "deny", "format": "exact" }, |
| 115 | { "match": "dan*", "policy": "allow", "format": "glob" } |
| 116 | ], |
| 117 | "policy": "deny" |
| 118 | } |
| 119 | } |
| 120 | |
| 121 | |
| 122 | Due to the way this driver requires setting nested properties, creating |
| 123 | it on the command line will require use of the JSON syntax for ``-object``. |
| 124 | In most cases, however, the next driver will be more suitable. |
| 125 | |
| 126 | List file |
| 127 | ^^^^^^^^^ |
| 128 | |
| 129 | This is a variant on the previous driver that allows for a more dynamic |
| 130 | access control policy by storing the match rules in a standalone file |
| 131 | that can be reloaded automatically upon change. |
| 132 | |
| 133 | To create an instance of this class via QMP: |
| 134 | |
| 135 | :: |
| 136 | |
| 137 | { |
| 138 | "execute": "object-add", |
| 139 | "arguments": { |
| 140 | "qom-type": "authz-list-file", |
| 141 | "id": "authz0", |
| 142 | "filename": "/etc/qemu/myvm-vnc.acl", |
| 143 | "refresh": true |
| 144 | } |
| 145 | } |
| 146 | |
| 147 | |
| 148 | If ``refresh`` is ``yes``, inotify is used to monitor for changes |
| 149 | to the file and auto-reload the rules. |
| 150 | |
| 151 | The ``myvm-vnc.acl`` file should contain the match rules in a format that |
| 152 | closely matches the previous driver: |
| 153 | |
| 154 | :: |
| 155 | |
| 156 | { |
| 157 | "rules": [ |
| 158 | { "match": "fred", "policy": "allow", "format": "exact" }, |
| 159 | { "match": "bob", "policy": "allow", "format": "exact" }, |
| 160 | { "match": "danb", "policy": "deny", "format": "exact" }, |
| 161 | { "match": "dan*", "policy": "allow", "format": "glob" } |
| 162 | ], |
| 163 | "policy": "deny" |
| 164 | } |
| 165 | |
| 166 | |
| 167 | The object can be created on the command line using |
| 168 | |
| 169 | :: |
| 170 | |
| 171 | -object authz-list-file,id=authz0,\ |
| 172 | filename=/etc/qemu/myvm-vnc.acl,refresh=on |
| 173 | |
| 174 | |
| 175 | PAM |
| 176 | ^^^ |
| 177 | |
| 178 | In some scenarios it might be desirable to integrate with authorization |
| 179 | mechanisms that are implemented outside of QEMU. In order to allow maximum |
| 180 | flexibility, QEMU provides a driver that uses the ``PAM`` framework. |
| 181 | |
| 182 | To create an instance of this class via QMP: |
| 183 | |
| 184 | :: |
| 185 | |
| 186 | { |
| 187 | "execute": "object-add", |
| 188 | "arguments": { |
| 189 | "qom-type": "authz-pam", |
| 190 | "id": "authz0", |
| 191 | "parameters": { |
| 192 | "service": "qemu-vnc-tls" |
| 193 | } |
| 194 | } |
| 195 | } |
| 196 | |
| 197 | |
| 198 | The driver only uses the PAM "account" verification |
| 199 | subsystem. The above config would require a config |
| 200 | file /etc/pam.d/qemu-vnc-tls. For a simple file |
| 201 | lookup it would contain |
| 202 | |
| 203 | :: |
| 204 | |
| 205 | account requisite pam_listfile.so item=user sense=allow \ |
| 206 | file=/etc/qemu/vnc.allow |
| 207 | |
| 208 | |
| 209 | The external file would then contain a list of usernames. |
| 210 | If x509 cert was being used as the username, a suitable |
| 211 | entry would match the distinguished name: |
| 212 | |
| 213 | :: |
| 214 | |
| 215 | CN=laptop.berrange.com,O=Berrange Home,L=London,ST=London,C=GB |
| 216 | |
| 217 | |
| 218 | On the command line it can be created using |
| 219 | |
| 220 | :: |
| 221 | |
| 222 | -object authz-pam,id=authz0,service=qemu-vnc-tls |
| 223 | |
| 224 | |
| 225 | There are a variety of PAM plugins that can be used which are not illustrated |
| 226 | here, and it is possible to implement brand new plugins using the PAM API. |
| 227 | |
| 228 | |
| 229 | Connecting backends |
| 230 | ~~~~~~~~~~~~~~~~~~~ |
| 231 | |
| 232 | The authorization driver is created using the ``-object`` argument and then |
| 233 | needs to be associated with a network service. The authorization driver object |
| 234 | will be given a unique ID that needs to be referenced. |
| 235 | |
| 236 | The property to set in the network service will vary depending on the type of |
| 237 | identity to verify. By convention, any network server backend that uses TLS |
| 238 | will provide ``tls-authz`` property, while any server using SASL will provide |
| 239 | a ``sasl-authz`` property. |
| 240 | |
| 241 | Thus an example using SASL and authorization for the VNC server would look |
| 242 | like: |
| 243 | |
| 244 | :: |
| 245 | |
| 246 | $QEMU --object authz-simple,id=authz0,identity=fred \ |
| 247 | --vnc 0.0.0.0:1,sasl,sasl-authz=authz0 |
| 248 | |
| 249 | While to validate both the x509 certificate and SASL username: |
| 250 | |
| 251 | :: |
| 252 | |
| 253 | echo "CN=laptop.qemu.org,O=QEMU Project,L=London,ST=London,C=GB" >> tls.acl |
| 254 | $QEMU --object authz-simple,id=authz0,identity=fred \ |
| 255 | --object authz-list-file,id=authz1,filename=tls.acl \ |
| 256 | --object tls-creds-x509,id=tls0,dir=/etc/qemu/tls,verify-peer=yes \ |
| 257 | --vnc 0.0.0.0:1,sasl,sasl-authz=auth0,tls-creds=tls0,tls-authz=authz1 |