aws-sdk-s3 1.45.0 → 1.143.0

Sign up to get free protection for your applications and to get access to all the features.
Files changed (128) hide show
  1. checksums.yaml +5 -5
  2. data/CHANGELOG.md +1106 -0
  3. data/LICENSE.txt +202 -0
  4. data/VERSION +1 -0
  5. data/lib/aws-sdk-s3/bucket.rb +784 -98
  6. data/lib/aws-sdk-s3/bucket_acl.rb +64 -18
  7. data/lib/aws-sdk-s3/bucket_cors.rb +79 -18
  8. data/lib/aws-sdk-s3/bucket_lifecycle.rb +66 -20
  9. data/lib/aws-sdk-s3/bucket_lifecycle_configuration.rb +68 -20
  10. data/lib/aws-sdk-s3/bucket_logging.rb +68 -16
  11. data/lib/aws-sdk-s3/bucket_notification.rb +52 -20
  12. data/lib/aws-sdk-s3/bucket_policy.rb +107 -17
  13. data/lib/aws-sdk-s3/bucket_region_cache.rb +2 -0
  14. data/lib/aws-sdk-s3/bucket_request_payment.rb +60 -15
  15. data/lib/aws-sdk-s3/bucket_tagging.rb +71 -18
  16. data/lib/aws-sdk-s3/bucket_versioning.rb +133 -17
  17. data/lib/aws-sdk-s3/bucket_website.rb +78 -21
  18. data/lib/aws-sdk-s3/client.rb +12610 -902
  19. data/lib/aws-sdk-s3/client_api.rb +1086 -191
  20. data/lib/aws-sdk-s3/customizations/bucket.rb +56 -37
  21. data/lib/aws-sdk-s3/customizations/errors.rb +27 -0
  22. data/lib/aws-sdk-s3/customizations/multipart_upload.rb +2 -0
  23. data/lib/aws-sdk-s3/customizations/object.rb +282 -68
  24. data/lib/aws-sdk-s3/customizations/object_summary.rb +5 -0
  25. data/lib/aws-sdk-s3/customizations/types/list_object_versions_output.rb +2 -0
  26. data/lib/aws-sdk-s3/customizations/types/permanent_redirect.rb +26 -0
  27. data/lib/aws-sdk-s3/customizations.rb +11 -1
  28. data/lib/aws-sdk-s3/encryption/client.rb +28 -7
  29. data/lib/aws-sdk-s3/encryption/decrypt_handler.rb +71 -29
  30. data/lib/aws-sdk-s3/encryption/default_cipher_provider.rb +43 -5
  31. data/lib/aws-sdk-s3/encryption/default_key_provider.rb +2 -0
  32. data/lib/aws-sdk-s3/encryption/encrypt_handler.rb +13 -2
  33. data/lib/aws-sdk-s3/encryption/errors.rb +2 -0
  34. data/lib/aws-sdk-s3/encryption/io_auth_decrypter.rb +2 -0
  35. data/lib/aws-sdk-s3/encryption/io_decrypter.rb +11 -3
  36. data/lib/aws-sdk-s3/encryption/io_encrypter.rb +2 -0
  37. data/lib/aws-sdk-s3/encryption/key_provider.rb +2 -0
  38. data/lib/aws-sdk-s3/encryption/kms_cipher_provider.rb +46 -11
  39. data/lib/aws-sdk-s3/encryption/materials.rb +8 -6
  40. data/lib/aws-sdk-s3/encryption/utils.rb +25 -0
  41. data/lib/aws-sdk-s3/encryption.rb +4 -0
  42. data/lib/aws-sdk-s3/encryptionV2/client.rb +570 -0
  43. data/lib/aws-sdk-s3/encryptionV2/decrypt_handler.rb +223 -0
  44. data/lib/aws-sdk-s3/encryptionV2/default_cipher_provider.rb +170 -0
  45. data/lib/aws-sdk-s3/encryptionV2/default_key_provider.rb +40 -0
  46. data/lib/aws-sdk-s3/encryptionV2/encrypt_handler.rb +65 -0
  47. data/lib/aws-sdk-s3/encryptionV2/errors.rb +37 -0
  48. data/lib/aws-sdk-s3/encryptionV2/io_auth_decrypter.rb +58 -0
  49. data/lib/aws-sdk-s3/encryptionV2/io_decrypter.rb +37 -0
  50. data/lib/aws-sdk-s3/encryptionV2/io_encrypter.rb +73 -0
  51. data/lib/aws-sdk-s3/encryptionV2/key_provider.rb +31 -0
  52. data/lib/aws-sdk-s3/encryptionV2/kms_cipher_provider.rb +173 -0
  53. data/lib/aws-sdk-s3/encryptionV2/materials.rb +60 -0
  54. data/lib/aws-sdk-s3/encryptionV2/utils.rb +103 -0
  55. data/lib/aws-sdk-s3/encryption_v2.rb +23 -0
  56. data/lib/aws-sdk-s3/endpoint_parameters.rb +178 -0
  57. data/lib/aws-sdk-s3/endpoint_provider.rb +591 -0
  58. data/lib/aws-sdk-s3/endpoints.rb +2590 -0
  59. data/lib/aws-sdk-s3/errors.rb +123 -1
  60. data/lib/aws-sdk-s3/event_streams.rb +8 -1
  61. data/lib/aws-sdk-s3/express_credentials.rb +55 -0
  62. data/lib/aws-sdk-s3/express_credentials_cache.rb +30 -0
  63. data/lib/aws-sdk-s3/express_credentials_provider.rb +36 -0
  64. data/lib/aws-sdk-s3/file_downloader.rb +176 -44
  65. data/lib/aws-sdk-s3/file_part.rb +11 -6
  66. data/lib/aws-sdk-s3/file_uploader.rb +39 -18
  67. data/lib/aws-sdk-s3/legacy_signer.rb +17 -25
  68. data/lib/aws-sdk-s3/multipart_file_uploader.rb +78 -20
  69. data/lib/aws-sdk-s3/multipart_stream_uploader.rb +56 -18
  70. data/lib/aws-sdk-s3/multipart_upload.rb +242 -32
  71. data/lib/aws-sdk-s3/multipart_upload_error.rb +2 -0
  72. data/lib/aws-sdk-s3/multipart_upload_part.rb +367 -45
  73. data/lib/aws-sdk-s3/object.rb +2191 -227
  74. data/lib/aws-sdk-s3/object_acl.rb +103 -25
  75. data/lib/aws-sdk-s3/object_copier.rb +9 -5
  76. data/lib/aws-sdk-s3/object_multipart_copier.rb +43 -19
  77. data/lib/aws-sdk-s3/object_summary.rb +1811 -208
  78. data/lib/aws-sdk-s3/object_version.rb +452 -80
  79. data/lib/aws-sdk-s3/plugins/accelerate.rb +17 -64
  80. data/lib/aws-sdk-s3/plugins/arn.rb +70 -0
  81. data/lib/aws-sdk-s3/plugins/bucket_dns.rb +7 -43
  82. data/lib/aws-sdk-s3/plugins/bucket_name_restrictions.rb +20 -3
  83. data/lib/aws-sdk-s3/plugins/dualstack.rb +7 -50
  84. data/lib/aws-sdk-s3/plugins/endpoints.rb +274 -0
  85. data/lib/aws-sdk-s3/plugins/expect_100_continue.rb +5 -4
  86. data/lib/aws-sdk-s3/plugins/express_session_auth.rb +91 -0
  87. data/lib/aws-sdk-s3/plugins/get_bucket_location_fix.rb +3 -1
  88. data/lib/aws-sdk-s3/plugins/http_200_errors.rb +11 -3
  89. data/lib/aws-sdk-s3/plugins/iad_regional_endpoint.rb +44 -0
  90. data/lib/aws-sdk-s3/plugins/location_constraint.rb +5 -1
  91. data/lib/aws-sdk-s3/plugins/md5s.rb +35 -30
  92. data/lib/aws-sdk-s3/plugins/redirects.rb +2 -0
  93. data/lib/aws-sdk-s3/plugins/s3_host_id.rb +2 -0
  94. data/lib/aws-sdk-s3/plugins/s3_signer.rb +56 -92
  95. data/lib/aws-sdk-s3/plugins/skip_whole_multipart_get_checksums.rb +31 -0
  96. data/lib/aws-sdk-s3/plugins/sse_cpk.rb +3 -1
  97. data/lib/aws-sdk-s3/plugins/streaming_retry.rb +139 -0
  98. data/lib/aws-sdk-s3/plugins/url_encoded_keys.rb +2 -0
  99. data/lib/aws-sdk-s3/presigned_post.rb +160 -99
  100. data/lib/aws-sdk-s3/presigner.rb +171 -80
  101. data/lib/aws-sdk-s3/resource.rb +120 -8
  102. data/lib/aws-sdk-s3/types.rb +11353 -4225
  103. data/lib/aws-sdk-s3/waiters.rb +67 -1
  104. data/lib/aws-sdk-s3.rb +16 -6
  105. data/sig/bucket.rbs +212 -0
  106. data/sig/bucket_acl.rbs +78 -0
  107. data/sig/bucket_cors.rbs +69 -0
  108. data/sig/bucket_lifecycle.rbs +88 -0
  109. data/sig/bucket_lifecycle_configuration.rbs +111 -0
  110. data/sig/bucket_logging.rbs +76 -0
  111. data/sig/bucket_notification.rbs +114 -0
  112. data/sig/bucket_policy.rbs +59 -0
  113. data/sig/bucket_request_payment.rbs +54 -0
  114. data/sig/bucket_tagging.rbs +65 -0
  115. data/sig/bucket_versioning.rbs +77 -0
  116. data/sig/bucket_website.rbs +93 -0
  117. data/sig/client.rbs +2360 -0
  118. data/sig/errors.rbs +34 -0
  119. data/sig/multipart_upload.rbs +110 -0
  120. data/sig/multipart_upload_part.rbs +105 -0
  121. data/sig/object.rbs +436 -0
  122. data/sig/object_acl.rbs +86 -0
  123. data/sig/object_summary.rbs +334 -0
  124. data/sig/object_version.rbs +131 -0
  125. data/sig/resource.rbs +124 -0
  126. data/sig/types.rbs +2562 -0
  127. data/sig/waiters.rbs +83 -0
  128. metadata +68 -15
@@ -0,0 +1,570 @@
1
+ # frozen_string_literal: true
2
+
3
+ require 'forwardable'
4
+
5
+ module Aws
6
+ module S3
7
+
8
+ REQUIRED_PARAMS = [:key_wrap_schema, :content_encryption_schema, :security_profile]
9
+ SUPPORTED_SECURITY_PROFILES = [:v2, :v2_and_legacy]
10
+
11
+ # Provides an encryption client that encrypts and decrypts data client-side,
12
+ # storing the encrypted data in Amazon S3. The `EncryptionV2::Client` (V2 Client)
13
+ # provides improved security over the `Encryption::Client` (V1 Client)
14
+ # by using more modern and secure algorithms. You can use the V2 Client
15
+ # to continue decrypting objects encrypted using deprecated algorithms
16
+ # by setting security_profile: :v2_and_legacy. The latest V1 Client also
17
+ # supports reading and decrypting objects encrypted by the V2 Client.
18
+ #
19
+ # This client uses a process called "envelope encryption". Your private
20
+ # encryption keys and your data's plain-text are **never** sent to
21
+ # Amazon S3. **If you lose you encryption keys, you will not be able to
22
+ # decrypt your data.**
23
+ #
24
+ # ## Envelope Encryption Overview
25
+ #
26
+ # The goal of envelope encryption is to combine the performance of
27
+ # fast symmetric encryption while maintaining the secure key management
28
+ # that asymmetric keys provide.
29
+ #
30
+ # A one-time-use symmetric key (envelope key) is generated client-side.
31
+ # This is used to encrypt the data client-side. This key is then
32
+ # encrypted by your master key and stored alongside your data in Amazon
33
+ # S3.
34
+ #
35
+ # When accessing your encrypted data with the encryption client,
36
+ # the encrypted envelope key is retrieved and decrypted client-side
37
+ # with your master key. The envelope key is then used to decrypt the
38
+ # data client-side.
39
+ #
40
+ # One of the benefits of envelope encryption is that if your master key
41
+ # is compromised, you have the option of just re-encrypting the stored
42
+ # envelope symmetric keys, instead of re-encrypting all of the
43
+ # data in your account.
44
+ #
45
+ # ## Basic Usage
46
+ #
47
+ # The encryption client requires an {Aws::S3::Client}. If you do not
48
+ # provide a `:client`, then a client will be constructed for you.
49
+ #
50
+ # require 'openssl'
51
+ # key = OpenSSL::PKey::RSA.new(1024)
52
+ #
53
+ # # encryption client
54
+ # s3 = Aws::S3::EncryptionV2::Client.new(
55
+ # encryption_key: key,
56
+ # key_wrap_schema: :rsa_oaep_sha1, # the key_wrap_schema must be rsa_oaep_sha1 for asymmetric keys
57
+ # content_encryption_schema: :aes_gcm_no_padding,
58
+ # security_profile: :v2 # use :v2_and_legacy to allow reading/decrypting objects encrypted by the V1 encryption client
59
+ # )
60
+ #
61
+ # # round-trip an object, encrypted/decrypted locally
62
+ # s3.put_object(bucket:'aws-sdk', key:'secret', body:'handshake')
63
+ # s3.get_object(bucket:'aws-sdk', key:'secret').body.read
64
+ # #=> 'handshake'
65
+ #
66
+ # # reading encrypted object without the encryption client
67
+ # # results in the getting the cipher text
68
+ # Aws::S3::Client.new.get_object(bucket:'aws-sdk', key:'secret').body.read
69
+ # #=> "... cipher text ..."
70
+ #
71
+ # ## Required Configuration
72
+ #
73
+ # You must configure all of the following:
74
+ #
75
+ # * a key or key provider - See the Keys section below. The key provided determines
76
+ # the key wrapping schema(s) supported for both encryption and decryption.
77
+ # * `key_wrap_schema` - The key wrapping schema. It must match the type of key configured.
78
+ # * `content_encryption_schema` - The only supported value currently is `:aes_gcm_no_padding`.
79
+ # More options will be added in future releases.
80
+ # * `security_profile` - Determines the support for reading objects written
81
+ # using older key wrap or content encryption schemas. If you need to read
82
+ # legacy objects encrypted by an existing V1 Client, then set this to `:v2_and_legacy`.
83
+ # Otherwise, set it to `:v2`
84
+ #
85
+ # ## Keys
86
+ #
87
+ # For client-side encryption to work, you must provide one of the following:
88
+ #
89
+ # * An encryption key
90
+ # * A {KeyProvider}
91
+ # * A KMS encryption key id
92
+ #
93
+ # Additionally, the key wrapping schema must agree with the type of the key:
94
+ # * :aes_gcm: An AES encryption key or a key provider.
95
+ # * :rsa_oaep_sha1: An RSA encryption key or key provider.
96
+ # * :kms_context: A KMS encryption key id
97
+ #
98
+ # ### An Encryption Key
99
+ #
100
+ # You can pass a single encryption key. This is used as a master key
101
+ # encrypting and decrypting all object keys.
102
+ #
103
+ # key = OpenSSL::Cipher.new("AES-256-ECB").random_key # symmetric key - used with `key_wrap_schema: :aes_gcm`
104
+ # key = OpenSSL::PKey::RSA.new(1024) # asymmetric key pair - used with `key_wrap_schema: :rsa_oaep_sha1`
105
+ #
106
+ # s3 = Aws::S3::EncryptionV2::Client.new(
107
+ # encryption_key: key,
108
+ # key_wrap_schema: :aes_gcm, # or :rsa_oaep_sha1 if using RSA
109
+ # content_encryption_schema: :aes_gcm_no_padding,
110
+ # security_profile: :v2
111
+ # )
112
+ #
113
+ # ### Key Provider
114
+ #
115
+ # Alternatively, you can use a {KeyProvider}. A key provider makes
116
+ # it easy to work with multiple keys and simplifies key rotation.
117
+ #
118
+ # ### KMS Encryption Key Id
119
+ #
120
+ # If you pass the id of an AWS Key Management Service (KMS) key and
121
+ # use :kms_content for the key_wrap_schema, then KMS will be used to
122
+ # generate, encrypt and decrypt object keys.
123
+ #
124
+ # # keep track of the kms key id
125
+ # kms = Aws::KMS::Client.new
126
+ # key_id = kms.create_key.key_metadata.key_id
127
+ #
128
+ # Aws::S3::EncryptionV2::Client.new(
129
+ # kms_key_id: key_id,
130
+ # kms_client: kms,
131
+ # key_wrap_schema: :kms_context,
132
+ # content_encryption_schema: :aes_gcm_no_padding,
133
+ # security_profile: :v2
134
+ # )
135
+ #
136
+ # ## Custom Key Providers
137
+ #
138
+ # A {KeyProvider} is any object that responds to:
139
+ #
140
+ # * `#encryption_materials`
141
+ # * `#key_for(materials_description)`
142
+ #
143
+ # Here is a trivial implementation of an in-memory key provider.
144
+ # This is provided as a demonstration of the key provider interface,
145
+ # and should not be used in production:
146
+ #
147
+ # class KeyProvider
148
+ #
149
+ # def initialize(default_key_name, keys)
150
+ # @keys = keys
151
+ # @encryption_materials = Aws::S3::EncryptionV2::Materials.new(
152
+ # key: @keys[default_key_name],
153
+ # description: JSON.dump(key: default_key_name),
154
+ # )
155
+ # end
156
+ #
157
+ # attr_reader :encryption_materials
158
+ #
159
+ # def key_for(matdesc)
160
+ # key_name = JSON.parse(matdesc)['key']
161
+ # if key = @keys[key_name]
162
+ # key
163
+ # else
164
+ # raise "encryption key not found for: #{matdesc.inspect}"
165
+ # end
166
+ # end
167
+ # end
168
+ #
169
+ # Given the above key provider, you can create an encryption client that
170
+ # chooses the key to use based on the materials description stored with
171
+ # the encrypted object. This makes it possible to use multiple keys
172
+ # and simplifies key rotation.
173
+ #
174
+ # # uses "new-key" for encrypting objects, uses either for decrypting
175
+ # keys = KeyProvider.new('new-key', {
176
+ # "old-key" => Base64.decode64("kM5UVbhE/4rtMZJfsadYEdm2vaKFsmV2f5+URSeUCV4="),
177
+ # "new-key" => Base64.decode64("w1WLio3agRWRTSJK/Ouh8NHoqRQ6fn5WbSXDTHjXMSo="),
178
+ # }),
179
+ #
180
+ # # chooses the key based on the materials description stored
181
+ # # with the encrypted object
182
+ # s3 = Aws::S3::EncryptionV2::Client.new(
183
+ # key_provider: keys,
184
+ # key_wrap_schema: ...,
185
+ # content_encryption_schema: :aes_gcm_no_padding,
186
+ # security_profile: :v2
187
+ # )
188
+ #
189
+ # ## Materials Description
190
+ #
191
+ # A materials description is JSON document string that is stored
192
+ # in the metadata (or instruction file) of an encrypted object.
193
+ # The {DefaultKeyProvider} uses the empty JSON document `"{}"`.
194
+ #
195
+ # When building a key provider, you are free to store whatever
196
+ # information you need to identify the master key that was used
197
+ # to encrypt the object.
198
+ #
199
+ # ## Envelope Location
200
+ #
201
+ # By default, the encryption client store the encryption envelope
202
+ # with the object, as metadata. You can choose to have the envelope
203
+ # stored in a separate "instruction file". An instruction file
204
+ # is an object, with the key of the encrypted object, suffixed with
205
+ # `".instruction"`.
206
+ #
207
+ # Specify the `:envelope_location` option as `:instruction_file` to
208
+ # use an instruction file for storing the envelope.
209
+ #
210
+ # # default behavior
211
+ # s3 = Aws::S3::EncryptionV2::Client.new(
212
+ # key_provider: ...,
213
+ # envelope_location: :metadata,
214
+ # )
215
+ #
216
+ # # store envelope in a separate object
217
+ # s3 = Aws::S3::EncryptionV2::Client.new(
218
+ # key_provider: ...,
219
+ # envelope_location: :instruction_file,
220
+ # instruction_file_suffix: '.instruction' # default
221
+ # key_wrap_schema: ...,
222
+ # content_encryption_schema: :aes_gcm_no_padding,
223
+ # security_profile: :v2
224
+ # )
225
+ #
226
+ # When using an instruction file, multiple requests are made when
227
+ # putting and getting the object. **This may cause issues if you are
228
+ # issuing concurrent PUT and GET requests to an encrypted object.**
229
+ #
230
+ module EncryptionV2
231
+ class Client
232
+
233
+ extend Deprecations
234
+ extend Forwardable
235
+ def_delegators :@client, :config, :delete_object, :head_object, :build_request
236
+
237
+ # Creates a new encryption client. You must configure all of the following:
238
+ #
239
+ # * a key or key provider - The key provided also determines the key wrapping
240
+ # schema(s) supported for both encryption and decryption.
241
+ # * `key_wrap_schema` - The key wrapping schema. It must match the type of key configured.
242
+ # * `content_encryption_schema` - The only supported value currently is `:aes_gcm_no_padding`
243
+ # More options will be added in future releases.
244
+ # * `security_profile` - Determines the support for reading objects written
245
+ # using older key wrap or content encryption schemas. If you need to read
246
+ # legacy objects encrypted by an existing V1 Client, then set this to `:v2_and_legacy`.
247
+ # Otherwise, set it to `:v2`
248
+ #
249
+ # To configure the key you must provide one of the following set of options:
250
+ #
251
+ # * `:encryption_key`
252
+ # * `:kms_key_id`
253
+ # * `:key_provider`
254
+ #
255
+ # You may also pass any other options accepted by `Client#initialize`.
256
+ #
257
+ # @option options [S3::Client] :client A basic S3 client that is used
258
+ # to make api calls. If a `:client` is not provided, a new {S3::Client}
259
+ # will be constructed.
260
+ #
261
+ # @option options [OpenSSL::PKey::RSA, String] :encryption_key The master
262
+ # key to use for encrypting/decrypting all objects.
263
+ #
264
+ # @option options [String] :kms_key_id When you provide a `:kms_key_id`,
265
+ # then AWS Key Management Service (KMS) will be used to manage the
266
+ # object encryption keys. By default a {KMS::Client} will be
267
+ # constructed for KMS API calls. Alternatively, you can provide
268
+ # your own via `:kms_client`. To only support decryption/reads, you may
269
+ # provide `:allow_decrypt_with_any_cmk` which will use
270
+ # the implicit CMK associated with the data during reads but will
271
+ # not allow you to encrypt/write objects with this client.
272
+ #
273
+ # @option options [#key_for] :key_provider Any object that responds
274
+ # to `#key_for`. This method should accept a materials description
275
+ # JSON document string and return return an encryption key.
276
+ #
277
+ # @option options [required, Symbol] :key_wrap_schema The Key wrapping
278
+ # schema to be used. It must match the type of key configured.
279
+ # Must be one of the following:
280
+ #
281
+ # * :kms_context (Must provide kms_key_id)
282
+ # * :aes_gcm (Must provide an AES (string) key)
283
+ # * :rsa_oaep_sha1 (Must provide an RSA key)
284
+ #
285
+ # @option options [required, Symbol] :content_encryption_schema
286
+ # Must be one of the following:
287
+ #
288
+ # * :aes_gcm_no_padding
289
+ #
290
+ # @option options [Required, Symbol] :security_profile
291
+ # Determines the support for reading objects written using older
292
+ # key wrap or content encryption schemas.
293
+ # Must be one of the following:
294
+ #
295
+ # * :v2 - Reads of legacy (v1) objects are NOT allowed
296
+ # * :v2_and_legacy - Enables reading of legacy (V1) schemas.
297
+ #
298
+ # @option options [Symbol] :envelope_location (:metadata) Where to
299
+ # store the envelope encryption keys. By default, the envelope is
300
+ # stored with the encrypted object. If you pass `:instruction_file`,
301
+ # then the envelope is stored in a separate object in Amazon S3.
302
+ #
303
+ # @option options [String] :instruction_file_suffix ('.instruction')
304
+ # When `:envelope_location` is `:instruction_file` then the
305
+ # instruction file uses the object key with this suffix appended.
306
+ #
307
+ # @option options [KMS::Client] :kms_client A default {KMS::Client}
308
+ # is constructed when using KMS to manage encryption keys.
309
+ #
310
+ def initialize(options = {})
311
+ validate_params(options)
312
+ @client = extract_client(options)
313
+ @cipher_provider = cipher_provider(options)
314
+ @envelope_location = extract_location(options)
315
+ @instruction_file_suffix = extract_suffix(options)
316
+ @kms_allow_decrypt_with_any_cmk =
317
+ options[:kms_key_id] == :kms_allow_decrypt_with_any_cmk
318
+ @security_profile = extract_security_profile(options)
319
+ end
320
+
321
+ # @return [S3::Client]
322
+ attr_reader :client
323
+
324
+ # @return [KeyProvider, nil] Returns `nil` if you are using
325
+ # AWS Key Management Service (KMS).
326
+ attr_reader :key_provider
327
+
328
+ # @return [Symbol] Determines the support for reading objects written
329
+ # using older key wrap or content encryption schemas.
330
+ attr_reader :security_profile
331
+
332
+ # @return [Boolean] If true the provided KMS key_id will not be used
333
+ # during decrypt, allowing decryption with the key_id from the object.
334
+ attr_reader :kms_allow_decrypt_with_any_cmk
335
+
336
+ # @return [Symbol<:metadata, :instruction_file>]
337
+ attr_reader :envelope_location
338
+
339
+ # @return [String] When {#envelope_location} is `:instruction_file`,
340
+ # the envelope is stored in the object with the object key suffixed
341
+ # by this string.
342
+ attr_reader :instruction_file_suffix
343
+
344
+ # Uploads an object to Amazon S3, encrypting data client-side.
345
+ # See {S3::Client#put_object} for documentation on accepted
346
+ # request parameters.
347
+ # @option params [Hash] :kms_encryption_context Additional encryption
348
+ # context to use with KMS. Applies only when KMS is used. In order
349
+ # to decrypt the object you will need to provide the identical
350
+ # :kms_encryption_context to `get_object`.
351
+ # @option (see S3::Client#put_object)
352
+ # @return (see S3::Client#put_object)
353
+ # @see S3::Client#put_object
354
+ def put_object(params = {})
355
+ kms_encryption_context = params.delete(:kms_encryption_context)
356
+ req = @client.build_request(:put_object, params)
357
+ req.handlers.add(EncryptHandler, priority: 95)
358
+ req.context[:encryption] = {
359
+ cipher_provider: @cipher_provider,
360
+ envelope_location: @envelope_location,
361
+ instruction_file_suffix: @instruction_file_suffix,
362
+ kms_encryption_context: kms_encryption_context
363
+ }
364
+ Aws::Plugins::UserAgent.feature('S3CryptoV2') do
365
+ req.send_request
366
+ end
367
+ end
368
+
369
+ # Gets an object from Amazon S3, decrypting data locally.
370
+ # See {S3::Client#get_object} for documentation on accepted
371
+ # request parameters.
372
+ # Warning: If you provide a block to get_object or set the request
373
+ # parameter :response_target to a Proc, then read the entire object to the
374
+ # end before you start using the decrypted data. This is to verify that
375
+ # the object has not been modified since it was encrypted.
376
+ #
377
+ # @option options [Symbol] :security_profile
378
+ # Determines the support for reading objects written using older
379
+ # key wrap or content encryption schemas. Overrides the value set
380
+ # on client construction if provided.
381
+ # Must be one of the following:
382
+ #
383
+ # * :v2 - Reads of legacy (v1) objects are NOT allowed
384
+ # * :v2_and_legacy - Enables reading of legacy (V1) schemas.
385
+ # @option params [String] :instruction_file_suffix The suffix
386
+ # used to find the instruction file containing the encryption
387
+ # envelope. You should not set this option when the envelope
388
+ # is stored in the object metadata. Defaults to
389
+ # {#instruction_file_suffix}.
390
+ # @option params [Hash] :kms_encryption_context Additional encryption
391
+ # context to use with KMS. Applies only when KMS is used.
392
+ # @option options [Boolean] :kms_allow_decrypt_with_any_cmk (false)
393
+ # By default the KMS CMK ID (kms_key_id) will be used during decrypt
394
+ # and will fail if there is a mismatch. Setting this to true
395
+ # will use the implicit CMK associated with the data.
396
+ # @option (see S3::Client#get_object)
397
+ # @return (see S3::Client#get_object)
398
+ # @see S3::Client#get_object
399
+ # @note The `:range` request parameter is not supported.
400
+ def get_object(params = {}, &block)
401
+ if params[:range]
402
+ raise NotImplementedError, '#get_object with :range not supported'
403
+ end
404
+ envelope_location, instruction_file_suffix = envelope_options(params)
405
+ kms_encryption_context = params.delete(:kms_encryption_context)
406
+ kms_any_cmk_mode = kms_any_cmk_mode(params)
407
+ security_profile = security_profile_from_params(params)
408
+
409
+ req = @client.build_request(:get_object, params)
410
+ req.handlers.add(DecryptHandler)
411
+ req.context[:encryption] = {
412
+ cipher_provider: @cipher_provider,
413
+ envelope_location: envelope_location,
414
+ instruction_file_suffix: instruction_file_suffix,
415
+ kms_encryption_context: kms_encryption_context,
416
+ kms_allow_decrypt_with_any_cmk: kms_any_cmk_mode,
417
+ security_profile: security_profile
418
+ }
419
+ Aws::Plugins::UserAgent.feature('S3CryptoV2') do
420
+ req.send_request(target: block)
421
+ end
422
+ end
423
+
424
+ private
425
+
426
+ # Validate required parameters exist and don't conflict.
427
+ # The cek_alg and wrap_alg are passed on to the CipherProviders
428
+ # and further validated there
429
+ def validate_params(options)
430
+ unless (missing_params = REQUIRED_PARAMS - options.keys).empty?
431
+ raise ArgumentError, "Missing required parameter(s): "\
432
+ "#{missing_params.map{ |s| ":#{s}" }.join(', ')}"
433
+ end
434
+
435
+ wrap_alg = options[:key_wrap_schema]
436
+
437
+ # validate that the wrap alg matches the type of key given
438
+ case wrap_alg
439
+ when :kms_context
440
+ unless options[:kms_key_id]
441
+ raise ArgumentError, 'You must provide :kms_key_id to use :kms_context'
442
+ end
443
+ end
444
+ end
445
+
446
+ def extract_client(options)
447
+ options[:client] || begin
448
+ options = options.dup
449
+ options.delete(:kms_key_id)
450
+ options.delete(:kms_client)
451
+ options.delete(:key_provider)
452
+ options.delete(:encryption_key)
453
+ options.delete(:envelope_location)
454
+ options.delete(:instruction_file_suffix)
455
+ REQUIRED_PARAMS.each { |p| options.delete(p) }
456
+ S3::Client.new(options)
457
+ end
458
+ end
459
+
460
+ def kms_client(options)
461
+ options[:kms_client] || begin
462
+ KMS::Client.new(
463
+ region: @client.config.region,
464
+ credentials: @client.config.credentials,
465
+ )
466
+ end
467
+ end
468
+
469
+ def cipher_provider(options)
470
+ if options[:kms_key_id]
471
+ KmsCipherProvider.new(
472
+ kms_key_id: options[:kms_key_id],
473
+ kms_client: kms_client(options),
474
+ key_wrap_schema: options[:key_wrap_schema],
475
+ content_encryption_schema: options[:content_encryption_schema]
476
+ )
477
+ else
478
+ @key_provider = extract_key_provider(options)
479
+ DefaultCipherProvider.new(
480
+ key_provider: @key_provider,
481
+ key_wrap_schema: options[:key_wrap_schema],
482
+ content_encryption_schema: options[:content_encryption_schema]
483
+ )
484
+ end
485
+ end
486
+
487
+ def extract_key_provider(options)
488
+ if options[:key_provider]
489
+ options[:key_provider]
490
+ elsif options[:encryption_key]
491
+ DefaultKeyProvider.new(options)
492
+ else
493
+ msg = 'you must pass a :kms_key_id, :key_provider, or :encryption_key'
494
+ raise ArgumentError, msg
495
+ end
496
+ end
497
+
498
+ def envelope_options(params)
499
+ location = params.delete(:envelope_location) || @envelope_location
500
+ suffix = params.delete(:instruction_file_suffix)
501
+ if suffix
502
+ [:instruction_file, suffix]
503
+ else
504
+ [location, @instruction_file_suffix]
505
+ end
506
+ end
507
+
508
+ def extract_location(options)
509
+ location = options[:envelope_location] || :metadata
510
+ if [:metadata, :instruction_file].include?(location)
511
+ location
512
+ else
513
+ msg = ':envelope_location must be :metadata or :instruction_file '\
514
+ "got #{location.inspect}"
515
+ raise ArgumentError, msg
516
+ end
517
+ end
518
+
519
+ def extract_suffix(options)
520
+ suffix = options[:instruction_file_suffix] || '.instruction'
521
+ if suffix.is_a? String
522
+ suffix
523
+ else
524
+ msg = ':instruction_file_suffix must be a String'
525
+ raise ArgumentError, msg
526
+ end
527
+ end
528
+
529
+ def kms_any_cmk_mode(params)
530
+ if !params[:kms_allow_decrypt_with_any_cmk].nil?
531
+ params.delete(:kms_allow_decrypt_with_any_cmk)
532
+ else
533
+ @kms_allow_decrypt_with_any_cmk
534
+ end
535
+ end
536
+
537
+ def extract_security_profile(options)
538
+ validate_security_profile(options[:security_profile])
539
+ end
540
+
541
+ def security_profile_from_params(params)
542
+ security_profile =
543
+ if !params[:security_profile].nil?
544
+ params.delete(:security_profile)
545
+ else
546
+ @security_profile
547
+ end
548
+ validate_security_profile(security_profile)
549
+ end
550
+
551
+ def validate_security_profile(security_profile)
552
+ unless SUPPORTED_SECURITY_PROFILES.include? security_profile
553
+ raise ArgumentError, "Unsupported security profile: :#{security_profile}. " \
554
+ "Please provide one of: #{SUPPORTED_SECURITY_PROFILES.map { |s| ":#{s}" }.join(', ')}"
555
+ end
556
+ if security_profile == :v2_and_legacy && !@warned_about_legacy
557
+ @warned_about_legacy = true
558
+ warn(
559
+ 'The S3 Encryption Client is configured to read encrypted objects ' \
560
+ "with legacy encryption modes. If you don't have objects " \
561
+ 'encrypted with these legacy modes, you should disable support ' \
562
+ 'for them to enhance security.'
563
+ )
564
+ end
565
+ security_profile
566
+ end
567
+ end
568
+ end
569
+ end
570
+ end