upstream: document ed25519-sk pubkey, private key and certificate

formats

OpenBSD-Commit-ID: 795a7c1c80315412e701bef90e31e376ea2f3c88

1 files changed, 40 insertions, 5 deletions

diff --git a/PROTOCOL.u2f b/PROTOCOL.u2f
index 8ccd20b56..7b1049c3e 100644
--- a/PROTOCOL.u2f
+++ b/PROTOCOL.u2f
@@ -36,15 +36,18 @@ in conjunction with a small per-device secret that is unique to the
 hardware, thus requiring little on-device storage for an effectively
 unlimited number of supported keys. This drives the requirement that
 the key handle be supplied for each signature operation. U2F tokens
-primarily use ECDSA signatures in the NIST-P256 field.
+primarily use ECDSA signatures in the NIST-P256 field, though the FIDO2
+standard specified additional key types include one based on Ed25519.
 
 SSH U2F Key formats
 -------------------
 
-OpenSSH integrates U2F as a new key and corresponding certificate type:
+OpenSSH integrates U2F as new key and corresponding certificate types:
 
         sk-ecdsa-sha2-nistp256@openssh.com
         sk-ecdsa-sha2-nistp256-cert-v01@openssh.com
+        sk-ssh-ed25519@openssh.com
+        sk-ssh-ed25519-cert-v01@openssh.com
 
 These key types are supported only for user authentication with the
 "publickey" method. They are not used for host-based user authentication
@@ -72,7 +75,22 @@ The corresponding private key contains:
         string          key_handle
         string          reserved
 
-The certificate form of a SSH U2F key appends the usual certificate
+The format of a sk-ssh-ed25519@openssh.com public key is:
+
+        string          "sk-ssh-ed25519@openssh.com"
+        string          public key
+        string          application (user-specified, but typically "ssh:")
+
+With a private half consisting of:
+
+        string          "sk-ssh-ed25519@openssh.com"
+        string          public key
+        string          application (user-specified, but typically "ssh:")
+        uint32          flags
+        string          key_handle
+        string          reserved
+
+The certificate form for SSH U2F keys appends the usual certificate
 information to the public key:
 
         string          "sk-ecdsa-sha2-nistp256-cert-v01@openssh.com"
@@ -92,6 +110,22 @@ information to the public key:
         string          signature key
         string          signature
 
+        string          "sk-ssh-ed25519-cert-v01@openssh.com"
+        string          nonce
+        string          public key
+        string          application
+        uint64          serial
+        uint32          type
+        string          key id
+        string          valid principals
+        uint64          valid after
+        uint64          valid before
+        string          critical options
+        string          extensions
+        string          reserved
+        string          signature key
+        string          signature
+
 During key generation, the hardware also returns attestation information
 that may be used to cryptographically prove that a given key is
 hardware-backed. Unfortunately, the protocol required for this proof is
@@ -187,8 +221,9 @@ OpenSSH integration
 U2F tokens may be attached via a number of means, including USB and NFC.
 The USB interface is standardised around a HID protocol, but we want to
 be able to support other transports as well as dummy implementations for
-regress testing. For this reason, OpenSSH shall perform all U2F operations
-via a dynamically-loaded middleware library.
+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: