Add S3 SDK upgrade doc to 9 and 10 and reference from the release notes.

emirmx · emirmx · commit af6347d647ef · 2026-01-26T16:16:38.000+01:00
diff --git a/content/en/docs/refguide10/runtime/custom-settings/amazon-s3-sdk-upgrade.md b/content/en/docs/refguide10/runtime/custom-settings/amazon-s3-sdk-upgrade.md
@@ -0,0 +1,43 @@
+---
+title: "Amazon S3 SDK Upgrade"
+url: /refguide10/amazon-s3-sdk-upgrade/
+description: "Describes breaking changes cause by Amazon S3 SDK library upgrade."
+---
+
+### Amazon S3 SDK Upgrade
+
+In Mendix 10.24.14 we upgraded the AWS SDK used for accessing S3 storage from version 1 to version 2. SDK version 2 has some [differences](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/migration-s3.html) which affects our S3 storage implementation.
+
+#### `com.mendix.storage.s3.Region` / `com.mendix.storage.s3.EndPoint` Settings
+
+SDK version 2 is stricter with these settings.
+
+The `com.mendix.storage.s3.Region` setting must always be set to the region matching the region of the bucket.
+
+The `com.mendix.storage.s3.EndPoint` setting must either not be set or set to an endpoint matching the region, for example: `s3.eu-west-1.amazonaws.com`.
+
+When the region is not specified or there is an incompatibility between the two settings above, error logs will contain entries similar to following:
+
+```
+- Unable to load region from any of the providers in the chain.
+- The bucket you are attempting to access must be addressed using the specified endpoint.
+- The authorization header is malformed; the region 'us-east-1' is wrong.
+```
+
+#### AWS Signature V2 Support (`com.mendix.storage.s3.UseV2Auth` Setting)
+
+SDK version 2 does not support AWS Signature v2 which is enabled by `UseV2Auth` setting. This signature type is deprecated, and is not supported by new regions. For more information, see [AWS's Documentation](https://docs.aws.amazon.com/AmazonS3/latest/API/specify-signature-version.html).
+
+We do not expect this to have any effect when using Amazon S3. It will, however, prevent use of S3 compatible solutions which only support the v2 signature type. In situations like that, you need to switch to either Amazon S3 or a compatible solution that supports newer signature types.
+
+#### Client Side Encryption Changes
+
+Client side encryption can be enabled using the `com.mendix.storage.s3.EncryptionKeys` setting. Previously, any encryption algorithm supported by the JDK could be used. With the new SDK only AES is supported.
+
+An error similar to the following will be printed in logs when an algorithm other than AES is used:
+
+```
+- Unsupported algorithm: DES
+```
+
+If you use an encryption algorithm other than `AES`, then all existing files should be migrated to use `AES` before upgrading to Mendix 11.6. This can be done by configuring a new `AES` key and rewriting all file documents.
diff --git a/content/en/docs/refguide9/runtime/custom-settings/amazon-s3-sdk-upgrade.md b/content/en/docs/refguide9/runtime/custom-settings/amazon-s3-sdk-upgrade.md
@@ -0,0 +1,43 @@
+---
+title: "Amazon S3 SDK Upgrade"
+url: /refguide10/amazon-s3-sdk-upgrade/
+description: "Describes breaking changes cause by Amazon S3 SDK library upgrade."
+---
+
+### Amazon S3 SDK Upgrade
+
+In Mendix 9.24.41 we upgraded the AWS SDK used for accessing S3 storage from version 1 to version 2. SDK version 2 has some [differences](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/migration-s3.html) which affects our S3 storage implementation.
+
+#### `com.mendix.storage.s3.Region` / `com.mendix.storage.s3.EndPoint` Settings
+
+SDK version 2 is stricter with these settings.
+
+The `com.mendix.storage.s3.Region` setting must always be set to the region matching the region of the bucket.
+
+The `com.mendix.storage.s3.EndPoint` setting must either not be set or set to an endpoint matching the region, for example: `s3.eu-west-1.amazonaws.com`.
+
+When the region is not specified or there is an incompatibility between the two settings above, error logs will contain entries similar to following:
+
+```
+- Unable to load region from any of the providers in the chain.
+- The bucket you are attempting to access must be addressed using the specified endpoint.
+- The authorization header is malformed; the region 'us-east-1' is wrong.
+```
+
+#### AWS Signature V2 Support (`com.mendix.storage.s3.UseV2Auth` Setting)
+
+SDK version 2 does not support AWS Signature v2 which is enabled by `UseV2Auth` setting. This signature type is deprecated, and is not supported by new regions. For more information, see [AWS's Documentation](https://docs.aws.amazon.com/AmazonS3/latest/API/specify-signature-version.html).
+
+We do not expect this to have any effect when using Amazon S3. It will, however, prevent use of S3 compatible solutions which only support the v2 signature type. In situations like that, you need to switch to either Amazon S3 or a compatible solution that supports newer signature types.
+
+#### Client Side Encryption Changes
+
+Client side encryption can be enabled using the `com.mendix.storage.s3.EncryptionKeys` setting. Previously, any encryption algorithm supported by the JDK could be used. With the new SDK only AES is supported.
+
+An error similar to the following will be printed in logs when an algorithm other than AES is used:
+
+```
+- Unsupported algorithm: DES
+```
+
+If you use an encryption algorithm other than `AES`, then all existing files should be migrated to use `AES` before upgrading to Mendix 11.6. This can be done by configuring a new `AES` key and rewriting all file documents.
diff --git a/content/en/docs/releasenotes/studio-pro/10/10.24.md b/content/en/docs/releasenotes/studio-pro/10/10.24.md
@@ -61,7 +61,7 @@ This is the [LTS](/releasenotes/studio-pro/lts-mts/#lts) version 10 release for
 ### Breaking Changes
     
 - Curly braces in a [placeholder text](/refguide/text-box/#placeholder-text) (for example, `{Name}`) must now be escaped with an extra opening curly brace (for example, `{{Name}`) to prevent the text from being incorrectly interpreted as a placeholder expression.
-- We upgraded the AWS S3 library used for S3 file storage backend from version 1 to 2. This new version of the library has stricter configuration handling and only supports AES for client side encryption.
+- We upgraded the AWS S3 library used for S3 file storage backend from version 1 to 2. This new version of the library has stricter configuration handling and only supports AES for client side encryption. More information can be found in [Amazon S3 SDK Upgrade](/refguide10/amazon-s3-sdk-upgrade/) and [S3 Storage Service Settings](/refguide10/custom-settings/#amazon-s3-storage-service-settings).
 - Added a consistency check for code actions that have a file name that does not match the casing of the document name, which could cause issues on certain operating systems and when deploying to the cloud environment.
 
 ## 10.24.13 {#102413}
diff --git a/content/en/docs/releasenotes/studio-pro/9/9.24.md b/content/en/docs/releasenotes/studio-pro/9/9.24.md
@@ -60,7 +60,7 @@ This is the [LTS](/releasenotes/studio-pro/lts-mts/#lts) version 9 release for a
 
 ### Breaking Changes
     
-- We upgraded the AWS S3 library used for S3 file storage backend from version 1 to 2. This new version of the library has stricter configuration handling and only supports AES for client side encryption.
+- We upgraded the AWS S3 library used for S3 file storage backend from version 1 to 2. This new version of the library has stricter configuration handling and only supports AES for client side encryption. More information can be found in [Amazon S3 SDK Upgrade](/refguide9/amazon-s3-sdk-upgrade/) and [S3 Storage Service Settings](/refguide9/custom-settings/#amazon-s3-storage-service-settings).
 
 ## 9.24.40
 
