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 5b8a0627..f8ca56b1 100644 --- a/PROTOCOL.u2f +++ b/PROTOCOL.u2f @@ -154,6 +154,16 @@ by trusted hardware before it will issue a certificate. To support this case, OpenSSH optionally allows retaining the attestation information at the time of key generation. It will take the following format: + string "ssh-sk-attest-v01" + string attestation certificate + string enrollment signature + string authenticator data (CBOR encoded) + uint32 reserved flags + string reserved string + +A previous version of this format, emitted prior to OpenSSH 8.4 omitted +the authenticator data. + string "ssh-sk-attest-v00" string attestation certificate string enrollment signature @@ -267,87 +277,15 @@ regress testing. For this reason, OpenSSH shall support a dynamically- loaded middleware libraries to communicate with security keys, but offer 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 0x00050000 /* API version */ - #define SSH_SK_VERSION_MAJOR_MASK 0xffff0000 - - /* Flags */ - #define SSH_SK_USER_PRESENCE_REQD 0x01 - #define SSH_SK_USER_VERIFICATION_REQD 0x04 - #define SSH_SK_RESIDENT_KEY 0x20 - - /* Algs */ - #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 - #define SSH_SK_ERR_DEVICE_NOT_FOUND -4 - - struct sk_enroll_response { - uint8_t *public_key; - size_t public_key_len; - uint8_t *key_handle; - size_t key_handle_len; - uint8_t *signature; - size_t signature_len; - uint8_t *attestation_cert; - size_t attestation_cert_len; - }; - - struct sk_sign_response { - uint8_t flags; - uint32_t counter; - uint8_t *sig_r; - size_t sig_r_len; - uint8_t *sig_s; - size_t sig_s_len; - }; - - struct sk_resident_key { - 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(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(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, struct sk_option **options, - struct sk_sign_response **sign_response); - - /* Enumerate all resident keys */ - 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 +The middleware library need only expose a handful of functions and +numbers listed in sk-api.h. Included in the defined numbers is a +SSH_SK_VERSION_MAJOR that should be incremented for each incompatible API change. -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 +miscellaneous options may be passed to the middleware as a NULL- +terminated array of pointers to struct sk_option. The middleware may +ignore unsupported or unknown options unless the "required" flag is set, +in which case it should return failure if an unsupported option is requested. 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 ssh-pkcs11-helper to provide address-space containment of the middleware from ssh-agent. -$OpenBSD: PROTOCOL.u2f,v 1.25 2020/08/31 00:17:41 djm Exp $ +$OpenBSD: PROTOCOL.u2f,v 1.26 2020/09/09 03:08:01 djm Exp $ |