diff --git a/content/en/docs/refguide/installation/upgrading-from-10-to-11/_index.md b/content/en/docs/refguide/installation/upgrading-from-10-to-11/_index.md index ef911f44e9b..73e86d0bf13 100644 --- a/content/en/docs/refguide/installation/upgrading-from-10-to-11/_index.md +++ b/content/en/docs/refguide/installation/upgrading-from-10-to-11/_index.md @@ -169,7 +169,7 @@ After the upgrade, your app may report the following new error: `A microflow tha You can resolve the error by enabling entity access for the microflow that calls the **ShowHomePage** microflow. However, this may not always align with your intended access control strategy. Alternatively, you can create a custom microflow that includes the [Show home page](/refguide/show-home-page/) activity without enabling entity access. You can then call this new microflow instead of the one in the **System** module. Another approach is to call the **Show home page** activity directly within your microflow. -### Amazon S3 SDK Upgrade +### Amazon S3 SDK Upgrade {#amazon-s3-sdk-upgrade} In Mendix 11.6.0 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. 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 new file mode 100644 index 00000000000..8adf5b4f6e3 --- /dev/null +++ b/content/en/docs/refguide10/runtime/custom-settings/amazon-s3-sdk-upgrade.md @@ -0,0 +1,47 @@ +--- +title: "Amazon S3 SDK Upgrade" +url: /refguide10/amazon-s3-sdk-upgrade/ +description: "Describes breaking changes cause by Amazon S3 SDK library upgrade." +--- + +## Introduction + +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. + +## Considerations When Upgrading Amazon S3 SDK + +You will need to consider the following when upgrading to a version of Mendix which uses SDK version 2 for accessing AWS S3 storage. + +### `com.mendix.storage.s3.Region` and `com.mendix.storage.s3.EndPoint` Settings + +SDK version 2 is stricter with these settings. + +* `com.mendix.storage.s3.Region` – always set to the region matching the region of the bucket. + +* `com.mendix.storage.s3.EndPoint` – either do not 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 the following: + +``` text +- 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 + +SDK version 2 does not support AWS Signature v2 which is enabled by the [`com.mendix.storage.s3.UseV2Auth`](/refguide10/custom-settings/#commendixstorages3UseV2Auth) 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 the 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`](/refguide10/custom-settings/#commendixstorages3EncryptionKeys) 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: + +``` text +- 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 10.24.14. 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 new file mode 100644 index 00000000000..2aac35552ab --- /dev/null +++ b/content/en/docs/refguide9/runtime/custom-settings/amazon-s3-sdk-upgrade.md @@ -0,0 +1,47 @@ +--- +title: "Amazon S3 SDK Upgrade" +url: /refguide9/amazon-s3-sdk-upgrade/ +description: "Describes breaking changes cause by Amazon S3 SDK library upgrade." +--- + +## Introduction + +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. + +## Considerations When Upgrading Amazon S3 SDK + +You will need to consider the following when upgrading to a version of Mendix which uses SDK version 2 for accessing AWS S3 storage. + +### `com.mendix.storage.s3.Region` and `com.mendix.storage.s3.EndPoint` Settings + +SDK version 2 is stricter with these settings. + +* `com.mendix.storage.s3.Region` – always set to the region matching the region of the bucket. + +* `com.mendix.storage.s3.EndPoint` – either do not 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 the following: + +``` text +- 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 + +SDK version 2 does not support AWS Signature v2 which is enabled by the [`com.mendix.storage.s3.UseV2Auth`](/refguide9/custom-settings/#commendixstorages3UseV2Auth) 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 the 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`](/refguide9/custom-settings/#commendixstorages3EncryptionKeys) 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: + +``` text +- 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 9.24.41. 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 index 83381ee6790..e2be8f2553e 100644 --- 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/11/11.6.md b/content/en/docs/releasenotes/studio-pro/11/11.6.md index e7076cf2c4b..7cc848d5880 100644 --- a/content/en/docs/releasenotes/studio-pro/11/11.6.md +++ b/content/en/docs/releasenotes/studio-pro/11/11.6.md @@ -154,7 +154,7 @@ Additionally, page parameters can now be marked as **Optional** and be given 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. More information can be found in [Upgrading from Mendix Studio Pro 10 to 11](/refguide/upgrading-from-10-to-11/) and [S3 Storage Service Settings](/refguide/custom-settings/#amazon-s3-storage-service-settings). +* 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 [Upgrading from Mendix Studio Pro 10 to 11](/refguide/upgrading-from-10-to-11/#amazon-s3-sdk-upgrade) and [S3 Storage Service Settings](/refguide/custom-settings/#amazon-s3-storage-service-settings). * We added a consistency check for code actions that have a filename 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. ### Known Issues diff --git a/content/en/docs/releasenotes/studio-pro/9/9.24.md b/content/en/docs/releasenotes/studio-pro/9/9.24.md index a85e3b363cc..7e4f5719453 100644 --- 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