1This document describes OpenSSH's support for U2F/FIDO security keys. 2 3Background 4---------- 5 6U2F is an open standard for two-factor authentication hardware, widely 7used for user authentication to websites. U2F tokens are ubiquitous, 8available from a number of manufacturers and are currently by far the 9cheapest way for users to achieve hardware-backed credential storage. 10 11The U2F protocol however cannot be trivially used as an SSH protocol key 12type as both the inputs to the signature operation and the resultant 13signature differ from those specified for SSH. For similar reasons, 14integration of U2F devices cannot be achieved via the PKCS#11 API. 15 16U2F also offers a number of features that are attractive in the context 17of SSH authentication. They can be configured to require indication 18of "user presence" for each signature operation (typically achieved 19by requiring the user touch the key). They also offer an attestation 20mechanism at key enrollment time that can be used to prove that a 21given key is backed by hardware. Finally the signature format includes 22a monotonic signature counter that can be used (at scale) to detect 23concurrent use of a private key, should it be extracted from hardware. 24 25U2F private keys are generated through an enrollment operation, 26which takes an application ID - a URL-like string, typically "ssh:" 27in this case, but a HTTP origin for the case of web authentication, 28and a challenge string (typically randomly generated). The enrollment 29operation returns a public key, a key handle that must be used to invoke 30the hardware-backed private key, some flags and signed attestation 31information that may be used to verify that a private key is hosted on a 32particular hardware instance. 33 34It is common for U2F hardware to derive private keys from the key handle 35in conjunction with a small per-device secret that is unique to the 36hardware, thus requiring little on-device storage for an effectively 37unlimited number of supported keys. This drives the requirement that 38the key handle be supplied for each signature operation. U2F tokens 39primarily use ECDSA signatures in the NIST-P256 field, though the FIDO2 40standard specifies additional key types, including one based on Ed25519. 41 42Use of U2F security keys does not automatically imply multi-factor 43authentication. From sshd's perspective, a security key constitutes a 44single factor of authentication, even if protected by a PIN or biometric 45authentication. To enable multi-factor authentication in ssh, please 46refer to the AuthenticationMethods option in sshd_config(5). 47 48 49SSH U2F Key formats 50------------------- 51 52OpenSSH integrates U2F as new key and corresponding certificate types: 53 54 sk-ecdsa-sha2-nistp256@openssh.com 55 sk-ecdsa-sha2-nistp256-cert-v01@openssh.com 56 sk-ssh-ed25519@openssh.com 57 sk-ssh-ed25519-cert-v01@openssh.com 58 59While each uses ecdsa-sha256-nistp256 as the underlying signature primitive, 60keys require extra information in the public and private keys, and in 61the signature object itself. As such they cannot be made compatible with 62the existing ecdsa-sha2-nistp* key types. 63 64The format of a sk-ecdsa-sha2-nistp256@openssh.com public key is: 65 66 string "sk-ecdsa-sha2-nistp256@openssh.com" 67 string curve name 68 ec_point Q 69 string application (user-specified, but typically "ssh:") 70 71The corresponding private key contains: 72 73 string "sk-ecdsa-sha2-nistp256@openssh.com" 74 string curve name 75 ec_point Q 76 string application (user-specified, but typically "ssh:") 77 uint8 flags 78 string key_handle 79 string reserved 80 81The format of a sk-ssh-ed25519@openssh.com public key is: 82 83 string "sk-ssh-ed25519@openssh.com" 84 string public key 85 string application (user-specified, but typically "ssh:") 86 87With a private half consisting of: 88 89 string "sk-ssh-ed25519@openssh.com" 90 string public key 91 string application (user-specified, but typically "ssh:") 92 uint8 flags 93 string key_handle 94 string reserved 95 96The certificate form for SSH U2F keys appends the usual certificate 97information to the public key: 98 99 string "sk-ecdsa-sha2-nistp256-cert-v01@openssh.com" 100 string nonce 101 string curve name 102 ec_point Q 103 string application 104 uint64 serial 105 uint32 type 106 string key id 107 string valid principals 108 uint64 valid after 109 uint64 valid before 110 string critical options 111 string extensions 112 string reserved 113 string signature key 114 string signature 115 116and for security key ed25519 certificates: 117 118 string "sk-ssh-ed25519-cert-v01@openssh.com" 119 string nonce 120 string public key 121 string application 122 uint64 serial 123 uint32 type 124 string key id 125 string valid principals 126 uint64 valid after 127 uint64 valid before 128 string critical options 129 string extensions 130 string reserved 131 string signature key 132 string signature 133 134Both security key certificates use the following encoding for private keys: 135 136 string type (e.g. "sk-ssh-ed25519-cert-v01@openssh.com") 137 string pubkey (the above key/cert structure) 138 string application 139 uint8 flags 140 string key_handle 141 string reserved 142 143During key generation, the hardware also returns attestation information 144that may be used to cryptographically prove that a given key is 145hardware-backed. Unfortunately, the protocol required for this proof is 146not privacy-preserving and may be used to identify U2F tokens with at 147least manufacturer and batch number granularity. For this reason, we 148choose not to include this information in the public key or save it by 149default. 150 151Attestation information is useful for out-of-band key and certificate 152registration workflows, e.g. proving to a CA that a key is backed 153by trusted hardware before it will issue a certificate. To support this 154case, OpenSSH optionally allows retaining the attestation information 155at the time of key generation. It will take the following format: 156 157 string "ssh-sk-attest-v00" 158 string attestation certificate 159 string enrollment signature 160 uint32 reserved flags 161 string reserved string 162 163OpenSSH treats the attestation certificate and enrollment signatures as 164opaque objects and does no interpretation of them itself. 165 166SSH U2F signatures 167------------------ 168 169In addition to the message to be signed, the U2F signature operation 170requires the key handle and a few additional parameters. The signature 171is signed over a blob that consists of: 172 173 byte[32] SHA256(application) 174 byte flags (including "user present", extensions present) 175 uint32 counter 176 byte[] extensions 177 byte[32] SHA256(message) 178 179No extensions are yet defined for SSH use. If any are defined in the future, 180it will be possible to infer their presence from the contents of the "flags" 181value. 182 183The signature returned from U2F hardware takes the following format: 184 185 byte flags (including "user present") 186 uint32 counter 187 byte[] ecdsa_signature (in X9.62 format). 188 189For use in the SSH protocol, we wish to avoid server-side parsing of ASN.1 190format data in the pre-authentication attack surface. Therefore, the 191signature format used on the wire in SSH2_USERAUTH_REQUEST packets will 192be reformatted to better match the existing signature encoding: 193 194 string "sk-ecdsa-sha2-nistp256@openssh.com" 195 string ecdsa_signature 196 byte flags 197 uint32 counter 198 199Where the "ecdsa_signature" field follows the RFC5656 ECDSA signature 200encoding: 201 202 mpint r 203 mpint s 204 205For Ed25519 keys the signature is encoded as: 206 207 string "sk-ssh-ed25519@openssh.com" 208 string signature 209 byte flags 210 uint32 counter 211 212ssh-agent protocol extensions 213----------------------------- 214 215ssh-agent requires a protocol extension to support U2F keys. At 216present the closest analogue to Security Keys in ssh-agent are PKCS#11 217tokens, insofar as they require a middleware library to communicate with 218the device that holds the keys. Unfortunately, the protocol message used 219to add PKCS#11 keys to ssh-agent does not include any way to send the 220key handle to the agent as U2F keys require. 221 222To avoid this, without having to add wholly new messages to the agent 223protocol, we will use the existing SSH2_AGENTC_ADD_ID_CONSTRAINED message 224with a new key constraint extension to encode a path to the middleware 225library for the key. The format of this constraint extension would be: 226 227 byte SSH_AGENT_CONSTRAIN_EXTENSION 228 string sk-provider@openssh.com 229 string middleware path 230 231This constraint-based approach does not present any compatibility 232problems. 233 234OpenSSH integration 235------------------- 236 237U2F tokens may be attached via a number of means, including USB and NFC. 238The USB interface is standardised around a HID protocol, but we want to 239be able to support other transports as well as dummy implementations for 240regress testing. For this reason, OpenSSH shall support a dynamically- 241loaded middleware libraries to communicate with security keys, but offer 242support for the common case of USB HID security keys internally. 243 244The middleware library need only expose a handful of functions: 245 246 #define SSH_SK_VERSION_MAJOR 0x00050000 /* API version */ 247 #define SSH_SK_VERSION_MAJOR_MASK 0xffff0000 248 249 /* Flags */ 250 #define SSH_SK_USER_PRESENCE_REQD 0x01 251 #define SSH_SK_USER_VERIFICATION_REQD 0x04 252 #define SSH_SK_RESIDENT_KEY 0x20 253 254 /* Algs */ 255 #define SSH_SK_ECDSA 0x00 256 #define SSH_SK_ED25519 0x01 257 258 /* Error codes */ 259 #define SSH_SK_ERR_GENERAL -1 260 #define SSH_SK_ERR_UNSUPPORTED -2 261 #define SSH_SK_ERR_PIN_REQUIRED -3 262 #define SSH_SK_ERR_DEVICE_NOT_FOUND -4 263 264 struct sk_enroll_response { 265 uint8_t *public_key; 266 size_t public_key_len; 267 uint8_t *key_handle; 268 size_t key_handle_len; 269 uint8_t *signature; 270 size_t signature_len; 271 uint8_t *attestation_cert; 272 size_t attestation_cert_len; 273 }; 274 275 struct sk_sign_response { 276 uint8_t flags; 277 uint32_t counter; 278 uint8_t *sig_r; 279 size_t sig_r_len; 280 uint8_t *sig_s; 281 size_t sig_s_len; 282 }; 283 284 struct sk_resident_key { 285 uint32_t alg; 286 size_t slot; 287 char *application; 288 struct sk_enroll_response key; 289 }; 290 291 struct sk_option { 292 char *name; 293 char *value; 294 uint8_t important; 295 }; 296 297 /* Return the version of the middleware API */ 298 uint32_t sk_api_version(void); 299 300 /* Enroll a U2F key (private key generation) */ 301 int sk_enroll(uint32_t alg, 302 const uint8_t *challenge, size_t challenge_len, 303 const char *application, uint8_t flags, const char *pin, 304 struct sk_option **options, 305 struct sk_enroll_response **enroll_response); 306 307 /* Sign a challenge */ 308 int sk_sign(uint32_t alg, const uint8_t *message, size_t message_len, 309 const char *application, 310 const uint8_t *key_handle, size_t key_handle_len, 311 uint8_t flags, const char *pin, struct sk_option **options, 312 struct sk_sign_response **sign_response); 313 314 /* Enumerate all resident keys */ 315 int sk_load_resident_keys(const char *pin, struct sk_option **options, 316 struct sk_resident_key ***rks, size_t *nrks); 317 318The SSH_SK_VERSION_MAJOR should be incremented for each incompatible 319API change. 320 321The options may be used to pass miscellaneous options to the middleware 322as a NULL-terminated array of pointers to struct sk_option. The middleware 323may ignore unsupported or unknown options unless the "important" flag is 324set, in which case it should return failure if an unsupported option is 325requested. 326 327At present the following options names are supported: 328 329 "device" 330 331 Specifies a specific FIDO device on which to perform the 332 operation. The value in this field is interpreted by the 333 middleware but it would be typical to specify a path to 334 a /dev node for the device in question. 335 336 "user" 337 338 Specifies the FIDO2 username used when enrolling a key, 339 overriding OpenSSH's default of using an all-zero username. 340 341In OpenSSH, the middleware will be invoked by using a similar mechanism to 342ssh-pkcs11-helper to provide address-space containment of the 343middleware from ssh-agent. 344 345