Install & Compatibility
Where this runs
tested against v1.16.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.915 runs
build_error
glibcpy 3.10–3.915 runs
installs and imports cleanly · install 4.6s · import 0.131s · 89MB
89MB installed
● package 89MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
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.
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()
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'tink'
The Tink library has not been installed in the current Python environment.
fixInstall the Tink library using pip: `pip install tink`
tink.python.cc.tink_error.TinkError: Tink has not been initialized or the requested primitive type is not supported.
Tink's cryptographic primitives are not initialized or registered before attempting to use them, or an unsupported primitive type is requested.
fixCall `tink.tink_config.register()` or the specific primitive's `register()` method (e.g., `tink.aead.register()`) at the start of your application.
tink.python.cc.tink_error.TinkError: invalid key
The provided key material (keyset) is either malformed, corrupted, or incompatible with the cryptographic operation being attempted.
fixEnsure the keyset is properly generated and loaded using `tink.keyset_handle` methods, and that it corresponds to the intended primitive (e.g., AEAD for AEAD operations).
tink.jwt._jwt_error.JwtInvalidError: invalid JWT signature
The signature of the provided JSON Web Token (JWT) does not match the expected signature, indicating tampering or that the wrong public key is used for verification.
fixVerify that the JWT was signed with the correct private key and that the public key used for verification corresponds to that private key and is correctly loaded into the `JwtPublicKeyVerify` primitive.
Upgrade
Version history
1.16.1latest on PyPI · released Aug 13, 2026
Audit
Dependencies
protobufrequiredUsed for serializing key material and configuration. Version 6.33.5 was specified in Tink Python v1.14.0.
google-cloud-kmsoptionalRequired for the 'gcpkms' extra to interact with Google Cloud KMS.
boto3optionalRequired for the 'awskms' extra to interact with AWS KMS.