Annotation of src/usr.bin/ssh/PROTOCOL.u2f, Revision 1.13
1.1 djm 1: This document describes OpenSSH's support for U2F/FIDO security keys.
2:
3: Background
4: ----------
5:
6: U2F is an open standard for two-factor authentication hardware, widely
7: used for user authentication to websites. U2F tokens are ubiquitous,
8: available from a number of manufacturers and are currently by far the
9: cheapest way for users to achieve hardware-backed credential storage.
10:
11: The U2F protocol however cannot be trivially used as an SSH protocol key
12: type as both the inputs to the signature operation and the resultant
13: signature differ from those specified for SSH. For similar reasons,
14: integration of U2F devices cannot be achieved via the PKCS#11 API.
15:
16: U2F also offers a number of features that are attractive in the context
17: of SSH authentication. They can be configured to require indication
18: of "user presence" for each signature operation (typically achieved
19: by requiring the user touch the key). They also offer an attestation
20: mechanism at key enrollment time that can be used to prove that a
21: given key is backed by hardware. Finally the signature format includes
22: a monotonic signature counter that can be used (at scale) to detect
23: concurrent use of a private key, should it be extracted from hardware.
24:
1.2 naddy 25: U2F private keys are generated through an enrollment operation,
1.1 djm 26: which takes an application ID - a URL-like string, typically "ssh:"
27: in this case, but a HTTP origin for the case of web authentication,
28: and a challenge string (typically randomly generated). The enrollment
29: operation returns a public key, a key handle that must be used to invoke
30: the hardware-backed private key, some flags and signed attestation
1.2 naddy 31: information that may be used to verify that a private key is hosted on a
1.1 djm 32: particular hardware instance.
33:
34: It is common for U2F hardware to derive private keys from the key handle
35: in conjunction with a small per-device secret that is unique to the
36: hardware, thus requiring little on-device storage for an effectively
37: unlimited number of supported keys. This drives the requirement that
38: the key handle be supplied for each signature operation. U2F tokens
1.7 djm 39: primarily use ECDSA signatures in the NIST-P256 field, though the FIDO2
40: standard specified additional key types include one based on Ed25519.
1.1 djm 41:
42: SSH U2F Key formats
43: -------------------
44:
1.7 djm 45: OpenSSH integrates U2F as new key and corresponding certificate types:
1.1 djm 46:
47: sk-ecdsa-sha2-nistp256@openssh.com
48: sk-ecdsa-sha2-nistp256-cert-v01@openssh.com
1.7 djm 49: sk-ssh-ed25519@openssh.com
50: sk-ssh-ed25519-cert-v01@openssh.com
1.1 djm 51:
52: These key types are supported only for user authentication with the
53: "publickey" method. They are not used for host-based user authentication
54: or server host key authentication.
55:
56: While each uses ecdsa-sha256-nistp256 as the underlying signature primitive,
57: keys require extra information in the public and private keys, and in
58: the signature object itself. As such they cannot be made compatible with
59: the existing ecdsa-sha2-nistp* key types.
60:
61: The format of a sk-ecdsa-sha2-nistp256@openssh.com public key is:
62:
63: string "sk-ecdsa-sha2-nistp256@openssh.com"
1.5 djm 64: string curve name
1.1 djm 65: ec_point Q
66: string application (user-specified, but typically "ssh:")
67:
68: The corresponding private key contains:
69:
70: string "sk-ecdsa-sha2-nistp256@openssh.com"
1.5 djm 71: string curve name
1.1 djm 72: ec_point Q
73: string application (user-specified, but typically "ssh:")
1.6 djm 74: uint8 flags
1.1 djm 75: string key_handle
76: string reserved
77:
1.7 djm 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:")
1.12 djm 89: uint8 flags
1.7 djm 90: string key_handle
91: string reserved
92:
93: The certificate form for SSH U2F keys appends the usual certificate
1.1 djm 94: information to the public key:
95:
1.2 naddy 96: string "sk-ecdsa-sha2-nistp256-cert-v01@openssh.com"
1.1 djm 97: string nonce
1.5 djm 98: string curve name
1.1 djm 99: ec_point Q
100: string application
101: uint64 serial
102: uint32 type
103: string key id
104: string valid principals
105: uint64 valid after
106: uint64 valid before
107: string critical options
108: string extensions
109: string reserved
110: string signature key
111: string signature
112:
1.12 djm 113: and for security key ed25519 certificates:
114:
1.7 djm 115: string "sk-ssh-ed25519-cert-v01@openssh.com"
116: string nonce
117: string public key
118: string application
119: uint64 serial
120: uint32 type
121: string key id
122: string valid principals
123: uint64 valid after
124: uint64 valid before
125: string critical options
126: string extensions
127: string reserved
128: string signature key
129: string signature
130:
1.12 djm 131: Both security key certificates use the following encoding for private keys:
132:
133: string type (e.g. "sk-ssh-ed25519-cert-v01@openssh.com")
134: string pubkey (the above key/cert structure)
135: string application
136: uint8 flags
137: string key_handle
138: string reserved
139:
1.1 djm 140: During key generation, the hardware also returns attestation information
141: that may be used to cryptographically prove that a given key is
142: hardware-backed. Unfortunately, the protocol required for this proof is
143: not privacy-preserving and may be used to identify U2F tokens with at
144: least manufacturer and batch number granularity. For this reason, we
145: choose not to include this information in the public key or save it by
146: default.
147:
148: Attestation information is very useful however in an organisational
1.2 naddy 149: context, where it may be used by a CA as part of certificate
1.1 djm 150: issuance. In this case, exposure to the CA of hardware identity is
151: desirable. To support this case, OpenSSH optionally allows retaining the
152: attestation information at the time of key generation. It will take the
153: following format:
154:
155: string "sk-attest-v00"
156: uint32 version (1 for U2F, 2 for FIDO2 in future)
157: string attestation certificate
158: string enrollment signature
159:
160: SSH U2F signatures
161: ------------------
162:
1.9 djm 163: In addition to the message to be signed, the U2F signature operation
1.10 djm 164: requires the key handle and a few additional parameters. The signature
165: is signed over a blob that consists of:
1.1 djm 166:
167: byte[32] SHA256(application)
168: byte flags (including "user present", extensions present)
169: uint32 counter
170: byte[] extensions
171: byte[32] SHA256(message)
172:
1.13 ! djm 173: No extensons are yet defined for SSH use. If any are defined in the future,
! 174: it will be possible to infer their presence from the contents of the "flags"
! 175: value.
! 176:
1.1 djm 177: The signature returned from U2F hardware takes the following format:
178:
179: byte flags (including "user present")
180: uint32 counter
1.10 djm 181: byte[] ecdsa_signature (in X9.62 format).
1.1 djm 182:
183: For use in the SSH protocol, we wish to avoid server-side parsing of ASN.1
184: format data in the pre-authentication attack surface. Therefore, the
185: signature format used on the wire in SSH2_USERAUTH_REQUEST packets will
1.8 djm 186: be reformatted to better match the existing signature encoding:
1.1 djm 187:
1.8 djm 188: string "sk-ecdsa-sha2-nistp256@openssh.com"
189: string ecdsa_signature
1.1 djm 190: byte flags
191: uint32 counter
192:
1.8 djm 193: Where the "ecdsa_signature" field follows the RFC5656 ECDSA signature
194: encoding:
195:
196: mpint r
197: mpint s
1.1 djm 198:
1.4 markus 199: For Ed25519 keys the signature is encoded as:
200:
201: string "sk-ssh-ed25519@openssh.com"
202: string signature
203: byte flags
204: uint32 counter
205:
1.1 djm 206: ssh-agent protocol extensions
207: -----------------------------
208:
1.2 naddy 209: ssh-agent requires a protocol extension to support U2F keys. At
1.1 djm 210: present the closest analogue to Security Keys in ssh-agent are PKCS#11
211: tokens, insofar as they require a middleware library to communicate with
212: the device that holds the keys. Unfortunately, the protocol message used
213: to add PKCS#11 keys to ssh-agent does not include any way to send the
214: key handle to the agent as U2F keys require.
215:
1.2 naddy 216: To avoid this, without having to add wholly new messages to the agent
217: protocol, we will use the existing SSH2_AGENTC_ADD_ID_CONSTRAINED message
218: with a new key constraint extension to encode a path to the middleware
1.1 djm 219: library for the key. The format of this constraint extension would be:
220:
221: byte SSH_AGENT_CONSTRAIN_EXTENSION
1.11 djm 222: string sk-provider@openssh.com
1.1 djm 223: string middleware path
224:
225: This constraint-based approach does not present any compatibility
226: problems.
227:
228: OpenSSH integration
229: -------------------
230:
231: U2F tokens may be attached via a number of means, including USB and NFC.
232: The USB interface is standardised around a HID protocol, but we want to
233: be able to support other transports as well as dummy implementations for
1.7 djm 234: regress testing. For this reason, OpenSSH shall support a dynamically-
235: loaded middleware libraries to communicate with security keys, but offer
236: support for the common case of USB HID security keys internally.
1.1 djm 237:
238: The middleware library need only expose a handful of functions:
239:
240: /* Flags */
241: #define SSH_SK_USER_PRESENCE_REQD 0x01
242:
1.3 markus 243: /* Algs */
244: #define SSH_SK_ECDSA 0x00
245: #define SSH_SK_ED25519 0x01
246:
1.1 djm 247: struct sk_enroll_response {
248: uint8_t *public_key;
249: size_t public_key_len;
250: uint8_t *key_handle;
251: size_t key_handle_len;
252: uint8_t *signature;
253: size_t signature_len;
254: uint8_t *attestation_cert;
255: size_t attestation_cert_len;
256: };
257:
258: struct sk_sign_response {
259: uint8_t flags;
260: uint32_t counter;
261: uint8_t *sig_r;
262: size_t sig_r_len;
263: uint8_t *sig_s;
264: size_t sig_s_len;
265: };
266:
267: /* Return the version of the middleware API */
268: uint32_t sk_api_version(void);
269:
270: /* Enroll a U2F key (private key generation) */
1.3 markus 271: int sk_enroll(int alg, const uint8_t *challenge, size_t challenge_len,
1.1 djm 272: const char *application, uint8_t flags,
273: struct sk_enroll_response **enroll_response);
274:
275: /* Sign a challenge */
1.3 markus 276: int sk_sign(int alg, const uint8_t *message, size_t message_len,
1.1 djm 277: const char *application,
278: const uint8_t *key_handle, size_t key_handle_len,
279: uint8_t flags, struct sk_sign_response **sign_response);
280:
1.9 djm 281: In OpenSSH, these will be invoked by using a similar mechanism to
282: ssh-pkcs11-helper to provide address-space containment of the
283: middleware from ssh-agent.
1.1 djm 284: