Tinkey

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.

Install from prebuilt binaries

Download the latest version of Tinkey from https://storage.googleapis.com/tinkey/tinkey-1.7.0.tar.gz. This version should work well on Linux, macOS and Windows.

Install with Homebrew

brew tap google/tink https://github.com/google/tink
brew install tinkey

Build from source

• Install Bazel

• Check out the code

git clone https://github.com/google/tink.git

• Build

cd tink/tools
bazel build tinkey

The binary is located at bazel-bin/tinkey/tinkey.

Usage

tinkey <command> [<args>]

Available commands:

• help: Prints a help message for all 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.
• destroy-key: Destroys the key material of 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: Deprecated. Rotate keysets in two steps using the commands add-key and later promote-key.

To obtain info about arguments available/required for a command, run tinkey <command> without further arguments.

• Generate a keyset, and write it to private-keyset.cfg

tinkey create-keyset --key-template ECDSA_P256 --out private-keyset.cfg

• Add a new key to a keyset. This does not change the primary key.

tinkey add-key --key-template ECDSA_P512 --in private-keyset.cfg \
  --out new-private-keyset.cfg

• List metadata of keys in a keyset:

tinkey list-keyset --in private-keyset.cfg

• Make the key with key ID 1234567890 the primary key. (You can get the key ID using the list-keyset command.)

tinkey promote-key --in private-keyset.cfg --key-id 1234567890 \
  --out new-private-keyset.cfg

• Create a public keyset from a private keyset

tinkey create-public-keyset --in private-keyset.cfg --out public-keyset.cfg

Note: tinkey does not allow you to overwrite the keyset to prevent accidental loss of existing keys. We recommend you always create a new keyset and only delete the old keyset when you are certain that the new keyset works.

Work with Key Management System (KMS)

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.

Master key URI

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/*.

Credentials

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.

Examples

Please replace gcp-kms://projects/tink-examples/locations/global/keyRings/foo/cryptoKeys/bar in the following examples with appropriate key URIs.

• Generate a keyset, encrypt, and write it to encrypted-keyset.cfg, using default credentials

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

• Generate a keyset, encrypt and write it to 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

• List metadata of keys in an encrypted keyset, using credentials in 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

• Decrypt a keyset, and write the cleartext keyset to cleartext-keyset.cfg, using default credentials

tinkey convert-keyset --in encrypted-keyset.cfg --out cleartext-keyset.cfg \
--master-key-uri gcp-kms://projects/tink-examples/locations/global/keyRings/foo/cryptoKeys/bar

• Encrypt a keyset, write the encrypted keyset to encrypted-keyset.cfg, using default credentials

tinkey 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

• Add a new key to an encrypted keyset, using default credentials. This does not change the primary key.

tinkey add-key --key-template AES256_GCM --in encrypted-keyset.cfg \
  --out new-encrypted-keyset.cfg \
--master-key-uri gcp-kms://projects/tink-examples/locations/global/keyRings/foo/cryptoKeys/bar

• Make the key with key ID 1234567890 the primary key in an encrypted keyset. (You can get the key ID using the list-keyset command.)

tinkey promote-key--in encrypted-keyset.cfg --key-id 1234567890 \
  --out new-encrypted-keyset.cfg \
--master-key-uri gcp-kms://projects/tink-examples/locations/global/keyRings/foo/cryptoKeys/bar