Class: Aws::S3::Encryption::Client

Inherits:

Object

• Object
• Aws::S3::Encryption::Client

Extended by:

Forwardable

Defined in:

aws-sdk-resources/lib/aws-sdk-resources/services/s3/encryption/client.rb

Instance Attribute Summary

• #client ⇒ S3::Client readonly
• #envelope_location ⇒ Symbol<:metadata, :instruction_file> readonly
• #instruction_file_suffix ⇒ String readonly

  When #envelope_location is :instruction_file, the envelope is stored in the object with the object key suffixed by this string.

• #key_provider ⇒ KeyProvider^? readonly

  Returns nil if you are using AWS Key Management Service (KMS).

Instance Method Summary

• #get_object(params = {}, &block) ⇒ Types::GetObjectOutput

  Gets an object from Amazon S3, decrypting data locally.

• #initialize(options = {}) ⇒ Client constructor

  Creates a new encryption client.

• #put_object(params = {}) ⇒ Types::PutObjectOutput

  Uploads an object to Amazon S3, encrypting data client-side.

Constructor Details

#initialize(options = {}) ⇒ Client

Creates a new encryption client. You must provide one of the following options:

• :encryption_key
• :kms_key_id
• :key_provider

You may also pass any other options accepted by Client#initialize.

Parameters:

• options (Hash) (defaults to: {}) —

  a customizable set of options

Options Hash (options):

• :client (S3::Client) —

  A basic S3 client that is used to make api calls. If a :client is not provided, a new Client will be constructed.

• :encryption_key (OpenSSL::PKey::RSA, String) —

  The master key to use for encrypting/decrypting all objects.

• :kms_key_id (String) —

  When you provide a :kms_key_id, then AWS Key Management Service (KMS) will be used to manage the object encryption keys. By default a KMS::Client will be constructed for KMS API calls. Alternatively, you can provide your own via :kms_client.

• :key_provider (#key_for) —

  Any object that responds to #key_for. This method should accept a materials description JSON document string and return return an encryption key.

• :envelope_location (Symbol) — default: :metadata —

  Where to store the envelope encryption keys. By default, the envelope is stored with the encrypted object. If you pass :instruction_file, then the envelope is stored in a separate object in Amazon S3.

• :instruction_file_suffix (String) — default: '.instruction' —

  When :envelope_location is :instruction_file then the instruction file uses the object key with this suffix appended.

• :kms_client (KMS::Client) —

  A default KMS::Client is constructed when using KMS to manage encryption keys.

# File 'aws-sdk-resources/lib/aws-sdk-resources/services/s3/encryption/client.rb', line 230

def initialize(options = {})
  @client = extract_client(options)
  @cipher_provider = cipher_provider(options)
  @envelope_location = extract_location(options)
  @instruction_file_suffix = extract_suffix(options)
end

Instance Attribute Details

#client ⇒ S3::Client (readonly)

Returns:

• (S3::Client)

# File 'aws-sdk-resources/lib/aws-sdk-resources/services/s3/encryption/client.rb', line 245

def client
  @client
end

#envelope_location ⇒ Symbol<:metadata, :instruction_file> (readonly)

Returns:

• (Symbol<:metadata, :instruction_file>)

# File 'aws-sdk-resources/lib/aws-sdk-resources/services/s3/encryption/client.rb', line 252

def envelope_location
  @envelope_location
end

#instruction_file_suffix ⇒ String (readonly)

Returns When #envelope_location is :instruction_file, the envelope is stored in the object with the object key suffixed by this string.

Returns:

• (String) —

  When #envelope_location is :instruction_file, the envelope is stored in the object with the object key suffixed by this string.

# File 'aws-sdk-resources/lib/aws-sdk-resources/services/s3/encryption/client.rb', line 257

def instruction_file_suffix
  @instruction_file_suffix
end

#key_provider ⇒ KeyProvider^? (readonly)

Returns nil if you are using AWS Key Management Service (KMS).

Returns:

• (KeyProvider, nil) —

  Returns nil if you are using AWS Key Management Service (KMS).

# File 'aws-sdk-resources/lib/aws-sdk-resources/services/s3/encryption/client.rb', line 249

def key_provider
  @key_provider
end

Instance Method Details

#get_object(params = {}, &block) ⇒ Types::GetObjectOutput

Note:

The :range request parameter is not yet supported.

Gets an object from Amazon S3, decrypting data locally. See Client#get_object for documentation on accepted request parameters.

Parameters:

• params (Hash) (defaults to: {}) —

  a customizable set of options

Options Hash (params):

• :instruction_file_suffix (String) —

  The suffix used to find the instruction file containing the encryption envelope. You should not set this option when the envelope is stored in the object metadata. Defaults to #instruction_file_suffix.

• :instruction_file_suffix (String)

Returns:

• (Types::GetObjectOutput) —

  Returns a response object which responds to the following methods:

  • #body => IO
  • #delete_marker => Boolean
  • #accept_ranges => String
  • #expiration => String
  • #restore => String
  • #last_modified => Time
  • #content_length => Integer
  • #etag => String
  • #missing_meta => Integer
  • #version_id => String
  • #cache_control => String
  • #content_disposition => String
  • #content_encoding => String
  • #content_language => String
  • #content_range => String
  • #content_type => String
  • #expires => Time
  • #expires_string => String
  • #website_redirect_location => String
  • #server_side_encryption => String
  • #metadata => Hash<String,String>
  • #sse_customer_algorithm => String
  • #sse_customer_key_md5 => String
  • #ssekms_key_id => String
  • #storage_class => String
  • #request_charged => String
  • #replication_status => String
  • #parts_count => Integer
  • #tag_count => Integer
  • #object_lock_mode => String
  • #object_lock_retain_until_date => Time
  • #object_lock_legal_hold_status => String

See Also:

• Client#get_object

# File 'aws-sdk-resources/lib/aws-sdk-resources/services/s3/encryption/client.rb', line 289

def get_object(params = {}, &block)
  if params[:range]
    raise NotImplementedError, '#get_object with :range not supported yet'
  end
  envelope_location, instruction_file_suffix = envelope_options(params)
  req = @client.build_request(:get_object, params)
  req.handlers.add(DecryptHandler)
  req.context[:encryption] = {
    cipher_provider: @cipher_provider,
    envelope_location: envelope_location,
    instruction_file_suffix: instruction_file_suffix,
  }
  req.send_request(target: block)
end

#put_object(params = {}) ⇒ Types::PutObjectOutput

Uploads an object to Amazon S3, encrypting data client-side. See Client#put_object for documentation on accepted request parameters.

Returns:

• (Types::PutObjectOutput) —

  Returns a response object which responds to the following methods:

  • #expiration => String
  • #etag => String
  • #server_side_encryption => String
  • #version_id => String
  • #sse_customer_algorithm => String
  • #sse_customer_key_md5 => String
  • #ssekms_key_id => String
  • #ssekms_encryption_context => String
  • #request_charged => String

See Also:

• Client#put_object

# File 'aws-sdk-resources/lib/aws-sdk-resources/services/s3/encryption/client.rb', line 265

def put_object(params = {})
  req = @client.build_request(:put_object, params)
  req.handlers.add(EncryptHandler, priority: 95)
  req.context[:encryption] = {
    cipher_provider: @cipher_provider,
    envelope_location: @envelope_location,
    instruction_file_suffix: @instruction_file_suffix,
  }
  req.send_request
end