Data Protection API Choices Guide: Choosing Tink, libsodium or Platform Crypto Safely

Most cryptographic failures in applications are not broken algorithms but correct algorithms called through the wrong API. A developer who reaches for raw AES, picks a mode, generates a nonce and stores the key next to the data has made four decisions that each can fail silently. High-level libraries such as Google Tink, libsodium and the AWS Encryption SDK exist to take those decisions away. This guide compares the main data protection APIs, explains what each one guarantees and does not, and gives a selection method, a rollout plan and review checks. It is written for application security engineers, architects and senior developers who choose or approve cryptographic dependencies.

Key takeaways

• Choose by abstraction level, not by algorithm. A misuse-resistant API (Tink Aead, libsodium crypto_secretbox_easy, Fernet) removes nonce, mode and padding choices that low-level APIs leave to the caller.
• Authenticated encryption is the default. OWASP ASVS 5.0 V11.3.3 expects encrypted data to be protected against modification, preferably with an approved authenticated encryption method; unauthenticated CBC or CTR is a finding.
• The key is the hard part. Every library in this guide is only as safe as where its key lives. Tink and the AWS Encryption SDK integrate with a KMS; libsodium and Fernet leave key storage entirely to you.
• Know each API's limits. Random-nonce AES-GCM is limited to about 2^32 messages per key, Fernet loads whole messages into memory, and sealed boxes do not authenticate the sender.
• Standardise and inventory. One approved library per language, wrapped in an internal module, is easier to review, migrate and make crypto-agile than many teams each calling primitives directly.

Why API level matters more than algorithm choice

Low-level interfaces such as the Java Cryptography Architecture Cipher class, the Web Crypto SubtleCrypto interface and OpenSSL's EVP functions expose primitives. They are flexible and necessary for protocol implementers, but they let callers pick insecure combinations. MDN's documentation of SubtleCrypto warns that its low-level primitives are very easy to misuse and that the pitfalls can be very subtle. The OWASP Cryptographic Storage Cheat Sheet makes the same point from the other side: IVs and similar attributes should be handled automatically by the library, custom algorithms should never be written, and ECB should not be used outside very specific circumstances.

A misuse-resistant library changes the developer's job from "assemble a construction" to "call encrypt with a key handle". Tink's own design notes describe its Aead interface as generating a fresh random nonce on every encrypt call and not accepting a caller-supplied nonce, which removes nonce reuse as a class of bug. libsodium's crypto_secretbox_easy still takes a nonce but fixes the algorithm, the tag and the layout, and its documentation states plainly that a nonce should never be reused with the same key. The difference in review effort is large: a reviewer checking a Tink call needs to look at key handling and associated data; a reviewer checking a raw AES call needs to check mode, padding, IV generation, tag verification, constant-time comparison and error handling.

For the underlying theory of modes and nonce misuse, see the Authenticated Encryption and Block Cipher Modes Guide and the Cryptographic Protocol Failures and Misuse Guide. This page stays on the practical question of which API to put in front of developers.

The main high-level libraries compared

What the platform APIs now do for you

• Go: cipher.NewGCMWithRandomNonce generates a random 96-bit nonce, prepends it to the ciphertext in Seal and extracts it in Open. The Go source states that a key must not encrypt more than 2^32 messages with it, to keep random nonce collisions negligible.
• .NET: the AesGcm constructors that do not take a tag size are marked obsolete (diagnostic SYSLIB0053); use the constructor that fixes tagSizeInBytes so encryption and decryption agree on a full-length tag.
• Java: always name the full transformation (for example AES/GCM/NoPadding). A bare "AES" string leaves the mode and padding to the provider default, which in common providers is ECB.
• Browser: SubtleCrypto is only available in secure contexts. exportKey exports keys unencrypted; use wrapKey for sensitive keys and create keys as non-extractable where the design allows.

Choosing the right primitive for the job

Most selection mistakes come from using encryption where a MAC or signature is needed, or from using deterministic encryption without understanding what it leaks. Tink organises its API by use case, which is a useful checklist even outside Tink.

OWASP's cheat sheet recommends an established hybrid scheme such as HPKE (RFC 9180) for public-key encryption and notes that the HPKE base mode does not authenticate the sender and gives only limited replay protection. libsodium's sealed box documentation makes the same point: the recipient can verify integrity but not the sender's identity.

Keys, keysets and KMS integration

A high-level library prevents construction errors; it does not decide where keys live. This is where the identity angle is real: data encryption keys and the credentials that unwrap them are non-human secrets, and a hard-coded key is a credential leak with a cryptographic blast radius.

• Tink keysets: Tink stores keys in keysets, generated from key templates (for example AES128_GCM) and serialised encrypted under a key encryption key held in a KMS. Tink's documentation recommends encrypted keysets and warns that cleartext keysets are not recommended because keys stored in plaintext often leak. The Tinkey CLI can create KMS-wrapped keysets.
• Envelope encryption: Tink's KMS Envelope AEAD and the AWS Encryption SDK both generate a fresh data key per message and wrap it under a KMS key. The AWS SDK stores encrypted data keys with the ciphertext in its message format and can wrap one data key under several wrapping keys, for example a KMS key and an on-premises HSM key. See the AWS KMS Security Guide and the Cloud KMS and Cloud HSM Guide.
• libsodium and Fernet: both take raw key bytes. Load them from a secrets manager or KMS at start-up, never from source code or a configuration file in the repository. libsodium provides sodium_memzero, sodium_mlock and sodium_malloc for keeping keys out of swap and core dumps, and its documentation recommends disabling core dumps for crypto code in production.
• Rotation: Tink keysets hold several keys with one primary used for new encryptions; MultiFernet encrypts with the first key and tries each key on decryption, and its rotate() re-encrypts a token under the primary key. Tink's key management overview suggests enabling automatic rotation of the KMS key.
• The KMS credential: the workload identity that can call KMS decrypt is the real key. Scope it to the specific key and the specific service. See the Cryptographic Key Management Guide.

Decision guidance

Small organisations: pick one library per language, publish a short code snippet for each approved use, and block direct primitive use in code review. Large organisations: wrap the chosen library in an internal crypto module owned by a platform team, so algorithm changes (for example a post-quantum migration) happen in one place. That wrapper is what OWASP ASVS V11.2.2 means by designing for crypto agility. See the Crypto-Agility Guide.

Rolling out an approved crypto library

1. Inventory current use. Search code for direct primitive calls (Cipher.getInstance, createCipheriv, crypto.subtle, AES.new, EVP_Encrypt) and hard-coded key material. ASVS V11.1.2 and V11.1.3 expect a maintained inventory and discovery. See the Cryptographic Inventory and CBOM Guide.
2. Publish the approved list. One library and a small set of key templates per language and use case, with examples. Record the decision so reviewers can cite it.
3. Build the wrapper. Expose encrypt(plaintext, context) and decrypt(ciphertext, context); take keys only from the KMS or secrets manager; include a key or format version so old ciphertext stays readable.
4. Test against known-answer and attack vectors. Project Wycheproof publishes JSON test vectors for AES-GCM, ChaCha20-Poly1305, XChaCha20-Poly1305, ECDSA, EdDSA, RSA, HKDF, ML-KEM and more; run them in CI for any wrapper that exposes primitives.
5. Pilot on one service. Encrypt new writes with the new library while reading old ciphertext with the legacy path (dual read). Keep the legacy decrypt path until re-encryption completes.
6. Re-encrypt and retire. Batch re-encrypt historical data, track progress as a metric, then remove the legacy decrypt code and its keys.
7. Enforce. Add static analysis rules that flag direct primitive use outside the wrapper, and fail builds on hard-coded keys.

Rollback: because new ciphertext carries a version marker and the legacy path is kept during the pilot, rolling back means switching writes back to the old path; never delete old keys until every record encrypted under them has been re-encrypted and verified.

Detection and measurement

• Static analysis: rules for ECB, static or zero IVs, Math.random() or java.util.Random for keys or nonces (OWASP lists the CSPRNG replacements per language), and string equality on MACs.
• Secret scanning: detect key material and Tink cleartext keysets committed to repositories. See the Git Secret Scanning Guide.
• KMS audit logs: decrypt calls by principal and key; alert on new principals or unusual volume against data keys.
• Dependency monitoring: track library versions and advisories; libsodium, Tink and pyca/cryptography all publish releases that change defaults.

Metrics that show the programme is working:

• Percentage of services whose encryption goes through the approved wrapper.
• Count of direct primitive call sites outside the wrapper, trending to zero.
• Hard-coded key findings open, and mean time to remove and rotate them.
• Percentage of stored ciphertext under a current key version.
• Percentage of data keys wrapped by a KMS or HSM rather than stored in configuration.

Framework mapping

Common failure patterns

• Hard-coded keys shared by every installation: in the Gladinet hard-coded keys exploitation, the AES key and IV used for access tickets were derived from fixed strings, so one extraction let attackers forge tickets against every customer. A KMS-wrapped keyset generated per installation would have removed the shared secret.
• Encryption without authentication: AES-CBC or CTR with no MAC, often from a copied snippet. Ciphertext can be modified, and padding errors can become an oracle. ASVS V11.3.3 and V11.3.5 address this.
• Nonce reuse at scale: counters reset on restart, or random 96-bit nonces under one key beyond the roughly 2^32 message limit that libsodium and Go both document for AES-GCM. Use XChaCha20-Poly1305, Tink's random-nonce Aead, or rekey.
• Wrong primitive: sealed boxes or HPKE base mode used as if they proved who sent the message, or deterministic encryption used for high-sensitivity fields where equality leakage matters.
• Cleartext keysets and exported keys: Tink cleartext keysets in configuration, or Web Crypto keys exported unencrypted to local storage.
• Library sprawl: five libraries across ten teams, none inventoried, so a deprecation or post-quantum migration cannot be planned.

Practitioner checklist

• Publish one approved data protection library per language, with key templates and examples for each use case.
• Require authenticated encryption everywhere; treat unauthenticated modes and ECB as blocking findings.
• Bind context such as tenant and record identifiers as associated data.
• Keep data keys wrapped by a KMS or HSM; ban cleartext keysets and hard-coded keys.
• Scope the KMS decrypt permission to the specific workload identity and key.
• Use streaming AEAD for large files and respect per-key message limits.
• Wrap the library in an internal module with a version marker to support rotation and crypto agility.
• Run Wycheproof vectors in CI for any code that exposes primitives.
• Track direct primitive call sites and hard-coded key findings as metrics.

Standards and references

• OWASP: Application Security Verification Standard 5.0
• OWASP: Cryptographic Storage Cheat Sheet
• Google: Tink, Choose a primitive
• Google: Tink, Key management overview
• libsodium: Authenticated Encryption with Additional Data
• AWS: What is the AWS Encryption SDK?
• pyca/cryptography: Fernet (symmetric encryption)
• C2SP: Project Wycheproof test vectors

Related NHI Mgmt Group resources: Cryptographic Key Management Guide · Authenticated Encryption and Block Cipher Modes Guide · OWASP CI/CD Top 10 CICD-SEC-6 Insufficient Credential Hygiene Guide · Crypto-Agility Guide