https://github.com/aws/amazon-s3-encryption-client-go
The Amazon S3 Encryption Client is a client-side encryption library that enables you to encrypt an object locally to ensure its security before passing it to Amazon Simple Storage Service (Amazon S3).
https://github.com/aws/amazon-s3-encryption-client-go
amazon-s3 aws aws-kms client-side-encryption encryption golang
Last synced: 8 months ago
JSON representation
The Amazon S3 Encryption Client is a client-side encryption library that enables you to encrypt an object locally to ensure its security before passing it to Amazon Simple Storage Service (Amazon S3).
- Host: GitHub
- URL: https://github.com/aws/amazon-s3-encryption-client-go
- Owner: aws
- License: apache-2.0
- Created: 2023-07-17T17:50:50.000Z (almost 3 years ago)
- Default Branch: main
- Last Pushed: 2025-02-04T20:46:12.000Z (over 1 year ago)
- Last Synced: 2025-02-04T21:31:50.443Z (over 1 year ago)
- Topics: amazon-s3, aws, aws-kms, client-side-encryption, encryption, golang
- Language: Go
- Homepage:
- Size: 333 KB
- Stars: 13
- Watchers: 8
- Forks: 3
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
README
# Amazon S3 Encryption Client for Go V3
[](https://github.com/aws/amazon-s3-encryption-client-go/actions/workflows/go-test.yml) [](https://github.com/aws/amazon-s3-encryption-client-go/blob/main/LICENSE)
This library provides an S3 client that supports client-side encryption.
`amazon-s3-encryption-client-go` is the v3 of the Amazon S3 Encryption Client for the Go programming language.
The v3 encryption client requires a minimum version of `Go 1.20`.
Check out the [release notes](https://github.com/aws/amazon-s3-encryption-client-go/blob/main/CHANGELOG.md) for information about the latest bug
fixes, updates, and features added to the encryption client.
Jump To:
* [Getting Started](#getting-started)
* [Migration](#migration)
## Maintenance and support for SDK major versions
For information about maintenance and support for SDK major versions and their underlying dependencies, see the
following in the AWS SDKs and Tools Shared Configuration and Credentials Reference Guide:
* [AWS SDKs and Tools Maintenance Policy](https://docs.aws.amazon.com/credref/latest/refdocs/maint-policy.html)
* [AWS SDKs and Tools Version Support Matrix](https://docs.aws.amazon.com/credref/latest/refdocs/version-support-matrix.html)
### Go version support policy
The v3 Encryption Client follows the upstream [release policy](https://go.dev/doc/devel/release#policy)
with an additional six months of support for the most recently deprecated
language version.
**AWS reserves the right to drop support for unsupported Go versions earlier to
address critical security issues.**
## Getting started
To get started working with the S3 Encryption Client set up your project for Go modules, and retrieve the client's dependencies with `go get`.
This example shows how you can use the v3 encryption client to make a `PutItem` request using a KmsKeyring.
###### Initialize Project
```sh
$ mkdir ~/encryptionclient
$ cd ~/encryptionclient
$ go mod init encryptionclient
```
###### Add SDK Dependencies
```sh
$ go get github.com/aws/amazon-s3-encryption-client-go/v3
```
###### Write Code
In your preferred editor add the following content to `main.go`
```go
package main
import (
"context"
"log"
"github.com/aws/aws-sdk-go-v2/aws"
"github.com/aws/aws-sdk-go-v2/config"
"github.com/aws/aws-sdk-go-v2/service/kms"
"github.com/aws/aws-sdk-go-v2/service/s3"
// Import the materials and client package
"github.com/aws/amazon-s3-encryption-client-go/v3/client"
"github.com/aws/amazon-s3-encryption-client-go/v3/materials"
)
func main() {
ctx := context.Background()
// Using the SDK's default configuration, loading additional config
// and credentials values from the environment variables, shared
// credentials, and shared configuration files
cfg, err := config.LoadDefaultConfig(ctx, config.WithRegion("us-west-2"))
if err != nil {
log.Fatalf("unable to load SDK config, %v", err)
}
key := "testObjectWithNewEncryptionClient"
plaintext := "This is a test.\n"
s3Client := s3.NewFromConfig(cfg)
kmsClient := kms.NewFromConfig(cfg)
// Create the keyring and &CMM-long; (&CMM-short;)
cmm, err := materials.NewCryptographicMaterialsManager(materials.NewKmsKeyring(kmsClient, kmsKeyArn, func(options *materials.KeyringOptions) {
options.EnableLegacyWrappingAlgorithms = false
}))
if err != nil {
log.Fatalf("error while creating new CMM")
}
s3EncryptionClient, err := client.New(s3Client, cmm)
_, err = s3EncryptionClient.PutObject(ctx, &s3Client.PutObjectInput{
Bucket: aws.String(bucket),
Key: aws.String(key),
Body: bytes.NewReader([]byte(plaintext)),
})
if err != nil {
log.Fatalf("error calling putObject: %v", err)
}
}
```
## Migration
This version of the library supports reading encrypted objects from previous versions.
It also supports writing objects with non-legacy algorithms.
The list of legacy modes and operations will be provided below.
### Examples
#### V2 KMS to V3
The following example demonstrates how to migrate a version v2 application that uses
the `NewKMSContextKeyGenerator` kms-key provider with a material
description and `AESGCMContentCipherBuilderV2` content cipher to
version v3 of the S3 Encryption Client for Go.
```go
func KmsContextV2toV3GCMExample() error {
bucket := LoadBucket()
kmsKeyAlias := LoadAwsKmsAlias()
objectKey := "my-object-key"
region := "us-west-2"
plaintext := "This is an example.\n"
// Create an S3EC Go v2 encryption client
// using the KMS client from AWS SDK for Go v1
sessKms, err := sessionV1.NewSession(&awsV1.Config{
Region: aws.String(region),
})
kmsSvc := kmsV1.New(sessKms)
handler := s3cryptoV2.NewKMSContextKeyGenerator(kmsSvc, kmsKeyAlias, s3cryptoV2.MaterialDescription{})
builder := s3cryptoV2.AESGCMContentCipherBuilderV2(handler)
encClient, err := s3cryptoV2.NewEncryptionClientV2(sessKms, builder)
if err != nil {
log.Fatalf("error creating new v2 client: %v", err)
}
// Encrypt using KMS+Context and AES-GCM content cipher
_, err = encClient.PutObject(s3V1.PutObjectInput{
Bucket: aws.String(bucket),
Key: aws.String(objectKey),
Body: bytes.NewReader([]byte(plaintext)),
})
if err != nil {
log.Fatalf("error calling putObject: %v", err)
}
fmt.Printf("successfully uploaded file to %s/%s\n", bucket, key)
// Create an S3EC Go v3 client
// using the KMS client from AWS SDK for Go v2
ctx := context.Background()
cfg, err := config.LoadDefaultConfig(ctx,
config.WithRegion(region),
)
kmsV2 := kms.NewFromConfig(cfg)
cmm, err := materials.NewCryptographicMaterialsManager(materials.NewKmsKeyring(kmsV2, kmsKeyAlias))
if err != nil {
t.Fatalf("error while creating new CMM")
}
s3V2 := s3.NewFromConfig(cfg)
s3ecV3, err := client.New(s3V2, cmm)
result, err := s3ecV3.GetObject(ctx, s3.GetObjectInput{
Bucket: aws.String(bucket),
Key: aws.String(objectKey),
})
if err != nil {
t.Fatalf("error while decrypting: %v", err)
}
```
#### Enable legacy decryption modes
The `enableLegacyUnauthenticatedModes` flag enables the S3 Encryption Client to decrypt
encrypted objects with a fully supported or legacy encryption algorithm.
Version V3 of the S3 Encryption Client uses one of the fully supported wrapping algorithms and the
wrapping key you specify to encrypt and decrypt the data keys. The
`enableLegacyWrappingAlgorithms` flag enables the S3 Encryption Client to decrypt
encrypted data keys with a fully supported or legacy wrapping algorithm.
```go
cmm, err := materials.NewCryptographicMaterialsManager(materials.NewKmsKeyring(kmsClient, kmsKeyArn, func(options *materials.KeyringOptions) {
options.EnableLegacyWrappingAlgorithms = true
})
if err != nil {
t.Fatalf("error while creating new CMM")
}
client, err := client.New(s3Client, cmm, func(clientOptions *client.EncryptionClientOptions) {
clientOptions.EnableLegacyUnauthenticatedModes = true
})
if err != nil {
// handle error
}
```
### Legacy Algorithms and Modes
#### Content Encryption
* AES/CBC
#### Key Wrap Encryption
* KMS (without context)
## Security
See [CONTRIBUTING](CONTRIBUTING.md#security-issue-notifications) for more information.
## License
This project is licensed under the Apache-2.0 License.