summaryrefslogtreecommitdiff
path: root/PROTOCOL.u2f
diff options
context:
space:
mode:
authordjm@openbsd.org <djm@openbsd.org>2020-01-06 02:00:46 +0000
committerDamien Miller <djm@mindrot.org>2020-01-06 13:12:46 +1100
commitc312ca077cd2a6c15545cd6b4d34ee2f69289174 (patch)
treeb8dd974c55dd0de351dfcbfc4f33fddb935a1c12 /PROTOCOL.u2f
parent2ab335712d084d9ccaf3f53afc3fa9535329da87 (diff)
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
Diffstat (limited to 'PROTOCOL.u2f')
-rw-r--r--PROTOCOL.u2f47
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.
233 233
234The middleware library need only expose a handful of functions: 234The middleware library need only expose a handful of functions:
235 235
236 #define SSH_SK_VERSION_MAJOR 0x00030000 /* API version */ 236 #define SSH_SK_VERSION_MAJOR 0x00040000 /* API version */
237 #define SSH_SK_VERSION_MAJOR_MASK 0xffff0000 237 #define SSH_SK_VERSION_MAJOR_MASK 0xffff0000
238 238
239 /* Flags */ 239 /* Flags */
@@ -245,6 +245,11 @@ The middleware library need only expose a handful of functions:
245 #define SSH_SK_ECDSA 0x00 245 #define SSH_SK_ECDSA 0x00
246 #define SSH_SK_ED25519 0x01 246 #define SSH_SK_ED25519 0x01
247 247
248 /* Error codes */
249 #define SSH_SK_ERR_GENERAL -1
250 #define SSH_SK_ERR_UNSUPPORTED -2
251 #define SSH_SK_ERR_PIN_REQUIRED -3
252
248 struct sk_enroll_response { 253 struct sk_enroll_response {
249 uint8_t *public_key; 254 uint8_t *public_key;
250 size_t public_key_len; 255 size_t public_key_len;
@@ -266,35 +271,63 @@ The middleware library need only expose a handful of functions:
266 }; 271 };
267 272
268 struct sk_resident_key { 273 struct sk_resident_key {
269 uint8_t alg; 274 uint32_t alg;
270 size_t slot; 275 size_t slot;
271 char *application; 276 char *application;
272 struct sk_enroll_response key; 277 struct sk_enroll_response key;
273 }; 278 };
274 279
280 struct sk_option {
281 char *name;
282 char *value;
283 uint8_t important;
284 };
285
275 /* Return the version of the middleware API */ 286 /* Return the version of the middleware API */
276 uint32_t sk_api_version(void); 287 uint32_t sk_api_version(void);
277 288
278 /* Enroll a U2F key (private key generation) */ 289 /* Enroll a U2F key (private key generation) */
279 int sk_enroll(int alg, const uint8_t *challenge, size_t challenge_len, 290 int sk_enroll(uint32_t alg,
291 const uint8_t *challenge, size_t challenge_len,
280 const char *application, uint8_t flags, const char *pin, 292 const char *application, uint8_t flags, const char *pin,
293 struct sk_option **options,
281 struct sk_enroll_response **enroll_response); 294 struct sk_enroll_response **enroll_response);
282 295
283 /* Sign a challenge */ 296 /* Sign a challenge */
284 int sk_sign(int alg, const uint8_t *message, size_t message_len, 297 int sk_sign(uint32_t alg, const uint8_t *message, size_t message_len,
285 const char *application, 298 const char *application,
286 const uint8_t *key_handle, size_t key_handle_len, 299 const uint8_t *key_handle, size_t key_handle_len,
287 uint8_t flags, const char *pin, 300 uint8_t flags, const char *pin, struct sk_option **options,
288 struct sk_sign_response **sign_response); 301 struct sk_sign_response **sign_response);
289 302
290 /* Enumerate all resident keys */ 303 /* Enumerate all resident keys */
291 int sk_load_resident_keys(const char *pin, 304 int sk_load_resident_keys(const char *pin, struct sk_option **options,
292 struct sk_resident_key ***rks, size_t *nrks); 305 struct sk_resident_key ***rks, size_t *nrks);
293 306
294The SSH_SK_VERSION_MAJOR should be incremented for each incompatible 307The SSH_SK_VERSION_MAJOR should be incremented for each incompatible
295API change. 308API change.
296 309
297In OpenSSH, these will be invoked by using a similar mechanism to 310The options may be used to pass miscellaneous options to the middleware
311as a NULL-terminated array of pointers to struct sk_option. The middleware
312may ignore unsupported or unknown options unless the "important" flag is
313set, in which case it should return failure if an unsupported option is
314requested.
315
316At present the following options names are supported:
317
318 "device"
319
320 Specifies a specific FIDO device on which to perform the
321 operation. The value in this field is interpreted by the
322 middleware but it would be typical to specify a path to
323 a /dev node for the device in question.
324
325 "user"
326
327 Specifies the FIDO2 username used when enrolling a key,
328 overriding OpenSSH's default of using an all-zero username.
329
330In OpenSSH, the middleware will be invoked by using a similar mechanism to
298ssh-pkcs11-helper to provide address-space containment of the 331ssh-pkcs11-helper to provide address-space containment of the
299middleware from ssh-agent. 332middleware from ssh-agent.
300 333