diff options
author | djm@openbsd.org <djm@openbsd.org> | 2019-11-18 04:34:47 +0000 |
---|---|---|
committer | Damien Miller <djm@mindrot.org> | 2019-11-18 15:57:17 +1100 |
commit | 130664344862a8c7afd3e24d8d36ce40af41a99f (patch) | |
tree | 4b676bccfef0e55f2c865ff51a010f32484f052a /PROTOCOL.u2f | |
parent | 71856e1142fc01628ce53098f8cfc74765464b35 (diff) |
upstream: document ed25519-sk pubkey, private key and certificate
formats
OpenBSD-Commit-ID: 795a7c1c80315412e701bef90e31e376ea2f3c88
Diffstat (limited to 'PROTOCOL.u2f')
-rw-r--r-- | PROTOCOL.u2f | 45 |
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 | |||
36 | hardware, thus requiring little on-device storage for an effectively | 36 | hardware, thus requiring little on-device storage for an effectively |
37 | unlimited number of supported keys. This drives the requirement that | 37 | unlimited number of supported keys. This drives the requirement that |
38 | the key handle be supplied for each signature operation. U2F tokens | 38 | the key handle be supplied for each signature operation. U2F tokens |
39 | primarily use ECDSA signatures in the NIST-P256 field. | 39 | primarily use ECDSA signatures in the NIST-P256 field, though the FIDO2 |
40 | standard specified additional key types include one based on Ed25519. | ||
40 | 41 | ||
41 | SSH U2F Key formats | 42 | SSH U2F Key formats |
42 | ------------------- | 43 | ------------------- |
43 | 44 | ||
44 | OpenSSH integrates U2F as a new key and corresponding certificate type: | 45 | OpenSSH 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 | ||
49 | These key types are supported only for user authentication with the | 52 | These 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 | ||
75 | The certificate form of a SSH U2F key appends the usual certificate | 78 | The 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 | |||
84 | With 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 | |||
93 | The certificate form for SSH U2F keys appends the usual certificate | ||
76 | information to the public key: | 94 | information 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 | |||
95 | During key generation, the hardware also returns attestation information | 129 | During key generation, the hardware also returns attestation information |
96 | that may be used to cryptographically prove that a given key is | 130 | that may be used to cryptographically prove that a given key is |
97 | hardware-backed. Unfortunately, the protocol required for this proof is | 131 | hardware-backed. Unfortunately, the protocol required for this proof is |
@@ -187,8 +221,9 @@ OpenSSH integration | |||
187 | U2F tokens may be attached via a number of means, including USB and NFC. | 221 | U2F tokens may be attached via a number of means, including USB and NFC. |
188 | The USB interface is standardised around a HID protocol, but we want to | 222 | The USB interface is standardised around a HID protocol, but we want to |
189 | be able to support other transports as well as dummy implementations for | 223 | be able to support other transports as well as dummy implementations for |
190 | regress testing. For this reason, OpenSSH shall perform all U2F operations | 224 | regress testing. For this reason, OpenSSH shall support a dynamically- |
191 | via a dynamically-loaded middleware library. | 225 | loaded middleware libraries to communicate with security keys, but offer |
226 | support for the common case of USB HID security keys internally. | ||
192 | 227 | ||
193 | The middleware library need only expose a handful of functions: | 228 | The middleware library need only expose a handful of functions: |
194 | 229 | ||