Documentation
¶
Index ¶
- Constants
- Variables
- func AddS3CryptoUserAgent(options *s3.Options)
- func CompressWrappingAlgorithm(fullAlgorithm string) (string, error)
- func GenerateNonZeroBytes(n int) ([]byte, error)
- func GenerateNonZeroBytesWithGenerator(n int, generator func(int) ([]byte, error)) ([]byte, error)
- func GetWriterStore(path string, useTempFile bool) (*writerStore, error)
- func NewBufferedReader(r io.Reader, bufferSize int) (io.ReadCloser, error)
- func NewContentLengthReader(f io.Reader) *contentLengthReader
- type CEKEntry
- type Cipher
- type ContentCipher
- func NewAESCBCContentCipher(materials materials.CryptographicMaterials) (ContentCipher, error)
- func NewAESGCMCommittingContentCipher(materials materials.CryptographicMaterials) (ContentCipher, error)
- func NewAESGCMContentCipher(materials materials.CryptographicMaterials) (ContentCipher, error)
- func NewAESGCMDecryptCommittingContentCipher(materials materials.CryptographicMaterials) (ContentCipher, error)
- type ContentCipherBuilder
- type ContentCipherBuilderWithContext
- type CryptoReadCloser
- type Decrypter
- type DefaultLoadStrategy
- type Encrypter
- type GetObjectAPIClient
- type KeyDerivationResult
- type LoadStrategy
- type LoadStrategyRequest
- type MetadataFormat
- type ObjectMetadata
- func EncodeMeta(reader lengthReader, cryptographicMaterials materials.CryptographicMaterials) (ObjectMetadata, error)
- func EncodeMetaV2(reader lengthReader, cryptographicMaterials materials.CryptographicMaterials) (ObjectMetadata, error)
- func EncodeMetaV3(cryptographicMaterials materials.CryptographicMaterials) (ObjectMetadata, error)
- func (e *ObjectMetadata) GetContentEncryptionAlgorithmString() (string, error)
- func (e *ObjectMetadata) GetContentEncryptionAlgorithmSuite() (*algorithms.AlgorithmSuite, error)
- func (e *ObjectMetadata) GetDecodedKey() ([]byte, error)
- func (e *ObjectMetadata) GetDecodedKeyCommitment() ([]byte, error)
- func (e *ObjectMetadata) GetDecodedMessageIDOrIV() ([]byte, error)
- func (e *ObjectMetadata) GetEncryptionContextOrMatDescV3() (string, error)
- func (e *ObjectMetadata) GetEncryptionContextV3() (string, error)
- func (e *ObjectMetadata) GetFullWrappingAlgorithm() (string, error)
- func (e *ObjectMetadata) GetMatDescV2() (string, error)
- func (e *ObjectMetadata) GetMatDescV3() (string, error)
- func (e *ObjectMetadata) UnmarshalJSON(value []byte) error
- type ObjectMetadataSaveStrategy
- type Padder
- type SaveStrategyRequest
Constants ¶
const ( // Key derivation constants DeriveKeyInfo = "DERIVEKEY" CommitKeyInfo = "COMMITKEY" )
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" )
const (
AESCBCPKCS5Padding = "AES/CBC/PKCS5Padding"
)
const DefaultInstructionKeySuffix = ".instruction"
DefaultInstructionKeySuffix is appended to the end of the instruction file key when grabbing or saving to S3
const (
GcmTagSizeBits = "128"
)
Variables ¶
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.
var AesCbcPadding = aescbcPadder{pkcs7Padder{16}}
var NoPadder = Padder(noPadder{})
NoPadder does not pad anything
Functions ¶
func AddS3CryptoUserAgent ¶
append to user agent (will be ft/s3-encrypt)
func CompressWrappingAlgorithm ¶ added in v3.2.0
CompressWrappingAlgorithm compresses a full wrapping algorithm name to V3 format
func GenerateNonZeroBytes ¶ added in v3.2.0
GenerateNonZeroBytes generates random bytes and validates they are not all zeros
func GenerateNonZeroBytesWithGenerator ¶ added in v3.2.0
GenerateNonZeroBytesWithGenerator allows injection of custom generator for testing
func GetWriterStore ¶
func NewBufferedReader ¶ added in v3.2.0
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 ¶
Types ¶
type CEKEntry ¶
type CEKEntry func(materials.CryptographicMaterials) (ContentCipher, error)
CEKEntry is a builder that returns a proper content decrypter and error
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
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 ¶
func (load DefaultLoadStrategy) Load(ctx context.Context, req *LoadStrategyRequest) (ObjectMetadata, error)
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
KeyDerivationResult holds the results of HKDF key derivation
func DeriveKeys ¶ added in v3.2.0
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 ¶
func (strat ObjectMetadataSaveStrategy) Save(ctx context.Context, saveReq *SaveStrategyRequest) error
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 ¶
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