async-aws · jderusse · Sep 19, 2024 · Sep 19, 2024
diff --git a/manifest.json b/manifest.json
@@ -1,6 +1,6 @@
 {
     "variables": {
-        "${LATEST}": "3.321.13"
+        "${LATEST}": "3.322.0"
     },
     "endpoints": "https://raw.githubusercontent.com/aws/aws-sdk-php/${LATEST}/src/data/endpoints.json",
     "services": {

diff --git a/src/Service/S3/CHANGELOG.md b/src/Service/S3/CHANGELOG.md
@@ -11,6 +11,7 @@
 ### Changed
 
 - Enable compiler optimization for the `sprintf` function.
+- AWS enhancement: Documentation updates.
 
 ## 2.3.0
 

diff --git a/src/Service/S3/src/Input/CopyObjectRequest.php b/src/Service/S3/src/Input/CopyObjectRequest.php
@@ -365,31 +365,56 @@ final class CopyObjectRequest extends Input
     private $taggingDirective;
 
     /**
-     * The server-side encryption algorithm used when storing this object in Amazon S3 (for example, `AES256`, `aws:kms`,
-     * `aws:kms:dsse`). Unrecognized or unsupported values won’t write a destination object and will receive a `400 Bad
-     * Request` response.
+     * The server-side encryption algorithm used when storing this object in Amazon S3. Unrecognized or unsupported values
+     * won’t write a destination object and will receive a `400 Bad Request` response.
      *
      * Amazon S3 automatically encrypts all new objects that are copied to an S3 bucket. When copying an object, if you
      * don't specify encryption information in your copy request, the encryption setting of the target object is set to the
      * default encryption configuration of the destination bucket. By default, all buckets have a base level of encryption
      * configuration that uses server-side encryption with Amazon S3 managed keys (SSE-S3). If the destination bucket has a
-     * default encryption configuration that uses server-side encryption with Key Management Service (KMS) keys (SSE-KMS),
-     * dual-layer server-side encryption with Amazon Web Services KMS keys (DSSE-KMS), or server-side encryption with
-     * customer-provided encryption keys (SSE-C), Amazon S3 uses the corresponding KMS key, or a customer-provided key to
-     * encrypt the target object copy.
-     *
-     * When you perform a `CopyObject` operation, if you want to use a different type of encryption setting for the target
-     * object, you can specify appropriate encryption-related headers to encrypt the target object with an Amazon S3 managed
-     * key, a KMS key, or a customer-provided key. If the encryption setting in your request is different from the default
-     * encryption configuration of the destination bucket, the encryption setting in your request takes precedence.
+     * different default encryption configuration, Amazon S3 uses the corresponding encryption key to encrypt the target
+     * object copy.
      *
      * With server-side encryption, Amazon S3 encrypts your data as it writes your data to disks in its data centers and
      * decrypts the data when you access it. For more information about server-side encryption, see Using Server-Side
      * Encryption [^1] in the *Amazon S3 User Guide*.
      *
-     * > For directory buckets, only server-side encryption with Amazon S3 managed keys (SSE-S3) (`AES256`) is supported.
+     * **General purpose buckets **
+     *
+     * - For general purpose buckets, there are the following supported options for server-side encryption: server-side
+     *   encryption with Key Management Service (KMS) keys (SSE-KMS), dual-layer server-side encryption with Amazon Web
+     *   Services KMS keys (DSSE-KMS), and server-side encryption with customer-provided encryption keys (SSE-C). Amazon S3
+     *   uses the corresponding KMS key, or a customer-provided key to encrypt the target object copy.
+     * - When you perform a `CopyObject` operation, if you want to use a different type of encryption setting for the target
+     *   object, you can specify appropriate encryption-related headers to encrypt the target object with an Amazon S3
+     *   managed key, a KMS key, or a customer-provided key. If the encryption setting in your request is different from the
+     *   default encryption configuration of the destination bucket, the encryption setting in your request takes
+     *   precedence.
+     *
+     * **Directory buckets **
+     *
+     * - For directory buckets, there are only two supported options for server-side encryption: server-side encryption with
+     *   Amazon S3 managed keys (SSE-S3) (`AES256`) and server-side encryption with KMS keys (SSE-KMS) (`aws:kms`). We
+     *   recommend that the bucket's default encryption uses the desired encryption configuration and you don't override the
+     *   bucket default encryption in your `CreateSession` requests or `PUT` object requests. Then, new objects are
+     *   automatically encrypted with the desired encryption settings. For more information, see Protecting data with
+     *   server-side encryption [^2] in the *Amazon S3 User Guide*. For more information about the encryption overriding
+     *   behaviors in directory buckets, see Specifying server-side encryption with KMS for new object uploads [^3].
+     * - To encrypt new object copies to a directory bucket with SSE-KMS, we recommend you specify SSE-KMS as the directory
+     *   bucket's default encryption configuration with a KMS key (specifically, a customer managed key [^4]). Amazon Web
+     *   Services managed key [^5] (`aws/s3`) isn't supported. Your SSE-KMS configuration can only support 1 customer
+     *   managed key [^6] per directory bucket for the lifetime of the bucket. After you specify a customer managed key for
+     *   SSE-KMS, you can't override the customer managed key for the bucket's SSE-KMS configuration. Then, when you perform
+     *   a `CopyObject` operation and want to specify server-side encryption settings for new object copies with SSE-KMS in
+     *   the encryption-related request headers, you must ensure the encryption key is the same customer managed key that
+     *   you specified for the directory bucket's default encryption configuration.
      *
      * [^1]: https://docs.aws.amazon.com/AmazonS3/latest/dev/serv-side-encryption.html
+     * [^2]: https://docs.aws.amazon.com/AmazonS3/latest/userguide/s3-express-serv-side-encryption.html
+     * [^3]: https://docs.aws.amazon.com/AmazonS3/latest/userguide/s3-express-specifying-kms-encryption.html
+     * [^4]: https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#customer-cmk
+     * [^5]: https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#aws-managed-cmk
+     * [^6]: https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#customer-cmk
      *
      * @var ServerSideEncryption::*|null
      */
@@ -475,25 +500,41 @@ final class CopyObjectRequest extends Input
     private $sseCustomerKeyMd5;
 
     /**
-     * Specifies the KMS ID (Key ID, Key ARN, or Key Alias) to use for object encryption. All GET and PUT requests for an
-     * object protected by KMS will fail if they're not made via SSL or using SigV4. For information about configuring any
-     * of the officially supported Amazon Web Services SDKs and Amazon Web Services CLI, see Specifying the Signature
+     * Specifies the KMS key ID (Key ID, Key ARN, or Key Alias) to use for object encryption. All GET and PUT requests for
+     * an object protected by KMS will fail if they're not made via SSL or using SigV4. For information about configuring
+     * any of the officially supported Amazon Web Services SDKs and Amazon Web Services CLI, see Specifying the Signature
      * Version in Request Authentication [^1] in the *Amazon S3 User Guide*.
      *
-     * > This functionality is not supported when the destination bucket is a directory bucket.
+     * **Directory buckets** - If you specify `x-amz-server-side-encryption` with `aws:kms`, you must specify the `
+     * x-amz-server-side-encryption-aws-kms-key-id` header with the ID (Key ID or Key ARN) of the KMS symmetric encryption
+     * customer managed key to use. Otherwise, you get an HTTP `400 Bad Request` error. Only use the key ID or key ARN. The
+     * key alias format of the KMS key isn't supported. Your SSE-KMS configuration can only support 1 customer managed key
+     * [^2] per directory bucket for the lifetime of the bucket. Amazon Web Services managed key [^3] (`aws/s3`) isn't
+     * supported.
      *
      * [^1]: https://docs.aws.amazon.com/AmazonS3/latest/dev/UsingAWSSDK.html#specify-signature-version
+     * [^2]: https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#customer-cmk
+     * [^3]: https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#aws-managed-cmk
      *
      * @var string|null
      */
     private $sseKmsKeyId;
 
     /**
-     * Specifies the Amazon Web Services KMS Encryption Context to use for object encryption. The value of this header is a
-     * base64-encoded UTF-8 string holding JSON with the encryption context key-value pairs. This value must be explicitly
-     * added to specify encryption context for `CopyObject` requests.
+     * Specifies the Amazon Web Services KMS Encryption Context as an additional encryption context to use for the
+     * destination object encryption. The value of this header is a base64-encoded UTF-8 string holding JSON with the
+     * encryption context key-value pairs.
      *
-     * > This functionality is not supported when the destination bucket is a directory bucket.
+     * **General purpose buckets** - This value must be explicitly added to specify encryption context for `CopyObject`
+     * requests if you want an additional encryption context for your destination object. The additional encryption context
+     * of the source object won't be copied to the destination object. For more information, see Encryption context [^1] in
+     * the *Amazon S3 User Guide*.
+     *
+     * **Directory buckets** - You can optionally provide an explicit encryption context value. The value must match the
+     * default encryption context - the bucket Amazon Resource Name (ARN). An additional encryption context value is not
+     * supported.
+     *
+     * [^1]: https://docs.aws.amazon.com/AmazonS3/latest/userguide/UsingKMSEncryption.html#encryption-context
      *
      * @var string|null
      */
@@ -509,9 +550,13 @@ final class CopyObjectRequest extends Input
      *
      * For more information, see Amazon S3 Bucket Keys [^1] in the *Amazon S3 User Guide*.
      *
-     * > This functionality is not supported when the destination bucket is a directory bucket.
+     * > **Directory buckets** - S3 Bucket Keys aren't supported, when you copy SSE-KMS encrypted objects from general
+     * > purpose buckets to directory buckets, from directory buckets to general purpose buckets, or between directory
+     * > buckets, through CopyObject [^2]. In this case, Amazon S3 makes a call to KMS every time a copy request is made for
+     * > a KMS-encrypted object.
      *
      * [^1]: https://docs.aws.amazon.com/AmazonS3/latest/dev/bucket-key.html
+     * [^2]: https://docs.aws.amazon.com/AmazonS3/latest/API/API_CopyObject.html
      *
      * @var bool|null
      */

diff --git a/src/Service/S3/src/Input/CreateMultipartUploadRequest.php b/src/Service/S3/src/Input/CreateMultipartUploadRequest.php
@@ -316,7 +316,36 @@ final class CreateMultipartUploadRequest extends Input
     /**
      * The server-side encryption algorithm used when you store this object in Amazon S3 (for example, `AES256`, `aws:kms`).
      *
-     * > For directory buckets, only server-side encryption with Amazon S3 managed keys (SSE-S3) (`AES256`) is supported.
+     * - **Directory buckets ** - For directory buckets, there are only two supported options for server-side encryption:
+     *   server-side encryption with Amazon S3 managed keys (SSE-S3) (`AES256`) and server-side encryption with KMS keys
+     *   (SSE-KMS) (`aws:kms`). We recommend that the bucket's default encryption uses the desired encryption configuration
+     *   and you don't override the bucket default encryption in your `CreateSession` requests or `PUT` object requests.
+     *   Then, new objects are automatically encrypted with the desired encryption settings. For more information, see
+     *   Protecting data with server-side encryption [^1] in the *Amazon S3 User Guide*. For more information about the
+     *   encryption overriding behaviors in directory buckets, see Specifying server-side encryption with KMS for new object
+     *   uploads [^2].
+     *
+     *   In the Zonal endpoint API calls (except CopyObject [^3] and UploadPartCopy [^4]) using the REST API, the encryption
+     *   request headers must match the encryption settings that are specified in the `CreateSession` request. You can't
+     *   override the values of the encryption settings (`x-amz-server-side-encryption`,
+     *   `x-amz-server-side-encryption-aws-kms-key-id`, `x-amz-server-side-encryption-context`, and
+     *   `x-amz-server-side-encryption-bucket-key-enabled`) that are specified in the `CreateSession` request. You don't
+     *   need to explicitly specify these encryption settings values in Zonal endpoint API calls, and Amazon S3 will use the
+     *   encryption settings values from the `CreateSession` request to protect new objects in the directory bucket.
+     *
+     *   > When you use the CLI or the Amazon Web Services SDKs, for `CreateSession`, the session token refreshes
+     *   > automatically to avoid service interruptions when a session expires. The CLI or the Amazon Web Services SDKs use
+     *   > the bucket's default encryption configuration for the `CreateSession` request. It's not supported to override the
+     *   > encryption settings values in the `CreateSession` request. So in the Zonal endpoint API calls (except CopyObject
+     *   > [^5] and UploadPartCopy [^6]), the encryption request headers must match the default encryption configuration of
+     *   > the directory bucket.
+     *
+     * [^1]: https://docs.aws.amazon.com/AmazonS3/latest/userguide/s3-express-serv-side-encryption.html
+     * [^2]: https://docs.aws.amazon.com/AmazonS3/latest/userguide/s3-express-specifying-kms-encryption.html
+     * [^3]: https://docs.aws.amazon.com/AmazonS3/latest/API/API_CopyObject.html
+     * [^4]: https://docs.aws.amazon.com/AmazonS3/latest/API/API_UploadPartCopy.html
+     * [^5]: https://docs.aws.amazon.com/AmazonS3/latest/API/API_CopyObject.html
+     * [^6]: https://docs.aws.amazon.com/AmazonS3/latest/API/API_UploadPartCopy.html
      *
      * @var ServerSideEncryption::*|null
      */
@@ -378,33 +407,59 @@ final class CreateMultipartUploadRequest extends Input
     private $sseCustomerKeyMd5;
 
     /**
-     * Specifies the ID (Key ID, Key ARN, or Key Alias) of the symmetric encryption customer managed key to use for object
-     * encryption.
+     * Specifies the KMS key ID (Key ID, Key ARN, or Key Alias) to use for object encryption. If the KMS key doesn't exist
+     * in the same account that's issuing the command, you must use the full Key ARN not the Key ID.
      *
-     * > This functionality is not supported for directory buckets.
+     * **General purpose buckets** - If you specify `x-amz-server-side-encryption` with `aws:kms` or `aws:kms:dsse`, this
+     * header specifies the ID (Key ID, Key ARN, or Key Alias) of the KMS key to use. If you specify
+     * `x-amz-server-side-encryption:aws:kms` or `x-amz-server-side-encryption:aws:kms:dsse`, but do not provide
+     * `x-amz-server-side-encryption-aws-kms-key-id`, Amazon S3 uses the Amazon Web Services managed key (`aws/s3`) to
+     * protect the data.
+     *
+     * **Directory buckets** - If you specify `x-amz-server-side-encryption` with `aws:kms`, you must specify the `
+     * x-amz-server-side-encryption-aws-kms-key-id` header with the ID (Key ID or Key ARN) of the KMS symmetric encryption
+     * customer managed key to use. Otherwise, you get an HTTP `400 Bad Request` error. Only use the key ID or key ARN. The
+     * key alias format of the KMS key isn't supported. Your SSE-KMS configuration can only support 1 customer managed key
+     * [^1] per directory bucket for the lifetime of the bucket. Amazon Web Services managed key [^2] (`aws/s3`) isn't
+     * supported.
+     *
+     * [^1]: https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#customer-cmk
+     * [^2]: https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#aws-managed-cmk
      *
      * @var string|null
      */
     private $sseKmsKeyId;
 
     /**
      * Specifies the Amazon Web Services KMS Encryption Context to use for object encryption. The value of this header is a
-     * base64-encoded UTF-8 string holding JSON with the encryption context key-value pairs.
+     * Base64-encoded string of a UTF-8 encoded JSON, which contains the encryption context as key-value pairs.
      *
-     * > This functionality is not supported for directory buckets.
+     * **Directory buckets** - You can optionally provide an explicit encryption context value. The value must match the
+     * default encryption context - the bucket Amazon Resource Name (ARN). An additional encryption context value is not
+     * supported.
      *
      * @var string|null
      */
     private $sseKmsEncryptionContext;
 
     /**
      * Specifies whether Amazon S3 should use an S3 Bucket Key for object encryption with server-side encryption using Key
-     * Management Service (KMS) keys (SSE-KMS). Setting this header to `true` causes Amazon S3 to use an S3 Bucket Key for
-     * object encryption with SSE-KMS.
-     *
-     * Specifying this header with an object action doesn’t affect bucket-level settings for S3 Bucket Key.
-     *
-     * > This functionality is not supported for directory buckets.
+     * Management Service (KMS) keys (SSE-KMS).
+     *
+     * **General purpose buckets** - Setting this header to `true` causes Amazon S3 to use an S3 Bucket Key for object
+     * encryption with SSE-KMS. Also, specifying this header with a PUT action doesn't affect bucket-level settings for S3
+     * Bucket Key.
+     *
+     * **Directory buckets** - S3 Bucket Keys are always enabled for `GET` and `PUT` operations in a directory bucket and
+     * can’t be disabled. S3 Bucket Keys aren't supported, when you copy SSE-KMS encrypted objects from general purpose
+     * buckets to directory buckets, from directory buckets to general purpose buckets, or between directory buckets,
+     * through CopyObject [^1], UploadPartCopy [^2], the Copy operation in Batch Operations [^3], or the import jobs [^4].
+     * In this case, Amazon S3 makes a call to KMS every time a copy request is made for a KMS-encrypted object.
+     *
+     * [^1]: https://docs.aws.amazon.com/AmazonS3/latest/API/API_CopyObject.html
+     * [^2]: https://docs.aws.amazon.com/AmazonS3/latest/API/API_UploadPartCopy.html
+     * [^3]: https://docs.aws.amazon.com/AmazonS3/latest/userguide/directory-buckets-objects-Batch-Ops
+     * [^4]: https://docs.aws.amazon.com/AmazonS3/latest/userguide/create-import-job
      *
      * @var bool|null
      */

diff --git a/src/Service/S3/src/Input/GetBucketEncryptionRequest.php b/src/Service/S3/src/Input/GetBucketEncryptionRequest.php
@@ -12,6 +12,14 @@ final class GetBucketEncryptionRequest extends Input
     /**
      * The name of the bucket from which the server-side encryption configuration is retrieved.
      *
+     * **Directory buckets ** - When you use this operation with a directory bucket, you must use path-style requests in the
+     * format `https://s3express-control.*region_code*.amazonaws.com/*bucket-name*`. Virtual-hosted-style requests aren't
+     * supported. Directory bucket names must be unique in the chosen Availability Zone. Bucket names must also follow the
+     * format `*bucket_base_name*--*az_id*--x-s3` (for example, `*DOC-EXAMPLE-BUCKET*--*usw2-az1*--x-s3`). For information
+     * about bucket naming restrictions, see Directory bucket naming rules [^1] in the *Amazon S3 User Guide*
+     *
+     * [^1]: https://docs.aws.amazon.com/AmazonS3/latest/userguide/directory-bucket-naming-rules.html
+     *
      * @required
      *
      * @var string|null
@@ -22,6 +30,9 @@ final class GetBucketEncryptionRequest extends Input
      * The account ID of the expected bucket owner. If the account ID that you provide does not match the actual owner of
      * the bucket, the request fails with the HTTP status code `403 Forbidden` (access denied).
      *
+     * > For directory buckets, this header is not supported in this API operation. If you specify this header, the request
+     * > fails with the HTTP status code `501 Not Implemented`.
+     *
      * @var string|null
      */
     private $expectedBucketOwner;