s3crypto

package
v1.38.64 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jun 17, 2021 License: Apache-2.0 Imports: 27 Imported by: 19

Documentation

Overview

Package s3crypto provides encryption to S3 using KMS and AES GCM.

Keyproviders are interfaces that handle masterkeys. Masterkeys are used to encrypt and decrypt the randomly generated cipher keys. The SDK currently uses KMS to do this. A user does not need to provide a master key since all that information is hidden in KMS.

Modes are interfaces that handle content encryption and decryption. It is an abstraction layer that instantiates the ciphers. If content is being encrypted we generate the key and iv of the cipher. For decryption, we use the metadata stored either on the object or an instruction file object to decrypt the contents.

Ciphers are interfaces that handle encryption and decryption of data. This may be key wrap ciphers or content ciphers.

Creating an S3 cryptography client

cmkID := "<some key ID>"
sess := session.Must(session.NewSession())
kmsClient := kms.New(sess)
// Create the KeyProvider
var matdesc s3crypto.MaterialDescription
handler := s3crypto.NewKMSContextKeyGenerator(kmsClient, cmkID, matdesc)

// Create an encryption and decryption client
// We need to pass the session here so S3 can use it. In addition, any decryption that
// occurs will use the KMS client.
svc, err := s3crypto.NewEncryptionClientV2(sess, s3crypto.AESGCMContentCipherBuilderV2(handler))
if err != nil {
	panic(err) // handle error
}

// Create a CryptoRegistry and register the algorithms you wish to use for decryption
cr := s3crypto.NewCryptoRegistry()

if err := s3crypto.RegisterAESGCMContentCipher(cr); err != nil {
	panic(err) // handle error
}

if err := s3crypto.RegisterKMSContextWrapWithAnyCMK(cr, kmsClient); err != nil {
	panic(err) // handle error
}

// Create a decryption client to decrypt artifacts
svc, err := s3crypto.NewDecryptionClientV2(sess, cr)
if err != nil {
	panic(err) // handle error
}

Configuration of the S3 cryptography client

sess := session.Must(session.NewSession())
handler := s3crypto.NewKMSContextKeyGenerator(kms.New(sess), cmkID, s3crypto.MaterialDescription{})
svc, err := s3crypto.NewEncryptionClientV2(sess, s3crypto.AESGCMContentCipherBuilderV2(handler), func (o *s3crypto.EncryptionClientOptions) {
	// Save instruction files to separate objects
	o.SaveStrategy = NewS3SaveStrategy(sess, "")

	// Change instruction file suffix to .example
	o.InstructionFileSuffix = ".example"

	// Set temp folder path
	o.TempFolderPath = "/path/to/tmp/folder/"

	// Any content less than the minimum file size will use memory
	// instead of writing the contents to a temp file.
	o.MinFileSize = int64(1024 * 1024 * 1024)
})
if err != nil {
	panic(err) // handle error
}

Object Metadata SaveStrategy

The default SaveStrategy is to save metadata to an object's headers. An alternative SaveStrategy can be provided to the EncryptionClientV2. For example, the S3SaveStrategy can be used to save the encryption metadata to a instruction file that is stored in S3 using the objects KeyName+InstructionFileSuffix. The InstructionFileSuffix defaults to .instruction. If using this strategy you will need to configure the DecryptionClientV2 to use the matching S3LoadStrategy LoadStrategy in order to decrypt object using this save strategy.

Custom Key Wrappers and Custom Content Encryption Algorithms

Registration of custom key wrapping or content encryption algorithms not provided by AWS is allowed by the SDK, but security and compatibility with custom types can not be guaranteed. For example if you want to support `CustomWrap` key wrapping algorithm and `CustomCEK` content encryption algorithm. You can use the CryptoRegistry to register these types.

cr := s3crypto.NewCryptoRegistry()

// Register a custom key wrap algorithm to the CryptoRegistry
if err := cr.AddWrap("CustomWrap", NewCustomWrapEntry); err != nil {
	panic(err) // handle error
}

// Register a custom content encryption algorithm to the CryptoRegistry
if err := cr.AddCEK("CustomCEK", NewCustomCEKEntry); err != nil {
	panic(err) // handle error
}

svc, err := s3crypto.NewDecryptionClientV2(sess, cr)
if err != nil {
	panic(err) // handle error
}

We have now registered these new algorithms to the decryption client. When the client calls `GetObject` and sees the wrap as `CustomWrap` then it'll use that wrap algorithm. This is also true for `CustomCEK`.

For encryption adding a custom content cipher builder and key handler will allow for encryption of custom defined ciphers.

// Our wrap algorithm, CustomWrap
handler := NewCustomWrap(key, iv)
// Our content cipher builder, NewCustomCEKContentBuilder
svc := s3crypto.NewEncryptionClientV2(sess, NewCustomCEKContentBuilder(handler))

Maintenance Mode Notification for V1 Clients

The EncryptionClient and DecryptionClient are in maintenance mode, no new updates will be released. Please see https://docs.aws.amazon.com/general/latest/gr/aws_sdk_cryptography.html for more information. Users of these clients should migrate to EncryptionClientV2 and DecryptionClientV2.

EncryptionClientV2 removes encryption support of the following features

  • AES/CBC (content cipher)
  • kms (key wrap algorithm)

Attempting to construct an EncryptionClientV2 with deprecated features will result in an error returned back to the calling application during construction of the client.

Users of `AES/CBC` will need to migrate usage to `AES/GCM`. Users of `kms` key provider will need to migrate `kms+context`.

DecryptionClientV2 client adds support for the `kms+context` key provider and maintains backwards comparability with objects encrypted with the V1 EncryptionClient.

Migrating from V1 to V2 Clients

Examples of how to migrate usage of the V1 clients to the V2 equivalents have been documented as usage examples of the NewEncryptionClientV2 and NewDecryptionClientV2 functions.

Please see the AWS SDK for Go Developer Guide for additional migration steps https://docs.aws.amazon.com/sdk-for-go/v1/developer-guide/s3-encryption-migration.html

Index

Examples

Constants

View Source
const AESCBC = "AES/CBC"

AESCBC is the string constant that signifies the AES CBC algorithm cipher.

View Source
const AESGCMNoPadding = "AES/GCM/NoPadding"

AESGCMNoPadding is the constant value that is used to specify the cek algorithm consiting of AES GCM with no padding.

View Source
const DefaultInstructionKeySuffix = ".instruction"

DefaultInstructionKeySuffix is appended to the end of the instruction file key when grabbing or saving to S3

View Source
const DefaultMinFileSize = 1024 * 512 * 5

DefaultMinFileSize is used to check whether we want to write to a temp file or store the data in memory.

View Source
const (
	// KMSContextWrap is a constant used during decryption to build a kms+context key handler
	KMSContextWrap = "kms+context"
)
View Source
const (
	// KMSWrap is a constant used during decryption to build a KMS key handler.
	KMSWrap = "kms"
)

Variables

View Source
var AESCBCPadder = Padder(aescbcPadding)

AESCBCPadder is used to pad AES encrypted and decrypted data. Although it uses the pkcs5Padder, it isn't following the RFC for PKCS5. The only reason why it is called pkcs5Padder is due to the Name returning PKCS5Padding.

View Source
var NoPadder = Padder(noPadder{})

NoPadder does not pad anything

Functions

func RegisterAESCBCContentCipher added in v1.34.0

func RegisterAESCBCContentCipher(registry *CryptoRegistry, padder Padder) error

RegisterAESCBCContentCipher registers the AES/CBC cipher and padder with the provided CryptoRegistry.

Example:

cr := s3crypto.NewCryptoRegistry()
if err := s3crypto.RegisterAESCBCContentCipher(cr, s3crypto.AESCBCPadder); err != nil {
	panic(err) // handle error
}

deprecated: This feature is in maintenance mode, no new updates will be released. Please see https://docs.aws.amazon.com/general/latest/gr/aws_sdk_cryptography.html for more information.

func RegisterAESGCMContentCipher added in v1.34.0

func RegisterAESGCMContentCipher(registry *CryptoRegistry) error

RegisterAESGCMContentCipher registers the AES/GCM content cipher algorithm with the provided CryptoRegistry.

Example:

cr := s3crypto.NewCryptoRegistry()
if err := s3crypto.RegisterAESGCMContentCipher(cr); err != nil {
	panic(err) // handle error
}

func RegisterKMSContextWrapWithAnyCMK added in v1.34.0

func RegisterKMSContextWrapWithAnyCMK(registry *CryptoRegistry, client kmsiface.KMSAPI) error

RegisterKMSContextWrapWithAnyCMK registers the kms+context wrapping algorithm to the given WrapRegistry. The wrapper will be configured to call KMS decrypt without providing a CMK.

Example:

sess := session.Must(session.NewSession())
cr := s3crypto.NewCryptoRegistry()
if err := s3crypto.RegisterKMSContextWrapWithAnyCMK(cr, kms.New(sess)); err != nil {
	panic(err) // handle error
}

func RegisterKMSContextWrapWithCMK added in v1.34.0

func RegisterKMSContextWrapWithCMK(registry *CryptoRegistry, client kmsiface.KMSAPI, cmkID string) error

RegisterKMSContextWrapWithCMK registers the kms+context wrapping algorithm to the given WrapRegistry. The wrapper will be configured to only call KMS Decrypt using the provided CMK.

Example:

cr := s3crypto.NewCryptoRegistry()
if err := RegisterKMSContextWrapWithCMK(); err != nil {
	panic(err) // handle error
}

func RegisterKMSWrapWithAnyCMK added in v1.34.0

func RegisterKMSWrapWithAnyCMK(registry *CryptoRegistry, client kmsiface.KMSAPI) error

RegisterKMSWrapWithAnyCMK registers the `kms` wrapping algorithm to the given WrapRegistry. The wrapper will be configured to call KMS Decrypt without providing a CMK.

Example:

sess := session.Must(session.NewSession())
cr := s3crypto.NewCryptoRegistry()
if err := s3crypto.RegisterKMSWrapWithAnyCMK(cr, kms.New(sess)); err != nil {
	panic(err) // handle error
}

deprecated: This feature is in maintenance mode, no new updates will be released. Please see https://docs.aws.amazon.com/general/latest/gr/aws_sdk_cryptography.html for more information.

func RegisterKMSWrapWithCMK added in v1.34.0

func RegisterKMSWrapWithCMK(registry *CryptoRegistry, client kmsiface.KMSAPI, cmkID string) error

RegisterKMSWrapWithCMK registers the `kms` wrapping algorithm to the given WrapRegistry. The wrapper will be configured to call KMS Decrypt with the provided CMK.

Example:

sess := session.Must(session.NewSession())
cr := s3crypto.NewCryptoRegistry()
if err := s3crypto.RegisterKMSWrapWithCMK(cr, kms.New(sess), "cmkId"); err != nil {
	panic(err) // handle error
}

deprecated: This feature is in maintenance mode, no new updates will be released. Please see https://docs.aws.amazon.com/general/latest/gr/aws_sdk_cryptography.html for more information.

Types

type CEKEntry

type CEKEntry func(CipherData) (ContentCipher, error)

CEKEntry is a builder that returns a proper content decrypter and error

type Cipher

type Cipher interface {
	Encrypter
	Decrypter
}

Cipher interface allows for either encryption and decryption of an object

type CipherData

type CipherData struct {
	Key                 []byte
	IV                  []byte
	WrapAlgorithm       string
	CEKAlgorithm        string
	TagLength           string
	MaterialDescription MaterialDescription
	// EncryptedKey should be populated when calling GenerateCipherData
	EncryptedKey []byte

	Padder Padder
}

CipherData is used for content encryption. It is used for storing the metadata of the encrypted content.

func (CipherData) Clone added in v1.34.0

func (cd CipherData) Clone() (v CipherData)

Clone returns a new copy of CipherData

type CipherDataDecrypter

type CipherDataDecrypter interface {
	DecryptKey([]byte) ([]byte, error)
}

CipherDataDecrypter is a handler to decrypt keys from the envelope.

type CipherDataDecrypterWithContext added in v1.28.3

type CipherDataDecrypterWithContext interface {
	DecryptKeyWithContext(aws.Context, []byte) ([]byte, error)
}

CipherDataDecrypterWithContext is a handler to decrypt keys from the envelope with request context.

type CipherDataGenerator

type CipherDataGenerator interface {
	GenerateCipherData(int, int) (CipherData, error)
}

CipherDataGenerator handles generating proper key and IVs of proper size for the content cipher. CipherDataGenerator will also encrypt the key and store it in the CipherData.

func NewKMSKeyGenerator

func NewKMSKeyGenerator(kmsClient kmsiface.KMSAPI, cmkID string) CipherDataGenerator

NewKMSKeyGenerator builds a new KMS key provider using the customer key ID and material description.

Example:

sess := session.Must(session.NewSession())
cmkID := "arn to key"
matdesc := s3crypto.MaterialDescription{}
handler := s3crypto.NewKMSKeyGenerator(kms.New(sess), cmkID)

deprecated: This feature is in maintenance mode, no new updates will be released. Please see https://docs.aws.amazon.com/general/latest/gr/aws_sdk_cryptography.html for more information.

func NewKMSKeyGeneratorWithMatDesc

func NewKMSKeyGeneratorWithMatDesc(kmsClient kmsiface.KMSAPI, cmkID string, matdesc MaterialDescription) CipherDataGenerator

NewKMSKeyGeneratorWithMatDesc builds a new KMS key provider using the customer key ID and material description.

Example:

sess := session.Must(session.NewSession())
cmkID := "arn to key"
matdesc := s3crypto.MaterialDescription{}
handler := s3crypto.NewKMSKeyGeneratorWithMatDesc(kms.New(sess), cmkID, matdesc)

deprecated: This feature is in maintenance mode, no new updates will be released. Please see https://docs.aws.amazon.com/general/latest/gr/aws_sdk_cryptography.html for more information.

type CipherDataGeneratorWithCEKAlg added in v1.33.0

type CipherDataGeneratorWithCEKAlg interface {
	GenerateCipherDataWithCEKAlg(ctx aws.Context, keySize, ivSize int, cekAlgorithm string) (CipherData, error)
}

CipherDataGeneratorWithCEKAlg handles generating proper key and IVs of proper size for the content cipher. CipherDataGenerator will also encrypt the key and store it in the CipherData.

func NewKMSContextKeyGenerator added in v1.33.0

func NewKMSContextKeyGenerator(client kmsiface.KMSAPI, cmkID string, matdesc MaterialDescription) CipherDataGeneratorWithCEKAlg

NewKMSContextKeyGenerator builds a new kms+context key provider using the customer key ID and material description.

Example:

sess := session.Must(session.NewSession())
cmkID := "KMS Key ARN"
var matdesc s3crypto.MaterialDescription
handler := s3crypto.NewKMSContextKeyGenerator(kms.New(sess), cmkID, matdesc)

type CipherDataGeneratorWithContext added in v1.28.3

type CipherDataGeneratorWithContext interface {
	GenerateCipherDataWithContext(aws.Context, int, int) (CipherData, error)
}

CipherDataGeneratorWithContext handles generating proper key and IVs of proper size for the content cipher. CipherDataGenerator will also encrypt the key and store it in the CipherData.

type ContentCipher

type ContentCipher interface {
	EncryptContents(io.Reader) (io.Reader, error)
	DecryptContents(io.ReadCloser) (io.ReadCloser, error)
	GetCipherData() CipherData
}

ContentCipher deals with encrypting and decrypting content

type ContentCipherBuilder

type ContentCipherBuilder interface {
	ContentCipher() (ContentCipher, error)
}

ContentCipherBuilder is a builder interface that builds ciphers for each request.

func AESCBCContentCipherBuilder added in v1.7.9

func AESCBCContentCipherBuilder(generator CipherDataGenerator, padder Padder) ContentCipherBuilder

AESCBCContentCipherBuilder returns a new encryption only AES/CBC mode structure using the provided padder. The provided cipher data generator will be used to provide keys for content encryption.

deprecated: This feature is in maintenance mode, no new updates will be released. Please see https://docs.aws.amazon.com/general/latest/gr/aws_sdk_cryptography.html for more information.

func AESGCMContentCipherBuilder

func AESGCMContentCipherBuilder(generator CipherDataGenerator) ContentCipherBuilder

AESGCMContentCipherBuilder returns a new encryption only AES/GCM mode structure with a specific cipher data generator that will provide keys to be used for content encryption.

Note: This uses the Go stdlib AEAD implementation for AES/GCM. Due to this objects to be encrypted or decrypted will be fully loaded into memory before encryption or decryption can occur. Caution must be taken to avoid memory allocation failures.

deprecated: This feature is in maintenance mode, no new updates will be released. Please see https://docs.aws.amazon.com/general/latest/gr/aws_sdk_cryptography.html for more information.

func AESGCMContentCipherBuilderV2 added in v1.34.0

func AESGCMContentCipherBuilderV2(generator CipherDataGeneratorWithCEKAlg) ContentCipherBuilder

AESGCMContentCipherBuilderV2 returns a new encryption only AES/GCM mode structure with a specific cipher data generator that will provide keys to be used for content encryption. This type is compatible with the V2 encryption client.

Note: This uses the Go stdlib AEAD implementation for AES/GCM. Due to this objects to be encrypted or decrypted will be fully loaded into memory before encryption or decryption can occur. Caution must be taken to avoid memory allocation failures.

type ContentCipherBuilderWithContext added in v1.28.3

type ContentCipherBuilderWithContext interface {
	ContentCipherWithContext(aws.Context) (ContentCipher, error)
}

ContentCipherBuilderWithContext is a builder interface that builds ciphers for each request.

type CryptoReadCloser

type CryptoReadCloser struct {
	Body      io.ReadCloser
	Decrypter io.Reader
	// contains filtered or unexported fields
}

CryptoReadCloser handles closing of the body and allowing reads from the decrypted content.

func (*CryptoReadCloser) Close

func (rc *CryptoReadCloser) Close() error

Close lets the CryptoReadCloser satisfy io.ReadCloser interface

func (*CryptoReadCloser) Read

func (rc *CryptoReadCloser) Read(b []byte) (int, error)

Read lets the CryptoReadCloser satisfy io.ReadCloser interface

type CryptoRegistry added in v1.34.0

type CryptoRegistry struct {
	// contains filtered or unexported fields
}

CryptoRegistry is a collection of registries for configuring a decryption client with different key wrapping algorithms, content encryption algorithms, and padders.

func NewCryptoRegistry added in v1.34.0

func NewCryptoRegistry() *CryptoRegistry

NewCryptoRegistry creates a new CryptoRegistry to which wrapping algorithms, content encryption ciphers, and padders can be registered for use with the DecryptionClientV2.

func (*CryptoRegistry) AddCEK added in v1.34.0

func (c *CryptoRegistry) AddCEK(name string, entry CEKEntry) error

AddCEK registers CEKEntry under the given name, returns an error if a CEKEntry is already present for the given name.

This method should only be used if you need to register custom content encryption algorithms. Please see the following methods for helpers to register AWS provided algorithms:

RegisterAESGCMContentCipher (AES/GCM)
RegisterAESCBCContentCipher (AES/CBC)

func (*CryptoRegistry) AddPadder added in v1.34.0

func (c *CryptoRegistry) AddPadder(name string, padder Padder) error

AddPadder registers Padder under the given name, returns an error if a Padder is already present for the given name.

This method should only be used to register custom padder implementations not provided by AWS.

func (*CryptoRegistry) AddWrap added in v1.34.0

func (c *CryptoRegistry) AddWrap(name string, entry WrapEntry) error

AddWrap registers the provided WrapEntry under the given name, returns an error if a WrapEntry is already present for the given name.

This method should only be used if you need to register custom wrapping algorithms. Please see the following methods for helpers to register AWS provided algorithms:

RegisterKMSContextWrapWithAnyCMK (kms+context)
RegisterKMSContextWrapWithCMK (kms+context)
RegisterKMSWrapWithAnyCMK (kms)
RegisterKMSWrapWithCMK (kms)

func (CryptoRegistry) GetCEK added in v1.34.0

func (c CryptoRegistry) GetCEK(name string) (CEKEntry, bool)

GetCEK returns the CEKEntry identified by the given name. Returns false if the entry is not registered.

func (*CryptoRegistry) GetPadder added in v1.34.0

func (c *CryptoRegistry) GetPadder(name string) (Padder, bool)

GetPadder returns the Padder identified by name. If the Padder is not present, returns false.

func (CryptoRegistry) GetWrap added in v1.34.0

func (c CryptoRegistry) GetWrap(name string) (WrapEntry, bool)

GetWrap returns the WrapEntry identified by the given name. Returns false if the entry is not registered.

func (*CryptoRegistry) RemoveCEK added in v1.34.0

func (c *CryptoRegistry) RemoveCEK(name string) (CEKEntry, bool)

RemoveCEK removes the CEKEntry identified by name. If the entry is not present returns false.

func (*CryptoRegistry) RemovePadder added in v1.34.0

func (c *CryptoRegistry) RemovePadder(name string) (Padder, bool)

RemovePadder removes the Padder identified by name. If the entry is not present returns false.

func (*CryptoRegistry) RemoveWrap added in v1.34.0

func (c *CryptoRegistry) RemoveWrap(name string) (WrapEntry, bool)

RemoveWrap removes the WrapEntry identified by name. If the WrapEntry is not present returns false.

type Decrypter

type Decrypter interface {
	Decrypt(io.Reader) io.Reader
}

Decrypter interface with only the decrypt method

type DecryptionClient

type DecryptionClient struct {
	S3Client s3iface.S3API
	// LoadStrategy is used to load the metadata either from the metadata of the object
	// or from a separate file in s3.
	//
	// Defaults to our default load strategy.
	LoadStrategy LoadStrategy

	WrapRegistry   map[string]WrapEntry
	CEKRegistry    map[string]CEKEntry
	PadderRegistry map[string]Padder
}

DecryptionClient is an S3 crypto client. The decryption client will handle all get object requests from Amazon S3. Supported key wrapping algorithms:

*AWS KMS

Supported content ciphers:

  • AES/GCM
  • AES/CBC

deprecated: This feature is in maintenance mode, no new updates will be released. Please see https://docs.aws.amazon.com/general/latest/gr/aws_sdk_cryptography.html for more information.

func NewDecryptionClient

func NewDecryptionClient(prov client.ConfigProvider, options ...func(*DecryptionClient)) *DecryptionClient

NewDecryptionClient instantiates a new S3 crypto client

Example:

sess := session.Must(session.NewSession())
svc := s3crypto.NewDecryptionClient(sess, func(svc *s3crypto.DecryptionClient{
	// Custom client options here
}))

deprecated: This feature is in maintenance mode, no new updates will be released. Please see https://docs.aws.amazon.com/general/latest/gr/aws_sdk_cryptography.html for more information.

func (*DecryptionClient) GetObject

func (c *DecryptionClient) GetObject(input *s3.GetObjectInput) (*s3.GetObjectOutput, error)

GetObject is a wrapper for GetObjectRequest

deprecated: This feature is in maintenance mode, no new updates will be released. Please see https://docs.aws.amazon.com/general/latest/gr/aws_sdk_cryptography.html for more information.

func (*DecryptionClient) GetObjectRequest

func (c *DecryptionClient) GetObjectRequest(input *s3.GetObjectInput) (*request.Request, *s3.GetObjectOutput)

GetObjectRequest will make a request to s3 and retrieve the object. In this process decryption will be done. The SDK only supports V2 reads of KMS and GCM.

Example:

 sess := session.Must(session.NewSession())
	svc := s3crypto.NewDecryptionClient(sess)
	req, out := svc.GetObjectRequest(&s3.GetObjectInput {
	  Key: aws.String("testKey"),
	  Bucket: aws.String("testBucket"),
	})
	err := req.Send()

deprecated: This feature is in maintenance mode, no new updates will be released. Please see https://docs.aws.amazon.com/general/latest/gr/aws_sdk_cryptography.html for more information.

func (*DecryptionClient) GetObjectWithContext added in v1.8.0

func (c *DecryptionClient) GetObjectWithContext(ctx aws.Context, input *s3.GetObjectInput, opts ...request.Option) (*s3.GetObjectOutput, error)

GetObjectWithContext is a wrapper for GetObjectRequest with the additional context, and request options support.

GetObjectWithContext is the same as GetObject with the additional support for Context input parameters. The Context must not be nil. A nil Context will cause a panic. Use the Context to add deadlining, timeouts, etc. In the future this may create sub-contexts for individual underlying requests.

deprecated: This feature is in maintenance mode, no new updates will be released. Please see https://docs.aws.amazon.com/general/latest/gr/aws_sdk_cryptography.html for more information.

type DecryptionClientOptions added in v1.33.0

type DecryptionClientOptions struct {
	S3Client s3iface.S3API
	// LoadStrategy is used to load the metadata either from the metadata of the object
	// or from a separate file in s3.
	//
	// Defaults to our default load strategy.
	LoadStrategy LoadStrategy

	CryptoRegistry *CryptoRegistry
}

DecryptionClientOptions is the configuration options for DecryptionClientV2.

type DecryptionClientV2 added in v1.33.0

type DecryptionClientV2 struct {
	// contains filtered or unexported fields
}

DecryptionClientV2 is an S3 crypto client. The decryption client will handle all get object requests from Amazon S3. Supported key wrapping algorithms:

  • AWS KMS
  • AWS KMS + Context

Supported content ciphers:

  • AES/GCM
  • AES/CBC

func NewDecryptionClientV2 added in v1.33.0

func NewDecryptionClientV2(
	prov client.ConfigProvider, cryptoRegistry *CryptoRegistry,
	options ...func(clientOptions *DecryptionClientOptions),
) (*DecryptionClientV2, error)

NewDecryptionClientV2 instantiates a new DecryptionClientV2. The NewDecryptionClientV2 must be configured with the desired key wrapping and content encryption algorithms that are required to be read by the client. These algorithms are registered by providing the client a CryptoRegistry that has been constructed with the desired configuration. NewDecryptionClientV2 will return an error if no key wrapping or content encryption algorithms have been provided.

Example:

sess := session.Must(session.NewSession())
cr := s3crypto.NewCryptoRegistry()
if err := s3crypto.RegisterKMSContextWrapWithAnyCMK(cr, kms.New(sess)); err != nil {
	panic(err) // handle error
}
if err := s3crypto.RegisterAESGCMContentCipher(cr); err != nil {
	panic(err) // handle error
}
svc, err := s3crypto.NewDecryptionClientV2(sess, cr, func(o *s3crypto.DecryptionClientOptions) {
	// Custom client options here
})
if err != nil {
	panic(err) // handle error
}
Example (Migration00)

ExampleNewDecryptionClientV2_migration00 provides a migration example for how users can migrate from the V1 Decryption Clients to the V2 Decryption Clients.

package main

import (
	"fmt"
	"io/ioutil"

	"github.com/aws/aws-sdk-go/aws"
	"github.com/aws/aws-sdk-go/aws/session"
	"github.com/aws/aws-sdk-go/service/kms"
	"github.com/aws/aws-sdk-go/service/s3"
	"github.com/aws/aws-sdk-go/service/s3/s3crypto"
)

func main() {
	sess := session.Must(session.NewSession())

	// Construction of an decryption client must be done using NewDecryptionClientV2
	// The V2 decryption client is able to decrypt object encrypted by the V1 client.
	//
	// decryptionClient := s3crypto.NewDecryptionClient(sess)

	// The V2 decryption client requires you to explicitly register the key wrap algorithms and content encryption algorithms
	// that you want to explicitly support decryption for.
	registry := s3crypto.NewCryptoRegistry()

	kmsClient := kms.New(sess)

	// If you need support for unwrapping data keys wrapped using the `kms` wrap algorithm you can use RegisterKMSWrapWithAnyCMK.
	// Alternatively you may use RegisterKMSWrapWithCMK if you wish to limit KMS decrypt calls to a specific CMK.
	if err := s3crypto.RegisterKMSWrapWithAnyCMK(registry, kmsClient); err != nil {
		fmt.Printf("error: %v", err)
		return
	}

	// For unwrapping data keys wrapped using the new `kms+context` key wrap algorithm you can use RegisterKMSContextWrapWithAnyCMK.
	// Alternatively you may use RegisterKMSWrapWithCMK if you wish to limit KMS decrypt calls to a specific CMK.
	if err := s3crypto.RegisterKMSContextWrapWithAnyCMK(registry, kmsClient); err != nil {
		fmt.Printf("error: %v", err)
		return
	}

	// If you need to decrypt objects encrypted using the V1 AES/CBC/PCKS5Padding cipher you can do so with RegisterAESCBCContentCipher
	if err := s3crypto.RegisterAESCBCContentCipher(registry, s3crypto.AESCBCPadder); err != nil {
		fmt.Printf("error: %v", err)
		return
	}

	// For decrypting objects encrypted in V1 or V2 using AES/GCM/NoPadding cipher you can do so with RegisterAESGCMContentCipher.
	if err := s3crypto.RegisterAESGCMContentCipher(registry); err != nil {
		fmt.Printf("error: %v", err)
		return
	}

	// Instantiate a new decryption client, and provided the Wrap, cek, and Padder that have been registered
	// with your desired algorithms.
	decryptionClient, err := s3crypto.NewDecryptionClientV2(sess, registry)
	if err != nil {
		fmt.Printf("error: %v", err)
		return
	}

	getObject, err := decryptionClient.GetObject(&s3.GetObjectInput{
		Bucket: aws.String("your_bucket"),
		Key:    aws.String("your_key"),
	})
	if err != nil {
		fmt.Printf("get object error: %v\n", err)
		return
	}

	_, err = ioutil.ReadAll(getObject.Body)
	if err != nil {
		fmt.Printf("error reading object: %v\n", err)
	}
	fmt.Println("get object completed")
}
Output:

Example (Migration01)

ExampleNewDecryptionClientV2_migration01 provides a more advanced migration example for how users can migrate from the V1 decryption client to the V2 decryption client using more complex client construction.

package main

import (
	"fmt"
	"io/ioutil"

	"github.com/aws/aws-sdk-go/aws"
	"github.com/aws/aws-sdk-go/aws/session"
	"github.com/aws/aws-sdk-go/service/kms"
	"github.com/aws/aws-sdk-go/service/s3"
	"github.com/aws/aws-sdk-go/service/s3/s3crypto"
)

func main() {
	sess := session.Must(session.NewSession())

	// Construction of an decryption client must be done using NewDecryptionClientV2
	// The V2 decryption client is able to decrypt object encrypted by the V1 client.
	//
	// decryptionClient := s3crypto.NewDecryptionClient(sess, func(o *s3crypto.DecryptionClient) {
	//	 o.S3Client = s3.New(sess, &aws.Config{Region: aws.String("us-west-2")})
	//})
	registry := s3crypto.NewCryptoRegistry()

	kmsClient := kms.New(sess)
	if err := s3crypto.RegisterKMSWrapWithAnyCMK(registry, kmsClient); err != nil {
		fmt.Printf("error: %v", err)
		return
	}

	// If you need to decrypt objects encrypted using AES/GCM/NoPadding cipher you can do so with RegisterAESGCMContentCipher
	if err := s3crypto.RegisterAESGCMContentCipher(registry); err != nil {
		fmt.Printf("error: %v", err)
		return
	}

	decryptionClient, err := s3crypto.NewDecryptionClientV2(sess, registry, func(o *s3crypto.DecryptionClientOptions) {
		o.S3Client = s3.New(sess, &aws.Config{Region: aws.String("us-west-2")})
	})
	if err != nil {
		fmt.Printf("error: %v", err)
		return
	}

	getObject, err := decryptionClient.GetObject(&s3.GetObjectInput{
		Bucket: aws.String("your_bucket"),
		Key:    aws.String("your_key"),
	})
	if err != nil {
		fmt.Printf("get object error: %v\n", err)
		return
	}

	_, err = ioutil.ReadAll(getObject.Body)
	if err != nil {
		fmt.Printf("error reading object: %v\n", err)
	}
	fmt.Println("get object completed")
}
Output:

func (*DecryptionClientV2) GetObject added in v1.33.0

func (c *DecryptionClientV2) GetObject(input *s3.GetObjectInput) (*s3.GetObjectOutput, error)

GetObject is a wrapper for GetObjectRequest

func (*DecryptionClientV2) GetObjectRequest added in v1.33.0

func (c *DecryptionClientV2) GetObjectRequest(input *s3.GetObjectInput) (*request.Request, *s3.GetObjectOutput)

GetObjectRequest will make a request to s3 and retrieve the object. In this process decryption will be done. The SDK only supports V2 reads of KMS and GCM.

Example:

req, out := svc.GetObjectRequest(&s3.GetObjectInput {
  Key: aws.String("testKey"),
  Bucket: aws.String("testBucket"),
})
err := req.Send()

func (*DecryptionClientV2) GetObjectWithContext added in v1.33.0

func (c *DecryptionClientV2) GetObjectWithContext(ctx aws.Context, input *s3.GetObjectInput, opts ...request.Option) (*s3.GetObjectOutput, error)

GetObjectWithContext is a wrapper for GetObjectRequest with the additional context, and request options support.

GetObjectWithContext is the same as GetObject with the additional support for Context input parameters. The Context must not be nil. A nil Context will cause a panic. Use the Context to add deadlining, timeouts, etc. In the future this may create sub-contexts for individual underlying requests.

type Encrypter

type Encrypter interface {
	Encrypt(io.Reader) io.Reader
}

Encrypter interface with only the encrypt method

type EncryptionClient

type EncryptionClient struct {
	S3Client             s3iface.S3API
	ContentCipherBuilder ContentCipherBuilder
	// SaveStrategy will dictate where the envelope is saved.
	//
	// Defaults to the object's metadata
	SaveStrategy SaveStrategy
	// TempFolderPath is used to store temp files when calling PutObject.
	// Temporary files are needed to compute the X-Amz-Content-Sha256 header.
	TempFolderPath string
	// MinFileSize is the minimum size for the content to write to a
	// temporary file instead of using memory.
	MinFileSize int64
}

EncryptionClient is an S3 crypto client. By default the SDK will use Authentication mode which will use KMS for key wrapping and AES GCM for content encryption. AES GCM will load all data into memory. However, the rest of the content algorithms do not load the entire contents into memory.

deprecated: This feature is in maintenance mode, no new updates will be released. Please see https://docs.aws.amazon.com/general/latest/gr/aws_sdk_cryptography.html for more information.

func NewEncryptionClient

func NewEncryptionClient(prov client.ConfigProvider, builder ContentCipherBuilder, options ...func(*EncryptionClient)) *EncryptionClient

NewEncryptionClient instantiates a new S3 crypto client

Example:

	cmkID := "arn:aws:kms:region:000000000000:key/00000000-0000-0000-0000-000000000000"
 sess := session.Must(session.NewSession())
	handler := s3crypto.NewKMSKeyGenerator(kms.New(sess), cmkID)
	svc := s3crypto.NewEncryptionClient(sess, s3crypto.AESGCMContentCipherBuilder(handler))

deprecated: This feature is in maintenance mode, no new updates will be released. Please see https://docs.aws.amazon.com/general/latest/gr/aws_sdk_cryptography.html for more information.

func (*EncryptionClient) PutObject

func (c *EncryptionClient) PutObject(input *s3.PutObjectInput) (*s3.PutObjectOutput, error)

PutObject is a wrapper for PutObjectRequest

deprecated: This feature is in maintenance mode, no new updates will be released. Please see https://docs.aws.amazon.com/general/latest/gr/aws_sdk_cryptography.html for more information.

func (*EncryptionClient) PutObjectRequest

func (c *EncryptionClient) PutObjectRequest(input *s3.PutObjectInput) (*request.Request, *s3.PutObjectOutput)

PutObjectRequest creates a temp file to encrypt the contents into. It then streams that data to S3.

Example:

svc := s3crypto.NewEncryptionClient(session.Must(session.NewSession()), s3crypto.AESGCMContentCipherBuilder(handler))
req, out := svc.PutObjectRequest(&s3.PutObjectInput {
  Key: aws.String("testKey"),
  Bucket: aws.String("testBucket"),
  Body: strings.NewReader("test data"),
})
err := req.Send()

deprecated: This feature is in maintenance mode, no new updates will be released. Please see https://docs.aws.amazon.com/general/latest/gr/aws_sdk_cryptography.html for more information.

func (*EncryptionClient) PutObjectWithContext added in v1.8.0

func (c *EncryptionClient) PutObjectWithContext(ctx aws.Context, input *s3.PutObjectInput, opts ...request.Option) (*s3.PutObjectOutput, error)

PutObjectWithContext is a wrapper for PutObjectRequest with the additional context, and request options support.

PutObjectWithContext is the same as PutObject with the additional support for Context input parameters. The Context must not be nil. A nil Context will cause a panic. Use the Context to add deadlining, timeouts, etc. In the future this may create sub-contexts for individual underlying requests. PutObject is a wrapper for PutObjectRequest

deprecated: This feature is in maintenance mode, no new updates will be released. Please see https://docs.aws.amazon.com/general/latest/gr/aws_sdk_cryptography.html for more information.

type EncryptionClientOptions added in v1.33.0

type EncryptionClientOptions struct {
	S3Client             s3iface.S3API
	ContentCipherBuilder ContentCipherBuilder
	// SaveStrategy will dictate where the envelope is saved.
	//
	// Defaults to the object's metadata
	SaveStrategy SaveStrategy
	// TempFolderPath is used to store temp files when calling PutObject.
	// Temporary files are needed to compute the X-Amz-Content-Sha256 header.
	TempFolderPath string
	// MinFileSize is the minimum size for the content to write to a
	// temporary file instead of using memory.
	MinFileSize int64
}

EncryptionClientOptions is the configuration options for EncryptionClientV2

type EncryptionClientV2 added in v1.33.0

type EncryptionClientV2 struct {
	// contains filtered or unexported fields
}

EncryptionClientV2 is an S3 crypto client. By default the SDK will use Authentication mode which will use KMS for key wrapping and AES GCM for content encryption. AES GCM will load all data into memory. However, the rest of the content algorithms do not load the entire contents into memory.

func NewEncryptionClientV2 added in v1.33.0

func NewEncryptionClientV2(prov client.ConfigProvider, contentCipherBuilder ContentCipherBuilder, options ...func(clientOptions *EncryptionClientOptions),
) (
	client *EncryptionClientV2, err error,
)

NewEncryptionClientV2 instantiates a new S3 crypto client. An error will be returned to the caller if the provided contentCipherBuilder has been deprecated or was constructed with a deprecated component.

Example:

	cmkID := "arn:aws:kms:region:000000000000:key/00000000-0000-0000-0000-000000000000"
 sess := session.Must(session.NewSession())
	var matdesc s3crypto.MaterialDescription
	handler := s3crypto.NewKMSContextKeyGenerator(kms.New(sess), cmkID, matdesc)
	svc := s3crypto.NewEncryptionClientV2(sess, s3crypto.AESGCMContentCipherBuilderV2(handler))
Example (Migration00)

ExampleNewEncryptionClientV2_migration00 provides a migration example for how users can migrate from the V1 encryption client to the V2 encryption client. This example demonstrates how an application using the `kms` key wrap algorithm with `AES/CBC/PKCS5Padding` can migrate their application to `kms+context` key wrapping with `AES/GCM/NoPadding` content encryption.

package main

import (
	"bytes"
	"fmt"

	"github.com/aws/aws-sdk-go/aws"
	"github.com/aws/aws-sdk-go/aws/session"
	"github.com/aws/aws-sdk-go/service/kms"
	"github.com/aws/aws-sdk-go/service/s3"
	"github.com/aws/aws-sdk-go/service/s3/s3crypto"
)

func main() {
	sess := session.Must(session.NewSession())
	kmsClient := kms.New(sess)
	cmkID := "1234abcd-12ab-34cd-56ef-1234567890ab"

	// Usage of NewKMSKeyGenerator (kms) key wrapping algorithm must be migrated to NewKMSContextKeyGenerator (kms+context) key wrapping algorithm
	//
	// cipherDataGenerator := s3crypto.NewKMSKeyGenerator(kmsClient, cmkID)
	cipherDataGenerator := s3crypto.NewKMSContextKeyGenerator(kmsClient, cmkID, s3crypto.MaterialDescription{})

	// Usage of AESCBCContentCipherBuilder (AES/CBC/PKCS5Padding) must be migrated to AESGCMContentCipherBuilder (AES/GCM/NoPadding)
	//
	// contentCipherBuilder := s3crypto.AESCBCContentCipherBuilder(cipherDataGenerator, s3crypto.AESCBCPadder)
	contentCipherBuilder := s3crypto.AESGCMContentCipherBuilderV2(cipherDataGenerator)

	// Construction of an encryption client should be done using NewEncryptionClientV2
	//
	// encryptionClient := s3crypto.NewEncryptionClient(sess, contentCipherBuilder)
	encryptionClient, err := s3crypto.NewEncryptionClientV2(sess, contentCipherBuilder)
	if err != nil {
		fmt.Printf("failed to construct encryption client: %v", err)
		return
	}

	_, err = encryptionClient.PutObject(&s3.PutObjectInput{
		Bucket: aws.String("your_bucket"),
		Key:    aws.String("your_key"),
		Body:   bytes.NewReader([]byte("your content")),
	})
	if err != nil {
		fmt.Printf("put object error: %v\n", err)
		return
	}
	fmt.Println("put object completed")
}
Output:

Example (Migration01)

ExampleNewEncryptionClientV2_migration01 provides a more advanced migration example for how users can migrate from the V1 encryption client to the V2 encryption client using more complex client construction.

package main

import (
	"bytes"
	"fmt"

	"github.com/aws/aws-sdk-go/aws"
	"github.com/aws/aws-sdk-go/aws/session"
	"github.com/aws/aws-sdk-go/service/kms"
	"github.com/aws/aws-sdk-go/service/s3"
	"github.com/aws/aws-sdk-go/service/s3/s3crypto"
)

func main() {
	sess := session.Must(session.NewSession())
	kmsClient := kms.New(sess)
	cmkID := "1234abcd-12ab-34cd-56ef-1234567890ab"

	cipherDataGenerator := s3crypto.NewKMSContextKeyGenerator(kmsClient, cmkID, s3crypto.MaterialDescription{})

	contentCipherBuilder := s3crypto.AESGCMContentCipherBuilderV2(cipherDataGenerator)

	// Overriding of the encryption client options is possible by passing in functional arguments that override the
	// provided EncryptionClientOptions.
	//
	// encryptionClient := s3crypto.NewEncryptionClient(cipherDataGenerator, contentCipherBuilder, func(o *s3crypto.EncryptionClient) {
	//	 o.S3Client = s3.New(sess, &aws.Config{Region: aws.String("us-west-2")}),
	// })
	encryptionClient, err := s3crypto.NewEncryptionClientV2(sess, contentCipherBuilder, func(o *s3crypto.EncryptionClientOptions) {
		o.S3Client = s3.New(sess, &aws.Config{Region: aws.String("us-west-2")})
	})
	if err != nil {
		fmt.Printf("failed to construct encryption client: %v", err)
		return
	}

	_, err = encryptionClient.PutObject(&s3.PutObjectInput{
		Bucket: aws.String("your_bucket"),
		Key:    aws.String("your_key"),
		Body:   bytes.NewReader([]byte("your content")),
	})
	if err != nil {
		fmt.Printf("put object error: %v\n", err)
		return
	}
	fmt.Println("put object completed")
}
Output:

func (*EncryptionClientV2) PutObject added in v1.33.0

func (c *EncryptionClientV2) PutObject(input *s3.PutObjectInput) (*s3.PutObjectOutput, error)

PutObject is a wrapper for PutObjectRequest

func (*EncryptionClientV2) PutObjectRequest added in v1.33.0

func (c *EncryptionClientV2) PutObjectRequest(input *s3.PutObjectInput) (*request.Request, *s3.PutObjectOutput)

PutObjectRequest creates a temp file to encrypt the contents into. It then streams that data to S3.

Example:

req, out := svc.PutObjectRequest(&s3.PutObjectInput {
  Key: aws.String("testKey"),
  Bucket: aws.String("testBucket"),
  Body: strings.NewReader("test data"),
})
err := req.Send()

func (*EncryptionClientV2) PutObjectWithContext added in v1.33.0

func (c *EncryptionClientV2) PutObjectWithContext(ctx aws.Context, input *s3.PutObjectInput, opts ...request.Option) (*s3.PutObjectOutput, error)

PutObjectWithContext is a wrapper for PutObjectRequest with the additional context, and request options support.

PutObjectWithContext is the same as PutObject with the additional support for Context input parameters. The Context must not be nil. A nil Context will cause a panic. Use the Context to add deadlining, timeouts, etc. In the future this may create sub-contexts for individual underlying requests.

type Envelope

type Envelope struct {
	// IV is the randomly generated IV base64 encoded.
	IV string `json:"x-amz-iv"`
	// CipherKey is the randomly generated cipher key.
	CipherKey string `json:"x-amz-key-v2"`
	// MaterialDesc is a description to distinguish from other envelopes.
	MatDesc string `json:"x-amz-matdesc"`
	WrapAlg string `json:"x-amz-wrap-alg"`
	CEKAlg  string `json:"x-amz-cek-alg"`
	TagLen  string `json:"x-amz-tag-len"`

	// deprecated: This MD5 hash is no longer populated
	UnencryptedMD5 string `json:"-"`

	UnencryptedContentLen string `json:"x-amz-unencrypted-content-length"`
}

Envelope encryption starts off by generating a random symmetric key using AES GCM. The SDK generates a random IV based off the encryption cipher chosen. The master key that was provided, whether by the user or KMS, will be used to encrypt the randomly generated symmetric key and base64 encode the iv. This will allow for decryption of that same data later.

func (*Envelope) UnmarshalJSON added in v1.33.6

func (e *Envelope) UnmarshalJSON(value []byte) error

UnmarshalJSON unmarshalls the given JSON bytes into Envelope

type HeaderV2LoadStrategy

type HeaderV2LoadStrategy struct{}

HeaderV2LoadStrategy will load the envelope from the metadata

func (HeaderV2LoadStrategy) Load

func (load HeaderV2LoadStrategy) Load(req *request.Request) (Envelope, error)

Load from a given object's header

type HeaderV2SaveStrategy

type HeaderV2SaveStrategy struct{}

HeaderV2SaveStrategy will save the metadata of the crypto contents to the header of the object.

func (HeaderV2SaveStrategy) Save

func (strat HeaderV2SaveStrategy) Save(env Envelope, req *request.Request) error

Save will save the envelope to the request's header.

type LoadStrategy

type LoadStrategy interface {
	Load(*request.Request) (Envelope, error)
}

LoadStrategy ...

type MaterialDescription

type MaterialDescription map[string]*string

MaterialDescription is used to identify how and what master key has been used.

func (MaterialDescription) Clone added in v1.34.0

func (md MaterialDescription) Clone() (clone MaterialDescription)

Clone returns a copy of the MaterialDescription

type Padder added in v1.7.9

type Padder interface {
	// Pad will pad the byte array.
	// The second parameter is NOT how many
	// bytes to pad by, but how many bytes
	// have been read prior to the padding.
	// This allows for streamable padding.
	Pad([]byte, int) ([]byte, error)
	// Unpad will unpad the byte bytes. Unpad
	// methods must be constant time.
	Unpad([]byte) ([]byte, error)
	// Name returns the name of the padder.
	// This is used when decrypting on
	// instantiating new padders.
	Name() string
}

Padder handles padding of crypto data

func NewPKCS7Padder added in v1.7.9

func NewPKCS7Padder(blockSize int) Padder

NewPKCS7Padder follows the RFC 2315: https://www.ietf.org/rfc/rfc2315.txt PKCS7 padding is subject to side-channel attacks and timing attacks. For the most secure data, use an authenticated crypto algorithm.

type S3LoadStrategy

type S3LoadStrategy struct {
	Client                *s3.S3
	InstructionFileSuffix string
}

S3LoadStrategy will load the instruction file from s3

func (S3LoadStrategy) Load

func (load S3LoadStrategy) Load(req *request.Request) (Envelope, error)

Load from a given instruction file suffix

type S3SaveStrategy

type S3SaveStrategy struct {
	Client                *s3.S3
	InstructionFileSuffix string
}

S3SaveStrategy will save the metadata to a separate instruction file in S3

func (S3SaveStrategy) Save

func (strat S3SaveStrategy) Save(env Envelope, req *request.Request) error

Save will save the envelope contents to s3.

type SaveStrategy

type SaveStrategy interface {
	Save(Envelope, *request.Request) error
}

SaveStrategy is how the data's metadata wants to be saved

type WrapEntry

type WrapEntry func(Envelope) (CipherDataDecrypter, error)

WrapEntry is builder that return a proper key decrypter and error

func NewKMSWrapEntry added in v1.14.22

func NewKMSWrapEntry(kmsClient kmsiface.KMSAPI) WrapEntry

NewKMSWrapEntry builds returns a new KMS key provider and its decrypt handler.

Example:

sess := session.Must(session.NewSession())
customKMSClient := kms.New(sess)
decryptHandler := s3crypto.NewKMSWrapEntry(customKMSClient)

svc := s3crypto.NewDecryptionClient(sess, func(svc *s3crypto.DecryptionClient) {
	svc.WrapRegistry[s3crypto.KMSWrap] = decryptHandler
}))

deprecated: This feature is in maintenance mode, no new updates will be released. Please see https://docs.aws.amazon.com/general/latest/gr/aws_sdk_cryptography.html for more information.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL