{"id":2809,"library":"tink","title":"Tink Python Cryptography Library","description":"Tink is a multi-language, cross-platform library that provides cryptographic APIs designed to be secure, easy to use, and hard to misuse. It is developed by cryptographers and security engineers at Google and offers primitives for common cryptographic tasks like AEAD, Streaming AEAD, Deterministic AEAD, MAC, Hybrid Encryption, Digital Signatures, and JWT. The library is actively maintained with frequent releases, currently at version 1.14.1.","status":"active","version":"1.14.1","language":"en","source_language":"en","source_url":"https://github.com/tink-crypto/tink-py","tags":["cryptography","security","kms","encryption","google","cloud"],"install":[{"cmd":"pip install tink","lang":"bash","label":"Core Tink library"},{"cmd":"pip install tink[gcpkms]","lang":"bash","label":"Tink with Google Cloud KMS integration"},{"cmd":"pip install tink[awskms]","lang":"bash","label":"Tink with AWS KMS integration (implied)"}],"dependencies":[{"reason":"Used for serializing key material and configuration. Version 6.33.5 was specified in Tink Python v1.14.0.","package":"protobuf","optional":false},{"reason":"Required for the 'gcpkms' extra to interact with Google Cloud KMS.","package":"google-cloud-kms","optional":true},{"reason":"Required for the 'awskms' extra to interact with AWS KMS.","package":"boto3","optional":true}],"imports":[{"symbol":"tink_config","correct":"from tink import tink_config"},{"symbol":"aead","correct":"from tink import aead"},{"symbol":"KeysetHandle","correct":"import tink"},{"symbol":"JsonKeysetReader","correct":"from tink.json_proto_keyset_format import parse"},{"symbol":"GcpKmsClient","correct":"from tink.integration import gcpkms"},{"note":"Required when parsing cleartext keysets, as a security token.","symbol":"secret_key_access","correct":"from tink import secret_key_access"}],"quickstart":{"code":"import tink\nfrom tink import aead\nfrom tink import tink_config\nfrom tink import secret_key_access\nfrom tink.json_proto_keyset_format import parse\n\ndef main():\n    # 1. Initialize Tink with all standard primitives.\n    tink_config.register()\n\n    # 2. Create a new AEAD keyset handle from a key template.\n    # WARNING: Using cleartext keysets directly in code is a security risk.\n    # For production, use secure key management, e.g., KMS or encrypted keysets.\n    key_template = aead.aead_key_templates.AES256_GCM\n    keyset_handle = tink.new_keyset_handle(key_template)\n\n    # 3. Obtain the AEAD primitive from the keyset handle.\n    aead_primitive = keyset_handle.primitive(aead.Aead)\n\n    # 4. Define plaintext and associated data.\n    plaintext = b'This is some secret data.'\n    associated_data = b'associated_data_for_encryption'\n\n    # 5. Encrypt the data.\n    ciphertext = aead_primitive.encrypt(plaintext, associated_data)\n    print(f'Encrypted data: {ciphertext.hex()}')\n\n    # 6. Decrypt the data.\n    try:\n        decrypted_data = aead_primitive.decrypt(ciphertext, associated_data)\n        print(f'Decrypted data: {decrypted_data.decode()}')\n        assert decrypted_data == plaintext\n        print('Encryption and decryption successful!')\n    except tink.TinkError as e:\n        print(f'Decryption failed: {e}')\n\n    # Example of loading a cleartext keyset (for demonstration only, not recommended for production)\n    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\\\"}]}'\n    try:\n        loaded_keyset_handle = parse(cleartext_keyset_json, secret_key_access.TOKEN)\n        print(\"Successfully loaded cleartext keyset (for demonstration).\")\n    except tink.TinkError as e:\n        print(f\"Failed to load cleartext keyset: {e}\")\n\nif __name__ == '__main__':\n    main()","lang":"python","description":"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."},"warnings":[{"fix":"To serialize `KeysetHandle` objects, use `tink.proto_keyset_format` or `tink.json_proto_keyset_format` instead.","message":"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.","severity":"breaking","affected_versions":">=1.14.0"},{"fix":"Ensure `GcpKmsClient` is instantiated without a `CryptoKeyVersion` when decryption operations are intended, or manage key versions appropriately for encryption-only contexts.","message":"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.","severity":"breaking","affected_versions":">=1.13.0"},{"fix":"Call `tink_config.register()` once at the start of your application, or register only the specific primitives you need (e.g., `aead.register()`).","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Consider using `with gcpkms.GcpKmsClient(...) as client:` to manage `GcpKmsClient` instances for robust resource handling.","message":"`GcpKmsClient` can be used as a context manager (i.e., in a `with` statement) since v1.13.0, which ensures proper resource cleanup.","severity":"gotcha","affected_versions":">=1.13.0"}],"env_vars":null,"last_verified":"2026-04-10T00:00:00.000Z","next_check":"2026-07-09T00:00:00.000Z"}