diff --git a/website/content/docs/concepts/security/permissions-model.mdx b/website/content/docs/concepts/security/permissions-model.mdx index 675053a288..4526c87030 100644 --- a/website/content/docs/concepts/security/permissions-model.mdx +++ b/website/content/docs/concepts/security/permissions-model.mdx @@ -14,7 +14,9 @@ model's fundamental concepts, provides examples of the specific forms of allowed grants, and contains a table that acts as an easy cheat sheet to help those new to its grant syntax with crafting roles. -Each grant is a mapping that describes a resource or set of resources and the actions that should be allowed on them. Thus, each grant contains one or more of: +Each grant is a mapping that describes a resource or set of resources and the +actions that should be allowed on them. Thus, each grant contains one or more +of: * An `id` field that indicates a specific resource or a wildcard to match all * A `type` field that indicates a specific resource type or a wildcard to match all @@ -157,7 +159,7 @@ Such a grant is essentially a full administrator grant for a scope. ### Templates A few template possibilities exist, which will at grant evaluation time -subsitute the given value into the ID field of the grant string: +substitute the given value into the ID field of the grant string: * `{{account.id}}`: The substituted value is the account ID associated with the token used to perform the action. As an example, diff --git a/website/content/docs/concepts/security/tls.mdx b/website/content/docs/concepts/security/tls.mdx new file mode 100644 index 0000000000..a0ebaffdf3 --- /dev/null +++ b/website/content/docs/concepts/security/tls.mdx @@ -0,0 +1,135 @@ +--- +layout: docs +page_title: TLS +sidebar_title: TLS +description: |- + How Boundary secures its connections +--- + +# TLS in Boundary + +As a security product, Boundary has been designed from the ground up to ensure +its connections are secure. There are three types of connections in Boundary; +this page will describe how TLS works with each of them. + +Some of the ways that Boundary uses TLS, e.g. for client-to-worker connections, +are different from most other products. It may not be readily apparent that user +configuration of TLS on the listening port of Workers is not only not required, +but more secure; however, when it comes to TLS, Boundary tries to provide high +security by default with simplicity of operation. + +Details are in the individual sections below. + +## Client-to-Controller TLS + +Boundary's API access (that is, the Controller server defaulting to port 9200) +uses standard PKI. TLS is configured by providing a valid certificate (and +optionally CA certificate or chain) and clients must trust that CA chain. This +provides broad compatibility with a wide array of clients. + +## Worker-to-Controller TLS + +The service exposed by the a Controller to handle Worker requests takes +advantage of the KMS key designated for `worker-auth` within Boundary's +configuration file, which must point to the same key on the KMS for both the +Controller and the Worker. Security of the connection relies on secure +transmission of a single set of allowed TLS parameters, which forms the entire +allowable CA chain for the connection. + +TLS establishment is performed as follows: + +1. The Worker generates a TLS certificate acting as a self-contained chain, as +well as a nonce. The generated key type is currently Ed25519. The certificate is +valid for a total of 2.5 minutes: thirty seconds before the current time (to +allow for some minor clock drift) and two minutes after (to allow time to +establish the connection). + +2. The Worker marshals the TLS chain and nonce and encrypts the resulting bytes +via the shared KMS. This value is marshaled and split into chunks. + +3. The Worker establishes a TLS 1.3 connection to the Controller. The encrypted +value is transmitted to the Controller via the TLS ALPN field as numbered +chunks. + +4. The Controller reads the chunks and reassembles them into the original +encrypted value. + +5. The Controller decrypts this value via the shared KMS. If successful, the +Controller validates that the nonce is not known, to ensure that this is not a +replay. + +6. The Controller uses the decrypted parameters to configures its TLS stack with +the same certificate and key. + +7. The connection is mutually authenticated; on each end, only the single +self-signed CA certificate that was securely transmitted is configured as a +valid root CA for validation checking. + +8. If successful, the nonce is stored in the database along with an expiration +time set several minutes past the actual expiration time of the certificate +itself. This ensures that any replay attempt that occurs is detected and +rejected until after the certificate is otherwise invalid. + +## Client-to-Worker TLS + +Workers do not require any configuration for their client-facing listeners to +support a high degree of security. Instead, the TLS configuration to use is +determined dynamically via SNI, and the session is then mutually authenticated. +Here's how it works: + +TLS establishment is performed as follows: + +1. When the session is authorized, the Controller generates a TLS certificate +acting as a self-contained chain. This is similar to the Worker-to-Controller +flow above, but in this case the key is an Ed25519 key generated via derivation +from a base key within the Controller, which itself is protected at rest via the +controller's "root" KMS. The derivation uses HKDF-SHA256 with the user ID and +the session ID as inputs. The lifetime of the certificate is tied to the +lifetime of the session. + +2. The certificate and private key (along with other session authorization data, +notably the session ID) are returned to the client as part of the output of an +`authorize-session` action against a target, in the form of a marshaled object. +The controller persists the certificate in the database, but not the private +key. + +3. The client (that is, the `boundary connect` command) parses this session +authorization data and uses the certificate and private key to construct a TLS +stack. It then makes a TLS 1.3 connection to a Worker, passing the session ID as +the SNI value. + +4. The worker sees the SNI value and makes a call to the Controller to fetch +session authorization information, keyed by the session ID. + +5. The Controller looks for a session with the given ID and fetches the +information. Using the session ID and the user ID tied to the session, it +re-derives the private key and passes all of the information back to the Worker. +Notably, this may include a TOFU (Trust On First Use) token. + +6. The Worker uses the given data to construct a TLS stack with the same +certificate and key. + +7. The connection is mutually authenticated; on each end, only the single +self-signed CA certificate that was securely transmitted is configured as a +valid root CA for validation checking. + +8. If successful, the client and Worker perform a handshake, where the client +passes a TOFU (Trust On First Use) value to the Worker. This value is derived +when the client is created; that is, when `boundary connect` is run. This allows +for a single client to make multiple connections within a session, without the +credentials being usable via a different client: + + * If the worker was not given a TOFU token in step 5, the worker submits the + value to the Controller. The Controller verifies (via a database transaction) + that the session has not had a different TOFU token submitted prior and stores + it. Otherwise it's rejected, and so is the connection, as a possible replay + attack. + + * If the Worker was given a TOFU token in step 5, it checks to see whether the + token values match. If not, the connection is rejected as a possible replay + attack. + +In the future, to support other client paradigms, we may support user +configuration of the Worker's client-facing TLS. In this model, the shared +certificate/private key would instead act as credentials for the session, +similar to a username/password. \ No newline at end of file diff --git a/website/data/docs-navigation.js b/website/data/docs-navigation.js index 9b7d5cc849..c426f87646 100644 --- a/website/data/docs-navigation.js +++ b/website/data/docs-navigation.js @@ -35,7 +35,10 @@ export default [ }, { category: 'security', - content: ['permissions-model'], + content: [ + 'permissions-model', + 'tls', + ] }, { category: 'domain-model',