When you start working with Tink for the first time, there are some key concepts you should understand before you begin your journey; these are described in the following sections.
Tink uses primitives as
cryptographic building blocks. A primitive defines the details of a
cryptographic algorithm and the key type. An example of a primitive is
Authenticated Encryption with Associated Data (AEAD), which exposes an interface
for encrypting (
Encrypt) and decrypting (
A key type implements a specific primitive. Most primitives have several key types to choose from, depending on your requirements for security, running time, and space. For example, AES128_GCM is an AEAD; it is fast and effective for most needs.
Tink uses keysets for managing keys. A keyset is essentially a set of keys that facilitate key rotation. Noteworthy properties of a keyset are:
- Each key in a keyset has a unique id, which is unique within a keyset. This id is usually added as a prefix to each produced ciphertext, signature or tag to indicate which key was used (see how Tink tags ciphertexts for more info).
- Only one key at a time in a keyset is primary. A primary key in a keyset is the key "in use" at the moment.
- All the keys in a keyset must be implementations of the same primitive (such as AEAD), but can have different key types (for example, an AES-GCM and XCHACHA20-POLY1305 key).
Each Tink implementation provides APIs to create or edit keysets. However, we recommend using Tinkey our CLI tool.
Users operate over a keyset using keyset handles. A keyset handle limits the
exposure of the actual sensitive key material. It also abstracts a keyset
allowing users to obtain a primitive that "wraps" the entire keyset. For
example, you can get an AEAD primitive of a keyset with
N keys; encryption and
decryption with the obtained primitive then uses the primary key in the keyset.
This may sound complicated, but we've prepared some materials to help you get started with Tink in two steps:
- Set up Tink
Follow a pre-prepared scenario to help you choose a primitive and key type. Select the appropriate scenario depending on what you want to do:
- Encrypt data
- Encrypt large files or data streams
- Exchange data
- Protect data from tampering
- Digitally sign data
- Use client-side encryption with a cloud provider
- Encrypt data deterministically
- Protect structured data
- Bind ciphertext to its context
- Meet FIPS 140-2 security requirements
- Learn about the Tink wire format
Picking a primitive can be tricky. If the use cases here don't fit your needs, ask a question on StackOverflow.