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()) // Create the KeyProvider handler := s3crypto.NewKMSContextKeyGenerator(kms.New(sess), cmkID) // 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 := s3crypto.NewEncryptionClientV2(sess, s3crypto.AESGCMContentCipherBuilder(handler)) svc := s3crypto.NewDecryptionClientV2(sess)
Configuration of the S3 cryptography client
sess := session.Must(session.NewSession()) handler := s3crypto.NewKMSContextKeyGenerator(kms.New(sess), cmkID) svc := s3crypto.NewEncryptionClientV2(sess, s3crypto.AESGCMContentCipherBuilder(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) })
The default SaveStrategy is to the object's header.
The InstructionFileSuffix defaults to .instruction. Careful here though, if you do this, be sure you know what that suffix is in grabbing data. All requests will look for fooKey.example instead of fooKey.instruction. This suffix only affects gets and not puts. Put uses the keyprovider's suffix.
Registration of new wrap or cek algorithms are also supported by the SDK. Let's say we want to support `AES Wrap` and `AES CTR`. Let's assume we have already defined the functionality.
svc := s3crypto.NewDecryptionClientV2(sess, func(o *s3crypto.DecryptionClientOptions) { o.WrapRegistry["CustomWrap"] = NewCustomWrap o.CEKRegistry["CustomCEK"] = NewCustomCEK })
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))
Deprecations ¶
The EncryptionClient and DecryptionClient types and their associated constructor functions have been deprecated. Users of these clients should migrate to EncryptionClientV2 and DecryptionClientV2 types and constructor functions.
EncryptionClientV2 removes encryption support of the following features
- AES/CBC/PKCS5Padding (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/PKCS5Padding` will need to migrate usage to `AES/GCM/NoPadding`. 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 deprecated 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.
Index ¶
- Constants
- Variables
- type CEKEntry
- type Cipher
- type CipherData
- type CipherDataDecrypter
- type CipherDataDecrypterWithContext
- type CipherDataGenerator
- type CipherDataGeneratorWithCEKAlg
- type CipherDataGeneratorWithCEKAlgWithContext
- type CipherDataGeneratorWithContext
- type ContentCipher
- type ContentCipherBuilder
- type ContentCipherBuilderWithContext
- type CryptoReadCloser
- type Decrypter
- type DecryptionClient
- func (c *DecryptionClient) GetObject(input *s3.GetObjectInput) (*s3.GetObjectOutput, error)
- func (c *DecryptionClient) GetObjectRequest(input *s3.GetObjectInput) (*request.Request, *s3.GetObjectOutput)
- func (c *DecryptionClient) GetObjectWithContext(ctx aws.Context, input *s3.GetObjectInput, opts ...request.Option) (*s3.GetObjectOutput, error)
- type DecryptionClientOptions
- type DecryptionClientV2
- func (c *DecryptionClientV2) GetObject(input *s3.GetObjectInput) (*s3.GetObjectOutput, error)
- func (c *DecryptionClientV2) GetObjectRequest(input *s3.GetObjectInput) (*request.Request, *s3.GetObjectOutput)
- func (c *DecryptionClientV2) GetObjectWithContext(ctx aws.Context, input *s3.GetObjectInput, opts ...request.Option) (*s3.GetObjectOutput, error)
- type Encrypter
- type EncryptionClient
- func (c *EncryptionClient) PutObject(input *s3.PutObjectInput) (*s3.PutObjectOutput, error)
- func (c *EncryptionClient) PutObjectRequest(input *s3.PutObjectInput) (*request.Request, *s3.PutObjectOutput)
- func (c *EncryptionClient) PutObjectWithContext(ctx aws.Context, input *s3.PutObjectInput, opts ...request.Option) (*s3.PutObjectOutput, error)
- type EncryptionClientOptions
- type EncryptionClientV2
- func (c *EncryptionClientV2) PutObject(input *s3.PutObjectInput) (*s3.PutObjectOutput, error)
- func (c *EncryptionClientV2) PutObjectRequest(input *s3.PutObjectInput) (*request.Request, *s3.PutObjectOutput)
- func (c *EncryptionClientV2) PutObjectWithContext(ctx aws.Context, input *s3.PutObjectInput, opts ...request.Option) (*s3.PutObjectOutput, error)
- type Envelope
- type HeaderV2LoadStrategy
- type HeaderV2SaveStrategy
- type LoadStrategy
- type MaterialDescription
- type Padder
- type S3LoadStrategy
- type S3SaveStrategy
- type SaveStrategy
- type WrapEntry
Examples ¶
Constants ¶
const ( // KMSWrap is a constant used during decryption to build a KMS key handler. KMSWrap = "kms" // KMSContextWrap is a constant used during decryption to build a kms+context key handler KMSContextWrap = "kms+context" )
const AESCBC = "AES/CBC"
AESCBC is the string constant that signifies the AES CBC algorithm cipher.
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.
const DefaultInstructionKeySuffix = ".instruction"
DefaultInstructionKeySuffix is appended to the end of the instruction file key when grabbing or saving to S3
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.
Variables ¶
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.
var NoPadder = Padder(noPadder{})
NoPadder does not pad anything
Functions ¶
This section is empty.
Types ¶
type CEKEntry ¶
type CEKEntry func(CipherData) (ContentCipher, error)
CEKEntry is a builder thatn returns a proper content decrypter and error
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.
type CipherDataDecrypter ¶
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.New(&aws.Config{}) cmkID := "arn to key" matdesc := s3crypto.MaterialDescription{} handler := s3crypto.NewKMSKeyGenerator(kms.New(sess), cmkID)
deprecated: See NewKMSContextKeyGenerator
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.New(&aws.Config{}) cmkID := "arn to key" matdesc := s3crypto.MaterialDescription{} handler := s3crypto.NewKMSKeyGeneratorWithMatDesc(kms.New(sess), cmkID, matdesc)
deprecated: See NewKMSContextKeyGeneratorWithMatDesc
type CipherDataGeneratorWithCEKAlg ¶ added in v1.33.0
type CipherDataGeneratorWithCEKAlg interface { GenerateCipherDataWithCEKAlg(int, int, string) (CipherData, error) CipherDataGenerator // backwards comparability to plug into older interface }
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) CipherDataGeneratorWithCEKAlg
NewKMSContextKeyGenerator builds a new kms+context key provider using the customer key ID and material description.
Example:
sess := session.New(&aws.Config{}) cmkID := "arn to key" matdesc := s3crypto.MaterialDescription{} handler := s3crypto.NewKMSContextKeyGenerator(kms.New(sess), cmkID)
func NewKMSContextKeyGeneratorWithMatDesc ¶ added in v1.33.0
func NewKMSContextKeyGeneratorWithMatDesc(kmsClient kmsiface.KMSAPI, cmkID string, matdesc MaterialDescription) CipherDataGeneratorWithCEKAlg
NewKMSContextKeyGeneratorWithMatDesc builds a new kms+context key provider using the customer key ID and material description.
Example:
sess := session.New(&aws.Config{}) cmkID := "arn to key" matdesc := s3crypto.MaterialDescription{} handler := s3crypto.NewKMSKeyGeneratorWithMatDesc(kms.New(sess), cmkID, matdesc)
type CipherDataGeneratorWithCEKAlgWithContext ¶ added in v1.33.0
type CipherDataGeneratorWithCEKAlgWithContext interface {
GenerateCipherDataWithCEKAlgWithContext(aws.Context, int, int, string) (CipherData, error)
}
CipherDataGeneratorWithCEKAlgWithContext 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 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 mode structure with a specific cipher for the master key
deprecated: This content cipher builder has been deprecated. Users should migrate to AESGCMContentCipherBuilder
func AESGCMContentCipherBuilder ¶
func AESGCMContentCipherBuilder(generator CipherDataGenerator) ContentCipherBuilder
AESGCMContentCipherBuilder returns a new encryption only mode structure with a specific cipher for the master key
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
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: See DecryptionClientV2
func NewDecryptionClient ¶
func NewDecryptionClient(prov client.ConfigProvider, options ...func(*DecryptionClient)) *DecryptionClient
NewDecryptionClient instantiates a new S3 crypto client
Example:
sess := session.New() svc := s3crypto.NewDecryptionClient(sess, func(svc *s3crypto.DecryptionClient{ // Custom client options here }))
deprecated: see NewDecryptionClientV2
func (*DecryptionClient) GetObject ¶
func (c *DecryptionClient) GetObject(input *s3.GetObjectInput) (*s3.GetObjectOutput, error)
GetObject is a wrapper for GetObjectRequest
deprecated: see DecryptionClientV2.GetObject
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: see DecryptionClientV2.GetObjectRequest
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: see DecryptionClientV2.GetObjectWithContext
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 WrapRegistry map[string]WrapEntry CEKRegistry map[string]CEKEntry PadderRegistry map[string]Padder }
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, options ...func(clientOptions *DecryptionClientOptions)) *DecryptionClientV2
NewDecryptionClientV2 instantiates a new V2 S3 crypto client. The returned DecryptionClientV2 will be able to decrypt object encrypted by both the V1 and V2 clients.
Example:
sess := session.Must(session.NewSession()) svc := s3crypto.NewDecryptionClientV2(sess, func(svc *s3crypto.DecryptionClientOptions{ // Custom client options here }))
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/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) decryptionClient := s3crypto.NewDecryptionClientV2(sess) 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/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")}) //}) decryptionClient := s3crypto.NewDecryptionClientV2(sess, func(o *s3crypto.DecryptionClientOptions) { o.S3Client = s3.New(sess, &aws.Config{Region: aws.String("us-west-2")}) }) 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:
sess := session.Must(session.NewSession()) svc := s3crypto.NewDecryptionClientV2(sess) 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 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: See EncryptionClientV2
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: See NewEncryptionClientV2
func (*EncryptionClient) PutObject ¶
func (c *EncryptionClient) PutObject(input *s3.PutObjectInput) (*s3.PutObjectOutput, error)
PutObject is a wrapper for PutObjectRequest
deprecated: See EncryptionClientV2.PutObject
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.New(session.New(), 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: See EncryptionClientV2.PutObjectRequest
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: See EncryptionClientV2.PutObjectWithContext
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 if it uses other deprecated components.
Example:
cmkID := "arn:aws:kms:region:000000000000:key/00000000-0000-0000-0000-000000000000" sess := session.Must(session.NewSession()) handler := s3crypto.NewKMSContextKeyGenerator(kms.New(sess), cmkID) svc := s3crypto.NewEncryptionClientV2(sess, s3crypto.AESGCMContentCipherBuilder(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) // Usage of AESCBCContentCipherBuilder (AES/CBC/PKCS5Padding) must be migrated to AESGCMContentCipherBuilder (AES/GCM/NoPadding) // // contentCipherBuilder := s3crypto.AESCBCContentCipherBuilder(cipherDataGenerator, s3crypto.AESCBCPadder) contentCipherBuilder := s3crypto.AESGCMContentCipherBuilder(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) contentCipherBuilder := s3crypto.AESGCMContentCipherBuilder(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:
sess := session.Must(session.NewSession()) handler := s3crypto.NewKMSContextKeyGenerator(kms.New(sess), "cmkID") svc := s3crypto.NewEncryptionClientV2(sess, 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()
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"` 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
UnmarshalJSON unmarshalls the given JSON bytes into Envelope
type HeaderV2LoadStrategy ¶
type HeaderV2LoadStrategy struct{}
HeaderV2LoadStrategy will load the envelope from the metadata
type HeaderV2SaveStrategy ¶
type HeaderV2SaveStrategy struct{}
HeaderV2SaveStrategy will save the metadata of the crypto contents to the header of the object.
type LoadStrategy ¶
LoadStrategy ...
type MaterialDescription ¶
MaterialDescription is used to identify how and what master key has been used.
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
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 ¶
S3LoadStrategy will load the instruction file from s3
type S3SaveStrategy ¶
S3SaveStrategy will save the metadata to a separate instruction file in S3
type SaveStrategy ¶
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 NewKMSContextWrapEntry ¶ added in v1.33.0
NewKMSContextWrapEntry builds returns a new KMS key provider and its decrypt handler.
Example:
sess := session.New(&aws.Config{}) customKMSClient := kms.New(sess) decryptHandler := s3crypto.NewKMSContextWrapEntry(customKMSClient) svc := s3crypto.NewDecryptionClient(sess, func(svc *s3crypto.DecryptionClient) { svc.WrapRegistry[s3crypto.KMSContextWrap] = decryptHandler }))
func NewKMSWrapEntry ¶ added in v1.14.22
NewKMSWrapEntry builds returns a new KMS key provider and its decrypt handler.
Example:
sess := session.New(&aws.Config{}) customKMSClient := kms.New(sess) decryptHandler := s3crypto.NewKMSWrapEntry(customKMSClient) svc := s3crypto.NewDecryptionClient(sess, func(svc *s3crypto.DecryptionClient) { svc.WrapRegistry[s3crypto.KMSWrap] = decryptHandler }))
deprecated: See NewKMSContextWrapEntry
Source Files ¶
- aes_cbc.go
- aes_cbc_content_cipher.go
- aes_cbc_padder.go
- aes_gcm.go
- aes_gcm_content_cipher.go
- cipher.go
- cipher_builder.go
- cipher_util.go
- decryption_client.go
- decryption_client_v2.go
- deprecations.go
- doc.go
- encryption_client.go
- encryption_client_v2.go
- envelope.go
- hash_io.go
- helper.go
- key_handler.go
- kms_key_handler.go
- mat_desc.go
- padder.go
- pkcs7_padder.go
- shared_client.go
- strategy.go