idnits 2.17.1 draft-cridland-kitten-clientkey-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (January 7, 2018) is 2294 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) ** Downref: Normative reference to an Informational RFC: RFC 2104 Summary: 2 errors (**), 0 flaws (~~), 1 warning (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group D. Cridland 3 Internet-Draft Surevine Ltd 4 Intended status: Standards Track January 7, 2018 5 Expires: July 11, 2018 7 Client Key SASL mechanism 8 draft-cridland-kitten-clientkey-00 10 Abstract 12 This document proposes a SASL mechanism which might be used to 13 authenticate specific clients on devices owned by a user. 15 Status of This Memo 17 This Internet-Draft is submitted in full conformance with the 18 provisions of BCP 78 and BCP 79. 20 Internet-Drafts are working documents of the Internet Engineering 21 Task Force (IETF). Note that other groups may also distribute 22 working documents as Internet-Drafts. The list of current Internet- 23 Drafts is at https://datatracker.ietf.org/drafts/current/. 25 Internet-Drafts are draft documents valid for a maximum of six months 26 and may be updated, replaced, or obsoleted by other documents at any 27 time. It is inappropriate to use Internet-Drafts as reference 28 material or to cite them other than as "work in progress." 30 This Internet-Draft will expire on July 11, 2018. 32 Copyright Notice 34 Copyright (c) 2018 IETF Trust and the persons identified as the 35 document authors. All rights reserved. 37 This document is subject to BCP 78 and the IETF Trust's Legal 38 Provisions Relating to IETF Documents 39 (https://trustee.ietf.org/license-info) in effect on the date of 40 publication of this document. Please review these documents 41 carefully, as they describe your rights and restrictions with respect 42 to this document. Code Components extracted from this document must 43 include Simplified BSD License text as described in Section 4.e of 44 the Trust Legal Provisions and are provided without warranty as 45 described in the Simplified BSD License. 47 Table of Contents 49 1. Requirements notation . . . . . . . . . . . . . . . . . . . . 2 50 2. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . 2 51 2.1. Initial Flow . . . . . . . . . . . . . . . . . . . . . . 3 52 2.2. Subsequent Authentication . . . . . . . . . . . . . . . . 3 53 3. Notation . . . . . . . . . . . . . . . . . . . . . . . . . . 3 54 4. The CLIENT-KEY mechanism . . . . . . . . . . . . . . . . . . 4 55 4.1. Mechanism Name . . . . . . . . . . . . . . . . . . . . . 4 56 4.2. Commencing State . . . . . . . . . . . . . . . . . . . . 4 57 4.3. Client Initial Response . . . . . . . . . . . . . . . . . 5 58 4.4. Server Addition Data With Success . . . . . . . . . . . . 5 59 5. Additional Application Protocol Support . . . . . . . . . . . 6 60 5.1. Client Registration . . . . . . . . . . . . . . . . . . . 6 61 5.2. Key Revocation . . . . . . . . . . . . . . . . . . . . . 7 62 5.3. Key Enumeration . . . . . . . . . . . . . . . . . . . . . 7 63 6. Security Considerations . . . . . . . . . . . . . . . . . . . 7 64 6.1. Exposure of key . . . . . . . . . . . . . . . . . . . . . 7 65 6.2. Dangerous Implementation Shortcuts . . . . . . . . . . . 8 66 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 8 67 7.1. Normative References . . . . . . . . . . . . . . . . . . 8 68 7.2. Informative References . . . . . . . . . . . . . . . . . 9 69 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 9 71 1. Requirements notation 73 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 74 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 75 document are to be interpreted as described in [RFC2119]. 77 2. Overview 79 Authentication within a "pure" SASL ([RFC4422]) environment - ie, 80 without call-outs to SAML or OAuth - might include TOTP pathways such 81 as [XEP-0388] proposes, and may also include multiple round-trips, 82 typically to strengthen security on password-based protocols. 84 It seems desirable to design a SASL mechanism to handle the 85 "reauthentication" case needed to avoid client-side storage of 86 reusable password data, bypass TOTP and similar, and allow for low 87 RTT counts. CLIENT-KEY is a SASL mechanism designed to be used when 88 supported by an application protocol framework which allows users to 89 enumerate and invalidate individual clients or devices. It is 90 designed to be a single round-trip, use channel binding where 91 available, and avoid storage of plaintext-equivalent credentials on 92 the server. 94 2.1. Initial Flow 96 A typical interaction with a new client might look as follows: 98 1. On connecting, the client uses a traditional mechanism based on a 99 password, such as SCRAM. 101 2. After authenticating successfully with SCRAM, the client is put 102 through a TOTP challenge. 104 3. The client offers to the user to "remember this device" or 105 similar. If the user wants to do so, the client performs device 106 registration and obtains a "client key", storing it locally. 108 2.2. Subsequent Authentication 110 The next time the client need to authenticate, it can use CLIENT-KEY: 112 1. On connecting, the client uses CLIENT-KEY to authenticate. 114 2. The server notes that CLIENT-KEY has been used, and elides TOTP. 116 If its client key is due to expire, it MAY at this point re-register, 117 generating a new client key. 119 3. Notation 121 This document uses relatively common notations for pseudocode: 123 H(message) The H function is a cryptographic hash function computing 124 the digest of the message - in this document always SHA-256. The 125 function returns some binary data. It is assumed to be both 126 collision-resistant and too difficult to practically guess message 127 from H(message). 129 HMAC(key, message) The HMAC function computes a MAC of the second 130 argument, keyed by the first argument, according to the algorithm 131 defined in [RFC2104]. It is assumed that given HMAC(key, message) 132 and message, it is too difficult to practically guess key. Given 133 only HMAC(key, message), it is assumed that guessing message is 134 difficult within a reasonable time. The hash function used within 135 the HMAC algorithm is H above. 137 BASE64(message) The BASE64 function returns a string which 138 represents the message encoded according to [RFC4648]. 140 NORMALIZE(string) The NORMALIZE function returns a string which has 141 been processed by whatever one normalizes with these days. 143 R(n) The R function returns a sequence of n octets generated 144 randomly with high entropy. 146 L(message) This function returns the number of octets in the message 147 (ie, the message length in octets). 149 HASHLEN This constant is the equivalent of L(H("")) - it is the 150 length of the output of the hash function. 152 XOR(msg1, msg2) The XOR function returns a bitwise XOR of msg1 153 against msg2. These two arguments MUST be the same length. 155 4. The CLIENT-KEY mechanism 157 4.1. Mechanism Name 159 This document defines two mechanisms, CLIENT-KEY and CLIENT-KEY-PLUS. 160 Both are based on SHA-256. Future documents may offer alternative 161 hash algorithms. 163 4.2. Commencing State 165 The client has information stored as follows: 167 ClientID The ClientID, an opaque string which uniquely identifies 168 the device and client instance for that authorization-id. 170 Secret The Client Secret Key, a random sequence of HASHLEN octets. 172 ValidationKey The Client Validation Key, a random sequence of 173 HASHLEN octets. 175 Counter A Counter which records the number of times the Secret has 176 been used. 178 Expiry The Expiry of the client key, after which is it no longer 179 valid. 181 If the client does not have these values stored, it obtains them by 182 authenticating as the user via some other mechanism and registering 183 as described below. 185 The server has information stored during this registration as 186 follows: 188 ClientID As above. 190 Counter Also as above. 192 EncryptedSecret This has the value XOR(Secret, ValidationKey). 194 Validator This has the value HMAC(EncryptedSecret, ValidationKey). 196 Expiry The Expiry of the client key, after which is it no longer 197 valid. 199 4.3. Client Initial Response 201 The client constructs an initial response as follows: 203 client-initial-response = gs2-header NUL authcid NUL client-id 204 NUL client-hmac NUL client-validation-key 205 authcid = 1*UTF-8-char 206 client-id = 1*UTF-8-char 207 client-hmac = base64string 208 ; = BASE64(HMAC(Secret, client-hmac-input)) 209 client-hmac-input = "Client Response" NUL authcid-norm 210 NUL client-id NUL Counter 211 [ NUL channel-binding-data ] 212 ; optional channel binding if -PLUS is used. 213 client-validation-key = base64string 214 ; = BASE64(ValidationKey) 215 authcid-norm = 1*UTF-8-char 216 ; = NORMALIZE(username) 217 username = 1*UTF-8-char 219 The client and server both calculate the client-hmac by: 221 1. Creating a message as: "Client Response" NUL authcid NUL client- 222 id NUL counter 224 2. If CLIENT-KEY-PLUS is used, append a NUL followed by the channel 225 binding information. 227 3. Calculating an HMAC using SHA-256 of the message, keyed by the 228 Secret. 230 4. Base64-encoding the result. 232 After the client sends the response, the counter is incremented. 234 4.4. Server Addition Data With Success 236 When the client's initial response is received, the server first 237 validates the ValidationKey provided, by checking if 238 HMAC(EncryptedSecret, ValidationKey) matches its stored Validator. 240 If this is not the case, the authentication attempt is rejected with 241 no further action. 243 If it matches, then any failure from this point on MUST result in 244 this key being revoked. 246 The server extracts Secret from EncryptedSecret as 247 XOR(EncryptedSecret, ValidationKey), and calculates its own value of 248 client-hmac. At this point, the Counter is updated - note that this 249 step is performed prior to comparing the two client-hmac values. 251 Finally the two client-hmac values are compared. If the client's 252 matches that calculated by the server, the authentication succeeds. 253 Success data is passed back as follows: 255 server-success-data = base64string 256 ; = BASE64(HMAC(Secret, server-hmac-input)) 257 server-hmac-input = "Server Response" NUL authcid 258 NUL client-id NUL Counter 259 [ NUL channel-binding-data ] 260 ; optional channel binding if -PLUS is used. 262 On receipt of this, the client calculates its own version. If the 263 computed value of server-success-data differs from that supplied by 264 the server it should abort the connection. 266 5. Additional Application Protocol Support 268 5.1. Client Registration 270 A client obtains the key by sending a message to the server 271 containing four items of information to the server: 273 1. A ClientID, which is a identifier unique within the scope of the 274 authzid for the client instance, expressed as an opaque string. 275 Good options for this include a UUID, better options include a 276 hash of the device serial number or similar. 278 2. A Client Name, which is a (potentially non-unique) human-readable 279 name for the client instance. For example, "MegaBrowser on 280 Linux", or "SuperClient on MyPhone". 282 3. A ValidationKey, used within the mechanism to validate that the 283 client knows the key, and decrypt the secret. This MUST be 284 random, and consist of HASHLEN octets. An effective method for 285 generating this is either R(HASHLEN) or H(R(40)). 287 4. A requested TTL, which gives the lifetime of the key. This might 288 be short, for session-based keys, or longer for persistent keys. 290 The server then generates Secret, and calculates EncryptedSecret as 291 XOR(Secret, ValidationKey). Secret MUST be HASHLEN random octets, 292 and again an effective method might be R(HASHLEN) or H(R(40)). It 293 then stores Validator as H(ValidationKey) and EncryptedSecret only. 295 The server then responds with a generated value of EncryptedSecret 296 and a timestamp giving the expiry time. This is the only point at 297 which the EncryptedSecret should be transferred. 299 The server MUST store only the items noted above, and most especially 300 MUST NOT store Secret or ValidationKey. 302 5.2. Key Revocation 304 Any authenticated client may revoke a key belonging to the same user 305 by sending a message to the server containing the ClientID 306 corresponding to an existing key. This simply causes the record of 307 the ClientID, Counter, EncryptedSecret and Validator to be removed. 309 5.3. Key Enumeration 311 Any authenticated client may enumerate keys belonging to the same 312 user by sending a message to the server. The server responds with a 313 list of items each containing a ClientID and the Client Name. Note 314 that the key is not included. 316 6. Security Considerations 318 This document is concerned with security throughout. This section is 319 concerned with specific threats and mitigations. 321 Our threat model assumes that an attacker can (with effort) obtain 322 the complete server database, may observe network traffic between the 323 client and server, and may obtain whatever data is stored on an 324 individual client. 326 6.1. Exposure of key 328 The Secret transferred from the server to the client during client 329 registration is clearly vulnerable to anyone able to observe the 330 unencrypted data on the connection. The connection therefore MUST be 331 protected by TLS or equivalent encryption. 333 It may also be extracted from the client at any point, since for use 334 it needs to be stored in such a way that the Secret, ValidationKey 335 and Counter are able to be retrieved. The effect of such compromise 336 can be mitigated by using relatively short expiry times, but it is 337 naturally mitigated by use of the counter, which means that an 338 attacker using the key causes the key to be invalidated on the 339 original device, alerting the user to a compromise and a likely 340 revocation cycle. This attack is undetectable if a long-expiry key 341 is unused by the legitimate client; we therefore recommend short- 342 expiry keys and that users are advised to revoke the keys of lost 343 devices. 345 The Secret cannot be obtained due to a server breach as long as only 346 the EncryptedSecret is stored. Servers MUST NOT store the Secret 347 itself. Similarly, the ValidationKey MUST NOT be stored on the 348 server. 350 6.2. Dangerous Implementation Shortcuts 352 If the server does not test that the HMAC(EncryptedSecret, 353 ValidationKey) matches Validator, then an attacker who has obtained 354 the server database can supply any value for ValidationKey and simply 355 use XOR(EncryptedSecret,ValidatorKey) as their corresponding value 356 for Secret. This would allow an attacker access based only on data 357 obtained from the server. 359 A client or server using a weak random function R() may mean its 360 chosen values for ValidationKey and Secret respectively are able to 361 be guessed. 363 If the server does not revoke the key on mismatches after the 364 ValidationKey is known to be correct, then an attacker can try 365 multiple values for Counter, increasingly the likelyhood of 366 discovering a match. 368 If the server revokes the key when the ValidationKey does not match 369 the Validator, this opens a denial of service attack whereby an 370 attacker can potentially revoke a user's keys. 372 7. References 374 7.1. Normative References 376 [RFC2104] Krawczyk, H., Bellare, M., and R. Canetti, "HMAC: Keyed- 377 Hashing for Message Authentication", RFC 2104, 378 DOI 10.17487/RFC2104, February 1997, 379 . 381 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 382 Requirement Levels", BCP 14, RFC 2119, 383 DOI 10.17487/RFC2119, March 1997, 384 . 386 [RFC4422] Melnikov, A., Ed. and K. Zeilenga, Ed., "Simple 387 Authentication and Security Layer (SASL)", RFC 4422, 388 DOI 10.17487/RFC4422, June 2006, 389 . 391 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 392 Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006, 393 . 395 7.2. Informative References 397 [XEP-0388] 398 Cridland, D., "Extensible SASL Profile", August 2017. 400 Author's Address 402 Dave Cridland 403 Surevine Ltd 404 PO Box 1136 405 Guildford GU1 9ND 406 UK 408 Phone: +44 845 468 1066 409 Email: dave.cridland@surevine.com