From 8fb0c497fcd80aca621af3aaec66a6e60cf8d2db Mon Sep 17 00:00:00 2001 From: James Telfer <792299+jamestelfer@users.noreply.github.com> Date: Wed, 20 Nov 2024 17:35:45 +1100 Subject: [PATCH] docs: remove migrated documentation These pages are now available on the main documentation site. --- docs/kms.md | 84 ---------------------------------- docs/releases.md | 72 ----------------------------- docs/verifying-releases.md | 92 -------------------------------------- 3 files changed, 248 deletions(-) delete mode 100644 docs/kms.md delete mode 100644 docs/releases.md delete mode 100644 docs/verifying-releases.md diff --git a/docs/kms.md b/docs/kms.md deleted file mode 100644 index d536e04..0000000 --- a/docs/kms.md +++ /dev/null @@ -1,84 +0,0 @@ -# Using KMS to sign GitHub JWTs - -It is more secure (though more complicated) to provide Chinmina with an AWS KMS key to sign JWTs for GitHub requests. - -## Uploading the KMS key - -1. [Generate the private key][github-key-generate] for the GitHub application. - -2. Check the private key and convert it ready for upload - - the key spec for your GitHub key _should_ be RSA 2048. To verify that this is - the case, run `openssl rsa -text -noout -in yourkey.pem` and examine the - output. - - convert the GitHub key from PEM to DER format for AWS: - - ```shell - openssl rsa -inform PEM -outform DER -in ./private-key.pem -out private-key.cer - ``` - -3. Follow the [AWS instructions][aws-import-key-material] for importing the - application private key into GitHub. This includes creating an RSA 2048 key - of type "EXTERNAL", encrypting the key material according to the instructions - and uploading it. - -4. Create an alias for the KMS key to allow for easy [manual key - rotation][aws-manual-key-rotation]. - -> [!IMPORTANT] -> A key alias is essential to allow for key rotation. Unless you're stopped -> by environmental policy, use the alias. The key will be able to be rotated -> without any service downtime. - -5. Ensure that the key policy has a statement allowing Chinmina to access the key. The specified role should be the role that the Chinmina process has access to at runtime. - - ```json - { - "Sid": "Allow Chinmina to sign using the key", - "Effect": "Allow", - "Principal": { - "AWS": [ - "arn:aws:iam::226140413739:role/full-task-role-name" - ] - }, - "Action": [ - "kms:Sign" - ], - "Resource": "*" - } - ``` - -> [!TIP] -> Chinmina does not assume a role to access the key. It assumes valid -> credentials are present for the AWS SDK to use. - -## Configuring the Chinmina service - -1. Set the environment variable `GITHUB_APP_PRIVATE_KEY_ARN` to the ARN of the **alias** that has just been created. - -2. Update IAM for your key - 1. The KMS key resource policy needs to allow the service to use the key - _for signing only_. - 2. The IAM policy for the Chinmina process (i.e. the AWS role available to - Chinmina when it runs) needs to be able to use the _alias_ created for - the private key. This is done with a condition in the policy element: - - ```json - { - "Action": "kms:Sign", - "Effect": "Allow", - "Resource": "*", - "Condition": { - "StringEquals": { - "kms:RequestAlias": "alias/chinmina-signing", - }, - }, - } - ``` - - Using the `kms:RequestAlias` condition instead of the fully qualified - key ARN in the `resource` attribute allows for transparent key rotation - without service interruption. - -[github-key-generate]: https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/managing-private-keys-for-github-apps#generating-private-keys -[aws-import-key-material]: https://docs.aws.amazon.com/kms/latest/developerguide/importing-keys.html -[aws-manual-key-rotation]: https://docs.aws.amazon.com/kms/latest/developerguide/rotate-keys.html#rotate-keys-manually diff --git a/docs/releases.md b/docs/releases.md deleted file mode 100644 index 023606a..0000000 --- a/docs/releases.md +++ /dev/null @@ -1,72 +0,0 @@ -# Release process - -In short: - -1. Releases are triggered by creating a release tag from `main`. This is currently manual. -2. Release tags conform to semantic versioning -3. Commits use conventional commit messages to aid in the changelog creation process -4. A GoReleaser pipeline is used to create the artifacts -5. All artifacts (binaries and images) are signed by the build process using `cosign` - -## When is a release ready? - -Releases are created on an as-needed basis. We prefer multiple, smaller releases over releases that have a greater number of changes. - -A release is ready when: - -- there are committed changes on `main`, and -- there is confidence in its stability. - -Stability is a pre-requisite for merging, so there should not be significant questions about the appropriateness of a `main` release. - -## Triggering a release - -Releases are triggered via the creation of a semantic-versioned tag, in the format `vX.Y.Z`. Creation of a tag in this format triggers the automated release process. - -Only repository administrators may create a tag in this format. - -## Release signing - -The [Sigstore][sigstore] ecosystem is leveraged for signing executable release outputs. ([Docs][sigstore-docs].) - -- [`cosign`][cosign] is used as the signing CLI tool -- The [`fulcio`][fulcio] public-good instance is used for ephemeral signing certificates -- The [`rekor`][rekor] [public-good instance][rekor-search] is used for Certificate Transparency record publishing. - -The signing process allows some useful attributes of the binaries to be verified: - -- the provider of the identity for the build process (i.e. GitHub Actions) -- the build process that was used to generate them (both scripts and compute) -- the Git reference of the code that was used to build the binary - -Releases are signed with `cosign`, with transparency records published to the [public-good Rekor instance]. - -[sigstore]: https://www.sigstore.dev/ -[sigstore-docs]: https://docs.sigstore.dev/ -[cosign]: https://github.com/sigstore/cosign?tab=readme-ov-file -[fulcio]: https://github.com/sigstore/fulcio?tab=readme-ov-file -[rekor]: https://github.com/sigstore/rekor?tab=readme-ov-file -[rekor-search]: https://search.sigstore.dev/ - -## Testing the release process - -It is possible to run GoReleaser locally to test some of the release proceses. -(`goreleaser` must be available.) - -```shell -# from the root of the local working copy -goreleaser release --clean --verbose --skip "announce,validate" -``` - -This will run the binary and image builds, and publish a temporary image to -[`ttl.sh`](https://ttl.sh/). Temporary images can be used in local testing with -`docker compose`. - -Some processes are skipped when doing this: - -- binary signing -- image signing -- changelog generation -- GitHub release creation - -Thus release testing verifies a proportion of the GoReleaser configuration, and allows the image/binary builds to be integration tested. diff --git a/docs/verifying-releases.md b/docs/verifying-releases.md deleted file mode 100644 index 93960a7..0000000 --- a/docs/verifying-releases.md +++ /dev/null @@ -1,92 +0,0 @@ -# Verifying releases with `cosign` - -Releases [are signed](./releases.md) with `cosign` as part of the release -process. The build produces additional attestation bundles during this process, -which can be used to verify both binaries and Docker images. - -For binaries, bundles are present in the `tar.gz` archive created by the -release. For images, bundles are stored in the OCI registry alongside the image -itself. - -## Obtaining `cosign` - -Download from the [`sigstore/cosign` project on GitHub][cosign-download], and -[verify the release][cosign-verify] as you prefer. - -[cosign-download]: https://github.com/sigstore/cosign?tab=readme-ov-file#installation -[cosign-verify]: https://docs.sigstore.dev/cosign/system_config/installation/#verifying-cosign-releases - -## Release identity - -The certificates issued by the release are issued for the GitHub Actions OIDC -provider, and the identity is the executed workflow, referenced by the Git tag -being built. - -| Field | Format | -|-|-| -| Issuer | `https://token.actions.githubusercontent.com` | -| Identity | `https://github.com/jamestelfer/chinmina-bridge/.github/workflows/release.yaml@refs/tags/` | - -> [!IMPORTANT] -> **Git tags are not static:** they can be updated to point to a different -> commit SHA. Examine the recorded claims for the exact commit. -> -> There are claims recorded for the exact commit of both the workflow that -> produced the artifact and the commit that the artifact source was built from. - -## Verifying an image release - -Images are published to Docker Hub in the `chinmina` repository. The images are -named `chinmina-bridge` and are labelled with their release tag (`vX.Y.Z`). - -An image can be verified with the following `cosign` command: - -```shell -TAG=vX.Y.Z \ -cosign verify "chinmina/chinmina-bridge:$TAG" \ - --certificate-oidc-issuer 'https://token.actions.githubusercontent.com' \ - --certificate-identity "https://github.com/jamestelfer/chinmina-bridge/.github/workflows/release.yaml@refs/tags/$TAG" \ - --output text - -# more details are available if you use JSON output: -TAG=vX.Y.Z \ -cosign verify "chinmina/chinmina-bridge:$TAG" \ - --certificate-oidc-issuer 'https://token.actions.githubusercontent.com' \ - --certificate-identity "https://github.com/jamestelfer/chinmina-bridge/.github/workflows/release.yaml@refs/tags/$TAG" \ - --output json | jq -``` - -The path `.[].optional.Bundle.Payload.logIndex` is the index entry in the public -transparency log, recording the details of the signing event. The details of the -event can be found at: https://search.sigstore.dev/. - -## Verifying the binary releases - -Download and extract the `tar.gz` of the binary you're interested in. The -artifacts present include both the binary itself (named `chinmina-bridge`) and -the signing bundle (`chinmina-bridge.cosign.bundle`). - -```shell -# declare the release details for download -TAG=vX.Y.Z -ARCH=arm64 - -# download the binary -curl -L -o chinmina-bridge_linux_${ARCH}.tar.gz \ - https://github.com/jamestelfer/chinmina-bridge/releases/download/${TAG}/chinmina-bridge_linux_${ARCH}.tar.gz - -# extract to the current directory -tar xvf chinmina-bridge_linux_${ARCH}.tar.gz - -# verify -cosign verify-blob \ - chinmina-bridge \ - --bundle chinmina-bridge.cosign.bundle \ - --certificate-oidc-issuer 'https://token.actions.githubusercontent.com' \ - --certificate-identity "https://github.com/jamestelfer/chinmina-bridge/.github/workflows/release.yaml@refs/tags/$TAG" - -# peek the details -jq -r '.rekorBundle.Payload.logIndex | "https://search.sigstore.dev/?logIndex=\(.)"' < chinmina-bridge.cosign.bundle - -# open the URL that is shown -```