Tink Python Cryptography Library

Warnings

• breaking Deserializing `KeysetHandle` objects using `pickle` is explicitly disallowed and will raise a `tink.TinkError`. This change was introduced in v1.14.0 to prevent unintentional key leakage.
  Fix: To serialize `KeysetHandle` objects, use `tink.proto_keyset_format` or `tink.json_proto_keyset_format` instead.
• breaking When a `GcpKmsClient` is instantiated with a `CryptoKeyVersion`, performing decryption will now raise an error, mirroring Google Cloud KMS service behavior which only allows specifying the version for encrypt operations.
  Fix: Ensure `GcpKmsClient` is instantiated without a `CryptoKeyVersion` when decryption operations are intended, or manage key versions appropriately for encryption-only contexts.
• gotcha Tink requires explicit registration of primitives or all standard implementations via `tink.tink_config.register()` (for all) or `primitive.register()` (e.g., `aead.register()`). Failing to do so will result in `tink.TinkError` messages like 'No wrapper registered' or 'No manager for type T has been registered' when attempting to obtain a primitive.
  Fix: Call `tink_config.register()` once at the start of your application, or register only the specific primitives you need (e.g., `aead.register()`).
• gotcha Directly using cleartext keysets (e.g., hardcoding them in your source code or loading them unencrypted from disk) is a significant security risk as it exposes sensitive key material.
  Fix: For production environments, always protect your cryptographic keys using secure key management solutions like Cloud KMS, AWS KMS, HashiCorp Vault, or by encrypting keysets using a master key.
• gotcha When using AEAD (Authenticated Encryption with Associated Data), the 'associated data' parameter is authenticated but *not* encrypted. It protects against tampering with the associated data but does not hide its contents.
  Fix: Be aware that associated data remains visible in cleartext. Do not include sensitive information in the associated data if it needs to remain confidential.
• gotcha `GcpKmsClient` can be used as a context manager (i.e., in a `with` statement) since v1.13.0, which ensures proper resource cleanup.
  Fix: Consider using `with gcpkms.GcpKmsClient(...) as client:` to manage `GcpKmsClient` instances for robust resource handling.

Install

• pip install tink Core Tink library
• pip install tink[gcpkms] Tink with Google Cloud KMS integration
• pip install tink[awskms] Tink with AWS KMS integration (implied)

Imports

• tink_config

  from tink import tink_config

• aead

  from tink import aead

• KeysetHandle

  import tink

• JsonKeysetReader

  from tink.json_proto_keyset_format import parse

• GcpKmsClient

  from tink.integration import gcpkms

• secret_key_access

  from tink import secret_key_access

  Required when parsing cleartext keysets, as a security token.

Quickstart

This quickstart demonstrates basic Authenticated Encryption with Associated Data (AEAD) using Tink. It covers initializing Tink, generating a new keyset, encrypting and decrypting data, and a warning-laden example of parsing a cleartext keyset. This example is simplified and does not involve KMS for brevity, but the same primitive concept applies.

import tink
from tink import aead
from tink import tink_config
from tink import secret_key_access
from tink.json_proto_keyset_format import parse

def main():
    # 1. Initialize Tink with all standard primitives.
    tink_config.register()

    # 2. Create a new AEAD keyset handle from a key template.
    # WARNING: Using cleartext keysets directly in code is a security risk.
    # For production, use secure key management, e.g., KMS or encrypted keysets.
    key_template = aead.aead_key_templates.AES256_GCM
    keyset_handle = tink.new_keyset_handle(key_template)

    # 3. Obtain the AEAD primitive from the keyset handle.
    aead_primitive = keyset_handle.primitive(aead.Aead)

    # 4. Define plaintext and associated data.
    plaintext = b'This is some secret data.'
    associated_data = b'associated_data_for_encryption'

    # 5. Encrypt the data.
    ciphertext = aead_primitive.encrypt(plaintext, associated_data)
    print(f'Encrypted data: {ciphertext.hex()}')

    # 6. Decrypt the data.
    try:
        decrypted_data = aead_primitive.decrypt(ciphertext, associated_data)
        print(f'Decrypted data: {decrypted_data.decode()}')
        assert decrypted_data == plaintext
        print('Encryption and decryption successful!')
    except tink.TinkError as e:
        print(f'Decryption failed: {e}')

    # Example of loading a cleartext keyset (for demonstration only, not recommended for production)
    cleartext_keyset_json = '{\"primaryKeyId\":1919301694,\"key\":[{\"keyData\":{\"typeUrl\":\"type.googleapis.com/google.crypto.tink.AesGcmKey\",\"value\":\"EhDKd0x8s2g+tXf1nJjDqD8u\",\"keyMaterialType\":\"SYMMETRIC\"},\"status\":\"ENABLED\",\"keyId\":1919301694,\"outputPrefixType\":\"TINK\"}]}'
    try:
        loaded_keyset_handle = parse(cleartext_keyset_json, secret_key_access.TOKEN)
        print("Successfully loaded cleartext keyset (for demonstration).")
    except tink.TinkError as e:
        print(f"Failed to load cleartext keyset: {e}")

if __name__ == '__main__':
    main()