{"id":15710330,"url":"https://github.com/aws/amazon-s3-encryption-client-go","last_synced_at":"2025-10-20T03:32:36.688Z","repository":{"id":207635287,"uuid":"667525707","full_name":"aws/amazon-s3-encryption-client-go","owner":"aws","description":"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).","archived":false,"fork":false,"pushed_at":"2025-02-04T20:46:12.000Z","size":341,"stargazers_count":13,"open_issues_count":3,"forks_count":3,"subscribers_count":8,"default_branch":"main","last_synced_at":"2025-02-04T21:31:50.443Z","etag":null,"topics":["amazon-s3","aws","aws-kms","client-side-encryption","encryption","golang"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/aws.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-07-17T17:50:50.000Z","updated_at":"2025-02-04T20:46:16.000Z","dependencies_parsed_at":"2023-11-16T21:13:36.159Z","dependency_job_id":"d50a7c2a-165b-4b44-a5d4-48455af491ae","html_url":"https://github.com/aws/amazon-s3-encryption-client-go","commit_stats":{"total_commits":97,"total_committers":10,"mean_commits":9.7,"dds":0.5567010309278351,"last_synced_commit":"2f531ed2db2fc089291d5c7962ee4ab36f57c0ed"},"previous_names":["aws/amazon-s3-encryption-client-go"],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aws%2Famazon-s3-encryption-client-go","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aws%2Famazon-s3-encryption-client-go/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aws%2Famazon-s3-encryption-client-go/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aws%2Famazon-s3-encryption-client-go/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aws","download_url":"https://codeload.github.com/aws/amazon-s3-encryption-client-go/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":237261402,"owners_count":19281221,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["amazon-s3","aws","aws-kms","client-side-encryption","encryption","golang"],"created_at":"2024-10-03T21:06:17.270Z","updated_at":"2025-10-20T03:32:34.270Z","avatar_url":"https://github.com/aws.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Amazon S3 Encryption Client for Go V3\n\n[![Go Build status](https://github.com/aws/amazon-s3-encryption-client-go/actions/workflows/go-test.yml/badge.svg?branch=main)](https://github.com/aws/amazon-s3-encryption-client-go/actions/workflows/go-test.yml)  [![Apache V2 License](https://img.shields.io/badge/license-Apache%20V2-blue.svg)](https://github.com/aws/amazon-s3-encryption-client-go/blob/main/LICENSE)\n\nThis library provides an S3 client that supports client-side encryption.\n`amazon-s3-encryption-client-go` is the v3 of the Amazon S3 Encryption Client for the Go programming language.\n\nThe v3 encryption client requires a minimum version of `Go 1.20`.\n\nCheck out the [release notes](https://github.com/aws/amazon-s3-encryption-client-go/blob/main/CHANGELOG.md) for information about the latest bug\nfixes, updates, and features added to the encryption client.\n\nJump To:\n* [Getting Started](#getting-started)\n* [Migration](#migration)\n\n## Maintenance and support for SDK major versions\n\nFor information about maintenance and support for SDK major versions and their underlying dependencies, see the\nfollowing in the AWS SDKs and Tools Shared Configuration and Credentials Reference Guide:\n\n* [AWS SDKs and Tools Maintenance Policy](https://docs.aws.amazon.com/credref/latest/refdocs/maint-policy.html)\n* [AWS SDKs and Tools Version Support Matrix](https://docs.aws.amazon.com/credref/latest/refdocs/version-support-matrix.html)\n\n### Go version support policy\n\nThe v3 Encryption Client follows the upstream [release policy](https://go.dev/doc/devel/release#policy)\nwith an additional six months of support for the most recently deprecated\nlanguage version.\n\n**AWS reserves the right to drop support for unsupported Go versions earlier to\naddress critical security issues.**\n\n## Getting started\nTo get started working with the S3 Encryption Client set up your project for Go modules, and retrieve the client's dependencies with `go get`.\nThis example shows how you can use the v3 encryption client to make a `PutItem` request using a KmsKeyring.\n\n###### Initialize Project\n```sh\n$ mkdir ~/encryptionclient\n$ cd ~/encryptionclient\n$ go mod init encryptionclient\n```\n###### Add SDK Dependencies\n```sh\n$ go get github.com/aws/amazon-s3-encryption-client-go/v3\n```\n\n###### Write Code\nIn your preferred editor add the following content to `main.go`\n\n```go\npackage main\n\nimport (\n\t\"context\"\n\t\"log\"\n\t\"github.com/aws/aws-sdk-go-v2/aws\"\n\t\"github.com/aws/aws-sdk-go-v2/config\"\n\t\"github.com/aws/aws-sdk-go-v2/service/kms\"\n\t\"github.com/aws/aws-sdk-go-v2/service/s3\"\n\t\n\t// Import the materials and client package \n\t\"github.com/aws/amazon-s3-encryption-client-go/v3/client\"\n\t\"github.com/aws/amazon-s3-encryption-client-go/v3/materials\"\n)\n\nfunc main() {\n\tctx := context.Background()\n    // Using the SDK's default configuration, loading additional config\n    // and credentials values from the environment variables, shared\n    // credentials, and shared configuration files\n    cfg, err := config.LoadDefaultConfig(ctx, config.WithRegion(\"us-west-2\"))\n    if err != nil {\n        log.Fatalf(\"unable to load SDK config, %v\", err)\n    }\n\tkey := \"testObjectWithNewEncryptionClient\"\n\tplaintext := \"This is a test.\\n\"\n\t\n\ts3Client := s3.NewFromConfig(cfg)\n\tkmsClient := kms.NewFromConfig(cfg)\n\n\t// Create the keyring and \u0026CMM-long; (\u0026CMM-short;)\n\tcmm, err := materials.NewCryptographicMaterialsManager(materials.NewKmsKeyring(kmsClient, kmsKeyArn, func(options *materials.KeyringOptions) {\n\t\toptions.EnableLegacyWrappingAlgorithms = false\n\t}))\n\tif err != nil {\n\t\tlog.Fatalf(\"error while creating new CMM\")\n\t}\n\n\ts3EncryptionClient, err := client.New(s3Client, cmm)\n\t\n\t_, err = s3EncryptionClient.PutObject(ctx, \u0026s3Client.PutObjectInput{\n\t\tBucket: aws.String(bucket),\n\t\tKey:    aws.String(key),\n\t\tBody:   bytes.NewReader([]byte(plaintext)),\n\t})\n\tif err != nil {\n\t\tlog.Fatalf(\"error calling putObject: %v\", err)\n\t}\n}\n```\n\n## Migration\n\nThis version of the library supports reading encrypted objects from previous versions.\nIt also supports writing objects with non-legacy algorithms.\nThe list of legacy modes and operations will be provided below.\n\n### Examples\n#### V2 KMS to V3\n\nThe following example demonstrates how to migrate a version v2 application that uses\nthe `NewKMSContextKeyGenerator` kms-key provider with a material\ndescription and `AESGCMContentCipherBuilderV2` content cipher to\nversion v3 of the S3 Encryption Client for Go.\n\n```go\nfunc KmsContextV2toV3GCMExample() error {\n \tbucket := LoadBucket()\n \tkmsKeyAlias := LoadAwsKmsAlias()\n \n \tobjectKey := \"my-object-key\"\n \tregion := \"us-west-2\"\n \tplaintext := \"This is an example.\\n\"\n \n \t// Create an S3EC Go v2 encryption client\n \t// using the KMS client from AWS SDK for Go v1\n\tsessKms, err := sessionV1.NewSession(\u0026awsV1.Config{\n        Region: aws.String(region),\n    })\n \n \tkmsSvc := kmsV1.New(sessKms)\n \thandler := s3cryptoV2.NewKMSContextKeyGenerator(kmsSvc, kmsKeyAlias, s3cryptoV2.MaterialDescription{})\n \tbuilder := s3cryptoV2.AESGCMContentCipherBuilderV2(handler)\n \tencClient, err := s3cryptoV2.NewEncryptionClientV2(sessKms, builder)\n \tif err != nil {\n \t\tlog.Fatalf(\"error creating new v2 client: %v\", err)\n \t}\n \n \t// Encrypt using KMS+Context and AES-GCM content cipher\n \t_, err = encClient.PutObject(s3V1.PutObjectInput{\n \t\tBucket: aws.String(bucket),\n \t\tKey:    aws.String(objectKey),\n \t\tBody:   bytes.NewReader([]byte(plaintext)),\n \t})\n \tif err != nil {\n \t\tlog.Fatalf(\"error calling putObject: %v\", err)\n \t}\n \tfmt.Printf(\"successfully uploaded file to %s/%s\\n\", bucket, key)\n \n \t// Create an S3EC Go v3 client\n \t// using the KMS client from AWS SDK for Go v2\n \tctx := context.Background()\n \tcfg, err := config.LoadDefaultConfig(ctx,\n \t\tconfig.WithRegion(region),\n \t)\n \n \tkmsV2 := kms.NewFromConfig(cfg)\n \tcmm, err := materials.NewCryptographicMaterialsManager(materials.NewKmsKeyring(kmsV2, kmsKeyAlias))\n \tif err != nil {\n \t\tt.Fatalf(\"error while creating new CMM\")\n \t}\n \n \ts3V2 := s3.NewFromConfig(cfg)\n \ts3ecV3, err := client.New(s3V2, cmm)\n \n \tresult, err := s3ecV3.GetObject(ctx, s3.GetObjectInput{\n \t\tBucket: aws.String(bucket),\n \t\tKey:    aws.String(objectKey),\n \t})\n \tif err != nil {\n \t\tt.Fatalf(\"error while decrypting: %v\", err)\n \t}\n```\n\n#### Enable legacy decryption modes\nThe `enableLegacyUnauthenticatedModes` flag enables the S3 Encryption Client to decrypt\nencrypted objects with a fully supported or legacy encryption algorithm.\nVersion V3 of the S3 Encryption Client uses one of the fully supported wrapping algorithms and the\nwrapping key you specify to encrypt and decrypt the data keys. The\n`enableLegacyWrappingAlgorithms` flag enables the S3 Encryption Client to decrypt\nencrypted data keys with a fully supported or legacy wrapping algorithm.\n\n```go\ncmm, err := materials.NewCryptographicMaterialsManager(materials.NewKmsKeyring(kmsClient, kmsKeyArn, func(options *materials.KeyringOptions) {\n     options.EnableLegacyWrappingAlgorithms = true\n })\n \n if err != nil {\n \tt.Fatalf(\"error while creating new CMM\")\n }\n \n client, err := client.New(s3Client, cmm, func(clientOptions *client.EncryptionClientOptions) {\n \t\tclientOptions.EnableLegacyUnauthenticatedModes = true\n })\n \n if err != nil {\n \t// handle error\n }\n```\n\n### Legacy Algorithms and Modes\n#### Content Encryption\n* AES/CBC\n#### Key Wrap Encryption\n* KMS (without context)\n\n## Security\n\nSee [CONTRIBUTING](CONTRIBUTING.md#security-issue-notifications) for more information.\n\n## License\n\nThis project is licensed under the Apache-2.0 License.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faws%2Famazon-s3-encryption-client-go","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faws%2Famazon-s3-encryption-client-go","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faws%2Famazon-s3-encryption-client-go/lists"}