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 5f44c3acc..fd0cd0de0 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.