From 512e150e48c8a21e6b94936a5eec87eca3ceb85c Mon Sep 17 00:00:00 2001 From: Tim Gross Date: Tue, 16 Jul 2024 16:34:51 -0400 Subject: [PATCH 1/4] docs: external KMS configuration In #23580 we're implementing support for encrypting Nomad's key material with external KMS providers or Vault Transit. This changeset breaks out the documentation from that PR to keep the review manageable and present it to a wider set of reviewers. Ref: https://hashicorp.atlassian.net/browse/NET-10334 Ref: https://github.com/hashicorp/nomad/issues/14852 Ref: https://github.com/hashicorp/nomad/pull/23580 --- .../docs/configuration/keyring/awskms.mdx | 99 ++++++++++++++ .../configuration/keyring/azurekeyvault.mdx | 92 +++++++++++++ .../docs/configuration/keyring/gcpckms.mdx | 93 +++++++++++++ .../docs/configuration/keyring/index.mdx | 106 ++++++++++++++ .../docs/configuration/keyring/transit.mdx | 129 ++++++++++++++++++ .../docs/operations/key-management.mdx | 5 +- website/data/docs-nav-data.json | 27 +++- 7 files changed, 549 insertions(+), 2 deletions(-) create mode 100644 website/content/docs/configuration/keyring/awskms.mdx create mode 100644 website/content/docs/configuration/keyring/azurekeyvault.mdx create mode 100644 website/content/docs/configuration/keyring/gcpckms.mdx create mode 100644 website/content/docs/configuration/keyring/index.mdx create mode 100644 website/content/docs/configuration/keyring/transit.mdx diff --git a/website/content/docs/configuration/keyring/awskms.mdx b/website/content/docs/configuration/keyring/awskms.mdx new file mode 100644 index 00000000000..e67829aed95 --- /dev/null +++ b/website/content/docs/configuration/keyring/awskms.mdx @@ -0,0 +1,99 @@ +--- +layout: docs +page_title: AWS KMS - Keyring - Configuration +description: |- + The AWS KMS keyring configures Nomad to use AWS KMS as the key material + wrapping mechanism. +--- + +# `awskms` keyring + +The AWS KMS keyring configures Nomad to use AWS KMS to wrap its keyring. This +example shows configuring AWS KMS keyring through the Nomad configuration file by +providing all the required values: + +```hcl +keyring "awskms" { + active = true + name = "example" + + # fields specific to awskms + region = "us-east-1" + access_key = "AKIAIOSFODNN7EXAMPLE" + secret_key = "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY" + kms_key_id = "19ec80b0-dfdd-4d97-8164-c6examplekey" + endpoint = "https://vpce-0e1bb1852241f8cc6-pzi0do8n.kms.us-east-1.vpce.amazonaws.com" +} +``` + +## `awskms` parameters + +These parameters apply to the `keyring` block in the Nomad configuration file: + +- `region` `(string: "us-east-1")`: The AWS region where the encryption key + lives. If not provided, may be populated from the `AWS_REGION` or + `AWS_DEFAULT_REGION` environment variables, from your `~/.aws/config` file, or + from instance metadata. + +- `access_key` `(string: )`: The AWS access key ID to use. May also be + specified by the `AWS_ACCESS_KEY_ID` environment variable or as part of the + AWS profile from the AWS CLI or instance profile. + +- `session_token` `(string: "")`: Specifies the AWS session token. This can also + be provided via the environment variable `AWS_SESSION_TOKEN`. + +- `secret_key` `(string: )`: The AWS secret access key to use. May + also be specified by the `AWS_SECRET_ACCESS_KEY` environment variable or as + part of the AWS profile from the AWS CLI or instance profile. + +- `kms_key_id` `(string: )`: The AWS KMS key ID or ARN to use for + encryption and decryption. An alias in the format `alias/key-alias-name` may + also be used here. + +- `endpoint` `(string: "")`: The KMS API endpoint to be used to make AWS KMS + requests. May also be specified by the `AWS_KMS_ENDPOINT` environment + variable. This is useful, for example, when connecting to KMS over a [VPC + Endpoint][]. If not set, Nomad will use the default API endpoint for your + region. + +## Authentication + +Authentication-related values must be provided, either as environment variables +or as configuration parameters. + +~> **Note:** Although the configuration file allows you to pass in +`AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` as part of the keyring block's +parameters, it is _strongly_ recommended to set these values via environment +variables or instance profile. + +AWS authentication values: + +- `AWS_REGION` or `AWS_DEFAULT_REGION` +- `AWS_ACCESS_KEY_ID` +- `AWS_SECRET_ACCESS_KEY` + +Note: The client uses the official AWS SDK and will use the specified +credentials, environment credentials, shared file credentials, or IAM role/ECS +task credentials in that order, if the above AWS specific values are not +provided. + +Nomad needs the following permissions on the KMS key: + +- `kms:Encrypt` +- `kms:Decrypt` +- `kms:DescribeKey` + +These can be granted via IAM permissions on the principal that Nomad uses, on +the KMS key policy for the KMS key, or via KMS Grants on the key. + +## Key rotation + +This seal supports rotating the root keys defined in AWS KMS +[doc][rotate_docs]. Both automatic rotation and manual rotation is supported for +KMS since the key information is stored with the encrypted data. Old keys must +not be disabled or deleted and are used to decrypt older data. Any new or +updated data will be encrypted with the current key defined in the keyring +configuration or set to current under a key alias. + +[VPC Endpoint]: https://docs.aws.amazon.com/kms/latest/developerguide/kms-vpc-endpoint.html +[rotate_docs]: https://docs.aws.amazon.com/kms/latest/developerguide/rotate-keys.html diff --git a/website/content/docs/configuration/keyring/azurekeyvault.mdx b/website/content/docs/configuration/keyring/azurekeyvault.mdx new file mode 100644 index 00000000000..5026b3795c3 --- /dev/null +++ b/website/content/docs/configuration/keyring/azurekeyvault.mdx @@ -0,0 +1,92 @@ +--- +layout: docs +page_title: Azure Key Vault - Keyring - Configuration +description: >- + The Azure Key Vault keyring configures Nomad to use Azure Key Vault as the key material + wrapping mechanism. +--- + +# `azurekeyvault` keyring + +The AWS KMS keyring configures Nomad to use AWS KMS to wrap its keyring. This +example shows configuring Azure Key Vault seal through the Vault configuration +file by providing all the required values: + +```hcl +seal "azurekeyvault" { + active = true + name = "example" + + # fields specific to azurekeyvault + tenant_id = "46646709-b63e-4747-be42-516edeaf1e14" + client_id = "03dc33fc-16d9-4b77-8152-3ec568f8af6e" + client_secret = "DUJDS3..." + vault_name = "nomad" + key_name = "nomad_key" +} +``` + +## `azurekeyvault` parameters + +These parameters apply to the `keyring` block in the Nomad configuration file: + +- `tenant_id` `(string: )`: The tenant id for the Azure Active + Directory organization. May also be specified by the `AZURE_TENANT_ID` + environment variable. + +- `client_id` `(string: )`: The client id for credentials to + query the Azure APIs. May also be specified by the `AZURE_CLIENT_ID` + environment variable. + +- `client_secret` `(string: )`: The client secret for + credentials to query the Azure APIs. May also be specified by the + `AZURE_CLIENT_SECRET` environment variable. + +- `environment` `(string: "AZUREPUBLICCLOUD")`: The Azure Cloud environment API + endpoints to use. May also be specified by the `AZURE_ENVIRONMENT` environment + variable. + +- `vault_name` `(string: )`: The Key Vault vault to use the encryption + keys for encryption and decryption. + +- `key_name` `(string: )`: The Key Vault key to use for encryption and + decryption. + +- `resource` `(string: "vault.azure.net")`: The AZ KeyVault resource's DNS + Suffix to connect to. May also be specified in the `AZURE_AD_RESOURCE` + environment variable. Needs to be changed to connect to Azure's Managed HSM + KeyVault instance type. + +## Authentication + +Authentication-related values must be provided, either as environment variables +or as configuration parameters. + +Azure authentication values: + +- `AZURE_TENANT_ID` +- `AZURE_CLIENT_ID` +- `AZURE_CLIENT_SECRET` +- `AZURE_ENVIRONMENT` +- `AZURE_AD_RESOURCE` + +~> **Note:** If Nomad is hosted on Azure, Vault can use Managed Service +Identities (MSI) to access Azure instead of an environment and shared client id +and secret. MSI must be [enabled][msi_enabled] on the VMs hosting Nomad, and it +is the preferred configuration since MSI prevents your Azure credentials from +being stored as clear text. + +-> **Note:** If you are using a Managed HSM KeyVault, `AZURE_AD_RESOURCE` or the +`resource` configuration parameter must be specified; usually this should point +to `managedhsm.azure.net`, but could point to other suffixes depending on Azure +environment. + +## Key rotation + +This seal supports rotating keys defined in Azure Key Vault. Key metadata is +stored with the encrypted data to ensure the correct key is used during +decryption operations. Set up Azure Key Vault with [key rotation][] using Azure +Automation Account and Vault will recognize newly rotated keys. + +[msi_enabled]: https://docs.microsoft.com/en-us/azure/active-directory/managed-service-identity/qs-configure-portal-windows-vm +[key rotation]: https://docs.microsoft.com/en-us/azure/key-vault/key-vault-key-rotation-log-monitoring diff --git a/website/content/docs/configuration/keyring/gcpckms.mdx b/website/content/docs/configuration/keyring/gcpckms.mdx new file mode 100644 index 00000000000..84022550596 --- /dev/null +++ b/website/content/docs/configuration/keyring/gcpckms.mdx @@ -0,0 +1,93 @@ +--- +layout: docs +page_title: GCP Cloud KMS - Keyrings - Configuration +description: >- + The GCP Cloud KMS keyring configures Nomad to use GCP Cloud KMS as the keyring + wrapping mechanism. +--- + +# `gcpckms` keyring + + +The GCP Cloud KMS keyring configures Nomad to use GCP Cloud KMS to wrap its +keyring. This example shows configuring GCP Cloud KMS keyring through the Nomad +configuration file by providing all the required values: + +```hcl +keyring "gcpckms" { + active = true + name = "example" + + credentials = "/etc/nomad.d/nomad-user-creds.json" + project = "nomad-project" + region = "global" + key_ring = "nomad-keyring" + crypto_key = "nomad-key" +} +``` + +## `gcpckms` parameters + +These parameters apply to the `keyring` stanza in the Nomad configuration file: + +- `credentials` `(string: )`: The path to the credentials JSON file to + use. May be also specified by the `GOOGLE_CREDENTIALS` or + `GOOGLE_APPLICATION_CREDENTIALS` environment variable or set automatically if + running under Google App Engine, Google Compute Engine or Google Kubernetes + Engine. + +- `project` `(string: )`: The GCP project ID to use. May also be + specified by the `GOOGLE_PROJECT` environment variable. + +- `region` `(string: )`: The GCP region/location where the key ring + lives. May also be specified by the `GOOGLE_REGION` environment variable. + +- `key_ring` `(string: )`: The GCP CKMS key ring to use. + +- `crypto_key` `(string: )`: The GCP CKMS crypto key to use for + encryption and decryption. + +## Authentication & permissions + +Authentication-related values must be provided, either as environment +variables or as configuration parameters. + +GCP authentication values: + +- `GOOGLE_CREDENTIALS` or `GOOGLE_APPLICATION_CREDENTIALS` +- `GOOGLE_PROJECT` +- `GOOGLE_REGION` + +Note: The client uses the official Google SDK and will use the specified +credentials, environment credentials, or [application default credentials][] in +that order, if the above GCP specific values are not provided. + +The service account needs the following minimum permissions on the crypto key: + +```text +cloudkms.cryptoKeyVersions.useToEncrypt +cloudkms.cryptoKeyVersions.useToDecrypt +cloudkms.cryptoKeys.get +``` + +These permissions can be described with the following role: + +```text +roles/cloudkms.cryptoKeyEncrypterDecrypter +cloudkms.cryptoKeys.get +``` + +`cloudkms.cryptoKeys.get` permission is used for retrieving metadata information +of keys from CloudKMS within this engine initialization process. + +## Key rotation + +This keyring supports rotating keys defined in Google Cloud KMS +[doc][rotating_keys]. Both scheduled rotation and manual rotation is supported +for CKMS since the key information. Old keys version must not be disabled or +deleted and are used to decrypt older data. Any new or updated data will be +encrypted with the primary key version. + + +[application default credentials]: https://developers.google.com/identity/protocols/application-default-credentials +[rotating_keys]: https://cloud.google.com/kms/docs/rotating-keys diff --git a/website/content/docs/configuration/keyring/index.mdx b/website/content/docs/configuration/keyring/index.mdx new file mode 100644 index 00000000000..6fbdd36ee52 --- /dev/null +++ b/website/content/docs/configuration/keyring/index.mdx @@ -0,0 +1,106 @@ +--- +layout: docs +page_title: keyring Block - Agent Configuration +description: >- + The "keyring" block configures the Nomad servers keyring decryption behavior. +--- + +# `keyring` Block + + + +The `keyring` block configures how the Nomad server protects the keyring used +for encrypting [variables][] and signing [workload identities][]. By default, +Nomad encrypts the key material with a unique key encryption key (KEK) that is +not shared between servers, and writes the wrapped key material to disk as +described in [Key Management][]. Nomad refers to this as `"aead"`. Using the +`keyring` configuration block, Nomad servers can instead use an external KMS or +Vault transit encryption. The encrypted key is stored on disk but is now +protected against offline attacks because the KEK is not present in the file. + +All `keyring` blocks require a label for the KMS type. Each external KMS has its +own configuration options. The `keyring` block only applies to Nomad servers, +not Nomad clients. + +```hcl +keyring [TYPE] { + name = "example" + active = true +} +``` + +The default `keyring` configuration is as follows: + +```hcl +keyring "aead" { + active = true +} +``` + +## `keyring` Parameters + +All `keyring` blocks support the following parameters. + +- `name` `(string: "")` - A unique identifier for the `keyring` block, used to + disambiguate when there are multiple blocks of the same type. + +- `active` `(bool: false)` - Indicates which block to use for encrypting + keys. For existing servers, changing which block is `active` only impacts new + keys created by a [key rotation][]. Existing keys are encrypted with the + previous `active` block, so those blocks should not be removed from the + configuration until they have been garbage collected and the keys have been + removed from the keystore. In Nomad Community Edition, only a single keyring + can be `active` at a time. + +## Migrating Keyrings + +To migrate to a new keyring, add the new `keyring` block to the servers with +`active=true`, and restart the servers. The server will start using the new +keyring wrapper when the current key is rotated either periodically or via the +[`nomad operator root keyring rotate`][keyring_rotate_cmd] command. + +Adding or removing a keyring requires restarting the Nomad server. You should +not remove a keyring until all keys it wraps have been garbage collected. You +can examine the contents of the `keystore` directory found in the Nomad server's +data directory and compare this against the output of [`nomad operator root +keyring list`][keyring_list_cmd]. + +## High Availability + + + This functionality only exists in Nomad Enterprise. + + +Keyring high availability provides the means to configure multiple active +`keyring` blocks, in order to have resilience against an outage of an external +KMS. When there are multiple `keyring` blocks with `active = true`, Nomad +Enterprise will encrypt each key it creates in all the active KMS providers. On +startup, Nomad will try each KMS provider in order until it finds a provider +that can decrypt each key. + +In this example high availability configuration, both `keyring` blocks use the +`"awskms"` provider, but each block uses a different KMS key in a different AWS +region. + +```hcl +keyring "awskms" { + active = true + name = "kms-us-east-1" + region = "us-east-1" + kms_key_id = "arn:aws:kms:us-east-1:000000000000:key/7d23633a-4464-11ef-a273-abd12example" +} + +keyring "awskms" { + active = true + name = "kms-us-east-2" + region = "us-east-2" + kms_key_id = "alias/nomad-keyring-us-east-2" +} +``` + +[variables]: /nomad/docs/concepts/variables +[workload identities]: /nomad/docs/concepts/workload-identity +[Key Management]: /nomad/docs/operations/key-management +[key rotation]: /nomad/docs/operations/key-management#key-rotation +[keyring_rotate_cmd]: /nomad/docs/commands/operator/root/keyring-rotate +[keyring_list_cmd]: /nomad/docs/commands/operator/root/keyring-list diff --git a/website/content/docs/configuration/keyring/transit.mdx b/website/content/docs/configuration/keyring/transit.mdx new file mode 100644 index 00000000000..fe16580c3dc --- /dev/null +++ b/website/content/docs/configuration/keyring/transit.mdx @@ -0,0 +1,129 @@ +--- +layout: docs +page_title: Vault Transit - Keyring - Configuration +description: |- + The Transit keyring configures Nomad to use Vault's Transit Secret Engine as + the key material wrapping mechanism. +--- + +# `transit` keyring + +The Vault transit keyring configures Nomad to use Vault's Transit Secret Engine +to wrap its keyring. This example shows configuring Vault Transit through the +Nomad configuration file by providing all the required values: + +```hcl +keyring "transit" { + + active = true + name = "example" + + # fields specific to transit + address = "https://vault:8200" + token = "s.Qf1s5zigZ4OX6akYjQXJC1jY" + disable_renewal = "false" + + // Key configuration + key_name = "transit_key_name" + mount_path = "transit/" + namespace = "ns1/" + + // TLS Configuration + tls_ca_cert = "/etc/vault/ca_cert.pem" + tls_client_cert = "/etc/vault/client_cert.pem" + tls_client_key = "/etc/vault/ca_cert.pem" + tls_server_name = "vault" + tls_skip_verify = "false" +} +``` + +## `transit` parameters + +These parameters apply to the `keyring` stanza in the Nomad configuration file: + +- `key_name` `(string: )`: The transit key to use for encryption and + decryption. + +- `key_id_prefix` `(string: "")`: An optional string to add to the key id of + values wrapped by this transit keyring. This can help disambiguate between two + transit keyring. + +- `mount_path` `(string: )`: The mount path to the transit secret + engine. + +- `disable_renewal` `(string: "false")`: Disables the automatic renewal of the + token in case the lifecycle of the token is managed with some other mechanism + outside of Vault, such as Vault Agent. + +The following parameters can be set in the `keyring` block but will fallback to +the values set in the server's [`vault`][vault_config] block if not set +here. Fields indicated as required must be set either here or the `vault` block. + +- `address` `(string: )`: The full address to the Vault cluster. This + may also be specified by the `VAULT_ADDR` environment variable. + +- `token` `(string: )`: The Vault token to use. This may also be + specified by the `VAULT_TOKEN` environment variable. + +- `namespace` `(string: "")`: The namespace path to the transit secret engine. + This may also be supplied using the `VAULT_NAMESPACE` environment variable. + +- `tls_ca_cert` `(string: "")`: Specifies the path to the CA certificate file used + for communication with the Vault server. This may also be specified using the + `VAULT_CACERT` environment variable. + +- `tls_client_cert` `(string: "")`: Specifies the path to the client certificate + for communication with the Vault server. This may also be specified using the + `VAULT_CLIENT_CERT` environment variable. + +- `tls_client_key` `(string: "")`: Specifies the path to the private key for + communication with the Vault server. This may also be specified using the + `VAULT_CLIENT_KEY` environment variable. + +- `tls_server_name` `(string: "")`: Name to use as the SNI host when connecting + to the Vault server via TLS. This may also be specified via the + `VAULT_TLS_SERVER_NAME` environment variable. + +- `tls_skip_verify` `(bool: "false")`: Disable verification of TLS certificates. + Using this option is highly discouraged and decreases the security of data + transmissions to and from the Vault server. This may also be specified using the + `VAULT_SKIP_VERIFY` environment variable. + +## Authentication + +Authentication-related values must be provided, either as environment variables +or as configuration parameters. + +~> **Note:** Although the configuration file allows you to pass in `VAULT_TOKEN` +as part of the keyring's parameters, it is _strongly_ recommended to set these +values via environment variables. + +The Vault token used to authenticate needs the following permissions on the +transit key: + +```hcl +path "/encrypt/" { + capabilities = ["update"] +} + +path "/decrypt/" { + capabilities = ["update"] +} +``` + +Other considerations for the token used: +* It should probably be an [orphan token][], otherwise when the parent token + expires or gets revoked the keyring will break. +* Consider making it a [periodic token][] and not setting an explicit max TTL, + otherwise at some point it will cease to be renewable. + +## Key rotation + +This keyring supports key rotation using the Transit Secret Engine's key rotation +endpoints. See [doc][rotate_doc]. Old keys must not be disabled or deleted and +are used to decrypt older data. + +[orphan token]: /vault/docs/concepts/tokens#token-hierarchies-and-orphan-tokens +[periodic token]: /vault/docs/concepts/tokens#periodic-tokens +[rotate_doc]: /vault/api-docs/secret/transit#rotate-key +[vault_config]: https://developer.hashicorp.com/nomad/docs/configuration/vault diff --git a/website/content/docs/operations/key-management.mdx b/website/content/docs/operations/key-management.mdx index 2f8b92165f6..303c3c01e75 100644 --- a/website/content/docs/operations/key-management.mdx +++ b/website/content/docs/operations/key-management.mdx @@ -11,7 +11,9 @@ sign task [workload identities][]. The servers store key metadata in raft, but the encryption key material is stored in a separate file in the `keystore` subdirectory of the Nomad [data directory][]. These files have the extension `.nks.json`. The key material in each file is wrapped in a unique key encryption -key (KEK) that is not shared between servers. +key (KEK) that is not shared between servers. Nomad servers can use an external +KMS or Vault transit encryption to wrap the key material using the [`keyring`][] +configuration block. Under normal operations the keyring is entirely managed by Nomad, but this section provides administrators additional context around key replication and @@ -62,5 +64,6 @@ keyring rotate`][] once the servers have joined. [variables]: /nomad/docs/concepts/variables [workload identities]: /nomad/docs/concepts/workload-identity [data directory]: /nomad/docs/configuration#data_dir +[`keyring`]: /nomad/docs/configuration/keyring [`nomad operator root keyring rotate -full`]: /nomad/docs/commands/operator/root/keyring-rotate [`nomad operator root keyring rotate`]: /nomad/docs/commands/operator/root/keyring-rotate diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json index a6f5270c4c5..2080de6b5be 100644 --- a/website/data/docs-nav-data.json +++ b/website/data/docs-nav-data.json @@ -66,7 +66,7 @@ } ] } - ] + ] }, { "title": "Integrations", @@ -236,6 +236,31 @@ "title": "consul", "path": "configuration/consul" }, + { + "title": "keyring", + "routes": [ + { + "title": "Overview", + "path": "configuration/keyring" + }, + { + "title": "AWS KMS", + "path": "configuration/keyring/awskms" + }, + { + "title": "Azure Key Vault", + "path": "configuration/keyring/azurekeyvault" + }, + { + "title": "GCP Cloud KMS", + "path": "configuration/keyring/gcpckms" + }, + { + "title": "Vault Transit", + "path": "configuration/keyring/transit" + } + ] + }, { "title": "plugin", "path": "configuration/plugin" From 32f9274e8995e48bafafd90a8141634c0a8c912e Mon Sep 17 00:00:00 2001 From: Tim Gross Date: Thu, 18 Jul 2024 09:29:49 -0400 Subject: [PATCH 2/4] Apply suggestions from code review Co-authored-by: Aimee Ukasick --- .../docs/configuration/keyring/awskms.mdx | 35 +++++----------- .../configuration/keyring/azurekeyvault.mdx | 30 +++++--------- .../docs/configuration/keyring/gcpckms.mdx | 21 +++++----- .../docs/configuration/keyring/index.mdx | 8 ++-- .../docs/configuration/keyring/transit.mdx | 41 ++++++++----------- 5 files changed, 53 insertions(+), 82 deletions(-) diff --git a/website/content/docs/configuration/keyring/awskms.mdx b/website/content/docs/configuration/keyring/awskms.mdx index e67829aed95..5039e32a098 100644 --- a/website/content/docs/configuration/keyring/awskms.mdx +++ b/website/content/docs/configuration/keyring/awskms.mdx @@ -10,7 +10,7 @@ description: |- The AWS KMS keyring configures Nomad to use AWS KMS to wrap its keyring. This example shows configuring AWS KMS keyring through the Nomad configuration file by -providing all the required values: +providing all the required values. ```hcl keyring "awskms" { @@ -35,35 +35,25 @@ These parameters apply to the `keyring` block in the Nomad configuration file: `AWS_DEFAULT_REGION` environment variables, from your `~/.aws/config` file, or from instance metadata. -- `access_key` `(string: )`: The AWS access key ID to use. May also be - specified by the `AWS_ACCESS_KEY_ID` environment variable or as part of the - AWS profile from the AWS CLI or instance profile. +- `access_key` `(string: )`: The AWS access key ID to use. Alternately specify via the `AWS_ACCESS_KEY_ID` environment variable or as part of the AWS profile from the AWS CLI or instance profile. -- `session_token` `(string: "")`: Specifies the AWS session token. This can also - be provided via the environment variable `AWS_SESSION_TOKEN`. +- `session_token` `(string: "")`: Specifies the AWS session token. Alternately specify via the environment variable `AWS_SESSION_TOKEN`. -- `secret_key` `(string: )`: The AWS secret access key to use. May - also be specified by the `AWS_SECRET_ACCESS_KEY` environment variable or as - part of the AWS profile from the AWS CLI or instance profile. +- `secret_key` `(string: )`: The AWS secret access key to use. Alternately specify via the `AWS_SECRET_ACCESS_KEY` environment variable or as part of the AWS profile from the AWS CLI or instance profile. - `kms_key_id` `(string: )`: The AWS KMS key ID or ARN to use for - encryption and decryption. An alias in the format `alias/key-alias-name` may - also be used here. + encryption and decryption. You can alternately use an alias in the format `alias/key-alias-name`. -- `endpoint` `(string: "")`: The KMS API endpoint to be used to make AWS KMS - requests. May also be specified by the `AWS_KMS_ENDPOINT` environment - variable. This is useful, for example, when connecting to KMS over a [VPC - Endpoint][]. If not set, Nomad will use the default API endpoint for your - region. +- `endpoint` `(string: "")`: The KMS API endpoint for AWS KMS requests. Alternately specify via the `AWS_KMS_ENDPOINT` environment variable. This is useful, for example, when connecting to KMS over a [VPC Endpoint][]. If not set, Nomad uses the default API endpoint for your region. ## Authentication -Authentication-related values must be provided, either as environment variables +You must provide authentication-related values either as environment variables or as configuration parameters. ~> **Note:** Although the configuration file allows you to pass in `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` as part of the keyring block's -parameters, it is _strongly_ recommended to set these values via environment +parameters, we strongly recommended that you set these values via environment variables or instance profile. AWS authentication values: @@ -72,10 +62,7 @@ AWS authentication values: - `AWS_ACCESS_KEY_ID` - `AWS_SECRET_ACCESS_KEY` -Note: The client uses the official AWS SDK and will use the specified -credentials, environment credentials, shared file credentials, or IAM role/ECS -task credentials in that order, if the above AWS specific values are not -provided. +Note: The client uses the official AWS SDK and the specified credentials, environment credentials, shared file credentials, or IAM role/ECS task credentials in that order, if you do not provide the aforementioned AWS-specific values. Nomad needs the following permissions on the KMS key: @@ -83,7 +70,7 @@ Nomad needs the following permissions on the KMS key: - `kms:Decrypt` - `kms:DescribeKey` -These can be granted via IAM permissions on the principal that Nomad uses, on +Grant these via IAM permissions on the principal that Nomad uses, on the KMS key policy for the KMS key, or via KMS Grants on the key. ## Key rotation @@ -92,7 +79,7 @@ This seal supports rotating the root keys defined in AWS KMS [doc][rotate_docs]. Both automatic rotation and manual rotation is supported for KMS since the key information is stored with the encrypted data. Old keys must not be disabled or deleted and are used to decrypt older data. Any new or -updated data will be encrypted with the current key defined in the keyring +updated data is encrypted with the current key defined in the keyring configuration or set to current under a key alias. [VPC Endpoint]: https://docs.aws.amazon.com/kms/latest/developerguide/kms-vpc-endpoint.html diff --git a/website/content/docs/configuration/keyring/azurekeyvault.mdx b/website/content/docs/configuration/keyring/azurekeyvault.mdx index 5026b3795c3..bfa78ce0601 100644 --- a/website/content/docs/configuration/keyring/azurekeyvault.mdx +++ b/website/content/docs/configuration/keyring/azurekeyvault.mdx @@ -10,7 +10,7 @@ description: >- The AWS KMS keyring configures Nomad to use AWS KMS to wrap its keyring. This example shows configuring Azure Key Vault seal through the Vault configuration -file by providing all the required values: +file by providing all the required values. ```hcl seal "azurekeyvault" { @@ -31,19 +31,16 @@ seal "azurekeyvault" { These parameters apply to the `keyring` block in the Nomad configuration file: - `tenant_id` `(string: )`: The tenant id for the Azure Active - Directory organization. May also be specified by the `AZURE_TENANT_ID` - environment variable. + Directory organization. Alternately specify via the `AZURE_TENANT_ID` environment variable. - `client_id` `(string: )`: The client id for credentials to - query the Azure APIs. May also be specified by the `AZURE_CLIENT_ID` - environment variable. + query the Azure APIs. Alternately specify via the `AZURE_CLIENT_ID` environment variable. - `client_secret` `(string: )`: The client secret for - credentials to query the Azure APIs. May also be specified by the - `AZURE_CLIENT_SECRET` environment variable. + credentials to query the Azure APIs. Alternately specify via the `AZURE_CLIENT_SECRET` environment variable. - `environment` `(string: "AZUREPUBLICCLOUD")`: The Azure Cloud environment API - endpoints to use. May also be specified by the `AZURE_ENVIRONMENT` environment + endpoints to use. Alternately specify via the `AZURE_ENVIRONMENT` environment variable. - `vault_name` `(string: )`: The Key Vault vault to use the encryption @@ -53,13 +50,13 @@ These parameters apply to the `keyring` block in the Nomad configuration file: decryption. - `resource` `(string: "vault.azure.net")`: The AZ KeyVault resource's DNS - Suffix to connect to. May also be specified in the `AZURE_AD_RESOURCE` + Suffix to connect to. Alternately specify via the `AZURE_AD_RESOURCE` environment variable. Needs to be changed to connect to Azure's Managed HSM KeyVault instance type. ## Authentication -Authentication-related values must be provided, either as environment variables +You must provide authentication-related values either as environment variables or as configuration parameters. Azure authentication values: @@ -70,23 +67,16 @@ Azure authentication values: - `AZURE_ENVIRONMENT` - `AZURE_AD_RESOURCE` -~> **Note:** If Nomad is hosted on Azure, Vault can use Managed Service -Identities (MSI) to access Azure instead of an environment and shared client id -and secret. MSI must be [enabled][msi_enabled] on the VMs hosting Nomad, and it -is the preferred configuration since MSI prevents your Azure credentials from -being stored as clear text. +~> **Note:** If Nomad is hosted on Azure, Vault can use Managed Service Identities (MSI) to access Azure instead of an environment and shared client id and secret. MSI must be [enabled][msi_enabled] on the VMs hosting Nomad. We recommend this configuration since MSI prevents your Azure credentials from being stored as clear text. --> **Note:** If you are using a Managed HSM KeyVault, `AZURE_AD_RESOURCE` or the -`resource` configuration parameter must be specified; usually this should point -to `managedhsm.azure.net`, but could point to other suffixes depending on Azure -environment. +-> **Note:** If you are using a Managed HSM KeyVault, you must specify `AZURE_AD_RESOURCE` or the `resource` configuration parameter; usually this should point to `managedhsm.azure.net` but could point to other suffixes depending on Azure environment. ## Key rotation This seal supports rotating keys defined in Azure Key Vault. Key metadata is stored with the encrypted data to ensure the correct key is used during decryption operations. Set up Azure Key Vault with [key rotation][] using Azure -Automation Account and Vault will recognize newly rotated keys. +Automation Account so Vault recognizes newly rotated keys. [msi_enabled]: https://docs.microsoft.com/en-us/azure/active-directory/managed-service-identity/qs-configure-portal-windows-vm [key rotation]: https://docs.microsoft.com/en-us/azure/key-vault/key-vault-key-rotation-log-monitoring diff --git a/website/content/docs/configuration/keyring/gcpckms.mdx b/website/content/docs/configuration/keyring/gcpckms.mdx index 84022550596..8b9bc813fce 100644 --- a/website/content/docs/configuration/keyring/gcpckms.mdx +++ b/website/content/docs/configuration/keyring/gcpckms.mdx @@ -11,7 +11,7 @@ description: >- The GCP Cloud KMS keyring configures Nomad to use GCP Cloud KMS to wrap its keyring. This example shows configuring GCP Cloud KMS keyring through the Nomad -configuration file by providing all the required values: +configuration file by providing all the required values. ```hcl keyring "gcpckms" { @@ -31,16 +31,15 @@ keyring "gcpckms" { These parameters apply to the `keyring` stanza in the Nomad configuration file: - `credentials` `(string: )`: The path to the credentials JSON file to - use. May be also specified by the `GOOGLE_CREDENTIALS` or + use. Alternately specify via the `GOOGLE_CREDENTIALS` or `GOOGLE_APPLICATION_CREDENTIALS` environment variable or set automatically if - running under Google App Engine, Google Compute Engine or Google Kubernetes + running under Google App Engine, Google Compute Engine, or Google Kubernetes Engine. -- `project` `(string: )`: The GCP project ID to use. May also be - specified by the `GOOGLE_PROJECT` environment variable. +- `project` `(string: )`: The GCP project ID to use. Alternately specify via the `GOOGLE_PROJECT` environment variable. - `region` `(string: )`: The GCP region/location where the key ring - lives. May also be specified by the `GOOGLE_REGION` environment variable. + lives. Alternately specify via the `GOOGLE_REGION` environment variable. - `key_ring` `(string: )`: The GCP CKMS key ring to use. @@ -49,7 +48,7 @@ These parameters apply to the `keyring` stanza in the Nomad configuration file: ## Authentication & permissions -Authentication-related values must be provided, either as environment +You must provide authentication-related values either as environment variables or as configuration parameters. GCP authentication values: @@ -58,9 +57,9 @@ GCP authentication values: - `GOOGLE_PROJECT` - `GOOGLE_REGION` -Note: The client uses the official Google SDK and will use the specified +Note: The client uses the official Google SDK and the specified credentials, environment credentials, or [application default credentials][] in -that order, if the above GCP specific values are not provided. +that order, if you do not provide the aforementioned GCP-specific values. The service account needs the following minimum permissions on the crypto key: @@ -77,7 +76,7 @@ roles/cloudkms.cryptoKeyEncrypterDecrypter cloudkms.cryptoKeys.get ``` -`cloudkms.cryptoKeys.get` permission is used for retrieving metadata information +Use `cloudkms.cryptoKeys.get` permission for retrieving metadata information of keys from CloudKMS within this engine initialization process. ## Key rotation @@ -85,7 +84,7 @@ of keys from CloudKMS within this engine initialization process. This keyring supports rotating keys defined in Google Cloud KMS [doc][rotating_keys]. Both scheduled rotation and manual rotation is supported for CKMS since the key information. Old keys version must not be disabled or -deleted and are used to decrypt older data. Any new or updated data will be +deleted and are used to decrypt older data. Any new or updated data is encrypted with the primary key version. diff --git a/website/content/docs/configuration/keyring/index.mdx b/website/content/docs/configuration/keyring/index.mdx index 6fbdd36ee52..3bb34547f13 100644 --- a/website/content/docs/configuration/keyring/index.mdx +++ b/website/content/docs/configuration/keyring/index.mdx @@ -14,7 +14,7 @@ for encrypting [variables][] and signing [workload identities][]. By default, Nomad encrypts the key material with a unique key encryption key (KEK) that is not shared between servers, and writes the wrapped key material to disk as described in [Key Management][]. Nomad refers to this as `"aead"`. Using the -`keyring` configuration block, Nomad servers can instead use an external KMS or +`keyring` configuration block, Nomad servers can instead use an external key management system (KMS) or Vault transit encryption. The encrypted key is stored on disk but is now protected against offline attacks because the KEK is not present in the file. @@ -55,7 +55,7 @@ All `keyring` blocks support the following parameters. ## Migrating Keyrings To migrate to a new keyring, add the new `keyring` block to the servers with -`active=true`, and restart the servers. The server will start using the new +`active=true`, and restart the servers. The server starts using the new keyring wrapper when the current key is rotated either periodically or via the [`nomad operator root keyring rotate`][keyring_rotate_cmd] command. @@ -74,8 +74,8 @@ keyring list`][keyring_list_cmd]. Keyring high availability provides the means to configure multiple active `keyring` blocks, in order to have resilience against an outage of an external KMS. When there are multiple `keyring` blocks with `active = true`, Nomad -Enterprise will encrypt each key it creates in all the active KMS providers. On -startup, Nomad will try each KMS provider in order until it finds a provider +Enterprise encrypts each key it creates in all the active KMS providers. On +startup, Nomad tries each KMS provider in order until it finds a provider that can decrypt each key. In this example high availability configuration, both `keyring` blocks use the diff --git a/website/content/docs/configuration/keyring/transit.mdx b/website/content/docs/configuration/keyring/transit.mdx index fe16580c3dc..bbbe3f7ca88 100644 --- a/website/content/docs/configuration/keyring/transit.mdx +++ b/website/content/docs/configuration/keyring/transit.mdx @@ -10,7 +10,7 @@ description: |- The Vault transit keyring configures Nomad to use Vault's Transit Secret Engine to wrap its keyring. This example shows configuring Vault Transit through the -Nomad configuration file by providing all the required values: +Nomad configuration file by providing all the required values. ```hcl keyring "transit" { @@ -55,50 +55,47 @@ These parameters apply to the `keyring` stanza in the Nomad configuration file: token in case the lifecycle of the token is managed with some other mechanism outside of Vault, such as Vault Agent. -The following parameters can be set in the `keyring` block but will fallback to -the values set in the server's [`vault`][vault_config] block if not set -here. Fields indicated as required must be set either here or the `vault` block. +Set the following parameters in the `keyring` block. If not set here, Nomad uses +the values set in the server's [`vault`][vault_config] block. You must set required fields either here or the `vault` block. -- `address` `(string: )`: The full address to the Vault cluster. This - may also be specified by the `VAULT_ADDR` environment variable. +- `address` `(string: )`: The full address to the Vault cluster. Alternately specify via the `VAULT_ADDR` environment variable. -- `token` `(string: )`: The Vault token to use. This may also be - specified by the `VAULT_TOKEN` environment variable. +- `token` `(string: )`: The Vault token to use. Alternately specify via the `VAULT_TOKEN` environment variable. - `namespace` `(string: "")`: The namespace path to the transit secret engine. - This may also be supplied using the `VAULT_NAMESPACE` environment variable. + Alternately specify via the `VAULT_NAMESPACE` environment variable. - `tls_ca_cert` `(string: "")`: Specifies the path to the CA certificate file used - for communication with the Vault server. This may also be specified using the + for communication with the Vault server. Alternately specify via the `VAULT_CACERT` environment variable. - `tls_client_cert` `(string: "")`: Specifies the path to the client certificate - for communication with the Vault server. This may also be specified using the + for communication with the Vault server. Alternately specify via the `VAULT_CLIENT_CERT` environment variable. - `tls_client_key` `(string: "")`: Specifies the path to the private key for - communication with the Vault server. This may also be specified using the + communication with the Vault server. Alternately specify via the `VAULT_CLIENT_KEY` environment variable. - `tls_server_name` `(string: "")`: Name to use as the SNI host when connecting - to the Vault server via TLS. This may also be specified via the + to the Vault server via TLS. Alternately specify via the `VAULT_TLS_SERVER_NAME` environment variable. - `tls_skip_verify` `(bool: "false")`: Disable verification of TLS certificates. Using this option is highly discouraged and decreases the security of data - transmissions to and from the Vault server. This may also be specified using the + transmissions to and from the Vault server. Alternately specify via the `VAULT_SKIP_VERIFY` environment variable. ## Authentication -Authentication-related values must be provided, either as environment variables +You must provide authentication-related values either as environment variables or as configuration parameters. -~> **Note:** Although the configuration file allows you to pass in `VAULT_TOKEN` -as part of the keyring's parameters, it is _strongly_ recommended to set these +~> **Note:** Although the configuration file lets you to pass in `VAULT_TOKEN` +as part of the keyring's parameters, we strongly recommended that you set these values via environment variables. -The Vault token used to authenticate needs the following permissions on the +The Vault authentication token needs the following permissions on the transit key: ```hcl @@ -112,15 +109,13 @@ path "/decrypt/" { ``` Other considerations for the token used: -* It should probably be an [orphan token][], otherwise when the parent token - expires or gets revoked the keyring will break. -* Consider making it a [periodic token][] and not setting an explicit max TTL, - otherwise at some point it will cease to be renewable. +* It should probably be an [orphan token][], otherwise when the parent token expires or gets revoked the keyring breaks. +* Consider making it a [periodic token][] and not setting an explicit max TTL, otherwise at some point it ceases to be renewable. ## Key rotation This keyring supports key rotation using the Transit Secret Engine's key rotation -endpoints. See [doc][rotate_doc]. Old keys must not be disabled or deleted and +endpoints. Refer to [Vault docs][rotate_doc]. Old keys must not be disabled or deleted and are used to decrypt older data. [orphan token]: /vault/docs/concepts/tokens#token-hierarchies-and-orphan-tokens From 9b3f186f64f6626bd50634e8e47c309eb94f47e7 Mon Sep 17 00:00:00 2001 From: Tim Gross Date: Thu, 18 Jul 2024 09:37:22 -0400 Subject: [PATCH 3/4] reflow markdown, replace seal with keyring --- .../docs/configuration/keyring/awskms.mdx | 34 ++++++++++++------ .../configuration/keyring/azurekeyvault.mdx | 30 ++++++++++------ .../docs/configuration/keyring/gcpckms.mdx | 17 ++++----- .../docs/configuration/keyring/index.mdx | 17 ++++----- .../docs/configuration/keyring/transit.mdx | 35 +++++++++++-------- 5 files changed, 81 insertions(+), 52 deletions(-) diff --git a/website/content/docs/configuration/keyring/awskms.mdx b/website/content/docs/configuration/keyring/awskms.mdx index 5039e32a098..119736668df 100644 --- a/website/content/docs/configuration/keyring/awskms.mdx +++ b/website/content/docs/configuration/keyring/awskms.mdx @@ -9,8 +9,8 @@ description: |- # `awskms` keyring The AWS KMS keyring configures Nomad to use AWS KMS to wrap its keyring. This -example shows configuring AWS KMS keyring through the Nomad configuration file by -providing all the required values. +example shows configuring AWS KMS keyring through the Nomad configuration file +by providing all the required values. ```hcl keyring "awskms" { @@ -35,16 +35,25 @@ These parameters apply to the `keyring` block in the Nomad configuration file: `AWS_DEFAULT_REGION` environment variables, from your `~/.aws/config` file, or from instance metadata. -- `access_key` `(string: )`: The AWS access key ID to use. Alternately specify via the `AWS_ACCESS_KEY_ID` environment variable or as part of the AWS profile from the AWS CLI or instance profile. +- `access_key` `(string: )`: The AWS access key ID to use. Alternately + specify via the `AWS_ACCESS_KEY_ID` environment variable or as part of the AWS + profile from the AWS CLI or instance profile. -- `session_token` `(string: "")`: Specifies the AWS session token. Alternately specify via the environment variable `AWS_SESSION_TOKEN`. +- `session_token` `(string: "")`: Specifies the AWS session token. Alternately + specify via the environment variable `AWS_SESSION_TOKEN`. -- `secret_key` `(string: )`: The AWS secret access key to use. Alternately specify via the `AWS_SECRET_ACCESS_KEY` environment variable or as part of the AWS profile from the AWS CLI or instance profile. +- `secret_key` `(string: )`: The AWS secret access key to + use. Alternately specify via the `AWS_SECRET_ACCESS_KEY` environment variable + or as part of the AWS profile from the AWS CLI or instance profile. - `kms_key_id` `(string: )`: The AWS KMS key ID or ARN to use for - encryption and decryption. You can alternately use an alias in the format `alias/key-alias-name`. + encryption and decryption. You can alternately use an alias in the format + `alias/key-alias-name`. -- `endpoint` `(string: "")`: The KMS API endpoint for AWS KMS requests. Alternately specify via the `AWS_KMS_ENDPOINT` environment variable. This is useful, for example, when connecting to KMS over a [VPC Endpoint][]. If not set, Nomad uses the default API endpoint for your region. +- `endpoint` `(string: "")`: The KMS API endpoint for AWS KMS + requests. Alternately specify via the `AWS_KMS_ENDPOINT` environment + variable. This is useful, for example, when connecting to KMS over a [VPC + Endpoint][]. If not set, Nomad uses the default API endpoint for your region. ## Authentication @@ -62,7 +71,10 @@ AWS authentication values: - `AWS_ACCESS_KEY_ID` - `AWS_SECRET_ACCESS_KEY` -Note: The client uses the official AWS SDK and the specified credentials, environment credentials, shared file credentials, or IAM role/ECS task credentials in that order, if you do not provide the aforementioned AWS-specific values. +Note: The client uses the official AWS SDK and the specified credentials, +environment credentials, shared file credentials, or IAM role/ECS task +credentials in that order, if you do not provide the aforementioned AWS-specific +values. Nomad needs the following permissions on the KMS key: @@ -70,12 +82,12 @@ Nomad needs the following permissions on the KMS key: - `kms:Decrypt` - `kms:DescribeKey` -Grant these via IAM permissions on the principal that Nomad uses, on -the KMS key policy for the KMS key, or via KMS Grants on the key. +Grant these via IAM permissions on the principal that Nomad uses, on the KMS key +policy for the KMS key, or via KMS Grants on the key. ## Key rotation -This seal supports rotating the root keys defined in AWS KMS +This keyring supports rotating the root keys defined in AWS KMS [doc][rotate_docs]. Both automatic rotation and manual rotation is supported for KMS since the key information is stored with the encrypted data. Old keys must not be disabled or deleted and are used to decrypt older data. Any new or diff --git a/website/content/docs/configuration/keyring/azurekeyvault.mdx b/website/content/docs/configuration/keyring/azurekeyvault.mdx index bfa78ce0601..4c32beac58c 100644 --- a/website/content/docs/configuration/keyring/azurekeyvault.mdx +++ b/website/content/docs/configuration/keyring/azurekeyvault.mdx @@ -9,8 +9,8 @@ description: >- # `azurekeyvault` keyring The AWS KMS keyring configures Nomad to use AWS KMS to wrap its keyring. This -example shows configuring Azure Key Vault seal through the Vault configuration -file by providing all the required values. +example shows configuring Azure Key Vault keyring through the Nomad +configuration file by providing all the required values. ```hcl seal "azurekeyvault" { @@ -31,13 +31,16 @@ seal "azurekeyvault" { These parameters apply to the `keyring` block in the Nomad configuration file: - `tenant_id` `(string: )`: The tenant id for the Azure Active - Directory organization. Alternately specify via the `AZURE_TENANT_ID` environment variable. + Directory organization. Alternately specify via the `AZURE_TENANT_ID` + environment variable. - `client_id` `(string: )`: The client id for credentials to - query the Azure APIs. Alternately specify via the `AZURE_CLIENT_ID` environment variable. + query the Azure APIs. Alternately specify via the `AZURE_CLIENT_ID` + environment variable. - `client_secret` `(string: )`: The client secret for - credentials to query the Azure APIs. Alternately specify via the `AZURE_CLIENT_SECRET` environment variable. + credentials to query the Azure APIs. Alternately specify via the + `AZURE_CLIENT_SECRET` environment variable. - `environment` `(string: "AZUREPUBLICCLOUD")`: The Azure Cloud environment API endpoints to use. Alternately specify via the `AZURE_ENVIRONMENT` environment @@ -50,8 +53,8 @@ These parameters apply to the `keyring` block in the Nomad configuration file: decryption. - `resource` `(string: "vault.azure.net")`: The AZ KeyVault resource's DNS - Suffix to connect to. Alternately specify via the `AZURE_AD_RESOURCE` - environment variable. Needs to be changed to connect to Azure's Managed HSM + Suffix to connect to. Alternately specify via the `AZURE_AD_RESOURCE` + environment variable. Needs to be changed to connect to Azure's Managed HSM KeyVault instance type. ## Authentication @@ -67,13 +70,20 @@ Azure authentication values: - `AZURE_ENVIRONMENT` - `AZURE_AD_RESOURCE` -~> **Note:** If Nomad is hosted on Azure, Vault can use Managed Service Identities (MSI) to access Azure instead of an environment and shared client id and secret. MSI must be [enabled][msi_enabled] on the VMs hosting Nomad. We recommend this configuration since MSI prevents your Azure credentials from being stored as clear text. +~> **Note:** If Nomad is hosted on Azure, Vault can use Managed Service +Identities (MSI) to access Azure instead of an environment and shared client id +and secret. MSI must be [enabled][msi_enabled] on the VMs hosting Nomad. We +recommend this configuration since MSI prevents your Azure credentials from +being stored as clear text. --> **Note:** If you are using a Managed HSM KeyVault, you must specify `AZURE_AD_RESOURCE` or the `resource` configuration parameter; usually this should point to `managedhsm.azure.net` but could point to other suffixes depending on Azure environment. +-> **Note:** If you are using a Managed HSM KeyVault, you must specify +`AZURE_AD_RESOURCE` or the `resource` configuration parameter; usually this +should point to `managedhsm.azure.net` but could point to other suffixes +depending on Azure environment. ## Key rotation -This seal supports rotating keys defined in Azure Key Vault. Key metadata is +This keyring supports rotating keys defined in Azure Key Vault. Key metadata is stored with the encrypted data to ensure the correct key is used during decryption operations. Set up Azure Key Vault with [key rotation][] using Azure Automation Account so Vault recognizes newly rotated keys. diff --git a/website/content/docs/configuration/keyring/gcpckms.mdx b/website/content/docs/configuration/keyring/gcpckms.mdx index 8b9bc813fce..01fccd3cc2a 100644 --- a/website/content/docs/configuration/keyring/gcpckms.mdx +++ b/website/content/docs/configuration/keyring/gcpckms.mdx @@ -36,7 +36,8 @@ These parameters apply to the `keyring` stanza in the Nomad configuration file: running under Google App Engine, Google Compute Engine, or Google Kubernetes Engine. -- `project` `(string: )`: The GCP project ID to use. Alternately specify via the `GOOGLE_PROJECT` environment variable. +- `project` `(string: )`: The GCP project ID to use. Alternately + specify via the `GOOGLE_PROJECT` environment variable. - `region` `(string: )`: The GCP region/location where the key ring lives. Alternately specify via the `GOOGLE_REGION` environment variable. @@ -57,9 +58,9 @@ GCP authentication values: - `GOOGLE_PROJECT` - `GOOGLE_REGION` -Note: The client uses the official Google SDK and the specified -credentials, environment credentials, or [application default credentials][] in -that order, if you do not provide the aforementioned GCP-specific values. +Note: The client uses the official Google SDK and the specified credentials, +environment credentials, or [application default credentials][] in that order, +if you do not provide the aforementioned GCP-specific values. The service account needs the following minimum permissions on the crypto key: @@ -76,16 +77,16 @@ roles/cloudkms.cryptoKeyEncrypterDecrypter cloudkms.cryptoKeys.get ``` -Use `cloudkms.cryptoKeys.get` permission for retrieving metadata information -of keys from CloudKMS within this engine initialization process. +Use `cloudkms.cryptoKeys.get` permission for retrieving metadata information of +keys from CloudKMS within this engine initialization process. ## Key rotation This keyring supports rotating keys defined in Google Cloud KMS [doc][rotating_keys]. Both scheduled rotation and manual rotation is supported for CKMS since the key information. Old keys version must not be disabled or -deleted and are used to decrypt older data. Any new or updated data is -encrypted with the primary key version. +deleted and are used to decrypt older data. Any new or updated data is encrypted +with the primary key version. [application default credentials]: https://developers.google.com/identity/protocols/application-default-credentials diff --git a/website/content/docs/configuration/keyring/index.mdx b/website/content/docs/configuration/keyring/index.mdx index 3bb34547f13..d1efecd5c7b 100644 --- a/website/content/docs/configuration/keyring/index.mdx +++ b/website/content/docs/configuration/keyring/index.mdx @@ -14,9 +14,10 @@ for encrypting [variables][] and signing [workload identities][]. By default, Nomad encrypts the key material with a unique key encryption key (KEK) that is not shared between servers, and writes the wrapped key material to disk as described in [Key Management][]. Nomad refers to this as `"aead"`. Using the -`keyring` configuration block, Nomad servers can instead use an external key management system (KMS) or -Vault transit encryption. The encrypted key is stored on disk but is now -protected against offline attacks because the KEK is not present in the file. +`keyring` configuration block, Nomad servers can instead use an external key +management system (KMS) or Vault transit encryption. The encrypted key is stored +on disk but is now protected against offline attacks because the KEK is not +present in the file. All `keyring` blocks require a label for the KMS type. Each external KMS has its own configuration options. The `keyring` block only applies to Nomad servers, @@ -55,9 +56,9 @@ All `keyring` blocks support the following parameters. ## Migrating Keyrings To migrate to a new keyring, add the new `keyring` block to the servers with -`active=true`, and restart the servers. The server starts using the new -keyring wrapper when the current key is rotated either periodically or via the -[`nomad operator root keyring rotate`][keyring_rotate_cmd] command. +`active=true`, and restart the servers. The server starts using the new keyring +wrapper when the current key is rotated either periodically or via the [`nomad +operator root keyring rotate`][keyring_rotate_cmd] command. Adding or removing a keyring requires restarting the Nomad server. You should not remove a keyring until all keys it wraps have been garbage collected. You @@ -75,8 +76,8 @@ Keyring high availability provides the means to configure multiple active `keyring` blocks, in order to have resilience against an outage of an external KMS. When there are multiple `keyring` blocks with `active = true`, Nomad Enterprise encrypts each key it creates in all the active KMS providers. On -startup, Nomad tries each KMS provider in order until it finds a provider -that can decrypt each key. +startup, Nomad tries each KMS provider in order until it finds a provider that +can decrypt each key. In this example high availability configuration, both `keyring` blocks use the `"awskms"` provider, but each block uses a different KMS key in a different AWS diff --git a/website/content/docs/configuration/keyring/transit.mdx b/website/content/docs/configuration/keyring/transit.mdx index bbbe3f7ca88..904ab8868e2 100644 --- a/website/content/docs/configuration/keyring/transit.mdx +++ b/website/content/docs/configuration/keyring/transit.mdx @@ -45,7 +45,7 @@ These parameters apply to the `keyring` stanza in the Nomad configuration file: decryption. - `key_id_prefix` `(string: "")`: An optional string to add to the key id of - values wrapped by this transit keyring. This can help disambiguate between two + values wrapped by this transit keyring. This can help disambiguate between two transit keyring. - `mount_path` `(string: )`: The mount path to the transit secret @@ -56,17 +56,20 @@ These parameters apply to the `keyring` stanza in the Nomad configuration file: outside of Vault, such as Vault Agent. Set the following parameters in the `keyring` block. If not set here, Nomad uses -the values set in the server's [`vault`][vault_config] block. You must set required fields either here or the `vault` block. +the values set in the server's [`vault`][vault_config] block. You must set +required fields either here or the `vault` block. -- `address` `(string: )`: The full address to the Vault cluster. Alternately specify via the `VAULT_ADDR` environment variable. +- `address` `(string: )`: The full address to the Vault cluster. + Alternately specify via the `VAULT_ADDR` environment variable. -- `token` `(string: )`: The Vault token to use. Alternately specify via the `VAULT_TOKEN` environment variable. +- `token` `(string: )`: The Vault token to use. Alternately specify + via the `VAULT_TOKEN` environment variable. - `namespace` `(string: "")`: The namespace path to the transit secret engine. Alternately specify via the `VAULT_NAMESPACE` environment variable. -- `tls_ca_cert` `(string: "")`: Specifies the path to the CA certificate file used - for communication with the Vault server. Alternately specify via the +- `tls_ca_cert` `(string: "")`: Specifies the path to the CA certificate file + used for communication with the Vault server. Alternately specify via the `VAULT_CACERT` environment variable. - `tls_client_cert` `(string: "")`: Specifies the path to the client certificate @@ -74,11 +77,11 @@ the values set in the server's [`vault`][vault_config] block. You must set requi `VAULT_CLIENT_CERT` environment variable. - `tls_client_key` `(string: "")`: Specifies the path to the private key for - communication with the Vault server. Alternately specify via the + communication with the Vault server. Alternately specify via the `VAULT_CLIENT_KEY` environment variable. - `tls_server_name` `(string: "")`: Name to use as the SNI host when connecting - to the Vault server via TLS. Alternately specify via the + to the Vault server via TLS. Alternately specify via the `VAULT_TLS_SERVER_NAME` environment variable. - `tls_skip_verify` `(bool: "false")`: Disable verification of TLS certificates. @@ -95,8 +98,8 @@ or as configuration parameters. as part of the keyring's parameters, we strongly recommended that you set these values via environment variables. -The Vault authentication token needs the following permissions on the -transit key: +The Vault authentication token needs the following permissions on the transit +key: ```hcl path "/encrypt/" { @@ -109,14 +112,16 @@ path "/decrypt/" { ``` Other considerations for the token used: -* It should probably be an [orphan token][], otherwise when the parent token expires or gets revoked the keyring breaks. -* Consider making it a [periodic token][] and not setting an explicit max TTL, otherwise at some point it ceases to be renewable. +* It should probably be an [orphan token][], otherwise when the parent token + expires or gets revoked the keyring breaks. +* Consider making it a [periodic token][] and not setting an explicit max TTL, + otherwise at some point it ceases to be renewable. ## Key rotation -This keyring supports key rotation using the Transit Secret Engine's key rotation -endpoints. Refer to [Vault docs][rotate_doc]. Old keys must not be disabled or deleted and -are used to decrypt older data. +This keyring supports key rotation using the Transit Secret Engine's key +rotation endpoints. Refer to [Vault docs][rotate_doc]. Old keys must not be +disabled or deleted and are used to decrypt older data. [orphan token]: /vault/docs/concepts/tokens#token-hierarchies-and-orphan-tokens [periodic token]: /vault/docs/concepts/tokens#periodic-tokens From e8ed28916e15b111f5beb5f1dab55f2c9f9081da Mon Sep 17 00:00:00 2001 From: Tim Gross Date: Fri, 19 Jul 2024 14:42:44 -0400 Subject: [PATCH 4/4] address comments on code review --- website/content/docs/configuration/keyring/awskms.mdx | 4 +++- .../docs/configuration/keyring/azurekeyvault.mdx | 2 +- website/content/docs/configuration/keyring/gcpckms.mdx | 3 +-- website/content/docs/configuration/keyring/index.mdx | 10 +++++----- website/content/docs/configuration/keyring/transit.mdx | 4 ++-- 5 files changed, 12 insertions(+), 11 deletions(-) diff --git a/website/content/docs/configuration/keyring/awskms.mdx b/website/content/docs/configuration/keyring/awskms.mdx index 119736668df..621a41c5f03 100644 --- a/website/content/docs/configuration/keyring/awskms.mdx +++ b/website/content/docs/configuration/keyring/awskms.mdx @@ -74,7 +74,8 @@ AWS authentication values: Note: The client uses the official AWS SDK and the specified credentials, environment credentials, shared file credentials, or IAM role/ECS task credentials in that order, if you do not provide the aforementioned AWS-specific -values. +values. Refer to the [AWS SDK and Tools standard credentials][aws-std-creds] +documentation. Nomad needs the following permissions on the KMS key: @@ -96,3 +97,4 @@ configuration or set to current under a key alias. [VPC Endpoint]: https://docs.aws.amazon.com/kms/latest/developerguide/kms-vpc-endpoint.html [rotate_docs]: https://docs.aws.amazon.com/kms/latest/developerguide/rotate-keys.html +[aws-std-creds]: https://docs.aws.amazon.com/sdkref/latest/guide/standardized-credentials.html diff --git a/website/content/docs/configuration/keyring/azurekeyvault.mdx b/website/content/docs/configuration/keyring/azurekeyvault.mdx index 4c32beac58c..7addbf2b1de 100644 --- a/website/content/docs/configuration/keyring/azurekeyvault.mdx +++ b/website/content/docs/configuration/keyring/azurekeyvault.mdx @@ -70,7 +70,7 @@ Azure authentication values: - `AZURE_ENVIRONMENT` - `AZURE_AD_RESOURCE` -~> **Note:** If Nomad is hosted on Azure, Vault can use Managed Service +~> **Note:** If Nomad is hosted on Azure, Nomad can use Managed Service Identities (MSI) to access Azure instead of an environment and shared client id and secret. MSI must be [enabled][msi_enabled] on the VMs hosting Nomad. We recommend this configuration since MSI prevents your Azure credentials from diff --git a/website/content/docs/configuration/keyring/gcpckms.mdx b/website/content/docs/configuration/keyring/gcpckms.mdx index 01fccd3cc2a..87ebf0734b1 100644 --- a/website/content/docs/configuration/keyring/gcpckms.mdx +++ b/website/content/docs/configuration/keyring/gcpckms.mdx @@ -33,8 +33,7 @@ These parameters apply to the `keyring` stanza in the Nomad configuration file: - `credentials` `(string: )`: The path to the credentials JSON file to use. Alternately specify via the `GOOGLE_CREDENTIALS` or `GOOGLE_APPLICATION_CREDENTIALS` environment variable or set automatically if - running under Google App Engine, Google Compute Engine, or Google Kubernetes - Engine. + running under Google Compute Engine. - `project` `(string: )`: The GCP project ID to use. Alternately specify via the `GOOGLE_PROJECT` environment variable. diff --git a/website/content/docs/configuration/keyring/index.mdx b/website/content/docs/configuration/keyring/index.mdx index d1efecd5c7b..aefe410f27a 100644 --- a/website/content/docs/configuration/keyring/index.mdx +++ b/website/content/docs/configuration/keyring/index.mdx @@ -13,11 +13,11 @@ The `keyring` block configures how the Nomad server protects the keyring used for encrypting [variables][] and signing [workload identities][]. By default, Nomad encrypts the key material with a unique key encryption key (KEK) that is not shared between servers, and writes the wrapped key material to disk as -described in [Key Management][]. Nomad refers to this as `"aead"`. Using the -`keyring` configuration block, Nomad servers can instead use an external key -management system (KMS) or Vault transit encryption. The encrypted key is stored -on disk but is now protected against offline attacks because the KEK is not -present in the file. +described in [Key Management][]. Nomad refers to this as `"aead"` (authenticated +encryption with associated data). Using the `keyring` configuration block, Nomad +servers can instead use an external key management system (KMS) or Vault transit +encryption. The encrypted key is stored on disk but is now protected against +offline attacks because the KEK is not present in the file. All `keyring` blocks require a label for the KMS type. Each external KMS has its own configuration options. The `keyring` block only applies to Nomad servers, diff --git a/website/content/docs/configuration/keyring/transit.mdx b/website/content/docs/configuration/keyring/transit.mdx index 904ab8868e2..05bb1a0a9ac 100644 --- a/website/content/docs/configuration/keyring/transit.mdx +++ b/website/content/docs/configuration/keyring/transit.mdx @@ -23,12 +23,12 @@ keyring "transit" { token = "s.Qf1s5zigZ4OX6akYjQXJC1jY" disable_renewal = "false" - // Key configuration + # Key configuration key_name = "transit_key_name" mount_path = "transit/" namespace = "ns1/" - // TLS Configuration + # TLS Configuration tls_ca_cert = "/etc/vault/ca_cert.pem" tls_client_cert = "/etc/vault/client_cert.pem" tls_client_key = "/etc/vault/ca_cert.pem"