Skip to content

Latest commit

 

History

History
193 lines (140 loc) · 6.15 KB

TINKEY.md

File metadata and controls

193 lines (140 loc) · 6.15 KB
Raw

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.5.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:

  • 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.

  • 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
tinkey add-key --key-template ECDSA_P384 --in private-keyset.cfg \
--out private-keyset.cfg
  • Rotate a keyset by adding a primary key
tinkey rotate-keyset --key-template ED25519 --in private-keyset.cfg \
--out private-keyset.cfg
  • List metadata of keys in a keyset:
tinkey list-keyset --in private-keyset.cfg
  • Create a public keyset from a private keyset
tinkey create-public-keyset --in private-keyset.cfg --out public-keyset.cfg

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:

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
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
  • Rotate an encrypted keyset by adding a primary key
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