This utility allows generating and manipulating Tink keysets. It can encrypt or decrypt keysets with master keys residing in a remote key management service (KMS). Out of the box it supports AWS KMS and Google Cloud KMS. Adding support for other KMS is easy, and doesn't require modifying Tinkey.
Tinkey requires Java 8 or later to run.
Download the latest version of Tinkey from https://storage.googleapis.com/tinkey/tinkey-1.5.0.tar.gz. This version should work well on Linux, macOS and Windows.
brew tap google/tink https://github.com/google/tink brew install tinkey
Install Bazel
Check out the code
git clone https://github.com/google/tink.git
cd tink/tools bazel build tinkey
The binary is located at bazel-bin/tinkey/tinkey
.
tinkey <command> [<args>]
Available commands:
add-key
: Generates and adds a new key to a keyset.convert-keyset
: Changes format, encrypts, decrypts a keyset.create-keyset
: Creates a new keyset.create-public-keyset
: Creates a public keyset from a private keyset.list-key-templates
: Lists all supported key templates.delete-key
: Deletes a specified key in a keyset.disable-key
: Disables a specified key in a keyset.enable-key
: Enables a specified key in a keyset.list-keyset
: Lists keys in a keyset.promote-key
: Promotes a specified key to primary.rotate-keyset
: Performs a key rotation in a keyset.To obtain info about arguments available/required for a command, run tinkey <command>
without further arguments.
private-keyset.cfg
tinkey create-keyset --key-template ECDSA_P256 --out private-keyset.cfg
tinkey add-key --key-template ECDSA_P384 --in private-keyset.cfg \ --out private-keyset.cfg
tinkey rotate-keyset --key-template ED25519 --in private-keyset.cfg \ --out private-keyset.cfg
tinkey list-keyset --in private-keyset.cfg
tinkey create-public-keyset --in private-keyset.cfg --out public-keyset.cfg
Tinkey can encrypt or decrypt keysets with master keys residing in remote KMSes. In this mode, users first create a master key in the KMS and tell Tinkey where the master key is via the --master-key-uri
option. To create a master key in Google Cloud KMS, see https://cloud.google.com/kms/docs/quickstart. To create a master key in AWS KMS, see http://docs.aws.amazon.com/kms/latest/developerguide/create-keys.html.
Every master key URI starts with a unique prefix that identifies its KMS. The prefix for AWS KMS is aws-kms://
, and Google Cloud KMS gcp-kms://
. AWS KMS master key URIs are in this format aws-kms://arn:aws:kms:<region>:<account-id>:key/<key-id>
, and Google Cloud KMS gcp-kms://projects/*/locations/*/keyRings/*/cryptoKeys/*
.
Tinkey needs credentials to connect to AWS KMS or Google Cloud KMS. Users tell Tinkey where/how to load credentials via the --credential
option. If --master-key-uri
is specified, --credential
specifies the credentials file path. Google Cloud credentials are service account JSON files that can be created and downloaded from Google Cloud Console. AWS credentials are properties files with the AWS access key ID is expected to be in the accessKey
property and the AWS secret key is expected to be in the secretKey
property.
If --credential
is missing Tinkey will attempt to load the default credentials:
AWS KMS: http://docs.aws.amazon.com/sdk-for-java/v1/developer-guide/credentials.html#credentials-default
Google Clous KMS: https://developers.google.com/identity/protocols/application-default-credentials.
Please replace gcp-kms://projects/tink-examples/locations/global/keyRings/foo/cryptoKeys/bar
in the following examples with appropriate key URIs.
encrypted-keyset.cfg
, using default credentialstinkey create-keyset --key-template AES128_GCM --out encrypted-keyset.cfg \ --master-key-uri gcp-kms://projects/tink-examples/locations/global/keyRings/foo/cryptoKeys/bar
encrypted-keyset.cfg
, using credentials in credentials.json
tinkey create-keyset --key-template AES128_GCM --out encrypted-keyset.cfg \ --master-key-uri gcp-kms://projects/tink-examples/locations/global/keyRings/foo/cryptoKeys/bar --credential credential.json
credentials.json
tinkey list-keyset --in encrypted-keyset.cfg \ --master-key-uri gcp-kms://projects/tink-examples/locations/global/keyRings/foo/cryptoKeys/bar --credential credential.json
cleartext-keyset.cfg
, using default credentialstinkey convert-keyset --in encrypted-keyset.cfg --out cleartext-keyset.cfg \ --master-key-uri gcp-kms://projects/tink-examples/locations/global/keyRings/foo/cryptoKeys/bar
encrypted-keyset.cfg
, using default credentialstinkey convert-keyset --in cleartext-keyset.cfg --out encrypted-keyset.cfg \ --new-master-key-uri gcp-kms://projects/tink-examples/locations/global/keyRings/foo/cryptoKeys/bar
tinkey add-key --key-template AES256_GCM --in encrypted-keyset.cfg \ --out encrypted-keyset.cfg \ --master-key-uri gcp-kms://projects/tink-examples/locations/global/keyRings/foo/cryptoKeys/bar
tinkey rotate-keyset --key-template AES256_GCM --in encrypted-keyset.cfg \ --out encrypted-keyset.cfg \ --master-key-uri gcp-kms://projects/tink-examples/locations/global/keyRings/foo/cryptoKeys/bar