docs: decision record about key management

[paullatzelsperger]

What this PR changes/adds

adds a decision record outlining planned changes in key management (remote signing, automatic key rotation)

Why it does that

improved security, centralized key management

Further notes

List other areas of code that have changed but are not necessarily linked to the main feature. This could be method
signature changes, package declarations, bugs that were encountered and were fixed inline, etc.

Linked Issue(s)

Closes # <-- insert Issue number if one exists

Please be sure to take a look at the contributing guidelines and our etiquette for pull requests.

[ndr-brt]

Adding this functionalities to the Vault interface will couple the signing process to the Vault instance, maybe it's better to keep them separated, because sign-as-a-service solutions (not provided by vault) could be used.

I would suggest to have a DigitalSignatureService (first name that came to mind), exposing the sign, verify and rotate methods, the default implementation will be the current one, that leverages on the Vault instance to get the keys and sign through nimbus.
Then other implementations could be provided, like for Hashicorp HSM.

[paullatzelsperger]

Coupling the signing process to the Vault isn't necessarily a bad thing, because it reflects reality: most Vaults (Azure, AWS, HCV) support facilities to sign, verify and rotate, in addition to be secure Key-Value stores.

So to me that coupling, and introducing a DigitalSignatureService is not mutually exclusive: the DigitalSignatureService would simply be the "client code" that calls methods on the Vault. To do that, the vault would still have to expose sign, verify and rotate methods.

This would mean, there could be one DigitalSignatureService:

• a VaultSignatureService, that delegates those calls to the Vault if supported, and performs actions locally if not.

If we don't add those methods to the vault, the we'll have pro provide a DigitalSignatureService per Vault, which is unnecessarily complex IMO.

[edit]: it would be the DigitalSignatureService implementation that uses JWSSigner and JWSVerifier objects from Nimbus. IF we went with separate services per Vault, this would introduce a dependency onto Nimbus in each Vault.

[ndr-brt]

[edit]: it would be the DigitalSignatureService implementation that uses JWSSigner and JWSVerifier objects from Nimbus. IF we went with separate services per Vault, this would introduce a dependency onto Nimbus in each Vault.

it's the other way around: the "nimbus way" to sign will just need to be implemented once in a "DigitalSignatureService" implementation (registered by default and eventually overridable), instead to need to be provided for every Vault implementation (because the sign, verify and rotate will need separate implementations for different Vault implementation, but, at the end, they will be the same).

TL;DR: it's the Signature service that uses vault, not the other way around

[paullatzelsperger]

Nimbus is mainly relevant for JWTs, and for that, it is sufficient to provide custom JWSSigner and JWSVerifier objects that we can plug in. We already have a TokenGenerationService, that can be customized with a JWSSigner, all we need is to do the equivalent for the TokenValidationService.

So in a way, JWSSigner/JWSVerifier combined are the DigitalSignatureService

In cases, where non-JWT content is signed, we could directly call the vault methods, I don't think we have such a case ATM though.

[ndr-brt]

I was more referring to changing the Vault interface, that doesn't look the best approach, because signature (also if only JWT) is something that "relies" on vault to sign or it can be done by a vault service, but also by a separate service.

An example is how AWS manages this: Secret Manager keeps secrets, while the signature as a service is made by a different product called KMS.

Keeping the interfaces separated will help flexibility and avoid hard coupling between vault and a signature service

[paullatzelsperger]

To sum up:

If we keep this separate, there would have to be a AwsKmsSignatureService, a AzureVaultSignatureService, a HashicorpVaultSignatureService, a GcpSecretsManagerSignatureService, etc., each provided individually.

Combining this, the JWSSigner and JWSVerifier would delegate to the SignatureService (instead of the Vault).

The default implementation of the SignatureService would simply take a vault, pull the keys out and sign/verify locally.

do i have this correct so far?

[ndr-brt]

Yes, looks good 👍

[paullatzelsperger]

updated the document. wanna give it another look?

[jimmarino]

I added wording suggestions for clarity.

[rafaelmag110]

Small nit:
Isn't this configuration redundant? If you add a remote signing service to your runtime, you'd expect remote signing to be done.
I could imagine a case where the remote signing service is added, only for the edc operator to find out later it wasn't working because it wasn't activated...

[paullatzelsperger]

yes, because doing this on the extension level will bake the mode of signing right into the distribution. with a config value, it's up to the user to either sign locally, or remotely.