From ab582c80e8e51da1797b12f83d482a8191e1581d Mon Sep 17 00:00:00 2001 From: Jeff Mitchell Date: Mon, 8 Oct 2018 12:45:17 -0400 Subject: [PATCH] Remove outdated references to UUIDs for token values --- website/source/api/auth/token/index.html.md | 2 +- website/source/docs/auth/app-id.html.md | 2 +- .../source/docs/commands/token/create.html.md | 3 +- .../source/docs/internals/security.html.md | 98 ++++++++++--------- website/source/docs/internals/token.html.md | 2 +- .../operations/deployment-guide.html.md | 2 +- .../guides/operations/replication.html.md | 2 +- 7 files changed, 59 insertions(+), 52 deletions(-) diff --git a/website/source/api/auth/token/index.html.md b/website/source/api/auth/token/index.html.md index 58010ca8c..2c3c7d863 100644 --- a/website/source/api/auth/token/index.html.md +++ b/website/source/api/auth/token/index.html.md @@ -68,7 +68,7 @@ during this call. ### Parameters - `id` `(string: "")` – The ID of the client token. Can only be specified by a - root token. Otherwise, the token ID is a randomly generated UUID. + root token. Otherwise, the token ID is a randomly generated value. - `role_name` `(string: "")` – The name of the token role. - `policies` `(array: "")` – A list of policies for the token. This must be a subset of the policies belonging to the token making the request, unless root. diff --git a/website/source/docs/auth/app-id.html.md b/website/source/docs/auth/app-id.html.md index 605b6f9c0..001c8a5e2 100644 --- a/website/source/docs/auth/app-id.html.md +++ b/website/source/docs/auth/app-id.html.md @@ -50,7 +50,7 @@ More details on this process follow: - The app ID is a unique ID that maps to a set of policies. This ID is generated by an operator and configured into the method. The ID itself is usually a - UUID, but any hard-to-guess unique value can be used. + UUID-formatted random value, but any hard-to-guess unique value can be used. - After creating app IDs, an operator authorizes a fixed set of user IDs with each app ID. When a valid {app ID, user ID} tuple is given to the "login" diff --git a/website/source/docs/commands/token/create.html.md b/website/source/docs/commands/token/create.html.md index 24c0a0dc6..653a3c279 100644 --- a/website/source/docs/commands/token/create.html.md +++ b/website/source/docs/commands/token/create.html.md @@ -82,8 +82,7 @@ flags](/docs/commands/index.html) included on all commands. "5m". - `-id` `(string: "")` - Value for the token. By default, this is an - auto-generated 36 character UUID. Specifying this value requires sudo - permissions. + auto-generated value. Specifying this value requires sudo permissions. - `-metadata` `(k=v: "")` - Arbitrary key=value metadata to associate with the token. This metadata will show in the audit log when the token is used. This diff --git a/website/source/docs/internals/security.html.md b/website/source/docs/internals/security.html.md index 47fb4fd8e..edbfd1dc0 100644 --- a/website/source/docs/internals/security.html.md +++ b/website/source/docs/internals/security.html.md @@ -101,54 +101,62 @@ to gain access to secret material they are not authorized to. This is an interna threat if the attacker is already permitted some level of access to Vault and is able to authenticate. -When a client first authenticates with Vault, an auth method is used to -verify the identity of the client and to return a list of associated ACL policies. -This association is configured by operators of Vault ahead of time. For example, -GitHub users in the "engineering" team may be mapped to the "engineering" and "ops" -Vault policies. Vault then generates a client token which is a randomly generated -UUID and maps it to the policy list. This client token is then returned to the client. +When a client first authenticates with Vault, an auth method is used to verify +the identity of the client and to return a list of associated ACL policies. +This association is configured by operators of Vault ahead of time. For +example, GitHub users in the "engineering" team may be mapped to the +"engineering" and "ops" Vault policies. Vault then generates a client token +which is a randomly generated, serialized value and maps it to the policy list. +This client token is then returned to the client. -On each request a client provides this token. Vault then uses it to check that the token -is valid and has not been revoked or expired, and generates an ACL based on the associated -policies. Vault uses a strict default deny or whitelist enforcement. This means unless -an associated policy allows for a given action, it will be denied. Each policy specifies -a level of access granted to a path in Vault. When the policies are merged (if multiple -policies are associated with a client), the highest access level permitted is used. -For example, if the "engineering" policy permits read/update access to the "eng/" path, -and the "ops" policy permits read access to the "ops/" path, then the user gets the -union of those. Policy is matched using the most specific defined policy, which may be -an exact match or the longest-prefix match glob pattern. +On each request a client provides this token. Vault then uses it to check that +the token is valid and has not been revoked or expired, and generates an ACL +based on the associated policies. Vault uses a strict default deny or whitelist +enforcement. This means unless an associated policy allows for a given action, +it will be denied. Each policy specifies a level of access granted to a path in +Vault. When the policies are merged (if multiple policies are associated with a +client), the highest access level permitted is used. For example, if the +"engineering" policy permits read/update access to the "eng/" path, and the +"ops" policy permits read access to the "ops/" path, then the user gets the +union of those. Policy is matched using the most specific defined policy, which +may be an exact match or the longest-prefix match glob pattern. Certain operations are only permitted by "root" users, which is a distinguished -policy built into Vault. This is similar to the concept of a root user on a Unix system -or an Administrator on Windows. Although clients could be provided with root tokens -or associated with the root policy, instead Vault supports the notion of "sudo" privilege. -As part of a policy, users may be granted "sudo" privileges to certain paths, so that -they can still perform security sensitive operations without being granted global -root access to Vault. +policy built into Vault. This is similar to the concept of a root user on a +Unix system or an Administrator on Windows. Although clients could be provided +with root tokens or associated with the root policy, instead Vault supports the +notion of "sudo" privilege. As part of a policy, users may be granted "sudo" +privileges to certain paths, so that they can still perform security sensitive +operations without being granted global root access to Vault. -Lastly, Vault supports using a [Two-man rule](https://en.wikipedia.org/wiki/Two-man_rule) for -unsealing using [Shamir's Secret Sharing technique](https://en.wikipedia.org/wiki/Shamir's_Secret_Sharing). -When Vault is started, it starts in an _sealed_ state. This means that the encryption key -needed to read and write from the storage backend is not yet known. The process of unsealing -requires providing the master key so that the encryption key can be retrieved. The risk of distributing -the master key is that a single malicious actor with access to it can decrypt the entire -Vault. Instead, Shamir's technique allows us to split the master key into multiple shares or parts. -The number of shares and the threshold needed is configurable, but by default Vault generates -5 shares, any 3 of which must be provided to reconstruct the master key. +Lastly, Vault supports using a [Two-man +rule](https://en.wikipedia.org/wiki/Two-man_rule) for unsealing using [Shamir's +Secret Sharing +technique](https://en.wikipedia.org/wiki/Shamir's_Secret_Sharing). When Vault +is started, it starts in an _sealed_ state. This means that the encryption key +needed to read and write from the storage backend is not yet known. The process +of unsealing requires providing the master key so that the encryption key can +be retrieved. The risk of distributing the master key is that a single +malicious actor with access to it can decrypt the entire Vault. Instead, +Shamir's technique allows us to split the master key into multiple shares or +parts. The number of shares and the threshold needed is configurable, but by +default Vault generates 5 shares, any 3 of which must be provided to +reconstruct the master key. -By using a secret sharing technique, we avoid the need to place absolute trust in the holder -of the master key, and avoid storing the master key at all. The master key is only -retrievable by reconstructing the shares. The shares are not useful for making any requests -to Vault, and can only be used for unsealing. Once unsealed the standard ACL mechanisms -are used for all requests. +By using a secret sharing technique, we avoid the need to place absolute trust +in the holder of the master key, and avoid storing the master key at all. The +master key is only retrievable by reconstructing the shares. The shares are not +useful for making any requests to Vault, and can only be used for unsealing. +Once unsealed the standard ACL mechanisms are used for all requests. -To make an analogy, a bank puts security deposit boxes inside of a vault. -Each security deposit box has a key, while the vault door has both a combination and a key. -The vault is encased in steel and concrete so that the door is the only practical entrance. -The analogy to Vault, is that the cryptosystem is the steel and concrete protecting the data. -While you could tunnel through the concrete or brute force the encryption keys, it would be -prohibitively time consuming. Opening the bank vault requires two-factors: the key and the combination. -Similarly, Vault requires multiple shares be provided to reconstruct the master key. -Once unsealed, each security deposit boxes still requires the owner provide a key, and similarly -the Vault ACL system protects all the secrets stored. +To make an analogy, a bank puts security deposit boxes inside of a vault. Each +security deposit box has a key, while the vault door has both a combination and +a key. The vault is encased in steel and concrete so that the door is the only +practical entrance. The analogy to Vault, is that the cryptosystem is the +steel and concrete protecting the data. While you could tunnel through the +concrete or brute force the encryption keys, it would be prohibitively time +consuming. Opening the bank vault requires two-factors: the key and the +combination. Similarly, Vault requires multiple shares be provided to +reconstruct the master key. Once unsealed, each security deposit boxes still +requires the owner provide a key, and similarly the Vault ACL system protects +all the secrets stored. diff --git a/website/source/docs/internals/token.html.md b/website/source/docs/internals/token.html.md index 89a755273..e0abbb3ad 100644 --- a/website/source/docs/internals/token.html.md +++ b/website/source/docs/internals/token.html.md @@ -15,7 +15,7 @@ token managed by the `token` backend. Every token has a number of properties: -* ID - The primary ID of a token is a randomly generated UUID +* ID - The primary ID of a token is a randomly generated value * Display Name - Optionally, a human readable display name * Metadata - Metadata used for audit logging * Number of Uses - Optionally, a restricted use count diff --git a/website/source/guides/operations/deployment-guide.html.md b/website/source/guides/operations/deployment-guide.html.md index b1807705a..7da421c9c 100644 --- a/website/source/guides/operations/deployment-guide.html.md +++ b/website/source/guides/operations/deployment-guide.html.md @@ -174,7 +174,7 @@ curl \ }' http://127.0.0.1:8500/v1/acl/create ``` -The response includes the UUID you will use as the `token` parameter value in Vault's storage stanza configuration. An example response: +The response includes the value you will use as the `token` parameter value in Vault's storage stanza configuration. An example response: ```json {"ID":"fe3b8d40-0ee0-8783-6cc2-ab1aa9bb16c1"} diff --git a/website/source/guides/operations/replication.html.md b/website/source/guides/operations/replication.html.md index fac32785c..438500b32 100644 --- a/website/source/guides/operations/replication.html.md +++ b/website/source/guides/operations/replication.html.md @@ -45,7 +45,7 @@ To fetch a secondary bootstrap token, run: The value for `id` is opaque to Vault and can be any identifying value you want; this can be used later to revoke the secondary and will be listed when you read replication status on the primary. You will get back a normal wrapped response, -except that the token will be a JWT instead of UUID-formatted random bytes. +except that the token will be JWT-formatted.. ### Activating a Secondary