1/*
2Package s3crypto provides encryption to S3 using KMS and AES GCM.
3
4Keyproviders are interfaces that handle masterkeys. Masterkeys are used to encrypt and decrypt the randomly
5generated cipher keys. The SDK currently uses KMS to do this. A user does not need to provide a master key
6since all that information is hidden in KMS.
7
8Modes are interfaces that handle content encryption and decryption. It is an abstraction layer that instantiates
9the ciphers. If content is being encrypted we generate the key and iv of the cipher. For decryption, we use the
10metadata stored either on the object or an instruction file object to decrypt the contents.
11
12Ciphers are interfaces that handle encryption and decryption of data. This may be key wrap ciphers or content
13ciphers.
14
15Creating an S3 cryptography client
16
17	cmkID := "<some key ID>"
18	sess := session.Must(session.NewSession())
19	kmsClient := kms.New(sess)
20	// Create the KeyProvider
21	var matdesc s3crypto.MaterialDescription
22	handler := s3crypto.NewKMSContextKeyGenerator(kmsClient, cmkID, matdesc)
23
24	// Create an encryption and decryption client
25	// We need to pass the session here so S3 can use it. In addition, any decryption that
26	// occurs will use the KMS client.
27	svc, err := s3crypto.NewEncryptionClientV2(sess, s3crypto.AESGCMContentCipherBuilderV2(handler))
28	if err != nil {
29		panic(err) // handle error
30	}
31
32	// Create a CryptoRegistry and register the algorithms you wish to use for decryption
33	cr := s3crypto.NewCryptoRegistry()
34
35	if err := s3crypto.RegisterAESGCMContentCipher(cr); err != nil {
36		panic(err) // handle error
37	}
38
39	if err := s3crypto.RegisterKMSContextWrapWithAnyCMK(cr, kmsClient); err != nil {
40		panic(err) // handle error
41	}
42
43	// Create a decryption client to decrypt artifacts
44	svc, err := s3crypto.NewDecryptionClientV2(sess, cr)
45	if err != nil {
46		panic(err) // handle error
47	}
48
49Configuration of the S3 cryptography client
50
51	sess := session.Must(session.NewSession())
52	handler := s3crypto.NewKMSContextKeyGenerator(kms.New(sess), cmkID, s3crypto.MaterialDescription{})
53	svc, err := s3crypto.NewEncryptionClientV2(sess, s3crypto.AESGCMContentCipherBuilderV2(handler), func (o *s3crypto.EncryptionClientOptions) {
54		// Save instruction files to separate objects
55		o.SaveStrategy = NewS3SaveStrategy(sess, "")
56
57		// Change instruction file suffix to .example
58		o.InstructionFileSuffix = ".example"
59
60		// Set temp folder path
61		o.TempFolderPath = "/path/to/tmp/folder/"
62
63		// Any content less than the minimum file size will use memory
64		// instead of writing the contents to a temp file.
65		o.MinFileSize = int64(1024 * 1024 * 1024)
66	})
67	if err != nil {
68		panic(err) // handle error
69	}
70
71Object Metadata SaveStrategy
72
73The default SaveStrategy is to save metadata to an object's headers. An alternative SaveStrategy can be provided to the EncryptionClientV2.
74For example, the S3SaveStrategy can be used to save the encryption metadata to a instruction file that is stored in S3
75using the objects KeyName+InstructionFileSuffix. The InstructionFileSuffix defaults to .instruction. If using this strategy you will need to
76configure the DecryptionClientV2 to use the matching S3LoadStrategy LoadStrategy in order to decrypt object using this save strategy.
77
78Custom Key Wrappers and Custom Content Encryption Algorithms
79
80Registration of custom key wrapping or content encryption algorithms not provided by AWS is allowed by the SDK, but
81security and compatibility with custom types can not be guaranteed. For example if you want to support `CustomWrap`
82key wrapping algorithm and `CustomCEK` content encryption algorithm. You can use the CryptoRegistry to register these types.
83
84	cr := s3crypto.NewCryptoRegistry()
85
86	// Register a custom key wrap algorithm to the CryptoRegistry
87	if err := cr.AddWrap("CustomWrap", NewCustomWrapEntry); err != nil {
88		panic(err) // handle error
89	}
90
91	// Register a custom content encryption algorithm to the CryptoRegistry
92	if err := cr.AddCEK("CustomCEK", NewCustomCEKEntry); err != nil {
93		panic(err) // handle error
94	}
95
96	svc, err := s3crypto.NewDecryptionClientV2(sess, cr)
97	if err != nil {
98		panic(err) // handle error
99	}
100
101We have now registered these new algorithms to the decryption client. When the client calls `GetObject` and sees
102the wrap as `CustomWrap` then it'll use that wrap algorithm. This is also true for `CustomCEK`.
103
104For encryption adding a custom content cipher builder and key handler will allow for encryption of custom
105defined ciphers.
106
107	// Our wrap algorithm, CustomWrap
108	handler := NewCustomWrap(key, iv)
109	// Our content cipher builder, NewCustomCEKContentBuilder
110	svc := s3crypto.NewEncryptionClientV2(sess, NewCustomCEKContentBuilder(handler))
111
112Maintenance Mode Notification for V1 Clients
113
114The 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.
115Users of these clients should migrate to EncryptionClientV2 and DecryptionClientV2.
116
117EncryptionClientV2 removes encryption support of the following features
118	* AES/CBC (content cipher)
119	* kms (key wrap algorithm)
120
121Attempting to construct an EncryptionClientV2 with deprecated features will result in an error returned back to the
122calling application during construction of the client.
123
124Users of `AES/CBC` will need to migrate usage to `AES/GCM`.
125Users of `kms` key provider will need to migrate `kms+context`.
126
127DecryptionClientV2 client adds support for the `kms+context` key provider and maintains backwards comparability with
128objects encrypted with the V1 EncryptionClient.
129
130Migrating from V1 to V2 Clients
131
132Examples of how to migrate usage of the V1 clients to the V2 equivalents have been documented as usage examples of
133the NewEncryptionClientV2 and NewDecryptionClientV2 functions.
134
135Please 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
136
137*/
138package s3crypto
139