switch to getarg directly
[heimdal.git] / doc / standardisation / draft-brezak-win2k-krb-rc4-hmac-02.txt
blob1fc9927dea4cd65ee4008afce49da9e0ab7d1d45
3 CAT working group                                              M. Swift 
4 Internet Draft                                                J. Brezak 
5 Document: draft-brezak-win2k-krb-rc4-hmac-02.txt              Microsoft 
6 Category: Informational                                   November 2000 
9            The Windows 2000 RC4-HMAC Kerberos encryption type 
12 tatus of this Memo 
14    This document is an Internet-Draft and is in full conformance with 
15    all provisions of Section 10 of RFC2026 [1]. Internet-Drafts are 
16    working documents of the Internet Engineering Task Force (IETF), its 
17    areas, and its working groups. Note that other groups may also 
18    distribute working documents as Internet-Drafts. Internet-Drafts are 
19    draft documents valid for a maximum of six months and may be 
20    updated, replaced, or obsoleted by other documents at any time. It 
21    is inappropriate to use Internet- Drafts as reference material or to 
22    cite them other than as "work in progress." 
23      
24    The list of current Internet-Drafts can be accessed at 
25    http://www.ietf.org/ietf/1id-abstracts.txt  
26    The list of Internet-Draft Shadow Directories can be accessed at 
27    http://www.ietf.org/shadow.html. 
28     
29 . Abstract 
30     
31    The Windows 2000 implementation of Kerberos introduces a new 
32    encryption type based on the RC4 encryption algorithm and using an 
33    MD5 HMAC for checksum. This is offered as an alternative to using 
34    the existing DES based encryption types. 
35     
36    The RC4-HMAC encryption types are used to ease upgrade of existing 
37    Windows NT environments, provide strong crypto (128-bit key 
38    lengths), and provide exportable (meet United States government 
39    export restriction requirements) encryption. 
40     
41    The Windows 2000 implementation of Kerberos contains new encryption 
42    and checksum types for two reasons: for export reasons early in the 
43    development process, 56 bit DES encryption could not be exported, 
44    and because upon upgrade from Windows NT 4.0 to Windows 2000, 
45    accounts will not have the appropriate DES keying material to do the 
46    standard DES encryption. Furthermore, 3DES is not available for 
47    export, and there was a desire to use a single flavor of encryption 
48    in the product for both US and international products. 
49     
50    As a result, there are two new encryption types and one new checksum 
51    type introduced in Windows 2000. 
52     
53     
54 . Conventions used in this document 
55     
58 wift                  Category - Informational                      1 
60                Windows 2000 RC4-HMAC Kerberos E-Type       June 2000 
63    The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 
64    "SHOULD", "SHOULD NOT", "RECOMMENDED",  "MAY", and "OPTIONAL" in 
65    this document are to be interpreted as described in RFC-2119 [2]. 
66     
67 . Key Generation 
68     
69    On upgrade from existing Windows NT domains, the user accounts would 
70    not have a DES based key available to enable the use of DES base 
71    encryption types specified in RFC 1510. The key used for RC4-HMAC is 
72    the same as the existing Windows NT key (NT Password Hash) for 
73    compatibility reasons. Once the account password is changed, the DES 
74    based keys are created and maintained. Once the DES keys are 
75    available DES based encryption types can be used with Kerberos.  
76     
77    The RC4-HMAC String to key function is defined as follow: 
78     
79    String2Key(password) 
80     
81         K = MD4(UNICODE(password)) 
82          
83    The RC4-HMAC keys are generated by using the Windows UNICODE version 
84    of the password. Each Windows UNICODE character is encoded in 
85    little-endian format of 2 octets each. Then performing an MD4 [6] 
86    hash operation on just the UNICODE characters of the password (not 
87    including the terminating zero octets). 
88     
89    For an account with a password of "foo", this String2Key("foo") will 
90    return: 
91     
92         0xac, 0x8e, 0x65, 0x7f, 0x83, 0xdf, 0x82, 0xbe, 
93         0xea, 0x5d, 0x43, 0xbd, 0xaf, 0x78, 0x00, 0xcc 
94     
95 . Basic Operations 
96     
97    The MD5 HMAC function is defined in [3]. It is used in this 
98    encryption type for checksum operations. Refer to [3] for details on 
99    its operation. In this document this function is referred to as 
100    HMAC(Key, Data) returning the checksum using the specified key on 
101    the data. 
102     
103    The basic MD5 hash operation is used in this encryption type and 
104    defined in [7]. In this document this function is referred to as 
105    MD5(Data) returning the checksum of the data. 
106     
107    RC4 is a stream cipher licensed by RSA Data Security [RSADSI]. A       
108    compatible cipher is described in [8]. In this document the function 
109    is referred to as RC4(Key, Data) returning the encrypted data using 
110    the specified key on the data. 
111     
112    These encryption types use key derivation as defined in [9] (RFC-
113    1510BIS) in Section titled "Key Derivation". With each message, the 
114    message type (T) is used as a component of the keying material. This 
115    summarizes the different key derivation values used in the various 
117 wift                  Category - Informational                      2 
119                Windows 2000 RC4-HMAC Kerberos E-Type       June 2000 
122    operations. Note that these differ from the key derivations used in 
123    other Kerberos encryption types. 
124     
125         T = 1 for TS-ENC-TS in the AS-Request 
126         T = 8 for the AS-Reply  
127         T = 7 for the Authenticator in the TGS-Request 
128         T = 8 for the TGS-Reply  
129         T = 2 for the Server Ticket in the AP-Request 
130         T = 11 for the Authenticator in the AP-Request 
131         T = 12 for the Server returned AP-Reply 
132         T = 15 in the generation of checksum for the MIC token 
133         T = 0 in the generation of sequence number for the MIC token  
134         T = 13 in the generation of checksum for the WRAP token 
135         T = 0 in the generation of sequence number for the WRAP token  
136         T = 0 in the generation of encrypted data for the WRAPPED token 
137     
138    All strings in this document are ASCII unless otherwise specified. 
139    The lengths of ASCII encoded character strings include the trailing 
140    terminator character (0). 
141     
142    The concat(a,b,c,...) function will return the logical concatenation 
143    (left to right) of the values of the arguments. 
144     
145    The nonce(n) function returns a pseudo-random number of "n" octets. 
146     
147 . Checksum Types 
148     
149    There is one checksum type used in this encryption type. The 
150    Kerberos constant for this type is: 
151         #define KERB_CHECKSUM_HMAC_MD5 (-138) 
152     
153    The function is defined as follows: 
154     
155    K - is the Key 
156    T - the message type, encoded as a little-endian four byte integer 
157     
158    CHKSUM(K, T, data) 
159     
160         Ksign = HMAC(K, "signaturekey")  //includes zero octet at end 
161         tmp = MD5(concat(T, data)) 
162         CHKSUM = HMAC(Ksign, tmp) 
163     
164     
165 . Encryption Types 
166     
167    There are two encryption types used in these encryption types. The 
168    Kerberos constants for these types are: 
169         #define KERB_ETYPE_RC4_HMAC             23 
170         #define KERB_ETYPE_RC4_HMAC_EXP         24 
171     
172    The basic encryption function is defined as follow: 
173     
174    T = the message type, encoded as a little-endian four byte integer. 
176 wift                  Category - Informational                      3 
178                Windows 2000 RC4-HMAC Kerberos E-Type       June 2000 
181     
182         BYTE L40[14] = "fortybits"; 
183         BYTE SK = "signaturekey"; 
184          
185         ENCRYPT (K, fRC4_EXP, T, data, data_len, edata, edata_len) 
186         { 
187             if (fRC4_EXP){ 
188                 *((DWORD *)(L40+10)) = T; 
189                 HMAC (K, L40, 10 + 4, K1); 
190             }else{ 
191                 HMAC (K, &T, 4, K1); 
192             } 
193             memcpy (K2, K1, 16); 
194             if (fRC4_EXP) memset (K1+7, 0xAB, 9); 
195             add_8_random_bytes(data, data_len, conf_plus_data); 
196             HMAC (K2, conf_plus_data, 8 + data_len, checksum); 
197             HMAC (K1, checksum, 16, K3); 
198             RC4(K3, conf_plus_data, 8 + data_len, edata + 16); 
199             memcpy (edata, checksum, 16); 
200             edata_len = 16 + 8 + data_len; 
201         }         
202          
203         DECRYPT (K, fRC4_EXP, T, edata, edata_len, data, data_len) 
204         { 
205             if (fRC4_EXP){ 
206                 *((DWORD *)(L40+10)) = T; 
207                 HMAC (K, L40, 14, K1); 
208             }else{ 
209                 HMAC (K, &T, 4, K1); 
210             } 
211             memcpy (K2, K1, 16); 
212             if (fRC4_EXP) memset (K1+7, 0xAB, 9); 
213             HMAC (K1, edata, 16, K3); // checksum is at edata 
214             RC4(K3, edata + 16, edata_len - 16, edata + 16); 
215             data_len = edata_len - 16 - 8; 
216             memcpy (data, edata + 16 + 8, data_len); 
217              
218             // verify generated and received checksums 
219             HMAC (K2, edata + 16, edata_len - 16, checksum); 
220             if (memcmp(edata, checksum, 16) != 0)  
221                 printf("CHECKSUM ERROR  !!!!!!\n"); 
222         } 
223     
224    The header field on the encrypted data in KDC messages is: 
225     
226         typedef struct _RC4_MDx_HEADER { 
227             UCHAR Checksum[16]; 
228             UCHAR Confounder[8]; 
229         } RC4_MDx_HEADER, *PRC4_MDx_HEADER; 
230          
231    The KDC message is encrypted using the ENCRYPT function not 
232    including the Checksum in the RC4_MDx_HEADER. 
233     
235 wift                  Category - Informational                      4 
237                Windows 2000 RC4-HMAC Kerberos E-Type       June 2000 
240    The character constant "fortybits" evolved from the time when a 40-
241    bit key length was all that was exportable from the United States. 
242    It is now used to recognize that the key length is of "exportable" 
243    length. In this description, the key size is actually 56-bits. 
244     
245 . Key Strength Negotiation 
246     
247    A Kerberos client and server can negotiate over key length if they 
248    are using mutual authentication. If the client is unable to perform 
249    full strength encryption, it may propose a key in the "subkey" field 
250    of the authenticator, using a weaker encryption type. The server 
251    must then either return the same key or suggest its own key in the 
252    subkey field of the AP reply message. The key used to encrypt data 
253    is derived from the key returned by the server. If the client is 
254    able to perform strong encryption but the server is not, it may 
255    propose a subkey in the AP reply without first being sent a subkey 
256    in the authenticator. 
258 . GSSAPI Kerberos V5 Mechanism Type  
260 .1 Mechanism Specific Changes 
261     
262    The GSSAPI per-message tokens also require new checksum and 
263    encryption types. The GSS-API per-message tokens must be changed to 
264    support these new encryption types (See [5] Section 1.2.2). The 
265    sealing algorithm identifier (SEAL_ALG) for an RC4 based encryption 
266    is: 
267         Byte 4..5 SEAL_ALG      0x10 0x00 - RC4 
268     
269    The signing algorithm identifier (SGN_ALG) for MD5 HMAC is: 
270         Byte 2..3 SGN ALG       0x11 0x00 - HMAC 
271     
272    The only support quality of protection is: 
273         #define GSS_KRB5_INTEG_C_QOP_DEFAULT    0x0 
274     
275    In addition, when using an RC4 based encryption type, the sequence 
276    number is sent in big-endian rather than little-endian order. 
277     
278    The Windows 2000 implementation also defines new GSSAPI flags in the 
279    initial token passed when initializing a security context. These 
280    flags are passed in the checksum field of the authenticator (See [5] 
281    Section 1.1.1). 
282     
283    GSS_C_DCE_STYLE - This flag was added for use with MicrosoftÆs 
284    implementation of DCE RPC, which initially expected three legs of 
285    authentication. Setting this flag causes an extra AP reply to be 
286    sent from the client back to the server after receiving the serverÆs 
287    AP reply. In addition, the context negotiation tokens do not have 
288    GSSAPI framing - they are raw AP message and do not include object 
289    identifiers. 
290         #define GSS_C_DCE_STYLE                 0x1000 
291     
294 wift                  Category - Informational                      5 
296                Windows 2000 RC4-HMAC Kerberos E-Type       June 2000 
299    GSS_C_IDENTIFY_FLAG - This flag allows the client to indicate to the 
300    server that it should only allow the server application to identify 
301    the client by name and ID, but not to impersonate the client. 
302         #define GSS_C_IDENTIFY_FLAG             0x2000 
303          
304    GSS_C_EXTENDED_ERROR_FLAG - Setting this flag indicates that the 
305    client wants to be informed of extended error information. In 
306    particular, Windows 2000 status codes may be returned in the data 
307    field of a Kerberos error message. This allows the client to 
308    understand a server failure more precisely. In addition, the server 
309    may return errors to the client that are normally handled at the 
310    application layer in the server, in order to let the client try to 
311    recover. After receiving an error message, the client may attempt to 
312    resubmit an AP request. 
313         #define GSS_C_EXTENDED_ERROR_FLAG       0x4000 
314     
315    These flags are only used if a client is aware of these conventions 
316    when using the SSPI on the Windows platform, they are not generally 
317    used by default. 
318     
319    When NetBIOS addresses are used in the GSSAPI, they are identified 
320    by the GSS_C_AF_NETBIOS value. This value is defined as: 
321         #define GSS_C_AF_NETBIOS                0x14 
322    NetBios addresses are 16-octet addresses typically composed of 1 to                                                                  th   15 characters, trailing blank (ascii char 20) filled, with a 16  
323    octet of 0x0. 
324     
325 .2 GSSAPI Checksum Type 
326     
327    The GSSAPI checksum type and algorithm is defined in Section 5. Only 
328    the first 8 octets of the checksum are used. The resulting checksum 
329    is stored in the SGN_CKSUM field (See [5] Section 1.2) for 
330    GSS_GetMIC() and GSS_Wrap(conf_flag=FALSE). 
331     
332         MIC (K, fRC4_EXP, seq_num, MIC_hdr, msg, msg_len, 
333              MIC_seq, MIC_checksum) 
334         { 
335             HMAC (K, SK, 13, K4); 
336             T = 15; 
337             memcpy (T_plus_hdr_plus_msg + 00, &T, 4); 
338             memcpy (T_plus_hdr_plus_msg + 04, MIC_hdr, 8);  
339                                                 // 0101 1100 FFFFFFFF 
340             memcpy (T_plus_hdr_plus_msg + 12, msg, msg_len); 
341             MD5 (T_hdr_msg, 4 + 8 + msg_len, MD5_of_T_hdr_msg); 
342             HMAC (K4, MD5_of_T_hdr_msg, CHKSUM); 
343             memcpy (MIC_checksum, CHKSUM, 8); // use only first 8 bytes 
344           
345             T = 0; 
346             if (fRC4_EXP){  
347                 *((DWORD *)(L40+10)) = T; 
348                 HMAC (K, L40, 14, K5); 
349             }else{ 
350                 HMAC (K, &T, 4, K5); 
352 wift                  Category - Informational                      6 
354                Windows 2000 RC4-HMAC Kerberos E-Type       June 2000 
357             } 
358             if (fRC4_EXP) memset(K5+7, 0xAB, 9); 
359             HMAC(K5, MIT_checksum, 8, K6); 
360             copy_seq_num_in_big_endian(seq_num, seq_plus_direction); 
361         //0x12345678 
362             copy_direction_flag (direction_flag, seq_plus_direction + 
363         4); //0x12345678FFFFFFFF 
364             RC4(K6, seq_plus_direction, 8, MIC_seq); 
365         } 
366     
367 .3 GSSAPI Encryption Types 
368     
369    There are two encryption types for GSSAPI message tokens, one that 
370    is 128 bits in strength, and one that is 56 bits in strength as 
371    defined in Section 6. 
372     
373    All padding is rounded up to 1 byte. One byte is needed to say that 
374    there is 1 byte of padding. The DES based mechanism type uses 8 byte 
375    padding. See [5] Section 1.2.2.3. 
376     
377    The encryption mechanism used for GSS wrap based messages is as 
378    follow: 
379     
380     
381         WRAP (K, fRC4_EXP, seq_num, WRAP_hdr, msg, msg_len, 
382               WRAP_seq, WRAP_checksum, edata, edata_len) 
383         { 
384             HMAC (K, SK, 13, K7); 
385             T = 13; 
386             PAD = 1; 
387             memcpy (T_hdr_conf_msg_pad + 00, &T, 4); 
388             memcpy (T_hdr_conf_msg_pad + 04, WRAP_hdr, 8); // 0101 1100 
389         FFFFFFFF 
390             memcpy (T_hdr_conf_msg_pad + 12, msg, msg_len); 
391             memcpy (T_hdr_conf_msg_pad + 12 + msg_len, &PAD, 1); 
392             MD5 (T_hdr_conf_msg_pad, 
393                  4 + 8 + 8 + msg_len + 1, 
394                  MD5_of_T_hdr_conf_msg_pad); 
395             HMAC (K7, MD5_of_T_hdr_conf_msg_pad, CHKSUM); 
396             memcpy (WRAP_checksum, CHKSUM, 8); // use only first 8 
397         bytes 
398           
399             T = 0; 
400             if (fRC4_EXP){  
401                 *((DWORD *)(L40+10)) = T; 
402                 HMAC (K, L40, 14, K8); 
403             }else{ 
404                 HMAC (K, &T, 4, K8); 
405             } 
406             if (fRC4_EXP) memset(K8+7, 0xAB, 9); 
407             HMAC(K8, WRAP_checksum, 8, K9); 
408             copy_seq_num_in_big_endian(seq_num, seq_plus_direction); 
409         //0x12345678 
411 wift                  Category - Informational                      7 
413                Windows 2000 RC4-HMAC Kerberos E-Type       June 2000 
416             copy_direction_flag (direction_flag, seq_plus_direction + 
417         4); //0x12345678FFFFFFFF 
418             RC4(K9, seq_plus_direction, 8, WRAP_seq); 
419           
420             for (i = 0; i < 16; i++) K10 [i] ^= 0xF0; // XOR each byte 
421         of key with 0xF0 
422             T = 0; 
423             if (fRC4_EXP){ 
424                 *(DWORD *)(L40+10) = T; 
425                 HMAC(K10, L40, 14, K11); 
426                 memset(K11+7, 0xAB, 9); 
427             }else{ 
428                 HMAC(K10, &T, 4, K11);  
429             } 
430             HMAC(K11, seq_num, 4, K12); 
431             RC4(K12, T_hdr_conf_msg_pad + 4 + 8, 8 + msg_len + 1, 
432         edata); /* skip T & hdr */ 
433             edata_len = 8 + msg_len + 1; // conf + msg_len + pad 
434          } 
435           
436     
437    The character constant "fortybits" evolved from the time when a 40-
438    bit key length was all that was exportable from the United States. 
439    It is now used to recognize that the key length is of "exportable" 
440    length. In this description, the key size is actually 56-bits. 
441     
442 . Security Considerations 
444    Care must be taken in implementing this encryption type because it 
445    uses a stream cipher. If a different IV isnÆt used in each direction 
446    when using a session key, the encryption is weak. By using the 
447    sequence number as an IV, this is avoided. 
448     
449 0. Acknowledgements 
450     
451    We would like to thank Salil Dangi for the valuable input in 
452    refining the descriptions of the functions and review input. 
453      
454 1. References 
456    1  Bradner, S., "The Internet Standards Process -- Revision 3", BCP 
457       9, RFC 2026, October 1996. 
458     
459    2  Bradner, S., "Key words for use in RFCs to Indicate Requirement 
460       Levels", BCP 14, RFC 2119, March 1997 
461     
462    3  Krawczyk, H., Bellare, M., Canetti, R.,"HMAC: Keyed-Hashing for 
463       Message Authentication", RFC 2104, February 1997 
464     
465    4  Kohl, J., Neuman, C., "The Kerberos Network Authentication 
466       Service (V5)", RFC 1510, September 1993 
470 wift                  Category - Informational                      8 
472                Windows 2000 RC4-HMAC Kerberos E-Type       June 2000 
476    5  Linn, J., "The Kerberos Version 5 GSS-API Mechanism", RFC-1964, 
477       June 1996 
479    6  R. Rivest, "The MD4 Message-Digest Algorithm", RFC-1320, April 
480       1992 
482    7  R. Rivest, "The MD5 Message-Digest Algorithm", RFC-1321, April 
483       1992 
485    8  Thayer, R. and K. Kaukonen, "A Stream Cipher Encryption             
486       Algorithm", Work in Progress. 
488    9  RC4 is a proprietary encryption algorithm available under license 
489       from RSA Data Security Inc.  For licensing information, contact: 
490        
491          RSA Data Security, Inc. 
492          100 Marine Parkway 
493          Redwood City, CA 94065-1031 
495    10 Neuman, C., Kohl, J., Ts'o, T., "The Kerberos Network 
496       Authentication Service (V5)", draft-ietf-cat-kerberos-revisions-
497       04.txt, June 25, 1999 
499     
500 2. Author's Addresses 
501     
502    Mike Swift 
503    Dept. of Computer Science 
504    Sieg Hall 
505    University of Washington 
506    Seattle, WA 98105 
507    Email: mikesw@cs.washington.edu  
508     
509    John Brezak 
510    Microsoft 
511    One Microsoft Way 
512    Redmond, Washington 
513    Email: jbrezak@microsoft.com 
514     
515     
529 wift                  Category - Informational                      9 
531                Windows 2000 RC4-HMAC Kerberos E-Type    October 1999 
534     
535 3. Full Copyright Statement 
537    "Copyright (C) The Internet Society (2000). All Rights Reserved. 
538     
539    This document and translations of it may be copied and          
540    furnished to others, and derivative works that comment on or          
541    otherwise explain it or assist in its implementation may be          
542    prepared, copied, published and distributed, in whole or in          
543    part, without restriction of any kind, provided that the above          
544    copyright notice and this paragraph are included on all such          
545    copies and derivative works.  However, this document itself may          
546    not be modified in any way, such as by removing the copyright          
547    notice or references to the Internet Society or other Internet          
548    organizations, except as needed for the purpose of developing          
549    Internet standards in which case the procedures for copyrights          
550    defined in the Internet Standards process must be followed, or          
551    as required to translate it into languages other than English. 
552     
553    The limited permissions granted above are perpetual and will          
554    not be revoked by the Internet Society or its successors or          
555    assigns. 
556     
588 wift                  Category - Informational                     10