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