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.
Primitives
Tink uses primitives as cryptographic building blocks that manage an underlying algorithm so users can perform cryptographic tasks safely. A primitive defines the details of a cryptographic algorithm and the key type.
Primitives supported by Tink:
- Authenticated Encryption with Associated Data (AEAD): The most common primitive for data encryption; suitable for most encryption needs. AEAD provides plaintext confidentiality, and allows verification of its integrity and authenticity. See Authenticated Encryption with Associated Data (AEAD).
- Deterministic encryption: A primitive that always produces the same ciphertext for a given plaintext and key. This can be risky, because an attacker only needs to find out which ciphertext corresponds to a given plaintext input to identify it. See Deterministic AEAD.
- Digital signature: An asymmetric (see Asymmetric key encryption) primitive for confirming the authenticity and integrity of signed data. See Digital signature.
- Hybrid encryption: A primitive that combines asymmetric key encryption and symmetric key encryption (see Asymmetric key encryption and Symmetric key encryption). Hybrid encryption combines the efficiency of symmetric encryption with the convenience of public-key encryption. To encrypt a message, a fresh symmetric key is generated and used to encrypt the plaintext data, while the recipient's public key is used to encrypt the symmetric key only. The final ciphertext consists of the symmetric ciphertext and the encrypted symmetric key. See Hybrid encryption.
- Message Authentication Code (MAC): A symmetric (see Symmetric key encryption) primitive for confirming the authenticity and integrity of data. See Message Authentication Code (MAC).
- Streaming AEAD: A primitive providing authenticated encryption for streaming data; useful when the data to be encrypted is too large to be processed in a single step. See Streaming AEAD.
See Supported primitives by language for compatibility information.
For more info, see primitive design.
Key types
A key type implements a specific primitive. Most primitives have several key types to choose from depending on your requirements for security, runtime, and space. For example, AES128_GCM is an AEAD that is fast and effective for most needs. See more at Supported key types by language.
Keysets & keyset handles
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.
For more info, see keyset design.