diff options
Diffstat (limited to 'PROTOCOL.u2f')
-rw-r--r-- | PROTOCOL.u2f | 98 |
1 files changed, 18 insertions, 80 deletions
diff --git a/PROTOCOL.u2f b/PROTOCOL.u2f index 5b8a06277..f8ca56b11 100644 --- a/PROTOCOL.u2f +++ b/PROTOCOL.u2f | |||
@@ -154,6 +154,16 @@ by trusted hardware before it will issue a certificate. To support this | |||
154 | case, OpenSSH optionally allows retaining the attestation information | 154 | case, OpenSSH optionally allows retaining the attestation information |
155 | at the time of key generation. It will take the following format: | 155 | at the time of key generation. It will take the following format: |
156 | 156 | ||
157 | string "ssh-sk-attest-v01" | ||
158 | string attestation certificate | ||
159 | string enrollment signature | ||
160 | string authenticator data (CBOR encoded) | ||
161 | uint32 reserved flags | ||
162 | string reserved string | ||
163 | |||
164 | A previous version of this format, emitted prior to OpenSSH 8.4 omitted | ||
165 | the authenticator data. | ||
166 | |||
157 | string "ssh-sk-attest-v00" | 167 | string "ssh-sk-attest-v00" |
158 | string attestation certificate | 168 | string attestation certificate |
159 | string enrollment signature | 169 | string enrollment signature |
@@ -267,87 +277,15 @@ regress testing. For this reason, OpenSSH shall support a dynamically- | |||
267 | loaded middleware libraries to communicate with security keys, but offer | 277 | loaded middleware libraries to communicate with security keys, but offer |
268 | support for the common case of USB HID security keys internally. | 278 | support for the common case of USB HID security keys internally. |
269 | 279 | ||
270 | The middleware library need only expose a handful of functions: | 280 | The middleware library need only expose a handful of functions and |
271 | 281 | numbers listed in sk-api.h. Included in the defined numbers is a | |
272 | #define SSH_SK_VERSION_MAJOR 0x00050000 /* API version */ | 282 | SSH_SK_VERSION_MAJOR that should be incremented for each incompatible |
273 | #define SSH_SK_VERSION_MAJOR_MASK 0xffff0000 | ||
274 | |||
275 | /* Flags */ | ||
276 | #define SSH_SK_USER_PRESENCE_REQD 0x01 | ||
277 | #define SSH_SK_USER_VERIFICATION_REQD 0x04 | ||
278 | #define SSH_SK_RESIDENT_KEY 0x20 | ||
279 | |||
280 | /* Algs */ | ||
281 | #define SSH_SK_ECDSA 0x00 | ||
282 | #define SSH_SK_ED25519 0x01 | ||
283 | |||
284 | /* Error codes */ | ||
285 | #define SSH_SK_ERR_GENERAL -1 | ||
286 | #define SSH_SK_ERR_UNSUPPORTED -2 | ||
287 | #define SSH_SK_ERR_PIN_REQUIRED -3 | ||
288 | #define SSH_SK_ERR_DEVICE_NOT_FOUND -4 | ||
289 | |||
290 | struct sk_enroll_response { | ||
291 | uint8_t *public_key; | ||
292 | size_t public_key_len; | ||
293 | uint8_t *key_handle; | ||
294 | size_t key_handle_len; | ||
295 | uint8_t *signature; | ||
296 | size_t signature_len; | ||
297 | uint8_t *attestation_cert; | ||
298 | size_t attestation_cert_len; | ||
299 | }; | ||
300 | |||
301 | struct sk_sign_response { | ||
302 | uint8_t flags; | ||
303 | uint32_t counter; | ||
304 | uint8_t *sig_r; | ||
305 | size_t sig_r_len; | ||
306 | uint8_t *sig_s; | ||
307 | size_t sig_s_len; | ||
308 | }; | ||
309 | |||
310 | struct sk_resident_key { | ||
311 | uint32_t alg; | ||
312 | size_t slot; | ||
313 | char *application; | ||
314 | struct sk_enroll_response key; | ||
315 | }; | ||
316 | |||
317 | struct sk_option { | ||
318 | char *name; | ||
319 | char *value; | ||
320 | uint8_t important; | ||
321 | }; | ||
322 | |||
323 | /* Return the version of the middleware API */ | ||
324 | uint32_t sk_api_version(void); | ||
325 | |||
326 | /* Enroll a U2F key (private key generation) */ | ||
327 | int sk_enroll(uint32_t alg, | ||
328 | const uint8_t *challenge, size_t challenge_len, | ||
329 | const char *application, uint8_t flags, const char *pin, | ||
330 | struct sk_option **options, | ||
331 | struct sk_enroll_response **enroll_response); | ||
332 | |||
333 | /* Sign a challenge */ | ||
334 | int sk_sign(uint32_t alg, const uint8_t *message, size_t message_len, | ||
335 | const char *application, | ||
336 | const uint8_t *key_handle, size_t key_handle_len, | ||
337 | uint8_t flags, const char *pin, struct sk_option **options, | ||
338 | struct sk_sign_response **sign_response); | ||
339 | |||
340 | /* Enumerate all resident keys */ | ||
341 | int sk_load_resident_keys(const char *pin, struct sk_option **options, | ||
342 | struct sk_resident_key ***rks, size_t *nrks); | ||
343 | |||
344 | The SSH_SK_VERSION_MAJOR should be incremented for each incompatible | ||
345 | API change. | 283 | API change. |
346 | 284 | ||
347 | The options may be used to pass miscellaneous options to the middleware | 285 | miscellaneous options may be passed to the middleware as a NULL- |
348 | as a NULL-terminated array of pointers to struct sk_option. The middleware | 286 | terminated array of pointers to struct sk_option. The middleware may |
349 | may ignore unsupported or unknown options unless the "important" flag is | 287 | ignore unsupported or unknown options unless the "required" flag is set, |
350 | set, in which case it should return failure if an unsupported option is | 288 | in which case it should return failure if an unsupported option is |
351 | requested. | 289 | requested. |
352 | 290 | ||
353 | At present the following options names are supported: | 291 | At present the following options names are supported: |
@@ -368,4 +306,4 @@ In OpenSSH, the middleware will be invoked by using a similar mechanism to | |||
368 | ssh-pkcs11-helper to provide address-space containment of the | 306 | ssh-pkcs11-helper to provide address-space containment of the |
369 | middleware from ssh-agent. | 307 | middleware from ssh-agent. |
370 | 308 | ||
371 | $OpenBSD: PROTOCOL.u2f,v 1.25 2020/08/31 00:17:41 djm Exp $ | 309 | $OpenBSD: PROTOCOL.u2f,v 1.26 2020/09/09 03:08:01 djm Exp $ |