client

Documentation

Overview

Package client provides the entrypoint for using AWS Encryption SDK for Go.

Index

• Constants
• Variables
• type BaseClient
• type Client
  • func NewClient() *Client
  • func NewClientWithConfig(cfg *clientconfig.ClientConfig) *Client
  • func (c *Client) Decrypt(ctx context.Context, ciphertext []byte, ...) ([]byte, format.MessageHeader, error)
  • func (c *Client) Encrypt(ctx context.Context, source []byte, ec suite.EncryptionContext, ...) ([]byte, format.MessageHeader, error)
• type DecryptOptionFunc
  • func WithDecryptionHandler(...) DecryptOptionFunc
• type DecryptOptions
• type EncryptOptionFunc
  • func WithAlgorithm(alg *suite.AlgorithmSuite) EncryptOptionFunc
  • func WithEncryptionHandler(...) EncryptOptionFunc
  • func WithFrameLength(frameLength int) EncryptOptionFunc
• type EncryptOptions

Examples

• NewClient
• NewClientWithConfig

Constants

const (
	// DefaultFrameLength default frame length for encryption.
	DefaultFrameLength = int(4096)
)

Variables

var ErrInvalidConfig = errors.New("client config invalid")

ErrInvalidConfig is returned when client configuration is invalid.

Types

type BaseClient

type BaseClient interface {
	Encrypt(ctx context.Context, source []byte, ec suite.EncryptionContext, materialsManager model.CryptoMaterialsManager, optFns ...EncryptOptionFunc) ([]byte, format.MessageHeader, error)
	Decrypt(ctx context.Context, ciphertext []byte, materialsManager model.CryptoMaterialsManager, optFns ...DecryptOptionFunc) ([]byte, format.MessageHeader, error)
	// contains filtered or unexported methods
}

type Client

type Client struct {
	// contains filtered or unexported fields
}

func NewClient

func NewClient() *Client

NewClient returns a new client with default clientconfig.ClientConfig config

Example

package main

import (
	"fmt"

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

func main() {
	var c = client.NewClient()
	fmt.Printf("%#v", *c)
}

Output:

client.Client{config:clientconfig.ClientConfig{commitmentPolicy:3, maxEncryptedDataKeys:10}}

func NewClientWithConfig

func NewClientWithConfig(cfg *clientconfig.ClientConfig) *Client

NewClientWithConfig returns a new client with cfg clientconfig.ClientConfig

Example

package main

import (
	"fmt"

	"github.com/chainifynet/aws-encryption-sdk-go/pkg/client"
	"github.com/chainifynet/aws-encryption-sdk-go/pkg/clientconfig"
	"github.com/chainifynet/aws-encryption-sdk-go/pkg/suite"
)

func main() {
	cfg, err := clientconfig.NewConfigWithOpts(
		clientconfig.WithCommitmentPolicy(suite.CommitmentPolicyRequireEncryptRequireDecrypt),
		clientconfig.WithMaxEncryptedDataKeys(2),
	)
	if err != nil {
		panic(err)
	}
	var c = client.NewClientWithConfig(cfg)
	fmt.Printf("%#v", *c)
}

Output:

client.Client{config:clientconfig.ClientConfig{commitmentPolicy:3, maxEncryptedDataKeys:2}}

func (*Client) Decrypt

func (c *Client) Decrypt(ctx context.Context, ciphertext []byte, materialsManager model.CryptoMaterialsManager, optFns ...DecryptOptionFunc) ([]byte, format.MessageHeader, error)

Decrypt decrypts the given ciphertext using the provided materials manager. It returns the decrypted plaintext and the message header.

Parameters:

• ctx: context.Context.
• ciphertext []byte: The data to decrypt.
• materialsManager model.CryptoMaterialsManager: The manager that provides the cryptographic materials.
• optFns DecryptOptionFunc: A variadic set of optional functions for configuring decryption options such as custom decryption handler.

Returns:

• []byte: The decrypted data.
• format.MessageHeader: The header of the encrypted message.
• error: An error if decryption fails.

func (*Client) Encrypt

func (c *Client) Encrypt(ctx context.Context, source []byte, ec suite.EncryptionContext, materialsManager model.CryptoMaterialsManager, optFns ...EncryptOptionFunc) ([]byte, format.MessageHeader, error)

Encrypt encrypts the given source data using the provided materials manager and encryption context. By default, it uses the algorithm suite.AES_256_GCM_HKDF_SHA512_COMMIT_KEY_ECDSA_P384 and a frame length of 4096.

This behavior can be modified by passing in optional functional arguments using EncryptOptionFunc. It returns the ciphertext data along with the message header.

Parameters:

• ctx context.Context: The context for the operation.
• source []byte: The data to encrypt.
• ec suite.EncryptionContext: The encryption context, a set of key-value pairs that are cryptographically bound to the encrypted data.
• materialsManager model.CryptoMaterialsManager: The manager that provides the cryptographic materials.
• optFns EncryptOptionFunc: A variadic set of optional functions for configuring encryption options such as custom algorithm or frame length.

Returns:

• []byte: The encrypted data.
• format.MessageHeader: The header of the encrypted message.
• error: An error if encryption fails.

Example usage:

ciphertext, header, err := client.Encrypt(context.TODO(), plaintext, encryptionContext, materialsManager,
    WithAlgorithm(customAlgorithm),
    WithFrameLength(1024))
if err != nil {
    // handle error
}

Notes:

1. The Encrypt function allows customization of the encryption process through its optional parameters.
2. The WithAlgorithm and WithFrameLength functions can be used to specify an encryption algorithm and frame length, respectively. If these functions are not used, default values are applied.

type DecryptOptionFunc

type DecryptOptionFunc func(o *DecryptOptions) error

DecryptOptionFunc is a function type that applies a configuration option to an DecryptOptions struct. It is used to customize the decryption process by setting various options in DecryptOptions.

Each function of this type takes a pointer to an DecryptOptions struct and modifies it accordingly. It returns an error if the provided option is invalid or cannot be applied.

Use WithDecryptionHandler to create DecryptOptionFunc function.

func WithDecryptionHandler

func WithDecryptionHandler(h func(config crypto.DecrypterConfig, cmm model.CryptoMaterialsManager) model.DecryptionHandler) DecryptOptionFunc

WithDecryptionHandler returns an DecryptOptionFunc that sets the decryption handler in DecryptOptions. This function allows the caller to specify a custom decryption handler.

Used mainly for testing purposes.

Parameters:

• h: A function that returns model.DecryptionHandler.

type DecryptOptions

type DecryptOptions struct {
	// Handler specifies a function that creates model.DecryptionHandler decryption handler.
	Handler func(config crypto.DecrypterConfig, cmm model.CryptoMaterialsManager) model.DecryptionHandler
}

DecryptOptions defines the configuration options for the decryption process.

Fields:

• Handler: Specifies a function that creates model.DecryptionHandler decryption handler. If not set, a default decrypter.New function is used.

type EncryptOptionFunc

type EncryptOptionFunc func(o *EncryptOptions) error

EncryptOptionFunc is a function type that applies a configuration option to an EncryptOptions struct. It is used to customize the encryption process by setting various options in EncryptOptions.

Each function of this type takes a pointer to an EncryptOptions struct and modifies it accordingly. It returns an error if the provided option is invalid or cannot be applied.

Use WithAlgorithm and WithFrameLength to create EncryptOptionFunc functions.

func WithAlgorithm

func WithAlgorithm(alg *suite.AlgorithmSuite) EncryptOptionFunc

WithAlgorithm returns an EncryptOptionFunc that sets the encryption algorithm in EncryptOptions. This function allows the caller to specify a custom algorithm for encryption.

Parameters:

• alg suite.AlgorithmSuite: suite.AlgorithmSuite which defines the encryption algorithm to be used.

Returns:

• EncryptOptionFunc: A function that sets the Algorithm field in EncryptOptions.

Errors:

• If alg is nil, it returns an error indicating that the algorithm must not be nil.

func WithEncryptionHandler

func WithEncryptionHandler(h func(config crypto.EncrypterConfig, cmm model.CryptoMaterialsManager) model.EncryptionHandler) EncryptOptionFunc

WithEncryptionHandler returns an EncryptOptionFunc that sets the encryption handler in EncryptOptions. This function allows the caller to specify a custom encryption handler.

Used mainly for testing purposes.

Parameters:

• h: A function that returns model.EncryptionHandler.

func WithFrameLength

func WithFrameLength(frameLength int) EncryptOptionFunc

WithFrameLength returns an EncryptOptionFunc that sets the frame length in EncryptOptions. This function allows the caller to specify a custom frame length for encryption, within allowed limits.

Parameters:

• frameLength int: The frame length to be set for encryption.

Returns:

• EncryptOptionFunc: A function that sets the FrameLength field in EncryptOptions.

Errors:

• If frameLength is less than suite.MinFrameSize (128) or greater than suite.MaxFrameSize (2147483647), it returns an error indicating that the frame length is out of range.
• If frameLength is not a multiple of the suite.BlockSize (128) of the crypto algorithm, it returns an error indicating that.

type EncryptOptions

type EncryptOptions struct {
	// Algorithm that defines the encryption algorithm to be used.
	Algorithm *suite.AlgorithmSuite
	// FrameLength specifies the frame length for encryption.
	FrameLength int
	// Handler specifies a function that creates model.EncryptionHandler encryption handler.
	Handler func(config crypto.EncrypterConfig, cmm model.CryptoMaterialsManager) model.EncryptionHandler
}

EncryptOptions defines the configuration options for the encryption process. It contains settings such as the algorithm to use for encryption and the frame length.

Fields:

• Algorithm suite.AlgorithmSuite: AlgorithmSuite that defines the encryption algorithm to be used. If nil, a default suite.AES_256_GCM_HKDF_SHA512_COMMIT_KEY_ECDSA_P384 algorithm is used.
• FrameLength int: Specifies the frame length for encryption. If not set, a default value of DefaultFrameLength is used.
• Handler: Specifies a function that creates model.EncryptionHandler encryption handler. If not set, a default encrypter.New function is used.