From 57e979ec5a137a59cab7295b94d5b6f58336233e Mon Sep 17 00:00:00 2001 From: Stephen Cuppett Date: Sat, 25 Jul 2026 08:36:30 -0400 Subject: [PATCH] docs: document S3 SSE-KMS support and deprecate SSE-C Add documentation for the SSE-KMS (AWS Key Management Service) server-side encryption support introduced in Nextcloud 34 (nextcloud/server#57623). Mark SSE-C as deprecated, noting the AWS policy change that disabled SSE-C by default on new S3 buckets in April 2026 and recommending SSE-KMS for new deployments. Co-Authored-By: Claude Opus 4.6 (1M context) Signed-off-by: Stephen Cuppett --- .../encryption_configuration.rst | 4 +- .../configuration_files/primary_storage.rst | 117 ++++++++++++++---- .../config_sample_php_parameters.rst | 10 ++ 3 files changed, 109 insertions(+), 22 deletions(-) diff --git a/admin_manual/configuration_files/encryption_configuration.rst b/admin_manual/configuration_files/encryption_configuration.rst index 84f89f7c0c2..16c31b71192 100644 --- a/admin_manual/configuration_files/encryption_configuration.rst +++ b/admin_manual/configuration_files/encryption_configuration.rst @@ -95,7 +95,9 @@ Key Points & Limitations SSE does **not** encrypt filenames or folder structures, only file contents. .. note:: - Don't confuse Nextcloud's SSE with S3 SSE-C (also supported). + Don't confuse Nextcloud's SSE with S3 server-side encryption. Nextcloud also supports + :ref:`S3 SSE-KMS ` (recommended) and the deprecated + :ref:`S3 SSE-C ` — both are configured in :doc:`primary_storage`. .. versionchanged:: 9.0.0 Nextcloud (since v9.0.0) supports Authenticated Encryption for all newly encrypted files. diff --git a/admin_manual/configuration_files/primary_storage.rst b/admin_manual/configuration_files/primary_storage.rst index 83b2f517560..54ec276fb56 100644 --- a/admin_manual/configuration_files/primary_storage.rst +++ b/admin_manual/configuration_files/primary_storage.rst @@ -187,6 +187,8 @@ Optional parameters sometimes needing adjustment: * :code:`use_path_style` defaults to :code:`false` * :code:`port` defaults to :code:`443` * :code:`sse_c_key` has no default +* :code:`sse_kms_enabled` defaults to :code:`false` +* :code:`sse_kms_key_id` has no default (uses the bucket default KMS key when omitted) Optional parameters less commonly needing adjustment: @@ -354,38 +356,111 @@ Than any newly created user will have their files put on :code:`server3`. It is possible to mix different object store backends and multibucket and non-multibucket in a multi-instance configuration. +.. _s3-sse-c: + --------------------------- S3 SSE-C encryption support --------------------------- -Nextcloud supports server side encryption, also known as `SSE-C `_, with compatible S3 bucket provider. The encryption and decryption happens on the S3 bucket side with a key provided by the Nextcloud server. +.. deprecated:: 34 + SSE-C support is deprecated. Use :ref:`s3-sse-kms` instead, which provides + centralized key management via AWS KMS and does not require managing encryption + keys on the Nextcloud server. -The key can be specified with the :code:`sse_c_key` parameter which needs to be provided as a base64 encoded string with a maximum length of 32 bytes. A random key could be generated using the the following command: +.. warning:: + Amazon S3 disabled SSE-C by default for all new buckets in April 2026. Existing + buckets that already hold SSE-C encrypted objects retain support, but new buckets + require explicit opt-in via the AWS ``PutBucketEncryption`` API. See the + `AWS announcement `_ + for details. For new deployments, use SSE-KMS instead. -:: +Nextcloud supports server-side encryption with customer-provided keys, also known as +`SSE-C `_, +with compatible S3 providers. The encryption and decryption happens on the S3 side using +a key provided by the Nextcloud server. + +The key is specified with the :code:`sse_c_key` parameter as a base64-encoded string with +a maximum length of 32 bytes. Generate a random key with: + +.. code-block:: bash openssl rand 32 | base64 +The following example shows how to configure the S3 object store with SSE-C encryption +support: -The following example shows how to configure the S3 object store with SSE-C encryption support in the objectstore section of the Nextcloud config.php file: +.. code-block:: php -:: + 'objectstore' => [ + 'class' => 'OC\\Files\\ObjectStore\\S3', + 'arguments' => [ + 'bucket' => 'nextcloud', + 'key' => 'ACCESS_KEY', + 'secret' => 'SECRET_KEY', + 'hostname' => 's3.example.com', + 'port' => 443, + 'use_ssl' => true, + 'use_path_style' => true, + 'autocreate' => true, + 'verify_bucket_exists' => true, + 'sse_c_key' => 'o9d3Q9tHcPMv6TIpH53MSXaUmY91YheZRwuIhwCFRSs=', + ], + ], + +.. _s3-sse-kms: + +----------------------------- +S3 SSE-KMS encryption support +----------------------------- + +.. versionadded:: 34 + +Nextcloud supports server-side encryption using +`AWS Key Management Service (SSE-KMS) `_. +With SSE-KMS, AWS encrypts objects at rest using KMS-managed keys. This provides +centralized key management, IAM-based access controls, CloudTrail audit logging, and +automatic key rotation — without requiring the Nextcloud server to manage encryption keys +directly. + +SSE-KMS is the recommended replacement for :ref:`SSE-C ` for new deployments. + +Two parameters control SSE-KMS: + +* :code:`sse_kms_enabled` — set to :code:`true` to enable SSE-KMS (default: :code:`false`) +* :code:`sse_kms_key_id` — (optional) the ARN of a specific KMS key to use; omit to use the + bucket's default KMS key + +.. note:: If both :code:`sse_c_key` and :code:`sse_kms_enabled` are set, SSE-C takes + precedence. This allows gradual migration from SSE-C to SSE-KMS. + +The following example shows how to configure the S3 object store with SSE-KMS using a +specific KMS key: + +.. code-block:: php + + 'objectstore' => [ + 'class' => 'OC\\Files\\ObjectStore\\S3', + 'arguments' => [ + 'bucket' => 'my-nextcloud-store', + 'region' => 'us-east-1', + 'key' => 'ACCESS_KEY', + 'secret' => 'SECRET_KEY', + 'sse_kms_enabled' => true, + 'sse_kms_key_id' => 'arn:aws:kms:us-east-1:123456789012:key/mrk-abc123', + ], + ], + +To use the bucket's default KMS key instead, omit :code:`sse_kms_key_id`: + +.. code-block:: php 'objectstore' => [ - array ( - 'class' => 'OC\\Files\\ObjectStore\\S3', - 'arguments' => - array ( - 'bucket' => 'nextcloud', - 'key' => 'nextcloud', - 'secret' => 'nextcloud', - 'hostname' => 's3', - 'port' => '443', - 'use_ssl' => true, - 'use_path_style' => true, - 'autocreate' => true, - 'verify_bucket_exists' => true, - 'sse_c_key' => 'o9d3Q9tHcPMv6TIpH53MSXaUmY91YheZRwuIhwCFRSs=', - ), - ); + 'class' => 'OC\\Files\\ObjectStore\\S3', + 'arguments' => [ + 'bucket' => 'my-nextcloud-store', + 'region' => 'us-east-1', + 'key' => 'ACCESS_KEY', + 'secret' => 'SECRET_KEY', + 'sse_kms_enabled' => true, + ], ], diff --git a/admin_manual/configuration_server/config_sample_php_parameters.rst b/admin_manual/configuration_server/config_sample_php_parameters.rst index f6997a2fad3..6642231c507 100644 --- a/admin_manual/configuration_server/config_sample_php_parameters.rst +++ b/admin_manual/configuration_server/config_sample_php_parameters.rst @@ -3199,6 +3199,16 @@ objectstore // using Amazon S3 (or any other implementation that supports it) we recommend enabling it by using "when_supported". 'request_checksum_calculation' => 'when_required', 'response_checksum_validation' => 'when_required', + // optional: Enable SSE-KMS (server-side encryption using AWS Key Management Service). Default: false + // Recommended for new deployments. See admin_manual/configuration_files/primary_storage for details. + 'sse_kms_enabled' => false, + // optional: ARN of a specific KMS key to use for SSE-KMS. Omit to use the bucket default KMS key. + // Example: 'arn:aws:kms:us-east-1:123456789012:key/mrk-abc123' + 'sse_kms_key_id' => '', + // optional: SSE-C (customer-provided key) for server-side encryption. Deprecated in Nextcloud 34. + // Base64-encoded 32-byte key. Generate with: openssl rand 32 | base64 + // AWS disabled SSE-C by default on new buckets in April 2026; use SSE-KMS for new deployments. + 'sse_c_key' => '', ], ],