pykmstool 2.1.0

Google Cloud KMS Certificate Signing Request (CSR) Generation Tool

Google Cloud KMS Certificate Signing Request (CSR) Generation Tool

Features

• List KMS key resource names within a specified region ID and/or project ID.
• Get PEM-encoded public key for a given KMS key.
• Generate CSR and sign it using KMS key.
  • Supports RSA (2048-4096, SHA256/SHA512), ECDSA (P-256, P-384, Secp256k1) and Ed25519 keys.
  • Automatically warns about possible compliance issues if the specified key is not HSM-protected or was imported (can be bypassed).
  • Subject X.509 name in the CSR is customized using RFC4514 string provided by the user.

Classic usage

Installation

Package available on PyPi:

pip3 install pykmstool

GCP Authentication

1. Install the gcloud CLI
2. Create application default credentials:

   gcloud auth application-default login
   

Tip: Alternatively, you can manually specify a service account JSON key file by appending --service-account-file path/to/credentials.json to every pykmstool command invocation in the further section.

Tip: If you need to specify quota project to use, please append --quota-project-id <...> on every invocation of pykmstool commands listed in the further section.

Tool usage

Generating a CSR

Generate and sign a CSR using a crypto key version specified by --key-version-name parameter. The name specified in the --x509-name parameter must be compliant with the RFC4514 format and will be embedded within the resulting CSR.

pykmstool sign-csr \
    --key-version-name projects/example-project/locations/europe-west6/keyRings/ExampleKeyRing/cryptoKeys/ExampleRSAKey1/cryptoKeyVersions/1 \
    --x509-name "C=US,O=Example Corp,CN=example.com"

Replace "US" with your two-letter country code, "Example Corp" with your organization name (company's name) and "example.com" with your company's domain.

See --help for all other available parameters.

Note: Required GCP IAM permissions:

cloudkms.cryptoKeyVersions.get
cloudkms.cryptoKeyVersions.viewPublicKey
cloudkms.cryptoKeyVersions.useToSign

Note: IAM Condition to scope those permissions to a single key (optional):

(
  resource.type == "cloudkms.googleapis.com/CryptoKey" &&
  resource.name == "projects/{projectName}/locations/{location}/keyRings/{keyRingName}/cryptoKeys/{keyName}"
) || (
  resource.type == "cloudkms.googleapis.com/CryptoKeyVersion" &&
  resource.name.startsWith("projects/{projectName}/locations/{location}/keyRings/{keyRingName}/cryptoKeys/{keyName}/cryptoKeyVersions/"
)

Substitute {...} placeholders with appropriate names.

Tip: EV Code Signing Certificate Authorities would usually not be very strict about the X.509 Name embedded inside the Certificate Signing Request. If there were no special instructions about that provided by the CA, it should be fully sufficient to just set "C" (Country), "O" (Company name), "CN" (Company's domain) keys, just as in the example command provided above.

Getting a PEM public key for given key version

pykmstool get-public-key \
    --key-version-name projects/example-project/locations/europe-west6/keyRings/ExampleKeyRing/cryptoKeys/ExampleRSAKey1/cryptoKeyVersions/1

Note: Required GCP IAM permissions:

cloudkms.cryptoKeyVersions.get
cloudkms.cryptoKeyVersions.viewPublicKey

Listing all enabled key versions globally or for a given location/project ID:

Resources will be listed only if the account has sufficient permissions to list resources.

# Only search within a specified project and location ID
pykmstool list-key-versions --project-id example-project --location-id europe-west6
# Search within a given location throughout all available projects
pykmstool list-key-versions --location-id europe-west6
# Search within a project throughout all possible locations (slow)
pykmstool list-key-versions --project-id example-project
# Search globally (slow)
pykmstool list-key-versions

Note: Required GCP IAM permissions (assuming that both --location-id and --project-id are provided):

cloudkms.keyRings.list
cloudkms.cryptoKeys.list	
cloudkms.cryptoKeyVersions.list	

Library usage

See src/pykmstool/kms_funcs.py for available functions.

Docker usage

Tip: With the Docker flow, you don't need to perform "Installation" and "GCP Authentication" steps listed above. The Docker version will automatically lead you through those processes.

Executing commands

docker run \
   -v ./gcloud-config:/root/.config/gcloud \
   -it ghcr.io/icedevml/pykmstool:v2.1.0 \
   -- \
   sign-csr \
   --key-version-name projects/example-project/locations/europe-west6/keyRings/ExampleKeyRing/cryptoKeys/ExampleRSAKey1/cryptoKeyVersions/1 \
   --x509-name "C=US,O=Example Corp,CN=example.com"

On the first run, this command will automatically lead you through the GCP sign in process.

See "Tool usage" section above for more information about supported commands.

Revoking authentication

Remember to invalidate your credentials after finishing work with the tool, which could be done using:

docker run \
   -v ./gcloud-config:/root/.config/gcloud \
   -it ghcr.io/icedevml/pykmstool:v2.1.0 \
   docker-revoke-credentials