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
 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 $