Documentation ¶
Overview ¶
Package aead provides implementations of the AEAD primitive.
AEAD encryption assures the confidentiality and authenticity of the data. This primitive is CPA secure.
Example ¶
package main import ( "bytes" "fmt" "log" "github.com/tink-crypto/tink-go/v2/aead" "github.com/tink-crypto/tink-go/v2/insecurecleartextkeyset" "github.com/tink-crypto/tink-go/v2/keyset" ) func main() { // A keyset created with "tinkey create-keyset --key-template=AES256_GCM". Note // that this keyset has the secret key information in cleartext. jsonKeyset := `{ "key": [{ "keyData": { "keyMaterialType": "SYMMETRIC", "typeUrl": "type.googleapis.com/google.crypto.tink.AesGcmKey", "value": "GiBWyUfGgYk3RTRhj/LIUzSudIWlyjCftCOypTr0jCNSLg==" }, "keyId": 294406504, "outputPrefixType": "TINK", "status": "ENABLED" }], "primaryKeyId": 294406504 }` // Create a keyset handle from the cleartext keyset in the previous // step. The keyset handle provides abstract access to the underlying keyset to // limit the exposure of accessing the raw key material. WARNING: In practice, // it is unlikely you will want to use a insecurecleartextkeyset, as it implies // that your key material is passed in cleartext, which is a security risk. // Consider encrypting it with a remote key in Cloud KMS, AWS KMS or HashiCorp Vault. // See https://github.com/google/tink/blob/master/docs/GOLANG-HOWTO.md#storing-and-loading-existing-keysets. keysetHandle, err := insecurecleartextkeyset.Read( keyset.NewJSONReader(bytes.NewBufferString(jsonKeyset))) if err != nil { log.Fatal(err) } // Retrieve the AEAD primitive we want to use from the keyset handle. primitive, err := aead.New(keysetHandle) if err != nil { log.Fatal(err) } // Use the primitive to encrypt a message. In this case the primary key of the // keyset will be used (which is also the only key in this example). plaintext := []byte("message") associatedData := []byte("associated data") ciphertext, err := primitive.Encrypt(plaintext, associatedData) if err != nil { log.Fatal(err) } // Use the primitive to decrypt the message. Decrypt finds the correct key in // the keyset and decrypts the ciphertext. If no key is found or decryption // fails, it returns an error. decrypted, err := primitive.Decrypt(ciphertext, associatedData) if err != nil { log.Fatal(err) } fmt.Println(string(decrypted)) }
Output: message
Example (KmsEnvelopeAEAD) ¶
package main // [START kms-envelope-aead-example] import ( "fmt" "log" "github.com/tink-crypto/tink-go/v2/aead" "github.com/tink-crypto/tink-go/v2/testing/fakekms" ) // The fake KMS should only be used in tests. It is not secure. const keyURI = "fake-kms://CM2b3_MDElQKSAowdHlwZS5nb29nbGVhcGlzLmNvbS9nb29nbGUuY3J5cHRvLnRpbmsuQWVzR2NtS2V5EhIaEIK75t5L-adlUwVhWvRuWUwYARABGM2b3_MDIAE" func main() { // Get a KEK (key encryption key) AEAD. This is usually a remote AEAD to a KMS. In this example, // we use a fake KMS to avoid making RPCs. client, err := fakekms.NewClient(keyURI) if err != nil { log.Fatal(err) } kekAEAD, err := client.GetAEAD(keyURI) if err != nil { log.Fatal(err) } // Get the KMS envelope AEAD primitive. primitive := aead.NewKMSEnvelopeAEAD2(aead.AES256GCMKeyTemplate(), kekAEAD) // Use the primitive. plaintext := []byte("message") associatedData := []byte("example KMS envelope AEAD encryption") ciphertext, err := primitive.Encrypt(plaintext, associatedData) if err != nil { log.Fatal(err) } decrypted, err := primitive.Decrypt(ciphertext, associatedData) if err != nil { log.Fatal(err) } fmt.Println(string(decrypted)) } // [END kms-envelope-aead-example]
Output: message
Index ¶
- func AES128CTRHMACSHA256KeyTemplate() *tinkpb.KeyTemplate
- func AES128GCMKeyTemplate() *tinkpb.KeyTemplate
- func AES128GCMSIVKeyTemplate() *tinkpb.KeyTemplate
- func AES256CTRHMACSHA256KeyTemplate() *tinkpb.KeyTemplate
- func AES256GCMKeyTemplate() *tinkpb.KeyTemplate
- func AES256GCMNoPrefixKeyTemplate() *tinkpb.KeyTemplate
- func AES256GCMSIVKeyTemplate() *tinkpb.KeyTemplate
- func AES256GCMSIVNoPrefixKeyTemplate() *tinkpb.KeyTemplate
- func ChaCha20Poly1305KeyTemplate() *tinkpb.KeyTemplate
- func CreateKMSEnvelopeAEADKeyTemplate(uri string, dekTemplate *tinkpb.KeyTemplate) (*tinkpb.KeyTemplate, error)deprecated
- func KMSEnvelopeAEADKeyTemplate(uri string, dekTemplate *tinkpb.KeyTemplate) *tinkpb.KeyTemplatedeprecated
- func New(handle *keyset.Handle) (tink.AEAD, error)
- func XChaCha20Poly1305KeyTemplate() *tinkpb.KeyTemplate
- type KMSEnvelopeAEAD
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func AES128CTRHMACSHA256KeyTemplate ¶
func AES128CTRHMACSHA256KeyTemplate() *tinkpb.KeyTemplate
AES128CTRHMACSHA256KeyTemplate is a KeyTemplate that generates an AES-CTR-HMAC-AEAD key with the following parameters:
- AES key size: 16 bytes
- AES CTR IV size: 16 bytes
- HMAC key size: 32 bytes
- HMAC tag size: 16 bytes
- HMAC hash function: SHA256
func AES128GCMKeyTemplate ¶
func AES128GCMKeyTemplate() *tinkpb.KeyTemplate
AES128GCMKeyTemplate is a KeyTemplate that generates an AES-GCM key with the following parameters:
- Key size: 16 bytes
- Output prefix type: TINK
func AES128GCMSIVKeyTemplate ¶
func AES128GCMSIVKeyTemplate() *tinkpb.KeyTemplate
AES128GCMSIVKeyTemplate is a KeyTemplate that generates an AES-GCM-SIV key with the following parameters:
- Key size: 16 bytes
- Output prefix type: TINK
func AES256CTRHMACSHA256KeyTemplate ¶
func AES256CTRHMACSHA256KeyTemplate() *tinkpb.KeyTemplate
AES256CTRHMACSHA256KeyTemplate is a KeyTemplate that generates an AES-CTR-HMAC-AEAD key with the following parameters:
- AES key size: 32 bytes
- AES CTR IV size: 16 bytes
- HMAC key size: 32 bytes
- HMAC tag size: 32 bytes
- HMAC hash function: SHA256
func AES256GCMKeyTemplate ¶
func AES256GCMKeyTemplate() *tinkpb.KeyTemplate
AES256GCMKeyTemplate is a KeyTemplate that generates an AES-GCM key with the following parameters:
- Key size: 32 bytes
- Output prefix type: TINK
func AES256GCMNoPrefixKeyTemplate ¶
func AES256GCMNoPrefixKeyTemplate() *tinkpb.KeyTemplate
AES256GCMNoPrefixKeyTemplate is a KeyTemplate that generates an AES-GCM key with the following parameters:
- Key size: 32 bytes
- Output prefix type: RAW
func AES256GCMSIVKeyTemplate ¶
func AES256GCMSIVKeyTemplate() *tinkpb.KeyTemplate
AES256GCMSIVKeyTemplate is a KeyTemplate that generates an AES-GCM-SIV key with the following parameters:
- Key size: 32 bytes
- Output prefix type: TINK
func AES256GCMSIVNoPrefixKeyTemplate ¶
func AES256GCMSIVNoPrefixKeyTemplate() *tinkpb.KeyTemplate
AES256GCMSIVNoPrefixKeyTemplate is a KeyTemplate that generates an AES-GCM key with the following parameters:
- Key size: 32 bytes
- Output prefix type: RAW
func ChaCha20Poly1305KeyTemplate ¶
func ChaCha20Poly1305KeyTemplate() *tinkpb.KeyTemplate
ChaCha20Poly1305KeyTemplate is a KeyTemplate that generates a CHACHA20_POLY1305 key.
func CreateKMSEnvelopeAEADKeyTemplate
deprecated
func CreateKMSEnvelopeAEADKeyTemplate(uri string, dekTemplate *tinkpb.KeyTemplate) (*tinkpb.KeyTemplate, error)
CreateKMSEnvelopeAEADKeyTemplate returns a key template that generates a KMSEnvelopeAEAD key for a given key encryption key (KEK) in a remote key management service (KMS).
When performing encrypt operations, a data encryption key (DEK) is generated for each ciphertext. The DEK is wrapped by the remote KMS using the KEK and stored alongside the ciphertext.
dekTemplate must be a KeyTemplate for any of these Tink AEAD key types (any other key template will be rejected):
- AesCtrHmacAeadKey
- AesGcmKey
- ChaCha20Poly1305Key
- XChaCha20Poly1305
- AesGcmSivKey
DEKs generated by this key template use the RAW output prefix to make them compatible with remote KMS encrypt/decrypt operations.
Unlike other templates, when you generate new keys with this template, Tink does not generate new key material, but only creates a reference to the remote KEK.
If either uri or dekTemplate contain invalid input, an error is returned.
Deprecated: Instead, call kmsClient.GetAEAD to get a remote AEAD, create an envelope AEAD using aead.NewKMSEnvelopeAEAD2. There is no need to call registry.RegisterKMSClient anymore.
func KMSEnvelopeAEADKeyTemplate
deprecated
func KMSEnvelopeAEADKeyTemplate(uri string, dekTemplate *tinkpb.KeyTemplate) *tinkpb.KeyTemplate
KMSEnvelopeAEADKeyTemplate returns a KeyTemplate that generates a KMSEnvelopeAEAD key for a given key encryption key (KEK) in a remote key management service (KMS).
If either uri or dekTemplate contain invalid input, program execution will be interrupted.
Deprecated: Use CreateKMSEnvelopeAEADKeyTemplate, which returns an error value instead of interrupting the program.
func XChaCha20Poly1305KeyTemplate ¶
func XChaCha20Poly1305KeyTemplate() *tinkpb.KeyTemplate
XChaCha20Poly1305KeyTemplate is a KeyTemplate that generates a XCHACHA20_POLY1305 key.
Types ¶
type KMSEnvelopeAEAD ¶
type KMSEnvelopeAEAD struct {
// contains filtered or unexported fields
}
KMSEnvelopeAEAD represents an instance of Envelope AEAD.
func NewKMSEnvelopeAEAD2 ¶
func NewKMSEnvelopeAEAD2(dekTemplate *tinkpb.KeyTemplate, remote tink.AEAD) *KMSEnvelopeAEAD
NewKMSEnvelopeAEAD2 creates an new instance of KMSEnvelopeAEAD.
dekTemplate must be a KeyTemplate for any of these Tink AEAD key types (any other key template will be rejected):
- AesCtrHmacAeadKey
- AesGcmKey
- ChaCha20Poly1305Key
- XChaCha20Poly1305
- AesGcmSivKey
Source Files ¶
Directories ¶
Path | Synopsis |
---|---|
internal
|
|
testing/kmsaead
Package kmsaead provides a keymanager for KmsAeadKey that may only be used in tests.
|
Package kmsaead provides a keymanager for KmsAeadKey that may only be used in tests. |
Package subtle provides subtle implementations of the AEAD primitive.
|
Package subtle provides subtle implementations of the AEAD primitive. |