From c5c729c96f68f71b7f4f6f64fe6f72cdba92c248 Mon Sep 17 00:00:00 2001 From: Nikolay Edigaryev Date: Mon, 10 Jul 2023 19:13:10 +0400 Subject: [PATCH] Document --no-pki (#107) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Document --no-pki * and re-verify → and will re-verify * against → only against * Less "we"'s --- DeploymentGuide.md | 63 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 63 insertions(+) diff --git a/DeploymentGuide.md b/DeploymentGuide.md index bbad90b..b507896 100644 --- a/DeploymentGuide.md +++ b/DeploymentGuide.md @@ -6,6 +6,69 @@ responsible for managing the cluster and scheduling of resources. Orchard Worker The following guide is split in two parts. First, we'll [deploy an Orchard Controller](#deploying-orchard-controller) and then we'll [configure and register Orchard Workers](#configuring-orchard-workers) with Ansible. +## Securing the communications with an Orchard Controller + +When an Orchard client or Worker connects to the Controller, they need to establish trust somehow and verify that they're talking to the right Controller and no [man-in-the-middle attack](https://en.wikipedia.org/wiki/Man-in-the-middle_attack) is possible. + +Similarly to most web-browsers that rely on the PKI ([public key infrastructure](https://en.wikipedia.org/wiki/Public_key_infrastructure)), Orchard uses a hybrid approach by defaulting to automatic PKI verification (can be disabled by [`--no-pki`](#--no-pki-override)) and falling-back to a manual verification for self-signed certificates. + +In this section, we assume the following Controller types: + +* *Controller with a publicly valid certificate* + * can be configured by passing `--controller-cert` and `--controller-key` command-line arguments to `orchard controller run` +* *Controller with a self-signed certificate* + * configured automatically on first Controller start-up when no `--controller-cert` and `--controller-key` are presented + +Below we'll explain how Orchard client and Worker handle these two Controller types. + +### Client + +Client connects (or in other words, associates) with the Controller using a `orchard context create` command. + +The default mode allows for connecting to both Controller types (see above) by leveraging a fall-back mechanism: + +* Client first tries to connect to the Controller and validates its certificate using host's root CA set (can be disabled with [`--no-pki`](#--no-pki-override)) +* if the Client has encountered a *Controller with a publicly valid certificate*, that would be the last step and the association would succeed +* if the Client is dealing with *Controller with a self-signed certificate*, the Client will do another connection attempt to probe the Controller's certificate +* the probed Controller's certificate fingerprint is then presented to the user, and if the user agrees to trust it, the Client then considers that certificate to be trusted for a given Controller address +* Client finally connects to the Controller again with a trusted CA set containing only that certificate, execute the final API sanity checks and if everything is OK then the association succeeds + +Afterward, each interaction with the Controller (e.g. `orchard create vm` command) will stick to the chosen verification method and will re-verify the presented Controller's certificate against: + +* PKI association: host's root CA set +* non-PKI association: a trusted certificate stored in the Orchard's configuration file + +Another thing to note is that PKI and non-PKI associations will emit slightly different Boostrap Tokens for use in Worker: + +* PKI: Bootstrap Token won't include the Controller's certificate, thus forcing the Worker to validate the Controller's certificate against the Worker's host root CA set +* non-PKI: Bootstrap Token will include the Controller's certificate, thus forcing the Worker to validate the Controller's certificate only against that Controller's certificate + +### Worker + +Worker connects to the Controller using a `orchard worker run` command. + +The default mode allows for connecting to both Controller types (see above) by looking at the Bootstrap Token contents: + +* if the Bootstrap Token was generated on a Client that associated with a Controller with the help of the PKI + * the bootstrap token would contain no Controller certificate + * the Orchard Worker will try the PKI approach (can be disabled with [`--no-pki`](#--no-pki-override) to effectively prevent the Worker from connecting) and fail if certificate verification using PKI is possible +* if the Bootstrap Token was generated on a Client that associated with a Controller by utilizing a manual fingerprint verification + * the bootstrap token would contain a Controller certificate + * the Orchard Worker will try to connect to the Controller with a trusted CA set containing only that certificate + +#### `--no-pki` override + +If you're accessing a *Controller with a self-signed certificate* and want to additionally guard yourself against [CA compromises](https://en.wikipedia.org/wiki/Certificate_authority#CA_compromise) and other PKI-specific attacks, pass a `--no-pki` command-line argument to the following commands: + +* `orchard context create --no-pki` + * this will prevent the Client from using PKI and will let you interactively verify the Controller's certificate fingerprint before connecting +* `orchard worker run --no-pki` + * this will prevent the Worker from trying to use PKI when connecting to the Controller using a Bootstrap Token that has no certificate included in it + +Note that we've deliberately chosen not to use environment variables (e.g. `ORCHARD_NO_PKI`), because it's hard to be sure whether the variable was picked up by the command or not. + +Compared to environment variables, an invalid command-line argument will result in an error that wouldn't let you run the command. + ## Deploying Orchard Controller Orchard API is secured by default: all requests must be authenticated with credentials of a service account.