internal

package
v3.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Dec 16, 2025 License: Apache-2.0 Imports: 27 Imported by: 0

Documentation

Index

Constants

View Source
const (
	// Key derivation constants
	DeriveKeyInfo = "DERIVEKEY"
	CommitKeyInfo = "COMMITKEY"
)
View Source
const (
	CekAlgorithmHeader     = amzPrefix + "cek-alg"
	KeyringAlgorithmHeader = amzPrefix + "wrap-alg"

	//= ../specification/s3-encryption/data-format/content-metadata.md#content-metadata-mapkeys
	//# - This mapkey ("x-amz-c") SHOULD be represented by a constant named "CONTENT_CIPHER_V3" or similar in the implementation code.
	ContentCipherV3 = amzPrefix + "c"

	//= ../specification/s3-encryption/data-format/content-metadata.md#content-metadata-mapkeys
	//# - This mapkey ("x-amz-3") SHOULD be represented by a constant named "ENCRYPTED_DATA_KEY_V3" or similar in the implementation code.
	EncryptedDataKeyV3 = amzPrefix + "3"

	//= ../specification/s3-encryption/data-format/content-metadata.md#content-metadata-mapkeys
	//# - This mapkey ("x-amz-m") SHOULD be represented by a constant named "MAT_DESC_V3" or similar in the implementation code.
	MatDescV3 = amzPrefix + "m"

	//= ../specification/s3-encryption/data-format/content-metadata.md#content-metadata-mapkeys
	//# - This mapkey ("x-amz-t") SHOULD be represented by a constant named "ENCRYPTION_CONTEXT_V3" or similar in the implementation code.
	EncryptionContextV3 = amzPrefix + "t"

	//= ../specification/s3-encryption/data-format/content-metadata.md#content-metadata-mapkeys
	//# - This mapkey ("x-amz-w") SHOULD be represented by a constant named "ENCRYPTED_DATA_KEY_ALGORITHM_V3" or similar in the implementation code.
	EncryptedDataKeyAlgorithmV3 = amzPrefix + "w"

	//= ../specification/s3-encryption/data-format/content-metadata.md#content-metadata-mapkeys
	//# - This mapkey ("x-amz-d") SHOULD be represented by a constant named "KEY_COMMITMENT_V3" or similar in the implementation code.
	KeyCommitmentV3 = amzPrefix + "d"

	//= ../specification/s3-encryption/data-format/content-metadata.md#content-metadata-mapkeys
	//# - This mapkey ("x-amz-i") SHOULD be represented by a constant named "MESSAGE_ID_V3" or similar in the implementation code.
	MessageIDV3 = amzPrefix + "i"
)
View Source
const (
	AESCBCPKCS5Padding = "AES/CBC/PKCS5Padding"
)
View Source
const DefaultInstructionKeySuffix = ".instruction"

DefaultInstructionKeySuffix is appended to the end of the instruction file key when grabbing or saving to S3

View Source
const (
	GcmTagSizeBits = "128"
)

Variables

View Source
var AESCBCPadder = Padder(AesCbcPadding)

AESCBCPadder is used to pad AES encrypted and decrypted data. Although it uses the pkcs5Padder, it isn't following the RFC for PKCS5. The only reason why it is called pkcs5Padder is due to the Name returning PKCS5Padding.

View Source
var AesCbcPadding = aescbcPadder{pkcs7Padder{16}}
View Source
var NoPadder = Padder(noPadder{})

NoPadder does not pad anything

Functions

func AddS3CryptoUserAgent

func AddS3CryptoUserAgent(options *s3.Options)

append to user agent (will be ft/s3-encrypt)

func CompressWrappingAlgorithm added in v3.2.0

func CompressWrappingAlgorithm(fullAlgorithm string) (string, error)

CompressWrappingAlgorithm compresses a full wrapping algorithm name to V3 format

func GenerateNonZeroBytes added in v3.2.0

func GenerateNonZeroBytes(n int) ([]byte, error)

GenerateNonZeroBytes generates random bytes and validates they are not all zeros

func GenerateNonZeroBytesWithGenerator added in v3.2.0

func GenerateNonZeroBytesWithGenerator(n int, generator func(int) ([]byte, error)) ([]byte, error)

GenerateNonZeroBytesWithGenerator allows injection of custom generator for testing

func GetWriterStore

func GetWriterStore(path string, useTempFile bool) (*writerStore, error)

func NewBufferedReader added in v3.2.0

func NewBufferedReader(r io.Reader, bufferSize int) (io.ReadCloser, error)

NewBufferedReader creates a buffered reader with the specified buffer size This implements the S3EC requirement to set buffer size to a reasonable default for GetObject

func NewContentLengthReader

func NewContentLengthReader(f io.Reader) *contentLengthReader

Types

type CEKEntry

CEKEntry is a builder that returns a proper content decrypter and error

type Cipher

type Cipher interface {
	Encrypter
	Decrypter
}

Cipher interface allows for either encryption and decryption of an object

type ContentCipher

type ContentCipher interface {
	EncryptContents(io.Reader) (io.Reader, error)
	DecryptContents(io.ReadCloser) (io.ReadCloser, error)
	GetCipherData() materials.CryptographicMaterials
}

ContentCipher deals with encrypting and decrypting content

func NewAESCBCContentCipher

func NewAESCBCContentCipher(materials materials.CryptographicMaterials) (ContentCipher, error)

NewAESCBCContentCipher will create a new aes cbc content cipher. If the cipher data's will set the cek algorithm if it hasn't been set.

func NewAESGCMCommittingContentCipher added in v3.2.0

func NewAESGCMCommittingContentCipher(materials materials.CryptographicMaterials) (ContentCipher, error)

NewAESGCMCommittingContentCipher returns a new encryption only AES/GCM mode structure with a specific cipher data generator that will provide keys to be used for content encryption.

Note: This uses the Go stdlib AEAD implementation for AES/GCM. Due to this, objects to be encrypted or decrypted will be fully loaded into memory before encryption or decryption can occur. Caution must be taken to avoid memory allocation failures.

func NewAESGCMContentCipher

func NewAESGCMContentCipher(materials materials.CryptographicMaterials) (ContentCipher, error)

NewAESGCMContentCipher returns a new encryption only AES/GCM mode structure with a specific cipher data generator that will provide keys to be used for content encryption.

Note: This uses the Go stdlib AEAD implementation for AES/GCM. Due to this, objects to be encrypted or decrypted will be fully loaded into memory before encryption or decryption can occur. Caution must be taken to avoid memory allocation failures.

func NewAESGCMDecryptCommittingContentCipher added in v3.2.0

func NewAESGCMDecryptCommittingContentCipher(materials materials.CryptographicMaterials) (ContentCipher, error)

type ContentCipherBuilder

type ContentCipherBuilder interface {
	ContentCipher() (ContentCipher, error)
}

ContentCipherBuilder is a builder interface that builds ciphers for each request.

type ContentCipherBuilderWithContext

type ContentCipherBuilderWithContext interface {
	ContentCipherWithContext(context.Context) (ContentCipher, error)
}

ContentCipherBuilderWithContext is a builder interface that builds ciphers for each request.

type CryptoReadCloser

type CryptoReadCloser struct {
	Body      io.ReadCloser
	Decrypter io.Reader
	// contains filtered or unexported fields
}

CryptoReadCloser handles closing of the body and allowing reads from the decrypted content.

func (*CryptoReadCloser) Close

func (rc *CryptoReadCloser) Close() error

Close lets the CryptoReadCloser satisfy io.ReadCloser interface

func (*CryptoReadCloser) Read

func (rc *CryptoReadCloser) Read(b []byte) (int, error)

Read lets the CryptoReadCloser satisfy io.ReadCloser interface

type Decrypter

type Decrypter interface {
	Decrypt(io.Reader) io.Reader
}

Decrypter interface with only the decrypt method

type DefaultLoadStrategy

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

DefaultLoadStrategy This is the only exported LoadStrategy since cx are no longer able to configure their client with a specific load strategy. Instead, we figure out which strategy to use based on the response header on decrypt.

func (DefaultLoadStrategy) Load

type Encrypter

type Encrypter interface {
	Encrypt(io.Reader) io.Reader
}

Encrypter interface with only the encrypt method

type GetObjectAPIClient

type GetObjectAPIClient interface {
	GetObject(context.Context, *s3.GetObjectInput, ...func(*s3.Options)) (*s3.GetObjectOutput, error)
}

GetObjectAPIClient is a client that implements the GetObject operation

type KeyDerivationResult added in v3.2.0

type KeyDerivationResult struct {
	DerivedEncryptionKey []byte
	CommitKey            []byte
}

KeyDerivationResult holds the results of HKDF key derivation

func DeriveKeys added in v3.2.0

func DeriveKeys(plaintextDataKey []byte, messageID []byte, algorithmSuiteID int, storedKeyCommitment []byte) (*KeyDerivationResult, error)

type LoadStrategy

type LoadStrategy interface {
	Load(context.Context, *LoadStrategyRequest) (ObjectMetadata, error)
}

LoadStrategy ...

type LoadStrategyRequest

type LoadStrategyRequest struct {
	// The HTTP response
	HTTPResponse *http.Response

	// The operation Input type
	Input interface{}
}

LoadStrategyRequest represents a request sent to a LoadStrategy to load the contents of an ObjectMetadata

type MetadataFormat added in v3.2.0

type MetadataFormat int

MetadataFormat represents the format version of S3EC metadata

const (
	FormatUnknown MetadataFormat = iota
	FormatInstructionFile
	FormatV1
	FormatV2
	FormatV3
)

func DetectAndValidateMetadataFormat added in v3.2.0

func DetectAndValidateMetadataFormat(metadata map[string]string) (MetadataFormat, error)

Validate and detect correct metadata format

type ObjectMetadata

type ObjectMetadata struct {
	// IV is the randomly generated IV base64 encoded.
	//= ../specification/s3-encryption/data-format/content-metadata.md#content-metadata-mapkeys
	//# - The mapkey "x-amz-iv" MUST be present for V2 format objects.
	IV string `json:"x-amz-iv"`
	// CipherKey is the randomly generated cipher key.
	//= ../specification/s3-encryption/data-format/content-metadata.md#content-metadata-mapkeys
	//# - The mapkey "x-amz-key-v2" MUST be present for V2 format objects.
	CipherKey string `json:"x-amz-key-v2"`
	// MaterialDesc is a description to distinguish from other envelopes.
	//= ../specification/s3-encryption/data-format/content-metadata.md#content-metadata-mapkeys
	//# - The mapkey "x-amz-matdesc" MUST be present for V2 format objects.
	MatDesc string `json:"x-amz-matdesc"`
	//= ../specification/s3-encryption/data-format/content-metadata.md#content-metadata-mapkeys
	//# - The mapkey "x-amz-wrap-alg" MUST be present for V2 format objects.
	KeyringAlg string `json:"x-amz-wrap-alg"`
	//= ../specification/s3-encryption/data-format/content-metadata.md#content-metadata-mapkeys
	//# - The mapkey "x-amz-cek-alg" MUST be present for V2 format objects.
	CEKAlg string `json:"x-amz-cek-alg"`
	//= ../specification/s3-encryption/data-format/content-metadata.md#content-metadata-mapkeys
	//# - The mapkey "x-amz-tag-len" MUST be present for V2 format objects.
	TagLen                string `json:"x-amz-tag-len"`
	UnencryptedContentLen string `json:"x-amz-unencrypted-content-length"`
	//= ../specification/s3-encryption/data-format/content-metadata.md#content-metadata-mapkeys
	//# - The mapkey "x-amz-c" MUST be present for V3 format objects.
	ContentCipher string `json:"x-amz-c"`
	//= ../specification/s3-encryption/data-format/content-metadata.md#content-metadata-mapkeys
	//# - The mapkey "x-amz-3" MUST be present for V3 format objects.
	EncryptedDataKey string `json:"x-amz-3"`
	//= ../specification/s3-encryption/data-format/content-metadata.md#content-metadata-mapkeys
	//# - The mapkey "x-amz-m" SHOULD be present for V3 format objects that use Raw Keyring Material Description.
	MatDescV3 string `json:"x-amz-m"`
	//= ../specification/s3-encryption/data-format/content-metadata.md#content-metadata-mapkeys
	//# - The mapkey "x-amz-t" SHOULD be present for V3 format objects that use KMS Encryption Context.
	EncryptionContext string `json:"x-amz-t"`
	//= ../specification/s3-encryption/data-format/content-metadata.md#content-metadata-mapkeys
	//# - The mapkey "x-amz-w" MUST be present for V3 format objects.
	WrappingAlgorithm string `json:"x-amz-w"`
	//= ../specification/s3-encryption/data-format/content-metadata.md#content-metadata-mapkeys
	//# - The mapkey "x-amz-d" MUST be present for V3 format objects.
	KeyCommitment string `json:"x-amz-d"`
	//= ../specification/s3-encryption/data-format/content-metadata.md#content-metadata-mapkeys
	//# - The mapkey "x-amz-i" MUST be present for V3 format objects.
	MessageID string `json:"x-amz-i"`
}

ObjectMetadata encryption starts off by generating a random symmetric key using AES GCM. The SDK generates a random IV based off the encryption cipher chosen. The master key that was provided, whether by the user or KMS, will be used to encrypt the randomly generated symmetric key and base64 encode the iv. This will allow for decryption of that same data later. = ../specification/s3-encryption/data-format/content-metadata.md#content-metadata-mapkeys = type=implication # The "x-amz-meta-" prefix is automatically added by the S3 server and MUST NOT be included in implementation code.

func EncodeMeta

func EncodeMeta(reader lengthReader, cryptographicMaterials materials.CryptographicMaterials) (ObjectMetadata, error)

func EncodeMetaV2 added in v3.2.0

func EncodeMetaV2(reader lengthReader, cryptographicMaterials materials.CryptographicMaterials) (ObjectMetadata, error)

func EncodeMetaV3 added in v3.2.0

func EncodeMetaV3(cryptographicMaterials materials.CryptographicMaterials) (ObjectMetadata, error)

func (*ObjectMetadata) GetContentEncryptionAlgorithmString added in v3.2.0

func (e *ObjectMetadata) GetContentEncryptionAlgorithmString() (string, error)

func (*ObjectMetadata) GetContentEncryptionAlgorithmSuite added in v3.2.0

func (e *ObjectMetadata) GetContentEncryptionAlgorithmSuite() (*algorithms.AlgorithmSuite, error)

func (*ObjectMetadata) GetDecodedKey

func (e *ObjectMetadata) GetDecodedKey() ([]byte, error)

func (*ObjectMetadata) GetDecodedKeyCommitment added in v3.2.0

func (e *ObjectMetadata) GetDecodedKeyCommitment() ([]byte, error)

func (*ObjectMetadata) GetDecodedMessageIDOrIV added in v3.2.0

func (e *ObjectMetadata) GetDecodedMessageIDOrIV() ([]byte, error)

func (*ObjectMetadata) GetEncryptionContextOrMatDescV3 added in v3.2.0

func (e *ObjectMetadata) GetEncryptionContextOrMatDescV3() (string, error)

func (*ObjectMetadata) GetEncryptionContextV3 added in v3.2.0

func (e *ObjectMetadata) GetEncryptionContextV3() (string, error)

func (*ObjectMetadata) GetFullWrappingAlgorithm added in v3.2.0

func (e *ObjectMetadata) GetFullWrappingAlgorithm() (string, error)

func (*ObjectMetadata) GetMatDescV2 added in v3.2.0

func (e *ObjectMetadata) GetMatDescV2() (string, error)

func (*ObjectMetadata) GetMatDescV3 added in v3.2.0

func (e *ObjectMetadata) GetMatDescV3() (string, error)

func (*ObjectMetadata) UnmarshalJSON

func (e *ObjectMetadata) UnmarshalJSON(value []byte) error

UnmarshalJSON unmarshalls the given JSON bytes into ObjectMetadata

type ObjectMetadataSaveStrategy

type ObjectMetadataSaveStrategy struct{}

ObjectMetadataSaveStrategy will save the metadata of the crypto contents to the header of the object.

func (ObjectMetadataSaveStrategy) Save

Save will save the envelope to the request's header.

type Padder

type Padder interface {
	// Pad will pad the byte array.
	// The second parameter is NOT how many
	// bytes to pad by, but how many bytes
	// have been read prior to the padding.
	// This allows for streamable padding.
	Pad([]byte, int) ([]byte, error)
	// Unpad will unpad the byte bytes. Unpad
	// methods must be constant time.
	Unpad([]byte) ([]byte, error)
	// Name returns the name of the padder.
	// This is used when decrypting on
	// instantiating new padders.
	Name() string
}

Padder handles padding of crypto data

func NewPKCS7Padder

func NewPKCS7Padder(blockSize int) Padder

NewPKCS7Padder follows the RFC 2315: https://www.ietf.org/rfc/rfc2315.txt PKCS7 padding is subject to side-channel attacks and timing attacks. For the most secure data, use an authenticated crypto algorithm.

type SaveStrategyRequest

type SaveStrategyRequest struct {
	// The envelope to save
	Envelope *ObjectMetadata

	// The HTTP request being built
	HTTPRequest *http.Request

	// The operation Input type
	Input interface{}
}

SaveStrategyRequest represents a request sent to a SaveStrategy to save the contents of an ObjectMetadata

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL