I want to protect structured data

Tink APIs take arbitrary binary blobs as input. This means that if you want to encrypt more complicated data, like protocol buffers, you need to encode the data first.

Encrypting a protobuf

To encrypt:

  1. Serialize the protobuf to a byte array.
  2. Encrypt the serialized bytes, then store or send the resulting ciphertext. Use:

To decrypt:

  1. Decrypt the ciphertext.
  2. If Step 1 was successful, deserialize the protobuf.

Protect a protobuf from tampering

In most cases, encrypting a protobuf is preferable to authentication alone.

To protect a protobuf from tampering:

  1. Serialize the protobuf to a byte array.
  2. Sign or authenticate the serialized bytes. Use:
  3. Store the serialized bytes together with the signature (or MAC).

To verify:

  1. Get the serialized protobuf and its signature (or MAC).
  2. Verify the signature (or MAC).
  3. Deserialize the protobuf.

Note that a valid signature or MAC does not guarantee that the data is correctly formatted. An implementation that parses the data should always expect that the data might be corrupt.

Protecting multiple data items

To protect multiple data items, use a serialization method. Add all of the data items to a protobuf, and encrypt (or authenticate) it as described above.

You can also serialize as follows:

serialize(data1 , data2 , …, datan) = 4-byte-data1's length || data1 || 4-byte-data2's length || data2 || … || 4-byte-dataN's length || dataN

Finally, encrypt (or authenticate) the resulting byte array.