Tink Cryptographic Library

Tink uses a registration system to choose specific implementations for primitives. You must register implementations before they can be used.

• Register all standard implementations: Use tink_config.register().
• Register a specific primitive: Use the .register() method on the specific primitive module (e.g., aead.register()).
• Register custom key managers: Use core.Registry.register_key_manager(manager_instance).

import tink
from tink import tink_config
tink_config.register()  # Registers all standard implementations

Deterministic AEAD is a symmetric primitive used to encrypt data such that the same plaintext always results in the same ciphertext.

Warning: Unlike standard AEAD, DAEAD implementations are not semantically secure because they lack randomized encryption. Use this only when your use case specifically requires deterministic output.

Tink separates symmetric and asymmetric primitives. Even though they use the same underlying algorithms, JWT primitives use specific JWT key types that store metadata like alg and kid.

Asymmetric (Recommended for distributed systems)

Use these when tokens are generated by one entity and verified by another. The private key signs, and the public key verifies.

• Primitives: JwtPublicKeySign and JwtPublicKeyVerify.
• Supported Algorithms: ES256, ES384, ES512, RS256, RS384, RS512, PS256, PS384, and PS512.

Symmetric (Internal use only)

Use these only if the same entity generates and verifies the tokens.

• Primitive: JwtMac.
• Supported Algorithms: HS256, HS384, and HS512.

Tink provides several flavors of Authenticated Encryption with Associated Data (AEAD) depending on your use case:

• AEAD: Standard authenticated encryption.
• Streaming AEAD: Designed for encrypting large streams of data.
• Deterministic AEAD: Provides encryption where the same plaintext and associated data always result in the same ciphertext (useful for searchable encryption).

This example demonstrates how to perform client-side encryption/decryption of Google Cloud Storage (GCS) blobs using Tink's Envelope Encryption pattern.

How it works:

1. Tink generates a new Data Encryption Key (DEK).
2. The data is encrypted with the DEK using AES256 GCM.
3. The DEK is then wrapped (encrypted) using a Key Encryption Key (KEK) located in Cloud KMS.
4. The encrypted DEK is stored alongside the ciphertext in GCS.

Important Constraint: The encryption result is bound to the specific GCS blob location. If you rename or move the blob to a different bucket, decryption will fail.

The core workflow for using Tink involves three main steps:

1. Key Management: Generating new key material or loading existing keys (e.g., from private shared preferences or Android Keystore).
2. Obtaining a Primitive: Using the keys to obtain a cryptographic primitive (an object that performs a specific cryptographic operation).
3. Performing Cryptography: Using the obtained primitive to execute operations like encryption or decryption.

On Android M or newer, it is recommended to encrypt keys with a master key stored in the Android Keystore for enhanced security.

Tink requires explicit initialization through the registration of implementations (identified by key types).

To register all implementations of all primitives, use TINKAllConfig with TINKConfig registerConfig:error:.

To register only specific primitives, such as AEAD, use the corresponding config class (e.g., TINKAeadConfig).

#import "Tink/TINKAllConfig.h"
#import "Tink/TINKConfig.h"

NSError *error = nil;
TINKAllConfig *config = [[TINKAllConfig alloc] initWithError:&error];
if (!config || error) {
  // handle error.
}

if (![TINKConfig registerConfig:config error:&error]) {
  // handle error.
}

Tink performs cryptographic tasks through two core abstractions: primitives and interfaces.

All Tink primitives share these general properties:

• Stateless: They are thread-safe.
• Copy-safe: Parameters can be safely copied.
• High Security: They provide at least 128-bit security (with the exception of RSA).

Tink supports the following additional cryptographic primitive families:

• Message Authentication Code (MAC): For verifying data integrity and authenticity.
• Pseudo Random Function (PRF) Families: For generating pseudo-random values.
• Hybrid Encryption: Combines asymmetric and symmetric encryption for efficient secure communication.
• Digital Signatures: For providing non-repudiation and authenticity using asymmetric keys.