docs: decision record about key management

docs/developer/decision-records/2025-01-17-key-management-improvement/README.md

@@ -0,0 +1,52 @@
+# Improvements to the handling of cryptographic keys and signatures
+
+## Decision
+
+We will extend the capabilities of our private key management in the following aspects:
+
+- key rotation: key pairs should get rotated automatically
+- remote signing: it should be possible to cryptographically sign payloads "remotely", i.e. outside of EDC
+
+## Rationale
+
+It will be necessary for production-grade enterprise deployments of the Connector and other components to have
+centralized key management capabilities, where key pairs are automatically rotated to defend against key attrition. This
+is typically implemented by HSMs such as Hashicorp Vault.
+
+In a similar fashion EDC will provide a feature to "remotely sign" payloads. Instead of transmitting the private key
+from the vault to EDC and signing the payload locally, which carries some risk of exposure, leakage, mishandling etc.,
+EDC will transmit the payload to the vault and have the content signed there.
+
+With this, the private key never leaves the vault, thus avoiding any risk of key exposure or leakage.
+
+> _Note that there may be an adversarial impact on latency, especially when transmitting very large payloads, such as
+VerifiablePresentations with many large VerifiableCredentials!_
+
+## Approach
+
+### Implementation Remote signing
+
+- add `byte[] sign(String keyId, byte[] data)` method to `Vault`
+- implement custom `JWSSigner` (from Nimbus) named `RemoteJwsSigner`, that delegates signing to the `Vault`. This custom
+  `JWSSigner` is provided as extension.
+- configuration values: `edc.vault.signing.enable` to enable/disable remote signing
+
+### Implementation Key Rotation
+
+- add `rotate(String keyId, Map<String, Object> keyProperties)` method to the `Vault` to specify the algorithm and
+  cryptographic properties as well as the TTL (time-to-live)
+- IdentityHub: `KeyPairServiceImpl` calls `Vault#rotate()` when rotating keys
+- configuration values:
+    - `edc.vault.keys.rotation.enable`: enable/disable automatic rotation
+    - `edc.vault.keys.rotation.algorithm`: the cryptographic algorithm
+    - `edc.vault.keys.rotation.ttl`: time-to-live (in days) for keys, until they get rotated automatically
+
+### Market overview
+
+|                  | Hashicorp Vault                                                         | Azure KeyVault                                                     | AWS KMS                                 |
+|------------------|-------------------------------------------------------------------------|--------------------------------------------------------------------|-----------------------------------------|
+| Remote Signing*) | natively supported (REST)                                               | natively supported (REST, SDK)                                     | natively supported (REST, SDK)          |
+| Key Rotation     | automatic and manual rotation <br/>supported via Transit Secrets Engine | automatic and manual rotation supported <br/>via rotation policies | automatic and manual rotation supported |
+
+*) automatic notifications upon rotation (auto or manual) are supported, but have to be implemented using CSP-specific
+eventing mechanisms, such as EventBridge (AWS) or EventGrid (Azure).

docs/developer/decision-records/README.md

@@ -68,4 +68,5 @@
 - [2024-10-24 bidirectional-data-transfers](./2024-10-24-bidirectional-data-transfers)
 - [2024-11-06 configuration-injection](./2024-11-06-configuration-injection)
 - [2024-11-19 transformer-version-scheme](./2024-11-19-transformer-version-scheme)
+- [2025-01-17 key management improvements](./2025-01-17-key-management-improvement)