diff --git a/website/source/docs/vault-enterprise/index.html.md b/website/source/docs/vault-enterprise/index.html.md index d694a1786c..d25ec92567 100644 --- a/website/source/docs/vault-enterprise/index.html.md +++ b/website/source/docs/vault-enterprise/index.html.md @@ -9,11 +9,8 @@ description: |- # Vault Enterprise -Vault Enterprise includes a number of features that may be useful in -specific workflows. These include: - -- [Replication](/docs/vault-enterprise/replication) -- [Secure Introduction Client](/docs/vault-enterprise/vsi) -- [HSM Key Wrapping and Auto-Unsealing](/docs/vault-enterprise/hsm) +Vault Enterprise includes a number of features that may be useful in specific +workflows. Please use the sidebar navigation on the left to choose a specific +topic. These features are part of [Vault Enterprise](https://www.hashicorp.com/vault.html?utm_source=oss&utm_medium=docs&utm_campaign=vault&_ga=1.201793489.1956619674.1489356624). diff --git a/website/source/docs/vault-enterprise/vsi/configuration.html.md b/website/source/docs/vault-enterprise/vsi/configuration.html.md deleted file mode 100644 index 0e86822e22..0000000000 --- a/website/source/docs/vault-enterprise/vsi/configuration.html.md +++ /dev/null @@ -1,138 +0,0 @@ ---- -layout: "docs" -page_title: "Vault Secure Introduction Client Configuration" -sidebar_current: "docs-vault-enterprise-vsi-configuration" -description: |- - Configuration details for Vault Secure Introduction Client. - ---- - -# Vault Secure Introduction Client Configuration - -The Vault Secure Introduction client has a flexible configuration system that -allows combining settings from CLI flags, environment variables, and a -configuration file, in that order of preference. - -Generally speaking, values with a source at a higher order of preference -override those from a source with a lower order of preference. The main -difference is in specification of servers, which is detailed further in this -document. - -The available directives from the configuration file, as well as their -environment variable and CLI flag counterparts, follow. - -## The Configuration File - -The configuration file is in [HCL](https://github.com/hashicorp/hcl) format and -contains top-level directives as well as directive blocks. An example: - -```javascript -environment "aws" { -} - -vault { - address = "https://vault.service.consul:8200" - mount_path = "auth/aws" -} - -serve "file" { - path = "/ramdisk/vault-token" -} -``` - -The configuration file can be specified either with the `config` CLI flag -or by simply providing the path to the configuration file as the command's -argument. - -All directives take string arguments unless explicitly specified otherwise. - -## Top-Level Directives - - * `environment`: A block with information about the environment under which the - client is running. If not specified, the client will attempt to - automatically discover its environment. The type may also be specified by - the `VAULT_SI_ENVIRONMENT` environment variable and the `environment` CLI - flag. Additional configuration key/value pairs can be passed in via the - `envconfig` CLI flag, which can be specified multiple times. - * `nonce_path`: If the client should save and load its nonce, the path where - the nonce should be stored. May also be specified by the - `VAULT_SI_NONCE_PATH` environment variable and the `nonce-path` CLI flag. - _This is a security-sensitive directive._ - * `vault`: A block with Vault server information, detailed below. - * `serve`: One or more blocks containing serving information, detailed below. - -## Environment Block Directives - -In the configuration file, the type is specified as the block's key, with -optional additional string values specified inside: - -```hcl -environment "aws" { - role = "prod" -} -``` - -The behavior with respect to these additional string values is -environment-specific. Currently, all environments simply round-trip any given -values to the Vault login endpoint. In the example above using the AWS -environment, the final set of values given to the login endpoint would be a -`pkcs7` key coming from the environment, as well as a `role` key with value -`prod` coming from the extra environment configuration. - -## Vault Block Directives - - * `address`: The address of the vault server, including scheme. May also be - specified by the `VAULT_ADDR` environment variable and the `address` CLI - flag. - * `mount_path`: The mount path of the authentication backend in Vault. If not - set, defaults to a value specific to the running environment (e.g. for AWS, - it will default to `auth/aws`. May also be specified by the - `VAULT_SI_MOUNT_PATH` environment variable and the `mount-path` CLI flag. - * `tls_skip_verify`: A boolean indicating whether to skip verification of the - certificate provided by the Vault server. May also be specified by the - `VAULT_SKIP_VERIFY` environment variable or the `tls-skip-verify` CLI flag. - _This is a security-sensitive directive._ - * `ca_cert`: A file containing a PEM-encoded X.509 CA certificate to use in - the validation chain of the Vault server's TLS certificate. May also be - specified by the `VAULT_CACERT` environment variable or the `ca-cert` CLI - flag. - * `ca_path`: A directory containing PEM-encoded X.509 CA certificates to use - in the validation chain of the Vault server's TLS certificate. May also be - specified by the `VAULT_CAPATH` environment variable or the `ca-path` CLI - flag. - -## Serve Block Directives - -In the configuration file, serve blocks can be one of two types: - - * Named serve blocks specify a name (`serve "myserver" {...`). The type of server - must be specified by the `type` directive within the block. - * Anonymous serve blocks, rather than specify a name, specify the type of - server (`serve "file" {...`). - -On the CLI, serve blocks are specified in one of two formats: - - * `:=`: specifies a key/value configuration directive for an - anonymous server with the given type. - * `::=`: specifies a key/value configuration directive - for a named server with the given type. - -The merging rules for CLI and configuration are as follows: - - * Each anonymous serve block in the configuration file stands alone, using - only the directives contained in the block. - * Each type of anonymous server specified in CLI flags CLI stands alone, with - the key/value configuration directives merged per-type. As a result, there - can only be one anonymous server per type specified in CLI flags. These are - not merged with any anonymous server specified in the configuration file. - * Key/value configuration directives for named serve blocks are merged between - the CLI and configuration file. - -### File Type Serve Block Directives - - * `path`: The path to a file on disk where the token should be written. To - avoid any possible issues during writing, the token will first be written to - a temporary file in the same directory, then atomically renamed to the given - path. The token will always be written with permissions `0640`; directory - permissions for this location should ensure access only to appropriate - readers. diff --git a/website/source/docs/vault-enterprise/vsi/index.html.md b/website/source/docs/vault-enterprise/vsi/index.html.md deleted file mode 100644 index 2910282a71..0000000000 --- a/website/source/docs/vault-enterprise/vsi/index.html.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -layout: "docs" -page_title: "About the Vault Secure Introduction Client" -sidebar_current: "docs-vault-enterprise-vsi" -description: |- - Vault Secure Introduction Client provides a turnkey way to securely introduce Vault tokens and features to applications running in various environments. - ---- - -# About the Vault Secure Introduction Client - -The Vault Secure Introduction Client is a feature of [Vault -Enterprise](https://www.hashicorp.com/vault.html) that provides a turnkey way -to securely introduce Vault tokens and features to applications running in -various environments. Currently, AWS EC2 instances are supported in conjunction -with Vault's AWS authentication backend. The client stays running until -terminated and will monitor the lifetime of retrieved Vault tokens, renewing -and reauthenticating as necessary. - -Configuration is simple and can generally be performed purely using CLI flags. -Please see the [Configuration](/docs/vault-enterprise/vsi/configuration.html) page for details -on client configuration. - -The [Security](/docs/vault-enterprise/vsi/security.html) page contains information and -suggestions to help deploy the client in a secure fashion. It assumes -familiarity with the AWS Authentication Backend. diff --git a/website/source/docs/vault-enterprise/vsi/security.html.md b/website/source/docs/vault-enterprise/vsi/security.html.md deleted file mode 100644 index 497d28fa2f..0000000000 --- a/website/source/docs/vault-enterprise/vsi/security.html.md +++ /dev/null @@ -1,113 +0,0 @@ ---- -layout: "docs" -page_title: "Vault Secure Introduction Client Security" -sidebar_current: "docs-vault-enterprise-vsi-security" -description: |- - Guidelines for secure usage of Vault Secure Introduction Client. ---- - -# Vault Secure Introduction Client Security - -This page discusses the various security-sensitive aspects of the Vault Secure -Introduction Client along with advice for secure usage. - -## General Advice - -### Use A Dedicated User - -We recommend that the VSI client be run by a dedicated user that does not run -other services. This reduces the chance that an attack on another service can -lead to accessing sensitive information (for instance, if the ability of the -client to store its nonce is used). This also ensures that tokens written with -the `file` serving type are not accessible to processes run by other users. - -### Write Tokens To Ephemeral Storage With A Dedicated Group - -When using the `file` serving type to write tokens to paths on the filesystem, -the directories containing those paths should only be accessible to a group or -groups of services that require access to the Vault token. The tokens are -always written with permissions `0640`. - -In addition, this should be a location that does not persist across reboots, -such as a ramdisk. After a reboot, the client will fetch a new token, so there -is no need to store the old one. - -### Firewall Instance Metadata - -If possible (based on operating system and/or distribution), use features of -the OS firewall to restrict access to the instance metadata (specifically the -signed `pkcs7` document) from the `http://169.254.169.254` endpoint to only the -users/groups that need it. - -## Nonces - -The AWS Authentication Backend operates on a Trust On First Use (TOFU) -principle, using nonces generated by a backend client to identify repeat -authentication requests by the same client. - -A nice benefit of this approach is that if a bad actor is able to acquire -machine instance metadata and authenticate before the VSI client, the errors -from the VSI client logs indicating a client nonce mismatch can be used to -trigger an alarm. - -The drawback is that reboot survivability is impacted. However, combinations of -options on the AWS Authentication Backend and the VSI client provide flexible -methods for managing this problem, allowing the security policy of nearly any -organization to be accommodated. - -Following are the various strategies of nonce management. - -### Immutable Instances - -If your EC2 instances are running in Auto Scaling Groups (ASGs), one strategy -is to enable the `disallow_reauthentication` option on a configured AMI in the -AWS Authentication Backend (or an associated Role Tag). This allows only a -single token to be granted to any particular instance ID (unless cleared via -the `whitelist/identity` endpoint in the backend), regardless of nonce. As a -result, rather than reboot an instance running in an ASG, the instance can -simply be terminated; when the ASG brings up a new instance, the instance ID -will be different and the new instance will be allowed to authenticate. - -### Manual/Automated Whitelist Management - -This approach relies on either manual or automated intervention, perhaps keyed -by reboot notifications or notifications from parsing the VSI client's error -log. In this approach, knowledge of the reboot of an instance provides -assurance to an operator that they can clear the instance and its nonce from -the backend's whitelist via the `whitelist/identity` endpoint, allowing the -client to use its new generated nonce to authenticate. - -### Instance Migration - -If your EC2 instances do not rely on ephemeral storage across reboots, one -approach is to stop/start the instance rather than reboot it, in conjunction -with enabling the `allow_instance_migration` option on a configured AMI in the -AWS Authentication Backend (or an associated Role Tag). - -When an instance is stopped and started, this causes a new placement of the -instances in the AWS infrastructure; this results in an updated value of -`pendingTime` in the instance metadata document. When the -`allow_instance_migration` option is turned on, a client is allowed to -authenticate for the same instance ID with a new nonce if the value of -`pendingTime` is later than the previously seen value. - -### Nonce Storage - -A final option for managing reboot survivability is to use the client's option -to store its nonce on the instance's filesystem and read this nonce the next -time it starts up. - -Although this option provides the best automated reboot survivability -guarantees, it does require storing the nonce in persistent storage. If using -this option, filesystem permissions should be used to ensure that only the user -running the client has access to the directory where the nonce will be stored -(the nonce will always be stored with permissions `0600`). - -This is a very security-sensitive option; so long as the nonce and instance -remain valid, disclosure of the nonce on a machine can allow any user or -service with access to the instance metadata to authenticate as the machine and -gain access to all Vault policies associated with the machine. For this reason, -you should also ensure that if you are having the client store its nonce, you -do not duplicate this nonce across instances (for instance, by baking it into -an AMI), as this would allow any user or service that learns this nonce with -access to any machine's instance metadata to authenticate as that instance. diff --git a/website/source/layouts/docs.erb b/website/source/layouts/docs.erb index 8c9a5ea7a2..af7f16e93f 100644 --- a/website/source/layouts/docs.erb +++ b/website/source/layouts/docs.erb @@ -344,17 +344,6 @@
  • > Replication
    • -
  • > - Secure Introduction - -
  • > HSM Support