tink-crypto / tink

Tink is a multi-language, cross-platform, open source library that provides cryptographic APIs that are secure, easy to use correctly, and hard(er) to misuse.
https://developers.google.com/tink
Apache License 2.0
13.5k stars 1.18k forks source link

Provide an easier to read example in the "I want to encrypt data deterministically" docs page #571

Closed fisadev closed 2 years ago

fisadev commented 2 years ago

This page of the docs is probably what most users will read first when trying to use the lib to encrypt data: https://developers.google.com/tink/deterministic-encryption

The example there is nice and very useful to use as a command line tool, but I believe it's not that good as docs on how to use Tink, because the Tink-related code is buried within lots of extra code doing other unrelated (to the lib) stuff, like args parsing, file reading, error handling, etc. Around 90% of the code in the example is unrelated to Tink.

IMHO, I would still keep that example console tool, but before that I would include a far simpler example in which only encryption with Tink is done. Something like this:

from tink import JsonKeysetReader, cleartext_keyset_handle, daead

# prepare Tink, a keyset and a cipher
daead.register()
keyset_handle = cleartext_keyset_handle.read(JsonKeysetReader("maybe a keyset example here? is it too complex?"))
cipher = keyset_handle.primitive(daead.DeterministicAead)

# encrypt data:
input_data = "Hello world!"
associated_data = b""
encrypted_data = cipher.encrypt_deterministically(input_data, associated_data)

# decrypt data:
decrypted_data = cipher.decrypt_deterministically(encrypted_data, associated_data)
kste commented 2 years ago

This is a very good point and we started adding simpler examples now, which also provide a more step-by-step explanation on what exactly is happening.