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

Inherits:
Object
  • Object
show all
Extended by:
Deprecations
Defined in:
lib/aws-sdk-resources/services/s3/encryption/client.rb

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(options = {}) ⇒ Client

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

  • ‘:encryption_key`

  • ‘:kms_key_id`

  • ‘:key_provider`

You may also pass any other options accepted by S3::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 S3::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.



220
221
222
223
224
225
 
# File 'lib/aws-sdk-resources/services/s3/encryption/client.rb', line 220

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) 


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

def client
  @client
end

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

Returns:

  • (Symbol<:metadata, :instruction_file>) 


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

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.



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

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).



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

def key_provider
  @key_provider
end

Instance Method Details

#get_object(params = {}, &block) ⇒ Object

Note:

The ‘:range` request parameter is not yet supported.

Gets an object from Amazon S3, decrypting data locally. See S3::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)

See Also:

  • S3::Client#get_object


272
273
274
275
276
277
278
279
280
281
282
283
284
285
 
# File 'lib/aws-sdk-resources/services/s3/encryption/client.rb', line 272

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 = {}) ⇒ Object

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

See Also:

  • S3::Client#put_object


248
249
250
251
252
253
254
255
256
257
 
# File 'lib/aws-sdk-resources/services/s3/encryption/client.rb', line 248

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