Design key import/generation for the signer API

[jku]

With #456 the signer API comes a lot closer to being a "fully featured API". The missing part is key generation and import (and maybe storing private keys)

Related issues: #446, #408, #280, #451 (and probably more)

Current status (after #456):

• Using signers and keys is possible without knowing the signer or key implementation, and without using the "old" API
• except to create keys this sort of code is typically used:

  key = keys.generate_ed25519_key() # key is a dictionary. keys is a module we would like to start hiding from users
  pubkey = SSlibKey.from_securesystemslib_key(key) # pubkey is an implementation of Key
  signer = Signer.from_priv_key_uri("file:path/to/file?encrypted=false", pubkey) # signer is an implementation of Signer
  
  

• the key dictionary is only used as an intermediate step

Proposal

• Signer implementations should provide implementation specific methods to create new keys or import them from other systems
• these methods may have whatever arguments they need
• Signer should expose the public key so callers can access it
• typical usage:

  # call implementation specific API (in this case SSlibsigner to generate a ed25519 key)
  signer = SSlibSigner.new_ed25519(...) 
  pubkey = signer.public_key
  

• this hides the keys module from users, and makes SSlibKey.from_securesystemslib_key unneeded
• AFAICT this should work for KMS, HSM, GPG, ...
• The implementation specific method could live elsewhere as well, but it seemed like it would make most sense in signer.

---

The part I have not 100% figured out is private key storage: how and when do you store the private key content in a way that you can then use the from_priv_key_uri() to load it again. This is somewhat different depending on the key type and in many cases does not even make sense (you can't really store environment variables)... possibly it should happen during the constructor, so SSlibSigner.new_ed25519() could actually take a priv_key_uri argument and and the generated key would immediately get stored ?

[jku]

As background for why the public_key should be a Signer property, and why I think import/generate-methods should be Signer implementation specific constructors:

In real-world scenarios, if you generate/import a Key, you always want to "connect" that to a specific signer, or at least the private key uri: you never want to just generate a Key because then how would you know how to sign for that Key? Somehow you need to be able to connect a signer private key uri to a keyid: we can leave that to the user of course but if both are properties of the Signer, that gets solved neatly

As an example if you import a public key from a Yubikey, you then always want to store configuration like
{"abcd": "hsm:yubikeylabelhere"} where abcd is the keyid of the public key, because otherwise the application would never know how to sign for abcd (or even that it should sign for abcd).

Constructing a Signer is not the only solution but I think it makes sense. Something like this

# import signer and key from a yubikey
signer = Signer.import("hsm:")
# store the whole public key in metadata, and private key access details
# (private key uri, keyid, maybe other things) in application configuration
repo.set_targets_key(signer.public_key)
configuration.save_signer(signer)

[jku]

So I guess the signer implementation specific APIs look roughly like this -- probably no signer is going to implement all three types of methods (and some signers might implement multiple versions of some methods):

Possible implementation specific methods:

• import(...): get everything, including public key, from "keyvault": for GCP and HSM at least. arguments should be data that is enough to construct a private key uri. Examples:
  • GCPSigner.import(gcp_key_id: str) -> GCPSigner
  • HSMSigner.import() -> HSMSigner (optional args like token_label may get added later)
• generate(...): construct new keys: this applies to e.g. SSlibSigner but not GCP or HSM. This likely needs not just the key parameters, but enough info to know how to generate a private key uri. Possible examples
  • SSlibSigner.generate_rsa(uri: str, bits: int, scheme: str) -> SSlibSSigner
  • SSlibSigner.generate_ecdsa(uri: str, bits: int) -> SSlibSSigner
• write() or secret() for storing/accessing key content: for those signers that actually want to write the private key material somewhere -- either a file or just the terminal output: currently this is just SSlibSigner with file: and envvar:
  • SSlibSigner.write() -- if uri scheme is "file:", then this writes the file
  • SSlibSigner.secret() -> str -- returns the private key content (useful for "envvar:" scheme)

Common properties I think Signer interface should require:

• priv_key_uri: str -- needed by application to when it wants to store the private key access details
• public_key: Key -- for public key import, for storing private key access details, but also for signing in some cases