kms-import imports a GitHub App private key into AWS KMS as non-extractable
key material. Applications then sign GitHub App JWTs with kms:Sign, and the
private key exists nowhere outside KMS.
It ships as a CLI and a Go library. It imports into an existing KMS key and does not create keys.
A GitHub App private key grants every permission of the app to anyone who holds it. Storing it in KMS rather than as a plaintext secret provides:
- Non-extractability. Imported material stays inside the KMS HSM boundary
and no API reads it back. The application receives only signatures from
kms:Sign. - Policy-based access. Every use is authorised by the key policy and IAM, and access is revocable without touching the application.
- Audit. CloudTrail records every
GetParametersForImport,ImportKeyMaterial, andSigncall against the key. - Alias-based rotation. An application that signs through an alias picks up a replacement key with no restart or configuration change.
- Protecting the GitHub private key describes the full key
lifecycle that
kms-importis part of: creating and restricting the key, configuring the signing service, and rotation. - Quick start imports a key from the command line.
KMS accepts key material only when it is encrypted ("wrapped") under a one-time public key issued for the target key. The ciphertext must match the wrapping algorithm's byte format exactly, and KMS rejects any mistake with a generic error.
The diagram shows each step of one import. Everything on the local side happens in memory.
sequenceDiagram
autonumber
box rgba(29,78,216,0.10) Local machine
participant PEM as app.pem
participant Tool as kms-import (in memory)
end
box rgba(126,34,206,0.10) AWS
participant KMS as AWS KMS (HSM)
end
PEM->>Tool: Read GitHub App private key (PKCS#35;1 or PKCS#35;8 PEM)
Tool->>Tool: Convert to PKCS#35;8 DER
Tool->>KMS: GetParametersForImport(key, RSA_AES_KEY_WRAP_SHA_256, RSA_4096)
KMS-->>Tool: Wrapping public key + import token (valid 24 h)
Tool->>Tool: Generate ephemeral AES-256 key
Tool->>Tool: AES key-wrap (RFC 5649) the DER key material
Tool->>Tool: RSA-OAEP-SHA-256 encrypt the AES key under the wrapping key
Tool->>Tool: Concatenate: encrypted AES key ‖ wrapped key material
Tool->>Tool: Wipe ephemeral AES key
Tool->>KMS: ImportKeyMaterial(key, import token, ciphertext, expiry model)
KMS->>KMS: Unwrap inside the HSM, bind material to key
KMS-->>Tool: Success
The wrapping algorithm is fixed at RSA_AES_KEY_WRAP_SHA_256 with an RSA_4096
wrapping key, the AWS recommendation for asymmetric key material. Only
RSA_2048 key material is supported, which is the spec GitHub issues App keys
in.
The manual import procedure performs the same steps with the AWS
CLI and openssl, at these costs:
- Plaintext files. The DER private key and the AES wrapping key are written to disk, creating more copies of the secret to destroy.
- Opaque failures. A wrong digest, padding variant, concatenation order, or import token all produce the same generic KMS error.
- Toolchain dependence. AES key wrap with padding needs OpenSSL 3.x. The LibreSSL shipped with macOS lacks it.
This guide imports a GitHub App private key into a new KMS key with default settings. For production, follow Protecting the GitHub private key on docs.chinmina.dev. It adds the key alias that rotation depends on, a key policy that restricts signing to one service, and the order to apply them in.
Before you start, you need:
- The GitHub App private key as a PEM file, referred to below as
<PEM_FILE>. - AWS credentials allowed to call
kms:CreateKey, plus the import permissions.
-
Install
kms-import. Installation lists the other channels.mise use -g github:chinmina/kms-import
-
Create a KMS key, and save the printed ARN as
<KEY_ARN>.aws kms create-key --origin EXTERNAL --key-spec RSA_2048 --key-usage SIGN_VERIFY \ --query KeyMetadata.Arn --output text
EXTERNALorigin allows import,RSA_2048matches GitHub App keys, andSIGN_VERIFYlets the key sign JWTs. The key starts in thePendingImportstate. -
Import the private key.
kms-import --key-file <PEM_FILE> --key-arn <KEY_ARN>
A successful import prints:
✅ Key material imported successfully - Key ID: 1234abcd-12ab-34cd-56ef-1234567890ab - State: Enabled The key is ready to use for signing. -
Confirm the key state.
aws kms describe-key --key-id <KEY_ARN> --query KeyMetadata.KeyState --output text
The output is
Enabled. -
Destroy every local copy of the PEM file. KMS cannot export the material, so a local copy is the only remaining way to leak the key.
Caution
Do not import key material with infrastructure-as-code tooling. Terraform's
aws_kms_external_key stores "all arguments including the key material … in
the raw state as plain text" (provider docs), and CloudFormation
cannot import key material at all. Provision the key with IaC, leave
key_material_base64 unset, and import with kms-import.
Pre-built binaries for Linux, macOS, and Windows (amd64/arm64) are published to GitHub Releases. Every artifact carries a build-provenance attestation, described in Verifying releases.
mise (recommended)
mise installs directly from GitHub Releases via its
GitHub backend. It
verifies the artifact's checksum and, when the
github_attestations setting
is enabled (currently the default), its build-provenance attestation:
mise use -g github:chinmina/kms-importOr pin a version for a project in its mise.toml:
[tools]
"github:chinmina/kms-import" = "1.0.0"Install script
Each release includes a self-contained installer script (generated with binstaller) that detects your platform and verifies the download against the release checksums embedded in the script — no network fetch of the checksum file:
curl -fsSL https://github.com/chinmina/kms-import/releases/latest/download/install.sh | shIt installs to ~/.local/bin by default; pass -b for a different directory.
To pin a version, fetch the script from that release, so its embedded
checksums match:
curl -fsSL https://github.com/chinmina/kms-import/releases/download/v1.2.3/install.sh \
| sh -s -- -b /usr/local/bin v1.2.3The script has its own build-provenance attestation. A verified script holds the genuine checksums for its release and enforces them on the binary, so verifying the script covers the binary for that release (requires an authenticated GitHub CLI):
curl -fsSL -O https://github.com/chinmina/kms-import/releases/latest/download/install.sh
gh attestation verify install.sh --repo chinmina/kms-import \
--signer-workflow chinmina/.github/.github/workflows/goreleaser-release.yml
sh install.shHomebrew (macOS)
brew install chinmina/tap/kms-importNix
nix profile install github:chinmina/nixpkgs#kms-importManual download
Download the archive for your platform from the
releases page, verify its
provenance, and put the binary on your PATH:
OS=linux ARCH=amd64 # or darwin/windows, arm64
curl -fsSLO "https://github.com/chinmina/kms-import/releases/latest/download/kms-import_${OS}_${ARCH}.tar.gz"
gh attestation verify "kms-import_${OS}_${ARCH}.tar.gz" --repo chinmina/kms-import \
--signer-workflow chinmina/.github/.github/workflows/goreleaser-release.yml
tar -xzf "kms-import_${OS}_${ARCH}.tar.gz" kms-import
install -m 0755 kms-import ~/.local/bin/Windows archives are .zip. See Verifying releases for
what the attestation proves and for checksum-only verification.
go install
Build from source with Go 1.27+:
go install github.com/chinmina/kms-import/cmd/kms-import@latestSource builds are not stamped with a release version, so --version reports
dev.
--key-file and exactly one of --key-id or --key-arn are required. All
other flags are optional.
| Flag | Type | Default | Description |
|---|---|---|---|
--key-file |
string | — | Required. Path to the PEM-encoded private key file. Accepts BEGIN RSA PRIVATE KEY (PKCS#1) and BEGIN PRIVATE KEY (PKCS#8); any other header is an error. |
--key-id |
string | — | Target KMS key ID. Mutually exclusive with --key-arn. |
--key-arn |
string | — | Target KMS key ARN. Mutually exclusive with --key-id. |
--expires |
string | none (key material does not expire) | Expiry for the imported key material as an RFC 3339 timestamp (e.g. 2027-01-01T00:00:00Z). A malformed or already-passed value is rejected before any AWS call is made. |
--profile |
string | SDK default | AWS named profile to use. |
--region |
string | SDK default | AWS region to use. |
--json |
bool | false |
Emit the result as a single JSON object on stdout and suppress all other output. |
--help, -h |
bool | false |
Show help. |
--version, -v |
bool | false |
Print the version. |
Target selection. The KMS import APIs accept a key ID or key ARN only, so
there is no --alias flag.
Credentials. Credentials and region resolve through the standard AWS SDK
chain (environment variables, shared config and credentials files, and IMDS).
--profile and --region override the corresponding defaults.
Expiry and reimport. Imported material does not expire by default
(KEY_MATERIAL_DOES_NOT_EXPIRE). --expires sets KEY_MATERIAL_EXPIRES with
the given ValidTo, and exists for compliance requirements. To revoke a
compromised key, delete it in the GitHub App settings, which takes effect
immediately. The same invocation performs both the initial import and a
reimport after material expires or is deleted. AWS requires a reimport to use
the same key material as the original.
JSON output. With --json, stdout carries only the result object:
{"keyId":"1234abcd-12ab-34cd-56ef-1234567890ab","keyState":"Enabled"}The reported Enabled state follows from a successful import. kms-import
does not read it back from KMS; use aws kms describe-key to confirm it.
Errors. Any failure exits non-zero with the error on stderr and nothing on
stdout, including in --json mode. Input errors (an unreadable key file, an
undecodable PEM, an unsupported PEM header, or an invalid --expires) are
reported before any AWS call.
kms-import calls two actions on the target key: kms:GetParametersForImport
and kms:ImportKeyMaterial. KMS allows an action when the key policy allows
it, either by granting it directly or by delegating to IAM policies in the
account. Where to grant the import actions depends on the key policy:
- Default key policy. It delegates to IAM, so the caller IAM policy alone is enough.
- Restrictive key policy. Add the key policy statement as well as the caller
IAM policy. The key policy recommended by docs.chinmina.dev
already grants both actions to administrator roles through its
AdministratorsManagestatement.
Replace the account ID, region, key ID, and role ARN with your own values.
Attach this policy to the principal that runs kms-import. It is scoped to the
key ARN, and GetParametersForImport is constrained to the wrapping algorithm
and key spec kms-import uses. ImportKeyMaterial can also be constrained with
kms:ExpirationModel and kms:ValidTo to mandate an expiry policy.
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "KMSGetWrappingParameters",
"Effect": "Allow",
"Action": "kms:GetParametersForImport",
"Resource": "arn:aws:kms:us-east-1:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
"Condition": {
"StringEquals": {
"kms:WrappingAlgorithm": "RSA_AES_KEY_WRAP_SHA_256",
"kms:WrappingKeySpec": "RSA_4096"
}
}
},
{
"Sid": "KMSImportKeyMaterial",
"Effect": "Allow",
"Action": "kms:ImportKeyMaterial",
"Resource": "arn:aws:kms:us-east-1:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"
}
]
}Add this statement to a restrictive key policy. It names the account as the
principal and matches the importing role with aws:PrincipalArn, so it keeps
working when the role is recreated (rationale). Within a
key policy, "Resource": "*" refers to the key the policy is attached to.
{
"Sid": "AllowKeyMaterialImport",
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::111122223333:root"
},
"Action": [
"kms:GetParametersForImport",
"kms:ImportKeyMaterial"
],
"Resource": "*",
"Condition": {
"ArnLike": {
"aws:PrincipalArn": "arn:aws:iam::111122223333:role/KeyImporter"
}
}
}Note
The kms:RequestAlias condition key has no effect on GetParametersForImport
or ImportKeyMaterial, so scope import permissions by key ARN. Alias scoping
belongs on the application's kms:Sign permission, as shown in
Configuring the Chinmina service.
KMS cannot rotate imported asymmetric key material. Rotation creates a replacement key, imports a new GitHub App private key into it, and repoints the alias the application signs through.
kms-import performs the import step. Target the replacement key by ARN, since
the alias still points at the old key and the import APIs reject aliases.
Confirm that aws kms describe-key --key-id <KEY_ARN> reports a KeyState of
Enabled before repointing the alias.
The rotation process on docs.chinmina.dev covers the full sequence. It includes generating the new key in GitHub, confirming the cutover in CloudTrail, and deleting the old private key in GitHub, which is the step that revokes it.
The import logic is a Go library that builds no SDK client and never calls
os.Exit. The caller injects a KMSClient, which the AWS SDK *kms.Client
satisfies. cli.Command() mounts the CLI as a subcommand of another urfave/cli
v3 application.
import (
"context"
"github.com/aws/aws-sdk-go-v2/config"
"github.com/aws/aws-sdk-go-v2/service/kms"
"github.com/chinmina/kms-import/pkg/kmsimport"
)
cfg, _ := config.LoadDefaultConfig(ctx)
der, _ := kmsimport.KeyMaterialFromPEM(pemBytes) // PEM (PKCS#1 or PKCS#8) → PKCS#8 DER
res, err := kmsimport.Import(ctx,
kmsimport.WithClient(kms.NewFromConfig(cfg)),
kmsimport.WithKeyID("1234abcd-12ab-34cd-56ef-1234567890ab"),
kmsimport.WithKeyMaterial(der),
)Release artifacts (the binary archives and install.sh) are published to
GitHub Releases and carry a build provenance
attestation created with Sigstore keyless
signing. Each artifact is bound, by digest, to the source commit and the
workflow run that built it. No long-lived signing key exists.
Verify a downloaded artifact with the GitHub CLI (2.49.0 or later):
gh attestation verify kms-import_linux_amd64.tar.gz --repo chinmina/kms-import \
--signer-workflow chinmina/.github/.github/workflows/goreleaser-release.yml--repo checks the source repository. --signer-workflow is required because
the artifacts are signed by the shared release workflow in chinmina/.github,
not by a workflow in this repository.
checksums.txt lists every archive. After downloading it alongside an archive,
check with sha256sum --check --ignore-missing checksums.txt, or
shasum -a 256 --check --ignore-missing checksums.txt on macOS.
Releases are immutable: once published, their assets cannot be changed and their tag cannot be moved. GitHub records a release attestation of the tag, commit, and every asset. Check a downloaded file against it with GitHub CLI 2.81.0 or later:
gh release verify-asset v1.2.3 kms-import_linux_amd64.tar.gz --repo chinmina/kms-import