tink

Documentation

Overview

Package tink provides the abstract interfaces of the primitives which Tink supports.

Index

• Constants
• type AEAD
• type DeterministicAEAD
• type HybridDecrypt
• type HybridEncrypt
• type MAC
• type Signer
• type StreamingAEAD
• type Verifier

Constants

const (
	// Version is the current version of Tink.
	Version = "1.6.1"
)

Types

type AEAD

type AEAD interface {
	// Encrypt encrypts plaintext with additionalData as additional
	// authenticated data. The resulting ciphertext allows for checking
	// authenticity and integrity of additional data additionalData,
	// but there are no guarantees wrt. secrecy of that data.
	Encrypt(plaintext, additionalData []byte) ([]byte, error)

	// Decrypt decrypts ciphertext with {@code additionalData} as additional
	// authenticated data. The decryption verifies the authenticity and integrity
	// of the additional data, but there are no guarantees wrt. secrecy of that data.
	Decrypt(ciphertext, additionalData []byte) ([]byte, error)
}

AEAD is the interface for authenticated encryption with additional authenticated data. Implementations of this interface are secure against adaptive chosen ciphertext attacks. Encryption with additional data ensures authenticity and integrity of that data, but not its secrecy. (see RFC 5116, https://tools.ietf.org/html/rfc5116)

type DeterministicAEAD

type DeterministicAEAD interface {
	// EncryptDeterministically deterministically encrypts plaintext with additionalData as
	// additional authenticated data. The resulting ciphertext allows for checking
	// authenticity and integrity of additional data additionalData,
	// but there are no guarantees wrt. secrecy of that data.
	EncryptDeterministically(plaintext, additionalData []byte) ([]byte, error)

	// DecryptDeterministically deterministically decrypts ciphertext with additionalData as
	// additional authenticated data. The decryption verifies the authenticity and integrity
	// of the additional data, but there are no guarantees wrt. secrecy of that data.
	DecryptDeterministically(ciphertext, additionalData []byte) ([]byte, error)
}

DeterministicAEAD is the interface for deterministic authenticated encryption with associated data.

Warning: Unlike AEAD, implementations of this interface are not semantically secure, because encrypting the same plaintext always yields the same ciphertext.

Security guarantees: Implementations of this interface provide 128-bit security level against multi-user attacks with up to 2^32 keys. That means if an adversary obtains 2^32 ciphertexts of the same message encrypted under 2^32 keys, they need to do 2^128 computations to obtain a single key.

Encryption with associated data ensures authenticity (who the sender is) and integrity (the data has not been tampered with) of that data, but not its secrecy.

References: https://tools.ietf.org/html/rfc5116 https://tools.ietf.org/html/rfc5297#section-1.3

type HybridDecrypt

type HybridDecrypt interface {
	/**
	 * Decrypt operation: decrypts ciphertext verifying the integrity of contextInfo.
	 * returns resulting plaintext
	 */
	Decrypt(ciphertext, contextInfo []byte) ([]byte, error)
}

HybridDecrypt Interface for hybrid decryption.

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 recipient’s 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 mechanisms to authenticate the sender.

Security guarantees

The functionality of Hybrid Encryption is represented as a pair of primitives (interfaces): HybridEncrypt for encryption of data, and HybridDecrypt for decryption. Implementations of these interfaces are secure against adaptive chosen ciphertext attacks. In addition to plaintext the encryption takes an extra parameter contextInfo, 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 contextInfo (but there are no guarantees wrt. the secrecy or authenticity of contextInfo).

contextInfo can be empty or null, but to ensure the correct decryption of a ciphertext the same value must be provided for the decryption operation as was used during encryption (HybridEncrypt).

A concrete instantiation of this interface can implement the binding of contextInfo to the ciphertext in various ways, for example:

use contextInfo as "associated data"-input for the employed AEAD symmetric
    encryption (cf. https://tools.ietf.org/html/rfc5116).
use contextInfo as "CtxInfo"-input for HKDF (if the implementation uses HKDF as key
    derivation function, cf. https://tools.ietf.org/html/rfc5869).

type HybridEncrypt

type HybridEncrypt interface {
	// Encrypt operation: encrypts plaintext} binding contextInfo to the resulting
	// ciphertext. Returns resulting ciphertext
	Encrypt(plaintext, contextInfo []byte) ([]byte, error)
}

HybridEncrypt is the Interface for 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 recipient’s 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 mechanisms to authenticate the sender.

Security guarantees

The functionality of Hybrid Encryption is represented as a pair of primitives (interfaces): HybridEncrypt for encryption of data, and HybridDecrypt for decryption. Implementations of these interfaces are secure against adaptive chosen ciphertext attacks. In addition to plaintext the encryption takes an extra parameter contextInfo, 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 contextInfo (but there are no guarantees wrt. the secrecy or authenticity of contextInfo).

contextInfo can be empty or null, but to ensure the correct decryption of a ciphertext the same value must be provided for the decryption operation as was used during encryption (cf. HybridEncrypt).

A concrete instantiation of this interface can implement the binding of contextInfo to the ciphertext in various ways, for example:

use contextInfo as "associated data"-input for the employed AEAD symmetric
    encryption (cf. https://tools.ietf.org/html/rfc5116).
use contextInfo as "CtxInfo"-input for HKDF (if the implementation uses HKDF as key
    derivation function, cf. https://tools.ietf.org/html/rfc5869).

type MAC

type MAC interface {

	// ComputeMAC computes message authentication code (MAC) for code data.
	ComputeMAC(data []byte) ([]byte, error)

	// Verify returns nil if mac is a correct authentication code (MAC) for data,
	// otherwise it returns an error.
	VerifyMAC(mac, data []byte) error
}

MAC is the interface for MACs (Message Authentication Codes). This interface should be used for authentication only, and not for other purposes (for example, it should not be used to generate pseudorandom bytes).

type Signer

type Signer interface {
	// Computes the digital signature for data.
	Sign(data []byte) ([]byte, error)
}

Signer is the signing interface for digital signature.

Implementations of this interface are secure against adaptive chosen-message attacks. Signing data ensures authenticity and integrity of that data, but not its secrecy.

type StreamingAEAD

type StreamingAEAD interface {
	// NewEncryptingWriter returns a wrapper around underlying io.Writer, such that any write-operation
	// via the wrapper results in AEAD-encryption of the written data, using aad
	// as associated authenticated data. The associated data is not included in the ciphertext
	// and has to be passed in as parameter for decryption.
	NewEncryptingWriter(w io.Writer, aad []byte) (io.WriteCloser, error)

	// NewDecryptingReader returns a wrapper around underlying io.Reader, such that any read-operation
	// via the wrapper results in AEAD-decryption of the underlying ciphertext,
	// using aad as associated authenticated data.
	NewDecryptingReader(r io.Reader, aad []byte) (io.Reader, error)
}

StreamingAEAD is an interface for streaming authenticated encryption with associated data.

Streaming encryption is typically used for encrypting large plaintexts such as large files. Tink may eventually contain multiple interfaces for streaming encryption depending on the supported properties. This interface supports a streaming interface for symmetric encryption with authentication. The underlying encryption modes are selected so that partial plaintext can be obtained fast by decrypting and authenticating just a part of the ciphertext.

Instances of StreamingAead must follow the OAE2 definition as 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

type Verifier

type Verifier interface {
	// Verifies returns nil if signature is a valid signature for data; otherwise returns an error.
	Verify(signature, data []byte) error
}

Verifier is the verifying interface for digital signature.

Implementations of this interface are secure against adaptive chosen-message attacks. Signing data ensures authenticity and integrity of that data, but not its secrecy.