summaryrefslogtreecommitdiff
path: root/PROTOCOL.u2f
diff options
context:
space:
mode:
authordjm@openbsd.org <djm@openbsd.org>2019-11-18 04:34:47 +0000
committerDamien Miller <djm@mindrot.org>2019-11-18 15:57:17 +1100
commit130664344862a8c7afd3e24d8d36ce40af41a99f (patch)
tree4b676bccfef0e55f2c865ff51a010f32484f052a /PROTOCOL.u2f
parent71856e1142fc01628ce53098f8cfc74765464b35 (diff)
upstream: document ed25519-sk pubkey, private key and certificate
formats OpenBSD-Commit-ID: 795a7c1c80315412e701bef90e31e376ea2f3c88
Diffstat (limited to 'PROTOCOL.u2f')
-rw-r--r--PROTOCOL.u2f45
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
36hardware, thus requiring little on-device storage for an effectively 36hardware, thus requiring little on-device storage for an effectively
37unlimited number of supported keys. This drives the requirement that 37unlimited number of supported keys. This drives the requirement that
38the key handle be supplied for each signature operation. U2F tokens 38the key handle be supplied for each signature operation. U2F tokens
39primarily use ECDSA signatures in the NIST-P256 field. 39primarily use ECDSA signatures in the NIST-P256 field, though the FIDO2
40standard specified additional key types include one based on Ed25519.
40 41
41SSH U2F Key formats 42SSH U2F Key formats
42------------------- 43-------------------
43 44
44OpenSSH integrates U2F as a new key and corresponding certificate type: 45OpenSSH integrates U2F as new key and corresponding certificate types:
45 46
46 sk-ecdsa-sha2-nistp256@openssh.com 47 sk-ecdsa-sha2-nistp256@openssh.com
47 sk-ecdsa-sha2-nistp256-cert-v01@openssh.com 48 sk-ecdsa-sha2-nistp256-cert-v01@openssh.com
49 sk-ssh-ed25519@openssh.com
50 sk-ssh-ed25519-cert-v01@openssh.com
48 51
49These key types are supported only for user authentication with the 52These key types are supported only for user authentication with the
50"publickey" method. They are not used for host-based user authentication 53"publickey" method. They are not used for host-based user authentication
@@ -72,7 +75,22 @@ The corresponding private key contains:
72 string key_handle 75 string key_handle
73 string reserved 76 string reserved
74 77
75The certificate form of a SSH U2F key appends the usual certificate 78The format of a sk-ssh-ed25519@openssh.com public key is:
79
80 string "sk-ssh-ed25519@openssh.com"
81 string public key
82 string application (user-specified, but typically "ssh:")
83
84With a private half consisting of:
85
86 string "sk-ssh-ed25519@openssh.com"
87 string public key
88 string application (user-specified, but typically "ssh:")
89 uint32 flags
90 string key_handle
91 string reserved
92
93The certificate form for SSH U2F keys appends the usual certificate
76information to the public key: 94information to the public key:
77 95
78 string "sk-ecdsa-sha2-nistp256-cert-v01@openssh.com" 96 string "sk-ecdsa-sha2-nistp256-cert-v01@openssh.com"
@@ -92,6 +110,22 @@ information to the public key:
92 string signature key 110 string signature key
93 string signature 111 string signature
94 112
113 string "sk-ssh-ed25519-cert-v01@openssh.com"
114 string nonce
115 string public key
116 string application
117 uint64 serial
118 uint32 type
119 string key id
120 string valid principals
121 uint64 valid after
122 uint64 valid before
123 string critical options
124 string extensions
125 string reserved
126 string signature key
127 string signature
128
95During key generation, the hardware also returns attestation information 129During key generation, the hardware also returns attestation information
96that may be used to cryptographically prove that a given key is 130that may be used to cryptographically prove that a given key is
97hardware-backed. Unfortunately, the protocol required for this proof is 131hardware-backed. Unfortunately, the protocol required for this proof is
@@ -187,8 +221,9 @@ OpenSSH integration
187U2F tokens may be attached via a number of means, including USB and NFC. 221U2F tokens may be attached via a number of means, including USB and NFC.
188The USB interface is standardised around a HID protocol, but we want to 222The USB interface is standardised around a HID protocol, but we want to
189be able to support other transports as well as dummy implementations for 223be able to support other transports as well as dummy implementations for
190regress testing. For this reason, OpenSSH shall perform all U2F operations 224regress testing. For this reason, OpenSSH shall support a dynamically-
191via a dynamically-loaded middleware library. 225loaded middleware libraries to communicate with security keys, but offer
226support for the common case of USB HID security keys internally.
192 227
193The middleware library need only expose a handful of functions: 228The middleware library need only expose a handful of functions:
194 229