sdk

README

AWS Encryption SDK for Go

This project is an implementation of the AWS Encryption SDK for the Go programming language, providing a set of libraries for developers to easily add encryption and decryption functionality to their Go applications. This implementation is inspired by the aws-encryption-sdk-python and follows the AWS Encryption SDK specification closely.

Motivation

The motivation behind this project was the absence of a Go implementation of the AWS Encryption SDK. This SDK aims to fill that gap, offering Go developers the tools to implement encryption according to AWS standards.

Features

• Support for Message Format Version 1 and 2 and related algorithms.
• AWS KMS Master Key Provider with a discovery filter.
• AWS KMS Multi-Region Keys using MRK-aware provider in Discovery or Strict mode.
• Raw Master Key provider using static keys.
• Comprehensive end-to-end tests ensuring compatibility with aws-encryption-sdk-cli.
• 100% code coverage with tests.

Current Limitations

• Does not support the Caching Materials Manager feature yet.
• Does not support KMS aliases at this stage.
• Raw Master Key provider does not support RSA encryption.
• Only framed content type is supported.

Requirements

• Go v1.21 or later.
• AWS SDK for Go v2

Installation

To install the AWS Encryption SDK for Go, use the following command:

$ go get github.com/chainifynet/aws-encryption-sdk-go@latest

Usage

This SDK provides a straightforward interface for encrypting and decrypting data.

For advanced use cases, check examples.

Setting Up the Client

First, set up the client with the necessary configuration.

Default Client Configuration

import (
	"github.com/chainifynet/aws-encryption-sdk-go/client"
	"github.com/chainifynet/aws-encryption-sdk-go/clientconfig"
	"github.com/chainifynet/aws-encryption-sdk-go/materials"
	"github.com/chainifynet/aws-encryption-sdk-go/providers/kmsprovider"
	"github.com/chainifynet/aws-encryption-sdk-go/providers/rawprovider"
	"github.com/chainifynet/aws-encryption-sdk-go/suite"
)

// setup Encryption SDK client with default config
sdkClient := client.NewClient()

Custom Client Configuration (advanced)

You can specify the commitment policy and the limit of maximum encrypted data keys.

// setup Encryption SDK client with custom client config
cfg, err := clientconfig.NewConfigWithOpts(
	clientconfig.WithCommitmentPolicy(suite.CommitmentPolicyRequireEncryptRequireDecrypt),
	clientconfig.WithMaxEncryptedDataKeys(3),
)
if err != nil {
	panic(err) // handle error
}

// setup Encryption SDK client with a custom config
sdkClient := client.NewClientWithConfig(cfg)

Prepare the Key Provider

Raw Key Provider using static keys

rawKeyProvider, err := rawprovider.NewWithOpts(
	"raw",
	providers.WithStaticKey("static1", []byte("superSecureKeySecureKey32bytes32")),
)
if err != nil {
	panic("raw key provider setup failed") // handle error
}

KMS Key Provider using KMS CMKs

You can optionally enable discovery or specify a discovery filter.

// KMS key ARN to be used for encryption and decryption
kmsKeyArn := "arn:aws:kms:us-east-1:123456789012:key/12345678-1234-1234-1234-123456789012"

// setup KMS key provider
kmsKeyProvider, err := kmsprovider.New(kmsKeyArn)
if err != nil {
	panic("kms key provider setup failed") // handle error
}

Create the Crypto Materials Manager

You can use either the KMS Key Provider, Raw Key Provider, or both combining them.

Crypto Materials Manager with the Raw Key Provider

cmm, err := materials.NewDefault(rawKeyProvider)
if err != nil {
	panic("materials manager setup failed") // handle error
}

Crypto Materials Manager with KMS Key Provider

cmm, err := materials.NewDefault(kmsKeyProvider)
if err != nil {
	panic("materials manager setup failed") // handle error
}

Crypto Materials Manager using both KMS and Raw Key Providers

cmm, err := materials.NewDefault(kmsKeyProvider, rawKeyProvider)
if err != nil {
	panic("materials manager setup failed") // handle error
}

Encrypting Data

To encrypt data, call the Encrypt method on the client.

// define the encryption context, which is a set of key-value pairs that represent additional authenticated data
encryptionContext := map[string]string{
	"purpose": "test",
}

// data to encrypt
secretData := []byte("secret data to encrypt")

// encrypt data
ciphertext, header, err := sdkClient.Encrypt(
	context.TODO(),
	secretData,
	encryptionContext,
	cmm,
)
if err != nil {
    panic("encryption failed") // handle error
}

Decrypting Data

To decrypt data, use the Decrypt method on the client.

// decrypt data
plaintext, header, err := sdkClient.Decrypt(context.TODO(), ciphertext, cmm)
if err != nil {
	panic("decryption failed") // handle error
}

TODO

• Add support for Caching Materials Manager.
• Add support for Message Format Version 1 #170.
• Add support for AWS KMS Multi-Region Keys #46.
• Add support for KMS aliases.
• Cover providers package with tests.
• Cover keys package with tests.
• Cover materials package with tests.
• GoDoc documentation #294.
• Streamlined encryption and decryption.

Support and Contributions

If you encounter any issues or would like to contribute to the project, please submit an issue or pull request on GitHub.

License

This SDK is licensed under the Apache License 2.0. See the LICENSE file for details.

For more information on how to use this SDK, please refer to the example directory and the detailed API reference in the documentation.

---

Stay tuned for further updates and features. Contributions and feedback are welcome!

Documentation

Overview

Package sdk is the Unofficial Go SDK implementation of the AWS Encryption SDK.

Getting started

To install the AWS Encryption SDK for Go, use the following command:

go get github.com/chainifynet/aws-encryption-sdk-go@latest

Usage

The following example demonstrates how to use SDK to encrypt and decrypt data using a static key.

package main

import (
	"context"
	"fmt"

	"github.com/chainifynet/aws-encryption-sdk-go/pkg/client"
	"github.com/chainifynet/aws-encryption-sdk-go/pkg/materials"
	"github.com/chainifynet/aws-encryption-sdk-go/pkg/providers/rawprovider"
)

func main() {
	// static key to use for encryption and decryption
	staticKey1 := []byte("superSecureKeySecureKey32bytes32")

	// data to encrypt
	secretData := []byte("secret data to encrypt")

	// setup Encryption SDK client with default configuration
	sdkClient := client.NewClient()

	// setup Raw Key provider
	rawKeyProvider, err := rawprovider.NewWithOpts(
		"raw",
		rawprovider.WithStaticKey("static1", staticKey1),
	)
	if err != nil {
		panic(err) // handle error
	}

	// setup crypto materials manager
	cmm, err := materials.NewDefault(rawKeyProvider)
	if err != nil {
		panic(err) // handle error
	}

	// encrypt data without encryption context passing nil as the third argument
	encrypted, header, err := sdkClient.Encrypt(context.TODO(), secretData, nil, cmm)
	if err != nil {
		panic(err) // handle error
	}

	fmt.Printf("encrypted encryption context: %v\n", header.AADData().EncryptionContext())

	// decrypt "encrypted" data
	decrypted, _, err := sdkClient.Decrypt(context.TODO(), encrypted, cmm)
	if err != nil {
		panic(err) // handle error
	}

	fmt.Printf("decrypted data: %s\n", decrypted)

	// verify that "decrypted" plaintext is identical to the original secret data
	if string(decrypted) != string(secretData) {
		panic("decrypted data does not match with the original data")
	}
}