materials

Documentation

Index

• Constants
• type CryptographicMaterials
• type CryptographicMaterialsManager
• type DataKey
• type DecryptMaterialsRequest
• type DecryptionMaterials
  • func NewDecryptionMaterials(req DecryptMaterialsRequest) (*DecryptionMaterials, error)
• type DefaultCryptographicMaterialsManager
  • func NewCryptographicMaterialsManager(keyring Keyring) (*DefaultCryptographicMaterialsManager, error)
  • func (cmm *DefaultCryptographicMaterialsManager) DecryptMaterials(ctx context.Context, req DecryptMaterialsRequest) (*CryptographicMaterials, error)
  • func (cmm *DefaultCryptographicMaterialsManager) GetEncryptionMaterials(ctx context.Context, matDesc MaterialDescription) (*CryptographicMaterials, error)
• type EncryptionMaterials
  • func NewEncryptionMaterials() *EncryptionMaterials
• type Keyring
• type KeyringOptions
• type KmsAPIClient
• type KmsAnyKeyKeyring
  • func NewKmsDecryptOnlyAnyKeyKeyring(apiClient KmsAPIClient, optFns ...func(options *KeyringOptions)) *KmsAnyKeyKeyring
  • func (k *KmsAnyKeyKeyring) OnDecrypt(ctx context.Context, materials *DecryptionMaterials, encryptedDataKey DataKey) (*CryptographicMaterials, error)
  • func (k *KmsAnyKeyKeyring) OnEncrypt(ctx context.Context, materials *EncryptionMaterials) (*CryptographicMaterials, error)
• type KmsKeyring
  • func NewKmsKeyring(apiClient KmsAPIClient, kmsKeyId string, ...) *KmsKeyring
  • func (k *KmsKeyring) OnDecrypt(ctx context.Context, materials *DecryptionMaterials, encryptedDataKey DataKey) (*CryptographicMaterials, error)
  • func (k *KmsKeyring) OnEncrypt(ctx context.Context, materials *EncryptionMaterials) (*CryptographicMaterials, error)
• type MaterialDescription
  • func (md MaterialDescription) Clone() (clone MaterialDescription)
  • func (md *MaterialDescription) DecodeDescription(b []byte) error
  • func (md *MaterialDescription) EncodeDescription() ([]byte, error)

Constants

const (
	GcmTagSizeBits = "128"
	// KMSKeyring is a constant used during decryption to build a KMS key handler.
	KMSKeyring = "kms"
	// KMSContextKeyring is a constant used during decryption to build a kms+context keyring
	KMSContextKeyring = "kms+context"

	// GrantToken is the key used to store the grant tokens in the context. They are used to avoid eventual consistency authorization issues when calling KMS APIs
	GrantTokens = "GrantTokens"
)

Types

type CryptographicMaterials

type CryptographicMaterials struct {
	Key                 []byte
	IV                  []byte
	KeyringAlgorithm    string
	CEKAlgorithm        string
	TagLength           string
	MaterialDescription MaterialDescription
	// EncryptedKey should be populated when calling GenerateCipherData
	EncryptedKey []byte
}

CryptographicMaterials is used for content encryption. It is used for storing the metadata of the encrypted content.

type CryptographicMaterialsManager

type CryptographicMaterialsManager interface {
	GetEncryptionMaterials(ctx context.Context, matDesc MaterialDescription) (*CryptographicMaterials, error)
	DecryptMaterials(ctx context.Context, req DecryptMaterialsRequest) (*CryptographicMaterials, error)
}

CryptographicMaterialsManager (CMM) assembles the cryptographic materials used to encrypt and decrypt the encrypted objects.

type DataKey

type DataKey struct {
	KeyMaterial      []byte
	EncryptedDataKey []byte
	DataKeyAlgorithm string
}

type DecryptMaterialsRequest

type DecryptMaterialsRequest struct {
	CipherKey  []byte
	Iv         []byte
	MatDesc    string
	KeyringAlg string
	CekAlg     string
	TagLength  string
}

DecryptMaterialsRequest contains the information required to assemble the DecryptionMaterials which are used by Keyring.OnDecrypt to decrypt the encrypted data key.

type DecryptionMaterials

type DecryptionMaterials struct {
	DataKey             DataKey
	ContentIV           []byte //base64 decoded content IV
	MaterialDescription MaterialDescription
	ContentAlgorithm    string
	TagLength           string
}

func NewDecryptionMaterials

func NewDecryptionMaterials(req DecryptMaterialsRequest) (*DecryptionMaterials, error)

type DefaultCryptographicMaterialsManager

type DefaultCryptographicMaterialsManager struct {
	Keyring *Keyring
}

DefaultCryptographicMaterialsManager provides support for encrypting and decrypting S3 objects using the configured Keyring.

func NewCryptographicMaterialsManager

func NewCryptographicMaterialsManager(keyring Keyring) (*DefaultCryptographicMaterialsManager, error)

NewCryptographicMaterialsManager creates a new DefaultCryptographicMaterialsManager with the given Keyring. The Keyring provided must not be nil. If Keyring is nil, NewCryptographicMaterialsManager will return error.

func (*DefaultCryptographicMaterialsManager) DecryptMaterials

func (cmm *DefaultCryptographicMaterialsManager) DecryptMaterials(ctx context.Context, req DecryptMaterialsRequest) (*CryptographicMaterials, error)

DecryptMaterials uses the provided DecryptMaterialsRequest to assemble DecryptionMaterials which are used by Keyring.OnDecrypt to decrypt the encrypted data key.

func (*DefaultCryptographicMaterialsManager) GetEncryptionMaterials

func (cmm *DefaultCryptographicMaterialsManager) GetEncryptionMaterials(ctx context.Context, matDesc MaterialDescription) (*CryptographicMaterials, error)

GetEncryptionMaterials assembles the required EncryptionMaterials and then calls Keyring.OnEncrypt to encrypt the materials.

type EncryptionMaterials

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

func NewEncryptionMaterials

func NewEncryptionMaterials() *EncryptionMaterials

type Keyring

type Keyring interface {
	// OnEncrypt generates/encrypts a data key for use with content encryption
	OnEncrypt(ctx context.Context, materials *EncryptionMaterials) (*CryptographicMaterials, error)
	// OnDecrypt decrypts the encryptedDataKeys and returns them in materials
	// for use with content decryption
	OnDecrypt(ctx context.Context, materials *DecryptionMaterials, encryptedDataKey DataKey) (*CryptographicMaterials, error)
}

Keyring implementations are responsible for encrypting/decrypting data keys using some kind of key material. Keyring implementations MAY support decryption-only (i.e. for legacy algorithms) or both encryption (including data key generation) and decryption.

type KeyringOptions

type KeyringOptions struct {
	EnableLegacyWrappingAlgorithms bool
}

KeyringOptions is for additional configuration on Keyring types to perform additional behaviors. When EnableLegacyWrappingAlgorithms is set to true, the Keyring MAY decrypt objects encrypted using legacy wrapping algorithms such as KMS v1.

type KmsAPIClient

type KmsAPIClient interface {
	GenerateDataKey(context.Context, *kms.GenerateDataKeyInput, ...func(*kms.Options)) (*kms.GenerateDataKeyOutput, error)
	Decrypt(context.Context, *kms.DecryptInput, ...func(*kms.Options)) (*kms.DecryptOutput, error)
}

KmsAPIClient is a client that implements the GenerateDataKey and Decrypt operations

type KmsAnyKeyKeyring

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

KmsAnyKeyKeyring is decrypt-only.

func NewKmsDecryptOnlyAnyKeyKeyring

func NewKmsDecryptOnlyAnyKeyKeyring(apiClient KmsAPIClient, optFns ...func(options *KeyringOptions)) *KmsAnyKeyKeyring

NewKmsDecryptOnlyAnyKeyKeyring creates a new KmsAnyKeyKeyring. This Keyring uses the KMS identifier persisted in the data key's ciphertext to decrypt the data key.

func (*KmsAnyKeyKeyring) OnDecrypt

func (k *KmsAnyKeyKeyring) OnDecrypt(ctx context.Context, materials *DecryptionMaterials, encryptedDataKey DataKey) (*CryptographicMaterials, error)

OnDecrypt decrypts the encryptedDataKeys and returns them in materials for use with content decryption, or an error if the object cannot be decrypted by the Keyring as its configured.

func (*KmsAnyKeyKeyring) OnEncrypt

func (k *KmsAnyKeyKeyring) OnEncrypt(ctx context.Context, materials *EncryptionMaterials) (*CryptographicMaterials, error)

OnEncrypt generates/encrypts a data key for use with content encryption The KmsAnyKeyKeyring does not support OnEncrypt, so an error is returned.

type KmsKeyring

type KmsKeyring struct {
	KmsKeyId string
	// contains filtered or unexported fields
}

KmsKeyring encrypts with encryption context and on decrypt it checks for the algorithm in the material description and makes the call to commonDecrypt with the correct parameters

func NewKmsKeyring

func NewKmsKeyring(apiClient KmsAPIClient, kmsKeyId string, optFns ...func(options *KeyringOptions)) *KmsKeyring

NewKmsKeyring creates a new KmsKeyring which calls KMS to encrypt/decrypt the data key used to encrypt the S3 object. The KmsKeyring will always use the kmsKeyId provided to encrypt and decrypt messages.

func (*KmsKeyring) OnDecrypt

func (k *KmsKeyring) OnDecrypt(ctx context.Context, materials *DecryptionMaterials, encryptedDataKey DataKey) (*CryptographicMaterials, error)

OnDecrypt decrypts the encryptedDataKeys and returns them in materials for use with content decryption, or an error if the object cannot be decrypted by the Keyring as its configured.

func (*KmsKeyring) OnEncrypt

func (k *KmsKeyring) OnEncrypt(ctx context.Context, materials *EncryptionMaterials) (*CryptographicMaterials, error)

OnEncrypt generates/encrypts a data key for use with content encryption.

type MaterialDescription

type MaterialDescription map[string]string

MaterialDescription is used to identify how and what master key has been used.

func (MaterialDescription) Clone

func (md MaterialDescription) Clone() (clone MaterialDescription)

Clone returns a copy of the MaterialDescription

func (*MaterialDescription) DecodeDescription

func (md *MaterialDescription) DecodeDescription(b []byte) error

func (*MaterialDescription) EncodeDescription

func (md *MaterialDescription) EncodeDescription() ([]byte, error)