blob: 1b6d20155d58a62fd8783d7cf7c46256389e8b45 [file] [log] [blame] [view]
# Tink Primitives
[Tink](https://github.com/google/tink) performs cryptographic tasks via
so-called _primitives_, which provide an abstract representation of the provided
functionality. Tink primitives encompass the following cryptographic operations
and are supported via the corresponding interfaces:
| **Primitive** | **Interfaces** |
| --------------------------------------------------- | ------------------------------ |
| Authenticated Encryption with Associated Data (AEAD)| AEAD |
| *Streaming* AEAD | StreamingAEAD |
| *Deterministic* AEAD | DeterministicAEAD |
| Message Authentication Code (MAC) | MAC |
| Pseudo Random Function Family (PRF) | Prf, PrfSet |
| Hybrid encryption | HybridEncrypt, HybridDecrypt |
| Digital signatures | PublicKeySign, PublicKeyVerify |
The interface names above correspond with the Java implementation. Other
language implementations may have modified interface names due to differing
naming conventions.
The tables in the section below summarize the current implementations of
primitives available in the corresponding languages, and the subsequent sections
describe the main properties of Tink primitives.
## Supported primitives and their implementations
### Primitives supported by language
**Primitive** | **Java** | **C++** | **ObjC** | **Go** | **Python**
------------------ | -------- | ------- | -------- | ------ | ----------
AEAD | yes | yes | yes | yes | yes
Streaming AEAD | yes | yes | no | yes | yes
Deterministic AEAD | yes | yes | yes | yes | yes
MAC | yes | yes | yes | yes | yes
PRF | yes | yes | no | yes | yes
Digital signatures | yes | yes | yes | yes | yes
Hybrid encryption | yes | yes | yes | yes | yes
JavaScript is currently under development.
### Primitive implementations supported by language
#### Java
| Primitive | Java Implementations |
| ------------------ | --------------------------------------------------------------------------------- |
| AEAD | AES-GCM, AES-GCM-SIV, AES-CTR-HMAC, AES-EAX, KMS Envelope, CHACHA20-POLY1305, XCHACHA-POLY1305 |
| Streaming AEAD | AES-GCM-HKDF-STREAMING, AES-CTR-HMAC-STREAMING |
| Deterministic AEAD | AES-SIV |
| MAC | HMAC-SHA2, AES-CMAC |
| PRF | HKDF-SHA2, HMAC-SHA2, AES-CMAC |
| Digital Signatures | ECDSA over NIST curves, Ed25519, RSA-SSA-PKCS1, RSA-SSA-PSS |
| Hybrid Encryption | ECIES with AEAD/DeterministicAEAD and HKDF |
#### C++
| Primitive | C++ Implementations |
| ------------------ | ------------------------------------------------------------------------------------------------ |
| AEAD | AES-GCM, AES-GCM-SIV, AES-CTR-HMAC, AES-EAX, KMS Envelope, XCHACHA20-POLY1305 |
| Streaming AEAD | AES-GCM-HKDF-STREAMING, AES-CTR-HMAC-STREAMING |
| Deterministic AEAD | AES-SIV |
| MAC | HMAC-SHA2, AES-CMAC |
| PRF | HKDF-SHA2, HMAC-SHA2, AES-CMAC |
| Digital Signatures | ECDSA over NIST curves, Ed25519, RSA-SSA-PKCS1, RSA-SSA-PSS |
| Hybrid Encryption | ECIES with AEAD/DeterministicAEAD and HKDF |
#### Objective-C
Primitive | Objective-C Implementations
------------------ | ---------------------------------------------------------------
AEAD | AES-GCM, AES-CTR-HMAC, AES-EAX, XCHACHA20-POLY1305
Deterministic AEAD | AES-SIV
MAC | HMAC-SHA2, AES-CMAC
Digital Signatures | ECDSA over NIST curves, Ed25519, RSA-SSA-PKCS1, RSA-SSA-PSS
Hybrid Encryption | ECIES with AEAD and HKDF
#### Go
| Primitive | Go Implementations |
| ------------------ | ------------------------------------------------------------------------ |
| AEAD | AES-GCM, AES-CTR-HMAC, KMS Envelope, CHACHA20-POLY1305, XCHACHA-POLY1305 |
| Streaming AEAD | AES-GCM-HKDF-STREAMING, AES-CTR-HMAC-STREAMING |
| Deterministic AEAD | AES-SIV |
| MAC | HMAC-SHA2, AES-CMAC |
| PRF | HKDF-SHA2, HMAC-SHA2, AES-CMAC |
| Digital Signatures | ECDSA over NIST curves, Ed25519 |
| Hybrid Encryption | ECIES with AEAD/DeterministicAEAD and HKDF |
#### Python
Primitive | Python Implementations
------------------ | -----------------------------------------------------------------------------
AEAD | AES-GCM, AES-CTR-HMAC, AES-EAX, KMS Envelope, XCHACHA20-POLY1305
Streaming AEAD | AES-GCM-HKDF-STREAMING, AES-CTR-HMAC-STREAMING
Deterministic AEAD | AES-SIV
MAC | HMAC-SHA2, AES-CMAC
PRF | HKDF-SHA2, HMAC-SHA2, AES-CMAC
Digital Signatures | ECDSA over NIST curves, Ed25519, RSA-SSA-PKCS1, RSA-SSA-PSS
Hybrid Encryption | ECIES with AEAD/DeterministicAEAD and HKDF
---
## General properties of all primitives
- stateless (hence thread-safe)
- copy-safe (for the parameters)
- at least 128-bit security (with an exception for RSA)
## Authenticated Encryption with Associated Data
AEAD primitive (Authenticated Encryption with Associated Data) provides
functionality of symmetric authenticated encryption. Implementations of this
primitive are secure against adaptive chosen ciphertext attacks.
When encrypting a plaintext one can optionally provide _associated data_ that
should be authenticated but not encrypted. That is, the encryption with
associated data ensures authenticity (ie. who the sender is) and integrity (ie.
data has not been tampered with) of that data, but not its secrecy (see
[RFC 5116](https://tools.ietf.org/html/rfc5116)). This is often used for binding
encryptions to a context. For example, in a banking database the contents of a
row (e.g. bank account balance) can be encrypted using the customer's id as
_associated data_. This would prevent swapping encrypted data between customers'
records.
Minimal properties:
- _plaintext_ and _associated data_ can have arbitrary length
(within the range 0..2<sup>32</sup> bytes)
- CCA2 security
- at least 80-bit authentication strength
- there are no secrecy or knowledge guarantees wrt. to the value of _associated
data_
- can encrypt at least 2<sup>32</sup> messages with a total of 2<sup>50</sup>
bytes so that no attack has success probability larger than 2<sup>-32</sup>
## Streaming Authenticated Encryption with Associated Data
Streaming AEAD primitive (Streaming Authenticated Encryption with Associated
Data) provides authenticated encryption for streaming data, and is useful when
the data to be encrypted is too large to be processed in a single step. Typical
use cases include encryption of large files or encryption of live data
streams.
The underlying encryption modes are selected so that partial plaintext
can be obtained fast by decrypting and authenticating just a part of the
ciphertext, without need of processing the entire ciphertext.
Encryption must be done in one session. There is no possibility to modify an
existing ciphertext or to append to it (other than to reencrypt the entire file
again).
Instances of _Streaming AEAD_ follow the OAE2 definition proposed in the
paper [_"Online Authenticated-Encryption and its Nonce-Reuse Misuse-Resistance"_
by Hoang, Reyhanitabar, Rogaway and
Vizár](https://eprint.iacr.org/2015/189.pdf).
Minimal properties:
- _plaintext_ can have arbitrary length within the range 0..2<sup>38</sup>
and _associated data_ can have arbitrary length within the range
0..2<sup>31</sup>-1 bytes
- CCA2 security
- at least 80-bit authentication strength
- there are no secrecy or knowledge guarantees wrt. to the value of _associated
data_
- can encrypt at least 2<sup>32</sup> messages with a total of 2<sup>68</sup>
bytes so that no attack with up to 2<sup>32</sup> chosen plaintexts/chosen
ciphertexts has success probability larger than 2<sup>-32</sup>.
## Deterministic Authenticated Encryption with Associated Data
Deterministic AEAD primitive (Deterministic Authenticated Encryption with
Associated Data, DAEAD) provides encryption with a _deterministic property_:
encrypting the same data always yields the same ciphertext. Such encryption is
useful e.g. for key wrapping or for some schemes for searching on encrypted data
(see [RFC 5297, Section 1.3](https://tools.ietf.org/html/rfc5297#section-1.3)
for more info). However, because of deterministic property, implementations of
this primitive are **not semantically secure**.
As for (regular) [AEAD](#authenticated-encryption-with-associated-data), when
using Deterministic AEAD to encrypt a plaintext one can optionally provide
_associated data_ that should be authenticated but not encrypted. That is, the
encryption with associated data ensures authenticity (ie. who the sender is) and
integrity (ie. data has not been tampered with) of that data, but not its
secrecy (see [RFC 5116](https://tools.ietf.org/html/rfc5116)).
Minimal properties:
- _plaintext_ and _associated data_ can have arbitrary length
(within the range 0..2<sup>32</sup> bytes)
- 128-bit security level against multi-user attacks with up to 2<sup>32</sup>
keys; that means if an adversary obtains 2<sup>32</sup> ciphertexts of the
same message encrypted under 2<sup>32</sup> keys, they need to do
2<sup>128</sup> computations to obtain a single key.
- at least 80-bit authentication strength
- there are no secrecy or knowledge guarantees wrt. to the value of _associated
data_
## Message Authentication Code
MAC primitive (Message Authentication Code) provides symmetric message
authentication. A sender sharing a _symmetric key_ with a recipient can compute
an _authentication tag_ for a given message, that allows for verifying that the
message comes from the sender and that it has not been modified. Instances of
MAC primitive are secure against existential forgery under chosen plaintext
attack, and can be deterministic or randomized. This interface should be used
for authentication only, and not for other purposes like generation of
pseudorandom bytes.
Minimal properties:
- secure against existential forgery under CPA
- at least 128-bit security, also in multi-user scenarios (when an attacker is
not targeting a specific key, but any key from a set of up to 2<sup>32</sup>
keys)
- at least 80-bit authentication strength
## Pseudo Random Function Families
The PRF set primitive allows to redact data in a deterministic fashion, for
example personal identifiable information or internal IDs, or to come up with a
user ID from user information without revealing said information in the ID. This
allows someone with access to the output of the PRF without access to the key do
some types of analysis, while limiting others.
Note that while in theory PRFs can be used in other ways, for example for
encryption or message authentication, the corresponding primitives should only
be used for these use cases.
WARNING: Since PRFs operate deterministically on their input, using a PRF to
redact will not automatically provide anonymity, but only provide pseudonymity.
It is an important tool to build privacy aware systems, but has to be used
carefully.
Minimal properties:
- without knowledge of the key the PRF is indistinguishable from a random
function
- at least 128-bit security, also in multi-user scenarios (when an attacker is
not targeting a specific key, but any key from a set of up to 2<sup>32</sup>
keys)
- at least 16 byte of output available
WARNING: While HMAC-SHA-2 and HKDF-SHA-2 behave like a cryptographically secure
hash function if the key is revealed, and still provide some protection against
revealing the input, AES-CMAC is only secure as long as the key is secure.
Since Tink operates on key sets, this primitive exposes a corresponding set of
PRFs instead of a single PRF. The PRFs are indexed by a 32 bit key id. This can
be used to rotate the key used to redact a piece of information, without losing
the previous association.
## Hybrid Encryption
Hybrid Encryption combines the efficiency of symmetric encryption with the
convenience of public-key encryption: to encrypt a message a fresh symmetric key
is generated and used to encrypt the actual plaintext data, while the
recipients public key is used to encrypt the symmetric key only, and the final
ciphertext consists of the symmetric ciphertext and the encrypted symmetric
key.
**WARNING** Hybrid Encryption does not provide authenticity, that is the
recipient of an encrypted message does not know the identity of the sender.
Similar to general public-key encryption schemes the security goal of Hybrid
Encryption is to provide privacy only. In other words, Hybrid Encryption is
secure if and only if the recipient can accept anonymous messages or can rely
on other mechanism to authenticate the sender.
The functionality of Hybrid Encryption is represented in Tink as a pair of
primitives: HybridEncrypt for encryption of data, and HybridDecrypt for
decryption. Implementations of these primitives are secure against adaptive
chosen ciphertext attacks.
In addition to the plaintext encryption accepts an extra parameter _context
info_, which usually is public data implicit from the context, but should be
bound to the resulting ciphertext, i.e. the ciphertext allows for checking the
integrity of _context info_ but there are no guarantees wrt. to secrecy or
authenticity of _context info_. The actual _context info_ can be empty or null,
but to ensure the correct decryption of the resulting ciphertext the same value
must be provided for decryption operation.
A concrete implementation of hybrid encryption can implement the binding of
_context info_ to the ciphertext in various ways, for example:
- use context\_info as "associated data"-input for the employed AEAD symmetric
encryption (cf. [RFC 5116](https://tools.ietf.org/html/rfc5116)).
- use context\_info as "CtxInfo"-input for HKDF (if the implementation uses HKDF
as key derivation function, cf.
[RFC 5869](https://tools.ietf.org/html/rfc5869)).
Furthermore, the DataEncapsulationMechanism can be achieved using either an Aead
primitive or a Determinisitic Aead.
Minimal properties:
- _plaintext_ and _context info_ can have arbitrary length
(within the range 0..2<sup>32</sup> bytes)
- secure against chosen ciphertext attacks
- 128-bit security for EC based schemes,
112-bit security for RSA based schemes (i.e. allow 2048 bit keys)
## Digital Signatures
Digital Signatures provide functionality of signing data and verification of
signatures. It ensures the authenticity and the integrity of the signed data,
but not its secrecy.
The functionality of Digital Signatures is represented in Tink as a pair of
primitives: PublicKeySign for signing of data, and PublicKeyVerify for
verification of signatures. Implementations of these primitives are secure
against adaptive chosen-message attacks.
Minimal properties:
- data to be signed can have arbitrary length
- 128-bit security for EC based schemes
- 112-bit security for RSA based schemes (i.e. allow 2048 bit keys)