feat: add support for S3 SSE-C (customer-provided encryption keys)

[schaurian]

Summary

Adds support for S3 Server-Side Encryption with Customer-provided keys (SSE-C) to the barman-cloud library.

A new optional sseCustomerKey field on S3Credentials references a secret holding a base64-encoded 256-bit AES key. When set, the key is materialized to a file and passed to every barman-cloud command via the --sse-customer-key file:// option.

This is the library-side change needed to close cloudnative-pg/plugin-barman-cloud#646 — S3-compatible providers such as Hetzner Object Storage only support SSE-C for encryption at rest, so the existing bucket-managed encryption field (SSE-S3 / SSE-KMS) cannot be used with them.

What changed

File	Change
pkg/api/config.go	New SSECustomerKey *SecretKeySelector field on S3Credentials (+ generated deepcopy)
pkg/utils/constants.go	SSECustomerKeyFileLocation — the on-disk path for the materialized key
pkg/credentials/env.go	Materialize/remove the key file from the referenced secret (same pattern as the Google credentials file)
pkg/command/commandbuilder.go	Inject --sse-customer-key file://… in the shared appendCloudProviderOptions
pkg/command/commandbuilder_test.go	Unit tests for the AWS SSE-C option
pkg/api/webhooks/config.go	Reject sseCustomerKey combined with data.encryption / wal.encryption (by @andrein, with tests)

Design notes

• Single injection point. The flag is added in appendCloudProviderOptions, through which every command builder already routes (barman-cloud-backup, -wal-archive, -wal-restore, -restore, -backup-list, -backup-delete, -check-wal-archive). SSE-C requires the key on every read and write, so covering the shared chokepoint avoids the classic "backups succeed but restores fail because a read path was missed" footgun.
• Key materialization mirrors the existing Google credentials handling (reconcileGoogleCredentials → a /controller/... file written atomically with 0600), so no new volume-mount plumbing is needed in consumers; the same code path serves both the operator and the plugin sidecar.
• Mutually exclusive with encryption. barman-cloud rejects --sse-customer-key together with --encryption at run time, so ValidateBackupConfiguration now reports one error per offending field (data.encryption, wal.encryption) when sseCustomerKey is set, instead of letting the first backup fail.
• Auth-method independent. The key is materialized before the auth branching in envSetAWSCredentials, so it works with explicit keys, session tokens, and inheritFromIAMRole.

Dependency / rollout

Runtime use requires Barman ≥ 3.20.0, which ships the --sse-customer-key option (EnterpriseDB/barman#973, released 2026-08-27). The plugin-barman-cloud sidecar pins Barman 3.20.0 since v0.15.0. The plugin side of this feature is cloudnative-pg/plugin-barman-cloud#1017.

Testing

• Full task ci run locally (commitlint, spellcheck, golangci-lint v2.13.2, go test ./..., uncommitted-drift check): all green.
• Field-tested by @andrein against a Ceph RGW store that supports only SSE-C, with CloudNativePG 1.30.0 and plugin-barman-cloud#1017 (WAL archiving, base backup, backup-list, retention via backup-delete, and recovery into a new Cluster all working with Encryption: SSE-C objects) — see the comments below.

🤖 Generated with Claude Code

[fkammer]

FYI: barman release is out: https://github.com/EnterpriseDB/barman/releases/tag/release%2F3.20.0

[andrein]

Tested at a300841 against a Ceph RGW object store that supports only SSE-C
(no SSE-S3 or SSE-KMS), with CloudNativePG 1.30.0 and the Barman Cloud plugin
from cloudnative-pg/plugin-barman-cloud#1017 with main merged in for
Barman 3.20.0.

• WAL archiving continuous; objects under wals/ report Encryption: SSE-C
  and return 400 when read without the key
• base backup completed; Backup.status populated by barman-cloud-backup-list
  reading the SSE-C backup.info
• ObjectStore.status.serverRecoveryWindow populated
• retention policy applied on the primary via barman-cloud-backup-delete
• recovery into a new Cluster through externalClusters[].plugin reproduced
  the source database: same row counts, table count and size

--sse-customer-key together with --encryption is rejected by Barman at run
time; schaurian#1 against this branch adds the corresponding check
to ValidateBackupConfiguration.

[schaurian]

Thanks for the test run and the validation change, @andrein — merged schaurian#1 into this branch.

Updated the branch (14f89b6):

• Rebased onto main (v0.6.0); the SSE-C commit and the validation commit are now separate commits on top of it.
• Reworded the body of the validation commit to start with a capital letter: this repo's commitlint enforces body-case: sentence-case, and that was the one task ci failure on the previous head. Author and sign-off are unchanged.
• The SSECustomerKey API comment used to say the field is "orthogonal" to encryption; it now states that the two cannot be combined, matching the validation. Description updated accordingly.

Full task ci (commitlint, spellcheck, golangci-lint v2.13.2, go test ./..., uncommitted-drift check) passes locally on this head.

For the record, Barman 3.20.0 with --sse-customer-key is released, and cloudnative-pg/plugin-barman-cloud#1017 is rebased on a main whose sidecar pins it.