[lxc-devel] [lxd/master] doc: Clarify API security and options to restrict

Fri May 17 07:06:27 UTC 2019

A non-text attachment was scrubbed...
Name: not available
Type: text/x-mailbox
Size: 383 bytes
Desc: not available
URL: <http://lists.linuxcontainers.org/pipermail/lxc-devel/attachments/20190517/34ebb036/attachment-0001.bin>
-------------- next part --------------
From 009e8af16e8702f430899a234fa02e7197306770 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?St=C3=A9phane=20Graber?= <stgraber at ubuntu.com>
Date: Fri, 17 May 2019 09:04:44 +0200
Subject: [PATCH] doc: Clarify API security and options to restrict
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Suggested-by: Chris Moberly
Signed-off-by: Stéphane Graber <stgraber at ubuntu.com>
---
 doc/index.md    | 15 ++++++++++++
 doc/security.md | 63 +++++++++++++++++++++++++++++++++++++------------
 2 files changed, 63 insertions(+), 15 deletions(-)

diff --git a/doc/index.md b/doc/index.md
index 89e53d552d..e25e86baf9 100644
--- a/doc/index.md
+++ b/doc/index.md
@@ -101,6 +101,21 @@ group to talk to LXD; you can create your own group if you want):
 sudo -E LD_LIBRARY_PATH=$LD_LIBRARY_PATH $GOPATH/bin/lxd --group sudo
 ```
 
+## Security
+LXD, similar to other similar container managers provides a UNIX socket for local communication.
+
+**WARNING**: Anyone with access to that socket can fully control LXD, which includes
+the ability to attach host devices and filesystems, this should
+therefore only be given to users who would be trusted with root access
+to the host.
+
+When listening to the network, the same API is available on a TLS socket
+(HTTPs), specific access on the remote API can be restricted through
+Canonical RBAC.
+
+
+More details are [available here](security.md).
+
 ## Getting started with LXD
 Now that you have LXD running on your system you can read the [getting started guide](https://linuxcontainers.org/lxd/getting-started-cli/) or go through more examples and configurations in [our documentation](https://lxd.readthedocs.org).
 
diff --git a/doc/security.md b/doc/security.md
index 4070bb9f01..c4c3180843 100644
--- a/doc/security.md
+++ b/doc/security.md
@@ -1,16 +1,30 @@
 # Security
 ## Introduction
-Local communications over the UNIX socket happen over a cleartext HTTP
-socket and access is restricted by socket ownership and mode.
+LXD is a daemon running as root.
 
+Access to that daemon is only possible over a local UNIX socket by default.
+Through configuration, it's then possible to expose the same API over
+the network on a TLS socket.
+
+**WARNING**: Local access to LXD through the UNIX socket always grants
+full access to LXD. This includes the ability to attach any filesystem
+paths or devices to any container as well as tweaking all security
+features on containers. You should only give such access to someone who
+you'd trust with root access to your system.
+
+The remote API uses either TLS client certificates or Candid based
+authentication. Canonical RBAC support can be used combined with Candid
+based authentication to limit what an API client may do on LXD.
+
+## TLS configuration
 Remote communications with the LXD daemon happen using JSON over HTTPS.
 The supported protocol must be TLS1.2 or better.
 
 All communications must use perfect forward secrecy and ciphers must be
 limited to strong elliptic curve ones (such as ECDHE-RSA or ECDHE-ECDSA).
 
-Any generated key should be at least 4096bit RSA and when using
-signatures, only SHA-2 signatures should be trusted.
+Any generated key should be at least 4096bit RSA, preferably EC384 and
+when using signatures, only SHA-2 signatures should be trusted.
 
 Since we control both client and server, there is no reason to support
 any backward compatibility to broken protocol or ciphers.
@@ -23,7 +37,27 @@ certificate for any client-server communication.
 To cause certificates to be regenerated, simply remove the old ones. On the
 next connection a new certificate will be generated.
 
-## Adding a remote with a default setup
+## Role Based Access Control (RBAC)
+LXD supports integrating with the Canonical RBAC service.
+
+This uses Candid based authentication with the RBAC service maintaining
+roles to user/group relationships. Those roles can be scoped down to LXD
+projects.
+
+By default, the 4 roles give you:
+
+ - auditor: Read-only access to the project
+ - user: Ability to do normal lifecycle actions (start, stop, ...),
+   execute commands in the containers, attach to console, manage snapshots, ...
+ - operator: All of the above + the ability to create, re-configure and
+   delete containers and images
+ - admin: All of the above + the ability to reconfigure the project itself
+
+**WARNING**: Of those roles, only `auditor` and `user` are currently
+suitable for a user whom you wouldn't trust with root access to the
+host.
+
+## Adding a remote with TLS client certificate authentication
 In the default setup, when the user adds a new server with `lxc remote add`,
 the server will be contacted over HTTPs, its certificate downloaded and the
 fingerprint will be shown to the user.
@@ -41,7 +75,7 @@ any additional credentials.
 This is a workflow that's very similar to that of SSH where an initial
 connection to an unknown server triggers a prompt.
 
-## Adding a remote with a PKI based setup
+## Adding a remote with a TLS client in a PKI based setup
 In the PKI setup, a system administrator is managing a central PKI, that
 PKI then issues client certificates for all the lxc clients and server
 certificates for all the LXD daemons.
@@ -73,7 +107,7 @@ pre-generated files.
 
 After this is done, restarting the server will have it run in PKI mode.
 
-## Adding a remote with Candid
+## Adding a remote with Candid authentication
 When LXD is configured with Candid, it will request that clients trying to
 authenticating with it get a Discharge token from the authentication server
 specified by the `candid.api.url` setting.
@@ -88,9 +122,9 @@ presenting the token received from the authentication server.  The LXD server
 verifies the token, thus authenticating the request.  The token is stored as
 cookie and is presented by the client at each request to LXD.
 
-## Managing trusted clients
-The list of certificates trusted by a LXD server can be obtained with `lxc
-config trust list`.
+## Managing trusted TLS clients
+The list of TLS certificates trusted by a LXD server can be obtained with
+`lxc config trust list`.
 
 Clients can manually be added using `lxc config trust add <file>`,
 removing the need for a shared trust password by letting an existing
@@ -99,9 +133,10 @@ administrator add the new client certificate directly to the trust store.
 To revoke trust to a client its certificate can be removed with `lxc config
 trust remove FINGERPRINT`.
 
-## Password prompt
-To establish a new trust relationship, a password must be set on the
-server and send by the client when adding itself.
+## Password prompt with TLS authentication
+To establish a new trust relationship when not already setup by the
+administrator, a password must be set on the server and sent by the
+client when adding itself.
 
 A remote add operation should therefore go like this:
 
@@ -129,7 +164,6 @@ if the certificate did in fact change. If it did, then the certificate
 can be replaced by the new one or the remote be removed altogether and
 re-added.
 
-
 ### Server trust relationship revoked
 In this case, the server still uses the same certificate but all API
 calls return a 403 with an error indicating that the client isn't
@@ -138,7 +172,6 @@ trusted.
 This happens if another trusted client or the local server administrator
 removed the trust entry on the server.
 
-
 ## Production setup
 For production setup, it's recommended that `core.trust_password` is unset
 after all clients have been added.  This prevents brute-force attacks trying to
