docs: decision record about key management (#4736)

* docs: decision record about key management * Update README.md * pr remarks * Apply suggestions from code review Co-authored-by: Jim Marino <[email protected]> * Update docs/developer/decision-records/2025-01-17-key-management-improvement/README.md Co-authored-by: andrea bertagnolli <[email protected]> --------- Co-authored-by: Jim Marino <[email protected]> Co-authored-by: andrea bertagnolli <[email protected]>
eclipse-edc · Jan 22, 2025 · f5bead2 · f5bead2
1 parent cf5d77e
commit f5bead2
Show file tree

Hide file tree

Showing 2 changed files with 68 additions and 0 deletions.
diff --git a/docs/developer/decision-records/2025-01-17-key-management-improvement/README.md b/docs/developer/decision-records/2025-01-17-key-management-improvement/README.md
@@ -0,0 +1,66 @@
+# 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 by the `SigningService`
+- remote signing: it should be possible to cryptographically sign payloads "remotely", i.e. outside of EDC
+
+## Rationale
+
+Production-grade enterprise deployments of the Connector and other components will require
+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 over the network, and signing the payload locally, which carries some risk of exposure, leakage,
+mishandling etc.,
+EDC will transmit the payload to the vault, have the payload signed/encrypted there and transmit the signature or
+encrypted payload back.
+
+With this, the private key never leaves the vault, thus avoiding any risk of key exposure or leakage.
+
+> _Note that there may be a penalty on latency, especially when transmitting very large payloads, such as
+VerifiablePresentations that contain many large VerifiableCredentials!_
+
+## Approach
+
+### Implementation Remote signing
+
+- add new interface `SigningService` that declares two methods:
+  ```java
+  public interface SigningService {
+    byte[] sign(String keyId, byte[] data);  
+    boolean verify(String keyId, byte[] signature);
+  }
+  ```
+- the default implementation performs signing and verifying exactly as implemented currently, pulling keys out of the
+  vault and performing the signing locally.
+- For each vault technology, there would be a `SigningService` implementation
+- Custom implementations of `JWSSigner` and `JWSVerifier` (from Nimbus) named `RemoteJwsSigner` and `RemoteJwsVerifier`
+  respectively, will delegate signing and verifying to the `SigningService`.
+  These objects are provided by an extension.
+- A configuration value `edc.signing.remote.enable` will be added to enable/disable remote signing
+
+### Implementation Key Rotation
+
+- Add `rotate(String keyId, Map<String, Object> keyProperties)` method to the `SigningService` to specify the algorithm
+  and cryptographic properties as well as the TTL (time-to-live)
+- IdentityHub: `KeyPairServiceImpl` calls `SigningService#rotate()` when rotating keys
+- Configuration values:
+    - `edc.signing.keys.rotation.enable`: enable/disable automatic rotation
+    - `edc.signing.keys.rotation.algorithm`: the cryptographic algorithm
+    - `edc.signing.keys.rotation.ttl`: time-to-live (in days) for keys, until they get rotated automatically
+
+_Note: necessary implementations on Technology repos are not listed here_
+
+### 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).
diff --git a/docs/developer/decision-records/README.md b/docs/developer/decision-records/README.md
@@ -68,4 +68,6 @@
 - [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)
+
 - [2025-01-21 Multiple Protocol Webhooks](./2025-01-21-multipe-protocol-webhooks)