Package: s3crypto

import "../ibm-cos-sdk-go/service/s3/s3crypto"

Constants

const DefaultInstructionKeySuffix = readonly

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

Value:

".instruction"
const AESGCMNoPadding = readonly

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

Value:

"AES/GCM/NoPadding"
const AESCBC = readonly

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

Value:

"AES/CBC"
const KMSWrap = readonly

KMSWrap is a constant used during decryption to build a KMS key handler.

Value:

"kms"
const DefaultMinFileSize = readonly

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

Value:

1024 * 512 * 5
const KMSContextWrap = readonly

KMSContextWrap is a constant used during decryption to build a kms+context key handler

Value:

"kms+context"

Variables

var NoPadder = writable

NoPadder does not pad anything

Value:

Padder(noPadder{})
var AESCBCPadder = writable

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.

Value:

Padder(aescbcPadding)
var _ awsFixture = writable

Value:

(*kmsContextKeyHandler)(nil)

Type Summary collapse

Interface Summary collapse

Function Summary collapse

Type Details

DecryptionClientOptions struct

DecryptionClientOptions is the configuration options for DecryptionClientV2.

Structure Fields:

S3Client s3iface.S3API
LoadStrategy LoadStrategy

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.

CryptoRegistry *CryptoRegistry

EncryptionClientOptions struct

EncryptionClientOptions is the configuration options for EncryptionClientV2

Structure Fields:

S3Client s3iface.S3API
ContentCipherBuilder ContentCipherBuilder
SaveStrategy SaveStrategy

SaveStrategy will dictate where the envelope is saved.

Defaults to the object's metadata

TempFolderPath string

TempFolderPath is used to store temp files when calling PutObject. Temporary files are needed to compute the X-Amz-Content-Sha256 header.

MinFileSize int64

MinFileSize is the minimum size for the content to write to a temporary file instead of using memory.

Function Details

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 docs.aws.amazon.com/general/latest/gr/aws_sdk_cryptography.html for more information.



20
21
22
 
// File 'service/s3/s3crypto/aes_cbc_content_cipher.go', line 20


func AESCBCContentCipherBuilder(generator CipherDataGenerator, padder Padder) ContentCipherBuilder {
	return cbcContentCipherBuilder{generator: generator, padder: padder}
}

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 docs.aws.amazon.com/general/latest/gr/aws_sdk_cryptography.html for more information.



22
23
24
 
// File 'service/s3/s3crypto/aes_gcm_content_cipher.go', line 22


func AESGCMContentCipherBuilder(generator CipherDataGenerator) ContentCipherBuilder {
	return gcmContentCipherBuilder{generator}
}

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.



32
33
34
 
// File 'service/s3/s3crypto/aes_gcm_content_cipher.go', line 32


func AESGCMContentCipherBuilderV2(generator CipherDataGeneratorWithCEKAlg) ContentCipherBuilder {
	return gcmContentCipherBuilderV2{generator}
}

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 docs.aws.amazon.com/general/latest/gr/aws_sdk_cryptography.html for more information.



51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
 
// File 'service/s3/s3crypto/decryption_client.go', line 51


func NewDecryptionClient(prov client.ConfigProvider, options ...func(*DecryptionClient)) *DecryptionClient {
	s3client := s3.New(prov)

	s3client.Handlers.Build.PushBack(func(r *request.Request) {
		request.AddToUserAgent(r, "S3CryptoV1n")
	})

	kmsClient := kms.New(prov)
	client := &DecryptionClient{
		S3Client: s3client,
		LoadStrategy: defaultV2LoadStrategy{
			client: s3client,
		},
		WrapRegistry: map[string]WrapEntry{
			KMSWrap:        NewKMSWrapEntry(kmsClient),
			KMSContextWrap: newKMSContextWrapEntryWithAnyCMK(kmsClient),
		},
		CEKRegistry: map[string]CEKEntry{
			AESGCMNoPadding:                    newAESGCMContentCipher,
			AESCBC + "/" + AESCBCPadder.Name(): newAESCBCContentCipher,
		},
		PadderRegistry: map[string]Padder{
			AESCBC + "/" + AESCBCPadder.Name(): AESCBCPadder,
			NoPadder.Name():                    NoPadder,
		},
	}
	for _, option := range options {
		option(client)
	}

	return client
}

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 docs.aws.amazon.com/general/latest/gr/aws_sdk_cryptography.html for more information.



59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
 
// File 'service/s3/s3crypto/encryption_client.go', line 59


func NewEncryptionClient(prov client.ConfigProvider, builder ContentCipherBuilder, options ...func(*EncryptionClient)) *EncryptionClient {
	s3client := s3.New(prov)

	s3client.Handlers.Build.PushBack(func(r *request.Request) {
		request.AddToUserAgent(r, "S3CryptoV1n")
	})

	client := &EncryptionClient{
		S3Client:             s3client,
		ContentCipherBuilder: builder,
		SaveStrategy:         HeaderV2SaveStrategy{},
		MinFileSize:          DefaultMinFileSize,
	}

	for _, option := range options {
		option(client)
	}

	return client
}

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)



28
29
30
 
// File 'service/s3/s3crypto/kms_context_key_handler.go', line 28


func NewKMSContextKeyGenerator(client kmsiface.KMSAPI, cmkID string, matdesc MaterialDescription) CipherDataGeneratorWithCEKAlg {
	return newKMSContextKeyHandler(client, cmkID, matdesc)
}

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 docs.aws.amazon.com/general/latest/gr/aws_sdk_cryptography.html for more information.



36
37
38
 
// File 'service/s3/s3crypto/kms_key_handler.go', line 36


func NewKMSKeyGenerator(kmsClient kmsiface.KMSAPI, cmkID string) CipherDataGenerator {
	return NewKMSKeyGeneratorWithMatDesc(kmsClient, cmkID, MaterialDescription{})
}

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 docs.aws.amazon.com/general/latest/gr/aws_sdk_cryptography.html for more information.



70
71
72
 
// File 'service/s3/s3crypto/kms_key_handler.go', line 70


func NewKMSKeyGeneratorWithMatDesc(kmsClient kmsiface.KMSAPI, cmkID string, matdesc MaterialDescription) CipherDataGenerator {
	return newKMSKeyHandler(kmsClient, cmkID, matdesc)
}

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 docs.aws.amazon.com/general/latest/gr/aws_sdk_cryptography.html for more information.



87
88
89
90
 
// File 'service/s3/s3crypto/kms_key_handler.go', line 87


func NewKMSWrapEntry(kmsClient kmsiface.KMSAPI) WrapEntry {
	kp := newKMSWrapEntry(kmsClient)
	return kp.decryptHandler
}

func NewPKCS7Padder(blockSize int) Padder

NewPKCS7Padder follows the RFC 2315: 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.



24
25
26
 
// File 'service/s3/s3crypto/pkcs7_padder.go', line 24


func NewPKCS7Padder(blockSize int) Padder {
	return pkcs7Padder{blockSize}
}

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 docs.aws.amazon.com/general/latest/gr/aws_sdk_cryptography.html for more information.



34
35
36
37
38
39
40
41
42
43
44
45
46
47
 
// File 'service/s3/s3crypto/aes_cbc_content_cipher.go', line 34


func RegisterAESCBCContentCipher(registry *CryptoRegistry, padder Padder) error {
	if registry == nil {
		return errNilCryptoRegistry
	}
	name := AESCBC + "/" + padder.Name()
	err := registry.AddCEK(name, newAESCBCContentCipher)
	if err != nil {
		return err
	}
	if err := registry.AddPadder(name, padder); err != nil {
		return err
	}
	return nil
}

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
}



44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
 
// File 'service/s3/s3crypto/aes_gcm_content_cipher.go', line 44


func RegisterAESGCMContentCipher(registry *CryptoRegistry) error {
	if registry == nil {
		return errNilCryptoRegistry
	}

	err := registry.AddCEK(AESGCMNoPadding, newAESGCMContentCipher)
	if err != nil {
		return err
	}

	// NoPadder is generic but required by this algorithm, so if it is already registered and is the expected implementation
	// don't error.
	padderName := NoPadder.Name()
	if v, ok := registry.GetPadder(padderName); !ok {
		if err := registry.AddPadder(padderName, NoPadder); err != nil {
			return err
		}
	} else if _, ok := v.(noPadder); !ok {
		return fmt.Errorf("%s is already registred but does not match expected type %T", padderName, NoPadder)
	}
	return nil
}

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
}



58
59
60
61
62
63
 
// File 'service/s3/s3crypto/kms_context_key_handler.go', line 58


func RegisterKMSContextWrapWithAnyCMK(registry *CryptoRegistry, client kmsiface.KMSAPI) error {
	if registry == nil {
		return errNilCryptoRegistry
	}
	return registry.AddWrap(KMSContextWrap, newKMSContextWrapEntryWithAnyCMK(client))
}

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
}



41
42
43
44
45
46
 
// File 'service/s3/s3crypto/kms_context_key_handler.go', line 41


func RegisterKMSContextWrapWithCMK(registry *CryptoRegistry, client kmsiface.KMSAPI, cmkID string) error {
	if registry == nil {
		return errNilCryptoRegistry
	}
	return registry.AddWrap(KMSContextWrap, newKMSContextWrapEntryWithCMK(client, cmkID))
}

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 docs.aws.amazon.com/general/latest/gr/aws_sdk_cryptography.html for more information.



123
124
125
126
127
128
 
// File 'service/s3/s3crypto/kms_key_handler.go', line 123


func RegisterKMSWrapWithAnyCMK(registry *CryptoRegistry, client kmsiface.KMSAPI) error {
	if registry == nil {
		return errNilCryptoRegistry
	}
	return registry.AddWrap(KMSWrap, NewKMSWrapEntry(client))
}

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 docs.aws.amazon.com/general/latest/gr/aws_sdk_cryptography.html for more information.



104
105
106
107
108
109
 
// File 'service/s3/s3crypto/kms_key_handler.go', line 104


func RegisterKMSWrapWithCMK(registry *CryptoRegistry, client kmsiface.KMSAPI, cmkID string) error {
	if registry == nil {
		return errNilCryptoRegistry
	}
	return registry.AddWrap(KMSWrap, newKMSWrapEntryWithCMK(client, cmkID))
}