===================================================================
RCS file: /cvsrepo/anoncvs/cvs/src/usr.bin/ssh/PROTOCOL.u2f,v
retrieving revision 1.16
retrieving revision 1.17
diff -u -r1.16 -r1.17
--- src/usr.bin/ssh/PROTOCOL.u2f	2019/12/30 09:25:29	1.16
+++ src/usr.bin/ssh/PROTOCOL.u2f	2020/01/06 02:00:46	1.17
@@ -233,7 +233,7 @@
 
 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 @@
 	#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 @@
 	};
 
 	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.