upstream: Extends the SK API to accept a set of key/value options

for all operations. These are intended to future-proof the API a little by
making it easier to specify additional fields for without having to change
the API version for each.

At present, only two options are defined: one to explicitly specify
the device for an operation (rather than accepting the middleware's
autoselection) and another to specify the FIDO2 username that may
be used when generating a resident key. These new options may be
invoked at key generation time via ssh-keygen -O

This also implements a suggestion from Markus to avoid "int" in favour
of uint32_t for the algorithm argument in the API, to make implementation
of ssh-sk-client/helper a little easier.

feedback, fixes and ok markus@

OpenBSD-Commit-ID: 973ce11704609022ab36abbdeb6bc23c8001eabc

1 files changed, 40 insertions, 7 deletions

diff --git a/PROTOCOL.u2f b/PROTOCOL.u2f
index 5f44c3ac..fd0cd0de 100644
--- a/PROTOCOL.u2f
+++ b/PROTOCOL.u2f
@@ -233,7 +233,7 @@ support for the common case of USB HID security keys internally.
 
 The middleware library need only expose a handful of functions:
 
-	#define SSH_SK_VERSION_MAJOR		0x00030000 /* API version */
+	#define SSH_SK_VERSION_MAJOR		0x00040000 /* API version */
 	#define SSH_SK_VERSION_MAJOR_MASK	0xffff0000
 
 	/* Flags */
@@ -245,6 +245,11 @@ The middleware library need only expose a handful of functions:
 	#define SSH_SK_ECDSA                   0x00
 	#define SSH_SK_ED25519                 0x01
 
+	/* Error codes */
+	#define SSH_SK_ERR_GENERAL		-1
+	#define SSH_SK_ERR_UNSUPPORTED		-2
+	#define SSH_SK_ERR_PIN_REQUIRED		-3
+
 	struct sk_enroll_response {
 		uint8_t *public_key;
 		size_t public_key_len;
@@ -266,35 +271,63 @@ The middleware library need only expose a handful of functions:
 	};
 
 	struct sk_resident_key {
-		uint8_t alg;
+		uint32_t alg;
 		size_t slot;
 		char *application;
 		struct sk_enroll_response key;
 	};
 
+	struct sk_option {
+		char *name;
+		char *value;
+		uint8_t important;
+	};
+
 	/* Return the version of the middleware API */
 	uint32_t sk_api_version(void);
 
 	/* Enroll a U2F key (private key generation) */
-	int sk_enroll(int alg, const uint8_t *challenge, size_t challenge_len,
+	int sk_enroll(uint32_t alg,
+	    const uint8_t *challenge, size_t challenge_len,
 	    const char *application, uint8_t flags, const char *pin,
+	    struct sk_option **options,
 	    struct sk_enroll_response **enroll_response);
 
 	/* Sign a challenge */
-	int sk_sign(int alg, const uint8_t *message, size_t message_len,
+	int sk_sign(uint32_t alg, const uint8_t *message, size_t message_len,
 	    const char *application,
 	    const uint8_t *key_handle, size_t key_handle_len,
-	    uint8_t flags, const char *pin,
+	    uint8_t flags, const char *pin, struct sk_option **options,
 	    struct sk_sign_response **sign_response);
 
 	/* Enumerate all resident keys */
-	int sk_load_resident_keys(const char *pin,
+	int sk_load_resident_keys(const char *pin, struct sk_option **options,
 	    struct sk_resident_key ***rks, size_t *nrks);
 
 The SSH_SK_VERSION_MAJOR should be incremented for each incompatible
 API change.
 
-In OpenSSH, these will be invoked by using a similar mechanism to
+The options may be used to pass miscellaneous options to the middleware
+as a NULL-terminated array of pointers to struct sk_option. The middleware
+may ignore unsupported or unknown options unless the "important" flag is
+set, in which case it should return failure if an unsupported option is
+requested.
+
+At present the following options names are supported:
+
+	"device"
+
+	Specifies a specific FIDO device on which to perform the
+	operation. The value in this field is interpreted by the
+	middleware but it would be typical to specify a path to
+	a /dev node for the device in question.
+
+	"user"
+
+	Specifies the FIDO2 username used when enrolling a key,
+	overriding OpenSSH's default of using an all-zero username.
+
+In OpenSSH, the middleware will be invoked by using a similar mechanism to
 ssh-pkcs11-helper to provide address-space containment of the
 middleware from ssh-agent.