diff options
author | djm@openbsd.org <djm@openbsd.org> | 2020-01-06 02:00:46 +0000 |
---|---|---|
committer | Damien Miller <djm@mindrot.org> | 2020-01-06 13:12:46 +1100 |
commit | c312ca077cd2a6c15545cd6b4d34ee2f69289174 (patch) | |
tree | b8dd974c55dd0de351dfcbfc4f33fddb935a1c12 /PROTOCOL.u2f | |
parent | 2ab335712d084d9ccaf3f53afc3fa9535329da87 (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.u2f | 47 |
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 | ||
234 | The middleware library need only expose a handful of functions: | 234 | The 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 | ||
294 | The SSH_SK_VERSION_MAJOR should be incremented for each incompatible | 307 | The SSH_SK_VERSION_MAJOR should be incremented for each incompatible |
295 | API change. | 308 | API change. |
296 | 309 | ||
297 | In OpenSSH, these will be invoked by using a similar mechanism to | 310 | The options may be used to pass miscellaneous options to the middleware |
311 | as a NULL-terminated array of pointers to struct sk_option. The middleware | ||
312 | may ignore unsupported or unknown options unless the "important" flag is | ||
313 | set, in which case it should return failure if an unsupported option is | ||
314 | requested. | ||
315 | |||
316 | At 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 | |||
330 | In OpenSSH, the middleware will be invoked by using a similar mechanism to | ||
298 | ssh-pkcs11-helper to provide address-space containment of the | 331 | ssh-pkcs11-helper to provide address-space containment of the |
299 | middleware from ssh-agent. | 332 | middleware from ssh-agent. |
300 | 333 | ||