cachepc-qemu

Fork of AMDESE/qemu with changes for cachepc side-channel attack
git clone https://git.sinitax.com/sinitax/cachepc-qemu
Log | Files | Refs | Submodules | LICENSE | sfeed.txt

authz.rst (8247B)


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