From 106791f6d2a4629b212ebe1c99708aa2d9236837 Mon Sep 17 00:00:00 2001 From: Mark Wolfe Date: Thu, 12 Sep 2024 11:34:13 +1000 Subject: [PATCH 1/6] Add a section on using AWS KMS keys with signed pipelines --- pages/agent/v3/signed_pipelines.md | 77 ++++++++++++++++++++++++++++-- 1 file changed, 74 insertions(+), 3 deletions(-) diff --git a/pages/agent/v3/signed_pipelines.md b/pages/agent/v3/signed_pipelines.md index 013155a01f..59f9b61fb5 100644 --- a/pages/agent/v3/signed_pipelines.md +++ b/pages/agent/v3/signed_pipelines.md @@ -42,9 +42,16 @@ The following fields are included in the signature for each step: You'll need to configure your agents and update pipeline definitions to enable signed pipelines. -### Step 1: Generate a key pair +Behind the scenes, signed pipelines use [JSON Web Signing (JWS)](https://datatracker.ietf.org/doc/html/rfc7797) to generate signatures. There are two options for creation of keys used with JWS, these are: + +* Self managed key pairs +* AWS KMS managed keys -Behind the scenes, signed pipelines use [JSON Web Signing (JWS)](https://datatracker.ietf.org/doc/html/rfc7797) to generate signatures. You'll need to generate a [JSON Web Key Set (JWKS)](https://datatracker.ietf.org/doc/html/rfc7517) to sign and verify your pipelines with, then configure your agents to use those keys. +## Self Managed Key Creation + +You'll need to generate a [JSON Web Key Set (JWKS)](https://datatracker.ietf.org/doc/html/rfc7517) to sign and verify your pipelines with, then configure your agents to use those keys. + +### Step 1: Generate a key pair Luckily, the agent has you covered! A JWKS generation tool is built into the agent, which you can use to generate a key pair. To use it, you'll need to [install the agent on your machine](/docs/agent/v3/installation), and then run: @@ -143,7 +150,7 @@ Replacing the following: This will download the pipeline definition using the Buildkite GraphQL API, sign all steps, and upload the signed pipeline definition back to Buildkite. -## Rotating signing keys +### Rotating signing keys Regularly rotating signing and verification keys is good security practice, as it reduces the impact of a compromised key. Because signed pipelines use JWKS as their key format, rotating keys is easy. @@ -154,3 +161,67 @@ To rotate your keys: 1. Update the `signing-key-id` on your signing agents to use the new key ID. The verifying agents will automatically use the public key with the matching key ID, if it's present. + +## AWS KMS Managed Key Setup + +AWS Key Management Service (AWS KMS) is a web service that securely protects cryptographic keys, when using this service with signed pipelines the agent never has access to the private key used to sign pipelines, with calls going via the KMS API. + +### Step 1: Create a KMS Key + +AWS KMS has a myriad of options when creating keys, for pipeline signing we require that you use some specific settings. + +1. The key type must be Asymmetric and have a usage type of `SIGN_VERIFY`. +2. The key spec must be `ECC_NIST_P256`. + +If your using the AWS CLI the key can be created as follows: + +```bash +aws kms create-key --key-spec ECC_NIST_P256 --key-usage SIGN_VERIFY +``` + +Once created you can retrieve the key identifier, this will be a UUID, for example `1234abcd-12ab-34cd-56ef-1234567890ab`. + +Optionally you can create a key alias, or friendly name for the key as follows: + +```bash +aws kms create-alias \ + --alias-name alias/example-alias \ + --target-key-id 1234abcd-12ab-34cd-56ef-1234567890ab +``` + +### Step 2: Configure the agents + +Next, you need to configure your agents to use the KMS key you created. On agents that upload pipelines, add the following to the agent's config file: + +```ini +signing-aws-kms-key= +``` + +This ensures that whenever those agents upload steps to Buildkite, they'll generate signatures using the private key you generated earlier. It also ensures that those agents verify the signatures of any steps they run, using the public key. + +```ini +verification-failure-behavior= +``` + +This setting determines the Buildkite agent's response when it receives a job without a proper signature, and also specifies how strictly the agent should enforce signature verification for incoming jobs. The agent will warn about missing or invalid signatures, but will still proceed to execute the job. If not explicitly specified, the default behavior is `block`, which prevents any job without a valid signature from running, ensuring a secure pipeline environment by default. + +### Step 3: Sign all steps + +To sign steps configured in the Buildkite dashboard, you need to add static signatures to the YAML. To do this, run: + +```sh +buildkite-agent tool sign \ + --graphql-token \ + --signing-aws-kms-key \ + --organization-slug \ + --pipeline-slug \ + --update +``` + +Replacing the following: + +- `` with a Buildkite GraphQL token that has the `write_pipelines` scope. +- `` with the path to the private key set you generated earlier. +- `` with the AWS KMS key ID or alias created earlier. +- `` with the slug of the organization the pipeline is in. +- `` with the slug of the pipeline you want to sign. From 8ee56ea9ee029db1d390aef12c2cee169725e314 Mon Sep 17 00:00:00 2001 From: Mark Wolfe Date: Thu, 12 Sep 2024 12:17:59 +1000 Subject: [PATCH 2/6] Add a section on IAM actions required to perform different roles --- pages/agent/v3/signed_pipelines.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/pages/agent/v3/signed_pipelines.md b/pages/agent/v3/signed_pipelines.md index 59f9b61fb5..785f5ed454 100644 --- a/pages/agent/v3/signed_pipelines.md +++ b/pages/agent/v3/signed_pipelines.md @@ -225,3 +225,18 @@ Replacing the following: - `` with the AWS KMS key ID or alias created earlier. - `` with the slug of the organization the pipeline is in. - `` with the slug of the pipeline you want to sign. + +### Step 4: Assign IAM Permissions to your Agents + +There are two common roles for agents when using signed pipelines, these being those that sign and upload pipelines, and those that verify steps. To follow least privilege best practice you should access to the KMS key using IAM to specific actions as seen below. + +For agents which will sign and verify pipelines the following IAM Actions are required. + +- kms:Sign +- kms:Verify +- kms:GetPublicKey + +For agents which only verify pipelines the following IAM Actions are required. + +- kms:Verify +- kms:GetPublicKey From ee2b1cac9543649624115d798f933325263c11a4 Mon Sep 17 00:00:00 2001 From: Mark Wolfe Date: Thu, 12 Sep 2024 13:13:26 +1000 Subject: [PATCH 3/6] Fixes for linting errors/warnings --- pages/agent/v3/signed_pipelines.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/pages/agent/v3/signed_pipelines.md b/pages/agent/v3/signed_pipelines.md index 785f5ed454..6e32bbb9fb 100644 --- a/pages/agent/v3/signed_pipelines.md +++ b/pages/agent/v3/signed_pipelines.md @@ -162,11 +162,11 @@ To rotate your keys: The verifying agents will automatically use the public key with the matching key ID, if it's present. -## AWS KMS Managed Key Setup +## AWS KMS managed key setup -AWS Key Management Service (AWS KMS) is a web service that securely protects cryptographic keys, when using this service with signed pipelines the agent never has access to the private key used to sign pipelines, with calls going via the KMS API. +AWS Key Management Service (AWS KMS) is a web service that securely protects cryptographic keys, when using this service with signed pipelines the agent never has access to the private key used to sign pipelines, with calls going with the KMS API. -### Step 1: Create a KMS Key +### Step 1: Create a KMS key AWS KMS has a myriad of options when creating keys, for pipeline signing we require that you use some specific settings. @@ -226,7 +226,7 @@ Replacing the following: - `` with the slug of the organization the pipeline is in. - `` with the slug of the pipeline you want to sign. -### Step 4: Assign IAM Permissions to your Agents +### Step 4: Assign IAM permissions to your agents There are two common roles for agents when using signed pipelines, these being those that sign and upload pipelines, and those that verify steps. To follow least privilege best practice you should access to the KMS key using IAM to specific actions as seen below. From 99ab986d49742589399b79e9dc65b7c7574e7821 Mon Sep 17 00:00:00 2001 From: Giles Gaskell Date: Fri, 13 Sep 2024 09:57:44 +1000 Subject: [PATCH 4/6] Fix Markdown linting issues. --- pages/agent/v3/signed_pipelines.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/pages/agent/v3/signed_pipelines.md b/pages/agent/v3/signed_pipelines.md index 6e32bbb9fb..d00f2d3469 100644 --- a/pages/agent/v3/signed_pipelines.md +++ b/pages/agent/v3/signed_pipelines.md @@ -44,8 +44,8 @@ You'll need to configure your agents and update pipeline definitions to enable s Behind the scenes, signed pipelines use [JSON Web Signing (JWS)](https://datatracker.ietf.org/doc/html/rfc7797) to generate signatures. There are two options for creation of keys used with JWS, these are: -* Self managed key pairs -* AWS KMS managed keys +- Self managed key pairs +- AWS KMS managed keys ## Self Managed Key Creation From 6f230a942a66f87a72aaa38f5bfc333da97a121a Mon Sep 17 00:00:00 2001 From: Giles Gaskell Date: Fri, 13 Sep 2024 10:00:28 +1000 Subject: [PATCH 5/6] Fix text linting issues. --- pages/agent/v3/signed_pipelines.md | 2 +- vale/styles/Buildkite/h1-h6_sentence_case.yml | 1 + 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/pages/agent/v3/signed_pipelines.md b/pages/agent/v3/signed_pipelines.md index d00f2d3469..0a8e31e0d6 100644 --- a/pages/agent/v3/signed_pipelines.md +++ b/pages/agent/v3/signed_pipelines.md @@ -47,7 +47,7 @@ Behind the scenes, signed pipelines use [JSON Web Signing (JWS)](https://datatra - Self managed key pairs - AWS KMS managed keys -## Self Managed Key Creation +## Self-managed key creation You'll need to generate a [JSON Web Key Set (JWKS)](https://datatracker.ietf.org/doc/html/rfc7517) to sign and verify your pipelines with, then configure your agents to use those keys. diff --git a/vale/styles/Buildkite/h1-h6_sentence_case.yml b/vale/styles/Buildkite/h1-h6_sentence_case.yml index 7b5397abe1..97eff668e4 100644 --- a/vale/styles/Buildkite/h1-h6_sentence_case.yml +++ b/vale/styles/Buildkite/h1-h6_sentence_case.yml @@ -112,6 +112,7 @@ exceptions: - Jenkins - JSON - JUnit + - KMS - Kubernetes - Linux - M1 From 7625927fc2717f1bf530fa0afe6a17f2dcc2a8f3 Mon Sep 17 00:00:00 2001 From: Giles Gaskell Date: Fri, 13 Sep 2024 10:03:04 +1000 Subject: [PATCH 6/6] Fix broken link (muffet) issue. --- pages/agent/v3/signed_pipelines.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/agent/v3/signed_pipelines.md b/pages/agent/v3/signed_pipelines.md index 0a8e31e0d6..920a966097 100644 --- a/pages/agent/v3/signed_pipelines.md +++ b/pages/agent/v3/signed_pipelines.md @@ -156,7 +156,7 @@ Regularly rotating signing and verification keys is good security practice, as i To rotate your keys: -1. [Generate a new key pair](#enabling-signed-pipelines-on-your-agents-step-1-generate-a-key-pair). +1. [Generate a new key pair](#self-managed-key-creation-step-1-generate-a-key-pair). 1. Add the new keys to your existing key sets. Be careful not to mix public and private keys. 1. Update the `signing-key-id` on your signing agents to use the new key ID.