From 1a34ba71b9e4f074ee4d392e0afc911964a38fed Mon Sep 17 00:00:00 2001 From: Johan Danielsson Date: Sun, 24 Oct 1999 18:30:33 +0000 Subject: [PATCH] move to subdirectory git-svn-id: svn://svn.h5l.se/heimdal/trunk/heimdal@7228 ec53bebd-3082-4978-b11e-865c3cabbd6b --- doc/draft-brezak-win2k-krb-rc4-hmac-00.txt | 412 - doc/draft-foo | 171 - doc/draft-foo.ms | 136 - doc/draft-foo2 | 171 - doc/draft-foo2.ms | 145 - doc/draft-foo3 | 227 - doc/draft-foo3.ms | 260 - doc/draft-horowitz-key-derivation-01.txt | 244 - doc/draft-ietf-cat-gssv2-08.txt | 62 - doc/draft-ietf-cat-gssv2-cbind-04.txt | 6188 ------------ doc/draft-ietf-cat-kerb-chg-password-02.txt | 311 - doc/draft-ietf-cat-kerb-des3-hmac-sha1-00.txt | 127 - doc/draft-ietf-cat-kerb-key-derivation-00.txt | 250 - doc/draft-ietf-cat-kerberos-err-msg-00.txt | 252 - doc/draft-ietf-cat-kerberos-pk-cross-01.txt | 282 - doc/draft-ietf-cat-kerberos-pk-init-03.txt | 589 -- doc/draft-ietf-cat-kerberos-revisions-00.txt | 8277 ----------------- doc/draft-ietf-cat-kerberos-revisions-01.txt | 6214 ------------- doc/draft-ietf-cat-kerberos-revisions-03.txt | 6766 -------------- doc/draft-ietf-cat-kerberos-revisions-04.txt | 6780 -------------- doc/draft-ietf-cat-krb-dns-locate-00.txt | 250 - doc/draft-ietf-ftpext-mlst-08.txt | 3415 ------- doc/rfc1508.txt | 2747 ------ doc/rfc1509.txt | 2691 ------ doc/rfc1510.txt | 6275 ------------- doc/rfc1750.txt | 1683 ---- doc/rfc1831.txt | 1011 -- doc/rfc1964.txt | 1123 --- doc/rfc2078.txt | 4763 ---------- doc/rfc2203.txt | 1291 --- doc/rfc2228.txt | 1515 --- 31 files changed, 64628 deletions(-) delete mode 100644 doc/draft-brezak-win2k-krb-rc4-hmac-00.txt delete mode 100644 doc/draft-foo delete mode 100644 doc/draft-foo.ms delete mode 100644 doc/draft-foo2 delete mode 100644 doc/draft-foo2.ms delete mode 100644 doc/draft-foo3 delete mode 100644 doc/draft-foo3.ms delete mode 100644 doc/draft-horowitz-key-derivation-01.txt delete mode 100644 doc/draft-ietf-cat-gssv2-08.txt delete mode 100644 doc/draft-ietf-cat-gssv2-cbind-04.txt delete mode 100644 doc/draft-ietf-cat-kerb-chg-password-02.txt delete mode 100644 doc/draft-ietf-cat-kerb-des3-hmac-sha1-00.txt delete mode 100644 doc/draft-ietf-cat-kerb-key-derivation-00.txt delete mode 100644 doc/draft-ietf-cat-kerberos-err-msg-00.txt delete mode 100644 doc/draft-ietf-cat-kerberos-pk-cross-01.txt delete mode 100644 doc/draft-ietf-cat-kerberos-pk-init-03.txt delete mode 100644 doc/draft-ietf-cat-kerberos-revisions-00.txt delete mode 100644 doc/draft-ietf-cat-kerberos-revisions-01.txt delete mode 100644 doc/draft-ietf-cat-kerberos-revisions-03.txt delete mode 100644 doc/draft-ietf-cat-kerberos-revisions-04.txt delete mode 100644 doc/draft-ietf-cat-krb-dns-locate-00.txt delete mode 100644 doc/draft-ietf-ftpext-mlst-08.txt delete mode 100644 doc/rfc1508.txt delete mode 100644 doc/rfc1509.txt delete mode 100644 doc/rfc1510.txt delete mode 100644 doc/rfc1750.txt delete mode 100644 doc/rfc1831.txt delete mode 100644 doc/rfc1964.txt delete mode 100644 doc/rfc2078.txt delete mode 100644 doc/rfc2203.txt delete mode 100644 doc/rfc2228.txt diff --git a/doc/draft-brezak-win2k-krb-rc4-hmac-00.txt b/doc/draft-brezak-win2k-krb-rc4-hmac-00.txt deleted file mode 100644 index a29c1ca76..000000000 --- a/doc/draft-brezak-win2k-krb-rc4-hmac-00.txt +++ /dev/null @@ -1,412 +0,0 @@ -CAT working group M. Swift -Internet Draft J. Brezak -Document: draft-brezak-win2k-krb-rc4-hmac-00.txt Microsoft -Category: Informational September, 1999 - - - The Windows 2000 RC4-HMAC Kerberos encryption type - - -Status of this Memo - - This document is an Internet-Draft and is in full conformance with - all provisions of Section 10 of RFC2026 [1]. Internet-Drafts are - working documents of the Internet Engineering Task Force (IETF), its - areas, and its working groups. Note that other groups may also - distribute working documents as Internet-Drafts. Internet-Drafts are - draft documents valid for a maximum of six months and may be - updated, replaced, or obsoleted by other documents at any time. It - is inappropriate to use Internet- Drafts as reference material or to - cite them other than as "work in progress." - - The list of current Internet-Drafts can be accessed at - http://www.ietf.org/ietf/1id-abstracts.txt - - The list of Internet-Draft Shadow Directories can be accessed at - http://www.ietf.org/shadow.html. - -1. Abstract - - The Windows 2000 implementation of Kerberos introduces a new - encryption type based on the RC4 encryption algorithm and using an - MD5 HMAC for checksum. This is offered as an alternative to using - the existing DES based encryption types. - - The RC4-HMAC encryption types are used to ease upgrade of existing - Windows NT environments, provide strong crypto (128-bit key - lengths), and provide exportable (meet United States government - export restriction requirements) encryption. - - The Windows 2000 implementation of Kerberos contains new encryption - and checksum types for two reasons: for export reasons early in the - development process, 56 bit DES encryption could not be exported, - and because upon upgrade from Windows NT 4.0 to Windows 2000, - accounts will not have the appropriate DES keying material to do the - standard DES encryption. Furthermore, 3DES is not available for - export, and there was a desired to use a single flavor of encryption - in the product for both US and international products. - - As a result, there are two new encryption types and one new checksum - type introduced in Windows 2000. - - -2. Conventions used in this document - - - -Swift Category - Informational 1 - - Windows 2000 RC4-HMAC Kerberos E-Type July 1999 - - - The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", - "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in - this document are to be interpreted as described in RFC-2119 [2]. - -3. Key Generation - - On upgrade from existing Windows NT domains, the user accounts would - not have a DES based key available to enable the use of DES base - encryption types specified in RFC 1510. The key used for RC4-HMAC is - the same as the existing Windows NT key for compatibility reasons. - Once the account password is changed, the DES based keys are created - and maintained. Once the DES keys are available DES based encryption - types can be used with Kerberos. - - The RC4-HMAC String to key function is defined as follow: - - String2Key(password) - - K = MD4(UNICODE(password)) - - The RC4-HMAC keys are generated by using the Windows UNICODE version - of the password. Each Windows UNICODE character is encoded in - little-endian format of 2 octets each. Then performing an MD4 [6] - hash operation on just the UNICODE characters of the password (not - including the terminating zero octets). - -4. Basic Operations - - The MD5 HMAC function is defined in [3]. It is used in this - encryption type for checksum operations. Refer to [3] for details on - its operation. In this document this function is referred to as - HMAC(Key, Data) returning the checksum using the specified key on - the data. - - The basic MD5 hash operation is used in this encryption type and - defined in [7]. In this document this function is referred to as - MD5(Key, Data) returning the checksum using the specified key on the - data. - - The basic RC4 encryption operation is used in this encryption type - and defined in [8]. In this document the function is referred to as - RC4(Key, Data) returning the encrypted data using the specified key - on the data. - - These encryption types use key derivation as defined in [9] (RFC- - 1510BIS) in Section titled "Key Derivation". With each message, the - message type (T) is used as a component of the keying material. - - The lengths of ASCII encoded character strings include the trailing - terminator character (0). - - The concat(a,b,c,...) function will return the logical concatenation - (left to right) of the values of the arguments. - -Swift Category - Informational 2 - - Windows 2000 RC4-HMAC Kerberos E-Type July 1999 - - - - The nonce(n) function returns a pseudo-random number of "n" octets. - -5. Checksum Types - - There is one checksum type used in this encryption type. The - Kerberos constant for this type is: - #define KERB_CHECKSUM_HMAC_MD5 (-138) - - The function is defined as follows: - - K - is the Key - T - the message type, encoded as a little-endian four byte integer - - CHKSUM(K, T, data) - - Ksign = HMAC(K, "signature key") //includes zero octet at end - tmp = MD5(Ksign, concat(T, data)) - CHKSUM = HMAC(K, tmp) - - -6. Encryption Types - - There are two encryption types used in these encryption types. The - Kerberos constants for these types are: - #define KERB_ETYPE_RC4_HMAC 23 - #define KERB_ETYPE_RC4_HMAC_EXP 24 - - The basic encryption function is defined as follow: - - T = the message type, encoded as a little-endian four byte integer. - - ENCRYPT(K, T, data) - if (K.enctype == KERB_ETYPE_RC4_HMAC_EXP) - L = "fiftysixbits" //includes zero octet at end - Else - L = "" // one octet of zero - Ksign = HMAC(K, concat(L, T)) - Confounder = nonce(8) // get an 8 octet nonce for a confounder - Checksum = HMAC(Ksign, concat(Confounder, data)) - Ke = Ksign - if (L == "fiftysixbits") memset(&Ke[7], 0x0ab, 9) - Ke2 = HMAC(Ke, Checksum) - data = RC4(Ke2, data) - - The header field on the encrypted data in KDC messages is: - - typedef struct _RC4_MDx_HEADER { - UCHAR Checksum[16]; - UCHAR Confounder[8]; - } RC4_MDx_HEADER, *PRC4_MDx_HEADER; - - - -Swift Category - Informational 3 - - Windows 2000 RC4-HMAC Kerberos E-Type July 1999 - - - The character constant "fiftysixbits" evolved from the time when a - 56-bit key length was all that was exportable from the United - States. It is now used to recognize that the key length is of - "exportable" length. - -7. Key Strength Negotiation - - A Kerberos client and server can negotiate over key length if they - are using mutual authentication. If the client is unable to perform - full strength encryption, it may propose a key in the "subkey" field - of the authenticator, using a weaker encryption type. The server - must then either return the same key or suggest its own key in the - subkey field of the AP reply message. The key used to encrypt data - is derived from the key returned by the server. If the client is - able to perform strong encryption but the server is not, it may - propose a subkey in the AP reply without first being sent a subkey - in the authenticator. - -8. GSSAPI Kerberos V5 Mechanism Type - -8.1 Mechanism Specific Changes - - The GSSAPI per-message tokens also require new checksum and - encryption types. The GSS-API per-message tokens must be changed to - support these new encryption types (See [5] Section 1.2.2). The - sealing algorithm identifier (SEAL_ALG) for an RC4 based encryption - is: - Byte 4..5 SEAL_ALG 0x10 0x00 - RC4 - - The signing algorithm identifier (SGN_ALG) for MD5 HMAC is: - Byte 2..3 SGN ALG 0x11 0x00 - HMAC - - The only support quality of protection is: - #define GSS_KRB5_INTEG_C_QOP_DEFAULT 0x0 - - In addition, when using an RC4 based encryption type, the sequence - number is sent in big-endian rather than little-endian order. - -8.2 GSSAPI Checksum Type - - The GSSAPI checksum type and algorithm is defined in Section 5. Only - the first 8 octets of the checksum are used. The resulting checksum - is stored in the SGN_CKSUM field (See [5] Section 1.2) for - GSS_GetMIC() and GSS_Wrap(conf_flag=FALSE). - -8.3 GSSAPI Encryption Types - - There are two encryption types for GSSAPI message tokens, one that - is 128 bits in strength, and one that is 56 bits in strength as - defined in Section 6. - - - - -Swift Category - Informational 4 - - Windows 2000 RC4-HMAC Kerberos E-Type July 1999 - - - All padding is rounded up to 1 byte. One byte is needed to say that - there is 1 byte of padding. The DES based mechanism type uses 8 byte - padding. See [5] Section 1.2.2.3. - - The encryption mechanism used for GSS based messages is as follow: - - GSS-ENCRYPT(K, T, data) - IV = SND_SEQ - K = XOR(K, 0xf0f0f0f0f0f0f0f0f0f0f0f0f0f0f0) - if (K.enctype == KERB_ETYPE_RC4_HMAC_EXP) - L = "fortybits" //includes zero octet at end - else - L = "" // one octet of zero - Ksign = HMAC(K, concat(L, T)) - Ke = Ksign - if (L == "fortybits") memset(&Ke[7], 0x0ab, 9) - Ke2 = HMAC(Ke, IV) - Data = RC4(Ke2, data) - SND_SEQ = RC4(Ke, seq#) - - The sequence number (SND_SEQ) and IV are used as defined in [5] - Section 1.2.2. - - The character constant "fortybits" evolved from the time when a 40- - bit key length was all that was exportable from the United States. - It is now used to recognize that the key length is of "exportable" - length. - -8. Security Considerations - - Care must be taken in implementing this encryption type because it - uses a stream cipher. If a different IV isnĘt used in each direction - when using a session key, the encryption is weak. By using the - sequence number as an IV, this is avoided. - -9. References - - 1 Bradner, S., "The Internet Standards Process -- Revision 3", BCP - 9, RFC 2026, October 1996. - - 2 Bradner, S., "Key words for use in RFCs to Indicate Requirement - Levels", BCP 14, RFC 2119, March 1997 - - 3 Krawczyk, H., Bellare, M., Canetti, R.,"HMAC: Keyed-Hashing for - Message Authentication", RFC 2104, February 1997 - - 4 Kohl, J., Neuman, C., "The Kerberos Network Authentication - Service (V5)", RFC 1510, September 1993 - - 5 Linn, J., "The Kerberos Version 5 GSS-API Mechanism", RFC-1964, - June 1996 - - - -Swift Category - Informational 5 - - Windows 2000 RC4-HMAC Kerberos E-Type July 1999 - - - - 6 R. Rivest, "The MD4 Message-Digest Algorithm", RFC-1320, April - 1992 - - 7 R. Rivest, "The MD5 Message-Digest Algorithm", RFC-1321, April - 1992 - - 8 RC4 is a proprietary encryption algorithm available under license - from RSA Data Security Inc. For licensing information, - contact: - RSA Data Security, Inc. - 100 Marine Parkway - Redwood City, CA 94065-1031 - - 9 Neuman, C., Kohl, J., Ts'o, T., "The Kerberos Network - Authentication Service (V5)", draft-ietf-cat-kerberos-revisions- - 04.txt, June 25, 1999 - - -10. Author's Addresses - - Mike Swift - Microsoft - One Microsoft Way - Redmond, Washington - Email: mikesw@microsoft.com - - John Brezak - Microsoft - One Microsoft Way - Redmond, Washington - Email: jbrezak@microsoft.com - - - - - - - - - - - - - - - - - - - - - - -Swift Category - Informational 6 - - Windows 2000 RC4-HMAC Kerberos E-Type July 1999 - - - -11. Full Copyright Statement - - Copyright (C) The Internet Society (1999). All Rights Reserved. - - This document and translations of it may be copied and furnished to - others, and derivative works that comment on or otherwise explain it - or assist in its implementation may be prepared, copied, published - and distributed, in whole or in part, without restriction of any - kind, provided that the above copyright notice and this paragraph - are included on all such copies and derivative works. However, this - document itself may not be modified in any way, such as by removing - the copyright notice or references to the Internet Society or other - Internet organizations, except as needed for the purpose of - developing Internet standards in which case the procedures for - copyrights defined in the Internet Standards process must be - followed, or as required to translate it into languages other than - English. - - The limited permissions granted above are perpetual and will not be - revoked by the Internet Society or its successors or assigns. - - This document and the information contained herein is provided on an - "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING - TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING - BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION - HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF - MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE." - - - - - - - - - - - - - - - - - - - - - - - - - - -Swift Category - Informational 7 - \ No newline at end of file diff --git a/doc/draft-foo b/doc/draft-foo deleted file mode 100644 index 8174d4678..000000000 --- a/doc/draft-foo +++ /dev/null @@ -1,171 +0,0 @@ - - - - - - -Network Working Group Assar Westerlund - SICS -Internet-Draft October, 1997 -Expire in six months - - Kerberos over IPv6 - -Status of this Memo - - This document is an Internet-Draft. Internet-Drafts are working - documents of the Internet Engineering Task Force (IETF), its areas, - and its working groups. Note that other groups may also distribute - working documents as Internet-Drafts. - - Internet-Drafts are draft documents valid for a maximum of six months - and may be updated, replaced, or obsoleted by other documents at any - time. It is inappropriate to use Internet- Drafts as reference - material or to cite them other than as "work in progress." - - To view the entire list of current Internet-Drafts, please check the - "1id-abstracts.txt" listing contained in the Internet-Drafts Shadow - Directories on ftp.is.co.za (Africa), ftp.nordu.net (Europe), - munnari.oz.au (Pacific Rim), ds.internic.net (US East Coast), or - ftp.isi.edu (US West Coast). - - Distribution of this memo is unlimited. Please send comments to the - mailing list. - -Abstract - - This document specifies the address types and transport types - necessary for using Kerberos [RFC1510] over IPv6 [RFC1883]. - -Specification - - IPv6 addresses are 128-bit (16-octet) quantities, encoded in MSB - order. The type of IPv6 addresses is twenty-four (24). - - The following addresses (see [RFC1884]) MUST not appear in any - Kerberos packet: - - the Unspecified Address - the Loopback Address - Link-Local addresses - - IPv4-mapped IPv6 addresses MUST be represented as addresses of type - 2. - - - - -Westerlund [Page 1] - -Internet Draft Kerberos over IPv6 October, 1997 - - - Communication with the KDC over IPv6 MUST be done as in section 8.2.1 - of [RFC1510]. - -Discussion - - [RFC1510] suggests using the address family constants in - from BSD. This cannot be done for IPv6 as these - numbers have diverged and are different on different BSD-derived - systems. [RFC2133] does not either specify a value for AF_INET6. - Thus a value has to be decided and the implementations have to - convert between the value used in Kerberos HostAddress and the local - AF_INET6. - - There are a few different address types in IPv6, see [RFC1884]. Some - of these are used for quite special purposes and it makes no sense to - include them in Kerberos packets. - - It is necessary to represent IPv4-mapped addresses as Internet - addresses (type 2) to be compatible with Kerberos implementations - that only support IPv4. - -Security considerations - - This memo does not introduce any known security considerations in - addition to those mentioned in [RFC1510]. - -References - - [RFC1510] Kohl, J. and Neuman, C., "The Kerberos Network - Authentication Service (V5)", RFC 1510, September 1993. - - [RFC1883] Deering, S., Hinden, R., "Internet Protocol, Version 6 - (IPv6) Specification", RFC 1883, December 1995. - - [RFC1884] Hinden, R., Deering, S., "IP Version 6 Addressing - Architecture", RFC 1884, December 1995. - - [RFC2133] Gilligan, R., Thomson, S., Bound, J., Stevens, W., "Basic - Socket Interface Extensions for IPv6", RFC2133, April 1997. - -Author's Address - - Assar Westerlund - Swedish Institute of Computer Science - Box 1263 - S-164 29 KISTA - Sweden - - - - -Westerlund [Page 2] - -Internet Draft Kerberos over IPv6 October, 1997 - - - Phone: +46-8-7521526 - Fax: +46-8-7517230 - EMail: assar@sics.se - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Westerlund [Page 3] - diff --git a/doc/draft-foo.ms b/doc/draft-foo.ms deleted file mode 100644 index 62b109afa..000000000 --- a/doc/draft-foo.ms +++ /dev/null @@ -1,136 +0,0 @@ -.pl 10.0i -.po 0 -.ll 7.2i -.lt 7.2i -.nr LL 7.2i -.nr LT 7.2i -.ds LF Westerlund -.ds RF [Page %] -.ds CF -.ds LH Internet Draft -.ds RH October, 1997 -.ds CH Kerberos over IPv6 -.hy 0 -.ad l -.in 0 -.ta \n(.luR -Network Working Group Assar Westerlund - SICS -Internet-Draft October, 1997 -Expire in six months - -.ce -Kerberos over IPv6 - -.ti 0 -Status of this Memo - -.in 3 -This document is an Internet-Draft. Internet-Drafts are working -documents of the Internet Engineering Task Force (IETF), its -areas, and its working groups. Note that other groups may also -distribute working documents as Internet-Drafts. - -Internet-Drafts are draft documents valid for a maximum of six -months and may be updated, replaced, or obsoleted by other -documents at any time. It is inappropriate to use Internet- -Drafts as reference material or to cite them other than as -"work in progress." - -To view the entire list of current Internet-Drafts, please check -the "1id-abstracts.txt" listing contained in the Internet-Drafts -Shadow Directories on ftp.is.co.za (Africa), ftp.nordu.net -(Europe), munnari.oz.au (Pacific Rim), ds.internic.net (US East -Coast), or ftp.isi.edu (US West Coast). - -Distribution of this memo is unlimited. Please send comments to the - mailing list. - -.ti 0 -Abstract - -.in 3 -This document specifies the address types and transport types -necessary for using Kerberos [RFC1510] over IPv6 [RFC1883]. - -.ti 0 -Specification - -.in 3 -IPv6 addresses are 128-bit (16-octet) quantities, encoded in MSB -order. The type of IPv6 addresses is twenty-four (24). - -The following addresses (see [RFC1884]) MUST not appear in any -Kerberos packet: - -the Unspecified Address -.br -the Loopback Address -.br -Link-Local addresses - -IPv4-mapped IPv6 addresses MUST be represented as addresses of type 2. - -Communication with the KDC over IPv6 MUST be done as in section -8.2.1 of [RFC1510]. - -.ti 0 -Discussion - -.in 3 -[RFC1510] suggests using the address family constants in - from BSD. This cannot be done for IPv6 as these -numbers have diverged and are different on different BSD-derived -systems. [RFC2133] does not either specify a value for AF_INET6. -Thus a value has to be decided and the implementations have to convert -between the value used in Kerberos HostAddress and the local AF_INET6. - -There are a few different address types in IPv6, see [RFC1884]. Some -of these are used for quite special purposes and it makes no sense to -include them in Kerberos packets. - -It is necessary to represent IPv4-mapped addresses as Internet -addresses (type 2) to be compatible with Kerberos implementations that -only support IPv4. - -.ti 0 -Security considerations - -.in 3 -This memo does not introduce any known security considerations in -addition to those mentioned in [RFC1510]. - -.ti 0 -References - -.in 3 -[RFC1510] Kohl, J. and Neuman, C., "The Kerberos Network -Authentication Service (V5)", RFC 1510, September 1993. - -[RFC1883] Deering, S., Hinden, R., "Internet Protocol, Version 6 -(IPv6) Specification", RFC 1883, December 1995. - -[RFC1884] Hinden, R., Deering, S., "IP Version 6 Addressing -Architecture", RFC 1884, December 1995. - -[RFC2133] Gilligan, R., Thomson, S., Bound, J., Stevens, W., "Basic -Socket Interface Extensions for IPv6", RFC2133, April 1997. - -.ti 0 -Author's Address - -Assar Westerlund -.br -Swedish Institute of Computer Science -.br -Box 1263 -.br -S-164 29 KISTA -.br -Sweden - -Phone: +46-8-7521526 -.br -Fax: +46-8-7517230 -.br -EMail: assar@sics.se diff --git a/doc/draft-foo2 b/doc/draft-foo2 deleted file mode 100644 index 0fa695f64..000000000 --- a/doc/draft-foo2 +++ /dev/null @@ -1,171 +0,0 @@ - - - - - - -Network Working Group Assar Westerlund - SICS -Internet-Draft Johan Danielsson -November, 1997 PDC, KTH -Expire in six months - - Kerberos over TCP - -Status of this Memo - - This document is an Internet-Draft. Internet-Drafts are working - documents of the Internet Engineering Task Force (IETF), its areas, - and its working groups. Note that other groups may also distribute - working documents as Internet-Drafts. - - Internet-Drafts are draft documents valid for a maximum of six months - and may be updated, replaced, or obsoleted by other documents at any - time. It is inappropriate to use Internet- Drafts as reference - material or to cite them other than as "work in progress." - - To view the entire list of current Internet-Drafts, please check the - "1id-abstracts.txt" listing contained in the Internet-Drafts Shadow - Directories on ftp.is.co.za (Africa), ftp.nordu.net (Europe), - munnari.oz.au (Pacific Rim), ds.internic.net (US East Coast), or - ftp.isi.edu (US West Coast). - - Distribution of this memo is unlimited. Please send comments to the - mailing list. - -Abstract - - This document specifies how the communication should be done between - a client and a KDC using Kerberos [RFC1510] with TCP as the transport - protocol. - -Specification - - This draft specifies an extension to section 8.2.1 of RFC1510. - - A Kerberos server MAY accept requests on TCP port 88 (decimal). - - The data sent from the client to the KDC should consist of 4 bytes - containing the length, in network byte order, of the Kerberos - request, followed by the request (AS-REQ or TGS-REQ) itself. The - reply from the KDC should consist of the length of the reply packet - (4 bytes, network byte order) followed by the packet itself (AS-REP, - TGS-REP, or KRB-ERROR). - - - - -Westerlund, Danielsson [Page 1] - -Internet Draft Kerberos over TCP November, 1997 - - - C->S: Open connection to TCP port 88 at the server - C->S: length of request - C->S: AS-REQ or TGS-REQ - S->C: length of reply - S->C: AS-REP, TGS-REP, or KRB-ERROR - -Discussion - - Even though the preferred way of sending kerberos packets is over UDP - there are several occasions when it's more practical to use TCP. - - Mainly, it's usually much less cumbersome to get TCP through - firewalls than UDP. - - In theory, there's no reason for having explicit length fields, that - information is already encoded in the ASN1 encoding of the Kerberos - packets. But having explicit lengths makes it unnecessary to have to - decode the ASN.1 encoding just to know how much data has to be read. - - Another way of signaling the end of the request of the reply would be - to do a half-close after the request and a full-close after the - reply. This does not work well with all kinds of firewalls. - -Security considerations - - This memo does not introduce any known security considerations in - addition to those mentioned in [RFC1510]. - -References - - [RFC1510] Kohl, J. and Neuman, C., "The Kerberos Network - Authentication Service (V5)", RFC 1510, September 1993. - -Authors' Addresses - - Assar Westerlund - Swedish Institute of Computer Science - Box 1263 - S-164 29 KISTA - Sweden - - Phone: +46-8-7521526 - Fax: +46-8-7517230 - EMail: assar@sics.se - - Johan Danielsson - PDC, KTH - S-100 44 STOCKHOLM - - - -Westerlund, Danielsson [Page 2] - -Internet Draft Kerberos over TCP November, 1997 - - - Sweden - - Phone: +46-8-7907885 - Fax: +46-8-247784 - EMail: joda@pdc.kth.se - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Westerlund, Danielsson [Page 3] - diff --git a/doc/draft-foo2.ms b/doc/draft-foo2.ms deleted file mode 100644 index 7e0fa0a62..000000000 --- a/doc/draft-foo2.ms +++ /dev/null @@ -1,145 +0,0 @@ -.pl 10.0i -.po 0 -.ll 7.2i -.lt 7.2i -.nr LL 7.2i -.nr LT 7.2i -.ds LF Westerlund, Danielsson -.ds RF [Page %] -.ds CF -.ds LH Internet Draft -.ds RH November, 1997 -.ds CH Kerberos over TCP -.hy 0 -.ad l -.in 0 -.ta \n(.luR -.nf -Network Working Group Assar Westerlund - SICS -Internet-Draft Johan Danielsson -November, 1997 PDC, KTH -Expire in six months -.fi - -.ce -Kerberos over TCP - -.ti 0 -Status of this Memo - -.in 3 -This document is an Internet-Draft. Internet-Drafts are working -documents of the Internet Engineering Task Force (IETF), its -areas, and its working groups. Note that other groups may also -distribute working documents as Internet-Drafts. - -Internet-Drafts are draft documents valid for a maximum of six -months and may be updated, replaced, or obsoleted by other -documents at any time. It is inappropriate to use Internet- -Drafts as reference material or to cite them other than as -"work in progress." - -To view the entire list of current Internet-Drafts, please check -the "1id-abstracts.txt" listing contained in the Internet-Drafts -Shadow Directories on ftp.is.co.za (Africa), ftp.nordu.net -(Europe), munnari.oz.au (Pacific Rim), ds.internic.net (US East -Coast), or ftp.isi.edu (US West Coast). - -Distribution of this memo is unlimited. Please send comments to the - mailing list. - -.ti 0 -Abstract - -.in 3 -This document specifies how the communication should be done between a -client and a KDC using Kerberos [RFC1510] with TCP as the transport -protocol. - -.ti 0 -Specification - -This draft specifies an extension to section 8.2.1 of RFC1510. - -A Kerberos server MAY accept requests on TCP port 88 (decimal). - -The data sent from the client to the KDC should consist of 4 bytes -containing the length, in network byte order, of the Kerberos request, -followed by the request (AS-REQ or TGS-REQ) itself. The reply from -the KDC should consist of the length of the reply packet (4 bytes, -network byte order) followed by the packet itself (AS-REP, TGS-REP, or -KRB-ERROR). - -.nf -C->S: Open connection to TCP port 88 at the server -C->S: length of request -C->S: AS-REQ or TGS-REQ -S->C: length of reply -S->C: AS-REP, TGS-REP, or KRB-ERROR -.fi - -.ti 0 -Discussion - -Even though the preferred way of sending kerberos packets is over UDP -there are several occasions when it's more practical to use TCP. - -Mainly, it's usually much less cumbersome to get TCP through firewalls -than UDP. - -In theory, there's no reason for having explicit length fields, that -information is already encoded in the ASN1 encoding of the Kerberos -packets. But having explicit lengths makes it unnecessary to have to -decode the ASN.1 encoding just to know how much data has to be read. - -Another way of signaling the end of the request of the reply would be -to do a half-close after the request and a full-close after the reply. -This does not work well with all kinds of firewalls. - -.ti 0 -Security considerations - -.in 3 -This memo does not introduce any known security considerations in -addition to those mentioned in [RFC1510]. - -.ti 0 -References - -.in 3 -[RFC1510] Kohl, J. and Neuman, C., "The Kerberos Network -Authentication Service (V5)", RFC 1510, September 1993. - -.ti 0 -Authors' Addresses - -Assar Westerlund -.br -Swedish Institute of Computer Science -.br -Box 1263 -.br -S-164 29 KISTA -.br -Sweden - -Phone: +46-8-7521526 -.br -Fax: +46-8-7517230 -.br -EMail: assar@sics.se - -Johan Danielsson -.br -PDC, KTH -.br -S-100 44 STOCKHOLM -.br -Sweden - -Phone: +46-8-7907885 -.br -Fax: +46-8-247784 -.br -EMail: joda@pdc.kth.se diff --git a/doc/draft-foo3 b/doc/draft-foo3 deleted file mode 100644 index 2b8b7bb57..000000000 --- a/doc/draft-foo3 +++ /dev/null @@ -1,227 +0,0 @@ - - - - - - -Network Working Group Assar Westerlund - SICS -Internet-Draft Johan Danielsson -November, 1997 PDC, KTH -Expire in six months - - Kerberos vs firewalls - -Status of this Memo - - This document is an Internet-Draft. Internet-Drafts are working - documents of the Internet Engineering Task Force (IETF), its areas, - and its working groups. Note that other groups may also distribute - working documents as Internet-Drafts. - - Internet-Drafts are draft documents valid for a maximum of six months - and may be updated, replaced, or obsoleted by other documents at any - time. It is inappropriate to use Internet- Drafts as reference - material or to cite them other than as "work in progress." - - To view the entire list of current Internet-Drafts, please check the - "1id-abstracts.txt" listing contained in the Internet-Drafts Shadow - Directories on ftp.is.co.za (Africa), ftp.nordu.net (Europe), - munnari.oz.au (Pacific Rim), ds.internic.net (US East Coast), or - ftp.isi.edu (US West Coast). - - Distribution of this memo is unlimited. Please send comments to the - mailing list. - -Abstract - -Introduction - - Kerberos[RFC1510] is a protocol for authenticating parties - communicating over insecure networks. - - Firewalling is a technique for achieving an illusion of security by - putting restrictions on what kinds of packets and how these are sent - between the internal (so called "secure") network and the global (or - "insecure") Internet. - -Definitions - - client: the user, process, and host acquiring tickets from the KDC - and authenticating itself to the kerberised server. - - KDC: the Kerberos Key Distribution Center - - - - -Westerlund, Danielsson [Page 1] - -Internet Draft Kerberos vs firewalls November, 1997 - - - Kerberised server: the server using Kerberos to authenticate the - client, for example telnetd. - -Firewalls - - A firewall is usually placed between the "inside" and the "outside" - networks, and is supposed to protect the inside from the evils on the - outside. There are different kinds of firewalls. The main - differences are in the way they forward packets. - - o+ The most straight forward type is the one that just imposes - restrictions on incoming packets. Such a firewall could be - described as a router that filters packets that match some - criteria. - - o+ They may also "hide" some or all addresses on the inside of the - firewall, replacing the addresses in the outgoing packets with the - address of the firewall (aka network address translation, or NAT). - NAT can also be used without any packet filtering, for instance - when you have more than one host sharing a single address (for - example, with a dialed-in PPP connection). - - There are also firewalls that does NAT both on the inside and the - outside (a server on the inside will see this as a connection from - the firewall). - - o+ A third type is the proxy type firewall, that parses the contents - of the packets, basically acting as a server to the client, and as - a client to the server (man-in-the-middle). If Kerberos is to be - used with this kind of firewall, a protocol module that handles - KDC requests has to be written. - - This type of firewall might also cause extra trouble when used with - kerberised versions of protocols that the proxy understands, in - addition to the ones mentioned below. This is the case with the FTP - Security Extensions [RFC2228], that adds a new set of commands to the - FTP protocol [RFC959], for integrity, confidentiality, and privacy - protecting commands. When transferring data, the FTP protocol uses a - separate data channel, and an FTP proxy will have to look out for - commands that start a data transfer. If all commands are encrypted, - this is impossible. A protocol that doesn't suffer from this is the - Telnet Authentication Option [RFC1416] that does all authentication - and encryption in-bound. - -Scenarios - - Here the different scenarios we have considered are described, the - problems they introduce and the proposed ways of solving them. - - - -Westerlund, Danielsson [Page 2] - -Internet Draft Kerberos vs firewalls November, 1997 - - - Combinations of these can also occur. - - Client behind firewall - - This is the most typical and common scenario. First of all the - client needs some way of communicating with the KDC. This can be - done with whatever means and is usually much simpler when the KDC is - able to communicate over TCP. - - Apart from that, the client needs to be sure that the ticket it will - acquire from the KDC can be used to authenticate to a server outside - its firewall. For this, it needs to add the address(es) of potential - firewalls between itself and the KDC/server, to the list of its own - addresses when requesting the ticket. We are not aware of any - protocol for determining this set of addresses, thus this will have - to be manually configured in the client. - - The client could also request a ticket with no addresses, but some - KDCs and servers might not accept such a ticket. - - With the ticket in possession, communication with the kerberised - server will not need to be any different from communicating between a - non-kerberised client and server. - - Kerberised server behind firewall - - The kerberised server does not talk to the KDC at all so nothing - beyond normal firewall-traversal techniques for reaching the server - itself needs to be applied. - - The kerberised server needs to be able to retrieve the original - address (before its firewall) that the request was sent for. If this - is done via some out-of-band mechanism or it's directly able to see - it doesn't matter. - - KDC behind firewall - - The same restrictions applies for a KDC as for any other server. - -Specification - -Security considerations - - This memo does not introduce any known security considerations in - addition to those mentioned in [RFC1510]. - -References - - - - -Westerlund, Danielsson [Page 3] - -Internet Draft Kerberos vs firewalls November, 1997 - - - [RFC959] Postel, J. and Reynolds, J., "File Transfer Protocol (FTP)", - RFC 969, October 1985 - - [RFC1416] Borman, D., "Telnet Authentication Option", RFC 1416, - February 1993. - - [RFC1510] Kohl, J. and Neuman, C., "The Kerberos Network - Authentication Service (V5)", RFC 1510, September 1993. - - [RFC2228] Horowitz, M. and Lunt, S., "FTP Security Extensions", - RFC2228, October 1997. - -Authors' Addresses - - Assar Westerlund - Swedish Institute of Computer Science - Box 1263 - S-164 29 KISTA - Sweden - - Phone: +46-8-7521526 - Fax: +46-8-7517230 - EMail: assar@sics.se - - Johan Danielsson - PDC, KTH - S-100 44 STOCKHOLM - Sweden - - Phone: +46-8-7907885 - Fax: +46-8-247784 - EMail: joda@pdc.kth.se - - - - - - - - - - - - - - - - - - - -Westerlund, Danielsson [Page 4] - diff --git a/doc/draft-foo3.ms b/doc/draft-foo3.ms deleted file mode 100644 index c024ca355..000000000 --- a/doc/draft-foo3.ms +++ /dev/null @@ -1,260 +0,0 @@ -.\" even if this file is called .ms, it's using the me macros. -.\" to format try something like `nroff -me' -.\" level 2 heading -.de HH -.$p "\\$2" "" "\\$1" -.$0 "\\$2" -.. -.\" make sure footnotes produce the right thing with nroff -.ie t \ -\{\ -.ds { \v'-0.4m'\x'\\n(0x=0*-0.2m'\s-3 -.ds } \s0\v'0.4m' -.\} -.el \ -\{\ -.ds { [ -.ds } ] -.\} -.ds * \\*{\\n($f\\*}\k* -.\" page footer -.fo 'Westerlund, Danielsson''[Page %]' -.\" date -.ds RH \*(mo, 19\n(yr -.\" left margin -.nr lm 6 -.\" heading indent per level -.nr si 3n -.\" footnote indent -.nr fi 0 -.\" paragraph indent -.nr po 0 -.\" don't hyphenate -.hy 0 -.\" left adjustment -.ad l -.\" indent 0 -.in 0 -.\" line length 16cm and page length 25cm (~10 inches) -.ll 16c -.pl 25c -.ta \n(.luR -.nf -Network Working Group Assar Westerlund - SICS -Internet-Draft Johan Danielsson -\*(RH PDC, KTH -Expire in six months -.fi - -.\" page header, has to be set here so it won't appear on page 1 -.he 'Internet Draft'Kerberos vs firewalls'\*(RH' -.ce -.b "Kerberos vs firewalls" - -.HH 1 "Status of this Memo" -.lp -This document is an Internet-Draft. Internet-Drafts are working -documents of the Internet Engineering Task Force (IETF), its areas, -and its working groups. Note that other groups may also distribute -working documents as Internet-Drafts. -.lp -Internet-Drafts are draft documents valid for a maximum of six months -and may be updated, replaced, or obsoleted by other documents at any -time. It is inappropriate to use Internet- Drafts as reference -material or to cite them other than as \*(lqwork in progress.\*(rq -.lp -To view the entire list of current Internet-Drafts, please check the -\*(lq1id-abstracts.txt\*(rq listing contained in the Internet-Drafts -Shadow Directories on ftp.is.co.za (Africa), ftp.nordu.net (Europe), -munnari.oz.au (Pacific Rim), ds.internic.net (US East Coast), or -ftp.isi.edu (US West Coast). -.lp -Distribution of this memo is unlimited. Please send comments to the - mailing list. -.HH 1 "Abstract" -.lp -Kerberos and firewalls both deal with security, but doesn't get along -very well. This memo discusses ways to use Kerberos in a firewalled -environment. -.HH 1 "Introduction" -.lp -Kerberos[RFC1510] -.(d -[RFC1510] -Kohl, J. and Neuman, C., \*(lqThe Kerberos Network Authentication -Service (V5)\*(rq, RFC 1510, September 1993. -.)d -is a protocol for authenticating parties communicating over insecure -networks. Firewalling is a technique for achieving an illusion of -security by putting restrictions on what kinds of packets and how -these are sent between the internal (so called \*(lqsecure\*(rq) -network and the global (or \*(lqinsecure\*(rq) Internet. The problems -with firewalls are many, but to name a few: -.np -Firewalls usually doesn't allow people to use UDP. The reason for this -is that UDP is (by firewall advocates) considered insecure. This -belief is probably based on the fact that many \*(lqinsecure\*(rq -protocols (like NFS) use UDP. UDP packets are also considered easy to -fake. -.np -Firewalls usually doesn't allow people to connect to arbitrary ports, -such as the ports used when talking to the KDC. -.np -In many non-computer organisations, the computer staff isn't what -you'd call \*(lqwizards\*(rq; a typical case is an academic -institution, where someone is taking care of the computers part time, -and is doing research the rest of the time. Adding a complex device -like a firewall to an environment like this, often leads to poorly run -systems that is more a hindrance for the legitimate users than to -possible crackers. -.lp -The easiest way to deal with firewalls is to ignore them, however in -some cases this just isn't possible. You might have users that are -stuck behind a firewall, but also has to access your system, or you -might find yourself behind a firewall, for instance when out -travelling. -.lp -To make it possible for people to use Kerberos from behind a firewall, -there are several things to consider. -.(q -.i -Add things to do when stuck behind a firewall, like talking about the -problem with local staff, making them open some port in the firewall, -using some other port, or proxy. -.r -.)q -.HH 1 "Firewalls" -.lp -A firewall is usually placed between the \*(lqinside\*(rq and the -\*(lqoutside\*(rq networks, and is supposed to protect the inside from the -evils on the outside. There are different kinds of firewalls. The -main differences are in the way they forward (or doesn't) packets. -.ip \(bu -The most straight forward type is the one that just imposes -restrictions on incoming packets. Such a firewall could be described -as a router that filters packets that match some criteria. -.ip \(bu -They may also \*(lqhide\*(rq some or all addresses on the inside of the -firewall, replacing the addresses in the outgoing packets with the -address of the firewall (aka network address translation, or NAT). NAT -can also be used without any packet filtering, for instance when you -have more than one host sharing a single address (e.g with a dialed-in -PPP connection). -.ip -There are also firewalls that does NAT both on the inside and the -outside (a server on the inside will see this as a connection from the -firewall). -.ip \(bu -A third type is the proxy type firewall, that parses the contents of -the packets, basically acting as a server to the client, and as a -client to the server (man-in-the-middle). If Kerberos is to be used -with this kind of firewall, a protocol module that handles KDC -requests has to be written\**. -.(f -\**Instead of writing a new module for Kerberos, it can be possible to -hitch a ride on some other protocol, that's already beeing handled by -the proxy. -.)f -.lp -The last type of firewall might also cause extra trouble when used -with kerberised versions of protocols that the proxy understands, in -addition to the ones mentioned below. This is the case with the FTP -Security Extensions [RFC2228], -.(d -[RFC2228] -Horowitz, M. and Lunt, S., \*(lqFTP Security Extensions\*(rq, RFC2228, -October 1997. -.)d -that adds a new set of commands to the FTP protocol [RFC959], -.(d -[RFC959] Postel, J. and Reynolds, J., \*(lqFile Transfer Protocol -(FTP)\*(rq, RFC 969, October 1985 -.)d -for integrity, confidentiality, and privacy protecting commands, and -data. When transferring data, the FTP protocol uses a separate data -channel, and an FTP proxy will have to look out for commands that -start a data transfer. If all commands are encrypted, this is -impossible. A protocol that doesn't suffer from this is the Telnet -Authentication Option [RFC1416] -.(d -[RFC1416] -Borman, D., \*(lqTelnet Authentication Option\*(rq, RFC 1416, February -1993. -.)d -that does all -authentication and encryption in-bound. -.HH 1 "Scenarios" -.lp -Here the different scenarios we have considered are described, the -problems they introduce and the proposed ways of solving them. -Combinations of these can also occur. -.HH 2 "Client behind firewall" -.lp -This is the most typical and common scenario. First of all the client -needs some way of communicating with the KDC. This can be done with -whatever means and is usually much simpler when the KDC is able to -communicate over TCP. -.lp -Apart from that, the client needs to be sure that the ticket it will -acquire from the KDC can be used to authenticate to a server outside -its firewall. For this, it needs to add the address(es) of potential -firewalls between itself and the KDC/server, to the list of its own -addresses when requesting the ticket. We are not aware of any -protocol for determining this set of addresses, thus this will have to -be manually configured in the client. -.lp -The client could also request a ticket with no addresses. This is not -a recommended way to solve this problem. The address was put into the -ticket to make it harder to use a stolen ticket. A ticket without -addresses will therefore be less \*(lqsecure.\*(rq RFC1510 also says that -the KDC may refuse to issue, and the server may refuse to accept an -address-less ticket. -.lp -With the ticket in possession, communication with the kerberised -server will not need to be any different from communicating between a -non-kerberised client and server. -.HH 2 "Kerberised server behind firewall" -.lp -The kerberised server does not talk to the KDC at all, so nothing -beyond normal firewall-traversal techniques for reaching the server -itself needs to be applied. -.lp -If the firewall rewrites the clients address, the server will have to -use some other (possibly firewall specific) protocol to retrieve the -original address. If this is not possible, the address field will have -to be ignored. This has the same effect as if there were no addresses -in the ticket (see the discussion above). -.HH 2 "KDC behind firewall" -.lp -The KDC is in this respect basically just like any other server. -.\" .uh "Specification" -.HH 1 "Security considerations" -.lp -Since the whole network behind a NAT-type firewall looks like one -computer from the outside, any security added by the addresses in the -ticket will be lost. -.HH 1 "References" -.lp -.pd -.HH 1 "Authors' Addresses" -.lp -.nf -Assar Westerlund -Swedish Institute of Computer Science -Box 1263 -S-164 29 KISTA -.sp -Phone: +46-8-7521526 -Fax: +46-8-7517230 -EMail: assar@sics.se -.sp 2 -Johan Danielsson -Center for Parallel Computers -KTH -S-100 44 STOCKHOLM -.sp -Phone: +46-8-7906356 -Fax: +46-8-247784 -EMail: joda@pdc.kth.se -.fi \ No newline at end of file diff --git a/doc/draft-horowitz-key-derivation-01.txt b/doc/draft-horowitz-key-derivation-01.txt deleted file mode 100644 index 4dcff486b..000000000 --- a/doc/draft-horowitz-key-derivation-01.txt +++ /dev/null @@ -1,244 +0,0 @@ -Network Working Group M. Horowitz - Cygnus Solutions -Internet-Draft March, 1997 - - - Key Derivation for Authentication, Integrity, and Privacy - -Status of this Memo - - This document is an Internet-Draft. Internet-Drafts are working - documents of the Internet Engineering Task Force (IETF), its areas, - and its working groups. Note that other groups may also distribute - working documents as Internet-Drafts. - - Internet-Drafts are draft documents valid for a maximum of six months - and may be updated, replaced, or obsoleted by other documents at any - time. It is inappropriate to use Internet-Drafts as reference - material or to cite them other than as ``work in progress.'' - - To learn the current status of any Internet-Draft, please check the - ``1id-abstracts.txt'' listing contained in the Internet-Drafts Shadow - Directories on ds.internic.net (US East Coast), nic.nordu.net - (Europe), ftp.isi.edu (US West Coast), or munnari.oz.au (Pacific - Rim). - - Distribution of this memo is unlimited. Please send comments to the - author. - -Abstract - - Recent advances in cryptography have made it desirable to use longer - cryptographic keys, and to make more careful use of these keys. In - particular, it is considered unwise by some cryptographers to use the - same key for multiple purposes. Since most cryptographic-based - systems perform a range of functions, such as authentication, key - exchange, integrity, and encryption, it is desirable to use different - cryptographic keys for these purposes. - - This RFC does not define a particular protocol, but defines a set of - cryptographic transformations for use with arbitrary network - protocols and block cryptographic algorithm. - - -Deriving Keys - - In order to use multiple keys for different functions, there are two - possibilities: - - - Each protocol ``key'' contains multiple cryptographic keys. The - implementation would know how to break up the protocol ``key'' for - use by the underlying cryptographic routines. - - - The protocol ``key'' is used to derive the cryptographic keys. - The implementation would perform this derivation before calling - - - -Horowitz [Page 1] - -Internet Draft Key Derivation March, 1997 - - - the underlying cryptographic routines. - - In the first solution, the system has the opportunity to provide - separate keys for different functions. This has the advantage that - if one of these keys is broken, the others remain secret. However, - this comes at the cost of larger ``keys'' at the protocol layer. In - addition, since these ``keys'' may be encrypted, compromising the - cryptographic key which is used to encrypt them compromises all the - component keys. Also, the not all ``keys'' are used for all possible - functions. Some ``keys'', especially those derived from passwords, - are generated from limited amounts of entropy. Wasting some of this - entropy on cryptographic keys which are never used is unwise. - - The second solution uses keys derived from a base key to perform - cryptographic operations. By carefully specifying how this key is - used, all of the advantages of the first solution can be kept, while - eliminating some disadvantages. In particular, the base key must be - used only for generating the derived keys, and this derivation must - be non-invertible and entropy-preserving. Given these restrictions, - compromise of one derived keys does not compromise the other subkeys. - Attack of the base key is limited, since it is only used for - derivation, and is not exposed to any user data. - - Since the derived key has as much entropy as the base keys (if the - cryptosystem is good), password-derived keys have the full benefit of - all the entropy in the password. - - To generate a derived key from a base key: - - Derived Key = DK(Base Key, Well-Known Constant) - - where - - DK(Key, Constant) = n-truncate(E(Key, Constant)) - - In this construction, E(Key, Plaintext) is a block cipher, Constant - is a well-known constant defined by the protocol, and n-truncate - truncates its argument by taking the first n bits; here, n is the key - size of E. - - If the output of E is is shorter than n bits, then some entropy in - the key will be lost. If the Constant is smaller than the block size - of E, then it must be padded so it may be encrypted. If the Constant - is larger than the block size, then it must be folded down to the - block size to avoid chaining, which affects the distribution of - entropy. - - In any of these situations, a variation of the above construction is - used, where the folded Constant is encrypted, and the resulting - output is fed back into the encryption as necessary (the | indicates - concatentation): - - K1 = E(Key, n-fold(Constant)) - K2 = E(Key, K1) - - - -Horowitz [Page 2] - -Internet Draft Key Derivation March, 1997 - - - K3 = E(Key, K2) - K4 = ... - - DK(Key, Constant) = n-truncate(K1 | K2 | K3 | K4 ...) - - n-fold is an algorithm which takes m input bits and ``stretches'' - them to form n output bits with no loss of entropy, as described in - [Blumenthal96]. In this document, n-fold is always used to produce n - bits of output, where n is the key size of E. - - If the size of the Constant is not equal to the block size of E, then - the Constant must be n-folded to the block size of E. This number is - used as input to E. If the block size of E is less than the key - size, then the output from E is taken as input to a second invocation - of E. This process is repeated until the number of bits accumulated - is greater than or equal to the key size of E. When enough bits have - been computed, the first n are taken as the derived key. - - Since the derived key is the result of one or more encryptions in the - base key, deriving the base key from the derived key is equivalent to - determining the key from a very small number of plaintext/ciphertext - pairs. Thus, this construction is as strong as the cryptosystem - itself. - - -Deriving Keys from Passwords - - When protecting information with a password or other user data, it is - necessary to convert an arbitrary bit string into an encryption key. - In addition, it is sometimes desirable that the transformation from - password to key be difficult to reverse. A simple variation on the - construction in the prior section can be used: - - Key = DK(n-fold(Password), Well-Known Constant) - - The n-fold algorithm is reversible, so recovery of the n-fold output - is equivalent to recovery of Password. However, recovering the n- - fold output is difficult for the same reason recovering the base key - from a derived key is difficult. - - - - Traditionally, the transformation from plaintext to ciphertext, or - vice versa, is determined by the cryptographic algorithm and the key. - A simple way to think of derived keys is that the transformation is - determined by the cryptographic algorithm, the constant, and the key. - - For interoperability, the constants used to derive keys for different - purposes must be specified in the protocol specification. The - constants must not be specified on the wire, or else an attacker who - determined one derived key could provide the associated constant and - spoof data using that derived key, rather than the one the protocol - designer intended. - - - - -Horowitz [Page 3] - -Internet Draft Key Derivation March, 1997 - - - Determining which parts of a protocol require their own constants is - an issue for the designer of protocol using derived keys. - - -Security Considerations - - This entire document deals with security considerations relating to - the use of cryptography in network protocols. - - -Acknowledgements - - I would like to thank Uri Blumenthal, Hugo Krawczyk, and Bill - Sommerfeld for their contributions to this document. - - -References - - [Blumenthal96] Blumenthal, U., "A Better Key Schedule for DES-Like - Ciphers", Proceedings of PRAGOCRYPT '96, 1996. - - -Author's Address - - Marc Horowitz - Cygnus Solutions - 955 Massachusetts Avenue - Cambridge, MA 02139 - - Phone: +1 617 354 7688 - Email: marc@cygnus.com - - - - - - - - - - - - - - - - - - - - - - - - - - -Horowitz [Page 4] diff --git a/doc/draft-ietf-cat-gssv2-08.txt b/doc/draft-ietf-cat-gssv2-08.txt deleted file mode 100644 index ccba35eeb..000000000 --- a/doc/draft-ietf-cat-gssv2-08.txt +++ /dev/null @@ -1,62 +0,0 @@ - - -A new Request for Comments is now available in online RFC libraries. - - - RFC 2078 - - Title: Generic Security Service Application Program - Interface, Version 2 - Author: J. Linn - Date: January 1997 - Mailbox: John.Linn@ov.com - Pages: 85 - Characters: 185990 - Obsoletes: 1508 - - URL: ftp://ds.internic.net/rfc/rfc2078.txt - - -This memo revises RFC-1508, making specific, incremental changes in -response to implementation experience and liaison requests. It is -intended, therefore, that this memo or a successor version thereto -will become the basis for subsequent progression of the GSS-API -specification on the standards track. This document is a product of -the Common Authentication Technology Working Group. - -This is now a Proposed Standard Protocol. - -This document specifies an Internet standards track protocol for the -Internet community, and requests discussion and suggestions for -improvements. Please refer to the current edition of the "Internet -Official Protocol Standards" (STD 1) for the standardization state and -status of this protocol. Distribution of this memo is unlimited. - -This announcement is sent to the IETF list and the RFC-DIST list. -Requests to be added to or deleted from the IETF distribution list -should be sent to IETF-REQUEST@CNRI.RESTON.VA.US. Requests to be -added to or deleted from the RFC-DIST distribution list should -be sent to RFC-DIST-REQUEST@ISI.EDU. - -Details on obtaining RFCs via FTP or EMAIL may be obtained by sending -an EMAIL message to rfc-info@ISI.EDU with the message body -help: ways_to_get_rfcs. For example: - - To: rfc-info@ISI.EDU - Subject: getting rfcs - - help: ways_to_get_rfcs - -Requests for special distribution should be addressed to either the -author of the RFC in question, or to admin@DS.INTERNIC.NET. Unless -specifically noted otherwise on the RFC itself, all RFCs are for -unlimited distribution. - -Submissions for Requests for Comments should be sent to -RFC-EDITOR@ISI.EDU. Please consult RFC 1543, Instructions to RFC -Authors, for further information. - - -Joyce K. Reynolds and Mary Kennedy -USC/Information Sciences Institute - diff --git a/doc/draft-ietf-cat-gssv2-cbind-04.txt b/doc/draft-ietf-cat-gssv2-cbind-04.txt deleted file mode 100644 index 518f4c63d..000000000 --- a/doc/draft-ietf-cat-gssv2-cbind-04.txt +++ /dev/null @@ -1,6188 +0,0 @@ - - Internet draft J.Wray - IETF Common Authentication Technology WG Digital Equipment Corporation - March 1997 - - - - Generic Security Service API Version 2 : C-bindings - - - 1. STATUS OF THIS MEMO - - This document is an Internet Draft. Internet Drafts are working - documents of the Internet Engineering Task Force (IETF), its Areas, and - its Working Groups. Note that other groups may also distribute working - documents as Internet Drafts. Internet Drafts are draft documents valid - for a maximum of six months. Internet Drafts may be updated, replaced, - or obsoleted by other documents at any time. It is not appropriate to - use Internet Drafts as reference material or to cite them other than as - a "working draft" or "work in progress." Please check the I-D abstract - listing contained in each Internet Draft directory to learn the current - status of this or any other Internet Draft. - - Comments on this document should be sent to "cat-ietf@MIT.EDU", the IETF - Common Authentication Technology WG discussion list. - - - 2. ABSTRACT - - This draft document specifies C language bindings for Version 2 of the - Generic Security Service Application Program Interface (GSSAPI), which - is described at a language-independent conceptual level in other drafts - [GSSAPI]. It revises RFC-1509, making specific incremental changes in - response to implementation experience and liaison requests. It is - intended, therefore, that this draft or a successor version thereof will - become the basis for subsequent progression of the GSS-API specification - on the standards track. - - The Generic Security Service Application Programming Interface provides - security services to its callers, and is intended for implementation - atop a variety of underlying cryptographic mechanisms. Typically, - GSSAPI callers will be application protocols into which security - enhancements are integrated through invocation of services provided by - the GSSAPI. The GSSAPI allows a caller application to authenticate a - principal identity associated with a peer application, to delegate - rights to a peer, and to apply security services such as confidentiality - and integrity on a per-message basis. - - - - - - - - - Wray Document Expiration: 1 September 1997 [Page 1] - - - - - - - - INTERNET-DRAFT GSS-API V2 - C bindings March 1997 - - - - 3. INTRODUCTION - - The Generic Security Service Application Programming Interface [GSSAPI] - provides security services to calling applications. It allows a - communicating application to authenticate the user associated with - another application, to delegate rights to another application, and to - apply security services such as confidentiality and integrity on a per- - message basis. - - There are four stages to using the GSSAPI: - - (a) The application acquires a set of credentials with which it may - prove its identity to other processes. The application's - credentials vouch for its global identity, which may or may not be - related to any local username under which it may be running. - - (b) A pair of communicating applications establish a joint security - context using their credentials. The security context is a pair - of GSSAPI data structures that contain shared state information, - which is required in order that per-message security services may - be provided. Examples of state that might be shared between - applications as part of a security context are cryptographic keys, - and message sequence numbers. As part of the establishment of a - security context, the context initiator is authenticated to the - responder, and may require that the responder is authenticated in - turn. The initiator may optionally give the responder the right - to initiate further security contexts, acting as an agent or - delegate of the initiator. This transfer of rights is termed - delegation, and is achieved by creating a set of credentials, - similar to those used by the initiating application, but which may - be used by the responder. - - To establish and maintain the shared information that makes up the - security context, certain GSSAPI calls will return a token data - structure, which is a cryptographically protected opaque data - type. The caller of such a GSSAPI routine is responsible for - transferring the token to the peer application, encapsulated if - necessary in an application-application protocol. On receipt of - such a token, the peer application should pass it to a - corresponding GSSAPI routine which will decode the token and - extract the information, updating the security context state - information accordingly. - - (c) Per-message services are invoked to apply either: - - (i) integrity and data origin authentication, or - - (ii) confidentiality, integrity and data origin authentication - - to application data, which are treated by GSSAPI as arbitrary - octet-strings. An application transmitting a message that it - - - - Wray Document Expiration: 1 September 1997 [Page 2] - - - - - - - - INTERNET-DRAFT GSS-API V2 - C bindings March 1997 - - - - wishes to protect will call the appropriate GSSAPI routine - (gss_get_mic or gss_wrap) to apply protection, specifying the - appropriate security context, and send the resulting token to the - receiving application. The receiver will pass the received token - (and, in the case of data protected by gss_get_mic, the - accompanying message-data) to the corresponding decoding routine - (gss_verify_mic or gss_unwrap) to remove the protection and - validate the data. - - (d) At the completion of a communications session (which may extend - across several transport connections), each application calls a - GSSAPI routine to delete the security context. Multiple contexts - may also be used (either successively or simultaneously) within a - single communications association, at the option of the - applications. - - - 4. GSSAPI ROUTINES - - This section lists the routines that make up the GSSAPI, and offers a - brief description of the purpose of each routine. Detailed descriptions - of each routine are listed in alphabetical order in section 7. - - Table 4-1 GSSAPI Credential-management Routines - - ROUTINE SECTION FUNCTION - - gss_acquire_cred 7.2 Assume a global identity; - Obtain a GSSAPI credential - handle for pre-existing - credentials. - - gss_add_cred 7.3 Construct credentials - incrementally - - gss_inquire_cred 7.21 Obtain information about - a credential. - - gss_inquire_cred_by_mech 7.22 Obtain per-mechanism information - about a credential. - - gss_release_cred 7.27 Discard a credential handle. - - - - - - - - - - - - - Wray Document Expiration: 1 September 1997 [Page 3] - - - - - - - - INTERNET-DRAFT GSS-API V2 - C bindings March 1997 - - - - Table 4-2 GSSAPI Context-level Routines - - ROUTINE SECTION FUNCTION - - gss_init_sec_context 7.19 Initiate a security context - with a peer application - - - gss_accept_sec_context 7.1 Accept a security context - initiated by a peer - application - - gss_delete_sec_context 7.9 Discard a security context - - gss_process_context_token 7.25 Process a token on a security - context from a peer - application - - gss_context_time 7.7 Determine for how long a - context will remain valid - - gss_inquire_context 7.20 Obtain information about a - security context - - gss_wrap_size_limit 7.33 Determine token-size limit for - gss_wrap on a context - - gss_export_sec_context 7.14 Transfer a security context to - another process - - gss_import_sec_context 7.17 Import a transferred context - - - - - Table 4-3 GSSAPI Per-message Routines - - ROUTINE SECTION FUNCTION - - gss_get_mic 7.15 Calculate a cryptographic - Message Integrity Code (MIC) - for a message; integrity service - - gss_verify_mic 7.32 Check a MIC against a message; - verify integrity of a received - message - - gss_wrap 7.36 Attach a MIC to a message, and - optionally encrypt the message - content; confidentiality service - - - - - Wray Document Expiration: 1 September 1997 [Page 4] - - - - - - - - INTERNET-DRAFT GSS-API V2 - C bindings March 1997 - - - - gss_unwrap 7.31 Verify a message with attached - MIC, and decrypt message - content if necessary. - - - - - Table 4-4 GSSAPI Name manipulation Routines - - ROUTINE SECTION FUNCTION - - gss_import_name 7.16 Convert a contiguous string name - to internal-form - - gss_display_name 7.10 Convert internal-form name - to text - - gss_compare_name 7.6 Compare two internal-form names - - gss_release_name 7.28 Discard an internal-form name - - gss_inquire_names_for_mech 7.24 List the name-types supported - by a specified mechanism - - gss_inquire_mechs_for_name 7.23 List mechanisms that support - a given nametype - - gss_canonicalize_name 7.5 Convert an internal name to - an MN. - - gss_export_name 7.13 Convert an MN to export form - - gss_duplicate_name 7.12 Create a copy of an internal name - - - - - Table 4-5 GSSAPI Miscellaneous Routines - - ROUTINE SECTION FUNCTION - - gss_display_status 7.11 Convert a GSSAPI status code - to text - - gss_indicate_mechs 7.18 Determine available underlying - authentication mechanisms - - gss_release_buffer 7.26 Discard a buffer - - gss_release_oid_set 7.29 Discard a set of object - identifiers - - - - Wray Document Expiration: 1 September 1997 [Page 5] - - - - - - - - INTERNET-DRAFT GSS-API V2 - C bindings March 1997 - - - - gss_create_empty_oid_set 7.8 Create a set containing no - object identifiers - - gss_add_oid_set_member 7.4 Add an object identifier to - a set - - gss_test_oid_set_member 7.30 Determines whether an object - identifier is a member of a set - - - - - - Individual GSSAPI implementations may augment these routines by - providing additional mechanism-specific routines if required - functionality is not available from the generic forms. Applications are - encouraged to use the generic routines wherever possible on portability - grounds. - - - 5. DATA TYPES AND CALLING CONVENTIONS - - The following conventions are used by the GSSAPI C-language bindings: - - 5.1. Integer types - - GSSAPI uses the following integer data type: - - OM_uint32 32-bit unsigned integer - - Where guaranteed minimum bit-count is important, this portable data type - is used by the GSSAPI routine definitions. Individual GSSAPI - implementations will include appropriate typedef definitions to map this - type onto a built-in data type. If the platform supports the X/Open - xom.h header file, the OM_uint32 definition contained therein should be - used; the GSSAPI header file in Appendix A contains logic that will - detect the prior inclusion of xom.h, and will not attempt to re-declare - OM_uint32. If the X/Open header file is not available on the platform, - the GSSAPI implementation should use the smallest natural unsigned - integer type that provides at least 32 bits of precision. - - 5.2. String and similar data - - Many of the GSSAPI routines take arguments and return values that - describe contiguous octet-strings. All such data is passed between the - GSSAPI and the caller using the gss_buffer_t data type. This data type - is a pointer to a buffer descriptor, which consists of a length field - that contains the total number of bytes in the datum, and a value field - which contains a pointer to the actual datum: - - - - - - Wray Document Expiration: 1 September 1997 [Page 6] - - - - - - - - INTERNET-DRAFT GSS-API V2 - C bindings March 1997 - - - - typedef struct gss_buffer_desc_struct { - size_t length; - void *value; - } gss_buffer_desc, *gss_buffer_t; - - Storage for data returned to the application by a GSSAPI routine using - the gss_buffer_t conventions is allocated by the GSSAPI routine. The - application may free this storage by invoking the gss_release_buffer - routine. Allocation of the gss_buffer_desc object is always the - responsibility of the application; unused gss_buffer_desc objects may - be initialized to the value GSS_C_EMPTY_BUFFER. - - 5.2.1. Opaque data types - - Certain multiple-word data items are considered opaque data types at the - GSSAPI, because their internal structure has no significance either to - the GSSAPI or to the caller. Examples of such opaque data types are the - input_token parameter to gss_init_sec_context (which is opaque to the - caller), and the input_message parameter to gss_wrap (which is opaque to - the GSSAPI). Opaque data is passed between the GSSAPI and the - application using the gss_buffer_t datatype. - - 5.2.2. Character strings - - Certain multiple-word data items may be regarded as simple ISO Latin-1 - character strings. Examples are the printable strings passed to - gss_import_name via the input_name_buffer parameter. Some GSSAPI - routines also return character strings. All such character strings are - passed between the application and the GSSAPI implementation using the - gss_buffer_t datatype, which is a pointer to a gss_buffer_desc object. - - When a gss_buffer_desc object describes a printable string, the length - field of the gss_buffer_desc should only count printable characters - within the string. In particular, a trailing NUL character should NOT - be included in the length count, nor should either the GSSAPI - implementation or the application assume the presence of an uncounted - trailing NUL. - - 5.3. Object Identifiers - - Certain GSSAPI procedures take parameters of the type gss_OID, or Object - identifier. This is a type containing ISO-defined tree-structured - values, and is used by the GSSAPI caller to select an underlying - security mechanism and to specify namespaces. A value of type gss_OID - has the following structure: - - typedef struct gss_OID_desc_struct { - OM_uint32 length; - void *elements; - } gss_OID_desc, *gss_OID; - - - - - Wray Document Expiration: 1 September 1997 [Page 7] - - - - - - - - INTERNET-DRAFT GSS-API V2 - C bindings March 1997 - - - - The elements field of this structure points to the first byte of an - octet string containing the ASN.1 BER encoding of the value portion of - the normal BER TLV encoding of the gss_OID. The length field contains - the number of bytes in this value. For example, the gss_OID value - corresponding to {iso(1) identified-organization(3) icd-ecma(12) - member-company(2) dec(1011) cryptoAlgorithms(7) DASS(5)}, meaning the - DASS X.509 authentication mechanism, has a length field of 7 and an - elements field pointing to seven octets containing the following octal - values: 53,14,2,207,163,7,5. GSSAPI implementations should provide - constant gss_OID values to allow applications to request any supported - mechanism, although applications are encouraged on portability grounds - to accept the default mechanism. gss_OID values should also be provided - to allow applications to specify particular name types (see section - 5.10). Applications should treat gss_OID_desc values returned by GSSAPI - routines as read-only. In particular, the application should not - attempt to deallocate them with free(). The gss_OID_desc datatype is - equivalent to the X/Open OM_object_identifier datatype[XOM]. - - 5.4. Object Identifier Sets - - Certain GSSAPI procedures take parameters of the type gss_OID_set. This - type represents one or more object identifiers (section 5.3). A - gss_OID_set object has the following structure: - - typedef struct gss_OID_set_desc_struct { - size_t count; - gss_OID elements; - } gss_OID_set_desc, *gss_OID_set; - - The count field contains the number of OIDs within the set. The - elements field is a pointer to an array of gss_OID_desc objects, each of - which describes a single OID. gss_OID_set values are used to name the - available mechanisms supported by the GSSAPI, to request the use of - specific mechanisms, and to indicate which mechanisms a given credential - supports. - - All OID sets returned to the application by GSSAPI are dynamic objects - (the gss_OID_set_desc, the "elements" array of the set, and the - "elements" array of each member OID are all dynamically allocated), and - this storage must be deallocated by the application using the - gss_release_oid_set() routine. - - - 5.5. Credentials - - A credential handle is a caller-opaque atomic datum that identifies a - GSSAPI credential data structure. It is represented by the caller- - opaque type gss_cred_id_t, which should be implemented as a pointer or - arithmetic type. If a pointer implementation is chosen, care must be - taken to ensure that two gss_cred_id_t values may be compared with the - == operator. - - - - Wray Document Expiration: 1 September 1997 [Page 8] - - - - - - - - INTERNET-DRAFT GSS-API V2 - C bindings March 1997 - - - - GSSAPI credentials can contain mechanism-specific principal - authentication data for multiple mechanisms. A GSSAPI credential is - composed of a set of credential-elements, each of which is applicable to - a single mechanism. A credential may contain at most one credential- - element for each supported mechanism. A credential-element identifies - the data needed by a single mechanism to authenticate a single - principal, and conceptually contains two credential-references that - describing the actual mechanism-specific authentication data, one to be - used by GSSAPI for initiating contexts, and one to be used for - accepting contexts. For mechanisms that do not distinguish between - acceptor and initiator credentials, both references would point to the - same underlying mechanism-specific authentication data. - - Credentials describe a set of mechanism-specific principals, and give - their holder the ability to act as any of those principals. All - principal identities asserted by a single GSSAPI credential should - belong to the same entity, although enforcement of this property is an - implementation-specific matter. The GSSAPI does not make the actual - credentials available to applications; instead a credential handle is - used to identify a particular credential, held internally by GSSAPI. - The combination of GSSAPI credential handle and mechanism identifies the - principal whose identity will be asserted by the credential when used - with that mechanism. - - The gss_init_sec_context and gss_accept_sec_context routines allow the - value GSS_C_NO_CREDENTIAL to be specified as their credential handle - parameter. This special credential-handle indicates a desire by the - application to act as a default principal. While individual GSSAPI - implementations are free to determine such default behavior as - appropriate to the mechanism, the following default behavior by these - routines is recommended for portability: - - (a) gss_init_sec_context - - (i) If there is only a single principal capable of initiating - security contexts for the chosen mechanism that the - application is authorized to act on behalf of, then that - principal shall be used, otherwise - - (ii) If the platform maintains a concept of a default network- - identity for the chosen mechanism, and if the application is - authorized to act on behalf of that identity for the purpose - of initiating security contexts, then the principal - corresponding to that identity shall be used, otherwise - - (iii) If the platform maintains a concept of a default local - identity, and provides a means to map local identities into - network-identities for the chosen mechanism, and if the - application is authorized to act on behalf of the network- - identity image of the default local identity for the purpose - of initiating security contexts using the chosen mechanism, - - - - Wray Document Expiration: 1 September 1997 [Page 9] - - - - - - - - INTERNET-DRAFT GSS-API V2 - C bindings March 1997 - - - - then the principal corresponding to that identity shall be - used, otherwise - - (iv) A user-configurable default identity should be used. - - (b) gss_accept_sec_context - - (i) If there is only a single authorized principal identity - capable of accepting security contexts for the chosen - mechanism, then that principal shall be used, otherwise - - (ii) If the mechanism can determine the identity of the target - principal by examining the context-establishment token, and - if the accepting application is authorized to act as that - principal for the purpose of accepting security contexts - using the chosen mechanism, then that principal identity - shall be used, otherwise - - (iii) If the mechanism supports context acceptance by any - principal, and if mutual authentication was not requested, - any principal that the application is authorized to accept - security contexts under using the chosen mechanism may be - used, otherwise - - (iv) A user-configurable default identity shall be used. - - The purpose of the above rules is to allow security contexts to be - established by both initiator and acceptor using the default behavior - wherever possible. Applications requesting default behavior are likely - to be more portable across mechanisms and platforms than ones that use - gss_acquire_cred to request a specific identity. - - 5.6. Contexts - - The gss_ctx_id_t data type contains a caller-opaque atomic value that - identifies one end of a GSSAPI security context. It should be - implemented as a pointer or arithmetic type. If a pointer type is - chosen, care should be taken to ensure that two gss_ctx_id_t values may - be compared with the == operator. - - The security context holds state information about each end of a peer - communication, including cryptographic state information. - - 5.7. Authentication tokens - - A token is a caller-opaque type that GSSAPI uses to maintain - synchronization between the context data structures at each end of a - GSSAPI security context. The token is a cryptographically protected - octet-string, generated by the underlying mechanism at one end of a - GSSAPI security context for use by the peer mechanism at the other end. - Encapsulation (if required) and transfer of the token are the - - - - Wray Document Expiration: 1 September 1997 [Page 10] - - - - - - - - INTERNET-DRAFT GSS-API V2 - C bindings March 1997 - - - - responsibility of the peer applications. A token is passed between the - GSSAPI and the application using the gss_buffer_t conventions. - - 5.8. Interprocess tokens - - Certain GSSAPI routines are intended to transfer data between processes - in multi-process programs. These routines use a caller-opaque octet- - string, generated by the GSSAPI in one process for use by the GSSAPI in - another process. The calling application is responsible for - transferring such tokens between processes in an OS-specific manner. - Note that, while GSSAPI implementors are encouraged to avoid placing - sensitive information within interprocess tokens, or to - cryptographically protect them, many implementations will be unable to - avoid placing key material or other sensitive data within them. It is - the application's responsibility to ensure that interprocess tokens are - protected in transit, and transferred only to processes that are - trustworthy. An interprocess token is passed between the GSSAPI and the - application using the gss_buffer_t conventions. - - 5.9. Status values - - One or more status codes are returned by each GSSAPI routine. Two - distinct sorts of status codes are returned. These are termed GSS - status codes and Mechanism status codes. - - 5.9.1. GSS status codes - - GSSAPI routines return GSS status codes as their OM_uint32 function - value. These codes indicate errors that are independent of the - underlying mechanism(s) used to provide the security service. The - errors that can be indicated via a GSS status code are either generic - API routine errors (errors that are defined in the GSS-API - specification) or calling errors (errors that are specific to these - language bindings). - - A GSS status code can indicate a single fatal generic API error from the - routine and a single calling error. In addition, supplementary status - information may be indicated via the setting of bits in the - supplementary info field of a GSS status code. - - These errors are encoded into the 32-bit GSS status code as follows: - - MSB LSB - |------------------------------------------------------------| - | Calling Error | Routine Error | Supplementary Info | - |------------------------------------------------------------| - Bit 31 24 23 16 15 0 - - - Hence if a GSS-API routine returns a GSS status code whose upper 16 bits - contain a non-zero value, the call failed. If the calling error field - - - - Wray Document Expiration: 1 September 1997 [Page 11] - - - - - - - - INTERNET-DRAFT GSS-API V2 - C bindings March 1997 - - - - is non-zero, the invoking application's call of the routine was - erroneous. Calling errors are defined in table 5-1. If the routine - error field is non-zero, the routine failed for one of the routine- - specific reasons listed below in table 5-2. Whether or not the upper 16 - bits indicate a failure or a success, the routine may indicate - additional information by setting bits in the supplementary info field - of the status code. The meaning of individual bits is listed below in - table 5-3. - - Table 5-1 Calling Errors - - Name Value in Meaning - Field - GSS_S_CALL_INACCESSIBLE_READ 1 A required input - parameter could - not be read. - GSS_S_CALL_INACCESSIBLE_WRITE 2 A required output - parameter could - not be written. - GSS_S_CALL_BAD_STRUCTURE 3 A parameter was - malformed - - - - - Table 5-2 Routine Errors - - Name Value in Meaning - Field - - GSS_S_BAD_MECH 1 An unsupported mechanism was - requested - GSS_S_BAD_NAME 2 An invalid name was supplied - GSS_S_BAD_NAMETYPE 3 A supplied name was of an - unsupported type - GSS_S_BAD_BINDINGS 4 Incorrect channel bindings - were supplied - GSS_S_BAD_STATUS 5 An invalid status code was - supplied - GSS_S_BAD_SIG 6 A token had an invalid - GSS_S_BAD_MIC MIC - GSS_S_NO_CRED 7 No credentials were supplied, - or the credentials were - unavailable or inaccessible. - GSS_S_NO_CONTEXT 8 No context has been - established - GSS_S_DEFECTIVE_TOKEN 9 A token was invalid - GSS_S_DEFECTIVE_CREDENTIAL 10 A credential was invalid - GSS_S_CREDENTIALS_EXPIRED 11 The referenced credentials - have expired - - - - - Wray Document Expiration: 1 September 1997 [Page 12] - - - - - - - - INTERNET-DRAFT GSS-API V2 - C bindings March 1997 - - - - GSS_S_CONTEXT_EXPIRED 12 The context has expired - GSS_S_FAILURE 13 Miscellaneous failure - (see text) - GSS_S_BAD_QOP 14 The quality-of-protection - requested could not be - provide - GSS_S_UNAUTHORIZED 15 The operation is forbidden by - local security policy - GSS_S_UNAVAILABLE 16 The operation or option is not - available - GSS_S_DUPLICATE_ELEMENT 17 The requested credential element - already exists - GSS_S_NAME_NOT_MN 18 The provided name was not a - mechanism name. - - - - - - Table 5-3 Supplementary Status Bits - - Name Bit Number Meaning - GSS_S_CONTINUE_NEEDED 0 (LSB) The routine must be called - again to complete its function. - See routine documentation for - detailed description. - GSS_S_DUPLICATE_TOKEN 1 The token was a duplicate of - an earlier token - GSS_S_OLD_TOKEN 2 The token's validity period - has expired - GSS_S_UNSEQ_TOKEN 3 A later token has already been - processed - GSS_S_GAP_TOKEN 4 An expected per-message token - was not received - - - The routine documentation also uses the name GSS_S_COMPLETE, which is a - zero value, to indicate an absence of any API errors or supplementary - information bits. - - All GSS_S_xxx symbols equate to complete OM_uint32 status codes, rather - than to bitfield values. For example, the actual value of the symbol - GSS_S_BAD_NAMETYPE (value 3 in the routine error field) is 3 << 16. - - The macros GSS_CALLING_ERROR(), GSS_ROUTINE_ERROR() and - GSS_SUPPLEMENTARY_INFO() are provided, each of which takes a GSS status - code and removes all but the relevant field. For example, the value - obtained by applying GSS_ROUTINE_ERROR to a status code removes the - calling errors and supplementary info fields, leaving only the routine - errors field. The values delivered by these macros may be directly - compared with a GSS_S_xxx symbol of the appropriate type. The macro - - - - Wray Document Expiration: 1 September 1997 [Page 13] - - - - - - - - INTERNET-DRAFT GSS-API V2 - C bindings March 1997 - - - - GSS_ERROR() is also provided, which when applied to a GSS status code - returns a non-zero value if the status code indicated a calling or - routine error, and a zero value otherwise. All macros defined by GSS- - API evaluate their argument(s) exactly once. - - A GSS-API implementation may choose to signal calling errors in a - platform-specific manner instead of, or in addition to the routine - value; routine errors and supplementary info should be returned via - routine status values only. - - 5.9.2. Mechanism-specific status codes - - GSS-API routines return a minor_status parameter, which is used to - indicate specialized errors from the underlying security mechanism. - This parameter may contain a single mechanism-specific error, indicated - by a OM_uint32 value. - - The minor_status parameter will always be set by a GSS-API routine, even - if it returns a calling error or one of the generic API errors indicated - above as fatal, although most other output parameters may remain unset - in such cases. However, output parameters that are expected to return - pointers to storage allocated by a routine must always be set by the - routine, even in the event of an error, although in such cases the GSS- - API routine may elect to set the returned parameter value to NULL to - indicate that no storage was actually allocated. Any length field - associated with such pointers (as in a gss_buffer_desc structure) should - also be set to zero in such cases. - - The GSS status code GSS_S_FAILURE is used to indicate that the - underlying mechanism detected an error for which no specific GSS status - code is defined. The mechanism status code will provide more details - about the error. - - 5.10. Names - - A name is used to identify a person or entity. GSS-API authenticates - the relationship between a name and the entity claiming the name. - - Since different authentication mechanisms may employ different - namespaces for identifying their principals, GSSAPI's naming support is - necessarily complex in multi-mechanism environments (or even in some - single-mechanism environments where the underlying mechanism supports - multiple namespaces). - - Two distinct representations are defined for names: - - (a) An internal form. This is the GSSAPI "native" format for names, - represented by the implementation-specific gss_name_t type. It is - opaque to GSSAPI callers. A single gss_name_t object may contain - multiple names from different namespaces, but all names should - refer to the same entity. An example of such an internal name - - - - Wray Document Expiration: 1 September 1997 [Page 14] - - - - - - - - INTERNET-DRAFT GSS-API V2 - C bindings March 1997 - - - - would be the name returned from a call to the gss_inquire_cred - routine, when applied to a credential containing credential - elements for multiple authentication mechanisms employing - different namespaces. This gss_name_t object will contain a - distinct name for the entity for each authentication mechanism. - - For GSSAPI implementations supporting multiple namespaces, objects - of type gss_name_t must contain sufficient information to - determine the namespace to which each primitive name belongs. - - (b) Mechanism-specific contiguous octet-string forms. A format - capable of containing a single name (from a single namespace). - Contiguous string names are always accompanied by an object - identifier specifying the namespace to which the name belongs, and - their format is dependent on the authentication mechanism that - employs the name. Many, but not all, contiguous string names will - be printable, and may therefore be used by GSSAPI applications for - communication with their users. - - Routines (gss_import_name and gss_display_name) are provided to convert - names between contiguous string representations and the internal - gss_name_t type. gss_import_name may support multiple syntaxes for each - supported namespace, allowing users the freedom to choose a preferred - name representation. gss_display_name should use an implementation- - chosen printable syntax for each supported name-type. - - If an application calls gss_display_name(), passing the internal name - resulting from a call to gss_import_name(), there is no guarantee the - the resulting contiguous string name will be the same as the original - imported string name. Nor do name-space identifiers necessarily survive - unchanged after a journey through the internal name-form. An example of - this might be a mechanism that authenticates X.500 names, but provides - an algorithmic mapping of Internet DNS names into X.500. That - mechanism's implementation of gss_import_name() might, when presented - with a DNS name, generate an internal name that contained both the - original DNS name and the equivalent X.500 name. Alternatively, it might - only store the X.500 name. In the latter case, gss_display_name() would - most likely generate a printable X.500 name, rather than the original - DNS name. - - The process of authentication delivers to the context acceptor an - internal name. Since this name has been authenticated by a single - mechanism, it contains only a single name (even if the internal name - presented by the context initiator to gss_init_sec_context had multiple - components). Such names are termed internal mechanism names, or "MN"s - and the names emitted by gss_accept_sec_context() are always of this - type. Since some applications may require MNs without wanting to incur - the overhead of an authentication operation, a second function, - gss_canonicalize_name(), is provided to convert a general internal name - into an MN. - - - - - Wray Document Expiration: 1 September 1997 [Page 15] - - - - - - - - INTERNET-DRAFT GSS-API V2 - C bindings March 1997 - - - - Comparison of internal-form names may be accomplished via the - gss_compare_name() routine, which returns true if the two names being - compared refer to the same entity. This removes the need for the - application program to understand the syntaxes of the various printable - names that a given GSS-API implementation may support. Since GSSAPI - assumes that all primitive names contained within a given internal name - refer to the same entity, gss_compare_name() can return true if the two - names have at least one primitive name in common. If the implementation - embodies knowledge of equivalence relationships between names taken from - different namespaces, this knowledge may also allow successful - comparison of internal names containing no overlapping primitive - elements. - - When used in large access control lists, the overhead of invoking - gss_import_name() and gss_compare_name() on each name from the ACL may - be prohibitive. As an alternative way of supporting this case, GSSAPI - defines a special form of the contiguous string name which may be - compared directly (e.g. with memcmp()). Contigous names suitable for - comparison are generated by the gss_export_name() routine, which - requires an MN as input. Exported names may be re-imported by the - gss_import_name() routine, and the resulting internal name will also be - an MN. The gss_OID constant GSS_C_NT_EXPORT_NAME indentifies the - "export name" type, and the value of this constant is given in Appendix - A. Structurally, an exported name object consists of a header - containing an OID identifying the mechanism that authenticated the name, - and a trailer containing the name itself, where the syntax of the - trailer is defined by the individual mechanism specification. The - precise format of an export name is defined in the language-independent - GSSAPI specification [GSSAPI]. - - Note that the results obtained by using gss_compare_name() will in - general be different from those obtained by invoking - gss_canonicalize_name() and gss_export_name(), and then comparing the - exported names. The first series of operation determines whether two - (unauthenticated) names identify the same principal; the second whether - a particular mechanism would authenticate them as the same principal. - These two operations will in general give the same results only for MNs. - - The gss_name_t datatype should be implemented as a pointer type. To - allow the compiler to aid the application programmer by performing - type-checking, the use of (void *) is discouraged. A pointer to an - implementation-defined type is the preferred choice. - - Storage is allocated by routines that return gss_name_t values. A - procedure, gss_release_name, is provided to free storage associated with - an internal-form name. - - - - - - - - - Wray Document Expiration: 1 September 1997 [Page 16] - - - - - - - - INTERNET-DRAFT GSS-API V2 - C bindings March 1997 - - - - 5.11. Channel Bindings - - GSS-API supports the use of user-specified tags to identify a given - context to the peer application. These tags are intended to be used to - identify the particular communications channel that carries the context. - Channel bindings are communicated to the GSS-API using the following - structure: - - typedef struct gss_channel_bindings_struct { - OM_uint32 initiator_addrtype; - gss_buffer_desc initiator_address; - OM_uint32 acceptor_addrtype; - gss_buffer_desc acceptor_address; - gss_buffer_desc application_data; - } *gss_channel_bindings_t; - - The initiator_addrtype and acceptor_addrtype fields denote the type of - addresses contained in the initiator_address and acceptor_address - buffers. The address type should be one of the following: - - GSS_C_AF_UNSPEC Unspecified address type - GSS_C_AF_LOCAL Host-local address type - GSS_C_AF_INET Internet address type (e.g. IP) - GSS_C_AF_IMPLINK ARPAnet IMP address type - GSS_C_AF_PUP pup protocols (eg BSP) address type - GSS_C_AF_CHAOS MIT CHAOS protocol address type - GSS_C_AF_NS XEROX NS address type - GSS_C_AF_NBS nbs address type - GSS_C_AF_ECMA ECMA address type - GSS_C_AF_DATAKIT datakit protocols address type - GSS_C_AF_CCITT CCITT protocols - GSS_C_AF_SNA IBM SNA address type - GSS_C_AF_DECnet DECnet address type - GSS_C_AF_DLI Direct data link interface address type - GSS_C_AF_LAT LAT address type - GSS_C_AF_HYLINK NSC Hyperchannel address type - GSS_C_AF_APPLETALK AppleTalk address type - GSS_C_AF_BSC BISYNC 2780/3780 address type - GSS_C_AF_DSS Distributed system services address type - GSS_C_AF_OSI OSI TP4 address type - GSS_C_AF_X25 X25 - GSS_C_AF_NULLADDR No address specified - - Note that these symbols name address families rather than specific - addressing formats. For address families that contain several - alternative address forms, the initiator_address and acceptor_address - fields must contain sufficient information to determine which address - form is used. When not otherwise specified, addresses should be - specified in network byte-order (that is, native byte-ordering for the - address family). - - - - - Wray Document Expiration: 1 September 1997 [Page 17] - - - - - - - - INTERNET-DRAFT GSS-API V2 - C bindings March 1997 - - - - Conceptually, the GSS-API concatenates the initiator_addrtype, - initiator_address, acceptor_addrtype, acceptor_address and - application_data to form an octet string. The mechanism calculates a - MIC over this octet string, and binds the MIC to the context - establishment token emitted by gss_init_sec_context. The same bindings - are presented by the context acceptor to gss_accept_sec_context, and a - MIC is calculated in the same way. The calculated MIC is compared with - that found in the token, and if the MICs differ, gss_accept_sec_context - will return a GSS_S_BAD_BINDINGS error, and the context will not be - established. Some mechanisms may include the actual channel binding - data in the token (rather than just a MIC); applications should - therefore not use confidential data as channel-binding components. - Individual mechanisms may impose additional constraints on addresses and - address types that may appear in channel bindings. For example, a - mechanism may verify that the initiator_address field of the channel - bindings presented to gss_init_sec_context contains the correct network - address of the host system. Portable applications should therefore - ensure that they either provide correct information for the address - fields, or omit addressing information, specifying GSS_C_AF_NULLADDR as - the address-types. - - 5.12. Optional parameters - - Various parameters are described as optional. This means that they - follow a convention whereby a default value may be requested. The - following conventions are used for omitted parameters. These - conventions apply only to those parameters that are explicitly - documented as optional. - - 5.12.1. gss_buffer_t types - - Specify GSS_C_NO_BUFFER as a value. For an input parameter this - signifies that default behavior is requested, while for an output - parameter it indicates that the information that would be returned via - the parameter is not required by the application. - - 5.12.2. Integer types (input) - - Individual parameter documentation lists values to be used to indicate - default actions. - - 5.12.3. Integer types (output) - - Specify NULL as the value for the pointer. - - 5.12.4. Pointer types - - Specify NULL as the value. - - - - - - - Wray Document Expiration: 1 September 1997 [Page 18] - - - - - - - - INTERNET-DRAFT GSS-API V2 - C bindings March 1997 - - - - 5.12.5. Object IDs - - Specify GSS_C_NO_OID as the value. - - 5.12.6. Object ID Sets - - Specify GSS_C_NO_OID_SET as the value. - - 5.12.7. Channel Bindings - - Specify GSS_C_NO_CHANNEL_BINDINGS to indicate that channel bindings are - not to be used. - - - 6. ADDITIONAL CONTROLS - - This section discusses the optional services that a context initiator - may request of the GSS-API at context establishment. Each of these - services is requested by setting a flag in the req_flags input parameter - to gss_init_sec_context. - - The optional services currently defined are: - - Delegation - The (usually temporary) transfer of rights from initiator - to acceptor, enabling the acceptor to authenticate itself as an - agent of the initiator. - - Mutual Authentication - In addition to the initiator authenticating its - identity to the context acceptor, the context acceptor should also - authenticate itself to the initiator. - - Replay detection - In addition to providing message integrity services, - gss_get_mic and gss_wrap should include message numbering - information to enable gss_verify_mic and gss_unwrap to detect if a - message has been duplicated. - - Out-of-sequence detection - In addition to providing message integrity - services, gss_get_mic and gss_wrap should include message - sequencing information to enable gss_verify_mic and gss_unwrap to - detect if a message has been received out of sequence. - - Anonymous authentication - The establishment of the security context - should not reveal the initiator's identity to the context - acceptor. - - Any currently undefined bits within such flag arguments should be - ignored by GSS-API implementations when presented by an application, and - should be set to zero when returned to the application by the GSS-API - implementation. - - - - - - Wray Document Expiration: 1 September 1997 [Page 19] - - - - - - - - INTERNET-DRAFT GSS-API V2 - C bindings March 1997 - - - - Some mechanisms may not support all optional services, and some - mechanisms may only support some services in conjunction with others. - Both gss_init_sec_context and gss_accept_sec_context inform the - applications which services will be available from the context when the - establishment phase is complete, via the ret_flags output parameter. In - general, if the security mechanism is capable of providing a requested - service, it should do so, even if additional services must be enabled in - order to provide the requested service. If the mechanism is incapable - of providing a requested service, it should proceed without the service, - leaving the application to abort the context establishment process if it - considers the requested service to be mandatory. - - Some mechanisms may specify that support for some services is optional, - and that implementors of the mechanism need not provide it. This is - most commonly true of the confidentiality service, often because of - legal restrictions on the use of data-encryption, but may apply to any - of the services. Such mechanisms are required to send at least one - token from acceptor to initiator during context establishment when the - initiator indicates a desire to use such a service, so that the - initiating GSSAPI can correctly indicate whether the service is - supported by the acceptor's GSSAPI. - - 6.1. Delegation - - The GSS-API allows delegation to be controlled by the initiating - application via a boolean parameter to gss_init_sec_context(), the - routine that establishes a security context. Some mechanisms do not - support delegation, and for such mechanisms attempts by an application - to enable delegation are ignored. - - The acceptor of a security context for which the initiator enabled - delegation will receive (via the delegated_cred_handle parameter of - gss_accept_sec_context) a credential handle that contains the delegated - identity, and this credential handle may be used to initiate subsequent - GSSAPI security contexts as an agent or delegate of the initiator. If - the original initiator's identity is "A" and the delegate's identity is - "B", then, depending on the underlying mechanism, the identity embodied - by the delegated credential may be either "A" or "B acting for A". - - For many mechanisms that support delegation, a simple boolean does not - provide enough control. Examples of additional aspects of delegation - control that a mechanism might provide to an application are duration of - delegation, network addresses from which delegation is valid, and - constraints on the tasks that may be performed by a delegate. Such - controls are presently outside the scope of the GSS-API. GSS-API - implementations supporting mechanisms offering additional controls - should provide extension routines that allow these controls to be - exercised (perhaps by modifying the initiator's GSS-API credential prior - to its use in establishing a context). However, the simple delegation - control provided by GSS-API should always be able to over-ride other - mechanism-specific delegation controls - If the application instructs - - - - Wray Document Expiration: 1 September 1997 [Page 20] - - - - - - - - INTERNET-DRAFT GSS-API V2 - C bindings March 1997 - - - - gss_init_sec_context() that delegation is not desired, then the - implementation must not permit delegation to occur. This is an - exception to the general rule that a mechanism may enable services even - if they are not requested - delegation may only be provide at the - explicit request of the application. - - 6.2. Mutual authentication - - Usually, a context acceptor will require that a context initiator - authenticate itself so that the acceptor may make an access-control - decision prior to performing a service for the initiator. In some - cases, the initiator may also request that the acceptor authenticate - itself. GSS-API allows the initiating application to request this - mutual authentication service by setting a flag when calling - gss_init_sec_context. - - The initiating application is informed as to whether or not mutual - authentication is being requested of the context acceptor. Note that - some mechanisms may not support mutual authentication, and other - mechanisms may always perform mutual authentication, whether or not the - initiating application requests it. In particular, mutual - authentication my be required by some mechanisms in order to support - replay or out-of-sequence message detection, and for such mechanisms a - request for either of these services will automatically enable mutual - authentication. - - 6.3. Replay and out-of-sequence detection - - The GSS-API may provide detection of mis-ordered message once a security - context has been established. Protection may be applied to messages by - either application, by calling either gss_get_mic or gss_wrap, and - verified by the peer application by calling gss_verify_mic or - gss_unwrap. - - gss_get_mic calculates a cryptographic checksum of an application - message, and returns that checksum in a token. The application should - pass both the token and the message to the peer application, which - presents them to gss_verify_mic. - - gss_wrap calculates a cryptographic checksum of an application message, - and places both the checksum and the message inside a single token. The - application should pass the token to the peer application, which - presents it to gss_unwrap to extract the message and verify the - checksum. - - Either pair of routines may be capable of detecting out-of-sequence - message delivery, or duplication of messages. Details of such mis- - ordered messages are indicated through supplementary status bits in the - major status code returned by gss_verify_mic or gss_unwrap. The - relevant supplementary bits are: - - - - - Wray Document Expiration: 1 September 1997 [Page 21] - - - - - - - - INTERNET-DRAFT GSS-API V2 - C bindings March 1997 - - - - GSS_S_DUPLICATE_TOKEN - The token is a duplicate of one that has already - been received and processed. Contexts that do not claim to - provide replay detection may still set this bit if the duplicate - message is processed immediately after the original, with no - intervening messages. - - GSS_S_OLD_TOKEN - The token is too old to determine whether or not it is - a duplicate. Contexts supporting out-of-sequence detection but - not replay detection should always set this bit if - GSS_S_UNSEQ_TOKEN is set; contexts that support replay detection - should only set this bit if the token is so old that it cannot be - checked for duplication. - - GSS_S_UNSEQ_TOKEN - A later token has already been processed. - - GSS_S_GAP_TOKEN - An earlier token has not yet been received. - - A mechanism need not maintain a list of all tokens that have been - processed in order to support these status codes. A typical mechanism - might retain information about only the most recent "N" tokens - processed, allowing it to distinguish duplicates and missing tokens - within the most recent "N" messages; the receipt of a token older than - the most recent "N" would result in a GSS_S_OLD_TOKEN status. - - 6.4. Anonymous Authentication - - In certain situations, an application may wish to initiate the - authentication process to authenticate a peer, without revealing its own - identity. As an example, consider an application providing access to a - database containing medical information, and offering unrestricted - access to the service. A client of such a service might wish to - authenticate the service (in order to establish trust in any information - retrieved from it), but might not wish the service to be able to obtain - the client's identity (perhaps due to privacy concerns about the - specific inquiries, or perhaps simply to avoid being placed on mailing- - lists). - - In normal use of the GSS-API, the initiator's identity is made available - to the acceptor as a result of the context establishment process. - However, context initiators may request that their identity not be - revealed to the context acceptor. Many mechanisms do not support - anonymous authentication, and for such mechanisms the request will not - be honored. An authentication token will be still be generated, but the - application is always informed if a requested service is unavailable, - and has the option to abort context establishment if anonymity is valued - above the other security services that would require a context to be - established. - - In addition to informing the application that a context is established - anonymously (via the ret_flags outputs from gss_init_sec_context and - gss_accept_sec_context), the optional src_name output from - - - - Wray Document Expiration: 1 September 1997 [Page 22] - - - - - - - - INTERNET-DRAFT GSS-API V2 - C bindings March 1997 - - - - gss_accept_sec_context and gss_inquire_context will, for such contexts, - return a reserved internal-form name, defined by the implementation. - When presented to gss_display_name, this reserved internal-form name - will result in a printable name that is syntactically distinguishable - from any valid principal name supported by the implementation, - associated with a name-type object identifier with the value - GSS_C_NT_ANONYMOUS, whose value us given in Appendix A. The printable - form of an anonymous name should be chosen such that it implies - anonymity, since this name may appear in, for example, audit logs. For - example, the string "" might be a good choice, if no valid - printable names supported by the implementation can begin with "<" and - end with ">". - - 6.5. Confidentiality - - If a context supports the confidentiality service, gss_wrap may be used - to encrypt application messages. Messages are selectively encrypted, - under the control of the conf_req_flag input parameter to gss_wrap. - - 6.6. Inter-process context transfer - - GSSAPI V2 provides routines (gss_export_sec_context and - gss_import_sec_context) which allow a security context to be transferred - between processes on a single machine. The most common use for such a - feature is a client-server design where the server is implemented as a - single process that accepts incoming security contexts, which then - launches child processes to deal with the data on these contexts. In - such a design, the child processes must have access to the security - context data structure created within the parent by its call to - gss_accept_sec_context so that they can use per-message protection - services and delete the security context when the communication session - ends. - - Since the security context data structure is expected to contain - sequencing information, it is impractical in general to share a context - between processes. Thus GSSAPI provides a call (gss_export_sec_context) - that the process which currently owns the context can call to declare - that it has no intention to use the context subsequently, and to create - an inter-process token containing information needed by the adopting - process to successfully import the context. After successful completion - of this call, the original security context is made inaccessible to the - calling process by GSSAPI, and any context handles referring to this - context are no longer valid. The originating process transfers the - inter-process token to the adopting process, which passes it to - gss_import_sec_context, and a fresh gss_ctx_id_t is created such that it - is functionally identical to the original context. - - The inter-process token may contain sensitive data from the original - security context (including cryptographic keys). Applications using - inter-process tokens to transfer security contexts must take appropriate - steps to protect these tokens in transit. - - - - Wray Document Expiration: 1 September 1997 [Page 23] - - - - - - - - INTERNET-DRAFT GSS-API V2 - C bindings March 1997 - - - - Implementations are not required to support the inter-process transfer - of security contexts. The ability to transfer a security context is - indicated when the context is created, by gss_init_sec_context or - gss_accept_sec_context setting the GSS_C_TRANS_FLAG bit in their - ret_flags parameter. - - - 6.7. The use of incomplete contexts - - Some mechanisms may allow the per-message services to be used before the - context establishment process is complete. For example, a mechanism may - include sufficient information in its initial context-level token for - the context acceptor to immediately decode messages protected with - gss_wrap or gss_get_mic. For such a mechanism, the initiating - application need not wait until subsequent context-level tokens have - been sent and received before invoking the per-message protection - services. - - The ability of a context to provide per-message services in advance of - complete context establishment is indicated by the setting of the - GSS_C_PROT_READY_FLAG bit in the ret_flags parameter from - gss_init_sec_context and gss_accept_sec_context. Applications wishing - to use per-message protection services on partially-established contexts - should check this flag before attempting to invoke gss_wrap or - gss_get_mic. - - - - 7. GSS-API routine descriptions - - In addition to the explicit major status codes documented here, the code - GSS_S_FAILURE may be returned by any routine, indicating an - implementation-specific or mechanism-specific error condition, further - details of which are reported via the minor_status parameter. - - - - - - - - - - - - - - - - - - - - - Wray Document Expiration: 1 September 1997 [Page 24] - - - - - - - - INTERNET-DRAFT GSS-API V2 - C bindings March 1997 - - - - 7.1. gss_accept_sec_context - - OM_uint32 gss_accept_sec_context ( - OM_uint32 * minor_status, - gss_ctx_id_t * context_handle, - const gss_cred_id_t acceptor_cred_handle, - const gss_buffer_t input_token_buffer, - const gss_channel_bindings_t - input_chan_bindings, - const gss_name_t * src_name, - gss_OID * mech_type, - gss_buffer_t output_token, - OM_uint32 * ret_flags, - OM_uint32 * time_rec, - gss_cred_id_t * delegated_cred_handle) - - Purpose: - - Allows a remotely initiated security context between the application and - a remote peer to be established. The routine may return a output_token - which should be transferred to the peer application, where the peer - application will present it to gss_init_sec_context. If no token need - be sent, gss_accept_sec_context will indicate this by setting the length - field of the output_token argument to zero. To complete the context - establishment, one or more reply tokens may be required from the peer - application; if so, gss_accept_sec_context will return a status flag of - GSS_S_CONTINUE_NEEDED, in which case it should be called again when the - reply token is received from the peer application, passing the token to - gss_accept_sec_context via the input_token parameters. - - Portable applications should be constructed to use the token length and - return status to determine whether a token needs to be sent or waited - for. Thus a typical portable caller should always invoke - gss_accept_sec_context within a loop: - - gss_ctx_id_t context_hdl = GSS_C_NO_CONTEXT; - ... - - do { - receive_token_from_peer(input_token); - maj_stat = gss_accept_sec_context(&min_stat, - &context_hdl, - cred_hdl, - input_token, - input_bindings, - &client_name, - &mech_type, - output_token, - &ret_flags, - &time_rec, - &deleg_cred); - - - - Wray Document Expiration: 1 September 1997 [Page 25] - - - - - - - - INTERNET-DRAFT GSS-API V2 - C bindings March 1997 - - - - if (GSS_ERROR(maj_stat)) { - report_error(maj_stat, min_stat); - }; - if (output_token->length != 0) { - send_token_to_peer(output_token); - gss_release_buffer(&min_stat, - output_token) - }; - if (GSS_ERROR(maj_stat)) { - if (context_hdl != GSS_C_NO_CONTEXT) - gss_delete_sec_context(&min_stat, - &context_hdl, - GSS_C_NO_BUFFER); - break; - }; - } while (maj_stat & GSS_S_CONTINUE_NEEDED); - - - Whenever the routine returns a major status that includes the value - GSS_S_CONTINUE_NEEDED, the context is not fully established and the - following restrictions apply to the output parameters: - - (a) The value returned via the time_rec parameter is undefined - - (b) Unless the accompanying ret_flags parameter contains the bit - GSS_C_PROT_READY_FLAG, indicating that per-message services may be - applied in advance of a successful completion status, the value - returned via the mech_type parameter may be undefined until the - routine returns a major status value of GSS_S_COMPLETE. - - (c) The values of the GSS_C_DELEG_FLAG, GSS_C_MUTUAL_FLAG, - GSS_C_REPLAY_FLAG, GSS_C_SEQUENCE_FLAG, GSS_C_CONF_FLAG, - GSS_C_INTEG_FLAG and GSS_C_ANON_FLAG bits returned via the - ret_flags parameter should contain the values that the - implementation expects would be valid if context establishment - were to succeed. - - The values of the GSS_C_PROT_READY_FLAG and GSS_C_TRANS_FLAG bits - within ret_flags should indicate the actual state at the time - gss_accept_sec_context returns, whether or not the context is - fully established. - - Although this requires that GSSAPI implementations set the - GSS_C_PROT_READY_FLAG in the final ret_flags returned to a caller - (i.e. when accompanied by a GSS_S_COMPLETE status code), - applications should not rely on this behavior as the flag was not - defined in Version 1 of the GSSAPI. Instead, applications should - be prepared to use per-message services after a successful context - establishment, according to the GSS_C_INTEG_FLAG and - GSS_C_CONF_FLAG values. - - - - - Wray Document Expiration: 1 September 1997 [Page 26] - - - - - - - - INTERNET-DRAFT GSS-API V2 - C bindings March 1997 - - - - All other bits within the ret_flags argument should be set to - zero. - - - While the routine returns GSS_S_CONTINUE_NEEDED, the values returned via - the ret_flags argument indicate the services that the implementation - expects to be available from the established context. - - If the initial call of gss_accept_sec_context() fails, the - implementation should not create a context object, and should leave the - value of the context_handle parameter set to GSS_C_NO_CONTEXT to - indicate this. In the event of a failure on a subsequent call, the - implementation is permitted to delete the "half-built" security context - (in which case it should set the context_handle parameter to - GSS_C_NO_CONTEXT), but the preferred behavior is to leave the security - context (and the context_handle parameter) untouched for the application - to delete (using gss_delete_sec_context). - - Parameters: - - context_handle gss_ctx_id_t, read/modify - context handle for new context. Supply - GSS_C_NO_CONTEXT for first call; use value - returned in subsequent calls. Once - gss_accept_sec_context() has returned a value - via this parameter, resources have been assigned - to the corresponding context, and must be - freed by the application after use with a call - to gss_delete_sec_context(). - - - acceptor_cred_handle gss_cred_id_t, read - Credential handle claimed by context acceptor. - Specify GSS_C_NO_CREDENTIAL to accept the - context as a default principal. If - GSS_C_NO_CREDENTIAL is specified, but no - default acceptor principal is defined, - GSS_S_NO_CRED will be returned. - - input_token_buffer buffer, opaque, read - token obtained from remote application. - - input_chan_bindings channel bindings, read, optional - Application-specified bindings. Allows - application to securely bind channel - identification information to the security - context. If channel bindings are not - used, specify GSS_C_NO_CHANNEL_BINDINGS. - - src_name gss_name_t, modify, optional - Authenticated name of context initiator. - - - - Wray Document Expiration: 1 September 1997 [Page 27] - - - - - - - - INTERNET-DRAFT GSS-API V2 - C bindings March 1997 - - - - After use, this name should be deallocated by - passing it to gss_release_name(). If not - required, specify NULL. - - mech_type Object ID, modify, optional - Security mechanism used. The returned - OID value will be a pointer into static - storage, and should be treated as read-only - by the caller (in particular, it does not - need to be freed). If not required, specify - NULL. - - output_token buffer, opaque, modify - Token to be passed to peer application. If the - length field of the returned token buffer is 0, - then no token need be passed to the peer - application. If a non-zero length field is - returned, the associated storage must be freed - after use by the application with a call to - gss_release_buffer(). - - ret_flags bit-mask, modify, optional - Contains various independent flags, each of - which indicates that the context supports a - specific service option. If not needed, - specify NULL. Symbolic names are - provided for each flag, and the symbolic names - corresponding to the required flags - should be logically-ANDed with the ret_flags - value to test whether a given option is - supported by the context. The flags are: - GSS_C_DELEG_FLAG - True - Delegated credentials are available - via the delegated_cred_handle - parameter - False - No credentials were delegated - GSS_C_MUTUAL_FLAG - True - Remote peer asked for mutual - authentication - False - Remote peer did not ask for mutual - authentication - GSS_C_REPLAY_FLAG - True - replay of protected messages - will be detected - False - replayed messages will not be - detected - GSS_C_SEQUENCE_FLAG - True - out-of-sequence protected - messages will be detected - False - out-of-sequence messages will not - be detected - - - - Wray Document Expiration: 1 September 1997 [Page 28] - - - - - - - - INTERNET-DRAFT GSS-API V2 - C bindings March 1997 - - - - GSS_C_CONF_FLAG - True - Confidentiality service may be invoked - by calling the gss_wrap routine - False - No confidentiality service (via - gss_wrap) available. gss_wrap will - provide message encapsulation, - data-origin authentication and - integrity services only. - GSS_C_INTEG_FLAG - True - Integrity service may be invoked by - calling either gss_get_mic or gss_wrap - routines. - False - Per-message integrity service - unavailable. - GSS_C_ANON_FLAG - True - The initiator does not wish to - be authenticated; the src_name - parameter (if requested) contains - an anonymous internal name. - False - The initiator has been - authenticated normally. - GSS_C_PROT_READY_FLAG - True - Protection services (as specified - by the states of the GSS_C_CONF_FLAG - and GSS_C_INTEG_FLAG) are available - if the accompanying major status return - value is either GSS_S_COMPLETE or - GSS_S_CONTINUE_NEEDED. - False - Protection services (as specified - by the states of the GSS_C_CONF_FLAG - and GSS_C_INTEG_FLAG) are available - only if the accompanying major status - return value is GSS_S_COMPLETE. - GSS_C_TRANS_FLAG - True - The resultant security context may - be transferred to other processes via - a call to gss_export_sec_context(). - False - The security context is not - transferrable. - All other bits should be set to zero. - - time_rec Integer, modify, optional - number of seconds for which the context - will remain valid. Specify NULL if not required. - - delegated_cred_handle - gss_cred_id_t, modify, optional - credential handle for credentials received from - context initiator. Only valid if deleg_flag in - ret_flags is true, in which case an explicit - - - - Wray Document Expiration: 1 September 1997 [Page 29] - - - - - - - - INTERNET-DRAFT GSS-API V2 - C bindings March 1997 - - - - credential handle (i.e. not GSS_C_NO_CREDENTIAL) - will be returned; if deleg_flag is false, - gss_accept_context() will set this parameter to - GSS_C_NO_CREDENTIAL. If a credential handle is - returned, the associated resources must be released - by the application after use with a call to - gss_release_cred(). Specify NULL if not required. - - - minor_status Integer, modify - Mechanism specific status code. - - - Function value: GSS status code - - GSS_S_COMPLETE Successful completion - - GSS_S_CONTINUE_NEEDED Indicates that a token from the peer application - is required to complete the context, and that - gss_accept_sec_context must be called again with that - token. - - GSS_S_DEFECTIVE_TOKEN Indicates that consistency checks performed on the - input_token failed. - - GSS_S_DEFECTIVE_CREDENTIAL Indicates that consistency checks performed - on the credential failed. - - GSS_S_NO_CRED The supplied credentials were not valid for context - acceptance, or the credential handle did not reference - any credentials. - - GSS_S_CREDENTIALS_EXPIRED The referenced credentials have expired. - - GSS_S_BAD_BINDINGS The input_token contains different channel bindings - to those specified via the input_chan_bindings - parameter. - - GSS_S_NO_CONTEXT Indicates that the supplied context handle did not - refer to a valid context. - - GSS_S_BAD_SIG The input_token contains an invalid MIC. - - GSS_S_OLD_TOKEN The input_token was too old. This is a fatal error - during context establishment. - - GSS_S_DUPLICATE_TOKEN The input_token is valid, but is a duplicate of a - token already processed. This is a fatal error during - context establishment. - - - - - - Wray Document Expiration: 1 September 1997 [Page 30] - - - - - - - - INTERNET-DRAFT GSS-API V2 - C bindings March 1997 - - - - GSS_S_BAD_MECH The received token specified a mechanism that is not - supported by the implementation or the provided - credential. - - - - - - - - 7.2. gss_acquire_cred - - - OM_uint32 gss_acquire_cred ( - OM_uint32 * minor_status, - const gss_name_t desired_name, - OM_uint32 time_req, - const gss_OID_set desired_mechs, - gss_cred_usage_t cred_usage, - gss_cred_id_t * output_cred_handle, - gss_OID_set * actual_mechs, - OM_uint32 * time_rec) - - Purpose: - - Allows an application to acquire a handle for a pre-existing credential - by name. GSS-API implementations must impose a local access-control - policy on callers of this routine to prevent unauthorized callers from - acquiring credentials to which they are not entitled. This routine is - not intended to provide a ``login to the network'' function, as such a - function would involve the creation of new credentials rather than - merely acquiring a handle to existing credentials. Such functions, if - required, should be defined in implementation-specific extensions to the - API. - - If desired_name is GSS_C_NO_NAME, the call is interpreted as a request - for a credential handle that will invoke default behavior when passed to - gss_init_sec_context() (if cred_usage is GSS_C_INITIATE or GSS_C_BOTH) - or gss_accept_sec_context() (if cred_usage is GSS_C_ACCEPT or - GSS_C_BOTH). - - This routine is expected to be used primarily by context acceptors, - since implementations are likely to provide mechanism-specific ways of - obtaining GSS-API initiator credentials from the system login process. - Some implementations may therefore not support the acquisition of - GSS_C_INITIATE or GSS_C_BOTH credentials via gss_acquire_cred for any - name other than an empty name. - - If credential acquisition is time-consuming for a mechanism, the - mechanism may chooses to delay the actual acquisition until the - credential is required (e.g. by gss_init_sec_context or - - - - Wray Document Expiration: 1 September 1997 [Page 31] - - - - - - - - INTERNET-DRAFT GSS-API V2 - C bindings March 1997 - - - - gss_accept_sec_context). Such mechanism-specific implementation - decisions should be invisible to the calling application; thus a call of - gss_inquire_cred immediately following the call of gss_acquire_cred must - return valid credential data, and may therefore incur the overhead of a - deferred credential acquisition. - - Parameters: - - desired_name gss_name_t, read - Name of principal whose credential - should be acquired - - time_req Integer, read, optional - number of seconds that credentials - should remain valid. Specify GSS_C_INDEFINITE - to request that the credentials have the maximum - permitted lifetime. - - desired_mechs Set of Object IDs, read, optional - set of underlying security mechanisms that - may be used. GSS_C_NO_OID_SET may be used - to obtain an implementation-specific default. - - cred_usage gss_cred_usage_t, read - GSS_C_BOTH - Credentials may be used - either to initiate or accept - security contexts. - GSS_C_INITIATE - Credentials will only be - used to initiate security - contexts. - GSS_C_ACCEPT - Credentials will only be used to - accept security contexts. - - output_cred_handle gss_cred_id_t, modify - The returned credential handle. Resources - associated with this credential handle must - be released by the application after use - with a call to gss_release_cred(). - - actual_mechs Set of Object IDs, modify, optional - The set of mechanisms for which the - credential is valid. Storage associated - with the returned OID-set must be released by - the application after use with a call to - gss_release_oid_set(). Specify NULL if not - required. - - time_rec Integer, modify, optional - Actual number of seconds for which the - returned credentials will remain valid. If the - implementation does not support expiration of - - - - Wray Document Expiration: 1 September 1997 [Page 32] - - - - - - - - INTERNET-DRAFT GSS-API V2 - C bindings March 1997 - - - - credentials, the value GSS_C_INDEFINITE will - be returned. Specify NULL if not required - - minor_status Integer, modify - Mechanism specific status code. - - Function value: GSS status code - - GSS_S_COMPLETE Successful completion - - GSS_S_BAD_MECH Unavailable mechanism requested - - GSS_S_BAD_NAMETYPE Type contained within desired_name parameter is not - supported - - GSS_S_BAD_NAME Value supplied for desired_name parameter is ill- - formed. - - GSS_S_CREDENTIALS_EXPIRED The credentials could not be acquired because - they have expired. - - GSS_S_NO_CRED No credentials were found for the specified name. - - - - - - - - 7.3. gss_add_cred - - - OM_uint32 gss_add_cred ( - OM_uint32 * minor_status, - const gss_cred_id_t input_cred_handle, - const gss_name_t desired_name, - const gss_OID desired_mech, - gss_cred_usage_t cred_usage, - OM_uint32 initiator_time_req, - OM_uint32 acceptor_time_req, - gss_cred_id_t * output_cred_handle, - gss_OID_set * actual_mechs, - OM_uint32 * initiator_time_rec, - OM_uint32 * acceptor_time_rec) - - - - - - - - - - - Wray Document Expiration: 1 September 1997 [Page 33] - - - - - - - - INTERNET-DRAFT GSS-API V2 - C bindings March 1997 - - - - Purpose: - - Adds a credential-element to a credential. The credential-element is - identified by the name of the principal to which it refers. GSSAPI - implementations must impose a local access-control policy on callers of - this routine to prevent unauthorized callers from acquiring credential- - elements to which they are not entitled. This routine is not intended to - provide a ``login to the network'' function, as such a function would - involve the creation of new mechanism-specific authentication data, - rather than merely acquiring a GSSAPI handle to existing data. Such - functions, if required, should be defined in implementation-specific - extensions to the API. - - This routine is expected to be used primarily by context acceptors, - since implementations are likely to provide mechanism-specific ways of - obtaining GSS-API initiator credentials from the system login process. - Some implementations may therefore not support the acquisition of - GSS_C_INITIATE or GSS_C_BOTH credentials via gss_acquire_cred. - - If credential acquisition is time-consuming for a mechanism, the - mechanism may chooses to delay the actual acquisition until the - credential is required (e.g. by gss_init_sec_context or - gss_accept_sec_context). Such mechanism-specific implementation - decisions should be invisible to the calling application; thus a call of - gss_inquire_cred immediately following the call of gss_acquire_cred must - return valid credential data, and may therefore incur the overhead of a - deferred credential acquisition. - - This routine can be used to either create a new credential containing - all credential-elements of the original in addition to the newly-acquire - credential-element, or to add the new credential-element to an existing - credential. If NULL is specified for the output_cred_handle parameter - argument, the new credential-element will be added to the credential - identified by input_cred_handle; if a valid pointer is specified for the - output_cred_handle parameter, a new credential and handle will be - created. - - If GSS_C_NO_CREDENTIAL is specified as the input_cred_handle, the - gss_add_cred will create its output_cred_handle based on default - behavior. That is, the call will have the same effect as if the - application had first made a call to gss_acquire_cred(), specifying the - same usage and passing GSS_C_NO_NAME as the desired_name parameter to - obtain an explicit credential handle embodying default behavior, passed - this credential handle to gss_add_cred(), and finally called - gss_release_cred() on the first credential handle. - - If GSS_C_NO_CREDENTIAL is specified as the input_cred_handle parameter, - a non-NULL output_cred_handle must be supplied. - - Parameters: - - - - - Wray Document Expiration: 1 September 1997 [Page 34] - - - - - - - - INTERNET-DRAFT GSS-API V2 - C bindings March 1997 - - - - minor_status Integer, modify - Mechanism specific status code. - - input_cred_handle gss_cred_id_t, read, optional - The credential to which a credential-element - will be added. If GSS_C_NO_CREDENTIAL is - specified, the routine will create the new - credential based on default behavior (see - description above). Note that, while the - credential-handle is not modified by - gss_add_cred(), the underlying credential - will be modified if output_credential_handle - is NULL. - - desired_name gss_name_t, read. - Name of principal whose credential - should be acquired. - - desired_mech Object ID, read - Underlying security mechanism with which the - credential may be used. - - cred_usage gss_cred_usage_t, read - GSS_C_BOTH - Credential may be used - either to initiate or accept - security contexts. - GSS_C_INITIATE - Credential will only be - used to initiate security - contexts. - GSS_C_ACCEPT - Credential will only be used to - accept security contexts. - - initiator_time_req Integer, read, optional - number of seconds that the credential - should remain valid for initiating security - contexts. This argument is ignored if the - created credentials are of type GSS_C_ACCEPT. - Specify GSS_C_INDEFINITE to request that the - credentials have the maximum permitted initiator - lifetime. - - acceptor_time_req Integer, read, optional - number of seconds that the credential - should remain valid for accepting security - contexts. This argument is ignored if the - created credentials are of type GSS_C_INITIATE. - Specify GSS_C_INDEFINITE to request that the - credentials have the maximum permitted initiator - lifetime. - - - - - Wray Document Expiration: 1 September 1997 [Page 35] - - - - - - - - INTERNET-DRAFT GSS-API V2 - C bindings March 1997 - - - - output_cred_handle gss_cred_id_t, modify, optional - The returned credential handle, containing - the new credential-element and all the - credential-elements from input_cred_handle. - If a valid pointer to a gss_cred_id_t is - supplied for this parameter, gss_add_cred - creates a new credential handle containing all - credential-elements from the input_cred_handle - and the newly acquired credential-element; if - NULL is specified for this parameter, the newly - acquired credential-element will be added - to the credential identified by input_cred_handle. - The resources associated with any credential - handle returned via this parameter must be - released by the application after use with a - call to gss_release_cred(). - - actual_mechs Set of Object IDs, modify, optional - The complete set of mechanisms for which - the new credential is valid. Storage for - the returned OID-set must be freed by the - application after use with a call to - gss_release_oid_set(). Specify NULL if - not required. - - initiator_time_rec Integer, modify, optional - Actual number of seconds for which the - returned credentials will remain valid for - initiating contexts using the specified - mechanism. If the implementation or mechanism - does not support expiration of credentials, the - value GSS_C_INDEFINITE will be returned. Specify - NULL if not required - - acceptor_time_rec Integer, modify, optional - Actual number of seconds for which the - returned credentials will remain valid for - accepting security contexts using the specified - mechanism. If the implementation or mechanism - does not support expiration of credentials, the - value GSS_C_INDEFINITE will be returned. Specify - NULL if not required - - Function value: GSS status code - - GSS_S_COMPLETE Successful completion - - GSS_S_BAD_MECH Unavailable mechanism requested - - GSS_S_BAD_NAMETYPE Type contained within desired_name parameter is not - supported - - - - - Wray Document Expiration: 1 September 1997 [Page 36] - - - - - - - - INTERNET-DRAFT GSS-API V2 - C bindings March 1997 - - - - GSS_S_BAD_NAME Value supplied for desired_name parameter is ill- - formed. - - GSS_S_DUPLICATE_ELEMENT The credential already contains an element for - the requested mechanism with overlapping usage and - validity period. - - GSS_S_CREDENTIALS_EXPIRED The required credentials could not be added - because they have expired. - - GSS_S_NO_CRED No credentials were found for the specified name. - - - - - - - - 7.4. gss_add_oid_set_member - - OM_uint32 gss_add_oid_set_member ( - OM_uint32 * minor_status, - const gss_OID member_oid, - gss_OID_set * oid_set) - - Purpose: - - Add an Object Identifier to an Object Identifier set. This routine is - intended for use in conjunction with gss_create_empty_oid_set when - constructing a set of mechanism OIDs for input to gss_acquire_cred. - - The oid_set parameter must refer to an OID-set that was created by - GSSAPI (e.g. a set returned by gss_create_empty_oid_set()). GSSAPI - creates a copy of the member_oid and inserts this copy into the set, - expanding the storage allocated to the OID-set's elements array if - necessary. The routine may add the new member OID anywhere within the - elements array, and implementations should verify that the new - member_oid is not already contained within the elements array. - - Parameters: - - minor_status Integer, modify - Mechanism specific status code - - member_oid Object ID, read - The object identifier to copied into - the set. - - oid_set Set of Object ID, modify - The set in which the object identifier - should be inserted. - - - - Wray Document Expiration: 1 September 1997 [Page 37] - - - - - - - - INTERNET-DRAFT GSS-API V2 - C bindings March 1997 - - - - Function value: GSS status code - - GSS_S_COMPLETE Successful completion - - - - - - - - 7.5. gss_canonicalize_name - - OM_uint32 gss_canonicalize_name ( - OM_uint32 * minor_status, - const gss_name_t input_name, - const gss_OID mech_type, - gss_name_t * output_name) - - Purpose: - - Generate a canonical mechanism name (MN) from an arbitrary internal - name. The mechanism name is the name that would be returned to a - context acceptor on successful authentication of a context where the - initiator used the input_name in a successful call to gss_acquire_cred, - specifying an OID set containing as its only member, - followed by a call to gss_init_sec_context, specifying as - the authentication mechanism. - - Parameters: - - minor_status Integer, modify - Mechanism specific status code - - input_name gss_name_t, read - The name for which a canonical form is - desired - - mech_type Object ID, read - The authentication mechanism for which the - canonical form of the name is desired. The - desired mechanism must be specified explicitly; - no default is provided. - - output_name gss_name_t, modify - The resultant canonical name. Storage - associated with this name must be freed by - the application after use with a call to - gss_release_name(). - - Function value: GSS status code - - - - - Wray Document Expiration: 1 September 1997 [Page 38] - - - - - - - - INTERNET-DRAFT GSS-API V2 - C bindings March 1997 - - - - GSS_S_COMPLETE Successful completion. - - GSS_S_BAD_MECH The identified mechanism is not supported. - - GSS_S_BAD_NAMETYPE The provided internal name contains no elements that - could be processed by the sepcified mechanism. - - GSS_S_BAD_NAME The provided internal name was ill-formed. - - - - - - - - 7.6. gss_compare_name - - OM_uint32 gss_compare_name ( - OM_uint32 * minor_status, - const gss_name_t name1, - const gss_name_t name2, - int * name_equal) - - Purpose: - - Allows an application to compare two internal-form names to determine - whether they refer to the same entity. - - If either name presented to gss_compare_name denotes an anonymous - principal, the routines should indicate that the two names do not refer - to the same identity. - - Parameters: - - minor_status Integer, modify - Mechanism specific status code. - - name1 gss_name_t, read - internal-form name - - name2 gss_name_t, read - internal-form name - - name_equal boolean, modify - non-zero - names refer to same entity - zero - names refer to different entities - (strictly, the names are not known - to refer to the same identity). - - Function value: GSS status code - - - - - Wray Document Expiration: 1 September 1997 [Page 39] - - - - - - - - INTERNET-DRAFT GSS-API V2 - C bindings March 1997 - - - - GSS_S_COMPLETE Successful completion - - GSS_S_BAD_NAMETYPE The two names were of incomparable types. - - GSS_S_BAD_NAME One or both of name1 or name2 was ill-formed - - - - - - - - 7.7. gss_context_time - - OM_uint32 gss_context_time ( - OM_uint32 * minor_status, - const gss_ctx_id_t context_handle, - OM_uint32 * time_rec) - - Purpose: - - Determines the number of seconds for which the specified context will - remain valid. - - Parameters: - - minor_status Integer, modify - Implementation specific status code. - - context_handle gss_ctx_id_t, read - Identifies the context to be interrogated. - - time_rec Integer, modify - Number of seconds that the context will remain - valid. If the context has already expired, - zero will be returned. - - Function value: GSS status code - - GSS_S_COMPLETE Successful completion - - GSS_S_CONTEXT_EXPIRED The context has already expired - - GSS_S_NO_CONTEXT The context_handle parameter did not identify a valid - context - - - - - - - - - - Wray Document Expiration: 1 September 1997 [Page 40] - - - - - - - - INTERNET-DRAFT GSS-API V2 - C bindings March 1997 - - - - 7.8. gss_create_empty_oid_set - - OM_uint32 gss_create_empty_oid_set ( - OM_uint32 * minor_status, - gss_OID_set * oid_set) - - Purpose: - - Create an object-identifier set containing no object identifiers, to - which members may be subsequently added using the - gss_add_oid_set_member() routine. These routines are intended to be - used to construct sets of mechanism object identifiers, for input to - gss_acquire_cred. - - Parameters: - - minor_status Integer, modify - Mechanism specific status code - - oid_set Set of Object IDs, modify - The empty object identifier set. - The routine will allocate the - gss_OID_set_desc object, which the - application must free after use with - a call to gss_release_oid_set(). - - Function value: GSS status code - - GSS_S_COMPLETE Successful completion - - - - - - - - 7.9. gss_delete_sec_context - - OM_uint32 gss_delete_sec_context ( - OM_uint32 * minor_status, - gss_ctx_id_t * context_handle, - gss_buffer_t output_token) - - Purpose: - - Delete a security context. gss_delete_sec_context will delete the local - data structures associated with the specified security context, and may - generate an output_token, which when passed to the peer - gss_process_context_token will instruct it to do likewise. If no token - is required by the mechanism, the GSS-API should set the length field of - the output_token (if provided) to zero. No further security services - - - - Wray Document Expiration: 1 September 1997 [Page 41] - - - - - - - - INTERNET-DRAFT GSS-API V2 - C bindings March 1997 - - - - may be obtained using the context specified by context_handle. - - In addition to deleting established security contexts, - gss_delete_sec_context must also be able to delete "half-built" security - contexts resulting from an incomplete sequence of - gss_init_sec_context()/gss_accept_sec_context() calls. - - The output_token parameter is retained for compatibility with version 1 - of the GSS-API. It is recommended that both peer applications invoke - gss_delete_sec_context passing the value GSS_C_NO_BUFFER for the - output_token parameter, indicating that no token is required, and that - gss_delete_sec_context should simply delete local context data - structures. If the application does pass a valid buffer to - gss_delete_sec_context, mechanisms are encouraged to return a zero- - length token, indicating that no peer action is necessary, and that no - token should be transferred by the application. - - Parameters: - - minor_status Integer, modify - Mechanism specific status code. - - context_handle gss_ctx_id_t, modify - context handle identifying context to delete. - After deleting the context, the GSSAPI will set - this context handle to GSS_C_NO_CONTEXT. - - output_token buffer, opaque, modify, optional - token to be sent to remote application to - instruct it to also delete the context. It - is recommended that applications specify - GSS_C_NO_BUFFER for this parameter, requesting - local deletion only. If a buffer parameter is - provided by the application, the mechanism may - return a token in it; mechanisms that implement - only local deletion should set the length field of - this token to zero to indicate to the application - that no token is to be sent to the peer. - - Function value: GSS status code - - GSS_S_COMPLETE Successful completion - - GSS_S_NO_CONTEXT No valid context was supplied - - - - - - - - - - - Wray Document Expiration: 1 September 1997 [Page 42] - - - - - - - - INTERNET-DRAFT GSS-API V2 - C bindings March 1997 - - - - 7.10. gss_display_name - - OM_uint32 gss_display_name ( - OM_uint32 * minor_status, - const gss_name_t input_name, - gss_buffer_t output_name_buffer, - gss_OID * output_name_type) - - Purpose: - - Allows an application to obtain a textual representation of an opaque - internal-form name for display purposes. The syntax of a printable - name is defined by the GSS-API implementation. - - If input_name denotes an anonymous principal, the implementation should - return the gss_OID value GSS_C_NT_ANONYMOUS as the output_name_type, and - a textual name that is syntactically distinct from all valid supported - printable names in output_name_buffer. - - Parameters: - - minor_status Integer, modify - Mechanism specific status code. - - input_name gss_name_t, read - name to be displayed - - output_name_buffer buffer, character-string, modify - buffer to receive textual name string. - The application must free storage associated - with this name after use with a call to - gss_release_buffer(). - - output_name_type Object ID, modify, optional - The type of the returned name. The returned - gss_OID will be a pointer into static storage, - and should be treated as read-only by the caller - (in particular, it does not need to be freed). - Specify NULL if not required. - - Function value: GSS status code - - GSS_S_COMPLETE Successful completion - - GSS_S_BAD_NAME input_name was ill-formed - - - - - - - - - - Wray Document Expiration: 1 September 1997 [Page 43] - - - - - - - - INTERNET-DRAFT GSS-API V2 - C bindings March 1997 - - - - 7.11. gss_display_status - - OM_uint32 gss_display_status ( - OM_uint32 * minor_status, - OM_uint32 status_value, - int status_type, - const gss_OID mech_type, - OM_uint32 * message_context, - gss_buffer_t status_string) - - Purpose: - - Allows an application to obtain a textual representation of a GSS-API - status code, for display to the user or for logging purposes. Since - some status values may indicate multiple conditions, applications may - need to call gss_display_status multiple times, each call generating a - single text string. The message_context parameter is used by - gss_acquire_cred to store state information about which error messages - have already been extracted from a given status_value; message_context - must be initialized to 0 by the application prior to the first call, and - gss_display_status will return a non-zero value in this parameter if - there are further messages to extract. The message_context parameter - contains all state information required by gss_display_status in order - to extract further messages from the status_value; even when a non-zero - value is returned in this parameter, the application is not required to - call gss_display_status again unless subsequent messages are desired. - The following code extracts all messages from a given status code and - prints them to stderr: - - - OM_uint32 message_context; - OM_uint32 status_code; - OM_uint32 maj_status; - OM_uint32 min_status; - gss_buffer_desc status_string; - - ... - - message_context = 0; - - do { - - maj_status = gss_display_status (&min_status, - status_code, - GSS_C_GSS_CODE, - GSS_C_NO_OID, - &message_context, - &status_string) - - fprintf(stderr, - "%.*s\n", - - - - Wray Document Expiration: 1 September 1997 [Page 44] - - - - - - - - INTERNET-DRAFT GSS-API V2 - C bindings March 1997 - - - - status_string.length, - status_string.value); - - gss_release_buffer(&min_status, - &status_string); - - } while (message_context != 0); - - - - Parameters: - - minor_status Integer, modify - Mechanism specific status code. - - status_value Integer, read - Status value to be converted - - status_type Integer, read - GSS_C_GSS_CODE - status_value is a GSS status - code - GSS_C_MECH_CODE - status_value is a mechanism - status code - - mech_type Object ID, read, optional - Underlying mechanism (used to interpret a - minor status value) Supply GSS_C_NO_OID to - obtain the system default. - - message_context Integer, read/modify - Should be initialized to zero by the - application prior to the first call. - On return from gss_display_status(), - a non-zero status_value parameter indicates - that additional messages may be extracted - from the status code via subsequent calls - to gss_display_status(), passing the same - status_value, status_type, mech_type, and - message_context parameters. - - status_string buffer, character string, modify - textual interpretation of the status_value. - Storage associated with this parameter must - be freed by the application after use with - a call to gss_release_buffer(). - - Function value: GSS status code - - GSS_S_COMPLETE Successful completion - - - - - - Wray Document Expiration: 1 September 1997 [Page 45] - - - - - - - - INTERNET-DRAFT GSS-API V2 - C bindings March 1997 - - - - GSS_S_BAD_MECH Indicates that translation in accordance with an - unsupported mechanism type was requested - - GSS_S_BAD_STATUS The status value was not recognized, or the status - type was neither GSS_C_GSS_CODE nor GSS_C_MECH_CODE. - - - - - - - - 7.12. gss_duplicate_name - - OM_uint32 gss_duplicate_name ( - OM_uint32 * minor_status, - const gss_name_t src_name, - gss_name_t * dest_name) - - Purpose: - - Create an exact duplicate of the existing internal name src_name. The - new dest_name will be independent of src_name (i.e. src_name and - dest_name must both be released, and the release of one shall not affect - the validity of the other). - - Parameters: - - minor_status Integer, modify - Mechanism specific status code. - - src_name gss_name_t, read - internal name to be duplicated. - - dest_name gss_name_t, modify - The resultant copy of . - Storage associated with this name must - be freed by the application after use - with a call to gss_release_name(). - - Function value: GSS status code - - GSS_S_COMPLETE Successful completion - - GSS_S_BAD_NAME The src_name parameter was ill-formed. - - - - - - - - - - Wray Document Expiration: 1 September 1997 [Page 46] - - - - - - - - INTERNET-DRAFT GSS-API V2 - C bindings March 1997 - - - - 7.13. gss_export_name - - OM_uint32 gss_export_name ( - OM_uint32 * minor_status, - const gss_name_t input_name, - gss_buffer_t exported_name) - - Purpose: - - To produce a canonical contiguous string representation of a mechanism - name (MN), suitable for direct comparison (e.g. with memcmp) for use in - authorization functions (e.g. matching entries in an access-control - list). - - The parameter must specify a valid MN (i.e. an internal - name generated by gss_accept_sec_context or by gss_canonicalize_name). - - - Parameters: - - minor_status Integer, modify - Mechanism specific status code - - input_name gss_name_t, read - The MN to be exported - - exported_name gss_buffer_t, octet-string, modify - The canonical contiguous string form of - . Storage associated with - this string must freed by the application - after use with gss_release_buffer(). - - Function value: GSS status code - - GSS_S_COMPLETE Successful completion - - GSS_S_NAME_NOT_MN The provided internal name was not a mechanism name. - - GSS_S_BAD_NAME The provide internal name was ill-formed. - - GSS_S_BAD_NAMETYPE The internal name was of a type not supported by the - GSSAPI implementation. - - - - - - - - - - - - - Wray Document Expiration: 1 September 1997 [Page 47] - - - - - - - - INTERNET-DRAFT GSS-API V2 - C bindings March 1997 - - - - 7.14. gss_export_sec_context - - OM_uint32 gss_export_sec_context ( - OM_uint32 * minor_status, - gss_ctx_id_t * context_handle, - gss_buffer_t interprocess_token) - - Purpose: - - Provided to support the sharing of work between multiple processes. - This routine will typically be used by the context-acceptor, in an - application where a single process receives incoming connection requests - and accepts security contexts over them, then passes the established - context to one or more other processes for message exchange. - gss_export_sec_context() deactivates the security context for the - calling process and creates an interprocess token which, when passed to - gss_import_sec_context in another process, will re-activate the context - in the second process. Only a single instantiation of a given context - may be active at any one time; a subsequent attempt by a context - exporter to access the exported security context will fail. - - The implementation may constrain the set of processes by which the - interprocess token may be imported, either as a function of local - security policy, or as a result of implementation decisions. For - example, some implementations may constrain contexts to be passed only - between processes that run under the same account, or which are part of - the same process group. - - The interprocess token may contain security-sensitive information (for - example cryptographic keys). While mechanisms are encouraged to either - avoid placing such sensitive information within interprocess tokens, or - to encrypt the token before returning it to the application, in a - typical object-library GSSAPI implementation this may not be possible. - Thus the application must take care to protect the interprocess token, - and ensure that any process to which the token is transferred is - trustworthy. - - If creation of the interprocess token is succesful, the implementation - shall deallocate all process-wide resources associated with the security - context, and set the context_handle to GSS_C_NO_CONTEXT. In the event - of an error that makes it impossible to complete the export of the - security context, the implementation must not return an interprocess - token, and should strive to leave the security context referenced by the - context_handle parameter untouched. If this is impossible, it is - permissible for the implementation to delete the security context, - providing it also sets the context_handle parameter to GSS_C_NO_CONTEXT. - - Parameters: - - minor_status Integer, modify - Mechanism specific status code - - - - Wray Document Expiration: 1 September 1997 [Page 48] - - - - - - - - INTERNET-DRAFT GSS-API V2 - C bindings March 1997 - - - - context_handle gss_ctx_id_t, modify - context handle identifying the context to transfer. - - interprocess_token buffer, opaque, modify - token to be transferred to target process. - Storage associated with this token must be - freed by the application after use with a - call to gss_release_buffer(). - - Function value: GSS status code - - GSS_S_COMPLETE Successful completion - - GSS_S_CONTEXT_EXPIRED The context has expired - - GSS_S_NO_CONTEXT The context was invalid - - GSS_S_UNAVAILABLE The operation is not supported. - - - - - - - - 7.15. gss_get_mic - - OM_uint32 gss_get_mic ( - OM_uint32 * minor_status, - const gss_ctx_id_t context_handle, - gss_qop_t qop_req, - const gss_buffer_t message_buffer, - gss_buffer_t msg_token) - - Purpose: - - Generates a cryptographic MIC for the supplied message, and places the - MIC in a token for transfer to the peer application. The qop_req - parameter allows a choice between several cryptographic algorithms, if - supported by the chosen mechanism. - - Parameters: - - minor_status Integer, modify - Implementation specific status code. - - context_handle gss_ctx_id_t, read - identifies the context on which the message - will be sent - - - - - Wray Document Expiration: 1 September 1997 [Page 49] - - - - - - - - INTERNET-DRAFT GSS-API V2 - C bindings March 1997 - - - qop_req gss_qop_t, read, optional - Specifies requested quality of protection. - Callers are encouraged, on portability grounds, - to accept the default quality of protection - offered by the chosen mechanism, which may be - requested by specifying GSS_C_QOP_DEFAULT for - this parameter. If an unsupported protection - strength is requested, gss_get_mic will return a - major_status of GSS_S_BAD_QOP. - - message_buffer buffer, opaque, read - message to be protected - - msg_token buffer, opaque, modify - buffer to receive token. The application must - free storage associated with this buffer after - use with a call to gss_release_buffer(). - - Function value: GSS status code - - GSS_S_COMPLETE Successful completion - - GSS_S_CONTEXT_EXPIRED The context has already expired - - GSS_S_NO_CONTEXT The context_handle parameter did not identify a valid - context - - GSS_S_BAD_QOP The specified QOP is not supported by the mechanism. - - - - - - - - 7.16. gss_import_name - - OM_uint32 gss_import_name ( - OM_uint32 * minor_status, - const gss_buffer_t input_name_buffer, - const gss_OID input_name_type, - gss_name_t * output_name) - - Purpose: - - Convert a contiguous string name to internal form. In general, the - internal name returned (via the parameter) will not be an - MN; the exception to this is if the indicates that the - contiguous string provided via the parameter is of - type GSS_C_NT_EXPORT_NAME, in which case the returned internal name will - be an MN for the mechanism that exported the name. - - - - - Wray Document Expiration: 1 September 1997 [Page 50] - - - - - - - - INTERNET-DRAFT GSS-API V2 - C bindings March 1997 - - - - Parameters: - - minor_status Integer, modify - Mechanism specific status code - - input_name_buffer buffer, octet-string, read - buffer containing contiguous string name to convert - - input_name_type Object ID, read, optional - Object ID specifying type of printable - name. Applications may specify either - GSS_C_NO_OID to use a mechanism-specific - default printable syntax, or an OID registered - by the GSS-API implementation to name a - specific namespace. - - output_name gss_name_t, modify - returned name in internal form. Storage - associated with this name must be freed - by the application after use with a call - to gss_release_name(). - - Function value: GSS status code - - GSS_S_COMPLETE Successful completion - - GSS_S_BAD_NAMETYPE The input_name_type was unrecognized - - GSS_S_BAD_NAME The input_name parameter could not be interpreted as a - name of the specified type - - - - - - - - - 7.17. gss_import_sec_context - - OM_uint32 gss_import_sec_context ( - OM_uint32 * minor_status, - const gss_buffer_t interprocess_token, - gss_ctx_id_t * context_handle) - - Purpose: - - Allows a process to import a security context established by another - process. A given interprocess token may be imported only once. See - gss_export_sec_context. - - - - - Wray Document Expiration: 1 September 1997 [Page 51] - - - - - - - - INTERNET-DRAFT GSS-API V2 - C bindings March 1997 - - - - Parameters: - - minor_status Integer, modify - Mechanism specific status code - - interprocess_token buffer, opaque, modify - token received from exporting process - - context_handle gss_ctx_id_t, modify - context handle of newly reactivated context. - Resources associated with this context handle - must be released by the application after use - with a call to gss_delete_sec_context(). - - - Function value: GSS status code - - GSS_S_COMPLETE Successful completion. - - GSS_S_NO_CONTEXT The token did not contain a valid context reference. - - GSS_S_DEFECTIVE_TOKEN The token was invalid. - - GSS_S_UNAVAILABLE The operation is unavailable. - - GSS_S_UNAUTHORIZED Local policy prevents the import of this context by - the current process.. - - - - - - - - 7.18. gss_indicate_mechs - - OM_uint32 gss_indicate_mechs ( - OM_uint32 * minor_status, - gss_OID_set * mech_set) - - Purpose: - - Allows an application to determine which underlying security mechanisms - are available. - - Parameters: - - minor_status Integer, modify - Mechanism specific status code. - - - - - Wray Document Expiration: 1 September 1997 [Page 52] - - - - - - - - INTERNET-DRAFT GSS-API V2 - C bindings March 1997 - - - mech_set set of Object IDs, modify - set of implementation-supported mechanisms. - The returned gss_OID_set value will be a - dynamically-allocated OID set, that should - be released by the caller after use with a - call to gss_release_oid_set(). - - Function value: GSS status code - - GSS_S_COMPLETE Successful completion - - - - - - - - 7.19. gss_init_sec_context - - OM_uint32 gss_init_sec_context ( - OM_uint32 * minor_status, - const gss_cred_id_t initiator_cred_handle, - gss_ctx_id_t * context_handle, - const gss_name_t target_name, - const gss_OID mech_type, - OM_uint32 req_flags, - OM_uint32 time_req, - const gss_channel_bindings_t - input_chan_bindings, - const gss_buffer_t input_token - gss_OID * actual_mech_type, - gss_buffer_t output_token, - OM_uint32 * ret_flags, - OM_uint32 * time_rec ) - - Purpose: - - Initiates the establishment of a security context between the - application and a remote peer. Initially, the input_token parameter - should be specified either as GSS_C_NO_BUFFER, or as a pointer to a - gss_buffer_desc object whose length field contains the value zero. The - routine may return a output_token which should be transferred to the - peer application, where the peer application will present it to - gss_accept_sec_context. If no token need be sent, gss_init_sec_context - will indicate this by setting the length field of the output_token - argument to zero. To complete the context establishment, one or more - reply tokens may be required from the peer application; if so, - gss_init_sec_context will return a status containing the supplementary - information bit GSS_S_CONTINUE_NEEDED. In this case, - gss_init_sec_context should be called again when the reply token is - received from the peer application, passing the reply token to - gss_init_sec_context via the input_token parameters. - - - - Wray Document Expiration: 1 September 1997 [Page 53] - - - - - - - - INTERNET-DRAFT GSS-API V2 - C bindings March 1997 - - - - Portable applications should be constructed to use the token length and - return status to determine whether a token needs to be sent or waited - for. Thus a typical portable caller should always invoke - gss_init_sec_context within a loop: - - int context_established = 0; - gss_ctx_id_t context_hdl = GSS_C_NO_CONTEXT; - ... - input_token->length = 0; - - while (!context_established) { - maj_stat = gss_init_sec_context(&min_stat, - cred_hdl, - &context_hdl, - target_name, - desired_mech, - desired_services, - desired_time, - input_bindings, - input_token, - &actual_mech, - output_token, - &actual_services, - &actual_time); - if (GSS_ERROR(maj_stat)) { - report_error(maj_stat, min_stat); - }; - if (output_token->length != 0) { - send_token_to_peer(output_token); - gss_release_buffer(&min_stat, - output_token) - }; - if (GSS_ERROR(maj_stat)) { - if (context_hdl != GSS_C_NO_CONTEXT) - gss_delete_sec_context(&min_stat, - &context_hdl, - GSS_C_NO_BUFFER); - break; - }; - if (maj_stat & GSS_S_CONTINUE_NEEDED) { - receive_token_from_peer(input_token); - } else { - context_established = 1; - }; - }; - - Whenever the routine returns a major status that includes the value - GSS_S_CONTINUE_NEEDED, the context is not fully established and the - following restrictions apply to the output parameters: - - - - - - Wray Document Expiration: 1 September 1997 [Page 54] - - - - - - - - INTERNET-DRAFT GSS-API V2 - C bindings March 1997 - - - - (a) The value returned via the time_rec parameter is undefined - - (b) Unless the accompanying ret_flags parameter contains the bit - GSS_C_PROT_READY_FLAG, indicating that per-message services may be - applied in advance of a successful completion status, the value - returned via the actual_mech_type parameter is undefined until the - routine returns a major status value of GSS_S_COMPLETE. - - (c) The values of the GSS_C_DELEG_FLAG, GSS_C_MUTUAL_FLAG, - GSS_C_REPLAY_FLAG, GSS_C_SEQUENCE_FLAG, GSS_C_CONF_FLAG, - GSS_C_INTEG_FLAG and GSS_C_ANON_FLAG bits returned via the - ret_flags parameter should contain the values that the - implementation expects would be valid if context establishment - were to succeed. In particular, if the application has requested - a service such as delegation or anonymous authentication via the - req_flags argument, and such a service is unavailable from the - underlying mechanism, gss_init_sec_context should generate a token - that will not provide the service, and indicate via the ret_flags - argument that the service will not be supported. The application - may choose to abort the context establishment by calling - gss_delete_sec_context (if it cannot continue in the absence of - the service), or it may choose to transmit the token and continue - context establishment (if the service was merely desired but not - mandatory). - - The values of the GSS_C_PROT_READY_FLAG and GSS_C_TRANS_FLAG bits - within ret_flags should indicate the actual state at the time - gss_init_sec_context returns, whether or not the context is fully - established. - - Although this requires that GSSAPI implementations set the - GSS_C_PROT_READY_FLAG in the final ret_flags returned to a caller - (i.e. when accompanied by a GSS_S_COMPLETE status code), - applications should not rely on this behavior as the flag was not - defined in Version 1 of the GSSAPI. Instead, applications should - be prepared to use per-message services after a successful context - establishment, according to the GSS_C_INTEG_FLAG and - GSS_C_CONF_FLAG values. - - All other bits within the ret_flags argument should be set to - zero. - - If the initial call of gss_init_sec_context() fails, the implementation - should not create a context object, and should leave the value of the - context_handle parameter set to GSS_C_NO_CONTEXT to indicate this. In - the event of a failure on a subsequent call, the implementation is - permitted to delete the "half-built" security context (in which case it - should set the context_handle parameter to GSS_C_NO_CONTEXT), but the - preferred behavior is to leave the security context untouched for the - application to delete (using gss_delete_sec_context). - - - - - Wray Document Expiration: 1 September 1997 [Page 55] - - - - - - - - INTERNET-DRAFT GSS-API V2 - C bindings March 1997 - - - - Parameters: - - minor_status Integer, modify - Mechanism specific status code. - - initiator_cred_handle gss_cred_id_t, read, optional - handle for credentials claimed. Supply - GSS_C_NO_CREDENTIAL to act as a default - initiator principal. If no default - initiator is defined, the function will - return GSS_S_NO_CRED. - - context_handle gss_ctx_id_t, read/modify - context handle for new context. Supply - GSS_C_NO_CONTEXT for first call; use value - returned by first call in continuation calls. - Resources associated with this context-handle - must be released by the application after use - with a call to gee_delete_sec_context(). - - target_name gss_name_t, read - Name of target - - mech_type OID, read, optional - Object ID of desired mechanism. Supply - GSS_C_NO_OID to obtain an implementation - specific default - - req_flags bit-mask, read - Contains various independent flags, each of - which requests that the context support a - specific service option. Symbolic - names are provided for each flag, and the - symbolic names corresponding to the required - flags should be logically-ORed - together to form the bit-mask value. The - flags are: - - GSS_C_DELEG_FLAG - True - Delegate credentials to remote peer - False - Don't delegate - GSS_C_MUTUAL_FLAG - True - Request that remote peer - authenticate itself - False - Authenticate self to remote peer - only - GSS_C_REPLAY_FLAG - True - Enable replay detection for - messages protected with gss_wrap - or gss_get_mic - False - Don't attempt to detect - replayed messages - - - Wray Document Expiration: 1 September 1997 [Page 56] - - - - - - - - INTERNET-DRAFT GSS-API V2 - C bindings March 1997 - - - - GSS_C_SEQUENCE_FLAG - True - Enable detection of out-of-sequence - protected messages - False - Don't attempt to detect - out-of-sequence messages - GSS_C_ANON_FLAG - True - Do not reveal the initiator's - identity to the acceptor. - False - Authenticate normally. - - time_req Integer, read, optional - Desired number of seconds for which context - should remain valid. Supply 0 to request a - default validity period. - - input_chan_bindings channel bindings, read, optional - Application-specified bindings. Allows - application to securely bind channel - identification information to the security - context. Specify GSS_C_NO_CHANNEL_BINDINGS - if channel bindings are not used. - - input_token buffer, opaque, read, optional (see text) - Token received from peer application. - Supply GSS_C_NO_BUFFER, or a pointer to - a buffer containing the value GSS_C_EMPTY_BUFFER - on initial call. - - actual_mech_type OID, modify, optional - Actual mechanism used. The OID returned via - this parameter will be a pointer to static - storage that should be treated as read-only; - In particular the application should not attempt - to free it. Specify NULL if not required. - - output_token buffer, opaque, modify - token to be sent to peer application. If - the length field of the returned buffer is - zero, no token need be sent to the peer - application. Storage associated with this - buffer must be freed by the application - after use with a call to gss_release_buffer(). - - ret_flags bit-mask, modify, optional - Contains various independent flags, each of which - indicates that the context supports a specific - service option. Specify NULL if not - required. Symbolic names are provided - for each flag, and the symbolic names - corresponding to the required flags should be - - - - Wray Document Expiration: 1 September 1997 [Page 57] - - - - - - - - INTERNET-DRAFT GSS-API V2 - C bindings March 1997 - - - - logically-ANDed with the ret_flags value to test - whether a given option is supported by the - context. The flags are: - - GSS_C_DELEG_FLAG - True - Credentials were delegated to - the remote peer - False - No credentials were delegated - GSS_C_MUTUAL_FLAG - True - Remote peer has been asked to - authenticated itself - False - Remote peer has not been asked to - authenticate itself - GSS_C_REPLAY_FLAG - True - replay of protected messages - will be detected - False - replayed messages will not be - detected - GSS_C_SEQUENCE_FLAG - True - out-of-sequence protected - messages will be detected - False - out-of-sequence messages will - not be detected - GSS_C_CONF_FLAG - True - Confidentiality service may be - invoked by calling gss_wrap routine - False - No confidentiality service (via - gss_wrap) available. gss_wrap will - provide message encapsulation, - data-origin authentication and - integrity services only. - GSS_C_INTEG_FLAG - True - Integrity service may be invoked by - calling either gss_get_mic or gss_wrap - routines. - False - Per-message integrity service - unavailable. - GSS_C_ANON_FLAG - True - The initiator's identity has not been - revealed, and will not be revealed if - any emitted token is passed to the - acceptor. - False - The initiator's identity has been or - will be authenticated normally. - GSS_C_PROT_READY_FLAG - True - Protection services (as specified - by the states of the GSS_C_CONF_FLAG - and GSS_C_INTEG_FLAG) are available for - use if the accompanying major status - return value is either GSS_S_COMPLETE or - GSS_S_CONTINUE_NEEDED. - - - - Wray Document Expiration: 1 September 1997 [Page 58] - - - - - - - - INTERNET-DRAFT GSS-API V2 - C bindings March 1997 - - - - False - Protection services (as specified - by the states of the GSS_C_CONF_FLAG - and GSS_C_INTEG_FLAG) are available - only if the accompanying major status - return value is GSS_S_COMPLETE. - GSS_C_TRANS_FLAG - True - The resultant security context may - be transferred to other processes via - a call to gss_export_sec_context(). - False - The security context is not - transferrable. - All other bits should be set to zero. - - time_rec Integer, modify, optional - number of seconds for which the context - will remain valid. If the implementation does - not support context expiration, the value - GSS_C_INDEFINITE will be returned. Specify - NULL if not required. - - Function value: GSS status code - - GSS_S_COMPLETE Successful completion - - GSS_S_CONTINUE_NEEDED Indicates that a token from the peer application - is required to complete the context, and that - gss_init_sec_context must be called again with that - token. - - GSS_S_DEFECTIVE_TOKEN Indicates that consistency checks performed on the - input_token failed - - GSS_S_DEFECTIVE_CREDENTIAL Indicates that consistency checks performed - on the credential failed. - - GSS_S_NO_CRED The supplied credentials were not valid for context - initiation, or the credential handle did not reference - any credentials. - - GSS_S_CREDENTIALS_EXPIRED The referenced credentials have expired - - GSS_S_BAD_BINDINGS The input_token contains different channel bindings - to those specified via the input_chan_bindings - parameter - - GSS_S_BAD_SIG The input_token contains an invalid MIC, or a MIC that - could not be verified - - GSS_S_OLD_TOKEN The input_token was too old. This is a fatal error - during context establishment - - - - - Wray Document Expiration: 1 September 1997 [Page 59] - - - - - - - - INTERNET-DRAFT GSS-API V2 - C bindings March 1997 - - - - GSS_S_DUPLICATE_TOKEN The input_token is valid, but is a duplicate of a - token already processed. This is a fatal error during - context establishment. - - GSS_S_NO_CONTEXT Indicates that the supplied context handle did not - refer to a valid context - - GSS_S_BAD_NAMETYPE The provided target_name parameter contained an - invalid or unsupported type of name - - GSS_S_BAD_NAME The provided target_name parameter was ill-formed. - - GSS_S_BAD_MECH The specified mechanism is not supported by the - provided credential, or is unrecognized by the - implementation. - - - - - - - - 7.20. gss_inquire_context - - OM_uint32 gss_inquire_context ( - OM_uint32 * minor_status, - const gss_ctx_id_t context_handle, - gss_name_t * src_name, - gss_name_t * targ_name, - OM_uint32 * lifetime_rec, - gss_OID * mech_type, - OM_uint32 * ctx_flags, - int * locally_initiated, - int * open ) - - Purpose: - - Obtains information about a security context. The caller must already - have obtained a handle that refers to the context, although the context - need not be fully established. - - Parameters: - - minor_status Integer, modify - Mechanism specific status code - - context_handle gss_ctx_id_t, read - A handle that refers to the security context. - - src_name gss_name_t, modify, optional - The name of the context initiator. - - - - Wray Document Expiration: 1 September 1997 [Page 60] - - - - - - - - INTERNET-DRAFT GSS-API V2 - C bindings March 1997 - - - - If the context was established using anonymous - authentication, and if the application invoking - gss_inquire_context is the context acceptor, - an anonymous name will be returned. Storage - associated with this name must be freed by the - application after use with a call to - gss_release_name(). Specify NULL if not - required. - - targ_name gss_name_t, modify, optional - The name of the context acceptor. - Storage associated with this name must be - freed by the application after use with a call - to gss_release_name(). Specify NULL if not - Specify NULL if not required. - - lifetime_rec Integer, modify, optional - The number of seconds for which the context - will remain valid. If the context has - expired, this parameter will be set to zero. - If the implementation does not support - context expiration, the value - GSS_C_INDEFINITE will be returned. Specify - NULL if not required. - - mech_type gss_OID, modify, optional - The security mechanism providing the - context. The returned OID will be a - pointer to static storage that should - be treated as read-only by the application; - in particular the application should not - attempt to free it. Specify NULL if not - required. - - ctx_flags bit-mask, modify, optional - Contains various independent flags, each of - which indicates that the context supports - (or is expected to support, if ctx_open is - false) a specific service option. If not - needed, specify NULL. Symbolic names are - provided for each flag, and the symbolic names - corresponding to the required flags - should be logically-ANDed with the ret_flags - value to test whether a given option is - supported by the context. The flags are: - - GSS_C_DELEG_FLAG - True - Credentials were delegated from - the initiator to the acceptor. - False - No credentials were delegated - - - - Wray Document Expiration: 1 September 1997 [Page 61] - - - - - - - - INTERNET-DRAFT GSS-API V2 - C bindings March 1997 - - - GSS_C_MUTUAL_FLAG - True - The acceptor was authenticated - to the initiator - False - The acceptor did not authenticate - itself. - GSS_C_REPLAY_FLAG - True - replay of protected messages - will be detected - False - replayed messages will not be - detected - GSS_C_SEQUENCE_FLAG - True - out-of-sequence protected - messages will be detected - False - out-of-sequence messages will not - be detected - GSS_C_CONF_FLAG - True - Confidentiality service may be invoked - by calling gss_wrap routine - False - No confidentiality service (via - gss_wrap) available. gss_wrap will - provide message encapsulation, - data-origin authentication and - integrity services only. - GSS_C_INTEG_FLAG - True - Integrity service may be invoked by - calling either gss_get_mic or gss_wrap - routines. - False - Per-message integrity service - unavailable. - GSS_C_ANON_FLAG - True - The initiator's identity will not - be revealed to the acceptor. - The src_name parameter (if - requested) contains an anonymous - internal name. - False - The initiator has been - authenticated normally. - GSS_C_PROT_READY_FLAG - True - Protection services (as specified - by the states of the GSS_C_CONF_FLAG - and GSS_C_INTEG_FLAG) are available - for use. - False - Protection services (as specified - by the states of the GSS_C_CONF_FLAG - and GSS_C_INTEG_FLAG) are available - only if the context is fully - established (i.e. if the open parameter - is non-zero). - GSS_C_TRANS_FLAG - True - The resultant security context may - be transferred to other processes via - a call to gss_export_sec_context(). - False - The security context is not - transferrable. - - Wray Document Expiration: 1 September 1997 [Page 62] - - - - - - - - INTERNET-DRAFT GSS-API V2 - C bindings March 1997 - - - - - - locally_initiated Boolean, modify - Non-zero if the invoking application is the - context initiator. - Specify NULL if not required. - - open Boolean, modify - Non-zero if the context is fully established; - Zero if a context-establishment token - is expected from the peer application. - Specify NULL if not required. - - Function value: GSS status code - - GSS_S_COMPLETE Successful completion - - GSS_S_NO_CONTEXT The referenced context could not be accessed. - - GSS_S_CONTEXT_EXPIRED The context has expired. If the lifetime_rec - parameter was requested, it will be set to 0. - - - - - - - - 7.21. gss_inquire_cred - - OM_uint32 gss_inquire_cred ( - OM_uint32 * minor_status, - const gss_cred_id_t cred_handle, - gss_name_t * name, - OM_uint32 * lifetime, - gss_cred_usage_t * cred_usage, - gss_OID_set * mechanisms ) - - Purpose: - - Obtains information about a credential. The caller must already have - obtained a handle that refers to the credential. - - Parameters: - - minor_status Integer, modify - Mechanism specific status code - - cred_handle gss_cred_id_t, read - A handle that refers to the target credential. - Specify GSS_C_NO_CREDENTIAL to inquire about - the default initiator principal. - - - Wray Document Expiration: 1 September 1997 [Page 63] - - - - - - - - INTERNET-DRAFT GSS-API V2 - C bindings March 1997 - - - - - name gss_name_t, modify, optional - The name whose identity the credential asserts. - Storage associated with this name should be freed - by the application after use with a call to - gss_release_name(). Specify NULL if not required. - - lifetime Integer, modify, optional - The number of seconds for which the credential - will remain valid. If the credential has - expired, this parameter will be set to zero. - If the implementation does not support - credential expiration, the value - GSS_C_INDEFINITE will be returned. Specify - NULL if not required. - - cred_usage gss_cred_usage_t, modify, optional - How the credential may be used. One of the - following: - GSS_C_INITIATE - GSS_C_ACCEPT - GSS_C_BOTH - Specify NULL if not required. - - mechanisms gss_OID_set, modify, optional - Set of mechanisms supported by the credential. - Storage associated with this OID set must be - freed by the application after use with a call - to gss_release_oid_set(). Specify NULL if not - required. - - Function value: GSS status code - - GSS_S_COMPLETE Successful completion - - GSS_S_NO_CRED The referenced credentials could not be accessed. - - GSS_S_DEFECTIVE_CREDENTIAL The referenced credentials were invalid. - - GSS_S_CREDENTIALS_EXPIRED The referenced credentials have expired. If - the lifetime parameter was not passed as NULL, it will - be set to 0. - - - - - - - - - - Wray Document Expiration: 1 September 1997 [Page 64] - - - - - - - - INTERNET-DRAFT GSS-API V2 - C bindings March 1997 - - - - 7.22. gss_inquire_cred_by_mech - - OM_uint32 gss_inquire_cred_by_mech ( - OM_uint32 * minor_status, - const gss_cred_id_t cred_handle, - const gss_OID mech_type, - gss_name_t * name, - OM_uint32 * initiator_lifetime, - OM_uint32 * acceptor_lifetime, - gss_cred_usage_t * cred_usage ) - - Purpose: - - Obtains per-mechanism information about a credential. The caller must - already have obtained a handle that refers to the credential. - - Parameters: - - minor_status Integer, modify - Mechanism specific status code - - cred_handle gss_cred_id_t, read - A handle that refers to the target credential. - Specify GSS_C_NO_CREDENTIAL to inquire about - the default initiator principal. - - mech_type gss_OID, read - The mechanism for which information should be - returned. - - name gss_name_t, modify, optional - The name whose identity the credential asserts. - Storage associated with this name must be - freed by the application after use with a call - to gss_release_name(). Specify NULL if not - required. - - initiator_lifetime Integer, modify, optional - The number of seconds for which the credential - will remain capable of initiating security contexts - under the specified mechanism. If the credential - can no longer be used to initiate contexts, or if - the credential usage for this mechanism is - GSS_C_ACCEPT, - this parameter will be set to zero. If the - implementation does not support expiration of - initiator credentials, the value GSS_C_INDEFINITE - will be returned. Specify NULL if not required. - - acceptor_lifetime Integer, modify, optional - The number of seconds for which the credential - - - - Wray Document Expiration: 1 September 1997 [Page 65] - - - - - - - - INTERNET-DRAFT GSS-API V2 - C bindings March 1997 - - - - will remain capable of accepting security contexts - under the specified mechanism. If the credential - can no longer be used to accept contexts, or if - the credential usage for this mechanism is - GSS_C_INITIATE, this parameter will be set to zero. - If the implementation does not support expiration - of acceptor credentials, the value GSS_C_INDEFINITE - will be returned. Specify NULL if not required. - - cred_usage gss_cred_usage_t, modify, optional - How the credential may be used with the specified - mechanism. One of the following: - GSS_C_INITIATE - GSS_C_ACCEPT - GSS_C_BOTH - Specify NULL if not required. - - Function value: GSS status code - - GSS_S_COMPLETE Successful completion - - GSS_S_NO_CRED The referenced credentials could not be accessed. - - GSS_S_DEFECTIVE_CREDENTIAL The referenced credentials were invalid. - - GSS_S_CREDENTIALS_EXPIRED The referenced credentials have expired. If - the lifetime parameter was not passed as NULL, it will - be set to 0. - - - - - - - - 7.23. gss_inquire_mechs_for_name - - OM_uint32 gss_inquire_mechs_for_name ( - OM_uint32 * minor_status, - const gss_name_t input_name, - gss_OID_set * mech_types ) - - Purpose: - - Returns the set of mechanisms supported by the GSSAPI implementation - that may be able to process the specified name. - - Each mechanism returned will recognize at least one element within the - name. It is permissible for this routine to be implemented within a - mechanism-independent GSSAPI layer, using the type information contained - within the presented name, and based on registration information - - - - Wray Document Expiration: 1 September 1997 [Page 66] - - - - - - - - INTERNET-DRAFT GSS-API V2 - C bindings March 1997 - - - - provided by individual mechanism implementations. This means that the - returned mech_types set may indicate that a particular mechanism will - understand the name when in fact it would refuse to accept the name as - input to gss_canonicalize_name, gss_init_sec_context, gss_acquire_cred - or gss_add_cred (due to some property of the specific name, as opposed - to the name type). Thus this routine should be used only as a pre- - filter for a call to a subsequent mechanism-specific routine. - - - - Parameters: - - minor_status Integer, modify - Implementation specific status code. - - input_name gss_name_t, read - The name to which the inquiry relates. - - mech_types gss_OID_set, modify - Set of mechanisms that may support the - specified name. The returned OID set - must be freed by the caller after use - with a call to gss_release_oid_set(). - - Function value: GSS status code - - GSS_S_COMPLETE Successful completion - - GSS_S_BAD_NAME The input_name parameter was ill-formed. - - GSS_S_BAD_NAMETYPE The input_name parameter contained an invalid or - unsupported type of name - - - - - - - 7.24. gss_inquire_names_for_mech - - OM_uint32 gss_inquire_names_for_mech ( - OM_uint32 * minor_status, - const gss_OID mechanism, - gss_OID_set * name_types) - - Purpose: - - Returns the set of nametypes supported by the specified mechanism. - - - - - - - Wray Document Expiration: 1 September 1997 [Page 67] - - - - - - - - INTERNET-DRAFT GSS-API V2 - C bindings March 1997 - - - - Parameters: - - minor_status Integer, modify - Implementation specific status code. - - mechanism gss_OID, read - The mechanism to be interrogated. - - name_types gss_OID_set, modify - Set of name-types supported by the specified - mechanism. The returned OID set must be - freed by the application after use with a - call to gss_release_oid_set(). - - Function value: GSS status code - - GSS_S_COMPLETE Successful completion - - - - - - - - 7.25. gss_process_context_token - - OM_uint32 gss_process_context_token ( - OM_uint32 * minor_status, - const gss_ctx_id_t context_handle, - const gss_buffer_t token_buffer) - - Purpose: - - Provides a way to pass a token to the security service. Used with - tokens emitted by gss_delete_sec_context. Note that mechanisms are - encouraged to perform local deletion, and not emit tokens from - gss_delete_sec_context. This routine, therefore, is primarily for - backwards compatibility with V1 applications. - - Parameters: - - minor_status Integer, modify - Implementation specific status code. - - context_handle gss_ctx_id_t, read - context handle of context on which token is to - be processed - - token_buffer buffer, opaque, read - token to process - - - - - Wray Document Expiration: 1 September 1997 [Page 68] - - - - - - - - INTERNET-DRAFT GSS-API V2 - C bindings March 1997 - - - - Function value: GSS status code - - GSS_S_COMPLETE Successful completion - - GSS_S_DEFECTIVE_TOKEN Indicates that consistency checks performed on the - token failed - - GSS_S_NO_CONTEXT The context_handle did not refer to a valid context - - - - - - - - 7.26. gss_release_buffer - - OM_uint32 gss_release_buffer ( - OM_uint32 * minor_status, - gss_buffer_t buffer) - - Purpose: - - Free storage associated with a buffer. The storage must have been - allocated by a GSS-API routine. In addition to freeing the associated - storage, the routine will zero the length field in the descriptor to - which the buffer parameter refers. - - Parameters: - - minor_status Integer, modify - Mechanism specific status code - - buffer buffer, modify - The storage associated with the buffer will be - deleted. The gss_buffer_desc object will not - be freed, but its length field will be zeroed. - - Function value: GSS status code - - GSS_S_COMPLETE Successful completion - - - - - - - - - - - - - - Wray Document Expiration: 1 September 1997 [Page 69] - - - - - - - - INTERNET-DRAFT GSS-API V2 - C bindings March 1997 - - - - 7.27. gss_release_cred - - OM_uint32 gss_release_cred ( - OM_uint32 * minor_status, - gss_cred_id_t * cred_handle) - - Purpose: - - Informs GSS-API that the specified credential handle is no longer - required by the application, and frees associated resources. - - Parameters: - - cred_handle gss_cred_id_t, modify, optional - Opaque handle identifying credential - to be released. If GSS_C_NO_CREDENTIAL - is supplied, the routine will complete - successfully, but will do nothing. - - minor_status Integer, modify - Mechanism specific status code. - - Function value: GSS status code - - GSS_S_COMPLETE Successful completion - - GSS_S_NO_CRED Credentials could not be accessed. - - - - - - - - 7.28. gss_release_name - - OM_uint32 gss_release_name ( - OM_uint32 * minor_status, - gss_name_t * name) - - Purpose: - - Free GSSAPI-allocated storage by associated with an internal-form name. - - Parameters: - - minor_status Integer, modify - Mechanism specific status code - - name gss_name_t, modify - The name to be deleted - - - - Wray Document Expiration: 1 September 1997 [Page 70] - - - - - - - - INTERNET-DRAFT GSS-API V2 - C bindings March 1997 - - - - Function value: GSS status code - - GSS_S_COMPLETE Successful completion - - GSS_S_BAD_NAME The name parameter did not contain a valid name - - - - - - - - 7.29. gss_release_oid_set - - OM_uint32 gss_release_oid_set ( - OM_uint32 * minor_status, - gss_OID_set * set) - - Purpose: - - Free storage associated with a GSSAPI-generated gss_OID_set object. The - set parameter must refer to an OID-set that was returned from a GSSAPI - routine. gss_release_oid_set() will free the storage associated with - each individual member OID, the OID set's elements array, and the - gss_OID_set_desc. - - - Parameters: - - minor_status Integer, modify - Mechanism specific status code - - set Set of Object IDs, modify - The storage associated with the gss_OID_set - will be deleted. - - Function value: GSS status code - - GSS_S_COMPLETE Successful completion - - - - - - - - - - - - - - - - Wray Document Expiration: 1 September 1997 [Page 71] - - - - - - - - INTERNET-DRAFT GSS-API V2 - C bindings March 1997 - - - - 7.30. gss_test_oid_set_member - - OM_uint32 gss_test_oid_set_member ( - OM_uint32 * minor_status, - const gss_OID member, - const gss_OID_set set, - int * present) - - Purpose: - - Interrogate an Object Identifier set to determine whether a specified - Object Identifier is a member. This routine is intended to be used with - OID sets returned by gss_indicate_mechs(), gss_acquire_cred(), and - gss_inquire_cred(), but will also work with user-generated sets. - - Parameters: - - minor_status Integer, modify - Mechanism specific status code - - member Object ID, read - The object identifier whose presence - is to be tested. - - set Set of Object ID, read - The Object Identifier set. - - present Boolean, modify - non-zero if the specified OID is a member - of the set, zero if not. - - Function value: GSS status code - - GSS_S_COMPLETE Successful completion - - - - - - - - 7.31. gss_unwrap - - OM_uint32 gss_unwrap ( - OM_uint32 * minor_status, - const gss_ctx_id_t context_handle, - const gss_buffer_t input_message_buffer, - gss_buffer_t output_message_buffer, - int * conf_state, - gss_qop_t * qop_state) - - - - - Wray Document Expiration: 1 September 1997 [Page 72] - - - - - - - - INTERNET-DRAFT GSS-API V2 - C bindings March 1997 - - - - Purpose: - - Converts a message previously protected by gss_wrap back to a usable - form, verifying the embedded MIC. The conf_state parameter indicates - whether the message was encrypted; the qop_state parameter indicates the - strength of protection that was used to provide the confidentiality and - integrity services. - - Parameters: - - minor_status Integer, modify - Mechanism specific status code. - - context_handle gss_ctx_id_t, read - Identifies the context on which the message - arrived - - input_message_buffer buffer, opaque, read - protected message - - output_message_buffer buffer, opaque, modify - Buffer to receive unwrapped message. - Storage associated with this buffer must - be freed by the application after use use - with a call to gss_release_buffer(). - - conf_state boolean, modify, optional - Non-zero - Confidentiality and integrity protection - were used - Zero - Integrity service only was used - Specify NULL if not required - - qop_state gss_qop_t, modify, optional - Quality of protection gained from MIC. - Specify NULL if not required - - Function value: GSS status code - - GSS_S_COMPLETE Successful completion - - GSS_S_DEFECTIVE_TOKEN The token failed consistency checks - - GSS_S_BAD_SIG The MIC was incorrect - - GSS_S_DUPLICATE_TOKEN The token was valid, and contained a correct MIC - for the message, but it had already been processed - - GSS_S_OLD_TOKEN The token was valid, and contained a correct MIC for - the message, but it is too old to check for - duplication. - - - - - Wray Document Expiration: 1 September 1997 [Page 73] - - - - - - - - INTERNET-DRAFT GSS-API V2 - C bindings March 1997 - - - - GSS_S_UNSEQ_TOKEN The token was valid, and contained a correct MIC for - the message, but has been verified out of sequence; a - later token has already been received. - - GSS_S_GAP_TOKEN The token was valid, and contained a correct MIC for - the message, but has been verified out of sequence; - an earlier expected token has not yet been received. - - GSS_S_CONTEXT_EXPIRED The context has already expired - - GSS_S_NO_CONTEXT The context_handle parameter did not identify a valid - context - - - - - - - - 7.32. gss_verify_mic - - OM_uint32 gss_verify_mic ( - OM_uint32 * minor_status, - const gss_ctx_id_t context_handle, - const gss_buffer_t message_buffer, - const gss_buffer_t token_buffer, - gss_qop_t * qop_state) - - Purpose: - - Verifies that a cryptographic MIC, contained in the token parameter, - fits the supplied message. The qop_state parameter allows a message - recipient to determine the strength of protection that was applied to - the message. - - Parameters: - - minor_status Integer, modify - Mechanism specific status code. - - context_handle gss_ctx_id_t, read - Identifies the context on which the message - arrived - - message_buffer buffer, opaque, read - Message to be verified - - token_buffer buffer, opaque, read - Token associated with message - - - - - Wray Document Expiration: 1 September 1997 [Page 74] - - - - - - - - INTERNET-DRAFT GSS-API V2 - C bindings March 1997 - - - qop_state gss_qop_t, modify, optional - quality of protection gained from MIC - Specify NULL if not required - - Function value: GSS status code - - GSS_S_COMPLETE Successful completion - - GSS_S_DEFECTIVE_TOKEN The token failed consistency checks - - GSS_S_BAD_SIG The MIC was incorrect - - GSS_S_DUPLICATE_TOKEN The token was valid, and contained a correct MIC - for the message, but it had already been processed - - GSS_S_OLD_TOKEN The token was valid, and contained a correct MIC for - the message, but it is too old to check for - duplication. - - GSS_S_UNSEQ_TOKEN The token was valid, and contained a correct MIC for - the message, but has been verified out of sequence; a - later token has already been received. - - GSS_S_GAP_TOKEN The token was valid, and contained a correct MIC for - the message, but has been verified out of sequence; - an earlier expected token has not yet been received. - - GSS_S_CONTEXT_EXPIRED The context has already expired - - GSS_S_NO_CONTEXT The context_handle parameter did not identify a valid - context - - - - - - - - 7.33. gss_wrap - - OM_uint32 gss_wrap ( - OM_uint32 * minor_status, - const gss_ctx_id_t context_handle, - int conf_req_flag, - gss_qop_t qop_req - const gss_buffer_t input_message_buffer, - int * conf_state, - gss_buffer_t output_message_buffer ) - - - - - - - - Wray Document Expiration: 1 September 1997 [Page 75] - - - - - - - - INTERNET-DRAFT GSS-API V2 - C bindings March 1997 - - - - Purpose: - - Attaches a cryptographic MIC and optionally encrypts the specified - input_message. The output_message contains both the MIC and the - message. The qop_req parameter allows a choice between several - cryptographic algorithms, if supported by the chosen mechanism. - - Since some application-level protocols may wish to use tokens emitted by - gss_wrap() to provide "secure framing", implementations should support - the wrapping of zero-length messages. - - Parameters: - - minor_status Integer, modify - Mechanism specific status code. - - context_handle gss_ctx_id_t, read - Identifies the context on which the message - will be sent - - conf_req_flag boolean, read - Non-zero - Both confidentiality and integrity - services are requested - Zero - Only integrity service is requested - - qop_req gss_qop_t, read, optional - Specifies required quality of protection. A - mechanism-specific default may be requested by - setting qop_req to GSS_C_QOP_DEFAULT. If an - unsupported protection strength is requested, - gss_wrap will return a major_status of - GSS_S_BAD_QOP. - - input_message_buffer buffer, opaque, read - Message to be protected - - conf_state boolean, modify, optional - Non-zero - Confidentiality, data origin - authentication and integrity - services have been applied - Zero - Integrity and data origin services only - has been applied. - Specify NULL if not required - - output_message_buffer buffer, opaque, modify - Buffer to receive protected message. - Storage associated with this message must - be freed by the application after use with - a call to gss_release_buffer(). - - Function value: GSS status code - - - - Wray Document Expiration: 1 September 1997 [Page 76] - - - - - - - - INTERNET-DRAFT GSS-API V2 - C bindings March 1997 - - - - GSS_S_COMPLETE Successful completion - - GSS_S_CONTEXT_EXPIRED The context has already expired - - GSS_S_NO_CONTEXT The context_handle parameter did not identify a valid - context - - GSS_S_BAD_QOP The specified QOP is not supported by the mechanism. - - - - - - - - 7.34. gss_wrap_size_limit - - OM_uint32 gss_wrap_size_limit ( - OM_uint32 * minor_status, - const gss_ctx_id_t context_handle, - int conf_req_flag, - gss_qop_t qop_req, - OM_uint32 req_output_size, - OM_uint32 * max_input_size) - - Purpose: - - Allows an application to determine the maximum message size that, if - presented to gss_wrap with the same conf_req_flag and qop_req - parameters, will result in an output token containing no more than - req_output_size bytes. - - This call is intended for use by applications that communicate over - protocols that impose a maximum message size. It enables the - application to fragment messages prior to applying protection. - - Successful completion of this call does not guarantee that gss_wrap will - be able to protect a message of length max_input_size bytes, since this - ability may depend on the availability of system resources at the time - that gss_wrap is called. However, if the implementation itself imposes - an upper limit on the length of messages that may be processed by - gss_wrap, the implementation should not return a value via - max_input_bytes that is greater than this length. - - Parameters: - - minor_status Integer, modify - Mechanism specific status code - - context_handle gss_ctx_id_t, read - A handle that refers to the security over - - - - Wray Document Expiration: 1 September 1997 [Page 77] - - - - - - - - INTERNET-DRAFT GSS-API V2 - C bindings March 1997 - - - - which the messages will be sent. - - conf_req_flag Boolean, read - Indicates whether gss_wrap will be asked - to apply confidentiality protection in - addition to integrity protection. See - the routine description for gss_wrap - for more details. - - qop_req gss_qop_t, read - Indicates the level of protection that - gss_wrap will be asked to provide. See - the routine description for gss_wrap for - more details. - - req_output_size Integer, read - The desired maximum size for tokens emitted - by gss_wrap. - - max_input_size Integer, modify - The maximum input message size that may - be presented to gss_wrap in order to - guarantee that the emitted token shall - be no larger than req_output_size bytes. - - Function value: GSS status code - - GSS_S_COMPLETE Successful completion - - GSS_S_NO_CONTEXT The referenced context could not be accessed. - - GSS_S_CONTEXT_EXPIRED The context has expired. - - GSS_S_BAD_QOP The specified QOP is not supported by the mechanism. - - - - - - - - - - - - - - - - - - - - - Wray Document Expiration: 1 September 1997 [Page 78] - - - - - - - - INTERNET-DRAFT GSS-API V2 - C bindings March 1997 - - - - APPENDIX A. GSS-API C header file gssapi.h - - C-language GSS-API implementations should include a copy of the - following header-file. - - #ifndef GSSAPI_H_ - #define GSSAPI_H_ - - - - /* - * First, include stddef.h to get size_t defined. - */ - #include - - /* - * If the platform supports the xom.h header file, it should be - * included here. - */ - #include - - - - /* - * Now define the three implementation-dependent types. - */ - typedef gss_ctx_id_t; - typedef gss_cred_id_t; - typedef gss_name_t; - - /* - * The following type must be defined as the smallest natural - * unsigned integer supported by the platform that has at least - * 32 bits of precision. - */ - typedef gss_uint32; - - - #ifdef OM_STRING - /* - * We have included the xom.h header file. Verify that OM_uint32 - * is defined correctly. - */ - - #if sizeof(gss_uint32) != sizeof(OM_uint32) - #error Incompatible definition of OM_uint32 from xom.h - #endif - - typedef OM_object_identifier gss_OID_desc, *gss_OID; - - #else - - - - Wray Document Expiration: 1 September 1997 [Page 79] - - - - - - - - INTERNET-DRAFT GSS-API V2 - C bindings March 1997 - - - - /* - * We can't use X/Open definitions, so roll our own. - */ - - typedef gss_uint32 OM_uint32; - - typedef struct gss_OID_desc_struct { - OM_uint32 length; - void *elements; - } gss_OID_desc, *gss_OID; - - #endif - - typedef struct gss_OID_set_desc_struct { - size_t count; - gss_OID elements; - } gss_OID_set_desc, *gss_OID_set; - - typedef struct gss_buffer_desc_struct { - size_t length; - void *value; - } gss_buffer_desc, *gss_buffer_t; - - typedef struct gss_channel_bindings_struct { - OM_uint32 initiator_addrtype; - gss_buffer_desc initiator_address; - OM_uint32 acceptor_addrtype; - gss_buffer_desc acceptor_address; - gss_buffer_desc application_data; - } *gss_channel_bindings_t; - - - /* - * For now, define a QOP-type as an OM_uint32 - */ - typedef OM_uint32 gss_qop_t; - - typedef int gss_cred_usage_t; - - /* - * Flag bits for context-level services. - */ - #define GSS_C_DELEG_FLAG 1 - #define GSS_C_MUTUAL_FLAG 2 - #define GSS_C_REPLAY_FLAG 4 - #define GSS_C_SEQUENCE_FLAG 8 - #define GSS_C_CONF_FLAG 16 - #define GSS_C_INTEG_FLAG 32 - #define GSS_C_ANON_FLAG 64 - #define GSS_C_PROT_READY_FLAG 128 - #define GSS_C_TRANS_FLAG 256 - - - - Wray Document Expiration: 1 September 1997 [Page 80] - - - - - - - - INTERNET-DRAFT GSS-API V2 - C bindings March 1997 - - - - /* - * Credential usage options - */ - #define GSS_C_BOTH 0 - #define GSS_C_INITIATE 1 - #define GSS_C_ACCEPT 2 - - /* - * Status code types for gss_display_status - */ - #define GSS_C_GSS_CODE 1 - #define GSS_C_MECH_CODE 2 - - /* - * The constant definitions for channel-bindings address families - */ - #define GSS_C_AF_UNSPEC 0 - #define GSS_C_AF_LOCAL 1 - #define GSS_C_AF_INET 2 - #define GSS_C_AF_IMPLINK 3 - #define GSS_C_AF_PUP 4 - #define GSS_C_AF_CHAOS 5 - #define GSS_C_AF_NS 6 - #define GSS_C_AF_NBS 7 - #define GSS_C_AF_ECMA 8 - #define GSS_C_AF_DATAKIT 9 - #define GSS_C_AF_CCITT 10 - #define GSS_C_AF_SNA 11 - #define GSS_C_AF_DECnet 12 - #define GSS_C_AF_DLI 13 - #define GSS_C_AF_LAT 14 - #define GSS_C_AF_HYLINK 15 - #define GSS_C_AF_APPLETALK 16 - #define GSS_C_AF_BSC 17 - #define GSS_C_AF_DSS 18 - #define GSS_C_AF_OSI 19 - #define GSS_C_AF_X25 21 - - #define GSS_C_AF_NULLADDR 255 - - /* - * Various Null values - */ - #define GSS_C_NO_NAME ((gss_name_t) 0) - #define GSS_C_NO_BUFFER ((gss_buffer_t) 0) - #define GSS_C_NO_OID ((gss_OID) 0) - #define GSS_C_NO_OID_SET ((gss_OID_set) 0) - #define GSS_C_NO_CONTEXT ((gss_ctx_id_t) 0) - #define GSS_C_NO_CREDENTIAL ((gss_cred_id_t) 0) - #define GSS_C_NO_CHANNEL_BINDINGS ((gss_channel_bindings_t) 0) - #define GSS_C_EMPTY_BUFFER {0, NULL} - - - - Wray Document Expiration: 1 September 1997 [Page 81] - - - - - - - - INTERNET-DRAFT GSS-API V2 - C bindings March 1997 - - - - /* - * Some alternate names for a couple of the above - * values. These are defined for V1 compatibility. - */ - #define GSS_C_NULL_OID GSS_C_NO_OID - #define GSS_C_NULL_OID_SET GSS_C_NO_OID_SET - - /* - * Define the default Quality of Protection for per-message - * services. Note that an implementation that offers multiple - * levels of QOP may define GSS_C_QOP_DEFAULT to be either zero - * (as done here) to mean "default protection", or to a specific - * explicit QOP value. However, a value of 0 should always be - * interpreted by a GSSAPI implementation as a request for the - * default protection level. - */ - #define GSS_C_QOP_DEFAULT 0 - - /* - * Expiration time of 2^32-1 seconds means infinite lifetime for a - * credential or security context - */ - #define GSS_C_INDEFINITE 0xfffffffful - - /* - * The implementation must reserve static storage for a - * gss_OID_desc object containing the value - * {10, (void *)"\x2a\x86\x48\x86\xf7\x12" - * "\x01\x02\x01\x01"}, - * corresponding to an object-identifier value of - * {iso(1) member-body(2) United States(840) mit(113554) - * infosys(1) gssapi(2) generic(1) user_name(1)}. The constant - * GSS_C_NT_USER_NAME should be initialized to point - * to that gss_OID_desc. - */ - extern gss_OID GSS_C_NT_USER_NAME; - - /* - * The implementation must reserve static storage for a - * gss_OID_desc object containing the value - * {10, (void *)"\x2a\x86\x48\x86\xf7\x12" - * "\x01\x02\x01\x02"}, - * corresponding to an object-identifier value of - * {iso(1) member-body(2) United States(840) mit(113554) - * infosys(1) gssapi(2) generic(1) machine_uid_name(2)}. - * The constant GSS_C_NT_MACHINE_UID_NAME should be - * initialized to point to that gss_OID_desc. - */ - extern gss_OID GSS_C_NT_MACHINE_UID_NAME; - - /* - - - - Wray Document Expiration: 1 September 1997 [Page 82] - - - - - - - - INTERNET-DRAFT GSS-API V2 - C bindings March 1997 - - - - * The implementation must reserve static storage for a - * gss_OID_desc object containing the value - * {10, (void *)"\x2a\x86\x48\x86\xf7\x12" - * "\x01\x02\x01\x03"}, - * corresponding to an object-identifier value of - * {iso(1) member-body(2) United States(840) mit(113554) - * infosys(1) gssapi(2) generic(1) string_uid_name(3)}. - * The constant GSS_C_NT_STRING_UID_NAME should be - * initialized to point to that gss_OID_desc. - */ - extern gss_OID GSS_C_NT_STRING_UID_NAME; - - /* - * The implementation must reserve static storage for a - * gss_OID_desc object containing the value - * {6, (void *)"\x2b\x06\x01\x05\x06\x02"}, - * corresponding to an object-identifier value of - * {1(iso), 3(org), 6(dod), 1(internet), 5(security), - * 6(nametypes), 2(gss-host-based-services)}. The constant - * GSS_C_NT_HOSTBASED_SERVICE should be initialized to point - * to that gss_OID_desc. - */ - extern gss_OID GSS_C_NT_HOSTBASED_SERVICE; - - /* - * The implementation must reserve static storage for a - * gss_OID_desc object containing the value - * {6, (void *)"\x2b\x06\01\x05\x06\x03"}, - * corresponding to an object identifier value of - * {1(iso), 3(org), 6(dod), 1(internet), 5(security), - * 6(nametypes), 3(gss-anonymous-name)}. The constant - * and GSS_C_NT_ANONYMOUS should be initialized to point - * to that gss_OID_desc. - */ - extern gss_OID GSS_C_NT_ANONYMOUS; - - - - /* - * The implementation must reserve static storage for a - * gss_OID_desc object containing the value - * {6, (void *)"\x2b\x06\x01\x05\x06\x04"}, - * corresponding to an object-identifier value of - * {1(iso), 3(org), 6(dod), 1(internet), 5(security), - * 6(nametypes), 4(gss-api-exported-name)}. The constant - * GSS_C_NT_EXPORT_NAME should be initialized to point - * to that gss_OID_desc. - */ - extern gss_OID GSS_C_NT_EXPORT_NAME; - - - - - - Wray Document Expiration: 1 September 1997 [Page 83] - - - - - - - - INTERNET-DRAFT GSS-API V2 - C bindings March 1997 - - - - /* Major status codes */ - - #define GSS_S_COMPLETE 0 - - /* - * Some "helper" definitions to make the status code macros obvious. - */ - #define GSS_C_CALLING_ERROR_OFFSET 24 - #define GSS_C_ROUTINE_ERROR_OFFSET 16 - #define GSS_C_SUPPLEMENTARY_OFFSET 0 - #define GSS_C_CALLING_ERROR_MASK 0377ul - #define GSS_C_ROUTINE_ERROR_MASK 0377ul - #define GSS_C_SUPPLEMENTARY_MASK 0177777ul - - /* - * The macros that test status codes for error conditions. - * Note that the GSS_ERROR() macro has changed slightly from - * the V1 GSSAPI so that it now evaluates its argument - * only once. - */ - #define GSS_CALLING_ERROR(x) \ - (x & (GSS_C_CALLING_ERROR_MASK << GSS_C_CALLING_ERROR_OFFSET)) - #define GSS_ROUTINE_ERROR(x) \ - (x & (GSS_C_ROUTINE_ERROR_MASK << GSS_C_ROUTINE_ERROR_OFFSET)) - #define GSS_SUPPLEMENTARY_INFO(x) \ - (x & (GSS_C_SUPPLEMENTARY_MASK << GSS_C_SUPPLEMENTARY_OFFSET)) - #define GSS_ERROR(x) \ - (x & ((GSS_C_CALLING_ERROR_MASK << GSS_C_CALLING_ERROR_OFFSET) | \ - (GSS_C_ROUTINE_ERROR_MASK << GSS_C_ROUTINE_ERROR_OFFSET))) - - - /* - * Now the actual status code definitions - */ - - /* - * Calling errors: - */ - #define GSS_S_CALL_INACCESSIBLE_READ \ - (1ul << GSS_C_CALLING_ERROR_OFFSET) - #define GSS_S_CALL_INACCESSIBLE_WRITE \ - (2ul << GSS_C_CALLING_ERROR_OFFSET) - #define GSS_S_CALL_BAD_STRUCTURE \ - (3ul << GSS_C_CALLING_ERROR_OFFSET) - - /* - * Routine errors: - */ - #define GSS_S_BAD_MECH (1ul << GSS_C_ROUTINE_ERROR_OFFSET) - #define GSS_S_BAD_NAME (2ul << GSS_C_ROUTINE_ERROR_OFFSET) - #define GSS_S_BAD_NAMETYPE (3ul << GSS_C_ROUTINE_ERROR_OFFSET) - - - - Wray Document Expiration: 1 September 1997 [Page 84] - - - - - - - - INTERNET-DRAFT GSS-API V2 - C bindings March 1997 - - - - #define GSS_S_BAD_BINDINGS (4ul << GSS_C_ROUTINE_ERROR_OFFSET) - #define GSS_S_BAD_STATUS (5ul << GSS_C_ROUTINE_ERROR_OFFSET) - #define GSS_S_BAD_SIG (6ul << GSS_C_ROUTINE_ERROR_OFFSET) - #define GSS_S_BAD_MIC GSS_S_BAD_SIG - #define GSS_S_NO_CRED (7ul << GSS_C_ROUTINE_ERROR_OFFSET) - #define GSS_S_NO_CONTEXT (8ul << GSS_C_ROUTINE_ERROR_OFFSET) - #define GSS_S_DEFECTIVE_TOKEN (9ul << GSS_C_ROUTINE_ERROR_OFFSET) - #define GSS_S_DEFECTIVE_CREDENTIAL (10ul << GSS_C_ROUTINE_ERROR_OFFSET) - #define GSS_S_CREDENTIALS_EXPIRED (11ul << GSS_C_ROUTINE_ERROR_OFFSET) - #define GSS_S_CONTEXT_EXPIRED (12ul << GSS_C_ROUTINE_ERROR_OFFSET) - #define GSS_S_FAILURE (13ul << GSS_C_ROUTINE_ERROR_OFFSET) - #define GSS_S_BAD_QOP (14ul << GSS_C_ROUTINE_ERROR_OFFSET) - #define GSS_S_UNAUTHORIZED (15ul << GSS_C_ROUTINE_ERROR_OFFSET) - #define GSS_S_UNAVAILABLE (16ul << GSS_C_ROUTINE_ERROR_OFFSET) - #define GSS_S_DUPLICATE_ELEMENT (17ul << GSS_C_ROUTINE_ERROR_OFFSET) - #define GSS_S_NAME_NOT_MN (18ul << GSS_C_ROUTINE_ERROR_OFFSET) - - /* - * Supplementary info bits: - */ - #define GSS_S_CONTINUE_NEEDED (1ul << (GSS_C_SUPPLEMENTARY_OFFSET + 0)) - #define GSS_S_DUPLICATE_TOKEN (1ul << (GSS_C_SUPPLEMENTARY_OFFSET + 1)) - #define GSS_S_OLD_TOKEN (1ul << (GSS_C_SUPPLEMENTARY_OFFSET + 2)) - #define GSS_S_UNSEQ_TOKEN (1ul << (GSS_C_SUPPLEMENTARY_OFFSET + 3)) - #define GSS_S_GAP_TOKEN (1ul << (GSS_C_SUPPLEMENTARY_OFFSET + 4)) - - - /* - * Finally, function prototypes for the GSS-API routines. - */ - - OM_uint32 gss_acquire_cred - (OM_uint32 *, /* minor_status */ - const gss_name_t, /* desired_name */ - OM_uint32, /* time_req */ - const gss_OID_set, /* desired_mechs */ - gss_cred_usage_t, /* cred_usage */ - gss_cred_id_t *, /* output_cred_handle */ - gss_OID_set *, /* actual_mechs */ - OM_uint32 * /* time_rec */ - ); - - OM_uint32 gss_release_cred - (OM_uint32 *, /* minor_status */ - gss_cred_id_t * /* cred_handle */ - ); - - OM_uint32 gss_init_sec_context - (OM_uint32 *, /* minor_status */ - const gss_cred_id_t, /* initiator_cred_handle */ - gss_ctx_id_t *, /* context_handle */ - - - - Wray Document Expiration: 1 September 1997 [Page 85] - - - - - - - - INTERNET-DRAFT GSS-API V2 - C bindings March 1997 - - - - const gss_name_t, /* target_name */ - const gss_OID, /* mech_type */ - OM_uint32, /* req_flags */ - OM_uint32, /* time_req */ - const gss_channel_bindings_t, - /* input_chan_bindings */ - const gss_buffer_t, /* input_token */ - gss_OID *, /* actual_mech_type */ - gss_buffer_t, /* output_token */ - OM_uint32 *, /* ret_flags */ - OM_uint32 * /* time_rec */ - ); - - OM_uint32 gss_accept_sec_context - (OM_uint32 *, /* minor_status */ - gss_ctx_id_t *, /* context_handle */ - const gss_cred_id_t, /* acceptor_cred_handle */ - const gss_buffer_t, /* input_token_buffer */ - const gss_channel_bindings_t, - /* input_chan_bindings */ - gss_name_t *, /* src_name */ - gss_OID *, /* mech_type */ - gss_buffer_t, /* output_token */ - OM_uint32 *, /* ret_flags */ - OM_uint32 *, /* time_rec */ - gss_cred_id_t * /* delegated_cred_handle */ - ); - - OM_uint32 gss_process_context_token - (OM_uint32 *, /* minor_status */ - const gss_ctx_id_t, /* context_handle */ - const gss_buffer_t /* token_buffer */ - ); - - OM_uint32 gss_delete_sec_context - (OM_uint32 *, /* minor_status */ - gss_ctx_id_t *, /* context_handle */ - gss_buffer_t /* output_token */ - ); - - OM_uint32 gss_context_time - (OM_uint32 *, /* minor_status */ - const gss_ctx_id_t, /* context_handle */ - OM_uint32 * /* time_rec */ - ); - - OM_uint32 gss_get_mic - (OM_uint32 *, /* minor_status */ - const gss_ctx_id_t, /* context_handle */ - gss_qop_t, /* qop_req */ - const gss_buffer_t, /* message_buffer */ - - - - Wray Document Expiration: 1 September 1997 [Page 86] - - - - - - - - INTERNET-DRAFT GSS-API V2 - C bindings March 1997 - - - - gss_buffer_t /* message_token */ - ); - - - OM_uint32 gss_verify_mic - (OM_uint32 *, /* minor_status */ - const gss_ctx_id_t, /* context_handle */ - const gss_buffer_t, /* message_buffer */ - const gss_buffer_t, /* token_buffer */ - gss_qop_t * /* qop_state */ - ); - - OM_uint32 gss_wrap - (OM_uint32 *, /* minor_status */ - const gss_ctx_id_t, /* context_handle */ - int, /* conf_req_flag */ - gss_qop_t, /* qop_req */ - const gss_buffer_t, /* input_message_buffer */ - int *, /* conf_state */ - gss_buffer_t /* output_message_buffer */ - ); - - - OM_uint32 gss_unwrap - (OM_uint32 *, /* minor_status */ - const gss_ctx_id_t, /* context_handle */ - const gss_buffer_t, /* input_message_buffer */ - gss_buffer_t, /* output_message_buffer */ - int *, /* conf_state */ - gss_qop_t * /* qop_state */ - ); - - - - OM_uint32 gss_display_status - (OM_uint32 *, /* minor_status */ - OM_uint32, /* status_value */ - int, /* status_type */ - const gss_OID, /* mech_type */ - OM_uint32 *, /* message_context */ - gss_buffer_t /* status_string */ - ); - - OM_uint32 gss_indicate_mechs - (OM_uint32 *, /* minor_status */ - gss_OID_set * /* mech_set */ - ); - - OM_uint32 gss_compare_name - (OM_uint32 *, /* minor_status */ - const gss_name_t, /* name1 */ - - - - Wray Document Expiration: 1 September 1997 [Page 87] - - - - - - - - INTERNET-DRAFT GSS-API V2 - C bindings March 1997 - - - - const gss_name_t, /* name2 */ - int * /* name_equal */ - ); - - OM_uint32 gss_display_name - (OM_uint32 *, /* minor_status */ - const gss_name_t, /* input_name */ - gss_buffer_t, /* output_name_buffer */ - gss_OID * /* output_name_type */ - ); - - OM_uint32 gss_import_name - (OM_uint32 *, /* minor_status */ - const gss_buffer_t, /* input_name_buffer */ - const gss_OID, /* input_name_type */ - gss_name_t * /* output_name */ - ); - - OM_uint32 gss_export_name - (OM_uint32 *, /* minor_status */ - const gss_name_t, /* input_name */ - gss_buffer_t /* exported_name */ - ); - - OM_uint32 gss_release_name - (OM_uint32 *, /* minor_status */ - gss_name_t * /* input_name */ - ); - - OM_uint32 gss_release_buffer - (OM_uint32 *, /* minor_status */ - gss_buffer_t /* buffer */ - ); - - OM_uint32 gss_release_oid_set - (OM_uint32 *, /* minor_status */ - gss_OID_set * /* set */ - ); - - OM_uint32 gss_inquire_cred - (OM_uint32 *, /* minor_status */ - const gss_cred_id_t, /* cred_handle */ - gss_name_t *, /* name */ - OM_uint32 *, /* lifetime */ - gss_cred_usage_t *, /* cred_usage */ - gss_OID_set * /* mechanisms */ - ); - - OM_uint32 gss_inquire_context ( - OM_uint32 *, /* minor_status */ - const gss_ctx_id_t, /* context_handle */ - - - - Wray Document Expiration: 1 September 1997 [Page 88] - - - - - - - - INTERNET-DRAFT GSS-API V2 - C bindings March 1997 - - - - gss_name_t *, /* src_name */ - gss_name_t *, /* targ_name */ - OM_uint32 *, /* lifetime_rec */ - gss_OID *, /* mech_type */ - OM_uint32 *, /* ctx_flags */ - int *, /* locally_initiated */ - int * /* open */ - ); - - OM_uint32 gss_wrap_size_limit ( - OM_uint32 *, /* minor_status */ - const gss_ctx_id_t, /* context_handle */ - int, /* conf_req_flag */ - gss_qop_t, /* qop_req */ - OM_uint32, /* req_output_size */ - OM_uint32 * /* max_input_size */ - ); - - - OM_uint32 gss_add_cred ( - OM_uint32 *, /* minor_status */ - const gss_cred_id_t, /* input_cred_handle */ - const gss_name_t, /* desired_name */ - const gss_OID, /* desired_mech */ - gss_cred_usage_t, /* cred_usage */ - OM_uint32, /* initiator_time_req */ - OM_uint32, /* acceptor_time_req */ - gss_cred_id_t *, /* output_cred_handle */ - gss_OID_set *, /* actual_mechs */ - OM_uint32 *, /* initiator_time_rec */ - OM_uint32 * /* acceptor_time_rec */ - ); - - - OM_uint32 gss_inquire_cred_by_mech ( - OM_uint32 *, /* minor_status */ - const gss_cred_id_t, /* cred_handle */ - const gss_OID, /* mech_type */ - gss_name_t *, /* name */ - OM_uint32 *, /* initiator_lifetime */ - OM_uint32 *, /* acceptor_lifetime */ - gss_cred_usage_t * /* cred_usage */ - ); - - OM_uint32 gss_export_sec_context ( - OM_uint32 *, /* minor_status */ - gss_ctx_id_t *, /* context_handle */ - gss_buffer_t /* interprocess_token */ - ); - - OM_uint32 gss_import_sec_context ( - - - - Wray Document Expiration: 1 September 1997 [Page 89] - - - - - - - - INTERNET-DRAFT GSS-API V2 - C bindings March 1997 - - - - OM_uint32 *, /* minor_status */ - const gss_buffer_t, /* interprocess_token */ - gss_ctx_id_t * /* context_handle */ - ); - - OM_uint32 gss_create_empty_oid_set ( - OM_uint32 *, /* minor_status */ - gss_OID_set * /* oid_set */ - ); - - OM_uint32 gss_add_oid_set_member ( - OM_uint32 *, /* minor_status */ - const gss_OID, /* member_oid */ - gss_OID_set * /* oid_set */ - ); - - OM_uint32 gss_test_oid_set_member ( - OM_uint32 *, /* minor_status */ - const gss_OID, /* member */ - const gss_OID_set, /* set */ - int * /* present */ - ); - - OM_uint32 gss_inquire_names_for_mech ( - OM_uint32 *, /* minor_status */ - const gss_OID, /* mechanism */ - gss_OID_set * /* name_types */ - ); - - OM_uint32 gss_inquire_mechs_for_name ( - OM_uint32 *, /* minor_status */ - const gss_name_t, /* input_name */ - gss_OID_set * /* mech_types */ - ); - - OM_uint32 gss_canonicalize_name ( - OM_uint32 *, /* minor_status */ - const gss_name_t, /* input_name */ - const gss_OID, /* mech_type */ - gss_name_t * /* output_name */ - ); - - OM_uint32 gss_duplicate_name ( - OM_uint32 *, /* minor_status */ - const gss_name_t, /* src_name */ - gss_name_t * /* dest_name */ - ); - - /* - * The following routines are obsolete variants of gss_get_mic, - * gss_verify_mic, gss_wrap and gss_unwrap. They should be - - - - Wray Document Expiration: 1 September 1997 [Page 90] - - - - - - - - INTERNET-DRAFT GSS-API V2 - C bindings March 1997 - - - - * provided by GSSAPI V2 implementations for backwards - * compatibility with V1 applications. Distinct entrypoints - * (as opposed to #defines) should be provided, both to allow - * GSSAPI V1 applications to link against GSSAPI V2 implementations, - * and to retain the slight parameter type differences between the - * obsolete versions of these routines and their current forms. - */ - - OM_uint32 gss_sign - (OM_uint32 *, /* minor_status */ - gss_ctx_id_t, /* context_handle */ - int, /* qop_req */ - gss_buffer_t, /* message_buffer */ - gss_buffer_t /* message_token */ - ); - - - OM_uint32 gss_verify - (OM_uint32 *, /* minor_status */ - gss_ctx_id_t, /* context_handle */ - gss_buffer_t, /* message_buffer */ - gss_buffer_t, /* token_buffer */ - int * /* qop_state */ - ); - - OM_uint32 gss_seal - (OM_uint32 *, /* minor_status */ - gss_ctx_id_t, /* context_handle */ - int, /* conf_req_flag */ - int, /* qop_req */ - gss_buffer_t, /* input_message_buffer */ - int *, /* conf_state */ - gss_buffer_t /* output_message_buffer */ - ); - - - OM_uint32 gss_unseal - (OM_uint32 *, /* minor_status */ - gss_ctx_id_t, /* context_handle */ - gss_buffer_t, /* input_message_buffer */ - gss_buffer_t, /* output_message_buffer */ - int *, /* conf_state */ - int * /* qop_state */ - ); - - - - - #endif /* GSSAPI_H_ */ - - - - - - Wray Document Expiration: 1 September 1997 [Page 91] - - - - - - - - INTERNET-DRAFT GSS-API V2 - C bindings March 1997 - - - - APPENDIX B. Additional constraints for application binary portability - - The purpose of this C-bindings document is to encourage source-level - portability of applications across GSS-API implementations on different - platforms and atop different mechanisms. Additional goals that have not - been explicitly addressed by this document are link-time and run-time - portability. - - Link-time portability provides the ability to compile an application - against one implementation of GSS-API, and then link it against a - different implementation on the same platform. It is a stricter - requirement than source-level portability. - - Run-time portability differs from link-time portability only on those - platforms that implement dynamically loadable GSS-API implementations, - but do not offer load-time symbol resolution. On such platforms, run- - time portability is a stricter requirement than link-time portability, - and will typically include the precise placement of the various GSS-API - routines within library entrypoint vectors. - - Individual platforms will impose their own rules that must be followed - to achieve link-time (and run-time, if different) portability. In order - to ensure either form of binary portability, an ABI specification must - be written for GSS-API implementations on that platform. However, it is - recognized that there are some issues that are likely to be common to - all such ABI specifications. This appendix is intended to be a - repository for such common issues, and contains some suggestions that - individual ABI specifications may choose to reference. Since machine - architectures vary greatly, it may not be possible or desirable to - follow these suggestions on all platforms. - - B.1. Pointers - - While ANSI-C provides a single pointer type for each declared type, plus - a single (void *) type, some platforms (notably those using segmented - memory architectures) augment this with various modified pointer types - (e.g. far pointers, near pointers). These language bindings assume - ANSI-C, and thus do not address such non-standard implementations. - GSS-API implementations for such platforms must choose an appropriate - memory model, and should use it consistently throughout. For example, - if a memory model is chosen that requires the use of far pointers when - passing routine parameters, then far pointers should also be used within - the structures defined by GSS-API. - - B.2. Internal structure alignment - - GSS-API defines several data-structures containing differently-sized - fields. An ABI specification should include a detailed description of - how the fields of such structures are aligned, and if there is any - internal padding in these data structures. The use of compiler defaults - for the platform is recommended. - - - - Wray Document Expiration: 1 September 1997 [Page 92] - - - - - - - - INTERNET-DRAFT GSS-API V2 - C bindings March 1997 - - - - B.3. Handle types - - The C bindings specify that the gss_cred_id_t and gss_ctx_id_t types - should be implemented as either pointer or arithmetic types, and that if - pointer types are used, care should be taken to ensure that two handles - may be compared with the == operator. Note that ANSI-C does not - guarantee that two pointer values may be compared with the == operator - unless either the two pointers point to members of a single array, or at - least one of the pointers contains a NULL value. - - For binary portability, additional constraints are required. The - following is an attempt at defining platform-independent constraints. - - (a) The size of the handle type must be the same as sizeof(void *), - using the appropriate memory model. - - (b) The == operator for the chosen type must be a simple bit-wise - comparison. That is, for two in-memory handle objects h1 and h2, - the boolean value of the expression - - (h1 == h2) - - should always be the same as the boolean value of the expression - - (memcmp(&h1, &h2, sizeof(h1)) == 0) - - (c) The actual use of the type (void *) for handle types is - discouraged, not for binary portability reasons, but since it - effectively disables much of the compile-time type-checking that - the compiler can otherwise perform, and is therefore not - "programmer-friendly". If a pointer implementation is desired, - and if the platform's implementation of pointers permits, the - handles should be implemented as pointers to distinct - implementation-defined types. - - B.4. The gss_name_t type - - The gss_name_t type, representing the internal name object, should be - implemented as a pointer type. The use of the (void *) type is - discouraged as it does not allow the compiler to perform strong type- - checking. However, the pointer type chosen should be of the same size - as the (void *) type. Provided this rule is obeyed, ABI specifications - need not further constrain the implementation of gss_name_t objects. - - B.5. The int and size_t types - - Some platforms may support differently sized implementations of the - "int" and "size_t" types, perhaps chosen through compiler switches, and - perhaps dependent on memory model. An ABI specification for such a - platform should include required implementations for these types. It is - recommended that the default implementation (for the chosen memory - - - - Wray Document Expiration: 1 September 1997 [Page 93] - - - - - - - - INTERNET-DRAFT GSS-API V2 - C bindings March 1997 - - - - model, if appropriate) is chosen. - - B.6. Procedure-calling conventions - - Some platforms support a variety of different binary conventions for - calling procedures. Such conventions cover things like the format of - the stack frame, the order in which the routine parameters are pushed - onto the stack, whether or not a parameter count is pushed onto the - stack, whether some argument(s) or return values are to be passed in - registers, and whether the called routine or the caller is responsible - for removing the stack frame on return. For such platforms, an ABI - specification should specify which calling convention is to be used for - GSSAPI implementations. - - - REFERENCES - - [GSSAPI] J. Linn, "Generic Security Service Application Program - Interface, Version 2", Internet-Draft draft-ietf-cat-gssv2- - 08, 26 August 1996. (This Internet-Draft, like all other - Internet-Drafts, is not an archival document and is subject - to change or deletion. It is available at the time of this - writing by anonymous ftp from ds.internic.net, directory - internet-drafts. Would-be readers should check for successor - Internet-Draft versions or Internet RFCs before relying on - this document.) - - [XOM] OSI Object Management API Specification, Version 2.0 t", - X.400 API Association & X/Open Company Limited, August 24, - 1990. Specification of datatypes and routines for - manipulating information objects. - - - AUTHOR'S ADDRESS - - John Wray Internet email: Wray@tuxedo.enet.dec.com - Digital Equipment Corporation Telephone: +1-508-486-5210 - 550 King Street, LKG2-2/Z7 - Littleton, MA 01460 - USA - - - - - - - - - - - - - - - Wray Document Expiration: 1 September 1997 [Page 94] - - - diff --git a/doc/draft-ietf-cat-kerb-chg-password-02.txt b/doc/draft-ietf-cat-kerb-chg-password-02.txt deleted file mode 100644 index e235bec58..000000000 --- a/doc/draft-ietf-cat-kerb-chg-password-02.txt +++ /dev/null @@ -1,311 +0,0 @@ - - - - -Network Working Group M. Horowitz - Stonecast, Inc. -Internet-Draft August, 1998 - - Kerberos Change Password Protocol - -Status of this Memo - - This document is an Internet-Draft. Internet-Drafts are working - documents of the Internet Engineering Task Force (IETF), its areas, - and its working groups. Note that other groups may also distribute - working documents as Internet-Drafts. - - Internet-Drafts are draft documents valid for a maximum of six months - and may be updated, replaced, or obsoleted by other documents at any - time. It is inappropriate to use Internet-Drafts as reference - material or to cite them other than as ``work in progress.'' - - To learn the current status of any Internet-Draft, please check the - ``1id-abstracts.txt'' listing contained in the Internet-Drafts Shadow - Directories on ftp.ietf.org (US East Coast), nic.nordu.net - (Europe), ftp.isi.edu (US West Coast), or munnari.oz.au (Pacific - Rim). - - Distribution of this memo is unlimited. Please send comments to the - mailing list. - -Abstract - - The Kerberos V5 protocol [RFC1510] does not describe any mechanism - for users to change their own passwords. In order to promote - interoperability between workstations, personal computers, terminal - servers, routers, and KDC's from multiple vendors, a common password - changing protocol is required. - - - -Overview - - When a user wishes to change his own password, or is required to by - local policy, a simple request of a password changing service is - necessary. This service must be implemented on at least one host for - each Kerberos realm, probably on one of the kdc's for that realm. - The service must accept requests on UDP port 464 (kpasswd), and may - accept requests on TCP port 464 as well. - - The protocol itself consists of a single request message followed by - a single reply message. For UDP transport, each message must be - fully contained in a single UDP packet. - - - - - - - - -Horowitz [Page 1] - -Internet Draft Kerberos Change Password Protocol August, 1998 - - -Request Message - - 0 1 2 3 - 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | message length | protocol version number | - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | AP_REQ length | AP-REQ data / - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - / KRB-PRIV message / - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - - message length (16 bits) - Contains the length of the message, including this field, in bytes - (big-endian integer) - protocol version number (16 bits) - Contains the hex constant 0x0001 (big-endian integer) - AP-REQ length (16 bits) - length (big-endian integer) of AP-REQ data, in bytes. - AP-REQ data, as described in RFC1510 (variable length) - This AP-REQ must be for the service principal - kadmin/changepw@REALM, where REALM is the REALM of the user who - wishes to change his password. The Ticket in the AP-REQ must be - derived from an AS request (thus having the INITIAL flag set), and - must include a subkey in the Authenticator. - KRB-PRIV message, as described in RFC1510 (variable length) - This KRB-PRIV message must be generated using the subkey in the - Authenticator in the AP-REQ data. The user-data component of the - message must consist of the user's new password. - - The server must verify the AP-REQ message, decrypt the new password, - perform any local policy checks (such as password quality, history, - authorization, etc.) required, then set the password to the new value - specified. - - The principal whose password is to be changed is the principal which - authenticated to the password changing service. This protocol does - not address administrators who want to change passwords of principal - besides their own. - - -Reply Message - - 0 1 2 3 - 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | message length | protocol version number | - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | AP_REP length | AP-REP data / - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - / KRB-PRIV or KRB-ERROR message / - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - - message length (16 bits) - - - -Horowitz [Page 2] - -Internet Draft Kerberos Change Password Protocol August, 1998 - - - Contains the length of the message, including this field, in bytes - (big-endian integer), - protocol version number (16 bits) - Contains the hex constant 0x0001 (big-endian integer) - AP-REP length (16 bits) - length of AP-REP data, in bytes. If the the length is zero, then - the last field will contain a KRB-ERROR message instead of a KRB- - PRIV message. - AP-REP data, as described in RFC1510 (variable length) - The AP-REP corresponding to the AP-REQ in the request packet. - KRB-PRIV or KRB-ERROR message, as described in RFC1510 (variable - length) - If the AP-REP length is zero, then this field contains a KRB-ERROR - message. Otherwise, it contains a KRB-PRIV message. This KRB- - PRIV message must be generated using the subkey in the - Authenticator in the AP-REQ data. - - The user-data component of the KRB-PRIV message, or e-data - component of the KRB-ERROR message, must consist of the following - data: - - 0 1 2 3 - 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | result code | result string / - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - - result code (16 bits) - The result code must have one of the following values (big- - endian integer): - 0x0000 if the request succeeds. (This value is not permitted - in a KRB-ERROR message.) - 0x0001 if the request fails due to being malformed - 0x0002 if the request fails due to a "hard" error processing - the request (for example, there is a resource or other - problem causing the request to fail) - 0x0003 if the request fails due to an error in authentication - processing - 0x0004 if the request fails due to a "soft" error processing - the request (for example, some policy or other similar - consideration is causing the request to be rejected). - 0xFFFF if the request fails for some other reason. - Although only a few non-zero result codes are specified here, - the client should accept any non-zero result code as indicating - failure. - result string (variable length) - This field should contain information which the server thinks - might be useful to the user, such as feedback about policy - failures. The string must be encoded in UTF-8. It may be - omitted if the server does not wish to include it. If it is - present, the client should display the string to the user. - This field is analogous to the string which follows the numeric - code in SMTP, FTP, and similar protocols. - - - - -Horowitz [Page 3] - -Internet Draft Kerberos Change Password Protocol August, 1998 - - -Dropped and Modified Messages - - An attacker (or simply a lossy network) could cause either the - request or reply to be dropped, or modified by substituting a KRB- - ERROR message in the reply. - - If a request is dropped, no modification of the password/key database - will take place. If a reply is dropped, the server will (assuming a - valid request) make the password change. However, the client cannot - distinguish between these two cases. - - In this situation, the client should construct a new authenticator, - re-encrypt the request, and retransmit. If the original request was - lost, the server will treat this as a valid request, and the password - will be changed normally. If the reply was lost, then the server - should take care to notice that the request was a duplicate of the - prior request, because the "new" password is the current password, - and the password change time is within some implementation-defined - replay time window. The server should then return a success reply - (an AP-REP message with result code == 0x0000) without actually - changing the password or any other information (such as modification - timestamps). - - If a success reply was replaced with an error reply, then the - application performing the request would return an error to the user. - In this state, the user's password has been changed, but the user - believes that it has not. If the user attempts to change the - password again, this will probably fail, because the user cannot - successfully provide the old password to get an INITIAL ticket to - make the request. This situation requires administrative - intervention as if a password was lost. This situation is, - unfortunately, impossible to prevent. - - -Security Considerations - - This document deals with changing passwords for Kerberos. Because - Kerberos is used for authentication and key distribution, it is - important that this protocol use the highest level of security - services available to a particular installation. Mutual - authentication is performed, so that the server knows the request is - valid, and the client knows that the request has been received and - processed by the server. - - There are also security issues relating to dropped or modified - messages which are addressed explicitly. - - -References - - [RFC1510] Kohl, J. and Neuman, C., "The Kerberos Network - Authentication Service (V5)", RFC 1510, September 1993. - - - - - -Horowitz [Page 4] - -Internet Draft Kerberos Change Password Protocol August, 1998 - - -Author's Address - - Marc Horowitz - Stonecast, Inc. - 108 Stow Road - Harvard, MA 01451 - - Phone: +1 978 456 9103 - Email: marc@stonecast.net - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Horowitz [Page 5] - diff --git a/doc/draft-ietf-cat-kerb-des3-hmac-sha1-00.txt b/doc/draft-ietf-cat-kerb-des3-hmac-sha1-00.txt deleted file mode 100644 index 2583a84da..000000000 --- a/doc/draft-ietf-cat-kerb-des3-hmac-sha1-00.txt +++ /dev/null @@ -1,127 +0,0 @@ - - - - - - -Network Working Group M. Horowitz - Cygnus Solutions -Internet-Draft November, 1996 - - - Triple DES with HMAC-SHA1 Kerberos Encryption Type - -Status of this Memo - - This document is an Internet-Draft. Internet-Drafts are working - documents of the Internet Engineering Task Force (IETF), its areas, - and its working groups. Note that other groups may also distribute - working documents as Internet-Drafts. - - Internet-Drafts are draft documents valid for a maximum of six months - and may be updated, replaced, or obsoleted by other documents at any - time. It is inappropriate to use Internet-Drafts as reference - material or to cite them other than as ``work in progress.'' - - To learn the current status of any Internet-Draft, please check the - ``1id-abstracts.txt'' listing contained in the Internet-Drafts Shadow - Directories on ds.internic.net (US East Coast), nic.nordu.net - (Europe), ftp.isi.edu (US West Coast), or munnari.oz.au (Pacific - Rim). - - Distribution of this memo is unlimited. Please send comments to the - mailing list. - -Abstract - - This document defines a new encryption type and a new checksum type - for use with Kerberos V5 [RFC1510]. This encryption type is based on - the Triple DES cryptosystem and the HMAC-SHA1 [Krawczyk96] message - authentication algorithm. - - The des3-cbc-hmac-sha1 encryption type has been assigned the value 7. - The hmac-sha1-des3 checksum type has been assigned the value 12. - - -Encryption Type des3-cbc-hmac-sha1 - - EncryptedData using this type must be generated as described in - [Horowitz96]. The encryption algorithm is Triple DES in Outer-CBC - mode. The keyed hash algorithm is HMAC-SHA1. Unless otherwise - specified, a zero IV must be used. If the length of the input data - is not a multiple of the block size, zero octets must be used to pad - the plaintext to the next eight-octet boundary. The counfounder must - be eight random octets (one block). - - -Checksum Type hmac-sha1-des3 - - Checksums using this type must be generated as described in - [Horowitz96]. The keyed hash algorithm is HMAC-SHA1. - - - -Horowitz [Page 1] - -Internet Draft Kerberos Triple DES with HMAC-SHA1 November, 1996 - - -Common Requirements - - Where the Triple DES key is represented as an EncryptionKey, it shall - be represented as three DES keys, with parity bits, concatenated - together. The key shall be represented with the most significant bit - first. - - When keys are generated by the derivation function, a key length of - 168 bits shall be used. The output bit string will be converted to a - valid Triple DES key by inserting DES parity bits after every seventh - bit. - - Any implementation which implements either of the encryption or - checksum types in this document must support both. - - -Security Considerations - - This entire document defines encryption and checksum types for use - with Kerberos V5. - - -References - - [Horowitz96] Horowitz, M., "Key Derivation for Kerberos V5", draft- - horowitz-kerb-key-derivation-00.txt, November 1996. - [Krawczyk96] Krawczyk, H., Bellare, and M., Canetti, R., "HMAC: - Keyed-Hashing for Message Authentication", draft-ietf-ipsec-hmac- - md5-01.txt, August, 1996. - [RFC1510] Kohl, J. and Neuman, C., "The Kerberos Network - Authentication Service (V5)", RFC 1510, September 1993. - - -Author's Address - - Marc Horowitz - Cygnus Solutions - 955 Massachusetts Avenue - Cambridge, MA 02139 - - Phone: +1 617 354 7688 - Email: marc@cygnus.com - - - - - - - - - - - - - - - -Horowitz [Page 2] - diff --git a/doc/draft-ietf-cat-kerb-key-derivation-00.txt b/doc/draft-ietf-cat-kerb-key-derivation-00.txt deleted file mode 100644 index 46a415852..000000000 --- a/doc/draft-ietf-cat-kerb-key-derivation-00.txt +++ /dev/null @@ -1,250 +0,0 @@ - - - - - -Network Working Group M. Horowitz - Cygnus Solutions -Internet-Draft November, 1996 - - - Key Derivation for Kerberos V5 - -Status of this Memo - - This document is an Internet-Draft. Internet-Drafts are working - documents of the Internet Engineering Task Force (IETF), its areas, - and its working groups. Note that other groups may also distribute - working documents as Internet-Drafts. - - Internet-Drafts are draft documents valid for a maximum of six months - and may be updated, replaced, or obsoleted by other documents at any - time. It is inappropriate to use Internet-Drafts as reference - material or to cite them other than as ``work in progress.'' - - To learn the current status of any Internet-Draft, please check the - ``1id-abstracts.txt'' listing contained in the Internet-Drafts Shadow - Directories on ds.internic.net (US East Coast), nic.nordu.net - (Europe), ftp.isi.edu (US West Coast), or munnari.oz.au (Pacific - Rim). - - Distribution of this memo is unlimited. Please send comments to the - mailing list. - -Abstract - - In the Kerberos protocol [RFC1510], cryptographic keys are used in a - number of places. In order to minimize the effect of compromising a - key, it is desirable to use a different key for each of these places. - Key derivation [Horowitz96] can be used to construct different keys - for each operation from the keys transported on the network. For - this to be possible, a small change to the specification is - necessary. - - -Overview - - Under RFC1510 as stated, key derivation could be specified as a set - of encryption types which share the same key type. The constant for - each derivation would be a function of the encryption type. However, - it is generally accepted that, for interoperability, key types and - encryption types must map one-to-one onto each other. (RFC 1510 is - being revised to address this issue.) Therefore, to use key - derivcation with Kerberos V5 requires a small change to the - specification. - - For each place where a key is used in Kerberos, a ``key usage'' must - be specified for that purpose. The key, key usage, and - encryption/checksum type together describe the transformation from - plaintext to ciphertext, or plaintext to checksum. For backward - - - -Horowitz [Page 1] - -Internet Draft Key Derivation for Kerberos V5 November, 1996 - - - compatibility, old encryption types would be defined independently of - the key usage. - - -Key Usage Values - - This is a complete list of places keys are used in the kerberos - protocol, with key usage values and RFC 1510 section numbers: - - 1. AS-REQ PA-ENC-TIMESTAMP padata timestamp, encrypted with the - client key (section 5.4.1) - 2. AS-REP Ticket and TGS-REP Ticket (includes tgs session key or - application session key), encrypted with the service key - (section 5.4.2) - 3. AS-REP encrypted part (includes tgs session key or application - session key), encrypted with the client key (section 5.4.2) - - 4. TGS-REQ KDC-REQ-BODY AuthorizationData, encrypted with the tgs - session key (section 5.4.1) - 5. TGS-REQ KDC-REQ-BODY AuthorizationData, encrypted with the tgs - authenticator subkey (section 5.4.1) - 6. TGS-REQ PA-TGS-REQ padata AP-REQ Authenticator cksum, keyed - with the tgs session key (sections 5.3.2, 5.4.1) - 7. TGS-REQ PA-TGS-REQ padata AP-REQ Authenticator (includes tgs - authenticator subkey), encrypted with the tgs session key - (section 5.3.2) - 8. TGS-REP encrypted part (includes application session key), - encrypted with the tgs session key (section 5.4.2) - 9. TGS-REP encrypted part (includes application session key), - encrypted with the tgs authenticator subkey (section 5.4.2) - - 10. AP-REQ Authenticator cksum, keyed with the application session - key (section 5.3.2) - 11. AP-REQ Authenticator (includes application authenticator - subkey), encrypted with the application session key (section - 5.3.2) - 12. AP-REP encrypted part (includes application session subkey), - encrypted with the application session key (section 5.5.2) - - 13. KRB-PRIV encrypted part, encrypted with a key chosen by the - application (section 5.7.1) - 14. KRB-CRED encrypted part, encrypted with a key chosen by the - application (section 5.6.1) - 15. KRB-SAVE cksum, keyed with a key chosen by the application - (section 5.8.1) - - 16. Data which is defined in some specification outside of - Kerberos to be encrypted using an RFC1510 encryption type. - 17. Data which is defined in some specification outside of - Kerberos to be checksummed using an RFC1510 checksum type. - - A few of these key usages need a little clarification. A service - which receives an AP-REQ has no way to know if the enclosed Ticket - was part of an AS-REP or TGS-REP. Therefore, key usage 2 must always - - - -Horowitz [Page 2] - -Internet Draft Key Derivation for Kerberos V5 November, 1996 - - - be used for generating a Ticket, whether it is in response to an AS- - REQ or TGS-REQ. - - There might exist other documents which define protocols in terms of - the RFC1510 encryption types or checksum types. Such documents would - not know about key usages. In order that these documents continue to - be meaningful until they are updated, key usages 16 and 17 must be - used to derive keys for encryption and checksums, respectively. New - protocols defined in terms of the Kerberos encryption and checksum - types should use their own key usages. Key usages may be registered - with IANA to avoid conflicts. Key usages shall be unsigned 32 bit - integers. Zero is not permitted. - - -Defining Cryptosystems Using Key Derivation - - Kerberos requires that the ciphertext component of EncryptedData be - tamper-resistant as well as confidential. This implies encryption - and integrity functions, which must each use their own separate keys. - So, for each key usage, two keys must be generated, one for - encryption (Ke), and one for integrity (Ki): - - Ke = DK(protocol key, key usage | 0xAA) - Ki = DK(protocol key, key usage | 0x55) - - where the key usage is represented as a 32 bit integer in network - byte order. The ciphertest must be generated from the plaintext as - follows: - - ciphertext = E(Ke, confounder | length | plaintext | padding) | - H(Ki, confounder | length | plaintext | padding) - - The confounder and padding are specific to the encryption algorithm - E. - - When generating a checksum only, there is no need for a confounder or - padding. Again, a new key (Kc) must be used. Checksums must be - generated from the plaintext as follows: - - Kc = DK(protocol key, key usage | 0x99) - - MAC = H(Kc, length | plaintext) - - Note that each enctype is described by an encryption algorithm E and - a keyed hash algorithm H, and each checksum type is described by a - keyed hash algorithm H. HMAC, with an appropriate hash, is - recommended for use as H. - - -Security Considerations - - This entire document addresses shortcomings in the use of - cryptographic keys in Kerberos V5. - - - - -Horowitz [Page 3] - -Internet Draft Key Derivation for Kerberos V5 November, 1996 - - -Acknowledgements - - I would like to thank Uri Blumenthal, Sam Hartman, and Bill - Sommerfeld for their contributions to this document. - - -References - - [Horowitz96] Horowitz, M., "Key Derivation for Authentication, - Integrity, and Privacy", draft-horowitz-key-derivation-00.txt, - November 1996. [RFC1510] Kohl, J. and Neuman, C., "The Kerberos - Network Authentication Service (V5)", RFC 1510, September 1993. - - -Author's Address - - Marc Horowitz - Cygnus Solutions - 955 Massachusetts Avenue - Cambridge, MA 02139 - - Phone: +1 617 354 7688 - Email: marc@cygnus.com - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Horowitz [Page 4] - diff --git a/doc/draft-ietf-cat-kerberos-err-msg-00.txt b/doc/draft-ietf-cat-kerberos-err-msg-00.txt deleted file mode 100644 index c5e4d05e7..000000000 --- a/doc/draft-ietf-cat-kerberos-err-msg-00.txt +++ /dev/null @@ -1,252 +0,0 @@ - -INTERNET-DRAFT Ari Medvinsky -draft-ietf-cat-kerberos-err-msg-00.txt Matt Hur -Updates: RFC 1510 Dominique Brezinski -expires September 30, 1997 CyberSafe Corporation - Gene Tsudik - Brian Tung - ISI - -Integrity Protection for the Kerberos Error Message - -0. Status Of this Memo - - This document is an Internet-Draft. Internet-Drafts are working - documents of the Internet Engineering Task Force (IETF), its - areas, and its working groups. Note that other groups may also - distribute working documents as Internet-Drafts. - - Internet-Drafts are draft documents valid for a maximum of six - months and may be updated, replaced, or obsoleted by other - documents at any time. It is inappropriate to use Internet-Drafts - as reference material or to cite them other than as "work in - progress." - - To learn the current status of any Internet-Draft, please check - the "1id-abstracts.txt" listing contained in the Internet-Drafts - Shadow Directories on ds.internic.net (US East Coast), - nic.nordu.net (Europe), ftp.isi.edu (US West Coast), or - munnari.oz.au (Pacific Rim). - - The distribution of this memo is unlimited. It is filed as - draft-ietf-cat-kerberos-pk-init-03.txt, and expires June xx, 1997. - Please send comments to the authors. - -1. Abstract - - The Kerberos error message, as defined in RFC 1510, is transmitted - to the client without any integrity assurance. Therefore, the - client has no means to distinguish between a valid error message - sent from the KDC and one sent by an attacker. This draft describes - a method for assuring the integrity of Kerberos error messages, and - proposes a consistent format for the e-data field in the KRB_ERROR - message. This e-data format enables the storage of cryptographic - checksums by providing an extensible mechanism for specifying e-data - types. - - -2. Motivation - - In the Kerberos protocol [1], if an error occurs for AS_REQ, - TGS_REQ, or AP_REQ, a clear text error message is returned to the - client. An attacker may exploit this vulnerability by sending a - false error message as a reply to any of the above requests. For - example, an attacker may send the KDC_ERR_KEY_EXPIRED error message - in order to force a user to change their password in hope that the - new key will not be as strong as the current key, and thus, easier - to break. - - Since false error messages may be utilized by an attacker, a - Kerberos client should have a means for determining how much trust - to place in a given error message. The rest of this draft - describes a method for assuring the integrity of Kerberos error - messages. - - -3. Approach - - We propose taking a cryptographic checksum over the entire KRB-ERROR - message. This checksum would be returned as part of the error - message and would enable the client to verify the integrity of the - error message. For interoperability reasons, no new fields are - added to the KRB-ERROR message. Instead, the e-data field (see - figure 1) is utilized to carry the cryptographic checksum. - - -3.1 Cryptographic checksums in error messages for AS_REQ, - TGS_REQ & AP_REQ - - If an error occurs for the AS request, the only key that is - available to the KDC is the shared secret (the key derived from the - clients password) registered in the KDCs database. The KDC will - use this key to sign the error message, if and only if, the client - already proved knowledge of the shared secret in the AS request - (e.g. via PA-ENC-TIMESTAMP in preauth data). This policy is needed - to prevent an attacker from getting the KDC to send a signed error - message and then launching an off-line attack in order to obtain a - key of a given principal. - - If an error occurs for a TGS or an AP request, the server will use - the session key sealed in the clients ticket granting ticket to - compute the checksum over the error message. If the checksum could - not be computed (e.g. error while decrypting the ticket) the error - message is returned to the client without the checksum. The client - then has the option to treat unprotected error messages differently. - - - KRB-ERROR ::= [APPLICATION 30] SEQUENCE { - pvno [0] integer, - msg-type [1] integer, - ctime [2] KerberosTime OPTIONAL, - cusec [3] INTEGER OPTIONAL, - stime [4] KerberosTime, - susec [5] INTEGER, - error-code [6] INTEGER, - crealm [7] Realm OPTIONAL, - cname [8] PrincipalName OPTIONAL, - realm [9] Realm, --Correct realm - sname [10] PrincipalName, --Correct name - e-text [11] GeneralString OPTIONAL, - e-data [12] OCTET STRING OPTIONAL - } - Figure 1 - - -3.2 Format of the e-data field - - We propose to place the cryptographic checksum in the e-data field. - First, we review the format of the e-data field, as specified in - RFC 1510. The format of e-data is specified only in two cases [2]. - "If the error code is KDC_ERR_PREAUTH_REQUIRED, then the e-data - field will contain an encoding of a sequence of padata fields": - - METHOD-DATA ::= SEQUENCE of PA-DATA - PA-DATA ::= SEQUENCE { - padata-type [1] INTEGER, - padata-value [2] OCTET STRING - } - - The second case deals with the KRB_AP_ERR_METHOD error code. The - e-data field will contain an encoding of the following sequence: - - METHOD-DATA ::= SEQUENCE { - method-type [0] INTEGER, - method-data [1] OCTET STRING OPTIONAL - } - - method-type indicates the required alternate authentication method. - - It should be noted that, in the case of KRB_AP_ERR_METHOD, a signed - checksum is not returned as part of the error message, since the - error code indicates that the Kerberos credentials provided in the - AP_REQ message are unacceptable. - - We propose that the e-data field have the following format for all - error-codes (except KRB_AP_ERR_METHOD): - - E-DATA ::= SEQUENCE { - data-type [1] INTEGER, - data-value [2] OCTET STRING, - } - - The data-type field specifies the type of information that is - carried in the data-value field. Thus, to send a cryptographic - checksum back to the client, the data-type is set to CHECKSUM, the - data-value is set to the ASN.1 encoding of the following sequence: - - Checksum ::= SEQUENCE { - cksumtype [0] INTEGER, - checksum [1] OCTET STRING - } - - -3.3 Computing the checksum - - After the error message is filled out, the error structure is - converted into ASN.1 representation. A cryptographic checksum is - then taken over the encoded error message; the result is placed in - the error message structure, as the last item in the e-data field. - To send the error message, ASN.1 encoding is again performed over - the error message, which now includes the cryptographic checksum. - - -3.4 Verifying the integrity of the error message - - In addition to verifying the cryptographic checksum for the error - message, the client must verify that the error message is bound to - its request. This is done by comparing the ctime field in the - error message to its counterpart in the request message. - - -4. E-DATA types - - Since the e-data types must not conflict with preauthentication data - types, we propose that the preauthentication data types in the range - of 2048 and above be reserved for use as e-data types. - - We define the following e-data type in support of integrity checking - for the Kerberos error message: - - CHECKSUM = 2048 -- the keyed checksum described above - - -5. Discussion - - -5.1 e-data types - - The extension for Kerberos error messages, as outlined above, is - extensible to allow for definition of other error data types. - We propose that the following e-data types be reserved: - - KDCTIME = 2049 - The error data would consist of the KDCs time in KerberosTime. - This data would be used by the client to adjust for clock skew. - - REDIRECT = 2050 - The error data would consist of a hostname. The hostname would - indicate the authoritative KDC from which to obtain a TGT. - - -5.2 e-data types vs. error code specific data formats - - Since RFC 1510 does not define an error data type, the data format - must be explicitly specified for each error code. This draft has - proposed an extension to RFC 1510 that would introduce the concept - of error data types. This would allow for a manageable set of data - types to be used for any error message. The authors assume that - the introduction of this e-data structure will not break any - existing Kerberos implementations. - - -6. Bibliography - - [1] J. Kohl, C. Neuman. The Kerberos Network Authentication - Service (V5). Request for Comments: 1510 - [2] J. Kohl, C. Neuman. The Kerberos Network Authentication - Service (V5). Request for Comments: 1510 p.67 - - -7. Authors - - Ari Medvinsky - Matthew Hur - Dominique Brezinski - - CyberSafe Corporation - 1605 NW Sammamish Road - Suite 310 - Issaquah, WA 98027-5378 - Phone: (206) 391-6000 - Fax: (206) 391-0508 - http:/www.cybersafe.com - - - Brian Tung - Gene Tsudik - - USC Information Sciences Institute - 4676 Admiralty Way Suite 1001 - Marina del Rey CA 90292-6695 - Phone: (310) 822-1511 - diff --git a/doc/draft-ietf-cat-kerberos-pk-cross-01.txt b/doc/draft-ietf-cat-kerberos-pk-cross-01.txt deleted file mode 100644 index 4b193c573..000000000 --- a/doc/draft-ietf-cat-kerberos-pk-cross-01.txt +++ /dev/null @@ -1,282 +0,0 @@ -INTERNET-DRAFT Brian Tung -draft-ietf-cat-kerberos-pk-cross-01.txt Tatyana Ryutov -Updates: RFC 1510 Clifford Neuman -expires September 30, 1997 Gene Tsudik - ISI - Bill Sommerfeld - Hewlett-Packard - Ari Medvinsky - Matthew Hur - CyberSafe Corporation - - - Public Key Cryptography for Cross-Realm Authentication in Kerberos - - -0. Status Of this Memo - - This document is an Internet-Draft. Internet-Drafts are working - documents of the Internet Engineering Task Force (IETF), its - areas, and its working groups. Note that other groups may also - distribute working documents as Internet-Drafts. - - Internet-Drafts are draft documents valid for a maximum of six - months and may be updated, replaced, or obsoleted by other - documents at any time. It is inappropriate to use Internet-Drafts - as reference material or to cite them other than as ``work in - progress.'' - - To learn the current status of any Internet-Draft, please check - the ``1id-abstracts.txt'' listing contained in the Internet-Drafts - Shadow Directories on ds.internic.net (US East Coast), - nic.nordu.net (Europe), ftp.isi.edu (US West Coast), or - munnari.oz.au (Pacific Rim). - - The distribution of this memo is unlimited. It is filed as - draft-ietf-cat-kerberos-pk-cross-01.txt, and expires September 30, - 1997. Please send comments to the authors. - - -1. Abstract - - This document defines extensions to the Kerberos protocol - specification (RFC 1510, "The Kerberos Network Authentication - Service (V5)", September 1993) to provide a method for using - public key cryptography during cross-realm authentication. The - methods defined here specify the way in which message exchanges - are to be used to transport cross-realm secret keys protected by - encryption under public keys certified as belonging to KDCs. - - -2. Motivation - - The advantages provided by public key cryptography--ease of - recoverability in the event of a compromise, the possibility of - an autonomous authentication infrastructure, to name a few--have - produced a demand for use by Kerberos authentication protocol. A - draft describing the use of public key cryptography in the initial - authentication exchange in Kerberos has already been submitted. - This draft describes its use in cross-realm authentication. - - The principal advantage provided by public key cryptography in - cross-realm authentication lies in the ability to leverage the - existing public key infrastructure. It frees the Kerberos realm - administrator from having to maintain separate keys for each other - realm with which it wishes to exchange authentication information, - or to utilize a hierarchical arrangement, which may pose problems - of trust. - - Even with the multi-hop cross-realm authentication, there must be - some way to locate the path by which separate realms are to be - transited. The current method, which makes use of the DNS-like - realm names typical to Kerberos, requires trust of the intermediate - KDCs. - - The methods described in this draft allow a realm to specify, at - the time of authentication, which certification paths it will - trust. A shared key for cross-realm authentication can be - established, for a period of time. Furthermore, these methods are - transparent to the client, so that only the KDC's need to be - modified to use them. - - It is not necessary to implement the changes described in the - "Public Key Cryptography for Initial Authentication" draft to make - use of the changes in this draft. We solicit comments about the - interaction between the two protocol changes, but as of this - writing, the authors do not perceive any obstacles to using both. - - -3. Protocol Amendments - - We assume that the user has already obtained a TGT. To perform - cross-realm authentication, the user sends a request to the local - KDC as per RFC 1510. If the two realms share a secret key, then - cross-realm authentication proceeds as usual. Otherwise, the - local KDC may attempt to establish a shared key with the remote - KDC using public key cryptography, and exchange this key through - the cross-realm ticket granting ticket. - - We will consider the specific channel on which the message - exchanges take place in Section 5 below. - - -3.1. Changes to the Cross-Realm Ticket Granting Ticket - - In order to avoid the need for changes to the "installed base" of - Kerberos application clients and servers, the only protocol change - is to the way in which cross-realm ticket granting tickets (TGTs) - are encrypted; as these tickets are opaque to clients and servers, - the only change visible to them will be the increased size of the - tickets. - - Cross-realm TGTs are granted by a local KDC to authenticate a user - to a remote KDC's ticket granting service. In standard Kerberos, - they are encrypted using a shared secret key manually configured - into each KDC. - - In order to incorporate public key cryptography, we define a new - encryption type, "ENCTYPE_PK_CROSS". Operationally, this encryption - type transforms an OCTET STRING of plaintext (normally an EncTktPart) - into the following SEQUENCE: - - PKCrossOutput ::= SEQUENCE { - certificate [0] OCTET STRING OPTIONAL, - -- public key certificate - -- of local KDC - encSharedKey [1] EncryptedData, - -- of type EncryptionKey - -- containing random symmetric key - -- encrypted using public key - -- of remote KDC - sigSharedKey [2] Signature, - -- of encSharedKey - -- using signature key - -- of local KDC - pkEncData [3] EncryptedData, - -- (normally) of type EncTktPart - -- encrypted using encryption key - -- found in encSharedKey - } - - PKCROSS operates as follows: when a client submits a request for - cross-realm authentication, the local KDC checks to see if it has - a long-term shared key established for that realm. If so, it uses - this key as per RFC 1510. - - If not, it sends a request for information to the remote KDC. The - content of this message is immaterial, as it does not need to be - processed by the remote KDC; for the sake of consistency, we define - it as follows: - - RemoteRequest ::= [APPLICATION 41] SEQUENCE { - nonce [0] INTEGER - } - - The remote KDC replies with a list of all trusted certifiers and - all its (the remote KDC's) certificates. We note that this response - is universal and does not depend on which KDC makes the request: - - RemoteReply ::= [APPLICATION 42] SEQUENCE { - trustedCertifiers [0] SEQUENCE OF PrincipalName, - certificates[1] SEQUENCE OF Certificate, - encTypeToUse [1] SEQUENCE OF INTEGER - -- encryption types usable - -- for encrypting pkEncData - } - - Certificate ::= SEQUENCE { - CertType [0] INTEGER, - -- type of certificate - -- 1 = X.509v3 (DER encoding) - -- 2 = PGP (per PGP draft) - CertData [1] OCTET STRING - -- actual certificate - -- type determined by CertType - } -- from pk-init draft - - Upon receiving this reply, the local KDC determines whether it has - a certificate the remote KDC trusts, and whether the remote KDC has - a certificate the local KDC trusts. If so, it issues a ticket - encrypted using the ENCTYPE_PK_CROSS encryption type defined above. - - -3.2. Profile Caches - - We observe that using PKCROSS as specified above requires two - private key operations: a signature generation by the local KDC and - a decryption by the remote KDC. This cost can be reduced in the - long term by judicious caching of the encSharedKey and the - sigSharedKey. - - Let us define a "profile" as the encSharedKey and sigSharedKey, in - conjunction with the associated remote realm name and decrypted - shared key (the key encrypted in the encSharedKey). - - To optimize these interactions, each KDC maintains two caches, one - for outbound profiles and one for inbound profiles. When generating - an outbound TGT for another realm, the local KDC first checks to see - if the corresponding entry exists in the outbound profile cache; if - so, it uses its contents to form the first three fields of the - PKCrossOutput; the shared key is used to encrypt the data for the - fourth field. If not, the components are generated fresh and stored - in the outbound profile cache. - - Upon receipt of the TGT, the remote realm checks its inbound profile - cache for the corresponding entry. If it exists, then it uses the - contents of the entry to decrypt the data encrypted in the pkEncData. - If not, then it goes through the full process of verifying and - extracting the shared key; if this is successful, then a new entry - is created in the inbound profile cache. - - The inbound profile cache should support multiple entries per realm, - in the event that the initiating realm is replicated. - - -4. Finding Realms Supporting PKCROSS - - If either the local realm or the destination realm does not support - PKCROSS, or both do not, the mechanism specified in Section 3 can - still be used in obtaining the desired remote TGT. - - In the reference Kerberos implementations, the default behavior is - to traverse a path up and down the realm name hierarchy, if the - two realms do not share a key. There is, however, the possibility - of using cross links--i.e., keys shared between two realms that - are non-contiguous in the realm name hierarchy--to shorten the - path, both to minimize delay and the number of intermediate realms - that need to be trusted. - - PKCROSS can be used as a way to provide cross-links even in the - absence of shared keys. If the client is aware that one or two - intermediate realms support PKCROSS, then a combination of - PKCROSS and conventional cross-realm authentication can be used - to reach the final destination realm. - - We solicit discussion on the best methods for clients and KDCs to - determine or advertise support for PKCROSS. - - -5. Message Ports - - We have not specified the port on which KDCs supporting PKCROSS - should listen to receive the request for information messages noted - above. We solicit discussion on which port should be used. We - propose to use the standard Kerberos ports (well-known 88 or 750), - but another possibility is to use a completely different port. - - We also solicit discussion on what other approaches can be taken to - obtain the information in the RemoteReply (e.g., secure DNS or some - other repository). - - -6. Expiration Date - - This Internet-Draft will expire on September 30, 1997. - - -7. Authors' Addresses - - Brian Tung - Tatyana Ryutov - Clifford Neuman - Gene Tsudik - USC/Information Sciences Institute - 4676 Admiralty Way Suite 1001 - Marina del Rey, CA 90292-6695 - Phone: +1 310 822 1511 - E-Mail: {brian, tryutov, bcn, gts}@isi.edu - - Bill Sommerfeld - Hewlett Packard - 300 Apollo Drive - Chelmsford MA 01824 - Phone: +1 508 436 4352 - E-Mail: sommerfeld@apollo.hp.com - - Ari Medvinsky - Matthew Hur - CyberSafe Corporation - 1605 NW Sammamish Road Suite 310 - Issaquah WA 98027-5378 - Phone: +1 206 391 6000 - E-mail: {ari.medvinsky, matt.hur}@cybersafe.com diff --git a/doc/draft-ietf-cat-kerberos-pk-init-03.txt b/doc/draft-ietf-cat-kerberos-pk-init-03.txt deleted file mode 100644 index d91c087dd..000000000 --- a/doc/draft-ietf-cat-kerberos-pk-init-03.txt +++ /dev/null @@ -1,589 +0,0 @@ - -INTERNET-DRAFT Clifford Neuman -draft-ietf-cat-kerberos-pk-init-03.txt Brian Tung -Updates: RFC 1510 ISI -expires September 30, 1997 John Wray - Digital Equipment Corporation - Ari Medvinsky - Matthew Hur - CyberSafe Corporation - Jonathan Trostle - Novell - - - Public Key Cryptography for Initial Authentication in Kerberos - - -0. Status Of this Memo - - This document is an Internet-Draft. Internet-Drafts are working - documents of the Internet Engineering Task Force (IETF), its - areas, and its working groups. Note that other groups may also - distribute working documents as Internet-Drafts. - - Internet-Drafts are draft documents valid for a maximum of six - months and may be updated, replaced, or obsoleted by other - documents at any time. It is inappropriate to use Internet-Drafts - as reference material or to cite them other than as "work in - progress." - - To learn the current status of any Internet-Draft, please check - the "1id-abstracts.txt" listing contained in the Internet-Drafts - Shadow Directories on ds.internic.net (US East Coast), - nic.nordu.net (Europe), ftp.isi.edu (US West Coast), or - munnari.oz.au (Pacific Rim). - - The distribution of this memo is unlimited. It is filed as - draft-ietf-cat-kerberos-pk-init-03.txt, and expires September 30, - 1997. Please send comments to the authors. - - -1. Abstract - - This document defines extensions (PKINIT) to the Kerberos protocol - specification (RFC 1510 [1]) to provide a method for using public - key cryptography during initial authentication. The methods - defined specify the ways in which preauthentication data fields and - error data fields in Kerberos messages are to be used to transport - public key data. - - -2. Introduction - - The popularity of public key cryptography has produced a desire for - its support in Kerberos [2]. The advantages provided by public key - cryptography include simplified key management (from the Kerberos - perspective) and the ability to leverage existing and developing - public key certification infrastructures. - - Public key cryptography can be integrated into Kerberos in a number - of ways. One is to to associate a key pair with each realm, which - can then be used to facilitate cross-realm authentication; this is - the topic of another draft proposal. Another way is to allow users - with public key certificates to use them in initial authentication. - This is the concern of the current document. - - One of the guiding principles in the design of PKINIT is that - changes should be as minimal as possible. As a result, the basic - mechanism of PKINIT is as follows: The user sends a request to the - KDC as before, except that if that user is to use public key - cryptography in the initial authentication step, his certificate - accompanies the initial request, in the preauthentication fields. - - Upon receipt of this request, the KDC verifies the certificate and - issues a ticket granting ticket (TGT) as before, except that instead - of being encrypted in the user's long-term key (which is derived - from a password), it is encrypted in a randomly-generated key. This - random key is in turn encrypted using the public key certificate - that came with the request and signed using the KDC's signature key, - and accompanies the reply, in the preauthentication fields. - - PKINIT also allows for users with only digital signature keys to - authenticate using those keys, and for users to store and retrieve - private keys on the KDC. - - The PKINIT specification may also be used for direct peer to peer - authentication without contacting a central KDC. This application - of PKINIT is described in PKTAPP [4] and is based on concepts - introduced in [5, 6]. For direct client-to-server authentication, - the client uses PKINIT to authenticate to the end server (instead - of a central KDC), which then issues a ticket for itself. This - approach has an advantage over SSL [7] in that the server does not - need to save state (cache session keys). Furthermore, an - additional benefit is that Kerberos tickets can facilitate - delegation (see [8]). - - -3. Proposed Extensions - - This section describes extensions to RFC 1510 for supporting the - use of public key cryptography in the initial request for a ticket - granting ticket (TGT). - - In summary, the following changes to RFC 1510 are proposed: - - --> Users may authenticate using either a public key pair or a - conventional (symmetric) key. If public key cryptography is - used, public key data is transported in preauthentication - data fields to help establish identity. - --> Users may store private keys on the KDC for retrieval during - Kerberos initial authentication. - - This proposal addresses two ways that users may use public key - cryptography for initial authentication. Users may present public - key certificates, or they may generate their own session key, - signed by their digital signature key. In either case, the end - result is that the user obtains an ordinary TGT that may be used for - subsequent authentication, with such authentication using only - conventional cryptography. - - Section 3.1 provides definitions to help specify message formats. - Section 3.2 and 3.3 describe the extensions for the two initial - authentication methods. Section 3.3 describes a way for the user to - store and retrieve his private key on the KDC. - - -3.1. Definitions - - Hash and encryption types will be specified using ENCTYPE tags; we - propose the addition of the following types: - - #define ENCTYPE_SIGN_DSA_GENERATE 0x0011 - #define ENCTYPE_SIGN_DSA_VERIFY 0x0012 - #define ENCTYPE_ENCRYPT_RSA_PRIV 0x0021 - #define ENCTYPE_ENCRYPT_RSA_PUB 0x0022 - - allowing further signature types to be defined in the range 0x0011 - through 0x001f, and further encryption types to be defined in the - range 0x0021 through 0x002f. - - The extensions involve new preauthentication fields. The - preauthentication data types are in the range 17 through 21. - These values are also specified along with their corresponding - ASN.1 definition. - - #define PA-PK-AS-REQ 17 - #define PA-PK-AS-REP 18 - #define PA-PK-AS-SIGN 19 - #define PA-PK-KEY-REQ 20 - #define PA-PK-KEY-REP 21 - - The extensions also involve new error types. The new error types - are in the range 227 through 229. They are: - - #define KDC_ERROR_CLIENT_NOT_TRUSTED 227 - #define KDC_ERROR_KDC_NOT_TRUSTED 228 - #define KDC_ERROR_INVALID_SIG 229 - - In the exposition below, we use the following terms: encryption key, - decryption key, signature key, verification key. It should be - understood that encryption and verification keys are essentially - public keys, and decryption and signature keys are essentially - private keys. The fact that they are logically distinct does - not preclude the assignment of bitwise identical keys. - - -3.2. Standard Public Key Authentication - - Implementation of the changes in this section is REQUIRED for - compliance with pk-init. - - It is assumed that all public keys are signed by some certification - authority (CA). The initial authentication request is sent as per - RFC 1510, except that a preauthentication field containing data - signed by the user's signature key accompanies the request: - - PA-PK-AS-REQ ::- SEQUENCE { - -- PA TYPE 17 - signedPKAuth [0] SignedPKAuthenticator, - userCert [1] SEQUENCE OF Certificate OPTIONAL, - -- the user's certificate - -- optionally followed by that - -- certificate's certifier chain - trustedCertifiers [2] SEQUENCE OF PrincipalName OPTIONAL - -- CAs that the client trusts - } - - SignedPKAuthenticator ::= SEQUENCE { - pkAuth [0] PKAuthenticator, - pkAuthSig [1] Signature, - -- of pkAuth - -- using user's signature key - } - - PKAuthenticator ::= SEQUENCE { - cusec [0] INTEGER, - -- for replay prevention - ctime [1] KerberosTime, - -- for replay prevention - nonce [2] INTEGER, - -- binds response to this request - kdcName [3] PrincipalName, - clientPubValue [4] SubjectPublicKeyInfo OPTIONAL, - -- for Diffie-Hellman algorithm - } - - Signature ::= SEQUENCE { - signedHash [0] EncryptedData - -- of type Checksum - -- encrypted under signature key - } - - Checksum ::= SEQUENCE { - cksumtype [0] INTEGER, - checksum [1] OCTET STRING - } -- as specified by RFC 1510 - - SubjectPublicKeyInfo ::= SEQUENCE { - algorithm [0] algorithmIdentifier, - subjectPublicKey [1] BIT STRING - } -- as specified by the X.509 recommendation [9] - - Certificate ::= SEQUENCE { - CertType [0] INTEGER, - -- type of certificate - -- 1 = X.509v3 (DER encoding) - -- 2 = PGP (per PGP draft) - CertData [1] OCTET STRING - -- actual certificate - -- type determined by CertType - } - - Note: If the signature uses RSA keys, then it is to be performed - as per PKCS #1. - - The PKAuthenticator carries information to foil replay attacks, - to bind the request and response, and to optionally pass the - client's Diffie-Hellman public value (i.e. for using DSA in - combination with Diffie-Hellman). The PKAuthenticator is signed - with the private key corresponding to the public key in the - certificate found in userCert (or cached by the KDC). - - In the PKAuthenticator, the client may specify the KDC name in one - of two ways: 1) a Kerberos principal name, or 2) the name in the - KDC's certificate (e.g., an X.500 name, or a PGP name). Note that - case #1 requires that the certificate name and the Kerberos principal - name be bound together (e.g., via an X.509v3 extension). - - The userCert field is a sequence of certificates, the first of which - must be the user's public key certificate. Any subsequent - certificates will be certificates of the certifiers of the user's - certificate. These cerificates may be used by the KDC to verify the - user's public key. This field is empty if the KDC already has the - user's certifcate. - - The trustedCertifiers field contains a list of certification - authorities trusted by the client, in the case that the client does - not possess the KDC's public key certificate. - - Upon receipt of the AS_REQ with PA-PK-AS-REQ pre-authentication - type, the KDC attempts to verify the user's certificate chain - (userCert), if one is provided in the request. This is done by - verifying the certification path against the KDC's policy of - legitimate certifiers. This may be based on a certification - hierarchy, or it may be simply a list of recognized certifiers in a - system like PGP. If the certification path does not match one of - the KDC's trusted certifiers, the KDC sends back an error message of - type KDC_ERROR_CLIENT_NOT_TRUSTED, and it includes in the error data - field a list of its own trusted certifiers, upon which the client - resends the request. - - If trustedCertifiers is provided in the PA-PK-AS-REQ, the KDC - verifies that it has a certificate issued by one of the certifiers - trusted by the client. If it does not have a suitable certificate, - the KDC returns an error message of type KDC_ERROR_KDC_NOT_TRUSTED - to the client. - - If a trust relationship exists, the KDC then verifies the client's - signature on PKAuthenticator. If that fails, the KDC returns an - error message of type KDC_ERROR_INVALID_SIG. Otherwise, the KDC - uses the timestamp in the PKAuthenticator to assure that the request - is not a replay. The KDC also verifies that its name is specified - in PKAuthenticator. - - Assuming no errors, the KDC replies as per RFC 1510, except that it - encrypts the reply not with the user's key, but with a random key - generated only for this particular response. This random key - is sealed in the preauthentication field: - - PA-PK-AS-REP ::= SEQUENCE { - -- PA TYPE 18 - kdcCert [0] SEQUENCE OF Certificate OPTIONAL, - -- the KDC's certificate - -- optionally followed by that - -- certificate's certifier chain - encPaReply [1] EncryptedData, - -- of type PaReply - -- using either the client public - -- key or the Diffie-Hellman key - -- specified by SignedDHPublicValue - signedDHPublicValue [2] SignedDHPublicValue OPTIONAL - } - - - PaReply ::= SEQUENCE { - replyEncKeyPack [0] ReplyEncKeyPack, - replyEncKeyPackSig [1] Signature, - -- of replyEncKeyPack - -- using KDC's signature key - } - - ReplyEncKeyPack ::= SEQUENCE { - replyEncKey [0] EncryptionKey, - -- used to encrypt main reply - nonce [1] INTEGER - -- binds response to the request - -- passed in the PKAuthenticator - } - - SignedDHPublicValue ::= SEQUENCE { - dhPublicValue [0] SubjectPublicKeyInfo, - dhPublicValueSig [1] Signature - -- of dhPublicValue - -- using KDC's signature key - } - - The kdcCert field is a sequence of certificates, the first of which - must have as its root certifier one of the certifiers sent to the - KDC in the PA-PK-AS-REQ. Any subsequent certificates will be - certificates of the certifiers of the KDC's certificate. These - cerificates may be used by the client to verify the KDC's public - key. This field is empty if the client did not send to the KDC a - list of trusted certifiers (the trustedCertifiers field was empty). - - Since each certifier in the certification path of a user's - certificate is essentially a separate realm, the name of each - certifier shall be added to the transited field of the ticket. The - format of these realm names shall follow the naming constraints set - forth in RFC 1510 (sections 7.1 and 3.3.3.1). Note that this will - require new nametypes to be defined for PGP certifiers and other - types of realms as they arise. - - The KDC's certificate must bind the public key to a name derivable - from the name of the realm for that KDC. The client then extracts - the random key used to encrypt the main reply. This random key (in - encPaReply) is encrypted with either the client's public key or - with a key derived from the DH values exchanged between the client - and the KDC. - - -3.3. Digital Signature - - Implementation of the changes in this section are OPTIONAL for - compliance with pk-init. - - We offer this option with the warning that it requires the client to - generate a random key; the client may not be able to guarantee the - same level of randomness as the KDC. - - If the user registered a digital signature key with the KDC instead - of an encryption key, then a separate exchange must be used. The - client sends a request for a TGT as usual, except that it (rather - than the KDC) generates the random key that will be used to encrypt - the KDC response. This key is sent to the KDC along with the - request in a preauthentication field: - - PA-PK-AS-SIGN ::= SEQUENCE { - -- PA TYPE 19 - encSignedKeyPack [0] EncryptedData - -- of SignedKeyPack - -- using the KDC's public key - } - - SignedKeyPack ::= SEQUENCE { - signedKey [0] KeyPack, - signedKeyAuth [1] PKAuthenticator, - signedKeySig [2] Signature - -- of signedKey.signedKeyAuth - -- using user's signature key - } - - KeyPack ::= SEQUENCE { - randomKey [0] EncryptionKey, - -- will be used to encrypt reply - nonce [1] INTEGER - } - - where the nonce is copied from the request. - - Upon receipt of the PA-PK-AS-SIGN, the KDC decrypts then verifies - the randomKey. It then replies as per RFC 1510, except that the - reply is encrypted not with a password-derived user key, but with - the randomKey sent in the request. Since the client already knows - this key, there is no need to accompany the reply with an extra - preauthentication field. The transited field of the ticket should - specify the certification path as described in Section 3.2. - - -3.4. Retrieving the Private Key From the KDC - - Implementation of the changes in this section is RECOMMENDED for - compliance with pk-init. - - When the user's private key is not stored local to the user, he may - choose to store the private key (normally encrypted using a - password-derived key) on the KDC. We provide this option to present - the user with an alternative to storing the private key on local - disk at each machine where he expects to authenticate himself using - pk-init. It should be noted that it replaces the added risk of - long-term storage of the private key on possibly many workstations - with the added risk of storing the private key on the KDC in a - form vulnerable to brute-force attack. - - In order to obtain a private key, the client includes a - preauthentication field with the AS-REQ message: - - PA-PK-KEY-REQ ::= SEQUENCE { - -- PA TYPE 20 - patimestamp [0] KerberosTime OPTIONAL, - -- used to address replay attacks. - pausec [1] INTEGER OPTIONAL, - -- used to address replay attacks. - nonce [2] INTEGER, - -- binds the reply to this request - privkeyID [3] SEQUENCE OF KeyID OPTIONAL - -- constructed as a hash of - -- public key corresponding to - -- desired private key - } - - KeyID ::= SEQUENCE { - KeyIdentifier [0] OCTET STRING - } - - The client may request a specific private key by sending the - corresponding ID. If this field is left empty, then all - private keys are returned. - - If all checks out, the KDC responds as described in the above - sections, except that an additional preauthentication field, - containing the user's private key, accompanies the reply: - - PA-PK-KEY-REP ::= SEQUENCE { - -- PA TYPE 21 - nonce [0] INTEGER, - -- binds the reply to the request - KeyData [1] SEQUENCE OF KeyPair - } - - KeyPair ::= SEQUENCE { - privKeyID [0] OCTET STRING, - -- corresponding to encPrivKey - encPrivKey [1] OCTET STRING - } - - -3.4.1. Additional Protection of Retrieved Private Keys - - We solicit discussion on the following proposal: that the client may - optionally include in its request additional data to encrypt the - private key, which is currently only protected by the user's - password. One possibility is that the client might generate a - random string of bits, encrypt it with the public key of the KDC (as - in the SignedKeyPack, but with an ordinary OCTET STRING in place of - an EncryptionKey), and include this with the request. The KDC then - XORs each returned key with this random bit string. (If the bit - string is too short, the KDC could either return an error, or XOR - the returned key with a repetition of the bit string.) - - In order to make this work, additional means of preauthentication - need to be devised in order to prevent attackers from simply - inserting their own bit string. One way to do this is to store - a hash of the password-derived key (the one used to encrypt the - private key). This hash is then used in turn to derive a second - key (called the hash-key); the hash-key is used to encrypt an ASN.1 - structure containing the generated bit string and a nonce value - that binds it to the request. - - Since the KDC possesses the hash, it can generate the hash-key and - verify this (weaker) preauthentication, and yet cannot reproduce - the private key itself, since the hash is a one-way function. - - -4. Logistics and Policy Issues - - We solicit discussion on how clients and KDCs should be configured - in order to determine which of the options described above (if any) - should be used. One possibility is to set the user's database - record to indicate that authentication is to use public key - cryptography; this will not work, however, in the event that the - client needs to know before making the initial request. - -5. Compatibility with One-Time Passcodes - - We solicit discussion on how the protocol changes proposed in this - draft will interact with the proposed use of one-time passcodes - discussed in draft-ietf-cat-kerberos-passwords-00.txt. - - -6. Strength of Cryptographic Schemes - - In light of recent findings on the strength of MD5 and DES, - we solicit discussion on which encryption types to incorporate - into the protocol changes. - - -7. Bibliography - - [1] J. Kohl, C. Neuman. The Kerberos Network Authentication - Service (V5). Request for Comments: 1510 - - [2] B.C. Neuman, Theodore Ts'o. Kerberos: An Authentication Service - for Computer Networks, IEEE Communications, 32(9):33-38. - September 1994. - - [3] A. Medvinsky, M. Hur. Addition of Kerberos Cipher Suites to - Transport Layer Security (TLS). - draft-ietf-tls-kerb-cipher-suites-00.txt - - [4] A. Medvinsky, M. Hur, B. Clifford Neuman. Public Key Utilizing - Tickets for Application Servers (PKTAPP). - draft-ietf-cat-pktapp-00.txt - - [5] M. Sirbu, J. Chuang. Distributed Authentication in Kerberos Using - Public Key Cryptography. Symposium On Network and Distributed System - Security, 1997. - - [6] B. Cox, J.D. Tygar, M. Sirbu. NetBill Security and Transaction - Protocol. In Proceedings of the USENIX Workshop on Electronic Commerce, - July 1995. - - [7] Alan O. Freier, Philip Karlton and Paul C. Kocher. - The SSL Protocol, Version 3.0 - IETF Draft. - - [8] B.C. Neuman, Proxy-Based Authorization and Accounting for - Distributed Systems. In Proceedings of the 13th International - Conference on Distributed Computing Systems, May 1993 - - [9] ITU-T (formerly CCITT) - Information technology - Open Systems Interconnection - - The Directory: Authentication Framework Recommendation X.509 - ISO/IEC 9594-8 - - -8. Acknowledgements - - Some of the ideas on which this proposal is based arose during - discussions over several years between members of the SAAG, the IETF - CAT working group, and the PSRG, regarding integration of Kerberos - and SPX. Some ideas have also been drawn from the DASS system. - These changes are by no means endorsed by these groups. This is an - attempt to revive some of the goals of those groups, and this - proposal approaches those goals primarily from the Kerberos - perspective. Lastly, comments from groups working on similar ideas - in DCE have been invaluable. - - -9. Expiration Date - - This draft expires September 30, 1997. - - -10. Authors - - Clifford Neuman - Brian Tung - USC Information Sciences Institute - 4676 Admiralty Way Suite 1001 - Marina del Rey CA 90292-6695 - Phone: +1 310 822 1511 - E-mail: {bcn, brian}@isi.edu - - John Wray - Digital Equipment Corporation - 550 King Street, LKG2-2/Z7 - Littleton, MA 01460 - Phone: +1 508 486 5210 - E-mail: wray@tuxedo.enet.dec.com - - Ari Medvinsky - Matthew Hur - CyberSafe Corporation - 1605 NW Sammamish Road Suite 310 - Issaquah WA 98027-5378 - Phone: +1 206 391 6000 - E-mail: {ari.medvinsky, matt.hur}@cybersafe.com - - Jonathan Trostle - Novell - E-mail: jonathan.trostle@novell.com diff --git a/doc/draft-ietf-cat-kerberos-revisions-00.txt b/doc/draft-ietf-cat-kerberos-revisions-00.txt deleted file mode 100644 index 2284c3c6b..000000000 --- a/doc/draft-ietf-cat-kerberos-revisions-00.txt +++ /dev/null @@ -1,8277 +0,0 @@ - -INTERNET-DRAFT Clifford Neuman - John Kohl - Theodore Ts'o - 11 July 1997 - - - - The Kerberos Network Authentication Service (V5) - - -STATUS OF THIS MEMO - - This document is an Internet-Draft. Internet-Drafts -are working documents of the Internet Engineering Task Force -(IETF), its areas, and its working groups. Note that other -groups may also distribute working documents as Internet- -Drafts. - - Internet-Drafts are draft documents valid for a maximum -of six months and may be updated, replaced, or obsoleted by -other documents at any time. It is inappropriate to use -Internet-Drafts as reference material or to cite them other -than as "work in progress." - - To learn the current status of any Internet-Draft, -please check the "1id-abstracts.txt" listing contained in -the Internet-Drafts Shadow Directories on ds.internic.net -(US East Coast), nic.nordu.net (Europe), ftp.isi.edu (US -West Coast), or munnari.oz.au (Pacific Rim). - - The distribution of this memo is unlimited. It is -filed as draft-ietf-cat-kerberos-revisions-00.txt, and expires -11 January 1998. Please send comments to: - - krb-protocol@MIT.EDU - -ABSTRACT - - - This document provides an overview and specification of -Version 5 of the Kerberos protocol, and updates RFC1510 to -clarify aspects of the protocol and its intended use that -require more detailed or clearer explanation than was pro- -vided in RFC1510. This document is intended to provide a -detailed description of the protocol, suitable for implemen- -tation, together with descriptions of the appropriate use of -protocol messages and fields within those messages. - - This document is not intended to describe Kerberos to -__________________________ -Project Athena, Athena, and Kerberos are trademarks of -the Massachusetts Institute of Technology (MIT). No -commercial use of these trademarks may be made without -prior written permission of MIT. - - - -Overview - 1 - Expires 11 January 1998 - - - - - - - - Version 5 - Specification Revision 6 - - -the end user, system administrator, or application -developer. Higher level papers describing Version 5 of the -Kerberos system [1] and documenting version 4 [23], are -available elsewhere. - -OVERVIEW - - This INTERNET-DRAFT describes the concepts and model -upon which the Kerberos network authentication system is -based. It also specifies Version 5 of the Kerberos proto- -col. - - The motivations, goals, assumptions, and rationale -behind most design decisions are treated cursorily; they are -more fully described in a paper available in IEEE communica- -tions [1] and earlier in the Kerberos portion of the Athena -Technical Plan [2]. The protocols have been a proposed -standard and are being considered for advancement for draft -standard through the IETF standard process. Comments are -encouraged on the presentation, but only minor refinements -to the protocol as implemented or extensions that fit within -current protocol framework will be considered at this time. - - Requests for addition to an electronic mailing list for -discussion of Kerberos, kerberos@MIT.EDU, may be addressed -to kerberos-request@MIT.EDU. This mailing list is gatewayed -onto the Usenet as the group comp.protocols.kerberos. -Requests for further information, including documents and -code availability, may be sent to info-kerberos@MIT.EDU. - -BACKGROUND - - The Kerberos model is based in part on Needham and -Schroeder's trusted third-party authentication protocol [4] -and on modifications suggested by Denning and Sacco [5]. -The original design and implementation of Kerberos Versions -1 through 4 was the work of two former Project Athena staff -members, Steve Miller of Digital Equipment Corporation and -Clifford Neuman (now at the Information Sciences Institute -of the University of Southern California), along with Jerome -Saltzer, Technical Director of Project Athena, and Jeffrey -Schiller, MIT Campus Network Manager. Many other members of -Project Athena have also contributed to the work on Ker- -beros. - - Version 5 of the Kerberos protocol (described in this -document) has evolved from Version 4 based on new require- -ments and desires for features not available in Version 4. -The design of Version 5 of the Kerberos protocol was led by -Clifford Neuman and John Kohl with much input from the com- -munity. The development of the MIT reference implementation -was led at MIT by John Kohl and Theodore T'so, with help and -contributed code from many others. Reference implementa- -tions of both version 4 and version 5 of Kerberos are pub- -licly available and commercial implementations have been - -Overview - 2 - Expires 11 January 1998 - - - - - - - - Version 5 - Specification Revision 6 - - -developed and are widely used. - - Details on the differences between Kerberos Versions 4 -and 5 can be found in [6]. - -1. Introduction - - Kerberos provides a means of verifying the identities -of principals, (e.g. a workstation user or a network server) -on an open (unprotected) network. This is accomplished -without relying on assertions by the host operating system, -without basing trust on host addresses, without requiring -physical security of all the hosts on the network, and under -the assumption that packets traveling along the network can -be read, modified, and inserted at will[1]. Kerberos per- -forms authentication under these conditions as a trusted -third-party authentication service by using conventional -(shared secret key[2]) cryptography. Kerberos extensions -have been proposed and implemented that provide for the use -of public key cryptography during certain phases of the -authentication protocol. These extensions provide for -authentication of users registered with public key certifi- -cation authorities, and allow the system to provide certain -benefits of public key cryptography in situations where they -are needed. - - The basic Kerberos authentication process proceeds as -follows: A client sends a request to the authentication -server (AS) requesting "credentials" for a given server. -The AS responds with these credentials, encrypted in the -client's key. The credentials consist of 1) a "ticket" for -the server and 2) a temporary encryption key (often called a -"session key"). The client transmits the ticket (which con- -tains the client's identity and a copy of the session key, -all encrypted in the server's key) to the server. The ses- -sion key (now shared by the client and server) is used to -authenticate the client, and may optionally be used to -__________________________ -[1] Note, however, that many applications use Kerberos' -functions only upon the initiation of a stream-based -network connection. Unless an application subsequently -provides integrity protection for the data stream, the -identity verification applies only to the initiation of -the connection, and does not guarantee that subsequent -messages on the connection originate from the same -principal. -[2] Secret and private are often used interchangeably -in the literature. In our usage, it takes two (or -more) to share a secret, thus a shared DES key is a -secret key. Something is only private when no one but -its owner knows it. Thus, in public key cryptosystems, -one has a public and a private key. - - - -Section 1. - 3 - Expires 11 January 1998 - - - - - - - - Version 5 - Specification Revision 6 - - -authenticate the server. It may also be used to encrypt -further communication between the two parties or to exchange -a separate sub-session key to be used to encrypt further -communication. - - Implementation of the basic protocol consists of one or -more authentication servers running on physically secure -hosts. The authentication servers maintain a database of -principals (i.e., users and servers) and their secret keys. -Code libraries provide encryption and implement the Kerberos -protocol. In order to add authentication to its transac- -tions, a typical network application adds one or two calls -to the Kerberos library directly or through the Generic -Security Services Application Programming Interface, GSSAPI, -described in separate document. These calls result in the -transmission of the necessary messages to achieve authenti- -cation. - - The Kerberos protocol consists of several sub-protocols -(or exchanges). There are two basic methods by which a -client can ask a Kerberos server for credentials. In the -first approach, the client sends a cleartext request for a -ticket for the desired server to the AS. The reply is sent -encrypted in the client's secret key. Usually this request -is for a ticket-granting ticket (TGT) which can later be -used with the ticket-granting server (TGS). In the second -method, the client sends a request to the TGS. The client -uses the TGT to authenticate itself to the TGS in the same -manner as if it were contacting any other application server -that requires Kerberos authentication. The reply is -encrypted in the session key from the TGT. Though the pro- -tocol specification describes the AS and the TGS as separate -servers, they are implemented in practice as different pro- -tocol entry points within a single Kerberos server. - - Once obtained, credentials may be used to verify the -identity of the principals in a transaction, to ensure the -integrity of messages exchanged between them, or to preserve -privacy of the messages. The application is free to choose -whatever protection may be necessary. - - To verify the identities of the principals in a tran- -saction, the client transmits the ticket to the application -server. Since the ticket is sent "in the clear" (parts of -it are encrypted, but this encryption doesn't thwart replay) -and might be intercepted and reused by an attacker, addi- -tional information is sent to prove that the message ori- -ginated with the principal to whom the ticket was issued. -This information (called the authenticator) is encrypted in -the session key, and includes a timestamp. The timestamp -proves that the message was recently generated and is not a -replay. Encrypting the authenticator in the session key -proves that it was generated by a party possessing the ses- -sion key. Since no one except the requesting principal and - - -Section 1. - 4 - Expires 11 January 1998 - - - - - - - - Version 5 - Specification Revision 6 - - -the server know the session key (it is never sent over the -network in the clear) this guarantees the identity of the -client. - - The integrity of the messages exchanged between princi- -pals can also be guaranteed using the session key (passed in -the ticket and contained in the credentials). This approach -provides detection of both replay attacks and message stream -modification attacks. It is accomplished by generating and -transmitting a collision-proof checksum (elsewhere called a -hash or digest function) of the client's message, keyed with -the session key. Privacy and integrity of the messages -exchanged between principals can be secured by encrypting -the data to be passed using the session key contained in the -ticket or the subsession key found in the authenticator. - - The authentication exchanges mentioned above require -read-only access to the Kerberos database. Sometimes, how- -ever, the entries in the database must be modified, such as -when adding new principals or changing a principal's key. -This is done using a protocol between a client and a third -Kerberos server, the Kerberos Administration Server (KADM). -There is also a protocol for maintaining multiple copies of -the Kerberos database. Neither of these protocols are -described in this document. - -1.1. Cross-Realm Operation - - The Kerberos protocol is designed to operate across -organizational boundaries. A client in one organization can -be authenticated to a server in another. Each organization -wishing to run a Kerberos server establishes its own -"realm". The name of the realm in which a client is -registered is part of the client's name, and can be used by -the end-service to decide whether to honor a request. - - By establishing "inter-realm" keys, the administrators -of two realms can allow a client authenticated in the local -realm to prove its identity to servers in other realms[3]. -The exchange of inter-realm keys (a separate key may be used -for each direction) registers the ticket-granting service of -each realm as a principal in the other realm. A client is -then able to obtain a ticket-granting ticket for the remote -realm's ticket-granting service from its local realm. When -that ticket-granting ticket is used, the remote ticket- -granting service uses the inter-realm key (which usually -__________________________ -[3] Of course, with appropriate permission the client -could arrange registration of a separately-named prin- -cipal in a remote realm, and engage in normal exchanges -with that realm's services. However, for even small -numbers of clients this becomes cumbersome, and more -automatic methods as described here are necessary. - - -Section 1.1. - 5 - Expires 11 January 1998 - - - - - - - - Version 5 - Specification Revision 6 - - -differs from its own normal TGS key) to decrypt the ticket- -granting ticket, and is thus certain that it was issued by -the client's own TGS. Tickets issued by the remote ticket- -granting service will indicate to the end-service that the -client was authenticated from another realm. - - A realm is said to communicate with another realm if -the two realms share an inter-realm key, or if the local -realm shares an inter-realm key with an intermediate realm -that communicates with the remote realm. An authentication -path is the sequence of intermediate realms that are tran- -sited in communicating from one realm to another. - - Realms are typically organized hierarchically. Each -realm shares a key with its parent and a different key with -each child. If an inter-realm key is not directly shared by -two realms, the hierarchical organization allows an authen- -tication path to be easily constructed. If a hierarchical -organization is not used, it may be necessary to consult a -database in order to construct an authentication path -between realms. - - Although realms are typically hierarchical, intermedi- -ate realms may be bypassed to achieve cross-realm authenti- -cation through alternate authentication paths (these might -be established to make communication between two realms more -efficient). It is important for the end-service to know -which realms were transited when deciding how much faith to -place in the authentication process. To facilitate this -decision, a field in each ticket contains the names of the -realms that were involved in authenticating the client. - -1.2. Authorization - -As an authentication service, Kerberos provides a means of -verifying the identity of principals on a network. Authen- -tication is usually useful primarily as a first step in the -process of authorization, determining whether a client may -use a service, which objects the client is allowed to -access, and the type of access allowed for each. Kerberos -does not, by itself, provide authorization. Possession of a -client ticket for a service provides only for authentication -of the client to that service, and in the absence of a -separate authorization procedure, it should not be con- -sidered by an application as authorizing the use of that -service. - - Such separate authorization methods may be implemented -as application specific access control functions and may be -based on files such as the application server, or on -separately issued authorization credentials such as those -based on proxies [7] , or on other authorization services. - - Applications should not be modified to accept the -issuance of a service ticket by the Kerberos server (even by - -Section 1.2. - 6 - Expires 11 January 1998 - - - - - - - - Version 5 - Specification Revision 6 - - -an modified Kerberos server) as granting authority to use -the service, since such applications may become vulnerable -to the bypass of this authorization check in an environment -where they interoperate with other KDCs or where other -options for application authentication (e.g. the PKTAPP pro- -posal) are provided. - -1.3. Environmental assumptions - -Kerberos imposes a few assumptions on the environment in -which it can properly function: - -+ "Denial of service" attacks are not solved with Ker- - beros. There are places in these protocols where an - intruder can prevent an application from participating - in the proper authentication steps. Detection and - solution of such attacks (some of which can appear to - be not-uncommon "normal" failure modes for the system) - is usually best left to the human administrators and - users. - -+ Principals must keep their secret keys secret. If an - intruder somehow steals a principal's key, it will be - able to masquerade as that principal or impersonate any - server to the legitimate principal. - -+ "Password guessing" attacks are not solved by Kerberos. - If a user chooses a poor password, it is possible for - an attacker to successfully mount an offline dictionary - attack by repeatedly attempting to decrypt, with suc- - cessive entries from a dictionary, messages obtained - which are encrypted under a key derived from the user's - password. - -+ Each host on the network must have a clock which is - "loosely synchronized" to the time of the other hosts; - this synchronization is used to reduce the bookkeeping - needs of application servers when they do replay detec- - tion. The degree of "looseness" can be configured on a - per-server basis, but is typically on the order of 5 - minutes. If the clocks are synchronized over the net- - work, the clock synchronization protocol must itself be - secured from network attackers. - -+ Principal identifiers are not recycled on a short-term - basis. A typical mode of access control will use - access control lists (ACLs) to grant permissions to - particular principals. If a stale ACL entry remains - for a deleted principal and the principal identifier is - reused, the new principal will inherit rights specified - in the stale ACL entry. By not re-using principal - identifiers, the danger of inadvertent access is - removed. - - - -Section 1.3. - 7 - Expires 11 January 1998 - - - - - - - - Version 5 - Specification Revision 6 - - -1.4. Glossary of terms - -Below is a list of terms used throughout this document. - - -Authentication Verifying the claimed identity of a - principal. - - -Authentication headerA record containing a Ticket and an - Authenticator to be presented to a - server as part of the authentication - process. - - -Authentication path A sequence of intermediate realms tran- - sited in the authentication process when - communicating from one realm to another. - - -Authenticator A record containing information that can - be shown to have been recently generated - using the session key known only by the - client and server. - - -Authorization The process of determining whether a - client may use a service, which objects - the client is allowed to access, and the - type of access allowed for each. - - -Capability A token that grants the bearer permis- - sion to access an object or service. In - Kerberos, this might be a ticket whose - use is restricted by the contents of the - authorization data field, but which - lists no network addresses, together - with the session key necessary to use - the ticket. - - -Ciphertext The output of an encryption function. - Encryption transforms plaintext into - ciphertext. - - -Client A process that makes use of a network - service on behalf of a user. Note that - in some cases a Server may itself be a - client of some other server (e.g. a - print server may be a client of a file - server). - - - -Section 1.4. - 8 - Expires 11 January 1998 - - - - - - - - Version 5 - Specification Revision 6 - - -Credentials A ticket plus the secret session key - necessary to successfully use that - ticket in an authentication exchange. - - -KDC Key Distribution Center, a network ser- - vice that supplies tickets and temporary - session keys; or an instance of that - service or the host on which it runs. - The KDC services both initial ticket and - ticket-granting ticket requests. The - initial ticket portion is sometimes - referred to as the Authentication Server - (or service). The ticket-granting - ticket portion is sometimes referred to - as the ticket-granting server (or ser- - vice). - - -Kerberos Aside from the 3-headed dog guarding - Hades, the name given to Project - Athena's authentication service, the - protocol used by that service, or the - code used to implement the authentica- - tion service. - - -Plaintext The input to an encryption function or - the output of a decryption function. - Decryption transforms ciphertext into - plaintext. - - -Principal A uniquely named client or server - instance that participates in a network - communication. - - -Principal identifierThe name used to uniquely identify each - different principal. - - -Seal To encipher a record containing several - fields in such a way that the fields - cannot be individually replaced without - either knowledge of the encryption key - or leaving evidence of tampering. - - -Secret key An encryption key shared by a principal - and the KDC, distributed outside the - bounds of the system, with a long life- - time. In the case of a human user's - principal, the secret key is derived - - -Section 1.4. - 9 - Expires 11 January 1998 - - - - - - - - Version 5 - Specification Revision 6 - - - from a password. - - -Server A particular Principal which provides a - resource to network clients. The server - is sometimes refered to as the Applica- - tion Server. - - -Service A resource provided to network clients; - often provided by more than one server - (for example, remote file service). - - -Session key A temporary encryption key used between - two principals, with a lifetime limited - to the duration of a single login "ses- - sion". - - -Sub-session key A temporary encryption key used between - two principals, selected and exchanged - by the principals using the session key, - and with a lifetime limited to the dura- - tion of a single association. - - -Ticket A record that helps a client authenti- - cate itself to a server; it contains the - client's identity, a session key, a - timestamp, and other information, all - sealed using the server's secret key. - It only serves to authenticate a client - when presented along with a fresh - Authenticator. - -2. Ticket flag uses and requests - -Each Kerberos ticket contains a set of flags which are used -to indicate various attributes of that ticket. Most flags -may be requested by a client when the ticket is obtained; -some are automatically turned on and off by a Kerberos -server as required. The following sections explain what the -various flags mean, and gives examples of reasons to use -such a flag. - -2.1. Initial and pre-authenticated tickets - - The INITIAL flag indicates that a ticket was issued -using the AS protocol and not issued based on a ticket- -granting ticket. Application servers that want to require -the demonstrated knowledge of a client's secret key (e.g. a -password-changing program) can insist that this flag be set -in any tickets they accept, and thus be assured that the - - -Section 2.1. - 10 - Expires 11 January 1998 - - - - - - - - Version 5 - Specification Revision 6 - - -client's key was recently presented to the application -client. - - The PRE-AUTHENT and HW-AUTHENT flags provide addition -information about the initial authentication, regardless of -whether the current ticket was issued directly (in which -case INITIAL will also be set) or issued on the basis of a -ticket-granting ticket (in which case the INITIAL flag is -clear, but the PRE-AUTHENT and HW-AUTHENT flags are carried -forward from the ticket-granting ticket). - -2.2. Invalid tickets - - The INVALID flag indicates that a ticket is invalid. -Application servers must reject tickets which have this flag -set. A postdated ticket will usually be issued in this -form. Invalid tickets must be validated by the KDC before -use, by presenting them to the KDC in a TGS request with the -VALIDATE option specified. The KDC will only validate tick- -ets after their starttime has passed. The validation is -required so that postdated tickets which have been stolen -before their starttime can be rendered permanently invalid -(through a hot-list mechanism) (see section 3.3.3.1). - -2.3. Renewable tickets - - Applications may desire to hold tickets which can be -valid for long periods of time. However, this can expose -their credentials to potential theft for equally long -periods, and those stolen credentials would be valid until -the expiration time of the ticket(s). Simply using short- -lived tickets and obtaining new ones periodically would -require the client to have long-term access to its secret -key, an even greater risk. Renewable tickets can be used to -mitigate the consequences of theft. Renewable tickets have -two "expiration times": the first is when the current -instance of the ticket expires, and the second is the latest -permissible value for an individual expiration time. An -application client must periodically (i.e. before it -expires) present a renewable ticket to the KDC, with the -RENEW option set in the KDC request. The KDC will issue a -new ticket with a new session key and a later expiration -time. All other fields of the ticket are left unmodified by -the renewal process. When the latest permissible expiration -time arrives, the ticket expires permanently. At each -renewal, the KDC may consult a hot-list to determine if the -ticket had been reported stolen since its last renewal; it -will refuse to renew such stolen tickets, and thus the -usable lifetime of stolen tickets is reduced. - - The RENEWABLE flag in a ticket is normally only inter- -preted by the ticket-granting service (discussed below in -section 3.3). It can usually be ignored by application -servers. However, some particularly careful application - - -Section 2.3. - 11 - Expires 11 January 1998 - - - - - - - - Version 5 - Specification Revision 6 - - -servers may wish to disallow renewable tickets. - - If a renewable ticket is not renewed by its expiration -time, the KDC will not renew the ticket. The RENEWABLE flag -is reset by default, but a client may request it be set by -setting the RENEWABLE option in the KRB_AS_REQ message. If -it is set, then the renew-till field in the ticket contains -the time after which the ticket may not be renewed. - -2.4. Postdated tickets - - Applications may occasionally need to obtain tickets -for use much later, e.g. a batch submission system would -need tickets to be valid at the time the batch job is ser- -viced. However, it is dangerous to hold valid tickets in a -batch queue, since they will be on-line longer and more -prone to theft. Postdated tickets provide a way to obtain -these tickets from the KDC at job submission time, but to -leave them "dormant" until they are activated and validated -by a further request of the KDC. If a ticket theft were -reported in the interim, the KDC would refuse to validate -the ticket, and the thief would be foiled. - - The MAY-POSTDATE flag in a ticket is normally only -interpreted by the ticket-granting service. It can be -ignored by application servers. This flag must be set in a -ticket-granting ticket in order to issue a postdated ticket -based on the presented ticket. It is reset by default; it -may be requested by a client by setting the ALLOW-POSTDATE -option in the KRB_AS_REQ message. This flag does not allow -a client to obtain a postdated ticket-granting ticket; post- -dated ticket-granting tickets can only by obtained by -requesting the postdating in the KRB_AS_REQ message. The -life (endtime-starttime) of a postdated ticket will be the -remaining life of the ticket-granting ticket at the time of -the request, unless the RENEWABLE option is also set, in -which case it can be the full life (endtime-starttime) of -the ticket-granting ticket. The KDC may limit how far in -the future a ticket may be postdated. - - The POSTDATED flag indicates that a ticket has been -postdated. The application server can check the authtime -field in the ticket to see when the original authentication -occurred. Some services may choose to reject postdated -tickets, or they may only accept them within a certain -period after the original authentication. When the KDC -issues a POSTDATED ticket, it will also be marked as -INVALID, so that the application client must present the -ticket to the KDC to be validated before use. - -2.5. Proxiable and proxy tickets - - At times it may be necessary for a principal to allow a -service to perform an operation on its behalf. The service - - -Section 2.5. - 12 - Expires 11 January 1998 - - - - - - - - Version 5 - Specification Revision 6 - - -must be able to take on the identity of the client, but only -for a particular purpose. A principal can allow a service -to take on the principal's identity for a particular purpose -by granting it a proxy. - - The process of granting a proxy using the proxy and -proxiable flags is used to provide credentials for use with -specific services. Though conceptually also a proxy, user's -wishing to delegate their identity for ANY purpose must use -the ticket forwarding mechanism described in the next sec- -tion to forward a ticket granting ticket. - - The PROXIABLE flag in a ticket is normally only inter- -preted by the ticket-granting service. It can be ignored by -application servers. When set, this flag tells the ticket- -granting server that it is OK to issue a new ticket (but not -a ticket-granting ticket) with a different network address -based on this ticket. This flag is set if requested by the -client on initial authentication. By default, the client -will request that it be set when requesting a ticket grant- -ing ticket, and reset when requesting any other ticket. - - This flag allows a client to pass a proxy to a server -to perform a remote request on its behalf, e.g. a print ser- -vice client can give the print server a proxy to access the -client's files on a particular file server in order to -satisfy a print request. - - In order to complicate the use of stolen credentials, -Kerberos tickets are usually valid from only those network -addresses specifically included in the ticket[4]. When -granting a proxy, the client must specify the new network -address from which the proxy is to be used, or indicate that -the proxy is to be issued for use from any address. - - The PROXY flag is set in a ticket by the TGS when it -issues a proxy ticket. Application servers may check this -flag and at their option they may require additional authen- -tication from the agent presenting the proxy in order to -provide an audit trail. - -2.6. Forwardable tickets - - Authentication forwarding is an instance of a proxy -where the service is granted complete use of the client's -identity. An example where it might be used is when a user -logs in to a remote system and wants authentication to work -from that system as if the login were local. - - The FORWARDABLE flag in a ticket is normally only -__________________________ -[4] Though it is permissible to request or issue tick- -ets with no network addresses specified. - - -Section 2.6. - 13 - Expires 11 January 1998 - - - - - - - - Version 5 - Specification Revision 6 - - -interpreted by the ticket-granting service. It can be -ignored by application servers. The FORWARDABLE flag has an -interpretation similar to that of the PROXIABLE flag, except -ticket-granting tickets may also be issued with different -network addresses. This flag is reset by default, but users -may request that it be set by setting the FORWARDABLE option -in the AS request when they request their initial ticket- -granting ticket. - - This flag allows for authentication forwarding without -requiring the user to enter a password again. If the flag -is not set, then authentication forwarding is not permitted, -but the same result can still be achieved if the user -engages in the AS exchange specifying the requested network -addresses and supplies a password. - - The FORWARDED flag is set by the TGS when a client -presents a ticket with the FORWARDABLE flag set and requests -a forwarded ticket by specifying the FORWARDED KDC option -and supplying a set of addresses for the new ticket. It is -also set in all tickets issued based on tickets with the -FORWARDED flag set. Application servers may choose to pro- -cess FORWARDED tickets differently than non-FORWARDED tick- -ets. - -2.7. Other KDC options - - There are two additional options which may be set in a -client's request of the KDC. The RENEWABLE-OK option indi- -cates that the client will accept a renewable ticket if a -ticket with the requested life cannot otherwise be provided. -If a ticket with the requested life cannot be provided, then -the KDC may issue a renewable ticket with a renew-till equal -to the the requested endtime. The value of the renew-till -field may still be adjusted by site-determined limits or -limits imposed by the individual principal or server. - - The ENC-TKT-IN-SKEY option is honored only by the -ticket-granting service. It indicates that the ticket to be -issued for the end server is to be encrypted in the session -key from the a additional second ticket-granting ticket pro- -vided with the request. See section 3.3.3 for specific -details. - -__________________________ -[5] The password-changing request must not be honored -unless the requester can provide the old password (the -user's current secret key). Otherwise, it would be -possible for someone to walk up to an unattended ses- -sion and change another user's password. -[6] To authenticate a user logging on to a local sys- -tem, the credentials obtained in the AS exchange may -first be used in a TGS exchange to obtain credentials - - -Section 3.1. - 14 - Expires 11 January 1998 - - - - - - - Version 5 - Specification Revision 6 - - - -3. Message Exchanges - -The following sections describe the interactions between -network clients and servers and the messages involved in -those exchanges. - -3.1. The Authentication Service Exchange - - Summary - Message direction Message type Section - 1. Client to Kerberos KRB_AS_REQ 5.4.1 - 2. Kerberos to client KRB_AS_REP or 5.4.2 - KRB_ERROR 5.9.1 - - - The Authentication Service (AS) Exchange between the -client and the Kerberos Authentication Server is initiated -by a client when it wishes to obtain authentication creden- -tials for a given server but currently holds no credentials. -In its basic form, the client's secret key is used for en- -cryption and decryption. This exchange is typically used at -the initiation of a login session to obtain credentials for -a Ticket-Granting Server which will subsequently be used to -obtain credentials for other servers (see section 3.3) -without requiring further use of the client's secret key. -This exchange is also used to request credentials for ser- -vices which must not be mediated through the Ticket-Granting -Service, but rather require a principal's secret key, such -as the password-changing service[5]. This exchange does not -by itself provide any assurance of the the identity of the -user[6]. - - The exchange consists of two messages: KRB_AS_REQ from -the client to Kerberos, and KRB_AS_REP or KRB_ERROR in -reply. The formats for these messages are described in sec- -tions 5.4.1, 5.4.2, and 5.9.1. - - In the request, the client sends (in cleartext) its own -identity and the identity of the server for which it is -requesting credentials. The response, KRB_AS_REP, contains -a ticket for the client to present to the server, and a ses- -sion key that will be shared by the client and the server. -The session key and additional information are encrypted in -the client's secret key. The KRB_AS_REP message contains -information which can be used to detect replays, and to -associate it with the message to which it replies. Various -errors can occur; these are indicated by an error response -(KRB_ERROR) instead of the KRB_AS_REP response. The error -__________________________ -for a local server. Those credentials must then be -verified by a local server through successful comple- -tion of the Client/Server exchange. - - - -Section 3.1. - 15 - Expires 11 January 1998 - - - - - - - - Version 5 - Specification Revision 6 - - -message is not encrypted. The KRB_ERROR message contains -information which can be used to associate it with the mes- -sage to which it replies. The lack of encryption in the -KRB_ERROR message precludes the ability to detect replays, -fabrications, or modifications of such messages. - - Without preautentication, the authentication server -does not know whether the client is actually the principal -named in the request. It simply sends a reply without know- -ing or caring whether they are the same. This is acceptable -because nobody but the principal whose identity was given in -the request will be able to use the reply. Its critical -information is encrypted in that principal's key. The ini- -tial request supports an optional field that can be used to -pass additional information that might be needed for the -initial exchange. This field may be used for pre- -authentication as described in section <>. - -3.1.1. Generation of KRB_AS_REQ message - - The client may specify a number of options in the ini- -tial request. Among these options are whether pre- -authentication is to be performed; whether the requested -ticket is to be renewable, proxiable, or forwardable; -whether it should be postdated or allow postdating of -derivative tickets; and whether a renewable ticket will be -accepted in lieu of a non-renewable ticket if the requested -ticket expiration date cannot be satisfied by a non- -renewable ticket (due to configuration constraints; see sec- -tion 4). See section A.1 for pseudocode. - - The client prepares the KRB_AS_REQ message and sends it -to the KDC. - -3.1.2. Receipt of KRB_AS_REQ message - - If all goes well, processing the KRB_AS_REQ message -will result in the creation of a ticket for the client to -present to the server. The format for the ticket is -described in section 5.3.1. The contents of the ticket are -determined as follows. - -3.1.3. Generation of KRB_AS_REP message - - The authentication server looks up the client and -server principals named in the KRB_AS_REQ in its database, -extracting their respective keys. If required, the server -pre-authenticates the request, and if the pre-authentication -check fails, an error message with the code -KDC_ERR_PREAUTH_FAILED is returned. If the server cannot -accommodate the requested encryption type, an error message -with code KDC_ERR_ETYPE_NOSUPP is returned. Otherwise it -generates a "random" session key[7]. -__________________________ - - -Section 3.1.3. - 16 - Expires 11 January 1998 - - - - - - - - Version 5 - Specification Revision 6 - - - If there are multiple encryption keys registered for a -client in the Kerberos database (or if the key registered -supports multiple encryption types; e.g. DES-CBC-CRC and -DES-CBC-MD5), then the etype field from the AS request is -used by the KDC to select the encryption method to be used -for encrypting the response to the client. If there is more -than one supported, strong encryption type in the etype -list, the first valid etype for which an encryption key is -available is used. The encryption method used to respond to -a TGS request is taken from the keytype of the session key -found in the ticket granting ticket. - - When the etype field is present in a KDC request, -whether an AS or TGS request, the KDC will attempt to assign -the type of the random session key from the list of methods -in the etype field. The KDC will select the appropriate -type using the list of methods provided together with infor- -mation from the Kerberos database indicating acceptable -encryption methods for the application server. The KDC will -not issue tickets with a weak session key encryption type. - - If the requested start time is absent, indicates a time -in the past, or is within the window of acceptable clock -skew for the KDC and the POSTDATE option has not been speci- -fied, then the start time of the ticket is set to the -authentication server's current time. If it indicates a -time in the future beyond the acceptable clock skew, but the -POSTDATED option has not been specified then the error -KDC_ERR_CANNOT_POSTDATE is returned. Otherwise the -requested start time is checked against the policy of the -local realm (the administrator might decide to prohibit cer- -tain types or ranges of postdated tickets), and if accept- -able, the ticket's start time is set as requested and the -INVALID flag is set in the new ticket. The postdated ticket -must be validated before use by presenting it to the KDC -after the start time has been reached. - - - - - - - - - -__________________________ -[7] "Random" means that, among other things, it should -be impossible to guess the next session key based on -knowledge of past session keys. This can only be -achieved in a pseudo-random number generator if it is -based on cryptographic principles. It is more desir- -able to use a truly random number generator, such as -one based on measurements of random physical phenomena. - - - -Section 3.1.3. - 17 - Expires 11 January 1998 - - - - - - - - Version 5 - Specification Revision 6 - - -The expiration time of the ticket will be set to the minimum -of the following: - -+The expiration time (endtime) requested in the KRB_AS_REQ - message. - -+The ticket's start time plus the maximum allowable lifetime - associated with the client principal (the authentication - server's database includes a maximum ticket lifetime field - in each principal's record; see section 4). - -+The ticket's start time plus the maximum allowable lifetime - associated with the server principal. - -+The ticket's start time plus the maximum lifetime set by - the policy of the local realm. - - If the requested expiration time minus the start time -(as determined above) is less than a site-determined minimum -lifetime, an error message with code KDC_ERR_NEVER_VALID is -returned. If the requested expiration time for the ticket -exceeds what was determined as above, and if the -"RENEWABLE-OK" option was requested, then the "RENEWABLE" -flag is set in the new ticket, and the renew-till value is -set as if the "RENEWABLE" option were requested (the field -and option names are described fully in section 5.4.1). - -If the RENEWABLE option has been requested or if the -RENEWABLE-OK option has been set and a renewable ticket is -to be issued, then the renew-till field is set to the -minimum of: - -+Its requested value. - -+The start time of the ticket plus the minimum of the two - maximum renewable lifetimes associated with the principals' - database entries. - -+The start time of the ticket plus the maximum renewable - lifetime set by the policy of the local realm. - - The flags field of the new ticket will have the follow- -ing options set if they have been requested and if the pol- -icy of the local realm allows: FORWARDABLE, MAY-POSTDATE, -POSTDATED, PROXIABLE, RENEWABLE. If the new ticket is post- -dated (the start time is in the future), its INVALID flag -will also be set. - - If all of the above succeed, the server formats a -KRB_AS_REP message (see section 5.4.2), copying the -addresses in the request into the caddr of the response, -placing any required pre-authentication data into the padata -of the response, and encrypts the ciphertext part in the -client's key using the requested encryption method, and - - -Section 3.1.3. - 18 - Expires 11 January 1998 - - - - - - - - Version 5 - Specification Revision 6 - - -sends it to the client. See section A.2 for pseudocode. - -3.1.4. Generation of KRB_ERROR message - - Several errors can occur, and the Authentication Server -responds by returning an error message, KRB_ERROR, to the -client, with the error-code and e-text fields set to -appropriate values. The error message contents and details -are described in Section 5.9.1. - -3.1.5. Receipt of KRB_AS_REP message - - If the reply message type is KRB_AS_REP, then the -client verifies that the cname and crealm fields in the -cleartext portion of the reply match what it requested. If -any padata fields are present, they may be used to derive -the proper secret key to decrypt the message. The client -decrypts the encrypted part of the response using its secret -key, verifies that the nonce in the encrypted part matches -the nonce it supplied in its request (to detect replays). -It also verifies that the sname and srealm in the response -match those in the request (or are otherwise expected -values), and that the host address field is also correct. -It then stores the ticket, session key, start and expiration -times, and other information for later use. The key- -expiration field from the encrypted part of the response may -be checked to notify the user of impending key expiration -(the client program could then suggest remedial action, such -as a password change). See section A.3 for pseudocode. - - Proper decryption of the KRB_AS_REP message is not suf- -ficient to verify the identity of the user; the user and an -attacker could cooperate to generate a KRB_AS_REP format -message which decrypts properly but is not from the proper -KDC. If the host wishes to verify the identity of the user, -it must require the user to present application credentials -which can be verified using a securely-stored secret key for -the host. If those credentials can be verified, then the -identity of the user can be assured. - -3.1.6. Receipt of KRB_ERROR message - - If the reply message type is KRB_ERROR, then the client -interprets it as an error and performs whatever -application-specific tasks are necessary to recover. - -3.2. The Client/Server Authentication Exchange - - Summary -Message direction Message type Section -Client to Application server KRB_AP_REQ 5.5.1 -[optional] Application server to client KRB_AP_REP or 5.5.2 - KRB_ERROR 5.9.1 - - - -Section 3.2. - 19 - Expires 11 January 1998 - - - - - - - - Version 5 - Specification Revision 6 - - - The client/server authentication (CS) exchange is used -by network applications to authenticate the client to the -server and vice versa. The client must have already -acquired credentials for the server using the AS or TGS -exchange. - -3.2.1. The KRB_AP_REQ message - - The KRB_AP_REQ contains authentication information -which should be part of the first message in an authenti- -cated transaction. It contains a ticket, an authenticator, -and some additional bookkeeping information (see section -5.5.1 for the exact format). The ticket by itself is insuf- -ficient to authenticate a client, since tickets are passed -across the network in cleartext[8], so the authenticator is -used to prevent invalid replay of tickets by proving to the -server that the client knows the session key of the ticket -and thus is entitled to use the ticket. The KRB_AP_REQ mes- -sage is referred to elsewhere as the "authentication -header." - -3.2.2. Generation of a KRB_AP_REQ message - - When a client wishes to initiate authentication to a -server, it obtains (either through a credentials cache, the -AS exchange, or the TGS exchange) a ticket and session key -for the desired service. The client may re-use any tickets -it holds until they expire. To use a ticket the client con- -structs a new Authenticator from the the system time, its -name, and optionally an application specific checksum, an -initial sequence number to be used in KRB_SAFE or KRB_PRIV -messages, and/or a session subkey to be used in negotiations -for a session key unique to this particular session. -Authenticators may not be re-used and will be rejected if -replayed to a server[9]. If a sequence number is to be -included, it should be randomly chosen so that even after -many messages have been exchanged it is not likely to col- -lide with other sequence numbers in use. - - The client may indicate a requirement of mutual -__________________________ -[8] Tickets contain both an encrypted and unencrypted -portion, so cleartext here refers to the entire unit, -which can be copied from one message and replayed in -another without any cryptographic skill. -[9] Note that this can make applications based on un- -reliable transports difficult to code correctly. If the -transport might deliver duplicated messages, either a -new authenticator must be generated for each retry, or -the application server must match requests and replies -and replay the first reply in response to a detected -duplicate. - - - -Section 3.2.2. - 20 - Expires 11 January 1998 - - - - - - - - Version 5 - Specification Revision 6 - - -authentication or the use of a session-key based ticket by -setting the appropriate flag(s) in the ap-options field of -the message. - - The Authenticator is encrypted in the session key and -combined with the ticket to form the KRB_AP_REQ message -which is then sent to the end server along with any addi- -tional application-specific information. See section A.9 -for pseudocode. - -3.2.3. Receipt of KRB_AP_REQ message - - Authentication is based on the server's current time of -day (clocks must be loosely synchronized), the authentica- -tor, and the ticket. Several errors are possible. If an -error occurs, the server is expected to reply to the client -with a KRB_ERROR message. This message may be encapsulated -in the application protocol if its "raw" form is not accept- -able to the protocol. The format of error messages is -described in section 5.9.1. - - The algorithm for verifying authentication information -is as follows. If the message type is not KRB_AP_REQ, the -server returns the KRB_AP_ERR_MSG_TYPE error. If the key -version indicated by the Ticket in the KRB_AP_REQ is not one -the server can use (e.g., it indicates an old key, and the -server no longer possesses a copy of the old key), the -KRB_AP_ERR_BADKEYVER error is returned. If the USE- -SESSION-KEY flag is set in the ap-options field, it indi- -cates to the server that the ticket is encrypted in the ses- -sion key from the server's ticket-granting ticket rather -than its secret key[10]. Since it is possible for the -server to be registered in multiple realms, with different -keys in each, the srealm field in the unencrypted portion of -the ticket in the KRB_AP_REQ is used to specify which secret -key the server should use to decrypt that ticket. The -KRB_AP_ERR_NOKEY error code is returned if the server -doesn't have the proper key to decipher the ticket. - - The ticket is decrypted using the version of the -server's key specified by the ticket. If the decryption -routines detect a modification of the ticket (each encryp- -tion system must provide safeguards to detect modified -ciphertext; see section 6), the KRB_AP_ERR_BAD_INTEGRITY -error is returned (chances are good that different keys were -used to encrypt and decrypt). - - The authenticator is decrypted using the session key -extracted from the decrypted ticket. If decryption shows it -to have been modified, the KRB_AP_ERR_BAD_INTEGRITY error is -__________________________ -[10] This is used for user-to-user authentication as -described in [8]. - - -Section 3.2.3. - 21 - Expires 11 January 1998 - - - - - - - - Version 5 - Specification Revision 6 - - -returned. The name and realm of the client from the ticket -are compared against the same fields in the authenticator. -If they don't match, the KRB_AP_ERR_BADMATCH error is -returned (they might not match, for example, if the wrong -session key was used to encrypt the authenticator). The -addresses in the ticket (if any) are then searched for an -address matching the operating-system reported address of -the client. If no match is found or the server insists on -ticket addresses but none are present in the ticket, the -KRB_AP_ERR_BADADDR error is returned. - - If the local (server) time and the client time in the -authenticator differ by more than the allowable clock skew -(e.g., 5 minutes), the KRB_AP_ERR_SKEW error is returned. -If the server name, along with the client name, time and -microsecond fields from the Authenticator match any -recently-seen such tuples, the KRB_AP_ERR_REPEAT error is -returned[11]. The server must remember any authenticator -presented within the allowable clock skew, so that a replay -attempt is guaranteed to fail. If a server loses track of -any authenticator presented within the allowable clock skew, -it must reject all requests until the clock skew interval -has passed. This assures that any lost or re-played authen- -ticators will fall outside the allowable clock skew and can -no longer be successfully replayed (If this is not done, an -attacker could conceivably record the ticket and authentica- -tor sent over the network to a server, then disable the -client's host, pose as the disabled host, and replay the -ticket and authenticator to subvert the authentication.). -If a sequence number is provided in the authenticator, the -server saves it for later use in processing KRB_SAFE and/or -KRB_PRIV messages. If a subkey is present, the server -either saves it for later use or uses it to help generate -its own choice for a subkey to be returned in a KRB_AP_REP -message. - - The server computes the age of the ticket: local -(server) time minus the start time inside the Ticket. If -the start time is later than the current time by more than -the allowable clock skew or if the INVALID flag is set in -the ticket, the KRB_AP_ERR_TKT_NYV error is returned. Oth- -erwise, if the current time is later than end time by more -than the allowable clock skew, the KRB_AP_ERR_TKT_EXPIRED -error is returned. - - If all these checks succeed without an error, the -__________________________ -[11] Note that the rejection here is restricted to au- -thenticators from the same principal to the same -server. Other client principals communicating with the -same server principal should not be have their authen- -ticators rejected if the time and microsecond fields -happen to match some other client's authenticator. - - -Section 3.2.3. - 22 - Expires 11 January 1998 - - - - - - - - Version 5 - Specification Revision 6 - - -server is assured that the client possesses the credentials -of the principal named in the ticket and thus, the client -has been authenticated to the server. See section A.10 for -pseudocode. - - Passing these checks provides only authentication of -the named principal; it does not imply authorization to use -the named service. Applications must make a separate -authorization decisions based upon the authenticated name of -the user, the requested operation, local acces control -information such as that contained in a .k5login or .k5users -file, and possibly a separate distributed authorization ser- -vice. - -3.2.4. Generation of a KRB_AP_REP message - - Typically, a client's request will include both the -authentication information and its initial request in the -same message, and the server need not explicitly reply to -the KRB_AP_REQ. However, if mutual authentication (not only -authenticating the client to the server, but also the server -to the client) is being performed, the KRB_AP_REQ message -will have MUTUAL-REQUIRED set in its ap-options field, and a -KRB_AP_REP message is required in response. As with the -error message, this message may be encapsulated in the -application protocol if its "raw" form is not acceptable to -the application's protocol. The timestamp and microsecond -field used in the reply must be the client's timestamp and -microsecond field (as provided in the authenticator)[12]. -If a sequence number is to be included, it should be ran- -domly chosen as described above for the authenticator. A -subkey may be included if the server desires to negotiate a -different subkey. The KRB_AP_REP message is encrypted in -the session key extracted from the ticket. See section A.11 -for pseudocode. - -3.2.5. Receipt of KRB_AP_REP message - - - If a KRB_AP_REP message is returned, the client uses -the session key from the credentials obtained for the -server[13] to decrypt the message, and verifies that the -__________________________ -[12] In the Kerberos version 4 protocol, the timestamp -in the reply was the client's timestamp plus one. This -is not necessary in version 5 because version 5 mes- -sages are formatted in such a way that it is not possi- -ble to create the reply by judicious message surgery -(even in encrypted form) without knowledge of the ap- -propriate encryption keys. -[13] Note that for encrypting the KRB_AP_REP message, -the sub-session key is not used, even if present in the -Authenticator. - - -Section 3.2.5. - 23 - Expires 11 January 1998 - - - - - - - - Version 5 - Specification Revision 6 - - -timestamp and microsecond fields match those in the Authen- -ticator it sent to the server. If they match, then the -client is assured that the server is genuine. The sequence -number and subkey (if present) are retained for later use. -See section A.12 for pseudocode. - - -3.2.6. Using the encryption key - - After the KRB_AP_REQ/KRB_AP_REP exchange has occurred, -the client and server share an encryption key which can be -used by the application. The "true session key" to be used -for KRB_PRIV, KRB_SAFE, or other application-specific uses -may be chosen by the application based on the subkeys in the -KRB_AP_REP message and the authenticator[14]. In some -cases, the use of this session key will be implicit in the -protocol; in others the method of use must be chosen from -several alternatives. We leave the protocol negotiations of -how to use the key (e.g. selecting an encryption or check- -sum type) to the application programmer; the Kerberos proto- -col does not constrain the implementation options, but an -example of how this might be done follows. - - One way that an application may choose to negotiate a -key to be used for subequent integrity and privacy protec- -tion is for the client to propose a key in the subkey field -of the authenticator. The server can then choose a key -using the proposed key from the client as input, returning -the new subkey in the subkey field of the application reply. -This key could then be used for subsequent communication. -To make this example more concrete, if the encryption method -in use required a 56 bit key, and for whatever reason, one -of the parties was prevented from using a key with more than -40 unknown bits, this method would allow the the party which -is prevented from using more than 40 bits to either propose -(if the client) an initial key with a known quantity for 16 -of those bits, or to mask 16 of the bits (if the server) -with the known quantity. The application implementor is -warned, however, that this is only an example, and that an -analysis of the particular crytosystem to be used, and the -reasons for limiting the key length, must be made before -deciding whether it is acceptable to mask bits of the key. - - With both the one-way and mutual authentication -exchanges, the peers should take care not to send sensitive -information to each other without proper assurances. In -particular, applications that require privacy or integrity -should use the KRB_AP_REP response from the server to client -__________________________ -[14] Implementations of the protocol may wish to pro- -vide routines to choose subkeys based on session keys -and random numbers and to generate a negotiated key to -be returned in the KRB_AP_REP message. - - -Section 3.2.6. - 24 - Expires 11 January 1998 - - - - - - - - Version 5 - Specification Revision 6 - - -to assure both client and server of their peer's identity. -If an application protocol requires privacy of its messages, -it can use the KRB_PRIV message (section 3.5). The KRB_SAFE -message (section 3.4) can be used to assure integrity. - - -3.3. The Ticket-Granting Service (TGS) Exchange - - Summary - Message direction Message type Section - 1. Client to Kerberos KRB_TGS_REQ 5.4.1 - 2. Kerberos to client KRB_TGS_REP or 5.4.2 - KRB_ERROR 5.9.1 - - - The TGS exchange between a client and the Kerberos -Ticket-Granting Server is initiated by a client when it -wishes to obtain authentication credentials for a given -server (which might be registered in a remote realm), when -it wishes to renew or validate an existing ticket, or when -it wishes to obtain a proxy ticket. In the first case, the -client must already have acquired a ticket for the Ticket- -Granting Service using the AS exchange (the ticket-granting -ticket is usually obtained when a client initially authenti- -cates to the system, such as when a user logs in). The mes- -sage format for the TGS exchange is almost identical to that -for the AS exchange. The primary difference is that encryp- -tion and decryption in the TGS exchange does not take place -under the client's key. Instead, the session key from the -ticket-granting ticket or renewable ticket, or sub-session -key from an Authenticator is used. As is the case for all -application servers, expired tickets are not accepted by the -TGS, so once a renewable or ticket-granting ticket expires, -the client must use a separate exchange to obtain valid -tickets. - - The TGS exchange consists of two messages: A request -(KRB_TGS_REQ) from the client to the Kerberos Ticket- -Granting Server, and a reply (KRB_TGS_REP or KRB_ERROR). -The KRB_TGS_REQ message includes information authenticating -the client plus a request for credentials. The authentica- -tion information consists of the authentication header -(KRB_AP_REQ) which includes the client's previously obtained -ticket-granting, renewable, or invalid ticket. In the -ticket-granting ticket and proxy cases, the request may -include one or more of: a list of network addresses, a col- -lection of typed authorization data to be sealed in the -ticket for authorization use by the application server, or -additional tickets (the use of which are described later). -The TGS reply (KRB_TGS_REP) contains the requested creden- -tials, encrypted in the session key from the ticket-granting -ticket or renewable ticket, or if present, in the sub- -session key from the Authenticator (part of the authentica- -tion header). The KRB_ERROR message contains an error code - - -Section 3.3. - 25 - Expires 11 January 1998 - - - - - - - - Version 5 - Specification Revision 6 - - -and text explaining what went wrong. The KRB_ERROR message -is not encrypted. The KRB_TGS_REP message contains informa- -tion which can be used to detect replays, and to associate -it with the message to which it replies. The KRB_ERROR mes- -sage also contains information which can be used to associ- -ate it with the message to which it replies, but the lack of -encryption in the KRB_ERROR message precludes the ability to -detect replays or fabrications of such messages. - -3.3.1. Generation of KRB_TGS_REQ message - - Before sending a request to the ticket-granting ser- -vice, the client must determine in which realm the applica- -tion server is registered[15]. If the client does not -already possess a ticket-granting ticket for the appropriate -realm, then one must be obtained. This is first attempted -by requesting a ticket-granting ticket for the destination -realm from a Kerberos server for which the client does -posess a ticket-granting ticket (using the KRB_TGS_REQ mes- -sage recursively). The Kerberos server may return a TGT for -the desired realm in which case one can proceed. Alterna- -tively, the Kerberos server may return a TGT for a realm -which is "closer" to the desired realm (further along the -standard hierarchical path), in which case this step must be -repeated with a Kerberos server in the realm specified in -the returned TGT. If neither are returned, then the request -must be retried with a Kerberos server for a realm higher in -the hierarchy. This request will itself require a ticket- -granting ticket for the higher realm which must be obtained -by recursively applying these directions. - - - Once the client obtains a ticket-granting ticket for -the appropriate realm, it determines which Kerberos servers -serve that realm, and contacts one. The list might be -obtained through a configuration file or network service or -it may be generated from the name of the realm; as long as -the secret keys exchanged by realms are kept secret, only -denial of service results from using a false Kerberos -server. -__________________________ -[15] This can be accomplished in several ways. It -might be known beforehand (since the realm is part of -the principal identifier), it might be stored in a -nameserver, or it might be obtained from a configura- -tion file. If the realm to be used is obtained from a -nameserver, there is a danger of being spoofed if the -nameservice providing the realm name is not authenti- -cated. This might result in the use of a realm which -has been compromised, and would result in an attacker's -ability to compromise the authentication of the appli- -cation server to the client. - - - -Section 3.3.1. - 26 - Expires 11 January 1998 - - - - - - - - Version 5 - Specification Revision 6 - - - As in the AS exchange, the client may specify a number -of options in the KRB_TGS_REQ message. The client prepares -the KRB_TGS_REQ message, providing an authentication header -as an element of the padata field, and including the same -fields as used in the KRB_AS_REQ message along with several -optional fields: the enc-authorization-data field for appli- -cation server use and additional tickets required by some -options. - - In preparing the authentication header, the client can -select a sub-session key under which the response from the -Kerberos server will be encrypted[16]. If the sub-session -key is not specified, the session key from the ticket- -granting ticket will be used. If the enc-authorization-data -is present, it must be encrypted in the sub-session key, if -present, from the authenticator portion of the authentica- -tion header, or if not present, using the session key from -the ticket-granting ticket. - - Once prepared, the message is sent to a Kerberos server -for the destination realm. See section A.5 for pseudocode. - -3.3.2. Receipt of KRB_TGS_REQ message - - The KRB_TGS_REQ message is processed in a manner simi- -lar to the KRB_AS_REQ message, but there are many additional -checks to be performed. First, the Kerberos server must -determine which server the accompanying ticket is for and it -must select the appropriate key to decrypt it. For a normal -KRB_TGS_REQ message, it will be for the ticket granting ser- -vice, and the TGS's key will be used. If the TGT was issued -by another realm, then the appropriate inter-realm key must -be used. If the accompanying ticket is not a ticket grant- -ing ticket for the current realm, but is for an application -server in the current realm, the RENEW, VALIDATE, or PROXY -options are specified in the request, and the server for -which a ticket is requested is the server named in the -accompanying ticket, then the KDC will decrypt the ticket in -the authentication header using the key of the server for -which it was issued. If no ticket can be found in the -padata field, the KDC_ERR_PADATA_TYPE_NOSUPP error is -returned. - - Once the accompanying ticket has been decrypted, the -user-supplied checksum in the Authenticator must be verified -against the contents of the request, and the message -rejected if the checksums do not match (with an error code -__________________________ -[16] If the client selects a sub-session key, care must -be taken to ensure the randomness of the selected sub- -session key. One approach would be to generate a ran- -dom number and XOR it with the session key from the -ticket-granting ticket. - - -Section 3.3.2. - 27 - Expires 11 January 1998 - - - - - - - - Version 5 - Specification Revision 6 - - -of KRB_AP_ERR_MODIFIED) or if the checksum is not keyed or -not collision-proof (with an error code of -KRB_AP_ERR_INAPP_CKSUM). If the checksum type is not sup- -ported, the KDC_ERR_SUMTYPE_NOSUPP error is returned. If -the authorization-data are present, they are decrypted using -the sub-session key from the Authenticator. - - If any of the decryptions indicate failed integrity -checks, the KRB_AP_ERR_BAD_INTEGRITY error is returned. - -3.3.3. Generation of KRB_TGS_REP message - - The KRB_TGS_REP message shares its format with the -KRB_AS_REP (KRB_KDC_REP), but with its type field set to -KRB_TGS_REP. The detailed specification is in section -5.4.2. - - The response will include a ticket for the requested -server. The Kerberos database is queried to retrieve the -record for the requested server (including the key with -which the ticket will be encrypted). If the request is for -a ticket granting ticket for a remote realm, and if no key -is shared with the requested realm, then the Kerberos server -will select the realm "closest" to the requested realm with -which it does share a key, and use that realm instead. This -is the only case where the response from the KDC will be for -a different server than that requested by the client. - - By default, the address field, the client's name and -realm, the list of transited realms, the time of initial -authentication, the expiration time, and the authorization -data of the newly-issued ticket will be copied from the -ticket-granting ticket (TGT) or renewable ticket. If the -transited field needs to be updated, but the transited type -is not supported, the KDC_ERR_TRTYPE_NOSUPP error is -returned. - - If the request specifies an endtime, then the endtime -of the new ticket is set to the minimum of (a) that request, -(b) the endtime from the TGT, and (c) the starttime of the -TGT plus the minimum of the maximum life for the application -server and the maximum life for the local realm (the maximum -life for the requesting principal was already applied when -the TGT was issued). If the new ticket is to be a renewal, -then the endtime above is replaced by the minimum of (a) the -value of the renew_till field of the ticket and (b) the -starttime for the new ticket plus the life (endtime- -starttime) of the old ticket. - - If the FORWARDED option has been requested, then the -resulting ticket will contain the addresses specified by the -client. This option will only be honored if the FORWARDABLE -flag is set in the TGT. The PROXY option is similar; the -resulting ticket will contain the addresses specified by the - - -Section 3.3.3. - 28 - Expires 11 January 1998 - - - - - - - - Version 5 - Specification Revision 6 - - -client. It will be honored only if the PROXIABLE flag in -the TGT is set. The PROXY option will not be honored on -requests for additional ticket-granting tickets. - - If the requested start time is absent, indicates a time -in the past, or is within the window of acceptable clock -skew for the KDC and the POSTDATE option has not been speci- -fied, then the start time of the ticket is set to the -authentication server's current time. If it indicates a -time in the future beyond the acceptable clock skew, but the -POSTDATED option has not been specified or the MAY-POSTDATE -flag is not set in the TGT, then the error -KDC_ERR_CANNOT_POSTDATE is returned. Otherwise, if the -ticket-granting ticket has the MAY-POSTDATE flag set, then -the resulting ticket will be postdated and the requested -starttime is checked against the policy of the local realm. -If acceptable, the ticket's start time is set as requested, -and the INVALID flag is set. The postdated ticket must be -validated before use by presenting it to the KDC after the -starttime has been reached. However, in no case may the -starttime, endtime, or renew-till time of a newly-issued -postdated ticket extend beyond the renew-till time of the -ticket-granting ticket. - - If the ENC-TKT-IN-SKEY option has been specified and an -additional ticket has been included in the request, the KDC -will decrypt the additional ticket using the key for the -server to which the additional ticket was issued and verify -that it is a ticket-granting ticket. If the name of the -requested server is missing from the request, the name of -the client in the additional ticket will be used. Otherwise -the name of the requested server will be compared to the -name of the client in the additional ticket and if dif- -ferent, the request will be rejected. If the request -succeeds, the session key from the additional ticket will be -used to encrypt the new ticket that is issued instead of -using the key of the server for which the new ticket will be -used[17]. - - If the name of the server in the ticket that is -presented to the KDC as part of the authentication header is -not that of the ticket-granting server itself, the server is -registered in the realm of the KDC, and the RENEW option is -requested, then the KDC will verify that the RENEWABLE flag -is set in the ticket, that the INVALID flag is not set in -the ticket, and that the renew_till time is still in the -future. If the VALIDATE option is rqeuested, the KDC will -__________________________ -[17] This allows easy implementation of user-to-user -authentication [8], which uses ticket-granting ticket -session keys in lieu of secret server keys in situa- -tions where such secret keys could be easily comprom- -ised. - - -Section 3.3.3. - 29 - Expires 11 January 1998 - - - - - - - - Version 5 - Specification Revision 6 - - -check that the starttime has passed and the INVALID flag is -set. If the PROXY option is requested, then the KDC will -check that the PROXIABLE flag is set in the ticket. If the -tests succeed, and the ticket passes the hotlist check -described in the next paragraph, the KDC will issue the -appropriate new ticket. - - -3.3.3.1. Checking for revoked tickets - - Whenever a request is made to the ticket-granting -server, the presented ticket(s) is(are) checked against a -hot-list of tickets which have been canceled. This hot-list -might be implemented by storing a range of issue timestamps -for "suspect tickets"; if a presented ticket had an authtime -in that range, it would be rejected. In this way, a stolen -ticket-granting ticket or renewable ticket cannot be used to -gain additional tickets (renewals or otherwise) once the -theft has been reported. Any normal ticket obtained before -it was reported stolen will still be valid (because they -require no interaction with the KDC), but only until their -normal expiration time. - - The ciphertext part of the response in the KRB_TGS_REP -message is encrypted in the sub-session key from the Authen- -ticator, if present, or the session key key from the -ticket-granting ticket. It is not encrypted using the -client's secret key. Furthermore, the client's key's -expiration date and the key version number fields are left -out since these values are stored along with the client's -database record, and that record is not needed to satisfy a -request based on a ticket-granting ticket. See section A.6 -for pseudocode. - -3.3.3.2. Encoding the transited field - - If the identity of the server in the TGT that is -presented to the KDC as part of the authentication header is -that of the ticket-granting service, but the TGT was issued -from another realm, the KDC will look up the inter-realm key -shared with that realm and use that key to decrypt the -ticket. If the ticket is valid, then the KDC will honor the -request, subject to the constraints outlined above in the -section describing the AS exchange. The realm part of the -client's identity will be taken from the ticket-granting -ticket. The name of the realm that issued the ticket- -granting ticket will be added to the transited field of the -ticket to be issued. This is accomplished by reading the -transited field from the ticket-granting ticket (which is -treated as an unordered set of realm names), adding the new -realm to the set, then constructing and writing out its -encoded (shorthand) form (this may involve a rearrangement -of the existing encoding). - - - -Section 3.3.3.2. - 30 - Expires 11 January 1998 - - - - - - - - Version 5 - Specification Revision 6 - - - Note that the ticket-granting service does not add the -name of its own realm. Instead, its responsibility is to -add the name of the previous realm. This prevents a mali- -cious Kerberos server from intentionally leaving out its own -name (it could, however, omit other realms' names). - - The names of neither the local realm nor the -principal's realm are to be included in the transited field. -They appear elsewhere in the ticket and both are known to -have taken part in authenticating the principal. Since the -endpoints are not included, both local and single-hop -inter-realm authentication result in a transited field that -is empty. - - Because the name of each realm transited is added to -this field, it might potentially be very long. To decrease -the length of this field, its contents are encoded. The -initially supported encoding is optimized for the normal -case of inter-realm communication: a hierarchical arrange- -ment of realms using either domain or X.500 style realm -names. This encoding (called DOMAIN-X500-COMPRESS) is now -described. - - Realm names in the transited field are separated by a -",". The ",", "\", trailing "."s, and leading spaces (" ") -are special characters, and if they are part of a realm -name, they must be quoted in the transited field by preced- -ing them with a "\". - - A realm name ending with a "." is interpreted as being -prepended to the previous realm. For example, we can encode -traversal of EDU, MIT.EDU, ATHENA.MIT.EDU, WASHINGTON.EDU, -and CS.WASHINGTON.EDU as: - - "EDU,MIT.,ATHENA.,WASHINGTON.EDU,CS.". - -Note that if ATHENA.MIT.EDU, or CS.WASHINGTON.EDU were end- -points, that they would not be included in this field, and -we would have: - - "EDU,MIT.,WASHINGTON.EDU" - -A realm name beginning with a "/" is interpreted as being -appended to the previous realm[18]. If it is to stand by -itself, then it should be preceded by a space (" "). For -example, we can encode traversal of /COM/HP/APOLLO, /COM/HP, -/COM, and /COM/DEC as: - - "/COM,/HP,/APOLLO, /COM/DEC". -__________________________ -[18] For the purpose of appending, the realm preceding -the first listed realm is considered to be the null -realm (""). - - -Section 3.3.3.2. - 31 - Expires 11 January 1998 - - - - - - - - Version 5 - Specification Revision 6 - - -Like the example above, if /COM/HP/APOLLO and /COM/DEC are -endpoints, they they would not be included in this field, -and we would have: - - "/COM,/HP" - - - A null subfield preceding or following a "," indicates -that all realms between the previous realm and the next -realm have been traversed[19]. Thus, "," means that all -realms along the path between the client and the server have -been traversed. ",EDU, /COM," means that that all realms -from the client's realm up to EDU (in a domain style hierar- -chy) have been traversed, and that everything from /COM down -to the server's realm in an X.500 style has also been -traversed. This could occur if the EDU realm in one hierar- -chy shares an inter-realm key directly with the /COM realm -in another hierarchy. - -3.3.4. Receipt of KRB_TGS_REP message - -When the KRB_TGS_REP is received by the client, it is pro- -cessed in the same manner as the KRB_AS_REP processing -described above. The primary difference is that the cipher- -text part of the response must be decrypted using the ses- -sion key from the ticket-granting ticket rather than the -client's secret key. See section A.7 for pseudocode. - - -3.4. The KRB_SAFE Exchange - - The KRB_SAFE message may be used by clients requiring -the ability to detect modifications of messages they -exchange. It achieves this by including a keyed collision- -proof checksum of the user data and some control informa- -tion. The checksum is keyed with an encryption key (usually -the last key negotiated via subkeys, or the session key if -no negotiation has occured). - -3.4.1. Generation of a KRB_SAFE message - -When an application wishes to send a KRB_SAFE message, it -collects its data and the appropriate control information -and computes a checksum over them. The checksum algorithm -should be a keyed one-way hash function (such as the RSA- -MD5-DES checksum algorithm specified in section 6.4.5, or -the DES MAC), generated using the sub-session key if -present, or the session key. Different algorithms may be -__________________________ -[19] For the purpose of interpreting null subfields, -the client's realm is considered to precede those in -the transited field, and the server's realm is con- -sidered to follow them. - - -Section 3.4.1. - 32 - Expires 11 January 1998 - - - - - - - - Version 5 - Specification Revision 6 - - -selected by changing the checksum type in the message. -Unkeyed or non-collision-proof checksums are not suitable -for this use. - - The control information for the KRB_SAFE message -includes both a timestamp and a sequence number. The -designer of an application using the KRB_SAFE message must -choose at least one of the two mechanisms. This choice -should be based on the needs of the application protocol. - - Sequence numbers are useful when all messages sent will -be received by one's peer. Connection state is presently -required to maintain the session key, so maintaining the -next sequence number should not present an additional prob- -lem. - - If the application protocol is expected to tolerate -lost messages without them being resent, the use of the -timestamp is the appropriate replay detection mechanism. -Using timestamps is also the appropriate mechanism for -multi-cast protocols where all of one's peers share a common -sub-session key, but some messages will be sent to a subset -of one's peers. - - After computing the checksum, the client then transmits -the information and checksum to the recipient in the message -format specified in section 5.6.1. - -3.4.2. Receipt of KRB_SAFE message - -When an application receives a KRB_SAFE message, it verifies -it as follows. If any error occurs, an error code is -reported for use by the application. - - The message is first checked by verifying that the pro- -tocol version and type fields match the current version and -KRB_SAFE, respectively. A mismatch generates a -KRB_AP_ERR_BADVERSION or KRB_AP_ERR_MSG_TYPE error. The -application verifies that the checksum used is a collision- -proof keyed checksum, and if it is not, a -KRB_AP_ERR_INAPP_CKSUM error is generated. The recipient -verifies that the operating system's report of the sender's -address matches the sender's address in the message, and (if -a recipient address is specified or the recipient requires -an address) that one of the recipient's addresses appears as -the recipient's address in the message. A failed match for -either case generates a KRB_AP_ERR_BADADDR error. Then the -timestamp and usec and/or the sequence number fields are -checked. If timestamp and usec are expected and not -present, or they are present but not current, the -KRB_AP_ERR_SKEW error is generated. If the server name, -along with the client name, time and microsecond fields from -the Authenticator match any recently-seen (sent or -received[20] ) such tuples, the KRB_AP_ERR_REPEAT error is -__________________________ -[20] This means that a client and server running on the - - - - - - - Version 5 - Specification Revision 6 - - -generated. If an incorrect sequence number is included, or -a sequence number is expected but not present, the -KRB_AP_ERR_BADORDER error is generated. If neither a time- -stamp and usec or a sequence number is present, a -KRB_AP_ERR_MODIFIED error is generated. Finally, the check- -sum is computed over the data and control information, and -if it doesn't match the received checksum, a -KRB_AP_ERR_MODIFIED error is generated. - - If all the checks succeed, the application is assured -that the message was generated by its peer and was not modi- -fied in transit. - -3.5. The KRB_PRIV Exchange - - The KRB_PRIV message may be used by clients requiring -confidentiality and the ability to detect modifications of -exchanged messages. It achieves this by encrypting the mes- -sages and adding control information. - -3.5.1. Generation of a KRB_PRIV message - -When an application wishes to send a KRB_PRIV message, it -collects its data and the appropriate control information -(specified in section 5.7.1) and encrypts them under an -encryption key (usually the last key negotiated via subkeys, -or the session key if no negotiation has occured). As part -of the control information, the client must choose to use -either a timestamp or a sequence number (or both); see the -discussion in section 3.4.1 for guidelines on which to use. -After the user data and control information are encrypted, -the client transmits the ciphertext and some "envelope" -information to the recipient. - -3.5.2. Receipt of KRB_PRIV message - -When an application receives a KRB_PRIV message, it verifies -it as follows. If any error occurs, an error code is -reported for use by the application. - - The message is first checked by verifying that the pro- -tocol version and type fields match the current version and -KRB_PRIV, respectively. A mismatch generates a -KRB_AP_ERR_BADVERSION or KRB_AP_ERR_MSG_TYPE error. The -application then decrypts the ciphertext and processes the -resultant plaintext. If decryption shows the data to have -been modified, a KRB_AP_ERR_BAD_INTEGRITY error is gen- -erated. The recipient verifies that the operating system's -report of the sender's address matches the sender's address -__________________________ -same host and communicating with one another using the -KRB_SAFE messages should not share a common replay -cache to detect KRB_SAFE replays. - - - -Section 3.5.2. - 34 - Expires 11 January 1998 - - - - - - - - Version 5 - Specification Revision 6 - - -in the message, and (if a recipient address is specified or -the recipient requires an address) that one of the -recipient's addresses appears as the recipient's address in -the message. A failed match for either case generates a -KRB_AP_ERR_BADADDR error. Then the timestamp and usec -and/or the sequence number fields are checked. If timestamp -and usec are expected and not present, or they are present -but not current, the KRB_AP_ERR_SKEW error is generated. If -the server name, along with the client name, time and -microsecond fields from the Authenticator match any -recently-seen such tuples, the KRB_AP_ERR_REPEAT error is -generated. If an incorrect sequence number is included, or -a sequence number is expected but not present, the -KRB_AP_ERR_BADORDER error is generated. If neither a time- -stamp and usec or a sequence number is present, a -KRB_AP_ERR_MODIFIED error is generated. - - If all the checks succeed, the application can assume -the message was generated by its peer, and was securely -transmitted (without intruders able to see the unencrypted -contents). - -3.6. The KRB_CRED Exchange - - The KRB_CRED message may be used by clients requiring -the ability to send Kerberos credentials from one host to -another. It achieves this by sending the tickets together -with encrypted data containing the session keys and other -information associated with the tickets. - -3.6.1. Generation of a KRB_CRED message - -When an application wishes to send a KRB_CRED message it -first (using the KRB_TGS exchange) obtains credentials to be -sent to the remote host. It then constructs a KRB_CRED mes- -sage using the ticket or tickets so obtained, placing the -session key needed to use each ticket in the key field of -the corresponding KrbCredInfo sequence of the encrypted part -of the the KRB_CRED message. - - Other information associated with each ticket and -obtained during the KRB_TGS exchange is also placed in the -corresponding KrbCredInfo sequence in the encrypted part of -the KRB_CRED message. The current time and, if specifically -required by the application the nonce, s-address, and r- -address fields, are placed in the encrypted part of the -KRB_CRED message which is then encrypted under an encryption -key previosuly exchanged in the KRB_AP exchange (usually the -last key negotiated via subkeys, or the session key if no -negotiation has occured). - -3.6.2. Receipt of KRB_CRED message - -When an application receives a KRB_CRED message, it verifies - - -Section 3.6.2. - 35 - Expires 11 January 1998 - - - - - - - - Version 5 - Specification Revision 6 - - -it. If any error occurs, an error code is reported for use -by the application. The message is verified by checking -that the protocol version and type fields match the current -version and KRB_CRED, respectively. A mismatch generates a -KRB_AP_ERR_BADVERSION or KRB_AP_ERR_MSG_TYPE error. The -application then decrypts the ciphertext and processes the -resultant plaintext. If decryption shows the data to have -been modified, a KRB_AP_ERR_BAD_INTEGRITY error is gen- -erated. - - If present or required, the recipient verifies that the -operating system's report of the sender's address matches -the sender's address in the message, and that one of the -recipient's addresses appears as the recipient's address in -the message. A failed match for either case generates a -KRB_AP_ERR_BADADDR error. The timestamp and usec fields -(and the nonce field if required) are checked next. If the -timestamp and usec are not present, or they are present but -not current, the KRB_AP_ERR_SKEW error is generated. - - If all the checks succeed, the application stores each -of the new tickets in its ticket cache together with the -session key and other information in the corresponding -KrbCredInfo sequence from the encrypted part of the KRB_CRED -message. - -4. The Kerberos Database - -The Kerberos server must have access to a database contain- -ing the principal identifiers and secret keys of principals -to be authenticated[21]. - -4.1. Database contents - -A database entry should contain at least the following -fields: - -Field Value - -name Principal's identif- -ier -key Principal's secret key -p_kvno Principal's key version -max_life Maximum lifetime for Tickets -__________________________ -[21] The implementation of the Kerberos server need not -combine the database and the server on the same -machine; it is feasible to store the principal database -in, say, a network name service, as long as the entries -stored therein are protected from disclosure to and -modification by unauthorized parties. However, we -recommend against such strategies, as they can make -system management and threat analysis quite complex. - - -Section 4.1. - 36 - Expires 11 January 1998 - - - - - - - - Version 5 - Specification Revision 6 - - -max_renewable_life Maximum total lifetime for renewable Tickets - -The name field is an encoding of the principal's identifier. -The key field contains an encryption key. This key is the -principal's secret key. (The key can be encrypted before -storage under a Kerberos "master key" to protect it in case -the database is compromised but the master key is not. In -that case, an extra field must be added to indicate the mas- -ter key version used, see below.) The p_kvno field is the -key version number of the principal's secret key. The -max_life field contains the maximum allowable lifetime (end- -time - starttime) for any Ticket issued for this principal. -The max_renewable_life field contains the maximum allowable -total lifetime for any renewable Ticket issued for this -principal. (See section 3.1 for a description of how these -lifetimes are used in determining the lifetime of a given -Ticket.) - - A server may provide KDC service to several realms, as -long as the database representation provides a mechanism to -distinguish between principal records with identifiers which -differ only in the realm name. - - When an application server's key changes, if the change -is routine (i.e. not the result of disclosure of the old -key), the old key should be retained by the server until all -tickets that had been issued using that key have expired. -Because of this, it is possible for several keys to be -active for a single principal. Ciphertext encrypted in a -principal's key is always tagged with the version of the key -that was used for encryption, to help the recipient find the -proper key for decryption. - - When more than one key is active for a particular prin- -cipal, the principal will have more than one record in the -Kerberos database. The keys and key version numbers will -differ between the records (the rest of the fields may or -may not be the same). Whenever Kerberos issues a ticket, or -responds to a request for initial authentication, the most -recent key (known by the Kerberos server) will be used for -encryption. This is the key with the highest key version -number. - -4.2. Additional fields - -Project Athena's KDC implementation uses additional fields -in its database: - -Field Value - -K_kvno Kerberos' key version -expiration Expiration date for entry -attributes Bit field of attributes -mod_date Timestamp of last modification - - -Section 4.2. - 37 - Expires 11 January 1998 - - - - - - - - Version 5 - Specification Revision 6 - - -mod_name Modifying principal's identifier - - -The K_kvno field indicates the key version of the Kerberos -master key under which the principal's secret key is -encrypted. - - After an entry's expiration date has passed, the KDC -will return an error to any client attempting to gain tick- -ets as or for the principal. (A database may want to main- -tain two expiration dates: one for the principal, and one -for the principal's current key. This allows password aging -to work independently of the principal's expiration date. -However, due to the limited space in the responses, the KDC -must combine the key expiration and principal expiration -date into a single value called "key_exp", which is used as -a hint to the user to take administrative action.) - - The attributes field is a bitfield used to govern the -operations involving the principal. This field might be -useful in conjunction with user registration procedures, for -site-specific policy implementations (Project Athena -currently uses it for their user registration process con- -trolled by the system-wide database service, Moira [9]), to -identify whether a principal can play the role of a client -or server or both, to note whether a server is appropriate -trusted to recieve credentials delegated by a client, or to -identify the "string to key" conversion algorithm used for a -principal's key[22]. Other bits are used to indicate that -certain ticket options should not be allowed in tickets -encrypted under a principal's key (one bit each): Disallow -issuing postdated tickets, disallow issuing forwardable -tickets, disallow issuing tickets based on TGT authentica- -tion, disallow issuing renewable tickets, disallow issuing -proxiable tickets, and disallow issuing tickets for which -the principal is the server. - - The mod_date field contains the time of last modifica- -tion of the entry, and the mod_name field contains the name -of the principal which last modified the entry. - -4.3. Frequently Changing Fields - - Some KDC implementations may wish to maintain the last -time that a request was made by a particular principal. -Information that might be maintained includes the time of -the last request, the time of the last request for a -ticket-granting ticket, the time of the last use of a -ticket-granting ticket, or other times. This information -can then be returned to the user in the last-req field (see -__________________________ -[22] See the discussion of the padata field in section -5.4.2 for details on why this can be useful. - - -Section 4.3. - 38 - Expires 11 January 1998 - - - - - - - - Version 5 - Specification Revision 6 - - -section 5.2). - - Other frequently changing information that can be main- -tained is the latest expiration time for any tickets that -have been issued using each key. This field would be used -to indicate how long old keys must remain valid to allow the -continued use of outstanding tickets. - -4.4. Site Constants - - The KDC implementation should have the following confi- -gurable constants or options, to allow an administrator to -make and enforce policy decisions: - -+ The minimum supported lifetime (used to determine whether - the KDC_ERR_NEVER_VALID error should be returned). This - constant should reflect reasonable expectations of - round-trip time to the KDC, encryption/decryption time, - and processing time by the client and target server, and - it should allow for a minimum "useful" lifetime. - -+ The maximum allowable total (renewable) lifetime of a - ticket (renew_till - starttime). - -+ The maximum allowable lifetime of a ticket (endtime - - starttime). - -+ Whether to allow the issue of tickets with empty address - fields (including the ability to specify that such tick- - ets may only be issued if the request specifies some - authorization_data). - -+ Whether proxiable, forwardable, renewable or post-datable - tickets are to be issued. - - -5. Message Specifications - - The following sections describe the exact contents and -encoding of protocol messages and objects. The ASN.1 base -definitions are presented in the first subsection. The -remaining subsections specify the protocol objects (tickets -and authenticators) and messages. Specification of encryp- -tion and checksum techniques, and the fields related to -them, appear in section 6. - -5.1. ASN.1 Distinguished Encoding Representation - - All uses of ASN.1 in Kerberos shall use the Dis- -tinguished Encoding Representation of the data elements as -described in the X.509 specification, section 8.7 [10]. - - - - - -Section 5.1. - 39 - Expires 11 January 1998 - - - - - - - - Version 5 - Specification Revision 6 - - -5.2. ASN.1 Base Definitions - - The following ASN.1 base definitions are used in the -rest of this section. Note that since the underscore char- -acter (_) is not permitted in ASN.1 names, the hyphen (-) is -used in its place for the purposes of ASN.1 names. - -Realm ::= GeneralString -PrincipalName ::= SEQUENCE { - name-type[0] INTEGER, - name-string[1] SEQUENCE OF GeneralString -} - - -Kerberos realms are encoded as GeneralStrings. Realms shall -not contain a character with the code 0 (the ASCII NUL). -Most realms will usually consist of several components -separated by periods (.), in the style of Internet Domain -Names, or separated by slashes (/) in the style of X.500 -names. Acceptable forms for realm names are specified in -section 7. A PrincipalName is a typed sequence of com- -ponents consisting of the following sub-fields: - -name-type This field specifies the type of name that fol- - lows. Pre-defined values for this field are - specified in section 7.2. The name-type should be - treated as a hint. Ignoring the name type, no two - names can be the same (i.e. at least one of the - components, or the realm, must be different). - This constraint may be eliminated in the future. - -name-stringThis field encodes a sequence of components that - form a name, each component encoded as a General- - String. Taken together, a PrincipalName and a - Realm form a principal identifier. Most Princi- - palNames will have only a few components (typi- - cally one or two). - - - - KerberosTime ::= GeneralizedTime - -- Specifying UTC time zone (Z) - - - The timestamps used in Kerberos are encoded as General- -izedTimes. An encoding shall specify the UTC time zone (Z) -and shall not include any fractional portions of the -seconds. It further shall not include any separators. -Example: The only valid format for UTC time 6 minutes, 27 -seconds after 9 pm on 6 November 1985 is 19851106210627Z. - - HostAddress ::= SEQUENCE { - addr-type[0] INTEGER, - address[1] OCTET STRING - - -Section 5.2. - 40 - Expires 11 January 1998 - - - - - - - - Version 5 - Specification Revision 6 - - - } - - HostAddresses ::= SEQUENCE OF SEQUENCE { - addr-type[0] INTEGER, - address[1] OCTET STRING - } - - - The host adddress encodings consists of two fields: - -addr-type This field specifies the type of address that - follows. Pre-defined values for this field are - specified in section 8.1. - - -address This field encodes a single address of type addr- - type. - -The two forms differ slightly. HostAddress contains exactly -one address; HostAddresses contains a sequence of possibly -many addresses. - -AuthorizationData ::= SEQUENCE OF SEQUENCE { - ad-type[0] INTEGER, - ad-data[1] OCTET STRING -} - - -ad-data This field contains authorization data to be - interpreted according to the value of the - corresponding ad-type field. - -ad-type This field specifies the format for the ad-data - subfield. All negative values are reserved for - local use. Non-negative values are reserved for - registered use. - - APOptions ::= BIT STRING { - reserved(0), - use-session-key(1), - mutual-required(2) - } - - - TicketFlags ::= BIT STRING { - reserved(0), - forwardable(1), - forwarded(2), - proxiable(3), - proxy(4), - may-postdate(5), - postdated(6), - invalid(7), - renewable(8), - initial(9), - - -Section 5.2. - 41 - Expires 11 January 1998 - - - - - - - - Version 5 - Specification Revision 6 - - - pre-authent(10), - hw-authent(11), - transited-policy-checked(12), - ok-as-delegate(13) - } - - - KDCOptions ::= BIT STRING { - reserved(0), - forwardable(1), - forwarded(2), - proxiable(3), - proxy(4), - allow-postdate(5), - postdated(6), - unused7(7), - renewable(8), - unused9(9), - unused10(10), - unused11(11), - unused12(12), - unused13(13), - disable-transited-check(26), - renewable-ok(27), - enc-tkt-in-skey(28), - renew(30), - validate(31) - } - - ASN.1 Bit strings have a length and a value. When - used in Kerberos for the APOptions, TicketFlags, - and KDCOptions, the length of the bit string on - generated values should be the smallest multiple - of 32 bits needed to include the highest order bit - that is set (1), but in no case less than 32 bits. - Implementations should accept values of bit - strings of any length and treat the value of flags - cooresponding to bits beyond the end of the bit - string as if the bit were reset (0). Comparisonof - bit strings of different length should treat the - smaller string as if it were padded with zeros - beyond the high order bits to the length of the - longer string[23]. - -__________________________ -[23] Warning for implementations that unpack and repack -data structures during the generation and verification -of embedded checksums: Because any checksums applied to -data structures must be checked against the original -data the length of bit strings must be preserved within -a data structure between the time that a checksum is -generated through transmission to the time that the -checksum is verified. - - - -Section 5.2. - 42 - Expires 11 January 1998 - - - - - - - - Version 5 - Specification Revision 6 - - - LastReq ::= SEQUENCE OF SEQUENCE { - lr-type[0] INTEGER, - lr-value[1] KerberosTime - } - - -lr-type This field indicates how the following lr-value - field is to be interpreted. Negative values indi- - cate that the information pertains only to the - responding server. Non-negative values pertain to - all servers for the realm. - - If the lr-type field is zero (0), then no informa- - tion is conveyed by the lr-value subfield. If the - absolute value of the lr-type field is one (1), - then the lr-value subfield is the time of last - initial request for a TGT. If it is two (2), then - the lr-value subfield is the time of last initial - request. If it is three (3), then the lr-value - subfield is the time of issue for the newest - ticket-granting ticket used. If it is four (4), - then the lr-value subfield is the time of the last - renewal. If it is five (5), then the lr-value - subfield is the time of last request (of any - type). - - -lr-value This field contains the time of the last request. - The time must be interpreted according to the con- - tents of the accompanying lr-type subfield. - - See section 6 for the definitions of Checksum, Check- -sumType, EncryptedData, EncryptionKey, EncryptionType, and -KeyType. - - -5.3. Tickets and Authenticators - - This section describes the format and encryption param- -eters for tickets and authenticators. When a ticket or -authenticator is included in a protocol message it is -treated as an opaque object. - -5.3.1. Tickets - - A ticket is a record that helps a client authenticate -to a service. A Ticket contains the following information: - -Ticket ::= [APPLICATION 1] SEQUENCE { - tkt-vno[0] INTEGER, - realm[1] Realm, - sname[2] PrincipalName, - enc-part[3] EncryptedData -} - - -Section 5.3.1. - 43 - Expires 11 January 1998 - - - - - - - - Version 5 - Specification Revision 6 - - --- Encrypted part of ticket -EncTicketPart ::= [APPLICATION 3] SEQUENCE { - flags[0] TicketFlags, - key[1] EncryptionKey, - crealm[2] Realm, - cname[3] PrincipalName, - transited[4] TransitedEncoding, - authtime[5] KerberosTime, - starttime[6] KerberosTime OPTIONAL, - endtime[7] KerberosTime, - renew-till[8] KerberosTime OPTIONAL, - caddr[9] HostAddresses OPTIONAL, - authorization-data[10] AuthorizationData OPTIONAL -} --- encoded Transited field -TransitedEncoding ::= SEQUENCE { - tr-type[0] INTEGER, -- must be registered - contents[1] OCTET STRING -} - -The encoding of EncTicketPart is encrypted in the key shared -by Kerberos and the end server (the server's secret key). -See section 6 for the format of the ciphertext. - -tkt-vno This field specifies the version number for the - ticket format. This document describes version - number 5. - - -realm This field specifies the realm that issued a - ticket. It also serves to identify the realm part - of the server's principal identifier. Since a - Kerberos server can only issue tickets for servers - within its realm, the two will always be identi- - cal. - - -sname This field specifies the name part of the server's - identity. - - -enc-part This field holds the encrypted encoding of the - EncTicketPart sequence. - - -flags This field indicates which of various options were - used or requested when the ticket was issued. It - is a bit-field, where the selected options are - indicated by the bit being set (1), and the - unselected options and reserved fields being reset - (0). Bit 0 is the most significant bit. The - encoding of the bits is specified in section 5.2. - The flags are described in more detail above in - section 2. The meanings of the flags are: - - -Section 5.3.1. - 44 - Expires 11 January 1998 - - - - - - Version 5 - Specification Revision 6 - - - Bit(s) Name Description - - 0 RESERVED - Reserved for future expansion of this - field. - - 1 FORWARDABLE - The FORWARDABLE flag is normally only - interpreted by the TGS, and can be - ignored by end servers. When set, this - flag tells the ticket-granting server - that it is OK to issue a new ticket- - granting ticket with a different network - address based on the presented ticket. - - 2 FORWARDED - When set, this flag indicates that the - ticket has either been forwarded or was - issued based on authentication involving - a forwarded ticket-granting ticket. - - 3 PROXIABLE - The PROXIABLE flag is normally only - interpreted by the TGS, and can be - ignored by end servers. The PROXIABLE - flag has an interpretation identical to - that of the FORWARDABLE flag, except - that the PROXIABLE flag tells the - ticket-granting server that only non- - ticket-granting tickets may be issued - with different network addresses. - - 4 PROXY - When set, this flag indicates that a - ticket is a proxy. - - 5 MAY-POSTDATE - The MAY-POSTDATE flag is normally only - interpreted by the TGS, and can be - ignored by end servers. This flag tells - the ticket-granting server that a post- - dated ticket may be issued based on this - ticket-granting ticket. - - 6 POSTDATED - This flag indicates that this ticket has - been postdated. The end-service can - check the authtime field to see when the - original authentication occurred. - - 7 INVALID - This flag indicates that a ticket is - invalid, and it must be validated by the - KDC before use. Application servers - must reject tickets which have this flag - set. - - - - - - - - -Section 5.3.1. - 45 - Expires 11 January 1998 - - - - - - - - Version 5 - Specification Revision 6 - - - 8 RENEWABLE - The RENEWABLE flag is normally only - interpreted by the TGS, and can usually - be ignored by end servers (some particu- - larly careful servers may wish to disal- - low renewable tickets). A renewable - ticket can be used to obtain a replace- - ment ticket that expires at a later - date. - - 9 INITIAL - This flag indicates that this ticket was - issued using the AS protocol, and not - issued based on a ticket-granting - ticket. - - 10 PRE-AUTHENT - This flag indicates that during initial - authentication, the client was authenti- - cated by the KDC before a ticket was - issued. The strength of the pre- - authentication method is not indicated, - but is acceptable to the KDC. - - 11 HW-AUTHENT - This flag indicates that the protocol - employed for initial authentication - required the use of hardware expected to - be possessed solely by the named client. - The hardware authentication method is - selected by the KDC and the strength of - the method is not indicated. - - - - -Section 5.3.1. - 46 - Expires 11 January 1998 - - - - - - - - Version 5 - Specification Revision 6 - - - 12 TRANSITED This flag indicates that the KDC for the - POLICY-CHECKED realm has checked the transited field - against a realm defined policy for - trusted certifiers. If this flag is - reset (0), then the application server - must check the transited field itself, - and if unable to do so it must reject - the authentication. If the flag is set - (1) then the application server may skip - its own validation of the transited - field, relying on the validation - performed by the KDC. At its option the - application server may still apply its - own validation based on a separate - policy for acceptance. - -Section 5.3.1. - 47 - Expires 11 January 1998 - - - - - - - - Version 5 - Specification Revision 6 - - - 13 OK-AS-DELEGATE This flag indicates that the server (not - the client) specified in the ticket has - been determined by policy of the realm - to be a suitable recipient of - delegation. A client can use the - presence of this flag to help it make a - decision whether to delegate credentials - (either grant a proxy or a forwarded - ticket granting ticket) to this server. - The client is free to ignore the value - of this flag. When setting this flag, - an administrator should consider the - security and placement of the server on - which the service will run, as well as - whether the service requires the use of - delegated credentials. - - - - -Section 5.3.1. - 48 - Expires 11 January 1998 - - - - - - - - Version 5 - Specification Revision 6 - - - 14 ANONYMOUS - This flag indicates that the principal - named in the ticket is a generic princi- - pal for the realm and does not identify - the individual using the ticket. The - purpose of the ticket is only to - securely distribute a session key, and - not to identify the user. Subsequent - requests using the same ticket and ses- - sion may be considered as originating - from the same user, but requests with - the same username but a different ticket - are likely to originate from different - users. - - 15-31 RESERVED - Reserved for future use. - - - -key This field exists in the ticket and the KDC - response and is used to pass the session key from - Kerberos to the application server and the client. - The field's encoding is described in section 6.2. - -crealm This field contains the name of the realm in which - the client is registered and in which initial - authentication took place. - - -cname This field contains the name part of the client's - principal identifier. - - -transited This field lists the names of the Kerberos realms - that took part in authenticating the user to whom - this ticket was issued. It does not specify the - order in which the realms were transited. See - section 3.3.3.2 for details on how this field - encodes the traversed realms. - - -authtime This field indicates the time of initial authenti- - cation for the named principal. It is the time of - issue for the original ticket on which this ticket - is based. It is included in the ticket to provide - additional information to the end service, and to - provide the necessary information for implementa- - tion of a `hot list' service at the KDC. An end - service that is particularly paranoid could refuse - to accept tickets for which the initial authenti- - cation occurred "too far" in the past. - - This field is also returned as part of the - response from the KDC. When returned as part of - the response to initial authentication - - -Section 5.3.1. - 49 - Expires 11 January 1998 - - - - - - - - Version 5 - Specification Revision 6 - - - (KRB_AS_REP), this is the current time on the Ker- - beros server[24]. - - -starttime This field in the ticket specifies the time after - which the ticket is valid. Together with endtime, - this field specifies the life of the ticket. If - it is absent from the ticket, its value should be - treated as that of the authtime field. - - -endtime This field contains the time after which the - ticket will not be honored (its expiration time). - Note that individual services may place their own - limits on the life of a ticket and may reject - tickets which have not yet expired. As such, this - is really an upper bound on the expiration time - for the ticket. - - -renew-tillThis field is only present in tickets that have - the RENEWABLE flag set in the flags field. It - indicates the maximum endtime that may be included - in a renewal. It can be thought of as the abso- - lute expiration time for the ticket, including all - renewals. - - -caddr This field in a ticket contains zero (if omitted) - or more (if present) host addresses. These are - the addresses from which the ticket can be used. - If there are no addresses, the ticket can be used - from any location. The decision by the KDC to - issue or by the end server to accept zero-address - tickets is a policy decision and is left to the - Kerberos and end-service administrators; they may - refuse to issue or accept such tickets. The sug- - gested and default policy, however, is that such - tickets will only be issued or accepted when addi- - tional information that can be used to restrict - the use of the ticket is included in the - authorization_data field. Such a ticket is a - capability. - - Network addresses are included in the ticket to - make it harder for an attacker to use stolen - credentials. Because the session key is not sent - over the network in cleartext, credentials can't -__________________________ -[24] It is NOT recommended that this time value be used -to adjust the workstation's clock since the workstation -cannot reliably determine that such a KRB_AS_REP actu- -ally came from the proper KDC in a timely manner. - - -Section 5.3.1. - 50 - Expires 11 January 1998 - - - - - - - - Version 5 - Specification Revision 6 - - - be stolen simply by listening to the network; an - attacker has to gain access to the session key - (perhaps through operating system security - breaches or a careless user's unattended session) - to make use of stolen tickets. - - It is important to note that the network address - from which a connection is received cannot be - reliably determined. Even if it could be, an - attacker who has compromised the client's worksta- - tion could use the credentials from there. - Including the network addresses only makes it more - difficult, not impossible, for an attacker to walk - off with stolen credentials and then use them from - a "safe" location. - - -authorization-data - The authorization-data field is used to pass - authorization data from the principal on whose - behalf a ticket was issued to the application ser- - vice. If no authorization data is included, this - field will be left out. Experience has shown that - the name of this field is confusing, and that a - better name for this field would be restrictions. - Unfortunately, it is not possible to change the - name of this field at this time. - - This field contains restrictions on any authority - obtained on the bases of authentication using the - ticket. It is possible for any principal in - posession of credentials to add entries to the - authorization data field since these entries - further restrict what can be done with the ticket. - Such additions can be made by specifying the addi- - tional entries when a new ticket is obtained dur- - ing the TGS exchange, or they may be added during - chained delegation using the authorization data - field of the authenticator. - - Because entries may be added to this field by the - holder of credentials, it is not allowable for the - presence of an entry in the authorization data - field of a ticket to amplify the priveleges one - would obtain from using a ticket. - - The data in this field may be specific to the end - service; the field will contain the names of ser- - vice specific objects, and the rights to those - objects. The format for this field is described - in section 5.2. Although Kerberos is not con- - cerned with the format of the contents of the sub- - fields, it does carry type information (ad-type). - - - -Section 5.3.1. - 51 - Expires 11 January 1998 - - - - - - - - Version 5 - Specification Revision 6 - - - By using the authorization_data field, a principal - is able to issue a proxy that is valid for a - specific purpose. For example, a client wishing - to print a file can obtain a file server proxy to - be passed to the print server. By specifying the - name of the file in the authorization_data field, - the file server knows that the print server can - only use the client's rights when accessing the - particular file to be printed. - - A separate service providing providing authoriza- - tion or certifying group membership may be built - using the authorization-data field. In this case, - the entity granting authorization (not the author- - ized entity), obtains a ticket in its own name - (e.g. the ticket is issued in the name of a - privelege server), and this entity adds restric- - tions on its own authority and delegates the res- - tricted authority through a proxy to the client. - The client would then present this authorization - credential to the application server separately - from the authentication exchange. - - Similarly, if one specifies the authorization-data - field of a proxy and leaves the host addresses - blank, the resulting ticket and session key can be - treated as a capability. See [7] for some sug- - gested uses of this field. - - The authorization-data field is optional and does - not have to be included in a ticket. - - -5.3.2. Authenticators - - An authenticator is a record sent with a ticket to a -server to certify the client's knowledge of the encryption -key in the ticket, to help the server detect replays, and to -help choose a "true session key" to use with the particular -session. The encoding is encrypted in the ticket's session -key shared by the client and the server: - --- Unencrypted authenticator -Authenticator ::= [APPLICATION 2] SEQUENCE { - authenticator-vno[0] INTEGER, - crealm[1] Realm, - cname[2] PrincipalName, - cksum[3] Checksum OPTIONAL, - cusec[4] INTEGER, - ctime[5] KerberosTime, - subkey[6] EncryptionKey OPTIONAL, - seq-number[7] INTEGER OPTIONAL, - authorization-data[8] AuthorizationData OPTIONAL -} - - - -Section 5.3.2. - 52 - Expires 11 January 1998 - - - - - - - - Version 5 - Specification Revision 6 - - -authenticator-vno - This field specifies the version number for the - format of the authenticator. This document speci- - fies version 5. - - -crealm and cname - These fields are the same as those described for - the ticket in section 5.3.1. - - -cksum This field contains a checksum of the the applica- - tion data that accompanies the KRB_AP_REQ. - - -cusec This field contains the microsecond part of the - client's timestamp. Its value (before encryption) - ranges from 0 to 999999. It often appears along - with ctime. The two fields are used together to - specify a reasonably accurate timestamp. - - -ctime This field contains the current time on the - client's host. - - -subkey This field contains the client's choice for an - encryption key which is to be used to protect this - specific application session. Unless an applica- - tion specifies otherwise, if this field is left - out the session key from the ticket will be used. - -seq-numberThis optional field includes the initial sequence - number to be used by the KRB_PRIV or KRB_SAFE mes- - sages when sequence numbers are used to detect - replays (It may also be used by application - specific messages). When included in the authen- - ticator this field specifies the initial sequence - number for messages from the client to the server. - When included in the AP-REP message, the initial - sequence number is that for messages from the - server to the client. When used in KRB_PRIV or - KRB_SAFE messages, it is incremented by one after - each message is sent. - - For sequence numbers to adequately support the - detection of replays they should be non-repeating, - even across connection boundaries. The initial - sequence number should be random and uniformly - distributed across the full space of possible - sequence numbers, so that it cannot be guessed by - an attacker and so that it and the successive - sequence numbers do not repeat other sequences. - - - -Section 5.3.2. - 53 - Expires 11 January 1998 - - - - - - - - Version 5 - Specification Revision 6 - - -authorization-data - This field is the same as described for the ticket - in section 5.3.1. It is optional and will only - appear when additional restrictions are to be - placed on the use of a ticket, beyond those car- - ried in the ticket itself. - -5.4. Specifications for the AS and TGS exchanges - - This section specifies the format of the messages used -in the exchange between the client and the Kerberos server. -The format of possible error messages appears in section -5.9.1. - -5.4.1. KRB_KDC_REQ definition - - The KRB_KDC_REQ message has no type of its own. -Instead, its type is one of KRB_AS_REQ or KRB_TGS_REQ -depending on whether the request is for an initial ticket or -an additional ticket. In either case, the message is sent -from the client to the Authentication Server to request -credentials for a service. - - The message fields are: - -AS-REQ ::= [APPLICATION 10] KDC-REQ -TGS-REQ ::= [APPLICATION 12] KDC-REQ - -KDC-REQ ::= SEQUENCE { - pvno[1] INTEGER, - msg-type[2] INTEGER, - padata[3] SEQUENCE OF PA-DATA OPTIONAL, - req-body[4] KDC-REQ-BODY -} - -PA-DATA ::= SEQUENCE { - padata-type[1] INTEGER, - padata-value[2] OCTET STRING, - -- might be encoded AP-REQ -} - -KDC-REQ-BODY ::= SEQUENCE { - kdc-options[0] KDCOptions, - cname[1] PrincipalName OPTIONAL, - -- Used only in AS-REQ - realm[2] Realm, -- Server's realm - -- Also client's in AS-REQ - sname[3] PrincipalName OPTIONAL, - from[4] KerberosTime OPTIONAL, - till[5] KerberosTime OPTIONAL, - rtime[6] KerberosTime OPTIONAL, - nonce[7] INTEGER, - etype[8] SEQUENCE OF INTEGER, - -- EncryptionType, - -- in preference order - - -Section 5.4.1. - 54 - Expires 11 January 1998 - - - - - - - - Version 5 - Specification Revision 6 - - - addresses[9] HostAddresses OPTIONAL, - enc-authorization-data[10] EncryptedData OPTIONAL, - -- Encrypted AuthorizationData - -- encoding - additional-tickets[11] SEQUENCE OF Ticket OPTIONAL -} - -The fields in this message are: - - -pvno This field is included in each message, and speci- - fies the protocol version number. This document - specifies protocol version 5. - - -msg-type This field indicates the type of a protocol mes- - sage. It will almost always be the same as the - application identifier associated with a message. - It is included to make the identifier more readily - accessible to the application. For the KDC-REQ - message, this type will be KRB_AS_REQ or - KRB_TGS_REQ. - - -padata The padata (pre-authentication data) field con- - tains a sequence of authentication information - which may be needed before credentials can be - issued or decrypted. In the case of requests for - additional tickets (KRB_TGS_REQ), this field will - include an element with padata-type of PA-TGS-REQ - and data of an authentication header (ticket- - granting ticket and authenticator). The checksum - in the authenticator (which must be collision- - proof) is to be computed over the KDC-REQ-BODY - encoding. In most requests for initial authenti- - cation (KRB_AS_REQ) and most replies (KDC-REP), - the padata field will be left out. - - This field may also contain information needed by - certain extensions to the Kerberos protocol. For - example, it might be used to initially verify the - identity of a client before any response is - returned. This is accomplished with a padata - field with padata-type equal to PA-ENC-TIMESTAMP - and padata-value defined as follows: - -padata-type ::= PA-ENC-TIMESTAMP -padata-value ::= EncryptedData -- PA-ENC-TS-ENC - -PA-ENC-TS-ENC ::= SEQUENCE { - patimestamp[0] KerberosTime, -- client's time - pausec[1] INTEGER OPTIONAL -} - - with patimestamp containing the client's time and - - -Section 5.4.1. - 55 - Expires 11 January 1998 - - - - - - - - Version 5 - Specification Revision 6 - - - pausec containing the microseconds which may be - omitted if a client will not generate more than - one request per second. The ciphertext (padata- - value) consists of the PA-ENC-TS-ENC sequence, - encrypted using the client's secret key. - - The padata field can also contain information - needed to help the KDC or the client select the - key needed for generating or decrypting the - response. This form of the padata is useful for - supporting the use of certain token cards with - Kerberos. The details of such extensions are - specified in separate documents. See [11] for - additional uses of this field. - -padata-type - The padata-type element of the padata field indi- - cates the way that the padata-value element is to - be interpreted. Negative values of padata-type - are reserved for unregistered use; non-negative - values are used for a registered interpretation of - the element type. - - -req-body This field is a placeholder delimiting the extent - of the remaining fields. If a checksum is to be - calculated over the request, it is calculated over - an encoding of the KDC-REQ-BODY sequence which is - enclosed within the req-body field. - - -kdc-options - This field appears in the KRB_AS_REQ and - KRB_TGS_REQ requests to the KDC and indicates the - flags that the client wants set on the tickets as - well as other information that is to modify the - behavior of the KDC. Where appropriate, the name - of an option may be the same as the flag that is - set by that option. Although in most case, the - bit in the options field will be the same as that - in the flags field, this is not guaranteed, so it - is not acceptable to simply copy the options field - to the flags field. There are various checks that - must be made before honoring an option anyway. - - The kdc_options field is a bit-field, where the - selected options are indicated by the bit being - set (1), and the unselected options and reserved - fields being reset (0). The encoding of the bits - is specified in section 5.2. The options are - described in more detail above in section 2. The - meanings of the options are: - - - - -Section 5.4.1. - 56 - Expires 11 January 1998 - - - - - Version 5 - Specification Revision 6 - - - Bit(s) Name Description - 0 RESERVED - Reserved for future expansion of this - field. - - 1 FORWARDABLE - The FORWARDABLE option indicates that - the ticket to be issued is to have its - forwardable flag set. It may only be - set on the initial request, or in a sub- - sequent request if the ticket-granting - ticket on which it is based is also for- - wardable. - - 2 FORWARDED - The FORWARDED option is only specified - in a request to the ticket-granting - server and will only be honored if the - ticket-granting ticket in the request - has its FORWARDABLE bit set. This - option indicates that this is a request - for forwarding. The address(es) of the - host from which the resulting ticket is - to be valid are included in the - addresses field of the request. - - 3 PROXIABLE - The PROXIABLE option indicates that the - ticket to be issued is to have its prox- - iable flag set. It may only be set on - the initial request, or in a subsequent - request if the ticket-granting ticket on - which it is based is also proxiable. - - 4 PROXY - The PROXY option indicates that this is - a request for a proxy. This option will - only be honored if the ticket-granting - ticket in the request has its PROXIABLE - bit set. The address(es) of the host - from which the resulting ticket is to be - valid are included in the addresses - field of the request. - - 5 ALLOW-POSTDATE - The ALLOW-POSTDATE option indicates that - the ticket to be issued is to have its - MAY-POSTDATE flag set. It may only be - set on the initial request, or in a sub- - sequent request if the ticket-granting - ticket on which it is based also has its - MAY-POSTDATE flag set. - - - - - - - -Section 5.4.1. - 57 - Expires 11 January 1998 - - - - - - - - Version 5 - Specification Revision 6 - - - 6 POSTDATED - The POSTDATED option indicates that this - is a request for a postdated ticket. - This option will only be honored if the - ticket-granting ticket on which it is - based has its MAY-POSTDATE flag set. - The resulting ticket will also have its - INVALID flag set, and that flag may be - reset by a subsequent request to the KDC - after the starttime in the ticket has - been reached. - - 7 UNUSED - This option is presently unused. - - 8 RENEWABLE - The RENEWABLE option indicates that the - ticket to be issued is to have its - RENEWABLE flag set. It may only be set - on the initial request, or when the - ticket-granting ticket on which the - request is based is also renewable. If - this option is requested, then the rtime - field in the request contains the - desired absolute expiration time for the - ticket. - - 9-13 UNUSED - These options are presently unused. - - 14 REQUEST-ANONYMOUS - The REQUEST-ANONYMOUS option indicates - that the ticket to be issued is not to - identify the user to which it was - issued. Instead, the principal identif- - ier is to be generic, as specified by - the policy of the realm (e.g. usually - anonymous@realm). The purpose of the - ticket is only to securely distribute a - session key, and not to identify the - user. The ANONYMOUS flag on the ticket - to be returned should be set. If the - local realms policy does not permit - anonymous credentials, the request is to - be rejected. - - 15-25 RESERVED - Reserved for future use. - - 26 DISABLE-TRANSITED-CHECK - By default the KDC will check the - transited field of a ticket-granting- - ticket against the policy of the local - realm before it will issue derivative - tickets based on the ticket granting - ticket. If this flag is set in the - request, checking of the transited field - is disabled. Tickets issued without the - performance of this check will be noted - by the reset (0) value of the - TRANSITED-POLICY-CHECKED flag, - indicating to the application server - that the tranisted field must be checked - locally. KDC's are encouraged but not - required to honor the - DISABLE-TRANSITED-CHECK option. - - - -Section 5.4.1. - 58 - Expires 11 January 1998 - - - - - - - - Version 5 - Specification Revision 6 - - - 27 RENEWABLE-OK - The RENEWABLE-OK option indicates that a - renewable ticket will be acceptable if a - ticket with the requested life cannot - otherwise be provided. If a ticket with - the requested life cannot be provided, - then a renewable ticket may be issued - with a renew-till equal to the the - requested endtime. The value of the - renew-till field may still be limited by - local limits, or limits selected by the - individual principal or server. - - 28 ENC-TKT-IN-SKEY - This option is used only by the ticket- - granting service. The ENC-TKT-IN-SKEY - option indicates that the ticket for the - end server is to be encrypted in the - session key from the additional ticket- - granting ticket provided. - - 29 RESERVED - Reserved for future use. - - 30 RENEW - This option is used only by the ticket- - granting service. The RENEW option - indicates that the present request is - for a renewal. The ticket provided is - encrypted in the secret key for the - server on which it is valid. This - option will only be honored if the - ticket to be renewed has its RENEWABLE - flag set and if the time in its renew- - till field has not passed. The ticket - to be renewed is passed in the padata - field as part of the authentication - header. - - 31 VALIDATE - This option is used only by the ticket- - granting service. The VALIDATE option - indicates that the request is to vali- - date a postdated ticket. It will only - be honored if the ticket presented is - postdated, presently has its INVALID - flag set, and would be otherwise usable - at this time. A ticket cannot be vali- - dated before its starttime. The ticket - presented for validation is encrypted in - the key of the server for which it is - valid and is passed in the padata field - as part of the authentication header. - -cname and sname - These fields are the same as those described for - the ticket in section 5.3.1. sname may only be - - -Section 5.4.1. - 59 - Expires 11 January 1998 - - - - - - - - Version 5 - Specification Revision 6 - - - absent when the ENC-TKT-IN-SKEY option is speci- - fied. If absent, the name of the server is taken - from the name of the client in the ticket passed - as additional-tickets. - - -enc-authorization-data - The enc-authorization-data, if present (and it can - only be present in the TGS_REQ form), is an encod- - ing of the desired authorization-data encrypted - under the sub-session key if present in the - Authenticator, or alternatively from the session - key in the ticket-granting ticket, both from the - padata field in the KRB_AP_REQ. - - -realm This field specifies the realm part of the - server's principal identifier. In the AS - exchange, this is also the realm part of the - client's principal identifier. - - -from This field is included in the KRB_AS_REQ and - KRB_TGS_REQ ticket requests when the requested - ticket is to be postdated. It specifies the - desired start time for the requested ticket. - - - -till This field contains the expiration date requested - by the client in a ticket request. It is option - and if omitted the requested ticket is to have the - maximum endtime permitted according to KDC policy - for the parties to the authentication exchange as - limited by expiration date of the ticket granting - ticket or other preauthentication credentials. - - -rtime This field is the requested renew-till time sent - from a client to the KDC in a ticket request. It - is optional. - - -nonce This field is part of the KDC request and - response. It it intended to hold a random number - generated by the client. If the same number is - included in the encrypted response from the KDC, - it provides evidence that the response is fresh - and has not been replayed by an attacker. Nonces - must never be re-used. Ideally, it should be gen- - erated randomly, but if the correct time is known, - it may suffice[25]. -__________________________ -[25] Note, however, that if the time is used as the - -Section 5.4.1. - 60 - Expires 11 January 1998 - - - - - - - - Version 5 - Specification Revision 6 - - -etype This field specifies the desired encryption algo- - rithm to be used in the response. - - -addresses This field is included in the initial request for - tickets, and optionally included in requests for - additional tickets from the ticket-granting - server. It specifies the addresses from which the - requested ticket is to be valid. Normally it - includes the addresses for the client's host. If - a proxy is requested, this field will contain - other addresses. The contents of this field are - usually copied by the KDC into the caddr field of - the resulting ticket. - - -additional-tickets - Additional tickets may be optionally included in a - request to the ticket-granting server. If the - ENC-TKT-IN-SKEY option has been specified, then - the session key from the additional ticket will be - used in place of the server's key to encrypt the - new ticket. If more than one option which - requires additional tickets has been specified, - then the additional tickets are used in the order - specified by the ordering of the options bits (see - kdc-options, above). - - - The application code will be either ten (10) or twelve -(12) depending on whether the request is for an initial -ticket (AS-REQ) or for an additional ticket (TGS-REQ). - - The optional fields (addresses, authorization-data and -additional-tickets) are only included if necessary to per- -form the operation specified in the kdc-options field. - - It should be noted that in KRB_TGS_REQ, the protocol -version number appears twice and two different message types -appear: the KRB_TGS_REQ message contains these fields as -does the authentication header (KRB_AP_REQ) that is passed -in the padata field. - -5.4.2. KRB_KDC_REP definition - - The KRB_KDC_REP message format is used for the reply -from the KDC for either an initial (AS) request or a subse- -quent (TGS) request. There is no message type for -__________________________ -nonce, one must make sure that the workstation time is -monotonically increasing. If the time is ever reset -backwards, there is a small, but finite, probability -that a nonce will be reused. - - - -Section 5.4.2. - 61 - Expires 11 January 1998 - - - - - - - - Version 5 - Specification Revision 6 - - -KRB_KDC_REP. Instead, the type will be either KRB_AS_REP or -KRB_TGS_REP. The key used to encrypt the ciphertext part of -the reply depends on the message type. For KRB_AS_REP, the -ciphertext is encrypted in the client's secret key, and the -client's key version number is included in the key version -number for the encrypted data. For KRB_TGS_REP, the cipher- -text is encrypted in the sub-session key from the Authenti- -cator, or if absent, the session key from the ticket- -granting ticket used in the request. In that case, no ver- -sion number will be present in the EncryptedData sequence. - - The KRB_KDC_REP message contains the following fields: - -AS-REP ::= [APPLICATION 11] KDC-REP -TGS-REP ::= [APPLICATION 13] KDC-REP - -KDC-REP ::= SEQUENCE { - pvno[0] INTEGER, - msg-type[1] INTEGER, - padata[2] SEQUENCE OF PA-DATA OPTIONAL, - crealm[3] Realm, - cname[4] PrincipalName, - ticket[5] Ticket, - enc-part[6] EncryptedData -} - - -EncASRepPart ::= [APPLICATION 25[27]] EncKDCRepPart -EncTGSRepPart ::= [APPLICATION 26] EncKDCRepPart - - - -EncKDCRepPart ::= SEQUENCE { - key[0] EncryptionKey, - last-req[1] LastReq, - nonce[2] INTEGER, - key-expiration[3] KerberosTime OPTIONAL, - flags[4] TicketFlags, - authtime[5] KerberosTime, - starttime[6] KerberosTime OPTIONAL, - endtime[7] KerberosTime, - renew-till[8] KerberosTime OPTIONAL, - srealm[9] Realm, - sname[10] PrincipalName, - caddr[11] HostAddresses OPTIONAL -} - - -pvno and msg-type - These fields are described above in section 5.4.1. - msg-type is either KRB_AS_REP or KRB_TGS_REP. -__________________________ -[27] An application code in the encrypted part of a -message provides an additional check that the message -was decrypted properly. - - -Section 5.4.2. - 62 - Expires 11 January 1998 - - - - - - - - Version 5 - Specification Revision 6 - - -padata This field is described in detail in section - 5.4.1. One possible use for this field is to - encode an alternate "mix-in" string to be used - with a string-to-key algorithm (such as is - described in section 6.3.2). This ability is use- - ful to ease transitions if a realm name needs to - change (e.g. when a company is acquired); in such - a case all existing password-derived entries in - the KDC database would be flagged as needing a - special mix-in string until the next password - change. - - -crealm, cname, srealm and sname - These fields are the same as those described for - the ticket in section 5.3.1. - - -ticket The newly-issued ticket, from section 5.3.1. - - -enc-part This field is a place holder for the ciphertext - and related information that forms the encrypted - part of a message. The description of the - encrypted part of the message follows each appear- - ance of this field. The encrypted part is encoded - as described in section 6.1. - - -key This field is the same as described for the ticket - in section 5.3.1. - - -last-req This field is returned by the KDC and specifies - the time(s) of the last request by a principal. - Depending on what information is available, this - might be the last time that a request for a - ticket-granting ticket was made, or the last time - that a request based on a ticket-granting ticket - was successful. It also might cover all servers - for a realm, or just the particular server. Some - implementations may display this information to - the user to aid in discovering unauthorized use of - one's identity. It is similar in spirit to the - last login time displayed when logging into - timesharing systems. - - -nonce This field is described above in section 5.4.1. - - -key-expiration - The key-expiration field is part of the response - from the KDC and specifies the time that the - - -Section 5.4.2. - 63 - Expires 11 January 1998 - - - - - - - - Version 5 - Specification Revision 6 - - - client's secret key is due to expire. The expira- - tion might be the result of password aging or an - account expiration. This field will usually be - left out of the TGS reply since the response to - the TGS request is encrypted in a session key and - no client information need be retrieved from the - KDC database. It is up to the application client - (usually the login program) to take appropriate - action (such as notifying the user) if the expira- - tion time is imminent. - - -flags, authtime, starttime, endtime, renew-till and caddr - These fields are duplicates of those found in the - encrypted portion of the attached ticket (see sec- - tion 5.3.1), provided so the client may verify - they match the intended request and to assist in - proper ticket caching. If the message is of type - KRB_TGS_REP, the caddr field will only be filled - in if the request was for a proxy or forwarded - ticket, or if the user is substituting a subset of - the addresses from the ticket granting ticket. If - the client-requested addresses are not present or - not used, then the addresses contained in the - ticket will be the same as those included in the - ticket-granting ticket. - - -5.5. Client/Server (CS) message specifications - - This section specifies the format of the messages used -for the authentication of the client to the application -server. - -5.5.1. KRB_AP_REQ definition - - The KRB_AP_REQ message contains the Kerberos protocol -version number, the message type KRB_AP_REQ, an options -field to indicate any options in use, and the ticket and -authenticator themselves. The KRB_AP_REQ message is often -referred to as the "authentication header". - -AP-REQ ::= [APPLICATION 14] SEQUENCE { - pvno[0] INTEGER, - msg-type[1] INTEGER, - ap-options[2] APOptions, - ticket[3] Ticket, - authenticator[4] EncryptedData -} - -APOptions ::= BIT STRING { - reserved(0), - use-session-key(1), - mutual-required(2) - - -Section 5.5.1. - 64 - Expires 11 January 1998 - - - - - - - - Version 5 - Specification Revision 6 - - -} - - -pvno and msg-type - These fields are described above in section 5.4.1. - msg-type is KRB_AP_REQ. - - -ap-optionsThis field appears in the application request - (KRB_AP_REQ) and affects the way the request is - processed. It is a bit-field, where the selected - options are indicated by the bit being set (1), - and the unselected options and reserved fields - being reset (0). The encoding of the bits is - specified in section 5.2. The meanings of the - options are: - - Bit(s) Name Description - - 0 RESERVED - Reserved for future expansion of this - field. - - 1 USE-SESSION-KEY - The USE-SESSION-KEY option indicates - that the ticket the client is presenting - to a server is encrypted in the session - key from the server's ticket-granting - ticket. When this option is not speci- - fied, the ticket is encrypted in the - server's secret key. - - 2 MUTUAL-REQUIRED - The MUTUAL-REQUIRED option tells the - server that the client requires mutual - authentication, and that it must respond - with a KRB_AP_REP message. - - 3-31 RESERVED - Reserved for future use. - - - -ticket This field is a ticket authenticating the client - to the server. - - -authenticator - This contains the authenticator, which includes - the client's choice of a subkey. Its encoding is - described in section 5.3.2. - -5.5.2. KRB_AP_REP definition - - The KRB_AP_REP message contains the Kerberos protocol -version number, the message type, and an encrypted time- -stamp. The message is sent in in response to an application -request (KRB_AP_REQ) where the mutual authentication option - - -Section 5.5.2. - 65 - Expires 11 January 1998 - - - - - - - - Version 5 - Specification Revision 6 - - -has been selected in the ap-options field. - -AP-REP ::= [APPLICATION 15] SEQUENCE { - pvno[0] INTEGER, - msg-type[1] INTEGER, - enc-part[2] EncryptedData -} - -EncAPRepPart ::= [APPLICATION 27[29]] SEQUENCE { - ctime[0] KerberosTime, - cusec[1] INTEGER, - subkey[2] EncryptionKey OPTIONAL, - seq-number[3] INTEGER OPTIONAL -} - -The encoded EncAPRepPart is encrypted in the shared session -key of the ticket. The optional subkey field can be used in -an application-arranged negotiation to choose a per associa- -tion session key. - - -pvno and msg-type - These fields are described above in section 5.4.1. - msg-type is KRB_AP_REP. - - -enc-part This field is described above in section 5.4.2. - - -ctime This field contains the current time on the - client's host. - - -cusec This field contains the microsecond part of the - client's timestamp. - - -subkey This field contains an encryption key which is to - be used to protect this specific application ses- - sion. See section 3.2.6 for specifics on how this - field is used to negotiate a key. Unless an - application specifies otherwise, if this field is - left out, the sub-session key from the authentica- - tor, or if also left out, the session key from the - ticket will be used. - - - -__________________________ -[29] An application code in the encrypted part of a -message provides an additional check that the message -was decrypted properly. - - - -Section 5.5.2. - 66 - Expires 11 January 1998 - - - - - - - - Version 5 - Specification Revision 6 - - -5.5.3. Error message reply - - If an error occurs while processing the application -request, the KRB_ERROR message will be sent in response. -See section 5.9.1 for the format of the error message. The -cname and crealm fields may be left out if the server cannot -determine their appropriate values from the corresponding -KRB_AP_REQ message. If the authenticator was decipherable, -the ctime and cusec fields will contain the values from it. - -5.6. KRB_SAFE message specification - - This section specifies the format of a message that can -be used by either side (client or server) of an application -to send a tamper-proof message to its peer. It presumes -that a session key has previously been exchanged (for exam- -ple, by using the KRB_AP_REQ/KRB_AP_REP messages). - -5.6.1. KRB_SAFE definition - - The KRB_SAFE message contains user data along with a -collision-proof checksum keyed with the last encryption key -negotiated via subkeys, or the session key if no negotiation -has occured. The message fields are: - -KRB-SAFE ::= [APPLICATION 20] SEQUENCE { - pvno[0] INTEGER, - msg-type[1] INTEGER, - safe-body[2] KRB-SAFE-BODY, - cksum[3] Checksum -} - -KRB-SAFE-BODY ::= SEQUENCE { - user-data[0] OCTET STRING, - timestamp[1] KerberosTime OPTIONAL, - usec[2] INTEGER OPTIONAL, - seq-number[3] INTEGER OPTIONAL, - s-address[4] HostAddress OPTIONAL, - r-address[5] HostAddress OPTIONAL -} - - - - -pvno and msg-type - These fields are described above in section 5.4.1. - msg-type is KRB_SAFE. - - -safe-body This field is a placeholder for the body of the - KRB-SAFE message. It is to be encoded separately - and then have the checksum computed over it, for - use in the cksum field. - - - -Section 5.6.1. - 67 - Expires 11 January 1998 - - - - - - - - Version 5 - Specification Revision 6 - - -cksum This field contains the checksum of the applica- - tion data. Checksum details are described in sec- - tion 6.4. The checksum is computed over the - encoding of the KRB-SAFE-BODY sequence. - - -user-data This field is part of the KRB_SAFE and KRB_PRIV - messages and contain the application specific data - that is being passed from the sender to the reci- - pient. - - -timestamp This field is part of the KRB_SAFE and KRB_PRIV - messages. Its contents are the current time as - known by the sender of the message. By checking - the timestamp, the recipient of the message is - able to make sure that it was recently generated, - and is not a replay. - - -usec This field is part of the KRB_SAFE and KRB_PRIV - headers. It contains the microsecond part of the - timestamp. - - -seq-number - This field is described above in section 5.3.2. - - -s-address This field specifies the address in use by the - sender of the message. - - -r-address This field specifies the address in use by the - recipient of the message. It may be omitted for - some uses (such as broadcast protocols), but the - recipient may arbitrarily reject such messages. - This field along with s-address can be used to - help detect messages which have been incorrectly - or maliciously delivered to the wrong recipient. - -5.7. KRB_PRIV message specification - - This section specifies the format of a message that can -be used by either side (client or server) of an application -to securely and privately send a message to its peer. It -presumes that a session key has previously been exchanged -(for example, by using the KRB_AP_REQ/KRB_AP_REP messages). - -5.7.1. KRB_PRIV definition - - The KRB_PRIV message contains user data encrypted in -the Session Key. The message fields are: - -__________________________ -[31] An application code in the encrypted part of a - - - - - - - Version 5 - Specification Revision 6 - - - -KRB-PRIV ::= [APPLICATION 21] SEQUENCE { - pvno[0] INTEGER, - msg-type[1] INTEGER, - enc-part[3] EncryptedData -} - -EncKrbPrivPart ::= [APPLICATION 28[31]] SEQUENCE { - user-data[0] OCTET STRING, - timestamp[1] KerberosTime OPTIONAL, - usec[2] INTEGER OPTIONAL, - seq-number[3] INTEGER OPTIONAL, - s-address[4] HostAddress OPTIONAL, -- sender's addr - r-address[5] HostAddress OPTIONAL -- recip's addr -} - - - -pvno and msg-type - These fields are described above in section 5.4.1. - msg-type is KRB_PRIV. - - -enc-part This field holds an encoding of the EncKrbPrivPart - sequence encrypted under the session key[32]. - This encrypted encoding is used for the enc-part - field of the KRB-PRIV message. See section 6 for - the format of the ciphertext. - - -user-data, timestamp, usec, s-address and r-address - These fields are described above in section 5.6.1. - - -seq-number - This field is described above in section 5.3.2. - -5.8. KRB_CRED message specification - - This section specifies the format of a message that can -be used to send Kerberos credentials from one principal to -__________________________ -message provides an additional check that the message -was decrypted properly. -[32] If supported by the encryption method in use, an -initialization vector may be passed to the encryption -procedure, in order to achieve proper cipher chaining. -The initialization vector might come from the last -block of the ciphertext from the previous KRB_PRIV mes- -sage, but it is the application's choice whether or not -to use such an initialization vector. If left out, the -default initialization vector for the encryption algo- -rithm will be used. - - -Section 5.8. - 69 - Expires 11 January 1998 - - - - - - - - Version 5 - Specification Revision 6 - - -another. It is presented here to encourage a common mechan- -ism to be used by applications when forwarding tickets or -providing proxies to subordinate servers. It presumes that -a session key has already been exchanged perhaps by using -the KRB_AP_REQ/KRB_AP_REP messages. - -5.8.1. KRB_CRED definition - - The KRB_CRED message contains a sequence of tickets to -be sent and information needed to use the tickets, including -the session key from each. The information needed to use -the tickets is encrypted under an encryption key previously -exchanged or transferred alongside the KRB_CRED message. -The message fields are: - -KRB-CRED ::= [APPLICATION 22] SEQUENCE { - pvno[0] INTEGER, - msg-type[1] INTEGER, -- KRB_CRED - tickets[2] SEQUENCE OF Ticket, - enc-part[3] EncryptedData -} - -EncKrbCredPart ::= [APPLICATION 29] SEQUENCE { - ticket-info[0] SEQUENCE OF KrbCredInfo, - nonce[1] INTEGER OPTIONAL, - timestamp[2] KerberosTime OPTIONAL, - usec[3] INTEGER OPTIONAL, - s-address[4] HostAddress OPTIONAL, - r-address[5] HostAddress OPTIONAL -} - -KrbCredInfo ::= SEQUENCE { - key[0] EncryptionKey, - prealm[1] Realm OPTIONAL, - pname[2] PrincipalName OPTIONAL, - flags[3] TicketFlags OPTIONAL, - authtime[4] KerberosTime OPTIONAL, - starttime[5] KerberosTime OPTIONAL, - endtime[6] KerberosTime OPTIONAL - renew-till[7] KerberosTime OPTIONAL, - srealm[8] Realm OPTIONAL, - sname[9] PrincipalName OPTIONAL, - caddr[10] HostAddresses OPTIONAL -} - - - - - -pvno and msg-type - These fields are described above in section 5.4.1. - msg-type is KRB_CRED. - - - - -Section 5.8.1. - 70 - Expires 11 January 1998 - - - - - - - - Version 5 - Specification Revision 6 - - -tickets - These are the tickets obtained from the KDC - specifically for use by the intended recipient. - Successive tickets are paired with the correspond- - ing KrbCredInfo sequence from the enc-part of the - KRB-CRED message. - - -enc-part This field holds an encoding of the EncKrbCredPart - sequence encrypted under the session key shared - between the sender and the intended recipient. - This encrypted encoding is used for the enc-part - field of the KRB-CRED message. See section 6 for - the format of the ciphertext. - - -nonce If practical, an application may require the - inclusion of a nonce generated by the recipient of - the message. If the same value is included as the - nonce in the message, it provides evidence that - the message is fresh and has not been replayed by - an attacker. A nonce must never be re-used; it - should be generated randomly by the recipient of - the message and provided to the sender of the mes- - sage in an application specific manner. - - -timestamp and usec - - These fields specify the time that the KRB-CRED - message was generated. The time is used to pro- - vide assurance that the message is fresh. - - -s-address and r-address - These fields are described above in section 5.6.1. - They are used optionally to provide additional - assurance of the integrity of the KRB-CRED mes- - sage. - - -key This field exists in the corresponding ticket - passed by the KRB-CRED message and is used to pass - the session key from the sender to the intended - recipient. The field's encoding is described in - section 6.2. - - The following fields are optional. If present, they -can be associated with the credentials in the remote ticket -file. If left out, then it is assumed that the recipient of -the credentials already knows their value. - - -prealm and pname - - -Section 5.8.1. - 71 - Expires 11 January 1998 - - - - - - - - Version 5 - Specification Revision 6 - - - The name and realm of the delegated principal - identity. - - -flags, authtime, starttime, endtime, renew-till, srealm, - sname, and caddr - These fields contain the values of the correspond- - ing fields from the ticket found in the ticket - field. Descriptions of the fields are identical - to the descriptions in the KDC-REP message. - -5.9. Error message specification - - This section specifies the format for the KRB_ERROR -message. The fields included in the message are intended to -return as much information as possible about an error. It -is not expected that all the information required by the -fields will be available for all types of errors. If the -appropriate information is not available when the message is -composed, the corresponding field will be left out of the -message. - - Note that since the KRB_ERROR message is not protected -by any encryption, it is quite possible for an intruder to -synthesize or modify such a message. In particular, this -means that the client should not use any fields in this mes- -sage for security-critical purposes, such as setting a sys- -tem clock or generating a fresh authenticator. The message -can be useful, however, for advising a user on the reason -for some failure. - -5.9.1. KRB_ERROR definition - - The KRB_ERROR message consists of the following fields: - -KRB-ERROR ::= [APPLICATION 30] SEQUENCE { - pvno[0] INTEGER, - msg-type[1] INTEGER, - ctime[2] KerberosTime OPTIONAL, - cusec[3] INTEGER OPTIONAL, - stime[4] KerberosTime, - susec[5] INTEGER, - error-code[6] INTEGER, - crealm[7] Realm OPTIONAL, - cname[8] PrincipalName OPTIONAL, - realm[9] Realm, -- Correct realm - sname[10] PrincipalName, -- Correct name - e-text[11] GeneralString OPTIONAL, - e-data[12] OCTET STRING OPTIONAL, - e-cksum[13] Checksum OPTIONAL -} - - - - - -Section 5.9.1. - 72 - Expires 11 January 1998 - - - - - - - - Version 5 - Specification Revision 6 - - -pvno and msg-type - These fields are described above in section 5.4.1. - msg-type is KRB_ERROR. - - -ctime This field is described above in section 5.4.1. - - - -cusec This field is described above in section 5.5.2. - - -stime This field contains the current time on the - server. It is of type KerberosTime. - - -susec This field contains the microsecond part of the - server's timestamp. Its value ranges from 0 to - 999999. It appears along with stime. The two - fields are used in conjunction to specify a rea- - sonably accurate timestamp. - - -error-codeThis field contains the error code returned by - Kerberos or the server when a request fails. To - interpret the value of this field see the list of - error codes in section 8. Implementations are - encouraged to provide for national language sup- - port in the display of error messages. - - -crealm, cname, srealm and sname - These fields are described above in section 5.3.1. - - -e-text This field contains additional text to help - explain the error code associated with the failed - request (for example, it might include a principal - name which was unknown). - - -e-data This field contains additional data about the - error for use by the application to help it - recover from or handle the error. If the error- - code is KDC_ERR_PREAUTH_REQUIRED, then the e-data - field will contain an encoding of a sequence of - padata fields, each corresponding to an acceptable - pre-authentication method and optionally contain- - ing data for the method: - - -e-cksum This field contains an optional checksum for the - KRB-ERROR message. The checksum is calculated - over the Kerberos ASN.1 encoding of the KRB-ERROR - - -Section 5.9.1. - 73 - Expires 11 January 1998 - - - - - - - - Version 5 - Specification Revision 6 - - - message with the checksum absent. The checksum is - then added to the KRB-ERROR structure and the mes- - sage is re-encoded. The Checksum should be calcu- - lated using the session key from the ticket grant- - ing ticket or service ticket, where available. If - the error is in response to a TGS or AP request, - the checksum should be calculated uing the the - session key from the client's ticket. If the - error is in response to an AS request, then the - checksum should be calulated using the client's - secret key ONLY if there has been suitable preau- - thentication to prove knowledge of the secret key - by the client[33]. If a checksum can not be com- - puted because the key to be used is not available, - no checksum will be included. - - METHOD-DATA ::= SEQUENCE of PA-DATA - - - If the error-code is KRB_AP_ERR_METHOD, then the - e-data field will contain an encoding of the fol- - lowing sequence: - - METHOD-DATA ::= SEQUENCE { - method-type[0] INTEGER, - method-data[1] OCTET STRING OPTIONAL - } - - method-type will indicate the required alternate - method; method-data will contain any required - additional information. - - - -6. Encryption and Checksum Specifications - -The Kerberos protocols described in this document are -designed to use stream encryption ciphers, which can be -simulated using commonly available block encryption ciphers, -such as the Data Encryption Standard, [12] in conjunction -with block chaining and checksum methods [13]. Encryption -is used to prove the identities of the network entities par- -ticipating in message exchanges. The Key Distribution -Center for each realm is trusted by all principals -registered in that realm to store a secret key in confi- -dence. Proof of knowledge of this secret key is used to -verify the authenticity of a principal. - - The KDC uses the principal's secret key (in the AS -__________________________ -[33] This prevents an attacker who generates an in- -correct AS request from obtaining verifiable plaintext -for use in an off-line password guessing attack. - - -Section 6. - 74 - Expires 11 January 1998 - - - - - - - - Version 5 - Specification Revision 6 - - -exchange) or a shared session key (in the TGS exchange) to -encrypt responses to ticket requests; the ability to obtain -the secret key or session key implies the knowledge of the -appropriate keys and the identity of the KDC. The ability -of a principal to decrypt the KDC response and present a -Ticket and a properly formed Authenticator (generated with -the session key from the KDC response) to a service verifies -the identity of the principal; likewise the ability of the -service to extract the session key from the Ticket and prove -its knowledge thereof in a response verifies the identity of -the service. - - The Kerberos protocols generally assume that the -encryption used is secure from cryptanalysis; however, in -some cases, the order of fields in the encrypted portions of -messages are arranged to minimize the effects of poorly -chosen keys. It is still important to choose good keys. If -keys are derived from user-typed passwords, those passwords -need to be well chosen to make brute force attacks more dif- -ficult. Poorly chosen keys still make easy targets for -intruders. - - The following sections specify the encryption and -checksum mechanisms currently defined for Kerberos. The -encodings, chaining, and padding requirements for each are -described. For encryption methods, it is often desirable to -place random information (often referred to as a confounder) -at the start of the message. The requirements for a con- -founder are specified with each encryption mechanism. - - Some encryption systems use a block-chaining method to -improve the the security characteristics of the ciphertext. -However, these chaining methods often don't provide an -integrity check upon decryption. Such systems (such as DES -in CBC mode) must be augmented with a checksum of the plain- -text which can be verified at decryption and used to detect -any tampering or damage. Such checksums should be good at -detecting burst errors in the input. If any damage is -detected, the decryption routine is expected to return an -error indicating the failure of an integrity check. Each -encryption type is expected to provide and verify an -appropriate checksum. The specification of each encryption -method sets out its checksum requirements. - - Finally, where a key is to be derived from a user's -password, an algorithm for converting the password to a key -of the appropriate type is included. It is desirable for -the string to key function to be one-way, and for the map- -ping to be different in different realms. This is important -because users who are registered in more than one realm will -often use the same password in each, and it is desirable -that an attacker compromising the Kerberos server in one -realm not obtain or derive the user's key in another. - - - -Section 6. - 75 - Expires 11 January 1998 - - - - - - - - Version 5 - Specification Revision 6 - - - For an discussion of the integrity characteristics of -the candidate encryption and checksum methods considered for -Kerberos, the the reader is referred to [14]. - -6.1. Encryption Specifications - - The following ASN.1 definition describes all encrypted -messages. The enc-part field which appears in the unen- -crypted part of messages in section 5 is a sequence consist- -ing of an encryption type, an optional key version number, -and the ciphertext. - - -EncryptedData ::= SEQUENCE { - etype[0] INTEGER, -- EncryptionType - kvno[1] INTEGER OPTIONAL, - cipher[2] OCTET STRING -- ciphertext -} - - -etype This field identifies which encryption algorithm - was used to encipher the cipher. Detailed specif- - ications for selected encryption types appear - later in this section. - - -kvno This field contains the version number of the key - under which data is encrypted. It is only present - in messages encrypted under long lasting keys, - such as principals' secret keys. - - -cipher This field contains the enciphered text, encoded - as an OCTET STRING. - - - The cipher field is generated by applying the specified -encryption algorithm to data composed of the message and -algorithm-specific inputs. Encryption mechanisms defined -for use with Kerberos must take sufficient measures to -guarantee the integrity of the plaintext, and we recommend -they also take measures to protect against precomputed dic- -tionary attacks. If the encryption algorithm is not itself -capable of doing so, the protections can often be enhanced -by adding a checksum and a confounder. - - The suggested format for the data to be encrypted -includes a confounder, a checksum, the encoded plaintext, -and any necessary padding. The msg-seq field contains the -part of the protocol message described in section 5 which is -to be encrypted. The confounder, checksum, and padding are -all untagged and untyped, and their length is exactly suffi- -cient to hold the appropriate item. The type and length is -implicit and specified by the particular encryption type - - -Section 6.1. - 76 - Expires 11 January 1998 - - - - - - - - Version 5 - Specification Revision 6 - - -being used (etype). The format for the data to be encrypted -is described in the following diagram: - - +-----------+----------+-------------+-----+ - |confounder | check | msg-seq | pad | - +-----------+----------+-------------+-----+ - -The format cannot be described in ASN.1, but for those who -prefer an ASN.1-like notation: - -CipherText ::= ENCRYPTED SEQUENCE { - confounder[0] UNTAGGED[35] OCTET STRING(conf_length) OPTIONAL, - check[1] UNTAGGED OCTET STRING(checksum_length) OPTIONAL, - msg-seq[2] MsgSequence, - pad UNTAGGED OCTET STRING(pad_length) OPTIONAL -} - - - One generates a random confounder of the appropriate -length, placing it in confounder; zeroes out check; calcu- -lates the appropriate checksum over confounder, check, and -msg-seq, placing the result in check; adds the necessary -padding; then encrypts using the specified encryption type -and the appropriate key. - - Unless otherwise specified, a definition of an encryp- -tion algorithm that specifies a checksum, a length for the -confounder field, or an octet boundary for padding uses this -ciphertext format[36]. Those fields which are not specified -will be omitted. - - In the interest of allowing all implementations using a -__________________________ -[35] In the above specification, UNTAGGED OCTET -STRING(length) is the notation for an octet string with -its tag and length removed. It is not a valid ASN.1 -type. The tag bits and length must be removed from the -confounder since the purpose of the confounder is so -that the message starts with random data, but the tag -and its length are fixed. For other fields, the length -and tag would be redundant if they were included be- -cause they are specified by the encryption type. -[36] The ordering of the fields in the CipherText is -important. Additionally, messages encoded in this for- -mat must include a length as part of the msg-seq field. -This allows the recipient to verify that the message -has not been truncated. Without a length, an attacker -could use a chosen plaintext attack to generate a mes- -sage which could be truncated, while leaving the check- -sum intact. Note that if the msg-seq is an encoding of -an ASN.1 SEQUENCE or OCTET STRING, then the length is -part of that encoding. - - - -Section 6.1. - 77 - Expires 11 January 1998 - - - - - - - - Version 5 - Specification Revision 6 - - -particular encryption type to communicate with all others -using that type, the specification of an encryption type -defines any checksum that is needed as part of the encryp- -tion process. If an alternative checksum is to be used, a -new encryption type must be defined. - - Some cryptosystems require additional information -beyond the key and the data to be encrypted. For example, -DES, when used in cipher-block-chaining mode, requires an -initialization vector. If required, the description for -each encryption type must specify the source of such addi- -tional information. - -6.2. Encryption Keys - - The sequence below shows the encoding of an encryption -key: - - EncryptionKey ::= SEQUENCE { - keytype[0] INTEGER, - keyvalue[1] OCTET STRING - } - - -keytype This field specifies the type of encryption key - that follows in the keyvalue field. It will - almost always correspond to the encryption algo- - rithm used to generate the EncryptedData, though - more than one algorithm may use the same type of - key (the mapping is many to one). This might hap- - pen, for example, if the encryption algorithm uses - an alternate checksum algorithm for an integrity - check, or a different chaining mechanism. - - -keyvalue This field contains the key itself, encoded as an - octet string. - - All negative values for the encryption key type are -reserved for local use. All non-negative values are -reserved for officially assigned type fields and interpreta- -tions. - -6.3. Encryption Systems - -6.3.1. The NULL Encryption System (null) - - If no encryption is in use, the encryption system is -said to be the NULL encryption system. In the NULL encryp- -tion system there is no checksum, confounder or padding. -The ciphertext is simply the plaintext. The NULL Key is -used by the null encryption system and is zero octets in -length, with keytype zero (0). - - - -Section 6.3.1. - 78 - Expires 11 January 1998 - - - - - - - - Version 5 - Specification Revision 6 - - -6.3.2. DES in CBC mode with a CRC-32 checksum (des-cbc-crc) - - The des-cbc-crc encryption mode encrypts information -under the Data Encryption Standard [12] using the cipher -block chaining mode [13]. A CRC-32 checksum (described in -ISO 3309 [15]) is applied to the confounder and message -sequence (msg-seq) and placed in the cksum field. DES -blocks are 8 bytes. As a result, the data to be encrypted -(the concatenation of confounder, checksum, and message) -must be padded to an 8 byte boundary before encryption. The -details of the encryption of this data are identical to -those for the des-cbc-md5 encryption mode. - - Note that, since the CRC-32 checksum is not collision- -proof, an attacker could use a probabilistic chosen- -plaintext attack to generate a valid message even if a con- -founder is used [14]. The use of collision-proof checksums -is recommended for environments where such attacks represent -a significant threat. The use of the CRC-32 as the checksum -for ticket or authenticator is no longer mandated as an -interoperability requirement for Kerberos Version 5 Specifi- -cation 1 (See section 9.1 for specific details). - - -6.3.3. DES in CBC mode with an MD4 checksum (des-cbc-md4) - - The des-cbc-md4 encryption mode encrypts information -under the Data Encryption Standard [12] using the cipher -block chaining mode [13]. An MD4 checksum (described in -[16]) is applied to the confounder and message sequence -(msg-seq) and placed in the cksum field. DES blocks are 8 -bytes. As a result, the data to be encrypted (the concate- -nation of confounder, checksum, and message) must be padded -to an 8 byte boundary before encryption. The details of the -encryption of this data are identical to those for the des- -cbc-md5 encryption mode. - - -6.3.4. DES in CBC mode with an MD5 checksum (des-cbc-md5) - - The des-cbc-md5 encryption mode encrypts information -under the Data Encryption Standard [12] using the cipher -block chaining mode [13]. An MD5 checksum (described in -[17].) is applied to the confounder and message sequence -(msg-seq) and placed in the cksum field. DES blocks are 8 -bytes. As a result, the data to be encrypted (the concate- -nation of confounder, checksum, and message) must be padded -to an 8 byte boundary before encryption. - - Plaintext and DES ciphtertext are encoded as 8-octet -blocks which are concatenated to make the 64-bit inputs for -the DES algorithms. The first octet supplies the 8 most -significant bits (with the octet's MSbit used as the DES -input block's MSbit, etc.), the second octet the next 8 - - -Section 6.3.4. - 79 - Expires 11 January 1998 - - - - - - - - Version 5 - Specification Revision 6 - - -bits, ..., and the eighth octet supplies the 8 least signi- -ficant bits. - - Encryption under DES using cipher block chaining -requires an additional input in the form of an initializa- -tion vector. Unless otherwise specified, zero should be -used as the initialization vector. Kerberos' use of DES -requires an 8-octet confounder. - - The DES specifications identify some "weak" and "semi- -weak" keys; those keys shall not be used for encrypting mes- -sages for use in Kerberos. Additionally, because of the way -that keys are derived for the encryption of checksums, keys -shall not be used that yield "weak" or "semi-weak" keys when -eXclusive-ORed with the constant F0F0F0F0F0F0F0F0. - - A DES key is 8 octets of data, with keytype one (1). -This consists of 56 bits of key, and 8 parity bits (one per -octet). The key is encoded as a series of 8 octets written -in MSB-first order. The bits within the key are also -encoded in MSB order. For example, if the encryption key is -(B1,B2,...,B7,P1,B8,...,B14,P2,B15,...,B49,P7,B50,...,B56,P8) -where B1,B2,...,B56 are the key bits in MSB order, and -P1,P2,...,P8 are the parity bits, the first octet of the key -would be B1,B2,...,B7,P1 (with B1 as the MSbit). [See the -FIPS 81 introduction for reference.] - - To generate a DES key from a text string (password), -the text string normally must have the realm and each com- -ponent of the principal's name appended[37], then padded -with ASCII nulls to an 8 byte boundary. This string is then -fan-folded and eXclusive-ORed with itself to form an 8 byte -DES key. The parity is corrected on the key, and it is used -to generate a DES CBC checksum on the initial string (with -the realm and name appended). Next, parity is corrected on -the CBC checksum. If the result matches a "weak" or "semi- -weak" key as described in the DES specification, it is -eXclusive-ORed with the constant 00000000000000F0. Finally, -the result is returned as the key. Pseudocode follows: - - string_to_key(string,realm,name) { - odd = 1; - s = string + realm; - for(each component in name) { - s = s + component; - } - tempkey = NULL; - pad(s); /* with nulls to 8 byte boundary */ - for(8byteblock in s) { -__________________________ -[37] In some cases, it may be necessary to use a dif- -ferent "mix-in" string for compatibility reasons; see -the discussion of padata in section 5.4.2. - - -Section 6.3.4. - 80 - Expires 11 January 1998 - - - - - - - - Version 5 - Specification Revision 6 - - - if(odd == 0) { - odd = 1; - reverse(8byteblock) - } - else odd = 0; - tempkey = tempkey XOR 8byteblock; - } - fixparity(tempkey); - key = DES-CBC-check(s,tempkey); - fixparity(key); - if(is_weak_key_key(key)) - key = key XOR 0xF0; - return(key); - } - -6.3.5. Triple DES EDE in outer CBC mode with an SHA1 check- -sum (des3-cbc-sha1) - - The des3-cbc-sha1 encryption encodes information using -three Data Encryption Standard transformations with three -DES keys. The first key is used to perform a DES ECB -encryption on an eight-octet data block using the first DES -key, followed by a DES ECB decryption of the result using -the second DES key, and a DES ECB encryption of the result -using the third DES key. Because DES blocks are 8 bytes, -the data to be encrypted (the concatenation of confounder, -checksum, and message) must first be padded to an 8 byte -boundary before encryption. To support the outer CBC mode, -the input is padded an eight-octet boundary. The first 8 -octets of the data to be encrypted (the confounder) is -exclusive-ored with an initialization vector of zero and -then ECB encrypted using triple DES as described above. -Subsequent blocks of 8 octets are exclusive-ored with the -ciphertext produced by the encryption on the previous block -before ECB encryption. - - An HMAC-SHA1 checksum (described in [18].) is applied -to the confounder and message sequence (msg-seq) and placed -in the cksum field. - - Plaintext are encoded as 8-octet blocks which are con- -catenated to make the 64-bit inputs for the DES algorithms. -The first octet supplies the 8 most significant bits (with -the octet's MSbit used as the DES input block's MSbit, -etc.), the second octet the next 8 bits, ..., and the eighth -octet supplies the 8 least significant bits. - - Encryption under Triple DES using cipher block chaining -requires an additional input in the form of an initializa- -tion vector. Unless otherwise specified, zero should be -used as the initialization vector. Kerberos' use of DES -requires an 8-octet confounder. - - The DES specifications identify some "weak" and "semi- - - -Section 6.3.5. - 81 - Expires 11 January 1998 - - - - - - - - Version 5 - Specification Revision 6 - - -weak" keys; those keys shall not be used for encrypting mes- -sages for use in Kerberos. Additionally, because of the way -that keys are derived for the encryption of checksums, keys -shall not be used that yield "weak" or "semi-weak" keys when -eXclusive-ORed with the constant F0F0F0F0F0F0F0F0. - - A Triple DES key is 24 octets of data, with keytype -seven (7). This consists of 168 bits of key, and 24 parity -bits (one per octet). The key is encoded as a series of 24 -octets written in MSB-first order, with the first 8 octets -treated as the first DES key, the second 8 octets as the -second key, and the third 8 octets the third DES key. The -bits within each key are also encoded in MSB order. For -example, if the encryption key is -(B1,B2,...,B7,P1,B8,...,B14,P2,B15,...,B49,P7,B50,...,B56,P8) -where B1,B2,...,B56 are the key bits in MSB order, and -P1,P2,...,P8 are the parity bits, the first octet of the key -would be B1,B2,...,B7,P1 (with B1 as the MSbit). [See the -FIPS 81 introduction for reference.] - - To generate a DES key from a text string (password), -the text string normally must have the realm and each com- -ponent of the principal's name appended[38], - - The input string (with any salt data appended to it) is -n-folded into a 24 octet (192 bit) string. To n-fold a -number X, replicate the input value to a length that is the -least common multiple of n and the length of X. Before each -repetition, the input X is rotated to the right by 13 bit -positions. The successive n-bit chunks are added together -using 1's-complement addition (addition with end-around -carry) to yield a n-bit result. (This transformation was -proposed by Richard Basch) - - Each successive set of 8 octets is taken as a DES key, -and its parity is adjusted in the same manner as previously -described. If any of the three sets of 8 octets match a -"weak" or "semi-weak" key as described in the DES specifica- -tion, that chunk is eXclusive-ORed with the constant -00000000000000F0. The resulting DES keys are then used in -sequence to perform a Triple-DES CBC encryption of the n- -folded input string (appended with any salt data), using a -zero initial vector. Parity, weak, and semi-weak keys are -once again corrected and the result is returned as the 24 -octet key. - - Pseudocode follows: - - string_to_key(string,realm,name) { -__________________________ -[38] In some cases, it may be necessary to use a dif- -ferent "mix-in" string for compatibility reasons; see -the discussion of padata in section 5.4.2. - - -Section 6.3.5. - 82 - Expires 11 January 1998 - - - - - - - - Version 5 - Specification Revision 6 - - - s = string + realm; - for(each component in name) { - s = s + component; - } - tkey[24] = fold(s); - fixparity(tkey); - if(isweak(tkey[0-7])) tkey[0-7] = tkey[0-7] XOR 0xF0; - if(isweak(tkey[8-15])) tkey[8-15] = tkey[8-15] XOR 0xF0; - if(is_weak(tkey[16-23])) tkey[16-23] = tkey[16-23] XOR 0xF0; - key[24] = 3DES-CBC(data=fold(s),key=tkey,iv=0); - fixparity(key); - if(is_weak(key[0-7])) key[0-7] = key[0-7] XOR 0xF0; - if(is_weak(key[8-15])) key[8-15] = key[8-15] XOR 0xF0; - if(is_weak(key[16-23])) key[16-23] = key[16-23] XOR 0xF0; - return(key); - } - -6.4. Checksums - - The following is the ASN.1 definition used for a check- -sum: - - Checksum ::= SEQUENCE { - cksumtype[0] INTEGER, - checksum[1] OCTET STRING - } - - -cksumtype This field indicates the algorithm used to gen- - erate the accompanying checksum. - -checksum This field contains the checksum itself, encoded - as an octet string. - - Detailed specification of selected checksum types -appear later in this section. Negative values for the -checksum type are reserved for local use. All non-negative -values are reserved for officially assigned type fields and -interpretations. - - Checksums used by Kerberos can be classified by two -properties: whether they are collision-proof, and whether -they are keyed. It is infeasible to find two plaintexts -which generate the same checksum value for a collision-proof -checksum. A key is required to perturb or initialize the -algorithm in a keyed checksum. To prevent message-stream -modification by an active attacker, unkeyed checksums should -only be used when the checksum and message will be subse- -quently encrypted (e.g. the checksums defined as part of the -encryption algorithms covered earlier in this section). - - Collision-proof checksums can be made tamper-proof if -the checksum value is encrypted before inclusion in a mes- -sage. In such cases, the composition of the checksum and - - -Section 6.4. - 83 - Expires 11 January 1998 - - - - - - - - Version 5 - Specification Revision 6 - - -the encryption algorithm must be considered a separate -checksum algorithm (e.g. RSA-MD5 encrypted using DES is a -new checksum algorithm of type RSA-MD5-DES). For most keyed -checksums, as well as for the encrypted forms of unkeyed -collision-proof checksums, Kerberos prepends a confounder -before the checksum is calculated. - -6.4.1. The CRC-32 Checksum (crc32) - - The CRC-32 checksum calculates a checksum based on a -cyclic redundancy check as described in ISO 3309 [15]. The -resulting checksum is four (4) octets in length. The CRC-32 -is neither keyed nor collision-proof. The use of this -checksum is not recommended. An attacker using a proba- -bilistic chosen-plaintext attack as described in [14] might -be able to generate an alternative message that satisfies -the checksum. The use of collision-proof checksums is -recommended for environments where such attacks represent a -significant threat. - -6.4.2. The RSA MD4 Checksum (rsa-md4) - - The RSA-MD4 checksum calculates a checksum using the -RSA MD4 algorithm [16]. The algorithm takes as input an -input message of arbitrary length and produces as output a -128-bit (16 octet) checksum. RSA-MD4 is believed to be -collision-proof. - -6.4.3. RSA MD4 Cryptographic Checksum Using DES (rsa-md4- -des) - - The RSA-MD4-DES checksum calculates a keyed collision- -proof checksum by prepending an 8 octet confounder before -the text, applying the RSA MD4 checksum algorithm, and -encrypting the confounder and the checksum using DES in -cipher-block-chaining (CBC) mode using a variant of the key, -where the variant is computed by eXclusive-ORing the key -with the constant F0F0F0F0F0F0F0F0[39]. The initialization -vector should be zero. The resulting checksum is 24 octets -long (8 octets of which are redundant). This checksum is -tamper-proof and believed to be collision-proof. - - The DES specifications identify some "weak keys" and -__________________________ -[39] A variant of the key is used to limit the use of a -key to a particular function, separating the functions -of generating a checksum from other encryption per- -formed using the session key. The constant -F0F0F0F0F0F0F0F0 was chosen because it maintains key -parity. The properties of DES precluded the use of the -complement. The same constant is used for similar pur- -pose in the Message Integrity Check in the Privacy -Enhanced Mail standard. - - -Section 6.4.3. - 84 - Expires 11 January 1998 - - - - - - - - Version 5 - Specification Revision 6 - - -"semi-weak keys"; those keys shall not be used for generat- -ing RSA-MD4 checksums for use in Kerberos. - - The format for the checksum is described in the follow- -ing diagram: - -+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ -| des-cbc(confounder + rsa-md4(confounder+msg),key=var(key),iv=0) | -+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ - -The format cannot be described in ASN.1, but for those who -prefer an ASN.1-like notation: - -rsa-md4-des-checksum ::= ENCRYPTED UNTAGGED SEQUENCE { - confounder[0] UNTAGGED OCTET STRING(8), - check[1] UNTAGGED OCTET STRING(16) -} - - - -6.4.4. The RSA MD5 Checksum (rsa-md5) - - The RSA-MD5 checksum calculates a checksum using the -RSA MD5 algorithm. [17]. The algorithm takes as input an -input message of arbitrary length and produces as output a -128-bit (16 octet) checksum. RSA-MD5 is believed to be -collision-proof. - -6.4.5. RSA MD5 Cryptographic Checksum Using DES (rsa-md5- -des) - - The RSA-MD5-DES checksum calculates a keyed collision- -proof checksum by prepending an 8 octet confounder before -the text, applying the RSA MD5 checksum algorithm, and -encrypting the confounder and the checksum using DES in -cipher-block-chaining (CBC) mode using a variant of the key, -where the variant is computed by eXclusive-ORing the key -with the constant F0F0F0F0F0F0F0F0. The initialization vec- -tor should be zero. The resulting checksum is 24 octets -long (8 octets of which are redundant). This checksum is -tamper-proof and believed to be collision-proof. - - The DES specifications identify some "weak keys" and -"semi-weak keys"; those keys shall not be used for encrypt- -ing RSA-MD5 checksums for use in Kerberos. - - The format for the checksum is described in the follow- -ing diagram: - -+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ -| des-cbc(confounder + rsa-md5(confounder+msg),key=var(key),iv=0) | -+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ - -The format cannot be described in ASN.1, but for those who - - -Section 6.4.5. - 85 - Expires 11 January 1998 - - - - - - - - Version 5 - Specification Revision 6 - - -prefer an ASN.1-like notation: - -rsa-md5-des-checksum ::= ENCRYPTED UNTAGGED SEQUENCE { - confounder[0] UNTAGGED OCTET STRING(8), - check[1] UNTAGGED OCTET STRING(16) -} - - -6.4.6. DES cipher-block chained checksum (des-mac) - - The DES-MAC checksum is computed by prepending an 8 -octet confounder to the plaintext, performing a DES CBC-mode -encryption on the result using the key and an initialization -vector of zero, taking the last block of the ciphertext, -prepending the same confounder and encrypting the pair using -DES in cipher-block-chaining (CBC) mode using a a variant of -the key, where the variant is computed by eXclusive-ORing -the key with the constant F0F0F0F0F0F0F0F0. The initializa- -tion vector should be zero. The resulting checksum is 128 -bits (16 octets) long, 64 bits of which are redundant. This -checksum is tamper-proof and collision-proof. - - The format for the checksum is described in the follow- -ing diagram: - -+--+--+--+--+--+--+--+--+-----+-----+-----+-----+-----+-----+-----+-----+ -| des-cbc(confounder + des-mac(conf+msg,iv=0,key),key=var(key),iv=0) | -+--+--+--+--+--+--+--+--+-----+-----+-----+-----+-----+-----+-----+-----+ - -The format cannot be described in ASN.1, but for those who -prefer an ASN.1-like notation: - -des-mac-checksum ::= ENCRYPTED UNTAGGED SEQUENCE { - confounder[0] UNTAGGED OCTET STRING(8), - check[1] UNTAGGED OCTET STRING(8) -} - - - The DES specifications identify some "weak" and "semi- -weak" keys; those keys shall not be used for generating -DES-MAC checksums for use in Kerberos, nor shall a key be -used whose variant is "weak" or "semi-weak". - -6.4.7. RSA MD4 Cryptographic Checksum Using DES alternative -(rsa-md4-des-k) - - The RSA-MD4-DES-K checksum calculates a keyed -collision-proof checksum by applying the RSA MD4 checksum -algorithm and encrypting the results using DES in cipher- -block-chaining (CBC) mode using a DES key as both key and -initialization vector. The resulting checksum is 16 octets -long. This checksum is tamper-proof and believed to be -collision-proof. Note that this checksum type is the old -method for encoding the RSA-MD4-DES checksum and it is no - - -Section 6.4.7. - 86 - Expires 11 January 1998 - - - - - - - - Version 5 - Specification Revision 6 - - -longer recommended. - -6.4.8. DES cipher-block chained checksum alternative (des- -mac-k) - - The DES-MAC-K checksum is computed by performing a DES -CBC-mode encryption of the plaintext, and using the last -block of the ciphertext as the checksum value. It is keyed -with an encryption key and an initialization vector; any -uses which do not specify an additional initialization vec- -tor will use the key as both key and initialization vector. -The resulting checksum is 64 bits (8 octets) long. This -checksum is tamper-proof and collision-proof. Note that -this checksum type is the old method for encoding the DES- -MAC checksum and it is no longer recommended. - - The DES specifications identify some "weak keys" and -"semi-weak keys"; those keys shall not be used for generat- -ing DES-MAC checksums for use in Kerberos. - -7. Naming Constraints - - -7.1. Realm Names - - Although realm names are encoded as GeneralStrings and -although a realm can technically select any name it chooses, -interoperability across realm boundaries requires agreement -on how realm names are to be assigned, and what information -they imply. - - To enforce these conventions, each realm must conform -to the conventions itself, and it must require that any -realms with which inter-realm keys are shared also conform -to the conventions and require the same from its neighbors. - - Kerberos realm names are case sensitive. Realm names -that differ only in the case of the characters are not -equivalent. There are presently four styles of realm names: -domain, X500, other, and reserved. Examples of each style -follow: - - domain: ATHENA.MIT.EDU (example) - X500: C=US/O=OSF (example) - other: NAMETYPE:rest/of.name=without-restrictions (example) - reserved: reserved, but will not conflict with above - - -Domain names must look like domain names: they consist of -components separated by periods (.) and they contain neither -colons (:) nor slashes (/). Domain names must be converted -to upper case when used as realm names. - - X.500 names contain an equal (=) and cannot contain a - - -Section 7.1. - 87 - Expires 11 January 1998 - - - - - - - - Version 5 - Specification Revision 6 - - -colon (:) before the equal. The realm names for X.500 names -will be string representations of the names with components -separated by slashes. Leading and trailing slashes will not -be included. - - Names that fall into the other category must begin with -a prefix that contains no equal (=) or period (.) and the -prefix must be followed by a colon (:) and the rest of the -name. All prefixes must be assigned before they may be -used. Presently none are assigned. - - The reserved category includes strings which do not -fall into the first three categories. All names in this -category are reserved. It is unlikely that names will be -assigned to this category unless there is a very strong -argument for not using the "other" category. - - These rules guarantee that there will be no conflicts -between the various name styles. The following additional -constraints apply to the assignment of realm names in the -domain and X.500 categories: the name of a realm for the -domain or X.500 formats must either be used by the organiza- -tion owning (to whom it was assigned) an Internet domain -name or X.500 name, or in the case that no such names are -registered, authority to use a realm name may be derived -from the authority of the parent realm. For example, if -there is no domain name for E40.MIT.EDU, then the adminis- -trator of the MIT.EDU realm can authorize the creation of a -realm with that name. - - This is acceptable because the organization to which -the parent is assigned is presumably the organization -authorized to assign names to its children in the X.500 and -domain name systems as well. If the parent assigns a realm -name without also registering it in the domain name or X.500 -hierarchy, it is the parent's responsibility to make sure -that there will not in the future exists a name identical to -the realm name of the child unless it is assigned to the -same entity as the realm name. - - -7.2. Principal Names - - As was the case for realm names, conventions are needed -to ensure that all agree on what information is implied by a -principal name. The name-type field that is part of the -principal name indicates the kind of information implied by -the name. The name-type should be treated as a hint. -Ignoring the name type, no two names can be the same (i.e. -at least one of the components, or the realm, must be dif- -ferent). This constraint may be eliminated in the future. -The following name types are defined: - - name-type value meaning - - -Section 7.2. - 88 - Expires 11 January 1998 - - - - - - - - Version 5 - Specification Revision 6 - - - NT-UNKNOWN 0 Name type not known - NT-PRINCIPAL 1 General principal name (e.g. username, or DCE principal) - NT-SRV-INST 2 Service and other unique instance (krbtgt) - NT-SRV-HST 3 Service with host name as instance (telnet, rcommands) - NT-SRV-XHST 4 Service with slash-separated host name components - NT-UID 5 Unique ID - - -When a name implies no information other than its uniqueness -at a particular time the name type PRINCIPAL should be used. -The principal name type should be used for users, and it -might also be used for a unique server. If the name is a -unique machine generated ID that is guaranteed never to be -reassigned then the name type of UID should be used (note -that it is generally a bad idea to reassign names of any -type since stale entries might remain in access control -lists). - - If the first component of a name identifies a service -and the remaining components identify an instance of the -service in a server specified manner, then the name type of -SRV-INST should be used. An example of this name type is -the Kerberos ticket-granting service whose name has a first -component of krbtgt and a second component identifying the -realm for which the ticket is valid. - - If instance is a single component following the service -name and the instance identifies the host on which the -server is running, then the name type SRV-HST should be -used. This type is typically used for Internet services -such as telnet and the Berkeley R commands. If the separate -components of the host name appear as successive components -following the name of the service, then the name type SRV- -XHST should be used. This type might be used to identify -servers on hosts with X.500 names where the slash (/) might -otherwise be ambiguous. - - A name type of UNKNOWN should be used when the form of -the name is not known. When comparing names, a name of type -UNKNOWN will match principals authenticated with names of -any type. A principal authenticated with a name of type -UNKNOWN, however, will only match other names of type UNK- -NOWN. - - Names of any type with an initial component of "krbtgt" -are reserved for the Kerberos ticket granting service. See -section 8.2.3 for the form of such names. - -7.2.1. Name of server principals - - The principal identifier for a server on a host will -generally be composed of two parts: (1) the realm of the KDC -with which the server is registered, and (2) a two-component - - -Section 7.2.1. - 89 - Expires 11 January 1998 - - - - - - - - Version 5 - Specification Revision 6 - - -name of type NT-SRV-HST if the host name is an Internet -domain name or a multi-component name of type NT-SRV-XHST if -the name of the host is of a form such as X.500 that allows -slash (/) separators. The first component of the two- or -multi-component name will identify the service and the -latter components will identify the host. Where the name of -the host is not case sensitive (for example, with Internet -domain names) the name of the host must be lower case. If -specified by the application protocol for services such as -telnet and the Berkeley R commands which run with system -privileges, the first component may be the string "host" -instead of a service specific identifier. When a host has -an official name and one or more aliases, the official name -of the host must be used when constructing the name of the -server principal. - -8. Constants and other defined values - - -8.1. Host address types - - All negative values for the host address type are -reserved for local use. All non-negative values are -reserved for officially assigned type fields and interpreta- -tions. - - The values of the types for the following addresses are -chosen to match the defined address family constants in the -Berkeley Standard Distributions of Unix. They can be found -in with symbolic names AF_xxx (where xxx is -an abbreviation of the address family name). - - -Internet addresses - - Internet addresses are 32-bit (4-octet) quantities, -encoded in MSB order. The type of internet addresses is two -(2). - -CHAOSnet addresses - - CHAOSnet addresses are 16-bit (2-octet) quantities, -encoded in MSB order. The type of CHAOSnet addresses is -five (5). - -ISO addresses - - ISO addresses are variable-length. The type of ISO -addresses is seven (7). - -Xerox Network Services (XNS) addresses - - XNS addresses are 48-bit (6-octet) quantities, encoded -in MSB order. The type of XNS addresses is six (6). - - -Section 8.1. - 90 - Expires 11 January 1998 - - - - - - - - Version 5 - Specification Revision 6 - - -AppleTalk Datagram Delivery Protocol (DDP) addresses - - AppleTalk DDP addresses consist of an 8-bit node number -and a 16-bit network number. The first octet of the address -is the node number; the remaining two octets encode the net- -work number in MSB order. The type of AppleTalk DDP -addresses is sixteen (16). - -DECnet Phase IV addresses - - DECnet Phase IV addresses are 16-bit addresses, encoded -in LSB order. The type of DECnet Phase IV addresses is -twelve (12). - -8.2. KDC messages - -8.2.1. IP transport - - When contacting a Kerberos server (KDC) for a -KRB_KDC_REQ request using UDP IP transport, the client shall -send a UDP datagram containing only an encoding of the -request to port 88 (decimal) at the KDC's IP address; the -KDC will respond with a reply datagram containing only an -encoding of the reply message (either a KRB_ERROR or a -KRB_KDC_REP) to the sending port at the sender's IP address. - - Kerberos servers supporting IP transport must accept -UDP requests on port 88 (decimal). Servers may also accept -TCP requests on port 88 (decimal). When the KRB_KDC_REQ -message is sent to the KDC by TCP, a new connection will be -established for each authentication exchange and the -KRB_KDC_REP or KRB_ERROR message will be returned to the -client on the TCP stream that was established for the -request. The connection will be broken after the reply has -been received (or upon time-out). Care must be taken in -managing TCP/IP connections with the KDC to prevent denial -of service attacks based on the number of TCP/IP connections -with the KDC that remain open. - -8.2.2. OSI transport - - During authentication of an OSI client to an OSI -server, the mutual authentication of an OSI server to an OSI -client, the transfer of credentials from an OSI client to an -OSI server, or during exchange of private or integrity -checked messages, Kerberos protocol messages may be treated -as opaque objects and the type of the authentication mechan- -ism will be: - -OBJECT IDENTIFIER ::= {iso (1), org(3), dod(6),internet(1), security(5), - kerberosv5(2)} - -Depending on the situation, the opaque object will be an -authentication header (KRB_AP_REQ), an authentication reply -(KRB_AP_REP), a safe message (KRB_SAFE), a private message - - -Section 8.2.2. - 91 - Expires 11 January 1998 - - - - - - - - Version 5 - Specification Revision 6 - - -(KRB_PRIV), or a credentials message (KRB_CRED). The opaque -data contains an application code as specified in the ASN.1 -description for each message. The application code may be -used by Kerberos to determine the message type. - -8.2.3. Name of the TGS - - The principal identifier of the ticket-granting service -shall be composed of three parts: (1) the realm of the KDC -issuing the TGS ticket (2) a two-part name of type NT-SRV- -INST, with the first part "krbtgt" and the second part the -name of the realm which will accept the ticket-granting -ticket. For example, a ticket-granting ticket issued by the -ATHENA.MIT.EDU realm to be used to get tickets from the -ATHENA.MIT.EDU KDC has a principal identifier of -"ATHENA.MIT.EDU" (realm), ("krbtgt", "ATHENA.MIT.EDU") -(name). A ticket-granting ticket issued by the -ATHENA.MIT.EDU realm to be used to get tickets from the -MIT.EDU realm has a principal identifier of "ATHENA.MIT.EDU" -(realm), ("krbtgt", "MIT.EDU") (name). - - -8.3. Protocol constants and associated values - -The following tables list constants used in the protocol and defines their -meanings. - -Encryption type etype value block size minimum pad size confounder size -NULL 0 1 0 0 -des-cbc-crc 1 8 4 8 -des-cbc-md4 2 8 0 8 -des-cbc-md5 3 8 0 8 - 4 -des3-cbc-md5 5 8 0 8 - 6 -des3-cbc-sha1 7 8 0 8 -sign-dsa-generate 8 (pkinit) -encrypt-rsa-priv 9 (pkinit) -encrypt-rsa-pub 10 (pkinit) -ENCTYPE_PK_CROSS 48 (reserved for pkcross) - 0x8003 - -Checksum type sumtype value checksum size -CRC32 1 4 -rsa-md4 2 16 -rsa-md4-des 3 24 -des-mac 4 16 -des-mac-k 5 8 -rsa-md4-des-k 6 16 -rsa-md5 7 16 -rsa-md5-des 8 24 -rsa-md5-des3 9 24 -hmac-sha1-des3 10 20 (I had this as 10, is it 12) - - -Section 8.3. - 92 - Expires 11 January 1998 - - - - - - - - Version 5 - Specification Revision 6 - - -padata type padata-type value - -PA-TGS-REQ 1 -PA-ENC-TIMESTAMP 2 -PA-PW-SALT 3 - 4 -PA-ENC-UNIX-TIME 5 -PA-SANDIA-SECUREID 6 -PA-SESAME 7 -PA-OSF-DCE 8 -PA-CYBERSAFE-SECUREID 9 -PA-AFS3-SALT 10 -PA-ETYPE-INFO 11 -SAM-CHALLENGE 12 (sam/otp) -SAM-RESPONSE 13 (sam/otp) -PA-PK-AS-REQ 14 (pkinit) -PA-PK-AS-REP 15 (pkinit) -PA-PK-AS-SIGN 16 (pkinit) -PA-PK-KEY-REQ 17 (pkinit) -PA-PK-KEY-REP 18 (pkinit) - -authorization data type ad-type value -reserved values 0-63 -OSF-DCE 64 -SESAME 65 - -alternate authentication type method-type value -reserved values 0-63 -ATT-CHALLENGE-RESPONSE 64 - -transited encoding type tr-type value -DOMAIN-X500-COMPRESS 1 -reserved values all others - - - -Label Value Meaning or MIT code - -pvno 5 current Kerberos protocol version number - -message types - -KRB_AS_REQ 10 Request for initial authentication -KRB_AS_REP 11 Response to KRB_AS_REQ request -KRB_TGS_REQ 12 Request for authentication based on TGT -KRB_TGS_REP 13 Response to KRB_TGS_REQ request -KRB_AP_REQ 14 application request to server -KRB_AP_REP 15 Response to KRB_AP_REQ_MUTUAL -KRB_SAFE 20 Safe (checksummed) application message -KRB_PRIV 21 Private (encrypted) application message -KRB_CRED 22 Private (encrypted) message to forward credentials -KRB_ERROR 30 Error response - - -Section 8.3. - 93 - Expires 11 January 1998 - - - - - - - - Version 5 - Specification Revision 6 - - -name types - -KRB_NT_UNKNOWN 0 Name type not known -KRB_NT_PRINCIPAL 1 Just the name of the principal as in DCE, or for users -KRB_NT_SRV_INST 2 Service and other unique instance (krbtgt) -KRB_NT_SRV_HST 3 Service with host name as instance (telnet, rcommands) -KRB_NT_SRV_XHST 4 Service with host as remaining components -KRB_NT_UID 5 Unique ID - -error codes - -KDC_ERR_NONE 0 No error -KDC_ERR_NAME_EXP 1 Client's entry in database has expired -KDC_ERR_SERVICE_EXP 2 Server's entry in database has expired -KDC_ERR_BAD_PVNO 3 Requested protocol version number not supported -KDC_ERR_C_OLD_MAST_KVNO 4 Client's key encrypted in old master key -KDC_ERR_S_OLD_MAST_KVNO 5 Server's key encrypted in old master key -KDC_ERR_C_PRINCIPAL_UNKNOWN 6 Client not found in Kerberos database -KDC_ERR_S_PRINCIPAL_UNKNOWN 7 Server not found in Kerberos database -KDC_ERR_PRINCIPAL_NOT_UNIQUE 8 Multiple principal entries in database -KDC_ERR_NULL_KEY 9 The client or server has a null key -KDC_ERR_CANNOT_POSTDATE 10 Ticket not eligible for postdating -KDC_ERR_NEVER_VALID 11 Requested start time is later than end time -KDC_ERR_POLICY 12 KDC policy rejects request -KDC_ERR_BADOPTION 13 KDC cannot accommodate requested option -KDC_ERR_ETYPE_NOSUPP 14 KDC has no support for encryption type -KDC_ERR_SUMTYPE_NOSUPP 15 KDC has no support for checksum type -KDC_ERR_PADATA_TYPE_NOSUPP 16 KDC has no support for padata type -KDC_ERR_TRTYPE_NOSUPP 17 KDC has no support for transited type -KDC_ERR_CLIENT_REVOKED 18 Clients credentials have been revoked -KDC_ERR_SERVICE_REVOKED 19 Credentials for server have been revoked -KDC_ERR_TGT_REVOKED 20 TGT has been revoked -KDC_ERR_CLIENT_NOTYET 21 Client not yet valid - try again later -KDC_ERR_SERVICE_NOTYET 22 Server not yet valid - try again later -KDC_ERR_KEY_EXPIRED 23 Password has expired - change password to reset -KDC_ERR_PREAUTH_FAILED 24 Pre-authentication information was invalid -KDC_ERR_PREAUTH_REQUIRED 25 Additional pre-authenticationrequired- -KDC_ERR_SERVER_NOMATCH 26 Requested server and ticket don't match -KDC_ERR_MUST_USE_USER2USER 27 Server principal valid for user2user only -KDC_ERR_PATH_NOT_ACCPETED 28 KDC Policy rejects transited path -KRB_AP_ERR_BAD_INTEGRITY 31 Integrity check on decrypted field failed -KRB_AP_ERR_TKT_EXPIRED 32 Ticket expired -KRB_AP_ERR_TKT_NYV 33 Ticket not yet valid -KRB_AP_ERR_REPEAT 34 Request is a replay -KRB_AP_ERR_NOT_US 35 The ticket isn't for us -KRB_AP_ERR_BADMATCH 36 Ticket and authenticator don't match -KRB_AP_ERR_SKEW 37 Clock skew too great -KRB_AP_ERR_BADADDR 38 Incorrect net address -KRB_AP_ERR_BADVERSION 39 Protocol version mismatch -KRB_AP_ERR_MSG_TYPE 40 Invalid msg type -KRB_AP_ERR_MODIFIED 41 Message stream modified -KRB_AP_ERR_BADORDER 42 Message out of order -KRB_AP_ERR_BADKEYVER 44 Specified version of key is not available -KRB_AP_ERR_NOKEY 45 Service key not available -KRB_AP_ERR_MUT_FAIL 46 Mutual authentication failed -KRB_AP_ERR_BADDIRECTION 47 Incorrect message direction -KRB_AP_ERR_METHOD 48 Alternative authentication method required -KRB_AP_ERR_BADSEQ 49 Incorrect sequence number in message - - - -Section 8.3. - 94 - Expires 11 January 1998 - - - - - - - - Version 5 - Specification Revision 6 - - -KRB_AP_ERR_INAPP_CKSUM 50 Inappropriate type of checksum in message -KRB_ERR_GENERIC 60 Generic error (description in e-text) -KRB_ERR_FIELD_TOOLONG 61 Field is too long for this implementation -KDC_ERROR_CLIENT_NOT_TRUSTED 62 (pkinit) -KDC_ERROR_KDC_NOT_TRUSTED 63 (pkinit) -KDC_ERROR_INVALID_SIG 64 (pkinit) -KDC_ERR_KEY_TOO_WEAK 65 (pkinit) - - -9. Interoperability requirements - - Version 5 of the Kerberos protocol supports a myriad of -options. Among these are multiple encryption and checksum -types, alternative encoding schemes for the transited field, -optional mechanisms for pre-authentication, the handling of -tickets with no addresses, options for mutual authentica- -tion, user to user authentication, support for proxies, for- -warding, postdating, and renewing tickets, the format of -realm names, and the handling of authorization data. - - In order to ensure the interoperability of realms, it -is necessary to define a minimal configuration which must be -supported by all implementations. This minimal configura- -tion is subject to change as technology does. For example, -if at some later date it is discovered that one of the -required encryption or checksum algorithms is not secure, it -will be replaced. - -9.1. Specification 1 - - This section defines the first specification of these -options. Implementations which are configured in this way -can be said to support Kerberos Version 5 Specification 1 -(5.1). - -Encryption and checksum methods - -The following encryption and checksum mechanisms must be -supported. Implementations may support other mechanisms as -well, but the additional mechanisms may only be used when -communicating with principals known to also support them: -This list is to be determined. -Encryption: DES-CBC-MD5 -Checksums: CRC-32, DES-MAC, DES-MAC-K, and DES-MD5 - - -__________________________ -- This error carries additional information in the e- -data field. The contents of the e-data field for this -message is described in section 5.9.1. - - - -Section 9.1. - 95 - Expires 11 January 1998 - - - - - - - - Version 5 - Specification Revision 6 - - -Realm Names - -All implementations must understand hierarchical realms in -both the Internet Domain and the X.500 style. When a ticket -granting ticket for an unknown realm is requested, the KDC -must be able to determine the names of the intermediate -realms between the KDCs realm and the requested realm. - -Transited field encoding - -DOMAIN-X500-COMPRESS (described in section 3.3.3.2) must be -supported. Alternative encodings may be supported, but they -may be used only when that encoding is supported by ALL -intermediate realms. - -Pre-authentication methods - -The TGS-REQ method must be supported. The TGS-REQ method is -not used on the initial request. The PA-ENC-TIMESTAMP -method must be supported by clients but whether it is -enabled by default may be determined on a realm by realm -basis. If not used in the initial request and the error -KDC_ERR_PREAUTH_REQUIRED is returned specifying PA-ENC- -TIMESTAMP as an acceptable method, the client should retry -the initial request using the PA-ENC-TIMESTAMP pre- -authentication method. Servers need not support the PA- -ENC-TIMESTAMP method, but if not supported the server should -ignore the presence of PA-ENC-TIMESTAMP pre-authentication -in a request. - -Mutual authentication - -Mutual authentication (via the KRB_AP_REP message) must be -supported. - - -Ticket addresses and flags - -All KDC's must pass on tickets that carry no addresses (i.e. -if a TGT contains no addresses, the KDC will return deriva- -tive tickets), but each realm may set its own policy for -issuing such tickets, and each application server will set -its own policy with respect to accepting them. - - Proxies and forwarded tickets must be supported. Indi- -vidual realms and application servers can set their own pol- -icy on when such tickets will be accepted. - - All implementations must recognize renewable and post- -dated tickets, but need not actually implement them. If -these options are not supported, the starttime and endtime -in the ticket shall specify a ticket's entire useful life. -When a postdated ticket is decoded by a server, all imple- -mentations shall make the presence of the postdated flag - - -Section 9.1. - 96 - Expires 11 January 1998 - - - - - - - - Version 5 - Specification Revision 6 - - -visible to the calling server. - -User-to-user authentication - -Support for user to user authentication (via the ENC-TKT- -IN-SKEY KDC option) must be provided by implementations, but -individual realms may decide as a matter of policy to reject -such requests on a per-principal or realm-wide basis. - -Authorization data - -Implementations must pass all authorization data subfields -from ticket-granting tickets to any derivative tickets -unless directed to suppress a subfield as part of the defin- -ition of that registered subfield type (it is never -incorrect to pass on a subfield, and no registered subfield -types presently specify suppression at the KDC). - - Implementations must make the contents of any authori- -zation data subfields available to the server when a ticket -is used. Implementations are not required to allow clients -to specify the contents of the authorization data fields. - -9.2. Recommended KDC values - -Following is a list of recommended values for a KDC imple- -mentation, based on the list of suggested configuration con- -stants (see section 4.4). - -minimum lifetime 5 minutes - -maximum renewable lifetime1 week - -maximum ticket lifetime1 day - -empty addresses only when suitable restrictions appear - in authorization data - -proxiable, etc. Allowed. - - - - - - - - - - - - - - - - - -Section 9.2. - 97 - Expires 11 January 1998 - - - - - - - - Version 5 - Specification Revision 6 - - -10. REFERENCES - - - -1. B. Clifford Neuman and Theodore Y. Ts'o, "An Authenti- - cation Service for Computer Networks," IEEE Communica- - tions Magazine, Vol. 32(9), pp. 33-38 (September 1994). - -2. S. P. Miller, B. C. Neuman, J. I. Schiller, and J. H. - Saltzer, Section E.2.1: Kerberos Authentication and - Authorization System, M.I.T. Project Athena, Cambridge, - Massachusetts (December 21, 1987). - -3. J. G. Steiner, B. C. Neuman, and J. I. Schiller, "Ker- - beros: An Authentication Service for Open Network Sys- - tems," pp. 191-202 in Usenix Conference Proceedings, - Dallas, Texas (February, 1988). - -4. Roger M. Needham and Michael D. Schroeder, "Using - Encryption for Authentication in Large Networks of Com- - puters," Communications of the ACM, Vol. 21(12), - pp. 993-999 (December, 1978). - -5. Dorothy E. Denning and Giovanni Maria Sacco, "Time- - stamps in Key Distribution Protocols," Communications - of the ACM, Vol. 24(8), pp. 533-536 (August 1981). - -6. John T. Kohl, B. Clifford Neuman, and Theodore Y. Ts'o, - "The Evolution of the Kerberos Authentication Service," - in an IEEE Computer Society Text soon to be published - (June 1992). - -7. B. Clifford Neuman, "Proxy-Based Authorization and - Accounting for Distributed Systems," in Proceedings of - the 13th International Conference on Distributed Com- - puting Systems, Pittsburgh, PA (May, 1993). - -8. Don Davis and Ralph Swick, "Workstation Services and - Kerberos Authentication at Project Athena," Technical - Memorandum TM-424, MIT Laboratory for Computer Science - (February 1990). - -9. P. J. Levine, M. R. Gretzinger, J. M. Diaz, W. E. Som- - merfeld, and K. Raeburn, Section E.1: Service Manage- - ment System, M.I.T. Project Athena, Cambridge, Mas- - sachusetts (1987). - -10. CCITT, Recommendation X.509: The Directory Authentica- - tion Framework, December 1988. - -11. J. Pato, Using Pre-Authentication to Avoid Password - Guessing Attacks, Open Software Foundation DCE Request - for Comments 26 (December 1992). - - - -Section 10. - 98 - Expires 11 January 1998 - - - - - - - - Version 5 - Specification Revision 6 - - -12. National Bureau of Standards, U.S. Department of Com- - merce, "Data Encryption Standard," Federal Information - Processing Standards Publication 46, Washington, DC - (1977). - -13. National Bureau of Standards, U.S. Department of Com- - merce, "DES Modes of Operation," Federal Information - Processing Standards Publication 81, Springfield, VA - (December 1980). - -14. Stuart G. Stubblebine and Virgil D. Gligor, "On Message - Integrity in Cryptographic Protocols," in Proceedings - of the IEEE Symposium on Research in Security and - Privacy, Oakland, California (May 1992). - -15. International Organization for Standardization, "ISO - Information Processing Systems - Data Communication - - High-Level Data Link Control Procedure - Frame Struc- - ture," IS 3309 (October 1984). 3rd Edition. - -16. R. Rivest, "The MD4 Message Digest Algorithm," RFC - 1320, MIT Laboratory for Computer Science (April - 1992). - -17. R. Rivest, "The MD5 Message Digest Algorithm," RFC - 1321, MIT Laboratory for Computer Science (April - 1992). - -18. H. Krawczyk, M. Bellare, and R. Canetti, "HMAC: Keyed- - Hashing for Message Authentication," Working Draft - draft-ietf-ipsec-hmac-md5-01.txt, (August 1996). - - - - - - - - - - - - - - - - - - - - - - - - - -Section 10. - 99 - Expires 11 January 1998 - - - - - - - - Version 5 - Specification Revision 6 - - -A. Pseudo-code for protocol processing - - This appendix provides pseudo-code describing how the -messages are to be constructed and interpreted by clients -and servers. - -A.1. KRB_AS_REQ generation - request.pvno := protocol version; /* pvno = 5 */ - request.msg-type := message type; /* type = KRB_AS_REQ */ - - if(pa_enc_timestamp_required) then - request.padata.padata-type = PA-ENC-TIMESTAMP; - get system_time; - padata-body.patimestamp,pausec = system_time; - encrypt padata-body into request.padata.padata-value - using client.key; /* derived from password */ - endif - - body.kdc-options := users's preferences; - body.cname := user's name; - body.realm := user's realm; - body.sname := service's name; /* usually "krbtgt", "localrealm" */ - if (body.kdc-options.POSTDATED is set) then - body.from := requested starting time; - else - omit body.from; - endif - body.till := requested end time; - if (body.kdc-options.RENEWABLE is set) then - body.rtime := requested final renewal time; - endif - body.nonce := random_nonce(); - body.etype := requested etypes; - if (user supplied addresses) then - body.addresses := user's addresses; - else - omit body.addresses; - endif - omit body.enc-authorization-data; - request.req-body := body; - - kerberos := lookup(name of local kerberos server (or servers)); - send(packet,kerberos); - - wait(for response); - if (timed_out) then - retry or use alternate server; - endif - -A.2. KRB_AS_REQ verification and KRB_AS_REP generation - decode message into req; - - client := lookup(req.cname,req.realm); - server := lookup(req.sname,req.realm); - - -Section A.2. - 100 - Expires 11 January 1998 - - - - - - - - Version 5 - Specification Revision 6 - - - - get system_time; - kdc_time := system_time.seconds; - - if (!client) then - /* no client in Database */ - error_out(KDC_ERR_C_PRINCIPAL_UNKNOWN); - endif - if (!server) then - /* no server in Database */ - error_out(KDC_ERR_S_PRINCIPAL_UNKNOWN); - endif - - if(client.pa_enc_timestamp_required and - pa_enc_timestamp not present) then - error_out(KDC_ERR_PREAUTH_REQUIRED(PA_ENC_TIMESTAMP)); - endif - - if(pa_enc_timestamp present) then - decrypt req.padata-value into decrypted_enc_timestamp - using client.key; - using auth_hdr.authenticator.subkey; - if (decrypt_error()) then - error_out(KRB_AP_ERR_BAD_INTEGRITY); - if(decrypted_enc_timestamp is not within allowable skew) then - error_out(KDC_ERR_PREAUTH_FAILED); - endif - if(decrypted_enc_timestamp and usec is replay) - error_out(KDC_ERR_PREAUTH_FAILED); - endif - add decrypted_enc_timestamp and usec to replay cache; - endif - - use_etype := first supported etype in req.etypes; - - if (no support for req.etypes) then - error_out(KDC_ERR_ETYPE_NOSUPP); - endif - - new_tkt.vno := ticket version; /* = 5 */ - new_tkt.sname := req.sname; - new_tkt.srealm := req.srealm; - reset all flags in new_tkt.flags; - - /* It should be noted that local policy may affect the */ - /* processing of any of these flags. For example, some */ - /* realms may refuse to issue renewable tickets */ - - if (req.kdc-options.FORWARDABLE is set) then - set new_tkt.flags.FORWARDABLE; - endif - if (req.kdc-options.PROXIABLE is set) then - set new_tkt.flags.PROXIABLE; - endif - - -Section A.2. - 101 - Expires 11 January 1998 - - - - - - - - Version 5 - Specification Revision 6 - - - if (req.kdc-options.ALLOW-POSTDATE is set) then - set new_tkt.flags.MAY-POSTDATE; - endif - if ((req.kdc-options.RENEW is set) or - (req.kdc-options.VALIDATE is set) or - (req.kdc-options.PROXY is set) or - (req.kdc-options.FORWARDED is set) or - (req.kdc-options.ENC-TKT-IN-SKEY is set)) then - error_out(KDC_ERR_BADOPTION); - endif - - new_tkt.session := random_session_key(); - new_tkt.cname := req.cname; - new_tkt.crealm := req.crealm; - new_tkt.transited := empty_transited_field(); - - new_tkt.authtime := kdc_time; - - if (req.kdc-options.POSTDATED is set) then - if (against_postdate_policy(req.from)) then - error_out(KDC_ERR_POLICY); - endif - set new_tkt.flags.POSTDATED; - set new_tkt.flags.INVALID; - new_tkt.starttime := req.from; - else - omit new_tkt.starttime; /* treated as authtime when omitted */ - endif - if (req.till = 0) then - till := infinity; - else - till := req.till; - endif - - new_tkt.endtime := min(till, - new_tkt.starttime+client.max_life, - new_tkt.starttime+server.max_life, - new_tkt.starttime+max_life_for_realm); - - if ((req.kdc-options.RENEWABLE-OK is set) and - (new_tkt.endtime < req.till)) then - /* we set the RENEWABLE option for later processing */ - set req.kdc-options.RENEWABLE; - req.rtime := req.till; - endif - - if (req.rtime = 0) then - rtime := infinity; - else - rtime := req.rtime; - endif - - if (req.kdc-options.RENEWABLE is set) then - set new_tkt.flags.RENEWABLE; - - -Section A.2. - 102 - Expires 11 January 1998 - - - - - - - - Version 5 - Specification Revision 6 - - - new_tkt.renew-till := min(rtime, - new_tkt.starttime+client.max_rlife, - new_tkt.starttime+server.max_rlife, - new_tkt.starttime+max_rlife_for_realm); - else - omit new_tkt.renew-till; /* only present if RENEWABLE */ - endif - - if (req.addresses) then - new_tkt.caddr := req.addresses; - else - omit new_tkt.caddr; - endif - - new_tkt.authorization_data := empty_authorization_data(); - - encode to-be-encrypted part of ticket into OCTET STRING; - new_tkt.enc-part := encrypt OCTET STRING - using etype_for_key(server.key), server.key, server.p_kvno; - - - /* Start processing the response */ - - resp.pvno := 5; - resp.msg-type := KRB_AS_REP; - resp.cname := req.cname; - resp.crealm := req.realm; - resp.ticket := new_tkt; - - resp.key := new_tkt.session; - resp.last-req := fetch_last_request_info(client); - resp.nonce := req.nonce; - resp.key-expiration := client.expiration; - resp.flags := new_tkt.flags; - - resp.authtime := new_tkt.authtime; - resp.starttime := new_tkt.starttime; - resp.endtime := new_tkt.endtime; - - if (new_tkt.flags.RENEWABLE) then - resp.renew-till := new_tkt.renew-till; - endif - - resp.realm := new_tkt.realm; - resp.sname := new_tkt.sname; - - resp.caddr := new_tkt.caddr; - - encode body of reply into OCTET STRING; - - resp.enc-part := encrypt OCTET STRING - using use_etype, client.key, client.p_kvno; - send(resp); - - - -Section A.2. - 103 - Expires 11 January 1998 - - - - - - - - Version 5 - Specification Revision 6 - - -A.3. KRB_AS_REP verification - decode response into resp; - - if (resp.msg-type = KRB_ERROR) then - if(error = KDC_ERR_PREAUTH_REQUIRED(PA_ENC_TIMESTAMP)) then - set pa_enc_timestamp_required; - goto KRB_AS_REQ; - endif - process_error(resp); - return; - endif - - /* On error, discard the response, and zero the session key */ - /* from the response immediately */ - - key = get_decryption_key(resp.enc-part.kvno, resp.enc-part.etype, - resp.padata); - unencrypted part of resp := decode of decrypt of resp.enc-part - using resp.enc-part.etype and key; - zero(key); - - if (common_as_rep_tgs_rep_checks fail) then - destroy resp.key; - return error; - endif - - if near(resp.princ_exp) then - print(warning message); - endif - save_for_later(ticket,session,client,server,times,flags); - -A.4. KRB_AS_REP and KRB_TGS_REP common checks - if (decryption_error() or - (req.cname != resp.cname) or - (req.realm != resp.crealm) or - (req.sname != resp.sname) or - (req.realm != resp.realm) or - (req.nonce != resp.nonce) or - (req.addresses != resp.caddr)) then - destroy resp.key; - return KRB_AP_ERR_MODIFIED; - endif - - /* make sure no flags are set that shouldn't be, and that all that */ - /* should be are set */ - if (!check_flags_for_compatability(req.kdc-options,resp.flags)) then - destroy resp.key; - return KRB_AP_ERR_MODIFIED; - endif - - if ((req.from = 0) and - (resp.starttime is not within allowable skew)) then - destroy resp.key; - return KRB_AP_ERR_SKEW; - - -Section A.4. - 104 - Expires 11 January 1998 - - - - - - - - Version 5 - Specification Revision 6 - - - endif - if ((req.from != 0) and (req.from != resp.starttime)) then - destroy resp.key; - return KRB_AP_ERR_MODIFIED; - endif - if ((req.till != 0) and (resp.endtime > req.till)) then - destroy resp.key; - return KRB_AP_ERR_MODIFIED; - endif - - if ((req.kdc-options.RENEWABLE is set) and - (req.rtime != 0) and (resp.renew-till > req.rtime)) then - destroy resp.key; - return KRB_AP_ERR_MODIFIED; - endif - if ((req.kdc-options.RENEWABLE-OK is set) and - (resp.flags.RENEWABLE) and - (req.till != 0) and - (resp.renew-till > req.till)) then - destroy resp.key; - return KRB_AP_ERR_MODIFIED; - endif - -A.5. KRB_TGS_REQ generation - /* Note that make_application_request might have to recursivly */ - /* call this routine to get the appropriate ticket-granting ticket */ - - request.pvno := protocol version; /* pvno = 5 */ - request.msg-type := message type; /* type = KRB_TGS_REQ */ - - body.kdc-options := users's preferences; - /* If the TGT is not for the realm of the end-server */ - /* then the sname will be for a TGT for the end-realm */ - /* and the realm of the requested ticket (body.realm) */ - /* will be that of the TGS to which the TGT we are */ - /* sending applies */ - body.sname := service's name; - body.realm := service's realm; - - if (body.kdc-options.POSTDATED is set) then - body.from := requested starting time; - else - omit body.from; - endif - body.till := requested end time; - if (body.kdc-options.RENEWABLE is set) then - body.rtime := requested final renewal time; - endif - body.nonce := random_nonce(); - body.etype := requested etypes; - if (user supplied addresses) then - body.addresses := user's addresses; - else - omit body.addresses; - - -Section A.5. - 105 - Expires 11 January 1998 - - - - - - - - Version 5 - Specification Revision 6 - - - endif - - body.enc-authorization-data := user-supplied data; - if (body.kdc-options.ENC-TKT-IN-SKEY) then - body.additional-tickets_ticket := second TGT; - endif - - request.req-body := body; - check := generate_checksum (req.body,checksumtype); - - request.padata[0].padata-type := PA-TGS-REQ; - request.padata[0].padata-value := create a KRB_AP_REQ using - the TGT and checksum - - /* add in any other padata as required/supplied */ - - kerberos := lookup(name of local kerberose server (or servers)); - send(packet,kerberos); - - wait(for response); - if (timed_out) then - retry or use alternate server; - endif - -A.6. KRB_TGS_REQ verification and KRB_TGS_REP generation - /* note that reading the application request requires first - determining the server for which a ticket was issued, and choosing the - correct key for decryption. The name of the server appears in the - plaintext part of the ticket. */ - - if (no KRB_AP_REQ in req.padata) then - error_out(KDC_ERR_PADATA_TYPE_NOSUPP); - endif - verify KRB_AP_REQ in req.padata; - - /* Note that the realm in which the Kerberos server is operating is - determined by the instance from the ticket-granting ticket. The realm - in the ticket-granting ticket is the realm under which the ticket - granting ticket was issued. It is possible for a single Kerberos - server to support more than one realm. */ - - auth_hdr := KRB_AP_REQ; - tgt := auth_hdr.ticket; - - if (tgt.sname is not a TGT for local realm and is not req.sname) then - error_out(KRB_AP_ERR_NOT_US); - - realm := realm_tgt_is_for(tgt); - - decode remainder of request; - - if (auth_hdr.authenticator.cksum is missing) then - error_out(KRB_AP_ERR_INAPP_CKSUM); - endif - - -Section A.6. - 106 - Expires 11 January 1998 - - - - - - - - Version 5 - Specification Revision 6 - - - if (auth_hdr.authenticator.cksum type is not supported) then - error_out(KDC_ERR_SUMTYPE_NOSUPP); - endif - if (auth_hdr.authenticator.cksum is not both collision-proof and keyed) then - error_out(KRB_AP_ERR_INAPP_CKSUM); - endif - - set computed_checksum := checksum(req); - if (computed_checksum != auth_hdr.authenticatory.cksum) then - error_out(KRB_AP_ERR_MODIFIED); - endif - - server := lookup(req.sname,realm); - - if (!server) then - if (is_foreign_tgt_name(server)) then - server := best_intermediate_tgs(server); - else - /* no server in Database */ - error_out(KDC_ERR_S_PRINCIPAL_UNKNOWN); - endif - endif - - session := generate_random_session_key(); - - - use_etype := first supported etype in req.etypes; - - if (no support for req.etypes) then - error_out(KDC_ERR_ETYPE_NOSUPP); - endif - - new_tkt.vno := ticket version; /* = 5 */ - new_tkt.sname := req.sname; - new_tkt.srealm := realm; - reset all flags in new_tkt.flags; - - /* It should be noted that local policy may affect the */ - /* processing of any of these flags. For example, some */ - /* realms may refuse to issue renewable tickets */ - - new_tkt.caddr := tgt.caddr; - resp.caddr := NULL; /* We only include this if they change */ - if (req.kdc-options.FORWARDABLE is set) then - if (tgt.flags.FORWARDABLE is reset) then - error_out(KDC_ERR_BADOPTION); - endif - set new_tkt.flags.FORWARDABLE; - endif - if (req.kdc-options.FORWARDED is set) then - if (tgt.flags.FORWARDABLE is reset) then - error_out(KDC_ERR_BADOPTION); - endif - set new_tkt.flags.FORWARDED; - - -Section A.6. - 107 - Expires 11 January 1998 - - - - - - - - Version 5 - Specification Revision 6 - - - new_tkt.caddr := req.addresses; - resp.caddr := req.addresses; - endif - if (tgt.flags.FORWARDED is set) then - set new_tkt.flags.FORWARDED; - endif - - if (req.kdc-options.PROXIABLE is set) then - if (tgt.flags.PROXIABLE is reset) - error_out(KDC_ERR_BADOPTION); - endif - set new_tkt.flags.PROXIABLE; - endif - if (req.kdc-options.PROXY is set) then - if (tgt.flags.PROXIABLE is reset) then - error_out(KDC_ERR_BADOPTION); - endif - set new_tkt.flags.PROXY; - new_tkt.caddr := req.addresses; - resp.caddr := req.addresses; - endif - - if (req.kdc-options.ALLOW-POSTDATE is set) then - if (tgt.flags.MAY-POSTDATE is reset) - error_out(KDC_ERR_BADOPTION); - endif - set new_tkt.flags.MAY-POSTDATE; - endif - if (req.kdc-options.POSTDATED is set) then - if (tgt.flags.MAY-POSTDATE is reset) then - error_out(KDC_ERR_BADOPTION); - endif - set new_tkt.flags.POSTDATED; - set new_tkt.flags.INVALID; - if (against_postdate_policy(req.from)) then - error_out(KDC_ERR_POLICY); - endif - new_tkt.starttime := req.from; - endif - - - if (req.kdc-options.VALIDATE is set) then - if (tgt.flags.INVALID is reset) then - error_out(KDC_ERR_POLICY); - endif - if (tgt.starttime > kdc_time) then - error_out(KRB_AP_ERR_NYV); - endif - if (check_hot_list(tgt)) then - error_out(KRB_AP_ERR_REPEAT); - endif - tkt := tgt; - reset new_tkt.flags.INVALID; - endif - - -Section A.6. - 108 - Expires 11 January 1998 - - - - - - - - Version 5 - Specification Revision 6 - - - if (req.kdc-options.(any flag except ENC-TKT-IN-SKEY, RENEW, - and those already processed) is set) then - error_out(KDC_ERR_BADOPTION); - endif - - new_tkt.authtime := tgt.authtime; - - if (req.kdc-options.RENEW is set) then - /* Note that if the endtime has already passed, the ticket would */ - /* have been rejected in the initial authentication stage, so */ - /* there is no need to check again here */ - if (tgt.flags.RENEWABLE is reset) then - error_out(KDC_ERR_BADOPTION); - endif - if (tgt.renew-till >= kdc_time) then - error_out(KRB_AP_ERR_TKT_EXPIRED); - endif - tkt := tgt; - new_tkt.starttime := kdc_time; - old_life := tgt.endttime - tgt.starttime; - new_tkt.endtime := min(tgt.renew-till, - new_tkt.starttime + old_life); - else - new_tkt.starttime := kdc_time; - if (req.till = 0) then - till := infinity; - else - till := req.till; - endif - new_tkt.endtime := min(till, - new_tkt.starttime+client.max_life, - new_tkt.starttime+server.max_life, - new_tkt.starttime+max_life_for_realm, - tgt.endtime); - - if ((req.kdc-options.RENEWABLE-OK is set) and - (new_tkt.endtime < req.till) and - (tgt.flags.RENEWABLE is set) then - /* we set the RENEWABLE option for later processing */ - set req.kdc-options.RENEWABLE; - req.rtime := min(req.till, tgt.renew-till); - endif - endif - - if (req.rtime = 0) then - rtime := infinity; - else - rtime := req.rtime; - endif - - if ((req.kdc-options.RENEWABLE is set) and - (tgt.flags.RENEWABLE is set)) then - set new_tkt.flags.RENEWABLE; - new_tkt.renew-till := min(rtime, - - -Section A.6. - 109 - Expires 11 January 1998 - - - - - - - - Version 5 - Specification Revision 6 - - - new_tkt.starttime+client.max_rlife, - new_tkt.starttime+server.max_rlife, - new_tkt.starttime+max_rlife_for_realm, - tgt.renew-till); - else - new_tkt.renew-till := OMIT; /* leave the renew-till field out */ - endif - if (req.enc-authorization-data is present) then - decrypt req.enc-authorization-data into decrypted_authorization_data - using auth_hdr.authenticator.subkey; - if (decrypt_error()) then - error_out(KRB_AP_ERR_BAD_INTEGRITY); - endif - endif - new_tkt.authorization_data := req.auth_hdr.ticket.authorization_data + - decrypted_authorization_data; - - new_tkt.key := session; - new_tkt.crealm := tgt.crealm; - new_tkt.cname := req.auth_hdr.ticket.cname; - - if (realm_tgt_is_for(tgt) := tgt.realm) then - /* tgt issued by local realm */ - new_tkt.transited := tgt.transited; - else - /* was issued for this realm by some other realm */ - if (tgt.transited.tr-type not supported) then - error_out(KDC_ERR_TRTYPE_NOSUPP); - endif - new_tkt.transited := compress_transited(tgt.transited + tgt.realm) - endif - - encode encrypted part of new_tkt into OCTET STRING; - if (req.kdc-options.ENC-TKT-IN-SKEY is set) then - if (server not specified) then - server = req.second_ticket.client; - endif - if ((req.second_ticket is not a TGT) or - (req.second_ticket.client != server)) then - error_out(KDC_ERR_POLICY); - endif - - new_tkt.enc-part := encrypt OCTET STRING using - using etype_for_key(second-ticket.key), second-ticket.key; - else - new_tkt.enc-part := encrypt OCTET STRING - using etype_for_key(server.key), server.key, server.p_kvno; - endif - - resp.pvno := 5; - resp.msg-type := KRB_TGS_REP; - resp.crealm := tgt.crealm; - resp.cname := tgt.cname; - - - -Section A.6. - 110 - Expires 11 January 1998 - - - - - - - - Version 5 - Specification Revision 6 - - - resp.ticket := new_tkt; - - resp.key := session; - resp.nonce := req.nonce; - resp.last-req := fetch_last_request_info(client); - resp.flags := new_tkt.flags; - - resp.authtime := new_tkt.authtime; - resp.starttime := new_tkt.starttime; - resp.endtime := new_tkt.endtime; - - omit resp.key-expiration; - - resp.sname := new_tkt.sname; - resp.realm := new_tkt.realm; - - if (new_tkt.flags.RENEWABLE) then - resp.renew-till := new_tkt.renew-till; - endif - - - encode body of reply into OCTET STRING; - - if (req.padata.authenticator.subkey) - resp.enc-part := encrypt OCTET STRING using use_etype, - req.padata.authenticator.subkey; - else resp.enc-part := encrypt OCTET STRING using use_etype, tgt.key; - - send(resp); - -A.7. KRB_TGS_REP verification - decode response into resp; - - if (resp.msg-type = KRB_ERROR) then - process_error(resp); - return; - endif - - /* On error, discard the response, and zero the session key from - the response immediately */ - - if (req.padata.authenticator.subkey) - unencrypted part of resp := decode of decrypt of resp.enc-part - using resp.enc-part.etype and subkey; - else unencrypted part of resp := decode of decrypt of resp.enc-part - using resp.enc-part.etype and tgt's session key; - if (common_as_rep_tgs_rep_checks fail) then - destroy resp.key; - return error; - endif - - check authorization_data as necessary; - save_for_later(ticket,session,client,server,times,flags); - - - -Section A.7. - 111 - Expires 11 January 1998 - - - - - - - - Version 5 - Specification Revision 6 - - -A.8. Authenticator generation - body.authenticator-vno := authenticator vno; /* = 5 */ - body.cname, body.crealm := client name; - if (supplying checksum) then - body.cksum := checksum; - endif - get system_time; - body.ctime, body.cusec := system_time; - if (selecting sub-session key) then - select sub-session key; - body.subkey := sub-session key; - endif - if (using sequence numbers) then - select initial sequence number; - body.seq-number := initial sequence; - endif - -A.9. KRB_AP_REQ generation - obtain ticket and session_key from cache; - - packet.pvno := protocol version; /* 5 */ - packet.msg-type := message type; /* KRB_AP_REQ */ - - if (desired(MUTUAL_AUTHENTICATION)) then - set packet.ap-options.MUTUAL-REQUIRED; - else - reset packet.ap-options.MUTUAL-REQUIRED; - endif - if (using session key for ticket) then - set packet.ap-options.USE-SESSION-KEY; - else - reset packet.ap-options.USE-SESSION-KEY; - endif - packet.ticket := ticket; /* ticket */ - generate authenticator; - encode authenticator into OCTET STRING; - encrypt OCTET STRING into packet.authenticator using session_key; - -A.10. KRB_AP_REQ verification - receive packet; - if (packet.pvno != 5) then - either process using other protocol spec - or error_out(KRB_AP_ERR_BADVERSION); - endif - if (packet.msg-type != KRB_AP_REQ) then - error_out(KRB_AP_ERR_MSG_TYPE); - endif - if (packet.ticket.tkt_vno != 5) then - either process using other protocol spec - or error_out(KRB_AP_ERR_BADVERSION); - endif - if (packet.ap_options.USE-SESSION-KEY is set) then - retrieve session key from ticket-granting ticket for - packet.ticket.{sname,srealm,enc-part.etype}; - - -Section A.10. - 112 - Expires 11 January 1998 - - - - - - - - Version 5 - Specification Revision 6 - - - else - retrieve service key for - packet.ticket.{sname,srealm,enc-part.etype,enc-part.skvno}; - endif - if (no_key_available) then - if (cannot_find_specified_skvno) then - error_out(KRB_AP_ERR_BADKEYVER); - else - error_out(KRB_AP_ERR_NOKEY); - endif - endif - decrypt packet.ticket.enc-part into decr_ticket using retrieved key; - if (decryption_error()) then - error_out(KRB_AP_ERR_BAD_INTEGRITY); - endif - decrypt packet.authenticator into decr_authenticator - using decr_ticket.key; - if (decryption_error()) then - error_out(KRB_AP_ERR_BAD_INTEGRITY); - endif - if (decr_authenticator.{cname,crealm} != - decr_ticket.{cname,crealm}) then - error_out(KRB_AP_ERR_BADMATCH); - endif - if (decr_ticket.caddr is present) then - if (sender_address(packet) is not in decr_ticket.caddr) then - error_out(KRB_AP_ERR_BADADDR); - endif - elseif (application requires addresses) then - error_out(KRB_AP_ERR_BADADDR); - endif - if (not in_clock_skew(decr_authenticator.ctime, - decr_authenticator.cusec)) then - error_out(KRB_AP_ERR_SKEW); - endif - if (repeated(decr_authenticator.{ctime,cusec,cname,crealm})) then - error_out(KRB_AP_ERR_REPEAT); - endif - save_identifier(decr_authenticator.{ctime,cusec,cname,crealm}); - get system_time; - if ((decr_ticket.starttime-system_time > CLOCK_SKEW) or - (decr_ticket.flags.INVALID is set)) then - /* it hasn't yet become valid */ - error_out(KRB_AP_ERR_TKT_NYV); - endif - if (system_time-decr_ticket.endtime > CLOCK_SKEW) then - error_out(KRB_AP_ERR_TKT_EXPIRED); - endif - /* caller must check decr_ticket.flags for any pertinent details */ - return(OK, decr_ticket, packet.ap_options.MUTUAL-REQUIRED); - -A.11. KRB_AP_REP generation - packet.pvno := protocol version; /* 5 */ - packet.msg-type := message type; /* KRB_AP_REP */ - - -Section A.11. - 113 - Expires 11 January 1998 - - - - - - - - Version 5 - Specification Revision 6 - - - body.ctime := packet.ctime; - body.cusec := packet.cusec; - if (selecting sub-session key) then - select sub-session key; - body.subkey := sub-session key; - endif - if (using sequence numbers) then - select initial sequence number; - body.seq-number := initial sequence; - endif - - encode body into OCTET STRING; - - select encryption type; - encrypt OCTET STRING into packet.enc-part; - -A.12. KRB_AP_REP verification - receive packet; - if (packet.pvno != 5) then - either process using other protocol spec - or error_out(KRB_AP_ERR_BADVERSION); - endif - if (packet.msg-type != KRB_AP_REP) then - error_out(KRB_AP_ERR_MSG_TYPE); - endif - cleartext := decrypt(packet.enc-part) using ticket's session key; - if (decryption_error()) then - error_out(KRB_AP_ERR_BAD_INTEGRITY); - endif - if (cleartext.ctime != authenticator.ctime) then - error_out(KRB_AP_ERR_MUT_FAIL); - endif - if (cleartext.cusec != authenticator.cusec) then - error_out(KRB_AP_ERR_MUT_FAIL); - endif - if (cleartext.subkey is present) then - save cleartext.subkey for future use; - endif - if (cleartext.seq-number is present) then - save cleartext.seq-number for future verifications; - endif - return(AUTHENTICATION_SUCCEEDED); - -A.13. KRB_SAFE generation - collect user data in buffer; - - /* assemble packet: */ - packet.pvno := protocol version; /* 5 */ - packet.msg-type := message type; /* KRB_SAFE */ - - body.user-data := buffer; /* DATA */ - if (using timestamp) then - get system_time; - body.timestamp, body.usec := system_time; - - -Section A.13. - 114 - Expires 11 January 1998 - - - - - - - - Version 5 - Specification Revision 6 - - - endif - if (using sequence numbers) then - body.seq-number := sequence number; - endif - body.s-address := sender host addresses; - if (only one recipient) then - body.r-address := recipient host address; - endif - checksum.cksumtype := checksum type; - compute checksum over body; - checksum.checksum := checksum value; /* checksum.checksum */ - packet.cksum := checksum; - packet.safe-body := body; - -A.14. KRB_SAFE verification - receive packet; - if (packet.pvno != 5) then - either process using other protocol spec - or error_out(KRB_AP_ERR_BADVERSION); - endif - if (packet.msg-type != KRB_SAFE) then - error_out(KRB_AP_ERR_MSG_TYPE); - endif - if (packet.checksum.cksumtype is not both collision-proof and keyed) then - error_out(KRB_AP_ERR_INAPP_CKSUM); - endif - if (safe_priv_common_checks_ok(packet)) then - set computed_checksum := checksum(packet.body); - if (computed_checksum != packet.checksum) then - error_out(KRB_AP_ERR_MODIFIED); - endif - return (packet, PACKET_IS_GENUINE); - else - return common_checks_error; - endif - -A.15. KRB_SAFE and KRB_PRIV common checks - if (packet.s-address != O/S_sender(packet)) then - /* O/S report of sender not who claims to have sent it */ - error_out(KRB_AP_ERR_BADADDR); - endif - if ((packet.r-address is present) and - (packet.r-address != local_host_address)) then - /* was not sent to proper place */ - error_out(KRB_AP_ERR_BADADDR); - endif - if (((packet.timestamp is present) and - (not in_clock_skew(packet.timestamp,packet.usec))) or - (packet.timestamp is not present and timestamp expected)) then - error_out(KRB_AP_ERR_SKEW); - endif - if (repeated(packet.timestamp,packet.usec,packet.s-address)) then - error_out(KRB_AP_ERR_REPEAT); - endif - - -Section A.15. - 115 - Expires 11 January 1998 - - - - - - - - Version 5 - Specification Revision 6 - - - if (((packet.seq-number is present) and - ((not in_sequence(packet.seq-number)))) or - (packet.seq-number is not present and sequence expected)) then - error_out(KRB_AP_ERR_BADORDER); - endif - if (packet.timestamp not present and packet.seq-number not present) then - error_out(KRB_AP_ERR_MODIFIED); - endif - - save_identifier(packet.{timestamp,usec,s-address}, - sender_principal(packet)); - - return PACKET_IS_OK; - -A.16. KRB_PRIV generation - collect user data in buffer; - - /* assemble packet: */ - packet.pvno := protocol version; /* 5 */ - packet.msg-type := message type; /* KRB_PRIV */ - - packet.enc-part.etype := encryption type; - - body.user-data := buffer; - if (using timestamp) then - get system_time; - body.timestamp, body.usec := system_time; - endif - if (using sequence numbers) then - body.seq-number := sequence number; - endif - body.s-address := sender host addresses; - if (only one recipient) then - body.r-address := recipient host address; - endif - - encode body into OCTET STRING; - - select encryption type; - encrypt OCTET STRING into packet.enc-part.cipher; - - -A.17. KRB_PRIV verification - receive packet; - if (packet.pvno != 5) then - either process using other protocol spec - or error_out(KRB_AP_ERR_BADVERSION); - endif - if (packet.msg-type != KRB_PRIV) then - error_out(KRB_AP_ERR_MSG_TYPE); - endif - - cleartext := decrypt(packet.enc-part) using negotiated key; - if (decryption_error()) then - - -Section A.17. - 116 - Expires 11 January 1998 - - - - - - - - Version 5 - Specification Revision 6 - - - error_out(KRB_AP_ERR_BAD_INTEGRITY); - endif - - if (safe_priv_common_checks_ok(cleartext)) then - return(cleartext.DATA, PACKET_IS_GENUINE_AND_UNMODIFIED); - else - return common_checks_error; - endif - -A.18. KRB_CRED generation - invoke KRB_TGS; /* obtain tickets to be provided to peer */ - - /* assemble packet: */ - packet.pvno := protocol version; /* 5 */ - packet.msg-type := message type; /* KRB_CRED */ - - for (tickets[n] in tickets to be forwarded) do - packet.tickets[n] = tickets[n].ticket; - done - - packet.enc-part.etype := encryption type; - - for (ticket[n] in tickets to be forwarded) do - body.ticket-info[n].key = tickets[n].session; - body.ticket-info[n].prealm = tickets[n].crealm; - body.ticket-info[n].pname = tickets[n].cname; - body.ticket-info[n].flags = tickets[n].flags; - body.ticket-info[n].authtime = tickets[n].authtime; - body.ticket-info[n].starttime = tickets[n].starttime; - body.ticket-info[n].endtime = tickets[n].endtime; - body.ticket-info[n].renew-till = tickets[n].renew-till; - body.ticket-info[n].srealm = tickets[n].srealm; - body.ticket-info[n].sname = tickets[n].sname; - body.ticket-info[n].caddr = tickets[n].caddr; - done - - get system_time; - body.timestamp, body.usec := system_time; - - if (using nonce) then - body.nonce := nonce; - endif - - if (using s-address) then - body.s-address := sender host addresses; - endif - if (limited recipients) then - body.r-address := recipient host address; - endif - - encode body into OCTET STRING; - - select encryption type; - encrypt OCTET STRING into packet.enc-part.cipher - - -Section A.18. - 117 - Expires 11 January 1998 - - - - - - - - Version 5 - Specification Revision 6 - - - using negotiated encryption key; - - -A.19. KRB_CRED verification - receive packet; - if (packet.pvno != 5) then - either process using other protocol spec - or error_out(KRB_AP_ERR_BADVERSION); - endif - if (packet.msg-type != KRB_CRED) then - error_out(KRB_AP_ERR_MSG_TYPE); - endif - - cleartext := decrypt(packet.enc-part) using negotiated key; - if (decryption_error()) then - error_out(KRB_AP_ERR_BAD_INTEGRITY); - endif - if ((packet.r-address is present or required) and - (packet.s-address != O/S_sender(packet)) then - /* O/S report of sender not who claims to have sent it */ - error_out(KRB_AP_ERR_BADADDR); - endif - if ((packet.r-address is present) and - (packet.r-address != local_host_address)) then - /* was not sent to proper place */ - error_out(KRB_AP_ERR_BADADDR); - endif - if (not in_clock_skew(packet.timestamp,packet.usec)) then - error_out(KRB_AP_ERR_SKEW); - endif - if (repeated(packet.timestamp,packet.usec,packet.s-address)) then - error_out(KRB_AP_ERR_REPEAT); - endif - if (packet.nonce is required or present) and - (packet.nonce != expected-nonce) then - error_out(KRB_AP_ERR_MODIFIED); - endif - - for (ticket[n] in tickets that were forwarded) do - save_for_later(ticket[n],key[n],principal[n], - server[n],times[n],flags[n]); - return - -A.20. KRB_ERROR generation - - /* assemble packet: */ - packet.pvno := protocol version; /* 5 */ - packet.msg-type := message type; /* KRB_ERROR */ - - get system_time; - packet.stime, packet.susec := system_time; - packet.realm, packet.sname := server name; - - if (client time available) then - - -Section A.20. - 118 - Expires 11 January 1998 - - - - - - - - Version 5 - Specification Revision 6 - - - packet.ctime, packet.cusec := client_time; - endif - packet.error-code := error code; - if (client name available) then - packet.cname, packet.crealm := client name; - endif - if (error text available) then - packet.e-text := error text; - endif - if (error data available) then - packet.e-data := error data; - endif - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 119 - Expires 11 January 1998 - - - - - - - - Version 5 - Specification Revision 6 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - cxx - Expires 11 January 1998 - - - - - - - - - - - Table of Contents - - - - -Overview .............................................. 2 - -Background ............................................ 2 - -1. Introduction ....................................... 3 - -1.1. Cross-Realm Operation ............................ 5 - -1.2. Authorization .................................... 6 - -1.3. Environmental assumptions ........................ 7 - -1.4. Glossary of terms ................................ 8 - -2. Ticket flag uses and requests ...................... 10 - -2.1. Initial and pre-authenticated tickets ............ 10 - -2.2. Invalid tickets .................................. 11 - -2.3. Renewable tickets ................................ 11 - -2.4. Postdated tickets ................................ 12 - -2.5. Proxiable and proxy tickets ...................... 12 - -2.6. Forwardable tickets .............................. 13 - -2.7. Other KDC options ................................ 14 - -3. Message Exchanges .................................. 14 - -3.1. The Authentication Service Exchange .............. 14 - -3.1.1. Generation of KRB_AS_REQ message ............... 16 - -3.1.2. Receipt of KRB_AS_REQ message .................. 16 - -3.1.3. Generation of KRB_AS_REP message ............... 16 - -3.1.4. Generation of KRB_ERROR message ................ 19 - -3.1.5. Receipt of KRB_AS_REP message .................. 19 - -3.1.6. Receipt of KRB_ERROR message ................... 19 - -3.2. The Client/Server Authentication Exchange ........ 19 - -3.2.1. The KRB_AP_REQ message ......................... 20 - - - - i - Expires 11 January 1998 - - - - - - - - Version 5 - Specification Revision 6 - - -3.2.2. Generation of a KRB_AP_REQ message ............. 20 - -3.2.3. Receipt of KRB_AP_REQ message .................. 21 - -3.2.4. Generation of a KRB_AP_REP message ............. 23 - -3.2.5. Receipt of KRB_AP_REP message .................. 23 - -3.2.6. Using the encryption key ....................... 24 - -3.3. The Ticket-Granting Service (TGS) Exchange ....... 25 - -3.3.1. Generation of KRB_TGS_REQ message .............. 26 - -3.3.2. Receipt of KRB_TGS_REQ message ................. 27 - -3.3.3. Generation of KRB_TGS_REP message .............. 28 - -3.3.3.1. Checking for revoked tickets ................. 30 - -3.3.3.2. Encoding the transited field ................. 30 - -3.3.4. Receipt of KRB_TGS_REP message ................. 32 - -3.4. The KRB_SAFE Exchange ............................ 32 - -3.4.1. Generation of a KRB_SAFE message ............... 32 - -3.4.2. Receipt of KRB_SAFE message .................... 33 - -3.5. The KRB_PRIV Exchange ............................ 34 - -3.5.1. Generation of a KRB_PRIV message ............... 34 - -3.5.2. Receipt of KRB_PRIV message .................... 34 - -3.6. The KRB_CRED Exchange ............................ 35 - -3.6.1. Generation of a KRB_CRED message ............... 35 - -3.6.2. Receipt of KRB_CRED message .................... 35 - -4. The Kerberos Database .............................. 36 - -4.1. Database contents ................................ 36 - -4.2. Additional fields ................................ 37 - -4.3. Frequently Changing Fields ....................... 38 - -4.4. Site Constants ................................... 39 - -5. Message Specifications ............................. 39 - - - - - ii - Expires 11 January 1998 - - - - - - - - Version 5 - Specification Revision 6 - - -5.1. ASN.1 Distinguished Encoding Representation ...... 39 - -5.2. ASN.1 Base Definitions ........................... 40 - -5.3. Tickets and Authenticators ....................... 43 - -5.3.1. Tickets ........................................ 43 - -5.3.2. Authenticators ................................. 52 - -5.4. Specifications for the AS and TGS exchanges ...... 54 - -5.4.1. KRB_KDC_REQ definition ......................... 54 - -5.4.2. KRB_KDC_REP definition ......................... 61 - -5.5. Client/Server (CS) message specifications ........ 64 - -5.5.1. KRB_AP_REQ definition .......................... 64 - -5.5.2. KRB_AP_REP definition .......................... 65 - -5.5.3. Error message reply ............................ 67 - -5.6. KRB_SAFE message specification ................... 67 - -5.6.1. KRB_SAFE definition ............................ 67 - -5.7. KRB_PRIV message specification ................... 68 - -5.7.1. KRB_PRIV definition ............................ 68 - -5.8. KRB_CRED message specification ................... 69 - -5.8.1. KRB_CRED definition ............................ 70 - -5.9. Error message specification ...................... 72 - -5.9.1. KRB_ERROR definition ........................... 72 - -6. Encryption and Checksum Specifications ............. 74 - -6.1. Encryption Specifications ........................ 76 - -6.2. Encryption Keys .................................. 78 - -6.3. Encryption Systems ............................... 78 - -6.3.1. The NULL Encryption System (null) .............. 78 - -6.3.2. DES in CBC mode with a CRC-32 checksum (des- -cbc-crc) .............................................. 79 - -6.3.3. DES in CBC mode with an MD4 checksum (des- - - - - iii - Expires 11 January 1998 - - - - - - - - Version 5 - Specification Revision 6 - - -cbc-md4) .............................................. 79 - -6.3.4. DES in CBC mode with an MD5 checksum (des- -cbc-md5) .............................................. 79 - -6.3.5. Triple DES EDE in outer CBC mode with an SHA1 -checksum (des3-cbc-sha1) .............................. 81 - -6.4. Checksums ........................................ 83 - -6.4.1. The CRC-32 Checksum (crc32) .................... 84 - -6.4.2. The RSA MD4 Checksum (rsa-md4) ................. 84 - -6.4.3. RSA MD4 Cryptographic Checksum Using DES -(rsa-md4-des) ......................................... 84 - -6.4.4. The RSA MD5 Checksum (rsa-md5) ................. 85 - -6.4.5. RSA MD5 Cryptographic Checksum Using DES -(rsa-md5-des) ......................................... 85 - -6.4.6. DES cipher-block chained checksum (des-mac) - -6.4.7. RSA MD4 Cryptographic Checksum Using DES -alternative (rsa-md4-des-k) ........................... 86 - -6.4.8. DES cipher-block chained checksum alternative -(des-mac-k) ........................................... 87 - -7. Naming Constraints ................................. 87 - -7.1. Realm Names ...................................... 87 - -7.2. Principal Names .................................. 88 - -7.2.1. Name of server principals ...................... 89 - -8. Constants and other defined values ................. 90 - -8.1. Host address types ............................... 90 - -8.2. KDC messages ..................................... 91 - -8.2.1. IP transport ................................... 91 - -8.2.2. OSI transport .................................. 91 - -8.2.3. Name of the TGS ................................ 92 - -8.3. Protocol constants and associated values ......... 92 - -9. Interoperability requirements ...................... 95 - - - - - iv - Expires 11 January 1998 - - - - - - - - Version 5 - Specification Revision 6 - - -9.1. Specification 1 .................................. 95 - -9.2. Recommended KDC values ........................... 97 - -10. REFERENCES ........................................ 98 - -A. Pseudo-code for protocol processing ................ 100 - -A.1. KRB_AS_REQ generation ............................ 100 - -A.2. KRB_AS_REQ verification and KRB_AS_REP genera- -tion .................................................. 100 - -A.3. KRB_AS_REP verification .......................... 104 - -A.4. KRB_AS_REP and KRB_TGS_REP common checks ......... 104 - -A.5. KRB_TGS_REQ generation ........................... 105 - -A.6. KRB_TGS_REQ verification and KRB_TGS_REP gen- -eration ............................................... 106 - -A.7. KRB_TGS_REP verification ......................... 111 - -A.8. Authenticator generation ......................... 112 - -A.9. KRB_AP_REQ generation ............................ 112 - -A.10. KRB_AP_REQ verification ......................... 112 - -A.11. KRB_AP_REP generation ........................... 113 - -A.12. KRB_AP_REP verification ......................... 114 - -A.13. KRB_SAFE generation ............................. 114 - -A.14. KRB_SAFE verification ........................... 115 - -A.15. KRB_SAFE and KRB_PRIV common checks ............. 115 - -A.16. KRB_PRIV generation ............................. 116 - -A.17. KRB_PRIV verification ........................... 116 - -A.18. KRB_CRED generation ............................. 117 - -A.19. KRB_CRED verification ........................... 118 - -A.20. KRB_ERROR generation ............................ 118 - - - - - - - - - v - Expires 11 January 1998 - - - - diff --git a/doc/draft-ietf-cat-kerberos-revisions-01.txt b/doc/draft-ietf-cat-kerberos-revisions-01.txt deleted file mode 100644 index 78db9d78f..000000000 --- a/doc/draft-ietf-cat-kerberos-revisions-01.txt +++ /dev/null @@ -1,6214 +0,0 @@ - -INTERNET-DRAFT Clifford Neuman - John Kohl - Theodore Ts'o - 21 November 1997 - -The Kerberos Network Authentication Service (V5) - -STATUS OF THIS MEMO - -This document is an Internet-Draft. Internet-Drafts are working documents of -the Internet Engineering Task Force (IETF), its areas, and its working -groups. Note that other groups may also distribute working documents as -Internet-Drafts. - -Internet-Drafts are draft documents valid for a maximum of six months and -may be updated, replaced, or obsoleted by other documents at any time. It is -inappropriate to use Internet-Drafts as reference material or to cite them -other than as 'work in progress.' - -To learn the current status of any Internet-Draft, please check the -'1id-abstracts.txt' listing contained in the Internet-Drafts Shadow -Directories on ds.internic.net (US East Coast), nic.nordu.net (Europe), -ftp.isi.edu (US West Coast), or munnari.oz.au (Pacific Rim). - -The distribution of this memo is unlimited. It is filed as -draft-ietf-cat-kerberos-r-01.txt, and expires 21 May 1998. Please send -comments to: krb-protocol@MIT.EDU - -ABSTRACT - -This document provides an overview and specification of Version 5 of the -Kerberos protocol, and updates RFC1510 to clarify aspects of the protocol -and its intended use that require more detailed or clearer explanation than -was provided in RFC1510. This document is intended to provide a detailed -description of the protocol, suitable for implementation, together with -descriptions of the appropriate use of protocol messages and fields within -those messages. - -This document is not intended to describe Kerberos to the end user, system -administrator, or application developer. Higher level papers describing -Version 5 of the Kerberos system [NT94] and documenting version 4 [SNS88], -are available elsewhere. - -OVERVIEW - -This INTERNET-DRAFT describes the concepts and model upon which the Kerberos -network authentication system is based. It also specifies Version 5 of the -Kerberos protocol. - -The motivations, goals, assumptions, and rationale behind most design -decisions are treated cursorily; they are more fully described in a paper -available in IEEE communications [NT94] and earlier in the Kerberos portion -of the Athena Technical Plan [MNSS87]. The protocols have been a proposed - - -draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 - -standard and are being considered for advancement for draft standard through -the IETF standard process. Comments are encouraged on the presentation, but -only minor refinements to the protocol as implemented or extensions that fit -within current protocol framework will be considered at this time. - -Requests for addition to an electronic mailing list for discussion of -Kerberos, kerberos@MIT.EDU, may be addressed to kerberos-request@MIT.EDU. -This mailing list is gatewayed onto the Usenet as the group -comp.protocols.kerberos. Requests for further information, including -documents and code availability, may be sent to info-kerberos@MIT.EDU. - -BACKGROUND - -The Kerberos model is based in part on Needham and Schroeder's trusted -third-party authentication protocol [NS78] and on modifications suggested by -Denning and Sacco [DS81]. The original design and implementation of Kerberos -Versions 1 through 4 was the work of two former Project Athena staff -members, Steve Miller of Digital Equipment Corporation and Clifford Neuman -(now at the Information Sciences Institute of the University of Southern -California), along with Jerome Saltzer, Technical Director of Project -Athena, and Jeffrey Schiller, MIT Campus Network Manager. Many other members -of Project Athena have also contributed to the work on Kerberos. - -Version 5 of the Kerberos protocol (described in this document) has evolved -from Version 4 based on new requirements and desires for features not -available in Version 4. The design of Version 5 of the Kerberos protocol was -led by Clifford Neuman and John Kohl with much input from the community. The -development of the MIT reference implementation was led at MIT by John Kohl -and Theodore T'so, with help and contributed code from many others. -Reference implementations of both version 4 and version 5 of Kerberos are -publicly available and commercial implementations have been developed and -are widely used. - -Details on the differences between Kerberos Versions 4 and 5 can be found in -[KNT92]. - -1. Introduction - -Kerberos provides a means of verifying the identities of principals, (e.g. a -workstation user or a network server) on an open (unprotected) network. This -is accomplished without relying on assertions by the host operating system, -without basing trust on host addresses, without requiring physical security -of all the hosts on the network, and under the assumption that packets -traveling along the network can be read, modified, and inserted at will[1]. -Kerberos performs authentication under these conditions as a trusted -third-party authentication service by using conventional (shared secret key -[2] cryptography. Kerberos extensions have been proposed and implemented -that provide for the use of public key cryptography during certain phases of -the authentication protocol. These extensions provide for authentication of -users registered with public key certification authorities, and allow the -system to provide certain benefits of public key cryptography in situations -where they are needed. - -The basic Kerberos authentication process proceeds as follows: A client - - -draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 - -sends a request to the authentication server (AS) requesting 'credentials' -for a given server. The AS responds with these credentials, encrypted in the -client's key. The credentials consist of 1) a 'ticket' for the server and 2) -a temporary encryption key (often called a "session key"). The client -transmits the ticket (which contains the client's identity and a copy of the -session key, all encrypted in the server's key) to the server. The session -key (now shared by the client and server) is used to authenticate the -client, and may optionally be used to authenticate the server. It may also -be used to encrypt further communication between the two parties or to -exchange a separate sub-session key to be used to encrypt further -communication. - -Implementation of the basic protocol consists of one or more authentication -servers running on physically secure hosts. The authentication servers -maintain a database of principals (i.e., users and servers) and their secret -keys. Code libraries provide encryption and implement the Kerberos protocol. -In order to add authentication to its transactions, a typical network -application adds one or two calls to the Kerberos library directly or -through the Generic Security Services Application Programming Interface, -GSSAPI, described in separate document. These calls result in the -transmission of the necessary messages to achieve authentication. - -The Kerberos protocol consists of several sub-protocols (or exchanges). -There are two basic methods by which a client can ask a Kerberos server for -credentials. In the first approach, the client sends a cleartext request for -a ticket for the desired server to the AS. The reply is sent encrypted in -the client's secret key. Usually this request is for a ticket-granting -ticket (TGT) which can later be used with the ticket-granting server (TGS). -In the second method, the client sends a request to the TGS. The client uses -the TGT to authenticate itself to the TGS in the same manner as if it were -contacting any other application server that requires Kerberos -authentication. The reply is encrypted in the session key from the TGT. -Though the protocol specification describes the AS and the TGS as separate -servers, they are implemented in practice as different protocol entry points -within a single Kerberos server. - -Once obtained, credentials may be used to verify the identity of the -principals in a transaction, to ensure the integrity of messages exchanged -between them, or to preserve privacy of the messages. The application is -free to choose whatever protection may be necessary. - -To verify the identities of the principals in a transaction, the client -transmits the ticket to the application server. Since the ticket is sent "in -the clear" (parts of it are encrypted, but this encryption doesn't thwart -replay) and might be intercepted and reused by an attacker, additional -information is sent to prove that the message originated with the principal -to whom the ticket was issued. This information (called the authenticator) -is encrypted in the session key, and includes a timestamp. The timestamp -proves that the message was recently generated and is not a replay. -Encrypting the authenticator in the session key proves that it was generated -by a party possessing the session key. Since no one except the requesting -principal and the server know the session key (it is never sent over the -network in the clear) this guarantees the identity of the client. - - - -draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 - -The integrity of the messages exchanged between principals can also be -guaranteed using the session key (passed in the ticket and contained in the -credentials). This approach provides detection of both replay attacks and -message stream modification attacks. It is accomplished by generating and -transmitting a collision-proof checksum (elsewhere called a hash or digest -function) of the client's message, keyed with the session key. Privacy and -integrity of the messages exchanged between principals can be secured by -encrypting the data to be passed using the session key contained in the -ticket or the subsession key found in the authenticator. - -The authentication exchanges mentioned above require read-only access to the -Kerberos database. Sometimes, however, the entries in the database must be -modified, such as when adding new principals or changing a principal's key. -This is done using a protocol between a client and a third Kerberos server, -the Kerberos Administration Server (KADM). There is also a protocol for -maintaining multiple copies of the Kerberos database. Neither of these -protocols are described in this document. - -1.1. Cross-Realm Operation - -The Kerberos protocol is designed to operate across organizational -boundaries. A client in one organization can be authenticated to a server in -another. Each organization wishing to run a Kerberos server establishes its -own 'realm'. The name of the realm in which a client is registered is part -of the client's name, and can be used by the end-service to decide whether -to honor a request. - -By establishing 'inter-realm' keys, the administrators of two realms can -allow a client authenticated in the local realm to prove its identity to -servers in other realms[3]. The exchange of inter-realm keys (a separate key -may be used for each direction) registers the ticket-granting service of -each realm as a principal in the other realm. A client is then able to -obtain a ticket-granting ticket for the remote realm's ticket-granting -service from its local realm. When that ticket-granting ticket is used, the -remote ticket-granting service uses the inter-realm key (which usually -differs from its own normal TGS key) to decrypt the ticket-granting ticket, -and is thus certain that it was issued by the client's own TGS. Tickets -issued by the remote ticket-granting service will indicate to the -end-service that the client was authenticated from another realm. - -A realm is said to communicate with another realm if the two realms share an -inter-realm key, or if the local realm shares an inter-realm key with an -intermediate realm that communicates with the remote realm. An -authentication path is the sequence of intermediate realms that are -transited in communicating from one realm to another. - -Realms are typically organized hierarchically. Each realm shares a key with -its parent and a different key with each child. If an inter-realm key is not -directly shared by two realms, the hierarchical organization allows an -authentication path to be easily constructed. If a hierarchical organization -is not used, it may be necessary to consult a database in order to construct -an authentication path between realms. - -Although realms are typically hierarchical, intermediate realms may be - - -draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 - -bypassed to achieve cross-realm authentication through alternate -authentication paths (these might be established to make communication -between two realms more efficient). It is important for the end-service to -know which realms were transited when deciding how much faith to place in -the authentication process. To facilitate this decision, a field in each -ticket contains the names of the realms that were involved in authenticating -the client. - -The application server is ultimately responsible for accepting or rejecting -authentication and should check the transited field. The application server -may choose to rely on the KDC for the application server's realm to check -the transited field. The application server's KDC will set the -TRANSITED-POLICY-CHECKED flag in this case. The KDC's for intermediate -realms may also check the transited field as they issue -ticket-granting-tickets for other realms, but they are encouraged not to do -so. A client may request that the KDC's not check the transited field by -setting the DISABLE-TRANSITED-CHECK flag. KDC's are encouraged but not -required to honor this flag. - -1.2. Authorization - -As an authentication service, Kerberos provides a means of verifying the -identity of principals on a network. Authentication is usually useful -primarily as a first step in the process of authorization, determining -whether a client may use a service, which objects the client is allowed to -access, and the type of access allowed for each. Kerberos does not, by -itself, provide authorization. Possession of a client ticket for a service -provides only for authentication of the client to that service, and in the -absence of a separate authorization procedure, it should not be considered -by an application as authorizing the use of that service. - -Such separate authorization methods may be implemented as application -specific access control functions and may be based on files such as the -application server, or on separately issued authorization credentials such -as those based on proxies [Neu93] , or on other authorization services. - -Applications should not be modified to accept the issuance of a service -ticket by the Kerberos server (even by an modified Kerberos server) as -granting authority to use the service, since such applications may become -vulnerable to the bypass of this authorization check in an environment if -they interoperate with other KDCs or where other options for application -authentication (e.g. the PKTAPP proposal) are provided. - -1.3. Environmental assumptions - -Kerberos imposes a few assumptions on the environment in which it can -properly function: - - * 'Denial of service' attacks are not solved with Kerberos. There are - places in these protocols where an intruder can prevent an application - from participating in the proper authentication steps. Detection and - solution of such attacks (some of which can appear to be nnot-uncommon - 'normal' failure modes for the system) is usually best left to the - human administrators and users. - - -draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 - - * Principals must keep their secret keys secret. If an intruder somehow - steals a principal's key, it will be able to masquerade as that - principal or impersonate any server to the legitimate principal. - * 'Password guessing' attacks are not solved by Kerberos. If a user - chooses a poor password, it is possible for an attacker to successfully - mount an offline dictionary attack by repeatedly attempting to decrypt, - with successive entries from a dictionary, messages obtained which are - encrypted under a key derived from the user's password. - * Each host on the network must have a clock which is 'loosely - synchronized' to the time of the other hosts; this synchronization is - used to reduce the bookkeeping needs of application servers when they - do replay detection. The degree of "looseness" can be configured on a - per-server basis, but is typically on the order of 5 minutes. If the - clocks are synchronized over the network, the clock synchronization - protocol must itself be secured from network attackers. - * Principal identifiers are not recycled on a short-term basis. A typical - mode of access control will use access control lists (ACLs) to grant - permissions to particular principals. If a stale ACL entry remains for - a deleted principal and the principal identifier is reused, the new - principal will inherit rights specified in the stale ACL entry. By not - re-using principal identifiers, the danger of inadvertent access is - removed. - -1.4. Glossary of terms - -Below is a list of terms used throughout this document. - -Authentication - Verifying the claimed identity of a principal. -Authentication header - A record containing a Ticket and an Authenticator to be presented to a - server as part of the authentication process. -Authentication path - A sequence of intermediate realms transited in the authentication - process when communicating from one realm to another. -Authenticator - A record containing information that can be shown to have been recently - generated using the session key known only by the client and server. -Authorization - The process of determining whether a client may use a service, which - objects the client is allowed to access, and the type of access allowed - for each. -Capability - A token that grants the bearer permission to access an object or - service. In Kerberos, this might be a ticket whose use is restricted by - the contents of the authorization data field, but which lists no - network addresses, together with the session key necessary to use the - ticket. -Ciphertext - The output of an encryption function. Encryption transforms plaintext - into ciphertext. -Client - A process that makes use of a network service on behalf of a user. Note - that in some cases a Server may itself be a client of some other server - - -draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 - - (e.g. a print server may be a client of a file server). -Credentials - A ticket plus the secret session key necessary to successfully use that - ticket in an authentication exchange. -KDC - Key Distribution Center, a network service that supplies tickets and - temporary session keys; or an instance of that service or the host on - which it runs. The KDC services both initial ticket and ticket-granting - ticket requests. The initial ticket portion is sometimes referred to as - the Authentication Server (or service). The ticket-granting ticket - portion is sometimes referred to as the ticket-granting server (or - service). -Kerberos - Aside from the 3-headed dog guarding Hades, the name given to Project - Athena's authentication service, the protocol used by that service, or - the code used to implement the authentication service. -Plaintext - The input to an encryption function or the output of a decryption - function. Decryption transforms ciphertext into plaintext. -Principal - A uniquely named client or server instance that participates in a - network communication. -Principal identifier - The name used to uniquely identify each different principal. -Seal - To encipher a record containing several fields in such a way that the - fields cannot be individually replaced without either knowledge of the - encryption key or leaving evidence of tampering. -Secret key - An encryption key shared by a principal and the KDC, distributed - outside the bounds of the system, with a long lifetime. In the case of - a human user's principal, the secret key is derived from a password. -Server - A particular Principal which provides a resource to network clients. - The server is sometimes refered to as the Application Server. -Service - A resource provided to network clients; often provided by more than one - server (for example, remote file service). -Session key - A temporary encryption key used between two principals, with a lifetime - limited to the duration of a single login "session". -Sub-session key - A temporary encryption key used between two principals, selected and - exchanged by the principals using the session key, and with a lifetime - limited to the duration of a single association. -Ticket - A record that helps a client authenticate itself to a server; it - contains the client's identity, a session key, a timestamp, and other - information, all sealed using the server's secret key. It only serves - to authenticate a client when presented along with a fresh - Authenticator. - -2. Ticket flag uses and requests - - - -draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 - -Each Kerberos ticket contains a set of flags which are used to indicate -various attributes of that ticket. Most flags may be requested by a client -when the ticket is obtained; some are automatically turned on and off by a -Kerberos server as required. The following sections explain what the various -flags mean, and gives examples of reasons to use such a flag. - -2.1. Initial and pre-authenticated tickets - -The INITIAL flag indicates that a ticket was issued using the AS protocol -and not issued based on a ticket-granting ticket. Application servers that -want to require the demonstrated knowledge of a client's secret key (e.g. a -password-changing program) can insist that this flag be set in any tickets -they accept, and thus be assured that the client's key was recently -presented to the application client. - -The PRE-AUTHENT and HW-AUTHENT flags provide addition information about the -initial authentication, regardless of whether the current ticket was issued -directly (in which case INITIAL will also be set) or issued on the basis of -a ticket-granting ticket (in which case the INITIAL flag is clear, but the -PRE-AUTHENT and HW-AUTHENT flags are carried forward from the -ticket-granting ticket). - -2.2. Invalid tickets - -The INVALID flag indicates that a ticket is invalid. Application servers -must reject tickets which have this flag set. A postdated ticket will -usually be issued in this form. Invalid tickets must be validated by the KDC -before use, by presenting them to the KDC in a TGS request with the VALIDATE -option specified. The KDC will only validate tickets after their starttime -has passed. The validation is required so that postdated tickets which have -been stolen before their starttime can be rendered permanently invalid -(through a hot-list mechanism) (see section 3.3.3.1). - -2.3. Renewable tickets - -Applications may desire to hold tickets which can be valid for long periods -of time. However, this can expose their credentials to potential theft for -equally long periods, and those stolen credentials would be valid until the -expiration time of the ticket(s). Simply using short-lived tickets and -obtaining new ones periodically would require the client to have long-term -access to its secret key, an even greater risk. Renewable tickets can be -used to mitigate the consequences of theft. Renewable tickets have two -"expiration times": the first is when the current instance of the ticket -expires, and the second is the latest permissible value for an individual -expiration time. An application client must periodically (i.e. before it -expires) present a renewable ticket to the KDC, with the RENEW option set in -the KDC request. The KDC will issue a new ticket with a new session key and -a later expiration time. All other fields of the ticket are left unmodified -by the renewal process. When the latest permissible expiration time arrives, -the ticket expires permanently. At each renewal, the KDC may consult a -hot-list to determine if the ticket had been reported stolen since its last -renewal; it will refuse to renew such stolen tickets, and thus the usable -lifetime of stolen tickets is reduced. - - - -draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 - -The RENEWABLE flag in a ticket is normally only interpreted by the -ticket-granting service (discussed below in section 3.3). It can usually be -ignored by application servers. However, some particularly careful -application servers may wish to disallow renewable tickets. - -If a renewable ticket is not renewed by its expiration time, the KDC will -not renew the ticket. The RENEWABLE flag is reset by default, but a client -may request it be set by setting the RENEWABLE option in the KRB_AS_REQ -message. If it is set, then the renew-till field in the ticket contains the -time after which the ticket may not be renewed. - -2.4. Postdated tickets - -Applications may occasionally need to obtain tickets for use much later, -e.g. a batch submission system would need tickets to be valid at the time -the batch job is serviced. However, it is dangerous to hold valid tickets in -a batch queue, since they will be on-line longer and more prone to theft. -Postdated tickets provide a way to obtain these tickets from the KDC at job -submission time, but to leave them "dormant" until they are activated and -validated by a further request of the KDC. If a ticket theft were reported -in the interim, the KDC would refuse to validate the ticket, and the thief -would be foiled. - -The MAY-POSTDATE flag in a ticket is normally only interpreted by the -ticket-granting service. It can be ignored by application servers. This flag -must be set in a ticket-granting ticket in order to issue a postdated ticket -based on the presented ticket. It is reset by default; it may be requested -by a client by setting the ALLOW-POSTDATE option in the KRB_AS_REQ message. -This flag does not allow a client to obtain a postdated ticket-granting -ticket; postdated ticket-granting tickets can only by obtained by requesting -the postdating in the KRB_AS_REQ message. The life (endtime-starttime) of a -postdated ticket will be the remaining life of the ticket-granting ticket at -the time of the request, unless the RENEWABLE option is also set, in which -case it can be the full life (endtime-starttime) of the ticket-granting -ticket. The KDC may limit how far in the future a ticket may be postdated. - -The POSTDATED flag indicates that a ticket has been postdated. The -application server can check the authtime field in the ticket to see when -the original authentication occurred. Some services may choose to reject -postdated tickets, or they may only accept them within a certain period -after the original authentication. When the KDC issues a POSTDATED ticket, -it will also be marked as INVALID, so that the application client must -present the ticket to the KDC to be validated before use. - -2.5. Proxiable and proxy tickets - -At times it may be necessary for a principal to allow a service to perform -an operation on its behalf. The service must be able to take on the identity -of the client, but only for a particular purpose. A principal can allow a -service to take on the principal's identity for a particular purpose by -granting it a proxy. - -The process of granting a proxy using the proxy and proxiable flags is used -to provide credentials for use with specific services. Though conceptually - - -draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 - -also a proxy, user's wishing to delegate their identity for ANY purpose must -use the ticket forwarding mechanism described in the next section to forward -a ticket granting ticket. - -The PROXIABLE flag in a ticket is normally only interpreted by the -ticket-granting service. It can be ignored by application servers. When set, -this flag tells the ticket-granting server that it is OK to issue a new -ticket (but not a ticket-granting ticket) with a different network address -based on this ticket. This flag is set if requested by the client on initial -authentication. By default, the client will request that it be set when -requesting a ticket granting ticket, and reset when requesting any other -ticket. - -This flag allows a client to pass a proxy to a server to perform a remote -request on its behalf, e.g. a print service client can give the print server -a proxy to access the client's files on a particular file server in order to -satisfy a print request. - -In order to complicate the use of stolen credentials, Kerberos tickets are -usually valid from only those network addresses specifically included in the -ticket[4]. When granting a proxy, the client must specify the new network -address from which the proxy is to be used, or indicate that the proxy is to -be issued for use from any address. - -The PROXY flag is set in a ticket by the TGS when it issues a proxy ticket. -Application servers may check this flag and at their option they may require -additional authentication from the agent presenting the proxy in order to -provide an audit trail. - -2.6. Forwardable tickets - -Authentication forwarding is an instance of a proxy where the service is -granted complete use of the client's identity. An example where it might be -used is when a user logs in to a remote system and wants authentication to -work from that system as if the login were local. - -The FORWARDABLE flag in a ticket is normally only interpreted by the -ticket-granting service. It can be ignored by application servers. The -FORWARDABLE flag has an interpretation similar to that of the PROXIABLE -flag, except ticket-granting tickets may also be issued with different -network addresses. This flag is reset by default, but users may request that -it be set by setting the FORWARDABLE option in the AS request when they -request their initial ticket- granting ticket. - -This flag allows for authentication forwarding without requiring the user to -enter a password again. If the flag is not set, then authentication -forwarding is not permitted, but the same result can still be achieved if -the user engages in the AS exchange specifying the requested network -addresses and supplies a password. - -The FORWARDED flag is set by the TGS when a client presents a ticket with -the FORWARDABLE flag set and requests a forwarded ticket by specifying the -FORWARDED KDC option and supplying a set of addresses for the new ticket. It -is also set in all tickets issued based on tickets with the FORWARDED flag - - -draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 - -set. Application servers may choose to process FORWARDED tickets differently -than non-FORWARDED tickets. - -2.7. Other KDC options - -There are two additional options which may be set in a client's request of -the KDC. The RENEWABLE-OK option indicates that the client will accept a -renewable ticket if a ticket with the requested life cannot otherwise be -provided. If a ticket with the requested life cannot be provided, then the -KDC may issue a renewable ticket with a renew-till equal to the the -requested endtime. The value of the renew-till field may still be adjusted -by site-determined limits or limits imposed by the individual principal or -server. - -The ENC-TKT-IN-SKEY option is honored only by the ticket-granting service. -It indicates that the ticket to be issued for the end server is to be -encrypted in the session key from the a additional second ticket-granting -ticket provided with the request. See section 3.3.3 for specific details. - -3. Message Exchanges - -The following sections describe the interactions between network clients and -servers and the messages involved in those exchanges. - -3.1. The Authentication Service Exchange - - Summary - Message direction Message type Section - 1. Client to Kerberos KRB_AS_REQ 5.4.1 - 2. Kerberos to client KRB_AS_REP or 5.4.2 - KRB_ERROR 5.9.1 - -The Authentication Service (AS) Exchange between the client and the Kerberos -Authentication Server is initiated by a client when it wishes to obtain -authentication credentials for a given server but currently holds no -credentials. In its basic form, the client's secret key is used for -encryption and decryption. This exchange is typically used at the initiation -of a login session to obtain credentials for a Ticket-Granting Server which -will subsequently be used to obtain credentials for other servers (see -section 3.3) without requiring further use of the client's secret key. This -exchange is also used to request credentials for services which must not be -mediated through the Ticket-Granting Service, but rather require a -principal's secret key, such as the password-changing service[5]. This -exchange does not by itself provide any assurance of the the identity of the -user[6]. - -The exchange consists of two messages: KRB_AS_REQ from the client to -Kerberos, and KRB_AS_REP or KRB_ERROR in reply. The formats for these -messages are described in sections 5.4.1, 5.4.2, and 5.9.1. - -In the request, the client sends (in cleartext) its own identity and the -identity of the server for which it is requesting credentials. The response, -KRB_AS_REP, contains a ticket for the client to present to the server, and a -session key that will be shared by the client and the server. The session - - -draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 - -key and additional information are encrypted in the client's secret key. The -KRB_AS_REP message contains information which can be used to detect replays, -and to associate it with the message to which it replies. Various errors can -occur; these are indicated by an error response (KRB_ERROR) instead of the -KRB_AS_REP response. The error message is not encrypted. The KRB_ERROR -message contains information which can be used to associate it with the -message to which it replies. The lack of encryption in the KRB_ERROR message -precludes the ability to detect replays, fabrications, or modifications of -such messages. - -Without preautentication, the authentication server does not know whether -the client is actually the principal named in the request. It simply sends a -reply without knowing or caring whether they are the same. This is -acceptable because nobody but the principal whose identity was given in the -request will be able to use the reply. Its critical information is encrypted -in that principal's key. The initial request supports an optional field that -can be used to pass additional information that might be needed for the -initial exchange. This field may be used for preauthentication as described -in section [hl<>]. - -3.1.1. Generation of KRB_AS_REQ message - -The client may specify a number of options in the initial request. Among -these options are whether pre-authentication is to be performed; whether the -requested ticket is to be renewable, proxiable, or forwardable; whether it -should be postdated or allow postdating of derivative tickets; and whether a -renewable ticket will be accepted in lieu of a non-renewable ticket if the -requested ticket expiration date cannot be satisfied by a non-renewable -ticket (due to configuration constraints; see section 4). See section A.1 -for pseudocode. - -The client prepares the KRB_AS_REQ message and sends it to the KDC. - -3.1.2. Receipt of KRB_AS_REQ message - -If all goes well, processing the KRB_AS_REQ message will result in the -creation of a ticket for the client to present to the server. The format for -the ticket is described in section 5.3.1. The contents of the ticket are -determined as follows. - -3.1.3. Generation of KRB_AS_REP message - -The authentication server looks up the client and server principals named in -the KRB_AS_REQ in its database, extracting their respective keys. If -required, the server pre-authenticates the request, and if the -pre-authentication check fails, an error message with the code -KDC_ERR_PREAUTH_FAILED is returned. If the server cannot accommodate the -requested encryption type, an error message with code KDC_ERR_ETYPE_NOSUPP -is returned. Otherwise it generates a 'random' session key[7]. - -If there are multiple encryption keys registered for a client in the -Kerberos database (or if the key registered supports multiple encryption -types; e.g. DES-CBC-CRC and DES-CBC-MD5), then the etype field from the AS -request is used by the KDC to select the encryption method to be used for - - -draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 - -encrypting the response to the client. If there is more than one supported, -strong encryption type in the etype list, the first valid etype for which an -encryption key is available is used. The encryption method used to respond -to a TGS request is taken from the keytype of the session key found in the -ticket granting ticket. - -When the etype field is present in a KDC request, whether an AS or TGS -request, the KDC will attempt to assign the type of the random session key -from the list of methods in the etype field. The KDC will select the -appropriate type using the list of methods provided together with -information from the Kerberos database indicating acceptable encryption -methods for the application server. The KDC will not issue tickets with a -weak session key encryption type. - -If the requested start time is absent, indicates a time in the past, or is -within the window of acceptable clock skew for the KDC and the POSTDATE -option has not been specified, then the start time of the ticket is set to -the authentication server's current time. If it indicates a time in the -future beyond the acceptable clock skew, but the POSTDATED option has not -been specified then the error KDC_ERR_CANNOT_POSTDATE is returned. Otherwise -the requested start time is checked against the policy of the local realm -(the administrator might decide to prohibit certain types or ranges of -postdated tickets), and if acceptable, the ticket's start time is set as -requested and the INVALID flag is set in the new ticket. The postdated -ticket must be validated before use by presenting it to the KDC after the -start time has been reached. - -The expiration time of the ticket will be set to the minimum of the -following: - - * The expiration time (endtime) requested in the KRB_AS_REQ message. - * The ticket's start time plus the maximum allowable lifetime associated - with the client principal (the authentication server's database - includes a maximum ticket lifetime field in each principal's record; - see section 4). - * The ticket's start time plus the maximum allowable lifetime associated - with the server principal. - * The ticket's start time plus the maximum lifetime set by the policy of - the local realm. - -If the requested expiration time minus the start time (as determined above) -is less than a site-determined minimum lifetime, an error message with code -KDC_ERR_NEVER_VALID is returned. If the requested expiration time for the -ticket exceeds what was determined as above, and if the 'RENEWABLE-OK' -option was requested, then the 'RENEWABLE' flag is set in the new ticket, -and the renew-till value is set as if the 'RENEWABLE' option were requested -(the field and option names are described fully in section 5.4.1). - -If the RENEWABLE option has been requested or if the RENEWABLE-OK option has -been set and a renewable ticket is to be issued, then the renew-till field -is set to the minimum of: - - * Its requested value. - * The start time of the ticket plus the minimum of the two maximum - - -draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 - - renewable lifetimes associated with the principals' database entries. - * The start time of the ticket plus the maximum renewable lifetime set by - the policy of the local realm. - -The flags field of the new ticket will have the following options set if -they have been requested and if the policy of the local realm allows: -FORWARDABLE, MAY-POSTDATE, POSTDATED, PROXIABLE, RENEWABLE. If the new -ticket is post-dated (the start time is in the future), its INVALID flag -will also be set. - -If all of the above succeed, the server formats a KRB_AS_REP message (see -section 5.4.2), copying the addresses in the request into the caddr of the -response, placing any required pre-authentication data into the padata of -the response, and encrypts the ciphertext part in the client's key using the -requested encryption method, and sends it to the client. See section A.2 for -pseudocode. - -3.1.4. Generation of KRB_ERROR message - -Several errors can occur, and the Authentication Server responds by -returning an error message, KRB_ERROR, to the client, with the error-code -and e-text fields set to appropriate values. The error message contents and -details are described in Section 5.9.1. - -3.1.5. Receipt of KRB_AS_REP message - -If the reply message type is KRB_AS_REP, then the client verifies that the -cname and crealm fields in the cleartext portion of the reply match what it -requested. If any padata fields are present, they may be used to derive the -proper secret key to decrypt the message. The client decrypts the encrypted -part of the response using its secret key, verifies that the nonce in the -encrypted part matches the nonce it supplied in its request (to detect -replays). It also verifies that the sname and srealm in the response match -those in the request (or are otherwise expected values), and that the host -address field is also correct. It then stores the ticket, session key, start -and expiration times, and other information for later use. The -key-expiration field from the encrypted part of the response may be checked -to notify the user of impending key expiration (the client program could -then suggest remedial action, such as a password change). See section A.3 -for pseudocode. - -Proper decryption of the KRB_AS_REP message is not sufficient to verify the -identity of the user; the user and an attacker could cooperate to generate a -KRB_AS_REP format message which decrypts properly but is not from the proper -KDC. If the host wishes to verify the identity of the user, it must require -the user to present application credentials which can be verified using a -securely-stored secret key for the host. If those credentials can be -verified, then the identity of the user can be assured. - -3.1.6. Receipt of KRB_ERROR message - -If the reply message type is KRB_ERROR, then the client interprets it as an -error and performs whatever application-specific tasks are necessary to -recover. - - -draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 - - -3.2. The Client/Server Authentication Exchange - - Summary -Message direction Message type Section -Client to Application server KRB_AP_REQ 5.5.1 -[optional] Application server to client KRB_AP_REP or 5.5.2 - KRB_ERROR 5.9.1 - -The client/server authentication (CS) exchange is used by network -applications to authenticate the client to the server and vice versa. The -client must have already acquired credentials for the server using the AS or -TGS exchange. - -3.2.1. The KRB_AP_REQ message - -The KRB_AP_REQ contains authentication information which should be part of -the first message in an authenticated transaction. It contains a ticket, an -authenticator, and some additional bookkeeping information (see section -5.5.1 for the exact format). The ticket by itself is insufficient to -authenticate a client, since tickets are passed across the network in -cleartext[DS90], so the authenticator is used to prevent invalid replay of -tickets by proving to the server that the client knows the session key of -the ticket and thus is entitled to use the ticket. The KRB_AP_REQ message is -referred to elsewhere as the 'authentication header.' - -3.2.2. Generation of a KRB_AP_REQ message - -When a client wishes to initiate authentication to a server, it obtains -(either through a credentials cache, the AS exchange, or the TGS exchange) a -ticket and session key for the desired service. The client may re-use any -tickets it holds until they expire. To use a ticket the client constructs a -new Authenticator from the the system time, its name, and optionally an -application specific checksum, an initial sequence number to be used in -KRB_SAFE or KRB_PRIV messages, and/or a session subkey to be used in -negotiations for a session key unique to this particular session. -Authenticators may not be re-used and will be rejected if replayed to a -server[LGDSR87]. If a sequence number is to be included, it should be -randomly chosen so that even after many messages have been exchanged it is -not likely to collide with other sequence numbers in use. - -The client may indicate a requirement of mutual authentication or the use of -a session-key based ticket by setting the appropriate flag(s) in the -ap-options field of the message. - -The Authenticator is encrypted in the session key and combined with the -ticket to form the KRB_AP_REQ message which is then sent to the end server -along with any additional application-specific information. See section A.9 -for pseudocode. - -3.2.3. Receipt of KRB_AP_REQ message - -Authentication is based on the server's current time of day (clocks must be -loosely synchronized), the authenticator, and the ticket. Several errors are - - -draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 - -possible. If an error occurs, the server is expected to reply to the client -with a KRB_ERROR message. This message may be encapsulated in the -application protocol if its 'raw' form is not acceptable to the protocol. -The format of error messages is described in section 5.9.1. - -The algorithm for verifying authentication information is as follows. If the -message type is not KRB_AP_REQ, the server returns the KRB_AP_ERR_MSG_TYPE -error. If the key version indicated by the Ticket in the KRB_AP_REQ is not -one the server can use (e.g., it indicates an old key, and the server no -longer possesses a copy of the old key), the KRB_AP_ERR_BADKEYVER error is -returned. If the USE-SESSION-KEY flag is set in the ap-options field, it -indicates to the server that the ticket is encrypted in the session key from -the server's ticket-granting ticket rather than its secret key[10]. Since it -is possible for the server to be registered in multiple realms, with -different keys in each, the srealm field in the unencrypted portion of the -ticket in the KRB_AP_REQ is used to specify which secret key the server -should use to decrypt that ticket. The KRB_AP_ERR_NOKEY error code is -returned if the server doesn't have the proper key to decipher the ticket. - -The ticket is decrypted using the version of the server's key specified by -the ticket. If the decryption routines detect a modification of the ticket -(each encryption system must provide safeguards to detect modified -ciphertext; see section 6), the KRB_AP_ERR_BAD_INTEGRITY error is returned -(chances are good that different keys were used to encrypt and decrypt). - -The authenticator is decrypted using the session key extracted from the -decrypted ticket. If decryption shows it to have been modified, the -KRB_AP_ERR_BAD_INTEGRITY error is returned. The name and realm of the client -from the ticket are compared against the same fields in the authenticator. -If they don't match, the KRB_AP_ERR_BADMATCH error is returned (they might -not match, for example, if the wrong session key was used to encrypt the -authenticator). The addresses in the ticket (if any) are then searched for -an address matching the operating-system reported address of the client. If -no match is found or the server insists on ticket addresses but none are -present in the ticket, the KRB_AP_ERR_BADADDR error is returned. - -If the local (server) time and the client time in the authenticator differ -by more than the allowable clock skew (e.g., 5 minutes), the KRB_AP_ERR_SKEW -error is returned. If the server name, along with the client name, time and -microsecond fields from the Authenticator match any recently-seen such -tuples, the KRB_AP_ERR_REPEAT error is returned[11]. The server must -remember any authenticator presented within the allowable clock skew, so -that a replay attempt is guaranteed to fail. If a server loses track of any -authenticator presented within the allowable clock skew, it must reject all -requests until the clock skew interval has passed. This assures that any -lost or re-played authenticators will fall outside the allowable clock skew -and can no longer be successfully replayed (If this is not done, an attacker -could conceivably record the ticket and authenticator sent over the network -to a server, then disable the client's host, pose as the disabled host, and -replay the ticket and authenticator to subvert the authentication.). If a -sequence number is provided in the authenticator, the server saves it for -later use in processing KRB_SAFE and/or KRB_PRIV messages. If a subkey is -present, the server either saves it for later use or uses it to help -generate its own choice for a subkey to be returned in a KRB_AP_REP message. - - -draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 - - -The server computes the age of the ticket: local (server) time minus the -start time inside the Ticket. If the start time is later than the current -time by more than the allowable clock skew or if the INVALID flag is set in -the ticket, the KRB_AP_ERR_TKT_NYV error is returned. Otherwise, if the -current time is later than end time by more than the allowable clock skew, -the KRB_AP_ERR_TKT_EXPIRED error is returned. - -If all these checks succeed without an error, the server is assured that the -client possesses the credentials of the principal named in the ticket and -thus, the client has been authenticated to the server. See section A.10 for -pseudocode. - -Passing these checks provides only authentication of the named principal; it -does not imply authorization to use the named service. Applications must -make a separate authorization decisions based upon the authenticated name of -the user, the requested operation, local acces control information such as -that contained in a .k5login or .k5users file, and possibly a separate -distributed authorization service. - -3.2.4. Generation of a KRB_AP_REP message - -Typically, a client's request will include both the authentication -information and its initial request in the same message, and the server need -not explicitly reply to the KRB_AP_REQ. However, if mutual authentication -(not only authenticating the client to the server, but also the server to -the client) is being performed, the KRB_AP_REQ message will have -MUTUAL-REQUIRED set in its ap-options field, and a KRB_AP_REP message is -required in response. As with the error message, this message may be -encapsulated in the application protocol if its "raw" form is not acceptable -to the application's protocol. The timestamp and microsecond field used in -the reply must be the client's timestamp and microsecond field (as provided -in the authenticator)[12]. If a sequence number is to be included, it should -be randomly chosen as described above for the authenticator. A subkey may be -included if the server desires to negotiate a different subkey. The -KRB_AP_REP message is encrypted in the session key extracted from the -ticket. See section A.11 for pseudocode. - -3.2.5. Receipt of KRB_AP_REP message - -If a KRB_AP_REP message is returned, the client uses the session key from -the credentials obtained for the server[13] to decrypt the message, and -verifies that the timestamp and microsecond fields match those in the -Authenticator it sent to the server. If they match, then the client is -assured that the server is genuine. The sequence number and subkey (if -present) are retained for later use. See section A.12 for pseudocode. - -3.2.6. Using the encryption key - -After the KRB_AP_REQ/KRB_AP_REP exchange has occurred, the client and server -share an encryption key which can be used by the application. The 'true -session key' to be used for KRB_PRIV, KRB_SAFE, or other -application-specific uses may be chosen by the application based on the -subkeys in the KRB_AP_REP message and the authenticator[14]. In some cases, - - -draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 - -the use of this session key will be implicit in the protocol; in others the -method of use must be chosen from several alternatives. We leave the -protocol negotiations of how to use the key (e.g. selecting an encryption or -checksum type) to the application programmer; the Kerberos protocol does not -constrain the implementation options, but an example of how this might be -done follows. - -One way that an application may choose to negotiate a key to be used for -subequent integrity and privacy protection is for the client to propose a -key in the subkey field of the authenticator. The server can then choose a -key using the proposed key from the client as input, returning the new -subkey in the subkey field of the application reply. This key could then be -used for subsequent communication. To make this example more concrete, if -the encryption method in use required a 56 bit key, and for whatever reason, -one of the parties was prevented from using a key with more than 40 unknown -bits, this method would allow the the party which is prevented from using -more than 40 bits to either propose (if the client) an initial key with a -known quantity for 16 of those bits, or to mask 16 of the bits (if the -server) with the known quantity. The application implementor is warned, -however, that this is only an example, and that an analysis of the -particular crytosystem to be used, and the reasons for limiting the key -length, must be made before deciding whether it is acceptable to mask bits -of the key. - -With both the one-way and mutual authentication exchanges, the peers should -take care not to send sensitive information to each other without proper -assurances. In particular, applications that require privacy or integrity -should use the KRB_AP_REP response from the server to client to assure both -client and server of their peer's identity. If an application protocol -requires privacy of its messages, it can use the KRB_PRIV message (section -3.5). The KRB_SAFE message (section 3.4) can be used to assure integrity. - -3.3. The Ticket-Granting Service (TGS) Exchange - - Summary - Message direction Message type Section - 1. Client to Kerberos KRB_TGS_REQ 5.4.1 - 2. Kerberos to client KRB_TGS_REP or 5.4.2 - KRB_ERROR 5.9.1 - -The TGS exchange between a client and the Kerberos Ticket-Granting Server is -initiated by a client when it wishes to obtain authentication credentials -for a given server (which might be registered in a remote realm), when it -wishes to renew or validate an existing ticket, or when it wishes to obtain -a proxy ticket. In the first case, the client must already have acquired a -ticket for the Ticket-Granting Service using the AS exchange (the -ticket-granting ticket is usually obtained when a client initially -authenticates to the system, such as when a user logs in). The message -format for the TGS exchange is almost identical to that for the AS exchange. -The primary difference is that encryption and decryption in the TGS exchange -does not take place under the client's key. Instead, the session key from -the ticket-granting ticket or renewable ticket, or sub-session key from an -Authenticator is used. As is the case for all application servers, expired -tickets are not accepted by the TGS, so once a renewable or ticket-granting - - -draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 - -ticket expires, the client must use a separate exchange to obtain valid -tickets. - -The TGS exchange consists of two messages: A request (KRB_TGS_REQ) from the -client to the Kerberos Ticket-Granting Server, and a reply (KRB_TGS_REP or -KRB_ERROR). The KRB_TGS_REQ message includes information authenticating the -client plus a request for credentials. The authentication information -consists of the authentication header (KRB_AP_REQ) which includes the -client's previously obtained ticket-granting, renewable, or invalid ticket. -In the ticket-granting ticket and proxy cases, the request may include one -or more of: a list of network addresses, a collection of typed authorization -data to be sealed in the ticket for authorization use by the application -server, or additional tickets (the use of which are described later). The -TGS reply (KRB_TGS_REP) contains the requested credentials, encrypted in the -session key from the ticket-granting ticket or renewable ticket, or if -present, in the sub-session key from the Authenticator (part of the -authentication header). The KRB_ERROR message contains an error code and -text explaining what went wrong. The KRB_ERROR message is not encrypted. The -KRB_TGS_REP message contains information which can be used to detect -replays, and to associate it with the message to which it replies. The -KRB_ERROR message also contains information which can be used to associate -it with the message to which it replies, but the lack of encryption in the -KRB_ERROR message precludes the ability to detect replays or fabrications of -such messages. - -3.3.1. Generation of KRB_TGS_REQ message - -Before sending a request to the ticket-granting service, the client must -determine in which realm the application server is registered[15]. If the -client does not already possess a ticket-granting ticket for the appropriate -realm, then one must be obtained. This is first attempted by requesting a -ticket-granting ticket for the destination realm from a Kerberos server for -which the client does posess a ticket-granting ticket (using the KRB_TGS_REQ -message recursively). The Kerberos server may return a TGT for the desired -realm in which case one can proceed. Alternatively, the Kerberos server may -return a TGT for a realm which is 'closer' to the desired realm (further -along the standard hierarchical path), in which case this step must be -repeated with a Kerberos server in the realm specified in the returned TGT. -If neither are returned, then the request must be retried with a Kerberos -server for a realm higher in the hierarchy. This request will itself require -a ticket-granting ticket for the higher realm which must be obtained by -recursively applying these directions. - -Once the client obtains a ticket-granting ticket for the appropriate realm, -it determines which Kerberos servers serve that realm, and contacts one. The -list might be obtained through a configuration file or network service or it -may be generated from the name of the realm; as long as the secret keys -exchanged by realms are kept secret, only denial of service results from -using a false Kerberos server. - -As in the AS exchange, the client may specify a number of options in the -KRB_TGS_REQ message. The client prepares the KRB_TGS_REQ message, providing -an authentication header as an element of the padata field, and including -the same fields as used in the KRB_AS_REQ message along with several - - -draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 - -optional fields: the enc-authorization-data field for application server use -and additional tickets required by some options. - -In preparing the authentication header, the client can select a sub-session -key under which the response from the Kerberos server will be encrypted[16]. -If the sub-session key is not specified, the session key from the -ticket-granting ticket will be used. If the enc-authorization-data is -present, it must be encrypted in the sub-session key, if present, from the -authenticator portion of the authentication header, or if not present, using -the session key from the ticket-granting ticket. - -Once prepared, the message is sent to a Kerberos server for the destination -realm. See section A.5 for pseudocode. - -3.3.2. Receipt of KRB_TGS_REQ message - -The KRB_TGS_REQ message is processed in a manner similar to the KRB_AS_REQ -message, but there are many additional checks to be performed. First, the -Kerberos server must determine which server the accompanying ticket is for -and it must select the appropriate key to decrypt it. For a normal -KRB_TGS_REQ message, it will be for the ticket granting service, and the -TGS's key will be used. If the TGT was issued by another realm, then the -appropriate inter-realm key must be used. If the accompanying ticket is not -a ticket granting ticket for the current realm, but is for an application -server in the current realm, the RENEW, VALIDATE, or PROXY options are -specified in the request, and the server for which a ticket is requested is -the server named in the accompanying ticket, then the KDC will decrypt the -ticket in the authentication header using the key of the server for which it -was issued. If no ticket can be found in the padata field, the -KDC_ERR_PADATA_TYPE_NOSUPP error is returned. - -Once the accompanying ticket has been decrypted, the user-supplied checksum -in the Authenticator must be verified against the contents of the request, -and the message rejected if the checksums do not match (with an error code -of KRB_AP_ERR_MODIFIED) or if the checksum is not keyed or not -collision-proof (with an error code of KRB_AP_ERR_INAPP_CKSUM). If the -checksum type is not supported, the KDC_ERR_SUMTYPE_NOSUPP error is -returned. If the authorization-data are present, they are decrypted using -the sub-session key from the Authenticator. - -If any of the decryptions indicate failed integrity checks, the -KRB_AP_ERR_BAD_INTEGRITY error is returned. - -3.3.3. Generation of KRB_TGS_REP message - -The KRB_TGS_REP message shares its format with the KRB_AS_REP (KRB_KDC_REP), -but with its type field set to KRB_TGS_REP. The detailed specification is in -section 5.4.2. - -The response will include a ticket for the requested server. The Kerberos -database is queried to retrieve the record for the requested server -(including the key with which the ticket will be encrypted). If the request -is for a ticket granting ticket for a remote realm, and if no key is shared -with the requested realm, then the Kerberos server will select the realm - - -draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 - -"closest" to the requested realm with which it does share a key, and use -that realm instead. This is the only case where the response from the KDC -will be for a different server than that requested by the client. - -By default, the address field, the client's name and realm, the list of -transited realms, the time of initial authentication, the expiration time, -and the authorization data of the newly-issued ticket will be copied from -the ticket-granting ticket (TGT) or renewable ticket. If the transited field -needs to be updated, but the transited type is not supported, the -KDC_ERR_TRTYPE_NOSUPP error is returned. - -If the request specifies an endtime, then the endtime of the new ticket is -set to the minimum of (a) that request, (b) the endtime from the TGT, and -(c) the starttime of the TGT plus the minimum of the maximum life for the -application server and the maximum life for the local realm (the maximum -life for the requesting principal was already applied when the TGT was -issued). If the new ticket is to be a renewal, then the endtime above is -replaced by the minimum of (a) the value of the renew_till field of the -ticket and (b) the starttime for the new ticket plus the life -(endtime-starttime) of the old ticket. - -If the FORWARDED option has been requested, then the resulting ticket will -contain the addresses specified by the client. This option will only be -honored if the FORWARDABLE flag is set in the TGT. The PROXY option is -similar; the resulting ticket will contain the addresses specified by the -client. It will be honored only if the PROXIABLE flag in the TGT is set. The -PROXY option will not be honored on requests for additional ticket-granting -tickets. - -If the requested start time is absent, indicates a time in the past, or is -within the window of acceptable clock skew for the KDC and the POSTDATE -option has not been specified, then the start time of the ticket is set to -the authentication server's current time. If it indicates a time in the -future beyond the acceptable clock skew, but the POSTDATED option has not -been specified or the MAY-POSTDATE flag is not set in the TGT, then the -error KDC_ERR_CANNOT_POSTDATE is returned. Otherwise, if the ticket-granting -ticket has the MAY-POSTDATE flag set, then the resulting ticket will be -postdated and the requested starttime is checked against the policy of the -local realm. If acceptable, the ticket's start time is set as requested, and -the INVALID flag is set. The postdated ticket must be validated before use -by presenting it to the KDC after the starttime has been reached. However, -in no case may the starttime, endtime, or renew-till time of a newly-issued -postdated ticket extend beyond the renew-till time of the ticket-granting -ticket. - -If the ENC-TKT-IN-SKEY option has been specified and an additional ticket -has been included in the request, the KDC will decrypt the additional ticket -using the key for the server to which the additional ticket was issued and -verify that it is a ticket-granting ticket. If the name of the requested -server is missing from the request, the name of the client in the additional -ticket will be used. Otherwise the name of the requested server will be -compared to the name of the client in the additional ticket and if -different, the request will be rejected. If the request succeeds, the -session key from the additional ticket will be used to encrypt the new - - -draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 - -ticket that is issued instead of using the key of the server for which the -new ticket will be used[17]. - -If the name of the server in the ticket that is presented to the KDC as part -of the authentication header is not that of the ticket-granting server -itself, the server is registered in the realm of the KDC, and the RENEW -option is requested, then the KDC will verify that the RENEWABLE flag is set -in the ticket, that the INVALID flag is not set in the ticket, and that the -renew_till time is still in the future. If the VALIDATE option is rqeuested, -the KDC will check that the starttime has passed and the INVALID flag is -set. If the PROXY option is requested, then the KDC will check that the -PROXIABLE flag is set in the ticket. If the tests succeed, and the ticket -passes the hotlist check described in the next paragraph, the KDC will issue -the appropriate new ticket. - -3.3.3.1. Checking for revoked tickets - -Whenever a request is made to the ticket-granting server, the presented -ticket(s) is(are) checked against a hot-list of tickets which have been -canceled. This hot-list might be implemented by storing a range of issue -timestamps for 'suspect tickets'; if a presented ticket had an authtime in -that range, it would be rejected. In this way, a stolen ticket-granting -ticket or renewable ticket cannot be used to gain additional tickets -(renewals or otherwise) once the theft has been reported. Any normal ticket -obtained before it was reported stolen will still be valid (because they -require no interaction with the KDC), but only until their normal expiration -time. - -The ciphertext part of the response in the KRB_TGS_REP message is encrypted -in the sub-session key from the Authenticator, if present, or the session -key key from the ticket-granting ticket. It is not encrypted using the -client's secret key. Furthermore, the client's key's expiration date and the -key version number fields are left out since these values are stored along -with the client's database record, and that record is not needed to satisfy -a request based on a ticket-granting ticket. See section A.6 for pseudocode. - -3.3.3.2. Encoding the transited field - -If the identity of the server in the TGT that is presented to the KDC as -part of the authentication header is that of the ticket-granting service, -but the TGT was issued from another realm, the KDC will look up the -inter-realm key shared with that realm and use that key to decrypt the -ticket. If the ticket is valid, then the KDC will honor the request, subject -to the constraints outlined above in the section describing the AS exchange. -The realm part of the client's identity will be taken from the -ticket-granting ticket. The name of the realm that issued the -ticket-granting ticket will be added to the transited field of the ticket to -be issued. This is accomplished by reading the transited field from the -ticket-granting ticket (which is treated as an unordered set of realm -names), adding the new realm to the set, then constructing and writing out -its encoded (shorthand) form (this may involve a rearrangement of the -existing encoding). - -Note that the ticket-granting service does not add the name of its own - - -draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 - -realm. Instead, its responsibility is to add the name of the previous realm. -This prevents a malicious Kerberos server from intentionally leaving out its -own name (it could, however, omit other realms' names). - -The names of neither the local realm nor the principal's realm are to be -included in the transited field. They appear elsewhere in the ticket and -both are known to have taken part in authenticating the principal. Since the -endpoints are not included, both local and single-hop inter-realm -authentication result in a transited field that is empty. - -Because the name of each realm transited is added to this field, it might -potentially be very long. To decrease the length of this field, its contents -are encoded. The initially supported encoding is optimized for the normal -case of inter-realm communication: a hierarchical arrangement of realms -using either domain or X.500 style realm names. This encoding (called -DOMAIN-X500-COMPRESS) is now described. - -Realm names in the transited field are separated by a ",". The ",", "\", -trailing "."s, and leading spaces (" ") are special characters, and if they -are part of a realm name, they must be quoted in the transited field by -preced- ing them with a "\". - -A realm name ending with a "." is interpreted as being prepended to the -previous realm. For example, we can encode traversal of EDU, MIT.EDU, -ATHENA.MIT.EDU, WASHINGTON.EDU, and CS.WASHINGTON.EDU as: - - "EDU,MIT.,ATHENA.,WASHINGTON.EDU,CS.". - -Note that if ATHENA.MIT.EDU, or CS.WASHINGTON.EDU were end-points, that they -would not be included in this field, and we would have: - - "EDU,MIT.,WASHINGTON.EDU" - -A realm name beginning with a "/" is interpreted as being appended to the -previous realm[18]. If it is to stand by itself, then it should be preceded -by a space (" "). For example, we can encode traversal of /COM/HP/APOLLO, -/COM/HP, /COM, and /COM/DEC as: - - "/COM,/HP,/APOLLO, /COM/DEC". - -Like the example above, if /COM/HP/APOLLO and /COM/DEC are endpoints, they -they would not be included in this field, and we would have: - - "/COM,/HP" - -A null subfield preceding or following a "," indicates that all realms -between the previous realm and the next realm have been traversed[19]. Thus, -"," means that all realms along the path between the client and the server -have been traversed. ",EDU, /COM," means that that all realms from the -client's realm up to EDU (in a domain style hierarchy) have been traversed, -and that everything from /COM down to the server's realm in an X.500 style -has also been traversed. This could occur if the EDU realm in one hierarchy -shares an inter-realm key directly with the /COM realm in another hierarchy. - - - -draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 - -3.3.4. Receipt of KRB_TGS_REP message - -When the KRB_TGS_REP is received by the client, it is processed in the same -manner as the KRB_AS_REP processing described above. The primary difference -is that the ciphertext part of the response must be decrypted using the -session key from the ticket-granting ticket rather than the client's secret -key. See section A.7 for pseudocode. - -3.4. The KRB_SAFE Exchange - -The KRB_SAFE message may be used by clients requiring the ability to detect -modifications of messages they exchange. It achieves this by including a -keyed collision-proof checksum of the user data and some control -information. The checksum is keyed with an encryption key (usually the last -key negotiated via subkeys, or the session key if no negotiation has -occured). - -3.4.1. Generation of a KRB_SAFE message - -When an application wishes to send a KRB_SAFE message, it collects its data -and the appropriate control information and computes a checksum over them. -The checksum algorithm should be a keyed one-way hash function (such as the -RSA- MD5-DES checksum algorithm specified in section 6.4.5, or the DES MAC), -generated using the sub-session key if present, or the session key. -Different algorithms may be selected by changing the checksum type in the -message. Unkeyed or non-collision-proof checksums are not suitable for this -use. - -The control information for the KRB_SAFE message includes both a timestamp -and a sequence number. The designer of an application using the KRB_SAFE -message must choose at least one of the two mechanisms. This choice should -be based on the needs of the application protocol. - -Sequence numbers are useful when all messages sent will be received by one's -peer. Connection state is presently required to maintain the session key, so -maintaining the next sequence number should not present an additional -problem. - -If the application protocol is expected to tolerate lost messages without -them being resent, the use of the timestamp is the appropriate replay -detection mechanism. Using timestamps is also the appropriate mechanism for -multi-cast protocols where all of one's peers share a common sub-session -key, but some messages will be sent to a subset of one's peers. - -After computing the checksum, the client then transmits the information and -checksum to the recipient in the message format specified in section 5.6.1. - -3.4.2. Receipt of KRB_SAFE message - -When an application receives a KRB_SAFE message, it verifies it as follows. -If any error occurs, an error code is reported for use by the application. - -The message is first checked by verifying that the protocol version and type -fields match the current version and KRB_SAFE, respectively. A mismatch - - -draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 - -generates a KRB_AP_ERR_BADVERSION or KRB_AP_ERR_MSG_TYPE error. The -application verifies that the checksum used is a collision-proof keyed -checksum, and if it is not, a KRB_AP_ERR_INAPP_CKSUM error is generated. The -recipient verifies that the operating system's report of the sender's -address matches the sender's address in the message, and (if a recipient -address is specified or the recipient requires an address) that one of the -recipient's addresses appears as the recipient's address in the message. A -failed match for either case generates a KRB_AP_ERR_BADADDR error. Then the -timestamp and usec and/or the sequence number fields are checked. If -timestamp and usec are expected and not present, or they are present but not -current, the KRB_AP_ERR_SKEW error is generated. If the server name, along -with the client name, time and microsecond fields from the Authenticator -match any recently-seen (sent or received[20] ) such tuples, the -KRB_AP_ERR_REPEAT error is generated. If an incorrect sequence number is -included, or a sequence number is expected but not present, the -KRB_AP_ERR_BADORDER error is generated. If neither a time-stamp and usec or -a sequence number is present, a KRB_AP_ERR_MODIFIED error is generated. -Finally, the checksum is computed over the data and control information, and -if it doesn't match the received checksum, a KRB_AP_ERR_MODIFIED error is -generated. - -If all the checks succeed, the application is assured that the message was -generated by its peer and was not modi- fied in transit. - -3.5. The KRB_PRIV Exchange - -The KRB_PRIV message may be used by clients requiring confidentiality and -the ability to detect modifications of exchanged messages. It achieves this -by encrypting the messages and adding control information. - -3.5.1. Generation of a KRB_PRIV message - -When an application wishes to send a KRB_PRIV message, it collects its data -and the appropriate control information (specified in section 5.7.1) and -encrypts them under an encryption key (usually the last key negotiated via -subkeys, or the session key if no negotiation has occured). As part of the -control information, the client must choose to use either a timestamp or a -sequence number (or both); see the discussion in section 3.4.1 for -guidelines on which to use. After the user data and control information are -encrypted, the client transmits the ciphertext and some 'envelope' -information to the recipient. - -3.5.2. Receipt of KRB_PRIV message - -When an application receives a KRB_PRIV message, it verifies it as follows. -If any error occurs, an error code is reported for use by the application. - -The message is first checked by verifying that the protocol version and type -fields match the current version and KRB_PRIV, respectively. A mismatch -generates a KRB_AP_ERR_BADVERSION or KRB_AP_ERR_MSG_TYPE error. The -application then decrypts the ciphertext and processes the resultant -plaintext. If decryption shows the data to have been modified, a -KRB_AP_ERR_BAD_INTEGRITY error is generated. The recipient verifies that the -operating system's report of the sender's address matches the sender's - - -draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 - -address in the message, and (if a recipient address is specified or the -recipient requires an address) that one of the recipient's addresses appears -as the recipient's address in the message. A failed match for either case -generates a KRB_AP_ERR_BADADDR error. Then the timestamp and usec and/or the -sequence number fields are checked. If timestamp and usec are expected and -not present, or they are present but not current, the KRB_AP_ERR_SKEW error -is generated. If the server name, along with the client name, time and -microsecond fields from the Authenticator match any recently-seen such -tuples, the KRB_AP_ERR_REPEAT error is generated. If an incorrect sequence -number is included, or a sequence number is expected but not present, the -KRB_AP_ERR_BADORDER error is generated. If neither a time-stamp and usec or -a sequence number is present, a KRB_AP_ERR_MODIFIED error is generated. - -If all the checks succeed, the application can assume the message was -generated by its peer, and was securely transmitted (without intruders able -to see the unencrypted contents). - -3.6. The KRB_CRED Exchange - -The KRB_CRED message may be used by clients requiring the ability to send -Kerberos credentials from one host to another. It achieves this by sending -the tickets together with encrypted data containing the session keys and -other information associated with the tickets. - -3.6.1. Generation of a KRB_CRED message - -When an application wishes to send a KRB_CRED message it first (using the -KRB_TGS exchange) obtains credentials to be sent to the remote host. It then -constructs a KRB_CRED message using the ticket or tickets so obtained, -placing the session key needed to use each ticket in the key field of the -corresponding KrbCredInfo sequence of the encrypted part of the the KRB_CRED -message. - -Other information associated with each ticket and obtained during the -KRB_TGS exchange is also placed in the corresponding KrbCredInfo sequence in -the encrypted part of the KRB_CRED message. The current time and, if -specifically required by the application the nonce, s-address, and r-address -fields, are placed in the encrypted part of the KRB_CRED message which is -then encrypted under an encryption key previosuly exchanged in the KRB_AP -exchange (usually the last key negotiated via subkeys, or the session key if -no negotiation has occured). - -3.6.2. Receipt of KRB_CRED message - -When an application receives a KRB_CRED message, it verifies it. If any -error occurs, an error code is reported for use by the application. The -message is verified by checking that the protocol version and type fields -match the current version and KRB_CRED, respectively. A mismatch generates a -KRB_AP_ERR_BADVERSION or KRB_AP_ERR_MSG_TYPE error. The application then -decrypts the ciphertext and processes the resultant plaintext. If decryption -shows the data to have been modified, a KRB_AP_ERR_BAD_INTEGRITY error is -generated. - -If present or required, the recipient verifies that the operating system's - - -draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 - -report of the sender's address matches the sender's address in the message, -and that one of the recipient's addresses appears as the recipient's address -in the message. A failed match for either case generates a -KRB_AP_ERR_BADADDR error. The timestamp and usec fields (and the nonce field -if required) are checked next. If the timestamp and usec are not present, or -they are present but not current, the KRB_AP_ERR_SKEW error is generated. - -If all the checks succeed, the application stores each of the new tickets in -its ticket cache together with the session key and other information in the -corresponding KrbCredInfo sequence from the encrypted part of the KRB_CRED -message. - -4. The Kerberos Database - -The Kerberos server must have access to a database contain- ing the -principal identifiers and secret keys of principals to be authenticated[21]. - -4.1. Database contents - -A database entry should contain at least the following fields: - -Field Value - -name Principal's identifier -key Principal's secret key -p_kvno Principal's key version -max_life Maximum lifetime for Tickets -max_renewable_life Maximum total lifetime for renewable Tickets - -The name field is an encoding of the principal's identifier. The key field -contains an encryption key. This key is the principal's secret key. (The key -can be encrypted before storage under a Kerberos "master key" to protect it -in case the database is compromised but the master key is not. In that case, -an extra field must be added to indicate the master key version used, see -below.) The p_kvno field is the key version number of the principal's secret -key. The max_life field contains the maximum allowable lifetime (endtime - -starttime) for any Ticket issued for this principal. The max_renewable_life -field contains the maximum allowable total lifetime for any renewable Ticket -issued for this principal. (See section 3.1 for a description of how these -lifetimes are used in determining the lifetime of a given Ticket.) - -A server may provide KDC service to several realms, as long as the database -representation provides a mechanism to distinguish between principal records -with identifiers which differ only in the realm name. - -When an application server's key changes, if the change is routine (i.e. not -the result of disclosure of the old key), the old key should be retained by -the server until all tickets that had been issued using that key have -expired. Because of this, it is possible for several keys to be active for a -single principal. Ciphertext encrypted in a principal's key is always tagged -with the version of the key that was used for encryption, to help the -recipient find the proper key for decryption. - -When more than one key is active for a particular principal, the principal - - -draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 - -will have more than one record in the Kerberos database. The keys and key -version numbers will differ between the records (the rest of the fields may -or may not be the same). Whenever Kerberos issues a ticket, or responds to a -request for initial authentication, the most recent key (known by the -Kerberos server) will be used for encryption. This is the key with the -highest key version number. - -4.2. Additional fields - -Project Athena's KDC implementation uses additional fields in its database: - -Field Value - -K_kvno Kerberos' key version -expiration Expiration date for entry -attributes Bit field of attributes -mod_date Timestamp of last modification -mod_name Modifying principal's identifier - -The K_kvno field indicates the key version of the Kerberos master key under -which the principal's secret key is encrypted. - -After an entry's expiration date has passed, the KDC will return an error to -any client attempting to gain tickets as or for the principal. (A database -may want to maintain two expiration dates: one for the principal, and one -for the principal's current key. This allows password aging to work -independently of the principal's expiration date. However, due to the -limited space in the responses, the KDC must combine the key expiration and -principal expiration date into a single value called 'key_exp', which is -used as a hint to the user to take administrative action.) - -The attributes field is a bitfield used to govern the operations involving -the principal. This field might be useful in conjunction with user -registration procedures, for site-specific policy implementations (Project -Athena currently uses it for their user registration process controlled by -the system-wide database service, Moira [LGDSR87]), to identify whether a -principal can play the role of a client or server or both, to note whether a -server is appropriate trusted to recieve credentials delegated by a client, -or to identify the 'string to key' conversion algorithm used for a -principal's key[22]. Other bits are used to indicate that certain ticket -options should not be allowed in tickets encrypted under a principal's key -(one bit each): Disallow issuing postdated tickets, disallow issuing -forwardable tickets, disallow issuing tickets based on TGT authentication, -disallow issuing renewable tickets, disallow issuing proxiable tickets, and -disallow issuing tickets for which the principal is the server. - -The mod_date field contains the time of last modification of the entry, and -the mod_name field contains the name of the principal which last modified -the entry. - -4.3. Frequently Changing Fields - -Some KDC implementations may wish to maintain the last time that a request -was made by a particular principal. Information that might be maintained - - -draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 - -includes the time of the last request, the time of the last request for a -ticket-granting ticket, the time of the last use of a ticket-granting -ticket, or other times. This information can then be returned to the user in -the last-req field (see section 5.2). - -Other frequently changing information that can be maintained is the latest -expiration time for any tickets that have been issued using each key. This -field would be used to indicate how long old keys must remain valid to allow -the continued use of outstanding tickets. - -4.4. Site Constants - -The KDC implementation should have the following configurable constants or -options, to allow an administrator to make and enforce policy decisions: - - * The minimum supported lifetime (used to determine whether the - KDC_ERR_NEVER_VALID error should be returned). This constant should - reflect reasonable expectations of round-trip time to the KDC, - encryption/decryption time, and processing time by the client and - target server, and it should allow for a minimum 'useful' lifetime. - * The maximum allowable total (renewable) lifetime of a ticket - (renew_till - starttime). - * The maximum allowable lifetime of a ticket (endtime - starttime). - * Whether to allow the issue of tickets with empty address fields - (including the ability to specify that such tickets may only be issued - if the request specifies some authorization_data). - * Whether proxiable, forwardable, renewable or post-datable tickets are - to be issued. - -5. Message Specifications - -The following sections describe the exact contents and encoding of protocol -messages and objects. The ASN.1 base definitions are presented in the first -subsection. The remaining subsections specify the protocol objects (tickets -and authenticators) and messages. Specification of encryption and checksum -techniques, and the fields related to them, appear in section 6. - -5.1. ASN.1 Distinguished Encoding Representation - -All uses of ASN.1 in Kerberos shall use the Distinguished Encoding -Representation of the data elements as described in the X.509 specification, -section 8.7 [X509-88]. - -5.2. ASN.1 Base Definitions - -The following ASN.1 base definitions are used in the rest of this section. -Note that since the underscore character (_) is not permitted in ASN.1 -names, the hyphen (-) is used in its place for the purposes of ASN.1 names. - -Realm ::= GeneralString -PrincipalName ::= SEQUENCE { - name-type[0] INTEGER, - name-string[1] SEQUENCE OF GeneralString -} - - -draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 - - -Kerberos realms are encoded as GeneralStrings. Realms shall not contain a -character with the code 0 (the ASCII NUL). Most realms will usually consist -of several components separated by periods (.), in the style of Internet -Domain Names, or separated by slashes (/) in the style of X.500 names. -Acceptable forms for realm names are specified in section 7. A PrincipalName -is a typed sequence of components consisting of the following sub-fields: - -name-type - This field specifies the type of name that follows. Pre-defined values - for this field are specified in section 7.2. The name-type should be - treated as a hint. Ignoring the name type, no two names can be the same - (i.e. at least one of the components, or the realm, must be different). - This constraint may be eliminated in the future. -name-string - This field encodes a sequence of components that form a name, each - component encoded as a GeneralString. Taken together, a PrincipalName - and a Realm form a principal identifier. Most PrincipalNames will have - only a few components (typically one or two). - -KerberosTime ::= GeneralizedTime - -- Specifying UTC time zone (Z) - -The timestamps used in Kerberos are encoded as GeneralizedTimes. An encoding -shall specify the UTC time zone (Z) and shall not include any fractional -portions of the seconds. It further shall not include any separators. -Example: The only valid format for UTC time 6 minutes, 27 seconds after 9 pm -on 6 November 1985 is 19851106210627Z. - -HostAddress ::= SEQUENCE { - addr-type[0] INTEGER, - address[1] OCTET STRING -} - -HostAddresses ::= SEQUENCE OF HostAddress - -The host adddress encodings consists of two fields: - -addr-type - This field specifies the type of address that follows. Pre-defined - values for this field are specified in section 8.1. -address - This field encodes a single address of type addr-type. - -The two forms differ slightly. HostAddress contains exactly one address; -HostAddresses contains a sequence of possibly many addresses. - -AuthorizationData ::= SEQUENCE OF SEQUENCE { - ad-type[0] INTEGER, - ad-data[1] OCTET STRING -} - -ad-data - This field contains authorization data to be interpreted according to - - -draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 - - the value of the corresponding ad-type field. -ad-type - This field specifies the format for the ad-data subfield. All negative - values are reserved for local use. Non-negative values are reserved for - registered use. - -Each sequence of type and data is refered to as an authorization element. -Elements may be application specific, however, there is a common set of -recursive elements that should be understood by all implementations. These -elements contain other elements embedded within them, and the interpretation -of the encapsulating element determines which of the embedded elements must -be interpreted, and which may be ignored. Definitions for these common -elements may be found in Appendix B. - -TicketExtensions ::= SEQUENCE OF SEQUENCE { - te-type[0] INTEGER, - te-data[1] OCTET STRING -} - - - -te-data - This field contains opaque data that must be caried with the ticket to - support extensions to the Kerberos protocol including but not limited - to some forms of inter-realm key exchange and plaintext authorization - data. See appendix C for some common uses of this field. -te-type - This field specifies the format for the te-data subfield. All negative - values are reserved for local use. Non-negative values are reserved for - registered use. - -APOptions ::= BIT STRING { - reserved(0), - use-session-key(1), - mutual-required(2) -} - -TicketFlags ::= BIT STRING { - reserved(0), - forwardable(1), - forwarded(2), - proxiable(3), - proxy(4), - may-postdate(5), - postdated(6), - invalid(7), - renewable(8), - initial(9), - pre-authent(10), - hw-authent(11), - transited-policy-checked(12), - ok-as-delegate(13) -} - - - -draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 - -KDCOptions ::= BIT STRING { - reserved(0), - forwardable(1), - forwarded(2), - proxiable(3), - proxy(4), - allow-postdate(5), - postdated(6), - unused7(7), - renewable(8), - unused9(9), - unused10(10), - unused11(11), - unused12(12), - unused13(13), - disable-transited-check(26), - renewable-ok(27), - enc-tkt-in-skey(28), - renew(30), - validate(31) -} - -ASN.1 Bit strings have a length and a value. When used in Kerberos for the -APOptions, TicketFlags, and KDCOptions, the length of the bit string on -generated values should be the smallest multiple of 32 bits needed to -include the highest order bit that is set (1), but in no case less than 32 -bits. Implementations should accept values of bit strings of any length and -treat the value of flags cooresponding to bits beyond the end of the bit -string as if the bit were reset (0). Comparisonof bit strings of different -length should treat the smaller string as if it were padded with zeros -beyond the high order bits to the length of the longer string[23]. - -LastReq ::= SEQUENCE OF SEQUENCE { - lr-type[0] INTEGER, - lr-value[1] KerberosTime -} - -lr-type - This field indicates how the following lr-value field is to be - interpreted. Negative values indicate that the information pertains - only to the responding server. Non-negative values pertain to all - servers for the realm. If the lr-type field is zero (0), then no - information is conveyed by the lr-value subfield. If the absolute value - of the lr-type field is one (1), then the lr-value subfield is the time - of last initial request for a TGT. If it is two (2), then the lr-value - subfield is the time of last initial request. If it is three (3), then - the lr-value subfield is the time of issue for the newest - ticket-granting ticket used. If it is four (4), then the lr-value - subfield is the time of the last renewal. If it is five (5), then the - lr-value subfield is the time of last request (of any type). -lr-value - This field contains the time of the last request. the time must be - interpreted according to the contents of the accompanying lr-type - subfield. - - -draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 - - -See section 6 for the definitions of Checksum, ChecksumType, EncryptedData, -EncryptionKey, EncryptionType, and KeyType. - -5.3. Tickets and Authenticators - -This section describes the format and encryption parameters for tickets and -authenticators. When a ticket or authenticator is included in a protocol -message it is treated as an opaque object. - -5.3.1. Tickets - -A ticket is a record that helps a client authenticate to a service. A Ticket -contains the following information: - -Ticket ::= [APPLICATION 1] SEQUENCE { - tkt-vno[0] INTEGER, - realm[1] Realm, - sname[2] PrincipalName, - enc-part[3] EncryptedData, - extensions[4] TicketExtensions OPTIONAL -} - --- Encrypted part of ticket -EncTicketPart ::= [APPLICATION 3] SEQUENCE { - flags[0] TicketFlags, - key[1] EncryptionKey, - crealm[2] Realm, - cname[3] PrincipalName, - transited[4] TransitedEncoding, - authtime[5] KerberosTime, - starttime[6] KerberosTime OPTIONAL, - endtime[7] KerberosTime, - renew-till[8] KerberosTime OPTIONAL, - caddr[9] HostAddresses OPTIONAL, - authorization-data[10] AuthorizationData OPTIONAL -} --- encoded Transited field -TransitedEncoding ::= SEQUENCE { - tr-type[0] INTEGER, -- must be registered - contents[1] OCTET STRING -} - -The encoding of EncTicketPart is encrypted in the key shared by Kerberos and -the end server (the server's secret key). See section 6 for the format of -the ciphertext. - -tkt-vno - This field specifies the version number for the ticket format. This - document describes version number 5. -realm - This field specifies the realm that issued a ticket. It also serves to - identify the realm part of the server's principal identifier. Since a - Kerberos server can only issue tickets for servers within its realm, - - -draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 - - the two will always be identical. -sname - This field specifies the name part of the server's identity. -enc-part - This field holds the encrypted encoding of the EncTicketPart sequence. -extensions - This optional field contains a sequence of extentions that may be used - to carry information that must be carried with the ticket to support - several extensions, including but not limited to plaintext - authorization data, tokens for exchanging inter-realm keys, and other - information that must be associated with a ticket for use by the - application server. See Appendix C for definitions of some common - extensions. - - Note that some older versions of Kerberos did not support this field. - Because this is an optional field it will not break older clients, but - older clients might strip this field from the ticket before sending it - to the application server. This limits the usefulness of this ticket - field to environments where the ticket will not be parsed and - reconstructed by these older Kerberos clients. - - If it is known that the client will strip this field from the ticket, - as an interim measure the KDC may append this field to the end of the - enc-part of the ticket and append a traler indicating the lenght of the - appended extensions field. (this paragraph is open for discussion, - including the form of the traler). -flags - This field indicates which of various options were used or requested - when the ticket was issued. It is a bit-field, where the selected - options are indicated by the bit being set (1), and the unselected - options and reserved fields being reset (0). Bit 0 is the most - significant bit. The encoding of the bits is specified in section 5.2. - The flags are described in more detail above in section 2. The meanings - of the flags are: - - Bit(s) Name Description - - 0 RESERVED - Reserved for future expansion of this - field. - - 1 FORWARDABLE - The FORWARDABLE flag is normally only - interpreted by the TGS, and can be - ignored by end servers. When set, this - flag tells the ticket-granting server - that it is OK to issue a new ticket- - granting ticket with a different network - address based on the presented ticket. - - 2 FORWARDED - When set, this flag indicates that the - ticket has either been forwarded or was - issued based on authentication involving - - -draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 - - a forwarded ticket-granting ticket. - - 3 PROXIABLE - The PROXIABLE flag is normally only - interpreted by the TGS, and can be - ignored by end servers. The PROXIABLE - flag has an interpretation identical to - that of the FORWARDABLE flag, except - that the PROXIABLE flag tells the - ticket-granting server that only non- - ticket-granting tickets may be issued - with different network addresses. - - 4 PROXY - When set, this flag indicates that a - ticket is a proxy. - - 5 MAY-POSTDATE - The MAY-POSTDATE flag is normally only - interpreted by the TGS, and can be - ignored by end servers. This flag tells - the ticket-granting server that a post- - dated ticket may be issued based on this - ticket-granting ticket. - - 6 POSTDATED - This flag indicates that this ticket has - been postdated. The end-service can - check the authtime field to see when the - original authentication occurred. - - 7 INVALID - This flag indicates that a ticket is - invalid, and it must be validated by the - KDC before use. Application servers - must reject tickets which have this flag - set. - - 8 RENEWABLE - The RENEWABLE flag is normally only - interpreted by the TGS, and can usually - be ignored by end servers (some particu- - larly careful servers may wish to disal- - low renewable tickets). A renewable - ticket can be used to obtain a replace- - ment ticket that expires at a later - date. - - 9 INITIAL - This flag indicates that this ticket was - issued using the AS protocol, and not - issued based on a ticket-granting - ticket. - - - -draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 - - 10 PRE-AUTHENT - This flag indicates that during initial - authentication, the client was authenti- - cated by the KDC before a ticket was - issued. The strength of the pre- - authentication method is not indicated, - but is acceptable to the KDC. - - 11 HW-AUTHENT - This flag indicates that the protocol - employed for initial authentication - required the use of hardware expected to - be possessed solely by the named client. - The hardware authentication method is - selected by the KDC and the strength of - the method is not indicated. - - 12 TRANSITED This flag indicates that the KDC for the - POLICY-CHECKED realm has checked the transited field - against a realm defined policy for - trusted certifiers. If this flag is - reset (0), then the application server - must check the transited field itself, - and if unable to do so it must reject - the authentication. If the flag is set - (1) then the application server may skip - its own validation of the transited - field, relying on the validation - performed by the KDC. At its option the - application server may still apply its - own validation based on a separate - policy for acceptance. - - 13 OK-AS-DELEGATE This flag indicates that the server (not - the client) specified in the ticket has - been determined by policy of the realm - to be a suitable recipient of - delegation. A client can use the - presence of this flag to help it make a - decision whether to delegate credentials - (either grant a proxy or a forwarded - ticket granting ticket) to this server. - The client is free to ignore the value - of this flag. When setting this flag, - an administrator should consider the - Security and placement of the server on - which the service will run, as well as - whether the service requires the use of - delegated credentials. - - 14 ANONYMOUS - This flag indicates that the principal - named in the ticket is a generic princi- - pal for the realm and does not identify - - -draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 - - the individual using the ticket. The - purpose of the ticket is only to - securely distribute a session key, and - not to identify the user. Subsequent - requests using the same ticket and ses- - sion may be considered as originating - from the same user, but requests with - the same username but a different ticket - are likely to originate from different - users. - - 15-31 RESERVED - Reserved for future use. - -key - This field exists in the ticket and the KDC response and is used to - pass the session key from Kerberos to the application server and the - client. The field's encoding is described in section 6.2. -crealm - This field contains the name of the realm in which the client is - registered and in which initial authentication took place. -cname - This field contains the name part of the client's principal identifier. -transited - This field lists the names of the Kerberos realms that took part in - authenticating the user to whom this ticket was issued. It does not - specify the order in which the realms were transited. See section - 3.3.3.2 for details on how this field encodes the traversed realms. -authtime - This field indicates the time of initial authentication for the named - principal. It is the time of issue for the original ticket on which - this ticket is based. It is included in the ticket to provide - additional information to the end service, and to provide the necessary - information for implementation of a `hot list' service at the KDC. An - end service that is particularly paranoid could refuse to accept - tickets for which the initial authentication occurred "too far" in the - past. This field is also returned as part of the response from the KDC. - When returned as part of the response to initial authentication - (KRB_AS_REP), this is the current time on the Ker- beros server[24]. -starttime - This field in the ticket specifies the time after which the ticket is - valid. Together with endtime, this field specifies the life of the - ticket. If it is absent from the ticket, its value should be treated as - that of the authtime field. -endtime - This field contains the time after which the ticket will not be honored - (its expiration time). Note that individual services may place their - own limits on the life of a ticket and may reject tickets which have - not yet expired. As such, this is really an upper bound on the - expiration time for the ticket. -renew-till - This field is only present in tickets that have the RENEWABLE flag set - in the flags field. It indicates the maximum endtime that may be - included in a renewal. It can be thought of as the absolute expiration - - -draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 - - time for the ticket, including all renewals. -caddr - This field in a ticket contains zero (if omitted) or more (if present) - host addresses. These are the addresses from which the ticket can be - used. If there are no addresses, the ticket can be used from any - location. The decision by the KDC to issue or by the end server to - accept zero-address tickets is a policy decision and is left to the - Kerberos and end-service administrators; they may refuse to issue or - accept such tickets. The suggested and default policy, however, is that - such tickets will only be issued or accepted when additional - information that can be used to restrict the use of the ticket is - included in the authorization_data field. Such a ticket is a - capability. - - Network addresses are included in the ticket to make it harder for an - attacker to use stolen credentials. Because the session key is not sent - over the network in cleartext, credentials can't be stolen simply by - listening to the network; an attacker has to gain access to the session - key (perhaps through operating system security breaches or a careless - user's unattended session) to make use of stolen tickets. - - It is important to note that the network address from which a - connection is received cannot be reliably determined. Even if it could - be, an attacker who has compromised the client's worksta- tion could - use the credentials from there. Including the network addresses only - makes it more difficult, not impossible, for an attacker to walk off - with stolen credentials and then use them from a "safe" location. -authorization-data - The authorization-data field is used to pass authorization data from - the principal on whose behalf a ticket was issued to the application - service. If no authorization data is included, this field will be left - out. Experience has shown that the name of this field is confusing, and - that a better name for this field would be restrictions. Unfortunately, - it is not possible to change the name of this field at this time. - - This field contains restrictions on any authority obtained on the basis - of authentication using the ticket. It is possible for any principal in - posession of credentials to add entries to the authorization data field - since these entries further restrict what can be done with the ticket. - Such additions can be made by specifying the additional entries when a - new ticket is obtained during the TGS exchange, or they may be added - during chained delegation using the authorization data field of the - authenticator. - - Because entries may be added to this field by the holder of - credentials, it is not allowable for the presence of an entry in the - authorization data field of a ticket to amplify the priveleges one - would obtain from using a ticket. - - The data in this field may be specific to the end service; the field - will contain the names of service specific objects, and the rights to - those objects. The format for this field is described in section 5.2. - Although Kerberos is not concerned with the format of the contents of - the sub-fields, it does carry type information (ad-type). - - -draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 - - - By using the authorization_data field, a principal is able to issue a - proxy that is valid for a specific purpose. For example, a client - wishing to print a file can obtain a file server proxy to be passed to - the print server. By specifying the name of the file in the - authorization_data field, the file server knows that the print server - can only use the client's rights when accessing the particular file to - be printed. - - A separate service providing authorization or certifying group - membership may be built using the authorization-data field. In this - case, the entity granting authorization (not the authorized entity), - obtains a ticket in its own name (e.g. the ticket is issued in the name - of a privelege server), and this entity adds restrictions on its own - authority and delegates the restricted authority through a proxy to the - client. The client would then present this authorization credential to - the application server separately from the authentication exchange. - - Similarly, if one specifies the authorization-data field of a proxy and - leaves the host addresses blank, the resulting ticket and session key - can be treated as a capability. See [Neu93] for some suggested uses of - this field. - - The authorization-data field is optional and does not have to be - included in a ticket. - -5.3.2. Authenticators - -An authenticator is a record sent with a ticket to a server to certify the -client's knowledge of the encryption key in the ticket, to help the server -detect replays, and to help choose a "true session key" to use with the -particular session. The encoding is encrypted in the ticket's session key -shared by the client and the server: - --- Unencrypted authenticator -Authenticator ::= [APPLICATION 2] SEQUENCE { - authenticator-vno[0] INTEGER, - crealm[1] Realm, - cname[2] PrincipalName, - cksum[3] Checksum OPTIONAL, - cusec[4] INTEGER, - ctime[5] KerberosTime, - subkey[6] EncryptionKey OPTIONAL, - seq-number[7] INTEGER OPTIONAL, - authorization-data[8] AuthorizationData OPTIONAL -} - - -authenticator-vno - This field specifies the version number for the format of the - authenticator. This document specifies version 5. -crealm and cname - These fields are the same as those described for the ticket in section - 5.3.1. - - -draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 - -cksum - This field contains a checksum of the the applica- tion data that - accompanies the KRB_AP_REQ. -cusec - This field contains the microsecond part of the client's timestamp. Its - value (before encryption) ranges from 0 to 999999. It often appears - along with ctime. The two fields are used together to specify a - reasonably accurate timestamp. -ctime - This field contains the current time on the client's host. -subkey - This field contains the client's choice for an encryption key which is - to be used to protect this specific application session. Unless an - application specifies otherwise, if this field is left out the session - key from the ticket will be used. -seq-number - This optional field includes the initial sequence number to be used by - the KRB_PRIV or KRB_SAFE messages when sequence numbers are used to - detect replays (It may also be used by application specific messages). - When included in the authenticator this field specifies the initial - sequence number for messages from the client to the server. When - included in the AP-REP message, the initial sequence number is that for - messages from the server to the client. When used in KRB_PRIV or - KRB_SAFE messages, it is incremented by one after each message is sent. - - For sequence numbers to adequately support the detection of replays - they should be non-repeating, even across connection boundaries. The - initial sequence number should be random and uniformly distributed - across the full space of possible sequence numbers, so that it cannot - be guessed by an attacker and so that it and the successive sequence - numbers do not repeat other sequences. -authorization-data - This field is the same as described for the ticket in section 5.3.1. It - is optional and will only appear when additional restrictions are to be - placed on the use of a ticket, beyond those carried in the ticket - itself. - -5.4. Specifications for the AS and TGS exchanges - -This section specifies the format of the messages used in the exchange -between the client and the Kerberos server. The format of possible error -messages appears in section 5.9.1. - -5.4.1. KRB_KDC_REQ definition - -The KRB_KDC_REQ message has no type of its own. Instead, its type is one of -KRB_AS_REQ or KRB_TGS_REQ depending on whether the request is for an initial -ticket or an additional ticket. In either case, the message is sent from the -client to the Authentication Server to request credentials for a service. - -The message fields are: - -AS-REQ ::= [APPLICATION 10] KDC-REQ -TGS-REQ ::= [APPLICATION 12] KDC-REQ - - -draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 - - -KDC-REQ ::= SEQUENCE { - pvno[1] INTEGER, - msg-type[2] INTEGER, - padata[3] SEQUENCE OF PA-DATA OPTIONAL, - req-body[4] KDC-REQ-BODY -} - -PA-DATA ::= SEQUENCE { - padata-type[1] INTEGER, - padata-value[2] OCTET STRING, - -- might be encoded AP-REQ -} - -KDC-REQ-BODY ::= SEQUENCE { - kdc-options[0] KDCOptions, - cname[1] PrincipalName OPTIONAL, - -- Used only in AS-REQ - realm[2] Realm, -- Server's realm - -- Also client's in AS-REQ - sname[3] PrincipalName OPTIONAL, - from[4] KerberosTime OPTIONAL, - till[5] KerberosTime OPTIONAL, - rtime[6] KerberosTime OPTIONAL, - nonce[7] INTEGER, - etype[8] SEQUENCE OF INTEGER, - -- EncryptionType, - -- in preference order - addresses[9] HostAddresses OPTIONAL, - enc-authorization-data[10] EncryptedData OPTIONAL, - -- Encrypted AuthorizationData - -- encoding - additional-tickets[11] SEQUENCE OF Ticket OPTIONAL -} - -The fields in this message are: - -pvno - This field is included in each message, and specifies the protocol - version number. This document specifies protocol version 5. -msg-type - This field indicates the type of a protocol message. It will almost - always be the same as the application identifier associated with a - message. It is included to make the identifier more readily accessible - to the application. For the KDC-REQ message, this type will be - KRB_AS_REQ or KRB_TGS_REQ. -padata - The padata (pre-authentication data) field contains a sequence of - authentication information which may be needed before credentials can - be issued or decrypted. In the case of requests for additional tickets - (KRB_TGS_REQ), this field will include an element with padata-type of - PA-TGS-REQ and data of an authentication header (ticket-granting ticket - and authenticator). The checksum in the authenticator (which must be - collision-proof) is to be computed over the KDC-REQ-BODY encoding. In - - -draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 - - most requests for initial authentication (KRB_AS_REQ) and most replies - (KDC-REP), the padata field will be left out. - - This field may also contain information needed by certain extensions to - the Kerberos protocol. For example, it might be used to initially - verify the identity of a client before any response is returned. This - is accomplished with a padata field with padata-type equal to - PA-ENC-TIMESTAMP and padata-value defined as follows: - - padata-type ::= PA-ENC-TIMESTAMP - padata-value ::= EncryptedData -- PA-ENC-TS-ENC - - PA-ENC-TS-ENC ::= SEQUENCE { - patimestamp[0] KerberosTime, -- client's time - pausec[1] INTEGER OPTIONAL - } - - with patimestamp containing the client's time and pausec containing the - microseconds which may be omitted if a client will not generate more - than one request per second. The ciphertext (padata-value) consists of - the PA-ENC-TS-ENC sequence, encrypted using the client's secret key. - - [use-specified-kvno item is here for discussion and may be removed] It - may also be used by the client to specify the version of a key that is - being used for accompanying preauthentication, and/or which should be - used to encrypt the reply from the KDC. - - PA-USE-SPECIFIED-KVNO ::= Integer - - The KDC should only accept and abide by the value of the - use-specified-kvno preauthentication data field when the specified key - is still valid and until use of a new key is confirmed. This situation - is likely to occur primarily during the period during which an updated - key is propagating to other KDC's in a realm. - - The padata field can also contain information needed to help the KDC or - the client select the key needed for generating or decrypting the - response. This form of the padata is useful for supporting the use of - certain token cards with Kerberos. The details of such extensions are - specified in separate documents. See [Pat92] for additional uses of - this field. -padata-type - The padata-type element of the padata field indicates the way that the - padata-value element is to be interpreted. Negative values of - padata-type are reserved for unregistered use; non-negative values are - used for a registered interpretation of the element type. -req-body - This field is a placeholder delimiting the extent of the remaining - fields. If a checksum is to be calculated over the request, it is - calculated over an encoding of the KDC-REQ-BODY sequence which is - enclosed within the req-body field. -kdc-options - This field appears in the KRB_AS_REQ and KRB_TGS_REQ requests to the - KDC and indicates the flags that the client wants set on the tickets as - - -draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 - - well as other information that is to modify the behavior of the KDC. - Where appropriate, the name of an option may be the same as the flag - that is set by that option. Although in most case, the bit in the - options field will be the same as that in the flags field, this is not - guaranteed, so it is not acceptable to simply copy the options field to - the flags field. There are various checks that must be made before - honoring an option anyway. - - The kdc_options field is a bit-field, where the selected options are - indicated by the bit being set (1), and the unselected options and - reserved fields being reset (0). The encoding of the bits is specified - in section 5.2. The options are described in more detail above in - section 2. The meanings of the options are: - - Bit(s) Name Description - 0 RESERVED - Reserved for future expansion of this - field. - - 1 FORWARDABLE - The FORWARDABLE option indicates that - the ticket to be issued is to have its - forwardable flag set. It may only be - set on the initial request, or in a sub- - sequent request if the ticket-granting - ticket on which it is based is also for- - wardable. - - 2 FORWARDED - The FORWARDED option is only specified - in a request to the ticket-granting - server and will only be honored if the - ticket-granting ticket in the request - has its FORWARDABLE bit set. This - option indicates that this is a request - for forwarding. The address(es) of the - host from which the resulting ticket is - to be valid are included in the - addresses field of the request. - - 3 PROXIABLE - The PROXIABLE option indicates that the - ticket to be issued is to have its prox- - iable flag set. It may only be set on - the initial request, or in a subsequent - request if the ticket-granting ticket on - which it is based is also proxiable. - - 4 PROXY - The PROXY option indicates that this is - a request for a proxy. This option will - only be honored if the ticket-granting - ticket in the request has its PROXIABLE - bit set. The address(es) of the host - - -draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 - - from which the resulting ticket is to be - valid are included in the addresses - field of the request. - - 5 ALLOW-POSTDATE - The ALLOW-POSTDATE option indicates that - the ticket to be issued is to have its - MAY-POSTDATE flag set. It may only be - set on the initial request, or in a sub- - sequent request if the ticket-granting - ticket on which it is based also has its - MAY-POSTDATE flag set. - - 6 POSTDATED - The POSTDATED option indicates that this - is a request for a postdated ticket. - This option will only be honored if the - ticket-granting ticket on which it is - based has its MAY-POSTDATE flag set. - The resulting ticket will also have its - INVALID flag set, and that flag may be - reset by a subsequent request to the KDC - after the starttime in the ticket has - been reached. - - 7 UNUSED - This option is presently unused. - - 8 RENEWABLE - The RENEWABLE option indicates that the - ticket to be issued is to have its - RENEWABLE flag set. It may only be set - on the initial request, or when the - ticket-granting ticket on which the - request is based is also renewable. If - this option is requested, then the rtime - field in the request contains the - desired absolute expiration time for the - ticket. - - 9-13 UNUSED - These options are presently unused. - - 14 REQUEST-ANONYMOUS - The REQUEST-ANONYMOUS option indicates - that the ticket to be issued is not to - identify the user to which it was - issued. Instead, the principal identif- - ier is to be generic, as specified by - the policy of the realm (e.g. usually - anonymous@realm). The purpose of the - ticket is only to securely distribute a - session key, and not to identify the - user. The ANONYMOUS flag on the ticket - - -draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 - - to be returned should be set. If the - local realms policy does not permit - anonymous credentials, the request is to - be rejected. - - 15-25 RESERVED - Reserved for future use. - - 26 DISABLE-TRANSITED-CHECK - By default the KDC will check the - transited field of a ticket-granting- - ticket against the policy of the local - realm before it will issue derivative - tickets based on the ticket granting - ticket. If this flag is set in the - request, checking of the transited field - is disabled. Tickets issued without the - performance of this check will be noted - by the reset (0) value of the - TRANSITED-POLICY-CHECKED flag, - indicating to the application server - that the tranisted field must be checked - locally. KDC's are encouraged but not - required to honor the - DISABLE-TRANSITED-CHECK option. - - 27 RENEWABLE-OK - The RENEWABLE-OK option indicates that a - renewable ticket will be acceptable if a - ticket with the requested life cannot - otherwise be provided. If a ticket with - the requested life cannot be provided, - then a renewable ticket may be issued - with a renew-till equal to the the - requested endtime. The value of the - renew-till field may still be limited by - local limits, or limits selected by the - individual principal or server. - - 28 ENC-TKT-IN-SKEY - This option is used only by the ticket- - granting service. The ENC-TKT-IN-SKEY - option indicates that the ticket for the - end server is to be encrypted in the - session key from the additional ticket- - granting ticket provided. - - 29 RESERVED - Reserved for future use. - - 30 RENEW - This option is used only by the ticket- - granting service. The RENEW option - indicates that the present request is - - -draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 - - for a renewal. The ticket provided is - encrypted in the secret key for the - server on which it is valid. This - option will only be honored if the - ticket to be renewed has its RENEWABLE - flag set and if the time in its renew- - till field has not passed. The ticket - to be renewed is passed in the padata - field as part of the authentication - header. - - 31 VALIDATE - This option is used only by the ticket- - granting service. The VALIDATE option - indicates that the request is to vali- - date a postdated ticket. It will only - be honored if the ticket presented is - postdated, presently has its INVALID - flag set, and would be otherwise usable - at this time. A ticket cannot be vali- - dated before its starttime. The ticket - presented for validation is encrypted in - the key of the server for which it is - valid and is passed in the padata field - as part of the authentication header. - -cname and sname - These fields are the same as those described for the ticket in section - 5.3.1. sname may only be absent when the ENC-TKT-IN-SKEY option is - specified. If absent, the name of the server is taken from the name of - the client in the ticket passed as additional-tickets. -enc-authorization-data - The enc-authorization-data, if present (and it can only be present in - the TGS_REQ form), is an encoding of the desired authorization-data - encrypted under the sub-session key if present in the Authenticator, or - alternatively from the session key in the ticket-granting ticket, both - from the padata field in the KRB_AP_REQ. -realm - This field specifies the realm part of the server's principal - identifier. In the AS exchange, this is also the realm part of the - client's principal identifier. -from - This field is included in the KRB_AS_REQ and KRB_TGS_REQ ticket - requests when the requested ticket is to be postdated. It specifies the - desired start time for the requested ticket. If this field is omitted - then the KDC should use the current time instead. -till - This field contains the expiration date requested by the client in a - ticket request. It is optional and if omitted the requested ticket is - to have the maximum endtime permitted according to KDC policy for the - parties to the authentication exchange as limited by expiration date of - the ticket granting ticket or other preauthentication credentials. -rtime - This field is the requested renew-till time sent from a client to the - - -draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 - - KDC in a ticket request. It is optional. -nonce - This field is part of the KDC request and response. It it intended to - hold a random number generated by the client. If the same number is - included in the encrypted response from the KDC, it provides evidence - that the response is fresh and has not been replayed by an attacker. - Nonces must never be re-used. Ideally, it should be generated randomly, - but if the correct time is known, it may suffice[25]. -etype - This field specifies the desired encryption algorithm to be used in the - response. -addresses - This field is included in the initial request for tickets, and - optionally included in requests for additional tickets from the - ticket-granting server. It specifies the addresses from which the - requested ticket is to be valid. Normally it includes the addresses for - the client's host. If a proxy is requested, this field will contain - other addresses. The contents of this field are usually copied by the - KDC into the caddr field of the resulting ticket. -additional-tickets - Additional tickets may be optionally included in a request to the - ticket-granting server. If the ENC-TKT-IN-SKEY option has been - specified, then the session key from the additional ticket will be used - in place of the server's key to encrypt the new ticket. If more than - one option which requires additional tickets has been specified, then - the additional tickets are used in the order specified by the ordering - of the options bits (see kdc-options, above). - -The application code will be either ten (10) or twelve (12) depending on -whether the request is for an initial ticket (AS-REQ) or for an additional -ticket (TGS-REQ). - -The optional fields (addresses, authorization-data and additional-tickets) -are only included if necessary to perform the operation specified in the -kdc-options field. - -It should be noted that in KRB_TGS_REQ, the protocol version number appears -twice and two different message types appear: the KRB_TGS_REQ message -contains these fields as does the authentication header (KRB_AP_REQ) that is -passed in the padata field. - -5.4.2. KRB_KDC_REP definition - -The KRB_KDC_REP message format is used for the reply from the KDC for either -an initial (AS) request or a subsequent (TGS) request. There is no message -type for KRB_KDC_REP. Instead, the type will be either KRB_AS_REP or -KRB_TGS_REP. The key used to encrypt the ciphertext part of the reply -depends on the message type. For KRB_AS_REP, the ciphertext is encrypted in -the client's secret key, and the client's key version number is included in -the key version number for the encrypted data. For KRB_TGS_REP, the -ciphertext is encrypted in the sub-session key from the Authenticator, or if -absent, the session key from the ticket-granting ticket used in the request. -In that case, no version number will be present in the EncryptedData -sequence. - - -draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 - - -The KRB_KDC_REP message contains the following fields: - -AS-REP ::= [APPLICATION 11] KDC-REP -TGS-REP ::= [APPLICATION 13] KDC-REP - -KDC-REP ::= SEQUENCE { - pvno[0] INTEGER, - msg-type[1] INTEGER, - padata[2] SEQUENCE OF PA-DATA OPTIONAL, - crealm[3] Realm, - cname[4] PrincipalName, - ticket[5] Ticket, - enc-part[6] EncryptedData -} - -EncASRepPart ::= [APPLICATION 25[27]] EncKDCRepPart -EncTGSRepPart ::= [APPLICATION 26] EncKDCRepPart - -EncKDCRepPart ::= SEQUENCE { - key[0] EncryptionKey, - last-req[1] LastReq, - nonce[2] INTEGER, - key-expiration[3] KerberosTime OPTIONAL, - flags[4] TicketFlags, - authtime[5] KerberosTime, - starttime[6] KerberosTime OPTIONAL, - endtime[7] KerberosTime, - renew-till[8] KerberosTime OPTIONAL, - srealm[9] Realm, - sname[10] PrincipalName, - caddr[11] HostAddresses OPTIONAL -} - -pvno and msg-type - These fields are described above in section 5.4.1. msg-type is either - KRB_AS_REP or KRB_TGS_REP. -padata - This field is described in detail in section 5.4.1. One possible use - for this field is to encode an alternate "mix-in" string to be used - with a string-to-key algorithm (such as is described in section 6.3.2). - This ability is useful to ease transitions if a realm name needs to - change (e.g. when a company is acquired); in such a case all existing - password-derived entries in the KDC database would be flagged as - needing a special mix-in string until the next password change. -crealm, cname, srealm and sname - These fields are the same as those described for the ticket in section - 5.3.1. -ticket - The newly-issued ticket, from section 5.3.1. -enc-part - This field is a place holder for the ciphertext and related information - that forms the encrypted part of a message. The description of the - encrypted part of the message follows each appearance of this field. - - -draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 - - The encrypted part is encoded as described in section 6.1. -key - This field is the same as described for the ticket in section 5.3.1. -last-req - This field is returned by the KDC and specifies the time(s) of the last - request by a principal. Depending on what information is available, - this might be the last time that a request for a ticket-granting ticket - was made, or the last time that a request based on a ticket-granting - ticket was successful. It also might cover all servers for a realm, or - just the particular server. Some implementations may display this - information to the user to aid in discovering unauthorized use of one's - identity. It is similar in spirit to the last login time displayed when - logging into timesharing systems. -nonce - This field is described above in section 5.4.1. -key-expiration - The key-expiration field is part of the response from the KDC and - specifies the time that the client's secret key is due to expire. The - expiration might be the result of password aging or an account - expiration. This field will usually be left out of the TGS reply since - the response to the TGS request is encrypted in a session key and no - client information need be retrieved from the KDC database. It is up to - the application client (usually the login program) to take appropriate - action (such as notifying the user) if the expiration time is imminent. -flags, authtime, starttime, endtime, renew-till and caddr - These fields are duplicates of those found in the encrypted portion of - the attached ticket (see section 5.3.1), provided so the client may - verify they match the intended request and to assist in proper ticket - caching. If the message is of type KRB_TGS_REP, the caddr field will - only be filled in if the request was for a proxy or forwarded ticket, - or if the user is substituting a subset of the addresses from the - ticket granting ticket. If the client-requested addresses are not - present or not used, then the addresses contained in the ticket will be - the same as those included in the ticket-granting ticket. - -5.5. Client/Server (CS) message specifications - -This section specifies the format of the messages used for the -authentication of the client to the application server. - -5.5.1. KRB_AP_REQ definition - -The KRB_AP_REQ message contains the Kerberos protocol version number, the -message type KRB_AP_REQ, an options field to indicate any options in use, -and the ticket and authenticator themselves. The KRB_AP_REQ message is often -referred to as the 'authentication header'. - -AP-REQ ::= [APPLICATION 14] SEQUENCE { - pvno[0] INTEGER, - msg-type[1] INTEGER, - ap-options[2] APOptions, - ticket[3] Ticket, - authenticator[4] EncryptedData -} - - -draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 - - -APOptions ::= BIT STRING { - reserved(0), - use-session-key(1), - mutual-required(2) -} - - - -pvno and msg-type - These fields are described above in section 5.4.1. msg-type is - KRB_AP_REQ. -ap-options - This field appears in the application request (KRB_AP_REQ) and affects - the way the request is processed. It is a bit-field, where the selected - options are indicated by the bit being set (1), and the unselected - options and reserved fields being reset (0). The encoding of the bits - is specified in section 5.2. The meanings of the options are: - - Bit(s) Name Description - 0 RESERVED - Reserved for future expansion of this - field. - - 1 USE-SESSION-KEY - The USE-SESSION-KEY option indicates - that the ticket the client is presenting - to a server is encrypted in the session - key from the server's ticket-granting - ticket. When this option is not speci- - fied, the ticket is encrypted in the - server's secret key. - - 2 MUTUAL-REQUIRED - The MUTUAL-REQUIRED option tells the - server that the client requires mutual - authentication, and that it must respond - with a KRB_AP_REP message. - - 3-31 RESERVED - Reserved for future use. -ticket - This field is a ticket authenticating the client to the server. -authenticator - This contains the authenticator, which includes the client's choice of - a subkey. Its encoding is described in section 5.3.2. - -5.5.2. KRB_AP_REP definition - -The KRB_AP_REP message contains the Kerberos protocol version number, the -message type, and an encrypted time- stamp. The message is sent in in -response to an application request (KRB_AP_REQ) where the mutual -authentication option has been selected in the ap-options field. - - - -draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 - -AP-REP ::= [APPLICATION 15] SEQUENCE { - pvno[0] INTEGER, - msg-type[1] INTEGER, - enc-part[2] EncryptedData -} - -EncAPRepPart ::= [APPLICATION 27[29]] SEQUENCE { - ctime[0] KerberosTime, - cusec[1] INTEGER, - subkey[2] EncryptionKey OPTIONAL, - seq-number[3] INTEGER OPTIONAL -} - -The encoded EncAPRepPart is encrypted in the shared session key of the -ticket. The optional subkey field can be used in an application-arranged -negotiation to choose a per association session key. - -pvno and msg-type - These fields are described above in section 5.4.1. msg-type is - KRB_AP_REP. -enc-part - This field is described above in section 5.4.2. -ctime - This field contains the current time on the client's host. -cusec - This field contains the microsecond part of the client's timestamp. -subkey - This field contains an encryption key which is to be used to protect - this specific application session. See section 3.2.6 for specifics on - how this field is used to negotiate a key. Unless an application - specifies otherwise, if this field is left out, the sub-session key - from the authenticator, or if also left out, the session key from the - ticket will be used. - -5.5.3. Error message reply - -If an error occurs while processing the application request, the KRB_ERROR -message will be sent in response. See section 5.9.1 for the format of the -error message. The cname and crealm fields may be left out if the server -cannot determine their appropriate values from the corresponding KRB_AP_REQ -message. If the authenticator was decipherable, the ctime and cusec fields -will contain the values from it. - -5.6. KRB_SAFE message specification - -This section specifies the format of a message that can be used by either -side (client or server) of an application to send a tamper-proof message to -its peer. It presumes that a session key has previously been exchanged (for -example, by using the KRB_AP_REQ/KRB_AP_REP messages). - -5.6.1. KRB_SAFE definition - -The KRB_SAFE message contains user data along with a collision-proof -checksum keyed with the last encryption key negotiated via subkeys, or the - - -draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 - -session key if no negotiation has occured. The message fields are: - -KRB-SAFE ::= [APPLICATION 20] SEQUENCE { - pvno[0] INTEGER, - msg-type[1] INTEGER, - safe-body[2] KRB-SAFE-BODY, - cksum[3] Checksum -} - -KRB-SAFE-BODY ::= SEQUENCE { - user-data[0] OCTET STRING, - timestamp[1] KerberosTime OPTIONAL, - usec[2] INTEGER OPTIONAL, - seq-number[3] INTEGER OPTIONAL, - s-address[4] HostAddress OPTIONAL, - r-address[5] HostAddress OPTIONAL -} - -pvno and msg-type - These fields are described above in section 5.4.1. msg-type is - KRB_SAFE. -safe-body - This field is a placeholder for the body of the KRB-SAFE message. It is - to be encoded separately and then have the checksum computed over it, - for use in the cksum field. -cksum - This field contains the checksum of the application data. Checksum - details are described in section 6.4. The checksum is computed over the - encoding of the KRB-SAFE-BODY sequence. -user-data - This field is part of the KRB_SAFE and KRB_PRIV messages and contain - the application specific data that is being passed from the sender to - the recipient. -timestamp - This field is part of the KRB_SAFE and KRB_PRIV messages. Its contents - are the current time as known by the sender of the message. By checking - the timestamp, the recipient of the message is able to make sure that - it was recently generated, and is not a replay. -usec - This field is part of the KRB_SAFE and KRB_PRIV headers. It contains - the microsecond part of the timestamp. -seq-number - This field is described above in section 5.3.2. -s-address - This field specifies the address in use by the sender of the message. -r-address - This field specifies the address in use by the recipient of the - message. It may be omitted for some uses (such as broadcast protocols), - but the recipient may arbitrarily reject such messages. This field - along with s-address can be used to help detect messages which have - been incorrectly or maliciously delivered to the wrong recipient. - -5.7. KRB_PRIV message specification - - - -draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 - -This section specifies the format of a message that can be used by either -side (client or server) of an application to securely and privately send a -message to its peer. It presumes that a session key has previously been -exchanged (for example, by using the KRB_AP_REQ/KRB_AP_REP messages). - -5.7.1. KRB_PRIV definition - -The KRB_PRIV message contains user data encrypted in the Session Key. The -message fields are: - -KRB-PRIV ::= [APPLICATION 21] SEQUENCE { - pvno[0] INTEGER, - msg-type[1] INTEGER, - enc-part[3] EncryptedData -} - -EncKrbPrivPart ::= [APPLICATION 28[31]] SEQUENCE { - user-data[0] OCTET STRING, - timestamp[1] KerberosTime OPTIONAL, - usec[2] INTEGER OPTIONAL, - seq-number[3] INTEGER OPTIONAL, - s-address[4] HostAddress OPTIONAL, -- sender's addr - r-address[5] HostAddress OPTIONAL -- recip's addr -} - -pvno and msg-type - These fields are described above in section 5.4.1. msg-type is - KRB_PRIV. -enc-part - This field holds an encoding of the EncKrbPrivPart sequence encrypted - under the session key[32]. This encrypted encoding is used for the - enc-part field of the KRB-PRIV message. See section 6 for the format of - the ciphertext. -user-data, timestamp, usec, s-address and r-address - These fields are described above in section 5.6.1. -seq-number - This field is described above in section 5.3.2. - -5.8. KRB_CRED message specification - -This section specifies the format of a message that can be used to send -Kerberos credentials from one principal to another. It is presented here to -encourage a common mechanism to be used by applications when forwarding -tickets or providing proxies to subordinate servers. It presumes that a -session key has already been exchanged perhaps by using the -KRB_AP_REQ/KRB_AP_REP messages. - -5.8.1. KRB_CRED definition - -The KRB_CRED message contains a sequence of tickets to be sent and -information needed to use the tickets, including the session key from each. -The information needed to use the tickets is encrypted under an encryption -key previously exchanged or transferred alongside the KRB_CRED message. The -message fields are: - - -draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 - - -KRB-CRED ::= [APPLICATION 22] SEQUENCE { - pvno[0] INTEGER, - msg-type[1] INTEGER, -- KRB_CRED - tickets[2] SEQUENCE OF Ticket, - enc-part[3] EncryptedData -} - -EncKrbCredPart ::= [APPLICATION 29] SEQUENCE { - ticket-info[0] SEQUENCE OF KrbCredInfo, - nonce[1] INTEGER OPTIONAL, - timestamp[2] KerberosTime OPTIONAL, - usec[3] INTEGER OPTIONAL, - s-address[4] HostAddress OPTIONAL, - r-address[5] HostAddress OPTIONAL -} - -KrbCredInfo ::= SEQUENCE { - key[0] EncryptionKey, - prealm[1] Realm OPTIONAL, - pname[2] PrincipalName OPTIONAL, - flags[3] TicketFlags OPTIONAL, - authtime[4] KerberosTime OPTIONAL, - starttime[5] KerberosTime OPTIONAL, - endtime[6] KerberosTime OPTIONAL - renew-till[7] KerberosTime OPTIONAL, - srealm[8] Realm OPTIONAL, - sname[9] PrincipalName OPTIONAL, - caddr[10] HostAddresses OPTIONAL -} - -pvno and msg-type - These fields are described above in section 5.4.1. msg-type is - KRB_CRED. -tickets - These are the tickets obtained from the KDC specifically for use by the - intended recipient. Successive tickets are paired with the - corresponding KrbCredInfo sequence from the enc-part of the KRB-CRED - message. -enc-part - This field holds an encoding of the EncKrbCredPart sequence encrypted - under the session key shared between the sender and the intended - recipient. This encrypted encoding is used for the enc-part field of - the KRB-CRED message. See section 6 for the format of the ciphertext. -nonce - If practical, an application may require the inclusion of a nonce - generated by the recipient of the message. If the same value is - included as the nonce in the message, it provides evidence that the - message is fresh and has not been replayed by an attacker. A nonce must - never be re-used; it should be generated randomly by the recipient of - the message and provided to the sender of the message in an application - specific manner. -timestamp and usec - These fields specify the time that the KRB-CRED message was generated. - - -draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 - - The time is used to provide assurance that the message is fresh. -s-address and r-address - These fields are described above in section 5.6.1. They are used - optionally to provide additional assurance of the integrity of the - KRB-CRED message. -key - This field exists in the corresponding ticket passed by the KRB-CRED - message and is used to pass the session key from the sender to the - intended recipient. The field's encoding is described in section 6.2. - -The following fields are optional. If present, they can be associated with -the credentials in the remote ticket file. If left out, then it is assumed -that the recipient of the credentials already knows their value. - -prealm and pname - The name and realm of the delegated principal identity. -flags, authtime, starttime, endtime, renew-till, srealm, sname, and caddr - These fields contain the values of the correspond- ing fields from the - ticket found in the ticket field. Descriptions of the fields are - identical to the descriptions in the KDC-REP message. - -5.9. Error message specification - -This section specifies the format for the KRB_ERROR message. The fields -included in the message are intended to return as much information as -possible about an error. It is not expected that all the information -required by the fields will be available for all types of errors. If the -appropriate information is not available when the message is composed, the -corresponding field will be left out of the message. - -Note that since the KRB_ERROR message is not protected by any encryption, it -is quite possible for an intruder to synthesize or modify such a message. In -particular, this means that the client should not use any fields in this -message for security-critical purposes, such as setting a system clock or -generating a fresh authenticator. The message can be useful, however, for -advising a user on the reason for some failure. - -5.9.1. KRB_ERROR definition - -The KRB_ERROR message consists of the following fields: - -KRB-ERROR ::= [APPLICATION 30] SEQUENCE { - pvno[0] INTEGER, - msg-type[1] INTEGER, - ctime[2] KerberosTime OPTIONAL, - cusec[3] INTEGER OPTIONAL, - stime[4] KerberosTime, - susec[5] INTEGER, - error-code[6] INTEGER, - crealm[7] Realm OPTIONAL, - cname[8] PrincipalName OPTIONAL, - realm[9] Realm, -- Correct realm - sname[10] PrincipalName, -- Correct name - e-text[11] GeneralString OPTIONAL, - - -draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 - - e-data[12] OCTET STRING OPTIONAL, - e-cksum[13] Checksum OPTIONAL, - e-typed-data[14] SEQUENCE of ETypedData OPTIONAL -} - -ETypedData ::= SEQUENCE { - e-data-type [1] INTEGER, - e-data-value [2] OCTET STRING, -} - - - -pvno and msg-type - These fields are described above in section 5.4.1. msg-type is - KRB_ERROR. -ctime - This field is described above in section 5.4.1. -cusec - This field is described above in section 5.5.2. -stime - This field contains the current time on the server. It is of type - KerberosTime. -susec - This field contains the microsecond part of the server's timestamp. Its - value ranges from 0 to 999999. It appears along with stime. The two - fields are used in conjunction to specify a reasonably accurate - timestamp. -error-code - This field contains the error code returned by Kerberos or the server - when a request fails. To interpret the value of this field see the list - of error codes in section 8. Implementations are encouraged to provide - for national language support in the display of error messages. -crealm, cname, srealm and sname - These fields are described above in section 5.3.1. -e-text - This field contains additional text to help explain the error code - associated with the failed request (for example, it might include a - principal name which was unknown). -e-data - This field contains additional data about the error for use by the - application to help it recover from or handle the error. If the - errorcode is KDC_ERR_PREAUTH_REQUIRED, then the e-data field will - contain an encoding of a sequence of padata fields, each corresponding - to an acceptable pre-authentication method and optionally containing - data for the method: - - METHOD-DATA ::= SEQUENCE of PA-DATA - - If the error-code is KRB_AP_ERR_METHOD, then the e-data field will - contain an encoding of the following sequence: - - METHOD-DATA ::= SEQUENCE { - method-type[0] INTEGER, - method-data[1] OCTET STRING OPTIONAL - - -draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 - - } - - method-type will indicate the required alternate method; method-data - will contain any required additional information. -e-cksum - This field contains an optional checksum for the KRB-ERROR message. The - checksum is calculated over the Kerberos ASN.1 encoding of the - KRB-ERROR message with the checksum absent. The checksum is then added - to the KRB-ERROR structure and the message is re-encoded. The Checksum - should be calculated using the session key from the ticket granting - ticket or service ticket, where available. If the error is in response - to a TGS or AP request, the checksum should be calculated uing the the - session key from the client's ticket. If the error is in response to an - AS request, then the checksum should be calulated using the client's - secret key ONLY if there has been suitable preauthentication to prove - knowledge of the secret key by the client[33]. If a checksum can not be - computed because the key to be used is not available, no checksum will - be included. -e-typed-data - [This field for discussion, may be deleted from final spec] This field - contains optional data that may be used to help the client recover from - the indicated error. [This could contain the METHOD-DATA specified - since I don't think anyone actually uses it yet. It could also contain - the PA-DATA sequence for the preauth required error if we had a clear - way to transition to the use of this field from the use of the untype - e-data field.] For example, this field may specify the key version of - the key used to verify preauthentication: - - e-data-type := 20 -- Key version number - e-data-value := Integer -- Key version number used to verify - preauthentication - -6. Encryption and Checksum Specifications - -The Kerberos protocols described in this document are designed to use stream -encryption ciphers, which can be simulated using commonly available block -encryption ciphers, such as the Data Encryption Standard, [DES77] in -conjunction with block chaining and checksum methods [DESM80]. Encryption is -used to prove the identities of the network entities participating in -message exchanges. The Key Distribution Center for each realm is trusted by -all principals registered in that realm to store a secret key in confidence. -Proof of knowledge of this secret key is used to verify the authenticity of -a principal. - -The KDC uses the principal's secret key (in the AS exchange) or a shared -session key (in the TGS exchange) to encrypt responses to ticket requests; -the ability to obtain the secret key or session key implies the knowledge of -the appropriate keys and the identity of the KDC. The ability of a principal -to decrypt the KDC response and present a Ticket and a properly formed -Authenticator (generated with the session key from the KDC response) to a -service verifies the identity of the principal; likewise the ability of the -service to extract the session key from the Ticket and prove its knowledge -thereof in a response verifies the identity of the service. - - - -draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 - -The Kerberos protocols generally assume that the encryption used is secure -from cryptanalysis; however, in some cases, the order of fields in the -encrypted portions of messages are arranged to minimize the effects of -poorly chosen keys. It is still important to choose good keys. If keys are -derived from user-typed passwords, those passwords need to be well chosen to -make brute force attacks more difficult. Poorly chosen keys still make easy -targets for intruders. - -The following sections specify the encryption and checksum mechanisms -currently defined for Kerberos. The encodings, chaining, and padding -requirements for each are described. For encryption methods, it is often -desirable to place random information (often referred to as a confounder) at -the start of the message. The requirements for a confounder are specified -with each encryption mechanism. - -Some encryption systems use a block-chaining method to improve the the -security characteristics of the ciphertext. However, these chaining methods -often don't provide an integrity check upon decryption. Such systems (such -as DES in CBC mode) must be augmented with a checksum of the plain-text -which can be verified at decryption and used to detect any tampering or -damage. Such checksums should be good at detecting burst errors in the -input. If any damage is detected, the decryption routine is expected to -return an error indicating the failure of an integrity check. Each -encryption type is expected to provide and verify an appropriate checksum. -The specification of each encryption method sets out its checksum -requirements. - -Finally, where a key is to be derived from a user's password, an algorithm -for converting the password to a key of the appropriate type is included. It -is desirable for the string to key function to be one-way, and for the -mapping to be different in different realms. This is important because users -who are registered in more than one realm will often use the same password -in each, and it is desirable that an attacker compromising the Kerberos -server in one realm not obtain or derive the user's key in another. - -For an discussion of the integrity characteristics of the candidate -encryption and checksum methods considered for Kerberos, the the reader is -referred to [SG92]. - -6.1. Encryption Specifications - -The following ASN.1 definition describes all encrypted messages. The -enc-part field which appears in the unencrypted part of messages in section -5 is a sequence consisting of an encryption type, an optional key version -number, and the ciphertext. - -EncryptedData ::= SEQUENCE { - etype[0] INTEGER, -- EncryptionType - kvno[1] INTEGER OPTIONAL, - cipher[2] OCTET STRING -- ciphertext -} - - - - - -draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 - -etype - This field identifies which encryption algorithm was used to encipher - the cipher. Detailed specifications for selected encryption types - appear later in this section. -kvno - This field contains the version number of the key under which data is - encrypted. It is only present in messages encrypted under long lasting - keys, such as principals' secret keys. -cipher - This field contains the enciphered text, encoded as an OCTET STRING. - -The cipher field is generated by applying the specified encryption algorithm -to data composed of the message and algorithm-specific inputs. Encryption -mechanisms defined for use with Kerberos must take sufficient measures to -guarantee the integrity of the plaintext, and we recommend they also take -measures to protect against precomputed dictionary attacks. If the -encryption algorithm is not itself capable of doing so, the protections can -often be enhanced by adding a checksum and a confounder. - -The suggested format for the data to be encrypted includes a confounder, a -checksum, the encoded plaintext, and any necessary padding. The msg-seq -field contains the part of the protocol message described in section 5 which -is to be encrypted. The confounder, checksum, and padding are all untagged -and untyped, and their length is exactly sufficient to hold the appropriate -item. The type and length is implicit and specified by the particular -encryption type being used (etype). The format for the data to be encrypted -is described in the following diagram: - - +-----------+----------+-------------+-----+ - |confounder | check | msg-seq | pad | - +-----------+----------+-------------+-----+ - -The format cannot be described in ASN.1, but for those who prefer an -ASN.1-like notation: - -CipherText ::= ENCRYPTED SEQUENCE { - confounder[0] UNTAGGED[35] OCTET STRING(conf_length) OPTIONAL, - check[1] UNTAGGED OCTET STRING(checksum_length) OPTIONAL, - msg-seq[2] MsgSequence, - pad UNTAGGED OCTET STRING(pad_length) OPTIONAL -} - -One generates a random confounder of the appropriate length, placing it in -confounder; zeroes out check; calculates the appropriate checksum over -confounder, check, and msg-seq, placing the result in check; adds the -necessary padding; then encrypts using the specified encryption type and the -appropriate key. - -Unless otherwise specified, a definition of an encryption algorithm that -specifies a checksum, a length for the confounder field, or an octet -boundary for padding uses this ciphertext format[36]. Those fields which are -not specified will be omitted. - -In the interest of allowing all implementations using a particular - - -draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 - -encryption type to communicate with all others using that type, the -specification of an encryption type defines any checksum that is needed as -part of the encryption process. If an alternative checksum is to be used, a -new encryption type must be defined. - -Some cryptosystems require additional information beyond the key and the -data to be encrypted. For example, DES, when used in cipher-block-chaining -mode, requires an initialization vector. If required, the description for -each encryption type must specify the source of such additional information. -6.2. Encryption Keys - -The sequence below shows the encoding of an encryption key: - - EncryptionKey ::= SEQUENCE { - keytype[0] INTEGER, - keyvalue[1] OCTET STRING - } - -keytype - This field specifies the type of encryption key that follows in the - keyvalue field. It will almost always correspond to the encryption - algorithm used to generate the EncryptedData, though more than one - algorithm may use the same type of key (the mapping is many to one). - This might happen, for example, if the encryption algorithm uses an - alternate checksum algorithm for an integrity check, or a different - chaining mechanism. -keyvalue - This field contains the key itself, encoded as an octet string. - -All negative values for the encryption key type are reserved for local use. -All non-negative values are reserved for officially assigned type fields and -interpreta- tions. - -6.3. Encryption Systems - -6.3.1. The NULL Encryption System (null) - -If no encryption is in use, the encryption system is said to be the NULL -encryption system. In the NULL encryption system there is no checksum, -confounder or padding. The ciphertext is simply the plaintext. The NULL Key -is used by the null encryption system and is zero octets in length, with -keytype zero (0). - -6.3.2. DES in CBC mode with a CRC-32 checksum (des-cbc-crc) - -The des-cbc-crc encryption mode encrypts information under the Data -Encryption Standard [DES77] using the cipher block chaining mode [DESM80]. A -CRC-32 checksum (described in ISO 3309 [ISO3309]) is applied to the -confounder and message sequence (msg-seq) and placed in the cksum field. DES -blocks are 8 bytes. As a result, the data to be encrypted (the concatenation -of confounder, checksum, and message) must be padded to an 8 byte boundary -before encryption. The details of the encryption of this data are identical -to those for the des-cbc-md5 encryption mode. - - - -draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 - -Note that, since the CRC-32 checksum is not collision-proof, an attacker -could use a probabilistic chosen-plaintext attack to generate a valid -message even if a confounder is used [SG92]. The use of collision-proof -checksums is recommended for environments where such attacks represent a -significant threat. The use of the CRC-32 as the checksum for ticket or -authenticator is no longer mandated as an interoperability requirement for -Kerberos Version 5 Specification 1 (See section 9.1 for specific details). - -6.3.3. DES in CBC mode with an MD4 checksum (des-cbc-md4) - -The des-cbc-md4 encryption mode encrypts information under the Data -Encryption Standard [DES77] using the cipher block chaining mode [DESM80]. -An MD4 checksum (described in [MD492]) is applied to the confounder and -message sequence (msg-seq) and placed in the cksum field. DES blocks are 8 -bytes. As a result, the data to be encrypted (the concatenation of -confounder, checksum, and message) must be padded to an 8 byte boundary -before encryption. The details of the encryption of this data are identical -to those for the des-cbc-md5 encryption mode. - -6.3.4. DES in CBC mode with an MD5 checksum (des-cbc-md5) - -The des-cbc-md5 encryption mode encrypts information under the Data -Encryption Standard [DES77] using the cipher block chaining mode [DESM80]. -An MD5 checksum (described in [MD5-92].) is applied to the confounder and -message sequence (msg-seq) and placed in the cksum field. DES blocks are 8 -bytes. As a result, the data to be encrypted (the concatenation of -confounder, checksum, and message) must be padded to an 8 byte boundary -before encryption. - -Plaintext and DES ciphtertext are encoded as blocks of 8 octets which are -concatenated to make the 64-bit inputs for the DES algorithms. The first -octet supplies the 8 most significant bits (with the octet's MSbit used as -the DES input block's MSbit, etc.), the second octet the next 8 bits, ..., -and the eighth octet supplies the 8 least significant bits. - -Encryption under DES using cipher block chaining requires an additional -input in the form of an initialization vector. Unless otherwise specified, -zero should be used as the initialization vector. Kerberos' use of DES -requires an 8 octet confounder. - -The DES specifications identify some 'weak' and 'semi-weak' keys; those keys -shall not be used for encrypting messages for use in Kerberos. Additionally, -because of the way that keys are derived for the encryption of checksums, -keys shall not be used that yield 'weak' or 'semi-weak' keys when -eXclusive-ORed with the hexadecimal constant F0F0F0F0F0F0F0F0. - -A DES key is 8 octets of data, with keytype one (1). This consists of 56 -bits of key, and 8 parity bits (one per octet). The key is encoded as a -series of 8 octets written in MSB-first order. The bits within the key are -also encoded in MSB order. For example, if the encryption key is -(B1,B2,...,B7,P1,B8,...,B14,P2,B15,...,B49,P7,B50,...,B56,P8) where -B1,B2,...,B56 are the key bits in MSB order, and P1,P2,...,P8 are the parity -bits, the first octet of the key would be B1,B2,...,B7,P1 (with B1 as the -MSbit). [See the FIPS 81 introduction for reference.] - - -draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 - - -String to key transformation - -To generate a DES key from a text string (password), the text string -normally must have the realm and each component of the principal's name -appended[37], then padded with ASCII nulls to an 8 byte boundary. This -string is then fan-folded and eXclusive-ORed with itself to form an 8 byte -DES key. The parity is corrected on the key, and it is used to generate a -DES CBC checksum on the initial string (with the realm and name appended). -Next, parity is corrected on the CBC checksum. If the result matches a -'weak' or 'semi-weak' key as described in the DES specification, it is -eXclusive-ORed with the constant 00000000000000F0. Finally, the result is -returned as the key. Pseudocode follows: - - string_to_key(string,realm,name) { - odd = 1; - s = string + realm; - for(each component in name) { - s = s + component; - } - tempkey = NULL; - pad(s); /* with nulls to 8 byte boundary */ - for(8byteblock in s) { - if(odd == 0) { - odd = 1; - reverse(8byteblock) - } - else odd = 0; - tempkey = tempkey XOR 8byteblock; - } - fixparity(tempkey); - key = DES-CBC-check(s,tempkey); - fixparity(key); - if(is_weak_key_key(key)) - key = key XOR 0xF0; - return(key); - } - -6.3.5. Triple DES EDE in outer CBC mode with an SHA1 check-sum -(des3-cbc-sha1) - -The des3-cbc-sha1 encryption encodes information using three Data Encryption -Standard transformations with three DES keys. The first key is used to -perform a DES ECB encryption on an eight-octet data block using the first -DES key, followed by a DES ECB decryption of the result using the second DES -key, and a DES ECB encryption of the result using the third DES key. Because -DES blocks are 8 bytes, the data to be encrypted (the concatenation of -confounder, checksum, and message) must first be padded to an 8 byte -boundary before encryption. To support the outer CBC mode, the input is -padded to an eight-octet boundary. The first 8 octets of the data to be -encrypted (the confounder) is exclusive-ored with an initialization vector -of zero and then ECB encrypted using triple DES as described above. -Subsequent blocks of 8 octets are exclusive-ored with the ciphertext -produced by the encryption on the previous block before ECB encryption. - - -draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 - - -An HMAC-SHA1 checksum (described in [KBC96].) is applied to the confounder -and message sequence (msg-seq) and placed in the cksum field. - -Plaintext are encoded as blocks of 8 octets which are concatenated to make -the 64-bit inputs for the DES algorithms. The first octet supplies the 8 -most significant bits (with the octet's MSbit used as the DES input block's -MSbit, etc.), the second octet the next 8 bits, ..., and the eighth octet -supplies the 8 least significant bits. - -Encryption under Triple DES using cipher block chaining requires an -additional input in the form of an initialization vector. Unless otherwise -specified, zero should be used as the initialization vector. Kerberos' use -of DES requires an 8 octet confounder. - -The DES specifications identify some 'weak' and 'semi-weak' keys; those keys -shall not be used for encrypting messages for use in Kerberos. Additionally, -because of the way that keys are derived for the encryption of checksums, -keys shall not be used that yield 'weak' or 'semi-weak' keys when -eXclusive-ORed with the hexadecimal constant F0F0F0F0F0F0F0F0. - -A Triple DES key is 24 octets of data, with keytype seven (7). This consists -of 168 bits of key, and 24 parity bits (one per octet). The key is encoded -as a series of 24 octets written in MSB-first order, with the first 8 octets -treated as the first DES key, the second 8 octets as the second key, and the -third 8 octets the third DES key. The bits within each key are also encoded -in MSB order. For example, if the encryption key is -(B1,B2,...,B7,P1,B8,...,B14,P2,B15,...,B49,P7,B50,...,B56,P8) where -B1,B2,...,B56 are the key bits in MSB order, and P1,P2,...,P8 are the parity -bits, the first octet of the key would be B1,B2,...,B7,P1 (with B1 as the -MSbit). [See the FIPS 81 introduction for reference.] - -Key derivation for specified operations (Horowitz) - -[Discussion is needed for this section, especially since it does not simply -derive key generation, but also specifies encryption using triple DES in a -manner that is different than the basic template that was specified for -single DES and similar systems] - -In the Kerberos protocol cryptographic keys are used in a number of places. -In order to minimize the effect of compromising a key, it is desirable to -use a different key in each of these places. Key derivation [Horowitz96] can -be used to construct different keys for each operation from the keys -transported on the network or derived from the password specified by the -user. - -For each place where a key is used in Kerberos, a ``key usage'' is specified -for that purpose. The key, key usage, and encryption/checksum type together -describe the transformation from plaintext to ciphertext. For backwards -compatibility, this key derivation is only specified here for encryption -methods based on triple DES. Encryption methods specified for use by -Kerberos in the future should specify the key derivation function to be -used. - - - -draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 - -Kerberos requires that the ciphertext component of EncryptedData be -tamper-resistant as well as confidential. This implies encryption and -integrity functions, which must each use their own separate keys. So, for -each key usage, two keys must be generated, one for encryption (Ke), and one -for integrity (Ki): - - Ke = DK(protocol key, key usage | 0xAA) - Ki = DK(protocol key, key usage | 0x55) - -where the key usage is represented as a 32 bit integer in network byte -order. The ciphertest must be generated from the plaintext as follows: - - ciphertext = E(Ke, confounder | length | plaintext | padding) | - H(Ki, confounder | length | plaintext | padding) - -The confounder and padding are specific to the encryption algorithm E. - -When generating a checksum only, there is no need for a confounder or -padding. Again, a new key (Kc) must be used. Checksums must be generated -from the plaintext as follows: - - Kc = DK(protocol key, key usage | 0x99) - MAC = H(Kc, length | plaintext) - - -Note that each enctype is described by an encryption algorithm E and a keyed -hash algorithm H, and each checksum type is described by a keyed hash -algorithm H. HMAC, with an appropriate hash, is recommended for use as H. - -The key usage value will be taken from the following list of places where -keys are used in the Kerberos protocol, with key usage values and Kerberos -specification section numbers: - - 1. AS-REQ PA-ENC-TIMESTAMP padata timestamp, encrypted with the - client key (section 5.4.1) - 2. AS-REP Ticket and TGS-REP Ticket (includes tgs session key or - application session key), encrypted with the service key - (section 5.4.2) - 3. AS-REP encrypted part (includes tgs session key or application - session key), encrypted with the client key (section 5.4.2) - - 4. TGS-REQ KDC-REQ-BODY AuthorizationData, encrypted with the tgs - session key (section 5.4.1) - 5. TGS-REQ KDC-REQ-BODY AuthorizationData, encrypted with the tgs - authenticator subkey (section 5.4.1) - 6. TGS-REQ PA-TGS-REQ padata AP-REQ Authenticator cksum, keyed - with the tgs session key (sections 5.3.2, 5.4.1) - 7. TGS-REQ PA-TGS-REQ padata AP-REQ Authenticator (includes tgs - authenticator subkey), encrypted with the tgs session key - (section 5.3.2) - 8. TGS-REP encrypted part (includes application session key), - encrypted with the tgs session key (section 5.4.2) - 9. TGS-REP encrypted part (includes application session key), - encrypted with the tgs authenticator subkey (section 5.4.2) - - -draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 - - - 10. AP-REQ Authenticator cksum, keyed with the application session - key (section 5.3.2) - 11. AP-REQ Authenticator (includes application authenticator - subkey), encrypted with the application session key (section - 5.3.2) - 12. AP-REP encrypted part (includes application session subkey), - encrypted with the application session key (section 5.5.2) - - 13. KRB-PRIV encrypted part, encrypted with a key chosen by the - application (section 5.7.1) - 14. KRB-CRED encrypted part, encrypted with a key chosen by the - application (section 5.6.1) - 15. KRB-SAFE cksum, keyed with a key chosen by the application - (section 5.8.1) - - 16. Data which is defined in some specification outside of - Kerberos to be encrypted using Kerberos encryption type. - 17. Data which is defined in some specification outside of - Kerberos to be checksummed using Kerberos checksum type. - - 18. KRB-ERROR checksum (e-cksum in section 5.9.1) - 19. AD-KDCIssued checksum (ad-checksum in appendix B.1) - 20. Checksum for Mandatory Ticket Extensions (appendix B.6) - 21. Checksum in Authorization Data in Ticket Extensions (appendix B.7) - -String to key transformation - -To generate a DES key from a text string (password), the text string -normally must have the realm and each component of the principal's name -appended[38]. - -The input string (with any salt data appended to it) is n-folded into a 24 -octet (192 bit) string. To n-fold a number X, replicate the input value to a -length that is the least common multiple of n and the length of X. Before -each repetition, the input X is rotated to the right by 13 bit positions. -The successive n-bit chunks are added together using 1's-complement addition -(addition with end-around carry) to yield a n-bit result. (This -transformation was proposed by Richard Basch) - -Each successive set of 8 octets is taken as a DES key, and its parity is -adjusted in the same manner as previously described. If any of the three -sets of 8 octets match a 'weak' or 'semi-weak key as described in the DES -specification, that chunk is eXclusive-ORed with the hexadecimal constant -00000000000000F0. The resulting DES keys are then used in sequence to -perform a Triple-DES CBC encryption of the n-folded input string (appended -with any salt data), using a zero initial vector. Parity, weak, and -semi-weak keys are once again corrected and the result is returned as the 24 -octet key. - -Pseudocode follows: - - string_to_key(string,realm,name) { - s = string + realm; - - -draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 - - for(each component in name) { - s = s + component; - } - tkey[24] = fold(s); - fixparity(tkey); - if(isweak(tkey[0-7])) tkey[0-7] = tkey[0-7] XOR 0xF0; - if(isweak(tkey[8-15])) tkey[8-15] = tkey[8-15] XOR 0xF0; - if(is_weak(tkey[16-23])) tkey[16-23] = tkey[16-23] XOR 0xF0; - key[24] = 3DES-CBC(data=fold(s),key=tkey,iv=0); - fixparity(key); - if(is_weak(key[0-7])) key[0-7] = key[0-7] XOR 0xF0; - if(is_weak(key[8-15])) key[8-15] = key[8-15] XOR 0xF0; - if(is_weak(key[16-23])) key[16-23] = key[16-23] XOR 0xF0; - return(key); - } - -6.4. Checksums - -The following is the ASN.1 definition used for a checksum: - - Checksum ::= SEQUENCE { - cksumtype[0] INTEGER, - checksum[1] OCTET STRING - } - -cksumtype - This field indicates the algorithm used to generate the accompanying - checksum. -checksum - This field contains the checksum itself, encoded as an octet string. - -Detailed specification of selected checksum types appear later in this -section. Negative values for the checksum type are reserved for local use. -All non-negative values are reserved for officially assigned type fields and -interpretations. - -Checksums used by Kerberos can be classified by two properties: whether they -are collision-proof, and whether they are keyed. It is infeasible to find -two plaintexts which generate the same checksum value for a collision-proof -checksum. A key is required to perturb or initialize the algorithm in a -keyed checksum. To prevent message-stream modification by an active -attacker, unkeyed checksums should only be used when the checksum and -message will be subsequently encrypted (e.g. the checksums defined as part -of the encryption algorithms covered earlier in this section). - -Collision-proof checksums can be made tamper-proof if the checksum value is -encrypted before inclusion in a message. In such cases, the composition of -the checksum and the encryption algorithm must be considered a separate -checksum algorithm (e.g. RSA-MD5 encrypted using DES is a new checksum -algorithm of type RSA-MD5-DES). For most keyed checksums, as well as for the -encrypted forms of unkeyed collision-proof checksums, Kerberos prepends a -confounder before the checksum is calculated. - -6.4.1. The CRC-32 Checksum (crc32) - - -draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 - - -The CRC-32 checksum calculates a checksum based on a cyclic redundancy check -as described in ISO 3309 [ISO3309]. The resulting checksum is four (4) -octets in length. The CRC-32 is neither keyed nor collision-proof. The use -of this checksum is not recommended. An attacker using a probabilistic -chosen-plaintext attack as described in [SG92] might be able to generate an -alternative message that satisfies the checksum. The use of collision-proof -checksums is recommended for environments where such attacks represent a -significant threat. - -6.4.2. The RSA MD4 Checksum (rsa-md4) - -The RSA-MD4 checksum calculates a checksum using the RSA MD4 algorithm -[MD4-92]. The algorithm takes as input an input message of arbitrary length -and produces as output a 128-bit (16 octet) checksum. RSA-MD4 is believed to -be collision-proof. - -6.4.3. RSA MD4 Cryptographic Checksum Using DES (rsa-md4-des) - -The RSA-MD4-DES checksum calculates a keyed collision-proof checksum by -prepending an 8 octet confounder before the text, applying the RSA MD4 -checksum algorithm, and encrypting the confounder and the checksum using DES -in cipher-block-chaining (CBC) mode using a variant of the key, where the -variant is computed by eXclusive-ORing the key with the constant -F0F0F0F0F0F0F0F0[39]. The initialization vector should be zero. The -resulting checksum is 24 octets long (8 octets of which are redundant). This -checksum is tamper-proof and believed to be collision-proof. - -The DES specifications identify some weak keys' and 'semi-weak keys'; those -keys shall not be used for generating RSA-MD4 checksums for use in Kerberos. - -The format for the checksum is described in the follow- ing diagram: - -+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ -| des-cbc(confounder + rsa-md4(confounder+msg),key=var(key),iv=0) | -+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ - -The format cannot be described in ASN.1, but for those who prefer an -ASN.1-like notation: - -rsa-md4-des-checksum ::= ENCRYPTED UNTAGGED SEQUENCE { - confounder[0] UNTAGGED OCTET STRING(8), - check[1] UNTAGGED OCTET STRING(16) -} - -6.4.4. The RSA MD5 Checksum (rsa-md5) - -The RSA-MD5 checksum calculates a checksum using the RSA MD5 algorithm. -[MD5-92]. The algorithm takes as input an input message of arbitrary length -and produces as output a 128-bit (16 octet) checksum. RSA-MD5 is believed to -be collision-proof. - -6.4.5. RSA MD5 Cryptographic Checksum Using DES (rsa-md5-des) - - - -draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 - -The RSA-MD5-DES checksum calculates a keyed collision-proof checksum by -prepending an 8 octet confounder before the text, applying the RSA MD5 -checksum algorithm, and encrypting the confounder and the checksum using DES -in cipher-block-chaining (CBC) mode using a variant of the key, where the -variant is computed by eXclusive-ORing the key with the hexadecimal constant -F0F0F0F0F0F0F0F0. The initialization vector should be zero. The resulting -checksum is 24 octets long (8 octets of which are redundant). This checksum -is tamper-proof and believed to be collision-proof. - -The DES specifications identify some 'weak keys' and 'semi-weak keys'; those -keys shall not be used for encrypting RSA-MD5 checksums for use in Kerberos. - -The format for the checksum is described in the following diagram: - -+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ -| des-cbc(confounder + rsa-md5(confounder+msg),key=var(key),iv=0) | -+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ - -The format cannot be described in ASN.1, but for those who prefer an -ASN.1-like notation: - -rsa-md5-des-checksum ::= ENCRYPTED UNTAGGED SEQUENCE { - confounder[0] UNTAGGED OCTET STRING(8), - check[1] UNTAGGED OCTET STRING(16) -} - -6.4.6. DES cipher-block chained checksum (des-mac) - -The DES-MAC checksum is computed by prepending an 8 octet confounder to the -plaintext, performing a DES CBC-mode encryption on the result using the key -and an initialization vector of zero, taking the last block of the -ciphertext, prepending the same confounder and encrypting the pair using DES -in cipher-block-chaining (CBC) mode using a a variant of the key, where the -variant is computed by eXclusive-ORing the key with the hexadecimal constant -F0F0F0F0F0F0F0F0. The initialization vector should be zero. The resulting -checksum is 128 bits (16 octets) long, 64 bits of which are redundant. This -checksum is tamper-proof and collision-proof. - -The format for the checksum is described in the following diagram: - -+--+--+--+--+--+--+--+--+-----+-----+-----+-----+-----+-----+-----+-----+ -| des-cbc(confounder + des-mac(conf+msg,iv=0,key),key=var(key),iv=0) | -+--+--+--+--+--+--+--+--+-----+-----+-----+-----+-----+-----+-----+-----+ - -The format cannot be described in ASN.1, but for those who prefer an -ASN.1-like notation: - -des-mac-checksum ::= ENCRYPTED UNTAGGED SEQUENCE { - confounder[0] UNTAGGED OCTET STRING(8), - check[1] UNTAGGED OCTET STRING(8) -} - -The DES specifications identify some 'weak' and 'semi-weak' keys; those keys -shall not be used for generating DES-MAC checksums for use in Kerberos, nor - - -draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 - -shall a key be used whose variant is 'weak' or 'semi-weak'. - -6.4.7. RSA MD4 Cryptographic Checksum Using DES alternative (rsa-md4-des-k) - -The RSA-MD4-DES-K checksum calculates a keyed collision-proof checksum by -applying the RSA MD4 checksum algorithm and encrypting the results using DES -in cipher-block-chaining (CBC) mode using a DES key as both key and -initialization vector. The resulting checksum is 16 octets long. This -checksum is tamper-proof and believed to be collision-proof. Note that this -checksum type is the old method for encoding the RSA-MD4-DES checksum and it -is no longer recommended. - -6.4.8. DES cipher-block chained checksum alternative (des-mac-k) - -The DES-MAC-K checksum is computed by performing a DES CBC-mode encryption -of the plaintext, and using the last block of the ciphertext as the checksum -value. It is keyed with an encryption key and an initialization vector; any -uses which do not specify an additional initialization vector will use the -key as both key and initialization vector. The resulting checksum is 64 bits -(8 octets) long. This checksum is tamper-proof and collision-proof. Note -that this checksum type is the old method for encoding the DES-MAC checksum -and it is no longer recommended. The DES specifications identify some 'weak -keys' and 'semi-weak keys'; those keys shall not be used for generating -DES-MAC checksums for use in Kerberos. - -7. Naming Constraints - -7.1. Realm Names - -Although realm names are encoded as GeneralStrings and although a realm can -technically select any name it chooses, interoperability across realm -boundaries requires agreement on how realm names are to be assigned, and -what information they imply. - -To enforce these conventions, each realm must conform to the conventions -itself, and it must require that any realms with which inter-realm keys are -shared also conform to the conventions and require the same from its -neighbors. - -Kerberos realm names are case sensitive. Realm names that differ only in the -case of the characters are not equivalent. There are presently four styles -of realm names: domain, X500, other, and reserved. Examples of each style -follow: - - domain: ATHENA.MIT.EDU (example) - X500: C=US/O=OSF (example) - other: NAMETYPE:rest/of.name=without-restrictions (example) - reserved: reserved, but will not conflict with above - -Domain names must look like domain names: they consist of components -separated by periods (.) and they contain neither colons (:) nor slashes -(/). Domain names must be converted to upper case when used as realm names. - -X.500 names contain an equal (=) and cannot contain a colon (:) before the - - -draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 - -equal. The realm names for X.500 names will be string representations of the -names with components separated by slashes. Leading and trailing slashes -will not be included. - -Names that fall into the other category must begin with a prefix that -contains no equal (=) or period (.) and the prefix must be followed by a -colon (:) and the rest of the name. All prefixes must be assigned before -they may be used. Presently none are assigned. - -The reserved category includes strings which do not fall into the first -three categories. All names in this category are reserved. It is unlikely -that names will be assigned to this category unless there is a very strong -argument for not using the 'other' category. - -These rules guarantee that there will be no conflicts between the various -name styles. The following additional constraints apply to the assignment of -realm names in the domain and X.500 categories: the name of a realm for the -domain or X.500 formats must either be used by the organization owning (to -whom it was assigned) an Internet domain name or X.500 name, or in the case -that no such names are registered, authority to use a realm name may be -derived from the authority of the parent realm. For example, if there is no -domain name for E40.MIT.EDU, then the administrator of the MIT.EDU realm can -authorize the creation of a realm with that name. - -This is acceptable because the organization to which the parent is assigned -is presumably the organization authorized to assign names to its children in -the X.500 and domain name systems as well. If the parent assigns a realm -name without also registering it in the domain name or X.500 hierarchy, it -is the parent's responsibility to make sure that there will not in the -future exists a name identical to the realm name of the child unless it is -assigned to the same entity as the realm name. - -7.2. Principal Names - -As was the case for realm names, conventions are needed to ensure that all -agree on what information is implied by a principal name. The name-type -field that is part of the principal name indicates the kind of information -implied by the name. The name-type should be treated as a hint. Ignoring the -name type, no two names can be the same (i.e. at least one of the -components, or the realm, must be different). The following name types are -defined: - - name-type value meaning - - NT-UNKNOWN 0 Name type not known - NT-PRINCIPAL 1 General principal name (e.g. username, or DCE principal) - NT-SRV-INST 2 Service and other unique instance (krbtgt) - NT-SRV-HST 3 Service with host name as instance (telnet, rcommands) - NT-SRV-XHST 4 Service with slash-separated host name components - NT-UID 5 Unique ID - NT-X500-PRINCIPAL 6 Encoded X.509 Distingished name [RFC 1779] - -When a name implies no information other than its uniqueness at a particular -time the name type PRINCIPAL should be used. The principal name type should - - -draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 - -be used for users, and it might also be used for a unique server. If the -name is a unique machine generated ID that is guaranteed never to be -reassigned then the name type of UID should be used (note that it is -generally a bad idea to reassign names of any type since stale entries might -remain in access control lists). - -If the first component of a name identifies a service and the remaining -components identify an instance of the service in a server specified manner, -then the name type of SRV-INST should be used. An example of this name type -is the Kerberos ticket-granting service whose name has a first component of -krbtgt and a second component identifying the realm for which the ticket is -valid. - -If instance is a single component following the service name and the -instance identifies the host on which the server is running, then the name -type SRV-HST should be used. This type is typically used for Internet -services such as telnet and the Berkeley R commands. If the separate -components of the host name appear as successive components following the -name of the service, then the name type SRV-XHST should be used. This type -might be used to identify servers on hosts with X.500 names where the slash -(/) might otherwise be ambiguous. - -A name type of NT-X500-PRINCIPAL should be used when a name from an X.509 -certificiate is translated into a Kerberos name. The encoding of the X.509 -name as a Kerberos principal shall conform to the encoding rules specified -in RFC 1779. - -A name type of UNKNOWN should be used when the form of the name is not -known. When comparing names, a name of type UNKNOWN will match principals -authenticated with names of any type. A principal authenticated with a name -of type UNKNOWN, however, will only match other names of type UNKNOWN. - -Names of any type with an initial component of 'krbtgt' are reserved for the -Kerberos ticket granting service. See section 8.2.3 for the form of such -names. - -7.2.1. Name of server principals - -The principal identifier for a server on a host will generally be composed -of two parts: (1) the realm of the KDC with which the server is registered, -and (2) a two-component name of type NT-SRV-HST if the host name is an -Internet domain name or a multi-component name of type NT-SRV-XHST if the -name of the host is of a form such as X.500 that allows slash (/) -separators. The first component of the two- or multi-component name will -identify the service and the latter components will identify the host. Where -the name of the host is not case sensitive (for example, with Internet -domain names) the name of the host must be lower case. If specified by the -application protocol for services such as telnet and the Berkeley R commands -which run with system privileges, the first component may be the string -'host' instead of a service specific identifier. When a host has an official -name and one or more aliases, the official name of the host must be used -when constructing the name of the server principal. - -8. Constants and other defined values - - -draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 - - -8.1. Host address types - -All negative values for the host address type are reserved for local use. -All non-negative values are reserved for officially assigned type fields and -interpretations. - -The values of the types for the following addresses are chosen to match the -defined address family constants in the Berkeley Standard Distributions of -Unix. They can be found in with symbolic names AF_xxx (where xxx is an -abbreviation of the address family name). - -Internet (IPv4) Addresses - -Internet (IPv4) addresses are 32-bit (4-octet) quantities, encoded in MSB -order. The type of IPv4 addresses is two (2). - -Internet (IPv6) Addresses - -IPv6 addresses are 128-bit (16-octet) quantities, encoded in MSB order. The -type of IPv6 addresses is twenty-four (24). [RFC1883] [RFC1884]. The -following addresses (see [RFC1884]) MUST not appear in any Kerberos packet: - - * the Unspecified Address - * the Loopback Address - * Link-Local addresses - -IPv4-mapped IPv6 addresses MUST be represented as addresses of type 2. - -CHAOSnet addresses - -CHAOSnet addresses are 16-bit (2-octet) quantities, encoded in MSB order. -The type of CHAOSnet addresses is five (5). - -ISO addresses - -ISO addresses are variable-length. The type of ISO addresses is seven (7). - -Xerox Network Services (XNS) addresses - -XNS addresses are 48-bit (6-octet) quantities, encoded in MSB order. The -type of XNS addresses is six (6). - -AppleTalk Datagram Delivery Protocol (DDP) addresses - -AppleTalk DDP addresses consist of an 8-bit node number and a 16-bit network -number. The first octet of the address is the node number; the remaining two -octets encode the network number in MSB order. The type of AppleTalk DDP -addresses is sixteen (16). - -DECnet Phase IV addresses - -DECnet Phase IV addresses are 16-bit addresses, encoded in LSB order. The -type of DECnet Phase IV addresses is twelve (12). - - -draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 - - -8.2. KDC messages - -8.2.1. UDP/IP transport - -When contacting a Kerberos server (KDC) for a KRB_KDC_REQ request using UDP -IP transport, the client shall send a UDP datagram containing only an -encoding of the request to port 88 (decimal) at the KDC's IP address; the -KDC will respond with a reply datagram containing only an encoding of the -reply message (either a KRB_ERROR or a KRB_KDC_REP) to the sending port at -the sender's IP address. Kerberos servers supporting IP transport must -accept UDP requests on port 88 (decimal). The response to a request made -through UDP/IP transport must also use UDP/IP transport. - -8.2.2. TCP/IP transport - -Kerberos servers (KDC's) must accept TCP requests on port 88 (decimal). When -the KRB_KDC_REQ message is sent to the KDC over a TCP stream, a new -connection will be established for each authentication exchange (request and -response). The KRB_KDC_REP or KRB_ERROR message will be returned to the -client on the same TCP stream that was established for the request. The -connection will be broken after the reply has been received (or upon -time-out). Care must be taken in managing TCP/IP connections with the KDC to -prevent denial of service attacks based on the number of TCP/IP connections -with the KDC that remain open. If multiple exchanges with the KDC are needed -for certain forms of preauthentication, multiple TCP connections will be -required. The response to a request made through TCP/IP transport must also -use TCP/IP transport. - -The first four octets of the TCP stream used to transmit the request request -will encode in network byte order the length of the request (KRB_KDC_REQ), -and the length will be followed by the request itself. The response will -similarly be preceeded by a 4 octet encoding in network byte order of the -length of the KRB_KDC_REP or the KRB_ERROR message and will be followed by -the KRB_KDC_REP or the KRB_ERROR response. - -8.2.3. OSI transport - -During authentication of an OSI client to an OSI server, the mutual -authentication of an OSI server to an OSI client, the transfer of -credentials from an OSI client to an OSI server, or during exchange of -private or integrity checked messages, Kerberos protocol messages may be -treated as opaque objects and the type of the authentication mechanism will -be: - -OBJECT IDENTIFIER ::= {iso (1), org(3), dod(6),internet(1), security(5),kerberosv5(2)} - -Depending on the situation, the opaque object will be an authentication -header (KRB_AP_REQ), an authentication reply (KRB_AP_REP), a safe message -(KRB_SAFE), a private message (KRB_PRIV), or a credentials message -(KRB_CRED). The opaque data contains an application code as specified in the -ASN.1 description for each message. The application code may be used by -Kerberos to determine the message type. - - - -draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 - -8.2.3. Name of the TGS - -The principal identifier of the ticket-granting service shall be composed of -three parts: (1) the realm of the KDC issuing the TGS ticket (2) a two-part -name of type NT-SRV-INST, with the first part "krbtgt" and the second part -the name of the realm which will accept the ticket-granting ticket. For -example, a ticket-granting ticket issued by the ATHENA.MIT.EDU realm to be -used to get tickets from the ATHENA.MIT.EDU KDC has a principal identifier -of "ATHENA.MIT.EDU" (realm), ("krbtgt", "ATHENA.MIT.EDU") (name). A -ticket-granting ticket issued by the ATHENA.MIT.EDU realm to be used to get -tickets from the MIT.EDU realm has a principal identifier of -"ATHENA.MIT.EDU" (realm), ("krbtgt", "MIT.EDU") (name). - -8.3. Protocol constants and associated values - -The following tables list constants used in the protocol and defines their -meanings. - -Encryption type etype value block size minimum pad size confounder size -NULL 0 1 0 0 -des-cbc-crc 1 8 4 8 -des-cbc-md4 2 8 0 8 -des-cbc-md5 3 8 0 8 - 4 -des3-cbc-md5 5 8 0 8 - 6 -des3-cbc-sha1 7 8 0 8 -sign-dsa-generate 8 (pkinit) -encrypt-rsa-priv 9 (pkinit) -encrypt-rsa-pub 10 (pkinit) -rsa-pub-md5 11 (pkinit) -rsa-pub-sha1 12 (pkinit) -ENCTYPE_PK_CROSS 48 (reserved for pkcross) - 0x8003 - -Checksum type sumtype value checksum size -CRC32 1 4 -rsa-md4 2 16 -rsa-md4-des 3 24 -des-mac 4 16 -des-mac-k 5 8 -rsa-md4-des-k 6 16 -rsa-md5 7 16 -rsa-md5-des 8 24 -rsa-md5-des3 9 24 -hmac-sha1-des3 10 20 (I had this as 10, is it 12) - -padata type padata-type value - -PA-TGS-REQ 1 -PA-ENC-TIMESTAMP 2 -PA-PW-SALT 3 - 4 -PA-ENC-UNIX-TIME 5 - - -draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 - -PA-SANDIA-SECUREID 6 -PA-SESAME 7 -PA-OSF-DCE 8 -PA-CYBERSAFE-SECUREID 9 -PA-AFS3-SALT 10 -PA-ETYPE-INFO 11 -SAM-CHALLENGE 12 (sam/otp) -SAM-RESPONSE 13 (sam/otp) -PA-PK-AS-REQ 14 (pkinit) -PA-PK-AS-REP 15 (pkinit) -PA-PK-AS-SIGN 16 (pkinit) -PA-PK-KEY-REQ 17 (pkinit) -PA-PK-KEY-REP 18 (pkinit) -PA-USE-SPECIFIED-KVNO 20 - -authorization data type ad-type value -AD-KDC-ISSUED 1 -AD-INTENDED-FOR-SERVER 2 -AD-INTENDED-FOR-APPLICATION-CLASS 3 -AD-IF-RELEVANT 4 -AD-OR 5 -AD-MANDATORY-TICKET-EXTENSIONS 6 -AD-IN-TICKET-EXTENSIONS 7 -reserved values 8-63 -OSF-DCE 64 -SESAME 65 - -Ticket Extension Types - -TE-TYPE-NULL 0 Null ticket extension -TE-TYPE-EXTERNAL-ADATA 1 Integrity protected authorization data - 2 TE-TYPE-PKCROSS-KDC (I have reservations) -TE-TYPE-PKCROSS-CLIENT 3 PKCROSS cross realm key ticket -TE-TYPE-CYBERSAFE-EXT 4 Assigned to CyberSafe Corp - 5 TE-TYPE-DEST-HOST (I have reservations) - -alternate authentication type method-type value -reserved values 0-63 -ATT-CHALLENGE-RESPONSE 64 - -transited encoding type tr-type value -DOMAIN-X500-COMPRESS 1 -reserved values all others - -Label Value Meaning or MIT code - -pvno 5 current Kerberos protocol version number - -message types - -KRB_AS_REQ 10 Request for initial authentication -KRB_AS_REP 11 Response to KRB_AS_REQ request -KRB_TGS_REQ 12 Request for authentication based on TGT -KRB_TGS_REP 13 Response to KRB_TGS_REQ request - - -draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 - -KRB_AP_REQ 14 application request to server -KRB_AP_REP 15 Response to KRB_AP_REQ_MUTUAL -KRB_SAFE 20 Safe (checksummed) application message -KRB_PRIV 21 Private (encrypted) application message -KRB_CRED 22 Private (encrypted) message to forward credentials -KRB_ERROR 30 Error response - -name types - -KRB_NT_UNKNOWN 0 Name type not known -KRB_NT_PRINCIPAL 1 Just the name of the principal as in DCE, or for users -KRB_NT_SRV_INST 2 Service and other unique instance (krbtgt) -KRB_NT_SRV_HST 3 Service with host name as instance (telnet, rcommands) -KRB_NT_SRV_XHST 4 Service with host as remaining components -KRB_NT_UID 5 Unique ID -KRB_NT_X500_PRINCIPAL 6 Encoded X.509 Distingished name [RFC 1779] - -error codes - -KDC_ERR_NONE 0 No error -KDC_ERR_NAME_EXP 1 Client's entry in database has expired -KDC_ERR_SERVICE_EXP 2 Server's entry in database has expired -KDC_ERR_BAD_PVNO 3 Requested protocol version number not - supported -KDC_ERR_C_OLD_MAST_KVNO 4 Client's key encrypted in old master key -KDC_ERR_S_OLD_MAST_KVNO 5 Server's key encrypted in old master key -KDC_ERR_C_PRINCIPAL_UNKNOWN 6 Client not found in Kerberos database -KDC_ERR_S_PRINCIPAL_UNKNOWN 7 Server not found in Kerberos database -KDC_ERR_PRINCIPAL_NOT_UNIQUE 8 Multiple principal entries in database -KDC_ERR_NULL_KEY 9 The client or server has a null key -KDC_ERR_CANNOT_POSTDATE 10 Ticket not eligible for postdating -KDC_ERR_NEVER_VALID 11 Requested start time is later than end time -KDC_ERR_POLICY 12 KDC policy rejects request -KDC_ERR_BADOPTION 13 KDC cannot accommodate requested option -KDC_ERR_ETYPE_NOSUPP 14 KDC has no support for encryption type -KDC_ERR_SUMTYPE_NOSUPP 15 KDC has no support for checksum type -KDC_ERR_PADATA_TYPE_NOSUPP 16 KDC has no support for padata type -KDC_ERR_TRTYPE_NOSUPP 17 KDC has no support for transited type -KDC_ERR_CLIENT_REVOKED 18 Clients credentials have been revoked -KDC_ERR_SERVICE_REVOKED 19 Credentials for server have been revoked -KDC_ERR_TGT_REVOKED 20 TGT has been revoked -KDC_ERR_CLIENT_NOTYET 21 Client not yet valid - try again later -KDC_ERR_SERVICE_NOTYET 22 Server not yet valid - try again later -KDC_ERR_KEY_EXPIRED 23 Password has expired - change password - to reset -KDC_ERR_PREAUTH_FAILED 24 Pre-authentication information was invalid -KDC_ERR_PREAUTH_REQUIRED 25 Additional pre-authenticationrequired [40] -KDC_ERR_SERVER_NOMATCH 26 Requested server and ticket don't match -KDC_ERR_MUST_USE_USER2USER 27 Server principal valid for user2user only -KDC_ERR_PATH_NOT_ACCPETED 28 KDC Policy rejects transited path -KRB_AP_ERR_BAD_INTEGRITY 31 Integrity check on decrypted field failed -KRB_AP_ERR_TKT_EXPIRED 32 Ticket expired -KRB_AP_ERR_TKT_NYV 33 Ticket not yet valid -KRB_AP_ERR_REPEAT 34 Request is a replay -KRB_AP_ERR_NOT_US 35 The ticket isn't for us -KRB_AP_ERR_BADMATCH 36 Ticket and authenticator don't match - - -draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 - -KRB_AP_ERR_SKEW 37 Clock skew too great -KRB_AP_ERR_BADADDR 38 Incorrect net address -KRB_AP_ERR_BADVERSION 39 Protocol version mismatch -KRB_AP_ERR_MSG_TYPE 40 Invalid msg type -KRB_AP_ERR_MODIFIED 41 Message stream modified -KRB_AP_ERR_BADORDER 42 Message out of order -KRB_AP_ERR_BADKEYVER 44 Specified version of key is not available -KRB_AP_ERR_NOKEY 45 Service key not available -KRB_AP_ERR_MUT_FAIL 46 Mutual authentication failed -KRB_AP_ERR_BADDIRECTION 47 Incorrect message direction -KRB_AP_ERR_METHOD 48 Alternative authentication method required -KRB_AP_ERR_BADSEQ 49 Incorrect sequence number in message -KRB_AP_ERR_INAPP_CKSUM 50 Inappropriate type of checksum in message -KRB_AP_PATH_NOT_ACCEPTED 51 Policy rejects transited path -KRB_ERR_GENERIC 60 Generic error (description in e-text) -KRB_ERR_FIELD_TOOLONG 61 Field is too long for this implementation -KDC_ERROR_CLIENT_NOT_TRUSTED 62 (pkinit) -KDC_ERROR_KDC_NOT_TRUSTED 63 (pkinit) -KDC_ERROR_INVALID_SIG 64 (pkinit) -KDC_ERR_KEY_TOO_WEAK 65 (pkinit) -KDC_ERR_CERTIFICATE_MISMATCH 66 (pkinit) - -9. Interoperability requirements - -Version 5 of the Kerberos protocol supports a myriad of options. Among these -are multiple encryption and checksum types, alternative encoding schemes for -the transited field, optional mechanisms for pre-authentication, the -handling of tickets with no addresses, options for mutual authentication, -user to user authentication, support for proxies, forwarding, postdating, -and renewing tickets, the format of realm names, and the handling of -authorization data. - -In order to ensure the interoperability of realms, it is necessary to define -a minimal configuration which must be supported by all implementations. This -minimal configuration is subject to change as technology does. For example, -if at some later date it is discovered that one of the required encryption -or checksum algorithms is not secure, it will be replaced. - -9.1. Specification 2 - -This section defines the second specification of these options. -Implementations which are configured in this way can be said to support -Kerberos Version 5 Specification 2 (5.1). Specification 1 (depricated) may -be found in RFC1510. - -Transport - -TCP/IP and UDP/IP transport must be supported by KDCs claiming conformance -to specification 2. Kerberos clients claiming conformance to specification 2 -must support UDP/IP transport for messages with the KDC and may support -TCP/IP transport. - -Encryption and checksum methods - - - -draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 - -The following encryption and checksum mechanisms must be supported. -Implementations may support other mechanisms as well, but the additional -mechanisms may only be used when communicating with principals known to also -support them: This list is to be determined. - -Encryption: DES-CBC-MD5 -Checksums: CRC-32, DES-MAC, DES-MAC-K, and DES-MD5 - -Realm Names - -All implementations must understand hierarchical realms in both the Internet -Domain and the X.500 style. When a ticket granting ticket for an unknown -realm is requested, the KDC must be able to determine the names of the -intermediate realms between the KDCs realm and the requested realm. - -Transited field encoding - -DOMAIN-X500-COMPRESS (described in section 3.3.3.2) must be supported. -Alternative encodings may be supported, but they may be used only when that -encoding is supported by ALL intermediate realms. - -Pre-authentication methods - -The TGS-REQ method must be supported. The TGS-REQ method is not used on the -initial request. The PA-ENC-TIMESTAMP method must be supported by clients -but whether it is enabled by default may be determined on a realm by realm -basis. If not used in the initial request and the error -KDC_ERR_PREAUTH_REQUIRED is returned specifying PA-ENC-TIMESTAMP as an -acceptable method, the client should retry the initial request using the -PA-ENC-TIMESTAMP preauthentication method. Servers need not support the -PA-ENC-TIMESTAMP method, but if not supported the server should ignore the -presence of PA-ENC-TIMESTAMP pre-authentication in a request. - -Mutual authentication - -Mutual authentication (via the KRB_AP_REP message) must be supported. - -Ticket addresses and flags - -All KDC's must pass on tickets that carry no addresses (i.e. if a TGT -contains no addresses, the KDC will return derivative tickets), but each -realm may set its own policy for issuing such tickets, and each application -server will set its own policy with respect to accepting them. - -Proxies and forwarded tickets must be supported. Individual realms and -application servers can set their own policy on when such tickets will be -accepted. - -All implementations must recognize renewable and postdated tickets, but need -not actually implement them. If these options are not supported, the -starttime and endtime in the ticket shall specify a ticket's entire useful -life. When a postdated ticket is decoded by a server, all implementations -shall make the presence of the postdated flag visible to the calling server. - - - -draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 - -User-to-user authentication - -Support for user to user authentication (via the ENC-TKT-IN-SKEY KDC option) -must be provided by implementations, but individual realms may decide as a -matter of policy to reject such requests on a per-principal or realm-wide -basis. - -Authorization data - -Implementations must pass all authorization data subfields from -ticket-granting tickets to any derivative tickets unless directed to -suppress a subfield as part of the definition of that registered subfield -type (it is never incorrect to pass on a subfield, and no registered -subfield types presently specify suppression at the KDC). - -Implementations must make the contents of any authorization data subfields -available to the server when a ticket is used. Implementations are not -required to allow clients to specify the contents of the authorization data -fields. - -9.2. Recommended KDC values - -Following is a list of recommended values for a KDC implementation, based on -the list of suggested configuration constants (see section 4.4). - -minimum lifetime 5 minutes -maximum renewable lifetime 1 week -maximum ticket lifetime 1 day -empty addresses only when suitable restrictions appear - in authorization data -proxiable, etc. Allowed. - -10. REFERENCES - -[NT94] B. Clifford Neuman and Theodore Y. Ts'o, "An Authenti- - cation Service for Computer Networks," IEEE Communica- - tions Magazine, Vol. 32(9), pp. 33-38 (September 1994). - -[MNSS87] S. P. Miller, B. C. Neuman, J. I. Schiller, and J. H. - Saltzer, Section E.2.1: Kerberos Authentication and - Authorization System, M.I.T. Project Athena, Cambridge, - Massachusetts (December 21, 1987). - -[SNS88] J. G. Steiner, B. C. Neuman, and J. I. Schiller, "Ker- - beros: An Authentication Service for Open Network Sys- - tems," pp. 191-202 in Usenix Conference Proceedings, - Dallas, Texas (February, 1988). - -[NS78] Roger M. Needham and Michael D. Schroeder, "Using - Encryption for Authentication in Large Networks of Com- - puters," Communications of the ACM, Vol. 21(12), - pp. 993-999 (December, 1978). - -[DS81] Dorothy E. Denning and Giovanni Maria Sacco, "Time- - - -draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 - - stamps in Key Distribution Protocols," Communications - of the ACM, Vol. 24(8), pp. 533-536 (August 1981). - -[KNT92] John T. Kohl, B. Clifford Neuman, and Theodore Y. Ts'o, - "The Evolution of the Kerberos Authentication Service," - in an IEEE Computer Society Text soon to be published - (June 1992). - -[Neu93] B. Clifford Neuman, "Proxy-Based Authorization and - Accounting for Distributed Systems," in Proceedings of - the 13th International Conference on Distributed Com- - puting Systems, Pittsburgh, PA (May, 1993). - -[DS90] Don Davis and Ralph Swick, "Workstation Services and - Kerberos Authentication at Project Athena," Technical - Memorandum TM-424, MIT Laboratory for Computer Science - (February 1990). - -[LGDSR87] P. J. Levine, M. R. Gretzinger, J. M. Diaz, W. E. Som- - merfeld, and K. Raeburn, Section E.1: Service Manage- - ment System, M.I.T. Project Athena, Cambridge, Mas- - sachusetts (1987). - -[X509-88] CCITT, Recommendation X.509: The Directory Authentica- - tion Framework, December 1988. - -[Pat92]. J. Pato, Using Pre-Authentication to Avoid Password - Guessing Attacks, Open Software Foundation DCE Request - for Comments 26 (December 1992). - -[DES77] National Bureau of Standards, U.S. Department of Com- - merce, "Data Encryption Standard," Federal Information - Processing Standards Publication 46, Washington, DC - (1977). - -[DESM80] National Bureau of Standards, U.S. Department of Com- - merce, "DES Modes of Operation," Federal Information - Processing Standards Publication 81, Springfield, VA - (December 1980). - -[SG92] Stuart G. Stubblebine and Virgil D. Gligor, "On Message - Integrity in Cryptographic Protocols," in Proceedings - of the IEEE Symposium on Research in Security and - Privacy, Oakland, California (May 1992). - -[IS3309] International Organization for Standardization, "ISO - Information Processing Systems - Data Communication - - High-Level Data Link Control Procedure - Frame Struc- - ture," IS 3309 (October 1984). 3rd Edition. - -[MD4-92] R. Rivest, "The MD4 Message Digest Algorithm," RFC - 1320, MIT Laboratory for Computer Science (April - 1992). - - - -draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 - -[MD5-92] R. Rivest, "The MD5 Message Digest Algorithm," RFC - 1321, MIT Laboratory for Computer Science (April - 1992). - -[KBC96] H. Krawczyk, M. Bellare, and R. Canetti, "HMAC: Keyed- - Hashing for Message Authentication," Working Draft - draft-ietf-ipsec-hmac-md5-01.txt, (August 1996). - -A. Pseudo-code for protocol processing - -This appendix provides pseudo-code describing how the messages are to be -constructed and interpreted by clients and servers. - -A.1. KRB_AS_REQ generation - - request.pvno := protocol version; /* pvno = 5 */ - request.msg-type := message type; /* type = KRB_AS_REQ */ - - if(pa_enc_timestamp_required) then - request.padata.padata-type = PA-ENC-TIMESTAMP; - get system_time; - padata-body.patimestamp,pausec = system_time; - encrypt padata-body into request.padata.padata-value - using client.key; /* derived from password */ - endif - - body.kdc-options := users's preferences; - body.cname := user's name; - body.realm := user's realm; - body.sname := service's name; /* usually "krbtgt", "localrealm" */ - if (body.kdc-options.POSTDATED is set) then - body.from := requested starting time; - else - omit body.from; - endif - body.till := requested end time; - if (body.kdc-options.RENEWABLE is set) then - body.rtime := requested final renewal time; - endif - body.nonce := random_nonce(); - body.etype := requested etypes; - if (user supplied addresses) then - body.addresses := user's addresses; - else - omit body.addresses; - endif - omit body.enc-authorization-data; - request.req-body := body; - - kerberos := lookup(name of local kerberos server (or servers)); - send(packet,kerberos); - - wait(for response); - if (timed_out) then - - -draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 - - retry or use alternate server; - endif - -A.2. KRB_AS_REQ verification and KRB_AS_REP generation - - decode message into req; - - client := lookup(req.cname,req.realm); - server := lookup(req.sname,req.realm); - - get system_time; - kdc_time := system_time.seconds; - - if (!client) then - /* no client in Database */ - error_out(KDC_ERR_C_PRINCIPAL_UNKNOWN); - endif - if (!server) then - /* no server in Database */ - error_out(KDC_ERR_S_PRINCIPAL_UNKNOWN); - endif - - if(client.pa_enc_timestamp_required and - pa_enc_timestamp not present) then - error_out(KDC_ERR_PREAUTH_REQUIRED(PA_ENC_TIMESTAMP)); - endif - - if(pa_enc_timestamp present) then - decrypt req.padata-value into decrypted_enc_timestamp - using client.key; - using auth_hdr.authenticator.subkey; - if (decrypt_error()) then - error_out(KRB_AP_ERR_BAD_INTEGRITY); - if(decrypted_enc_timestamp is not within allowable skew) then - error_out(KDC_ERR_PREAUTH_FAILED); - endif - if(decrypted_enc_timestamp and usec is replay) - error_out(KDC_ERR_PREAUTH_FAILED); - endif - add decrypted_enc_timestamp and usec to replay cache; - endif - - use_etype := first supported etype in req.etypes; - - if (no support for req.etypes) then - error_out(KDC_ERR_ETYPE_NOSUPP); - endif - - new_tkt.vno := ticket version; /* = 5 */ - new_tkt.sname := req.sname; - new_tkt.srealm := req.srealm; - reset all flags in new_tkt.flags; - - /* It should be noted that local policy may affect the */ - - -draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 - - /* processing of any of these flags. For example, some */ - /* realms may refuse to issue renewable tickets */ - - if (req.kdc-options.FORWARDABLE is set) then - set new_tkt.flags.FORWARDABLE; - endif - if (req.kdc-options.PROXIABLE is set) then - set new_tkt.flags.PROXIABLE; - endif - - if (req.kdc-options.ALLOW-POSTDATE is set) then - set new_tkt.flags.MAY-POSTDATE; - endif - if ((req.kdc-options.RENEW is set) or - (req.kdc-options.VALIDATE is set) or - (req.kdc-options.PROXY is set) or - (req.kdc-options.FORWARDED is set) or - (req.kdc-options.ENC-TKT-IN-SKEY is set)) then - error_out(KDC_ERR_BADOPTION); - endif - - new_tkt.session := random_session_key(); - new_tkt.cname := req.cname; - new_tkt.crealm := req.crealm; - new_tkt.transited := empty_transited_field(); - - new_tkt.authtime := kdc_time; - - if (req.kdc-options.POSTDATED is set) then - if (against_postdate_policy(req.from)) then - error_out(KDC_ERR_POLICY); - endif - set new_tkt.flags.POSTDATED; - set new_tkt.flags.INVALID; - new_tkt.starttime := req.from; - else - omit new_tkt.starttime; /* treated as authtime when omitted */ - endif - if (req.till = 0) then - till := infinity; - else - till := req.till; - endif - - new_tkt.endtime := min(till, - new_tkt.starttime+client.max_life, - new_tkt.starttime+server.max_life, - new_tkt.starttime+max_life_for_realm); - - if ((req.kdc-options.RENEWABLE-OK is set) and - (new_tkt.endtime < req.till)) then - /* we set the RENEWABLE option for later processing */ - set req.kdc-options.RENEWABLE; - req.rtime := req.till; - - -draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 - - endif - - if (req.rtime = 0) then - rtime := infinity; - else - rtime := req.rtime; - endif - - if (req.kdc-options.RENEWABLE is set) then - set new_tkt.flags.RENEWABLE; - new_tkt.renew-till := min(rtime, - new_tkt.starttime+client.max_rlife, - new_tkt.starttime+server.max_rlife, - new_tkt.starttime+max_rlife_for_realm); - else - omit new_tkt.renew-till; /* only present if RENEWABLE */ - endif - - if (req.addresses) then - new_tkt.caddr := req.addresses; - else - omit new_tkt.caddr; - endif - - new_tkt.authorization_data := empty_authorization_data(); - - encode to-be-encrypted part of ticket into OCTET STRING; - new_tkt.enc-part := encrypt OCTET STRING - using etype_for_key(server.key), server.key, server.p_kvno; - - /* Start processing the response */ - - resp.pvno := 5; - resp.msg-type := KRB_AS_REP; - resp.cname := req.cname; - resp.crealm := req.realm; - resp.ticket := new_tkt; - - resp.key := new_tkt.session; - resp.last-req := fetch_last_request_info(client); - resp.nonce := req.nonce; - resp.key-expiration := client.expiration; - resp.flags := new_tkt.flags; - - resp.authtime := new_tkt.authtime; - resp.starttime := new_tkt.starttime; - resp.endtime := new_tkt.endtime; - - if (new_tkt.flags.RENEWABLE) then - resp.renew-till := new_tkt.renew-till; - endif - - resp.realm := new_tkt.realm; - resp.sname := new_tkt.sname; - - -draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 - - - resp.caddr := new_tkt.caddr; - - encode body of reply into OCTET STRING; - - resp.enc-part := encrypt OCTET STRING - using use_etype, client.key, client.p_kvno; - send(resp); - -A.3. KRB_AS_REP verification - - decode response into resp; - - if (resp.msg-type = KRB_ERROR) then - if(error = KDC_ERR_PREAUTH_REQUIRED(PA_ENC_TIMESTAMP)) then - set pa_enc_timestamp_required; - goto KRB_AS_REQ; - endif - process_error(resp); - return; - endif - - /* On error, discard the response, and zero the session key */ - /* from the response immediately */ - - key = get_decryption_key(resp.enc-part.kvno, resp.enc-part.etype, - resp.padata); - unencrypted part of resp := decode of decrypt of resp.enc-part - using resp.enc-part.etype and key; - zero(key); - - if (common_as_rep_tgs_rep_checks fail) then - destroy resp.key; - return error; - endif - - if near(resp.princ_exp) then - print(warning message); - endif - save_for_later(ticket,session,client,server,times,flags); - -A.4. KRB_AS_REP and KRB_TGS_REP common checks - - if (decryption_error() or - (req.cname != resp.cname) or - (req.realm != resp.crealm) or - (req.sname != resp.sname) or - (req.realm != resp.realm) or - (req.nonce != resp.nonce) or - (req.addresses != resp.caddr)) then - destroy resp.key; - return KRB_AP_ERR_MODIFIED; - endif - - - -draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 - - /* make sure no flags are set that shouldn't be, and that all that */ - /* should be are set */ - if (!check_flags_for_compatability(req.kdc-options,resp.flags)) then - destroy resp.key; - return KRB_AP_ERR_MODIFIED; - endif - - if ((req.from = 0) and - (resp.starttime is not within allowable skew)) then - destroy resp.key; - return KRB_AP_ERR_SKEW; - endif - if ((req.from != 0) and (req.from != resp.starttime)) then - destroy resp.key; - return KRB_AP_ERR_MODIFIED; - endif - if ((req.till != 0) and (resp.endtime > req.till)) then - destroy resp.key; - return KRB_AP_ERR_MODIFIED; - endif - - if ((req.kdc-options.RENEWABLE is set) and - (req.rtime != 0) and (resp.renew-till > req.rtime)) then - destroy resp.key; - return KRB_AP_ERR_MODIFIED; - endif - if ((req.kdc-options.RENEWABLE-OK is set) and - (resp.flags.RENEWABLE) and - (req.till != 0) and - (resp.renew-till > req.till)) then - destroy resp.key; - return KRB_AP_ERR_MODIFIED; - endif - -A.5. KRB_TGS_REQ generation - - /* Note that make_application_request might have to recursivly */ - /* call this routine to get the appropriate ticket-granting ticket */ - - request.pvno := protocol version; /* pvno = 5 */ - request.msg-type := message type; /* type = KRB_TGS_REQ */ - - body.kdc-options := users's preferences; - /* If the TGT is not for the realm of the end-server */ - /* then the sname will be for a TGT for the end-realm */ - /* and the realm of the requested ticket (body.realm) */ - /* will be that of the TGS to which the TGT we are */ - /* sending applies */ - body.sname := service's name; - body.realm := service's realm; - - if (body.kdc-options.POSTDATED is set) then - body.from := requested starting time; - else - - -draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 - - omit body.from; - endif - body.till := requested end time; - if (body.kdc-options.RENEWABLE is set) then - body.rtime := requested final renewal time; - endif - body.nonce := random_nonce(); - body.etype := requested etypes; - if (user supplied addresses) then - body.addresses := user's addresses; - else - omit body.addresses; - endif - - body.enc-authorization-data := user-supplied data; - if (body.kdc-options.ENC-TKT-IN-SKEY) then - body.additional-tickets_ticket := second TGT; - endif - - request.req-body := body; - check := generate_checksum (req.body,checksumtype); - - request.padata[0].padata-type := PA-TGS-REQ; - request.padata[0].padata-value := create a KRB_AP_REQ using - the TGT and checksum - - /* add in any other padata as required/supplied */ - - kerberos := lookup(name of local kerberose server (or servers)); - send(packet,kerberos); - - wait(for response); - if (timed_out) then - retry or use alternate server; - endif - -A.6. KRB_TGS_REQ verification and KRB_TGS_REP generation - - /* note that reading the application request requires first - determining the server for which a ticket was issued, and choosing the - correct key for decryption. The name of the server appears in the - plaintext part of the ticket. */ - - if (no KRB_AP_REQ in req.padata) then - error_out(KDC_ERR_PADATA_TYPE_NOSUPP); - endif - verify KRB_AP_REQ in req.padata; - - /* Note that the realm in which the Kerberos server is operating is - determined by the instance from the ticket-granting ticket. The realm - in the ticket-granting ticket is the realm under which the ticket - granting ticket was issued. It is possible for a single Kerberos - server to support more than one realm. */ - - - -draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 - - auth_hdr := KRB_AP_REQ; - tgt := auth_hdr.ticket; - - if (tgt.sname is not a TGT for local realm and is not req.sname) then - error_out(KRB_AP_ERR_NOT_US); - - realm := realm_tgt_is_for(tgt); - - decode remainder of request; - - if (auth_hdr.authenticator.cksum is missing) then - error_out(KRB_AP_ERR_INAPP_CKSUM); - endif - - if (auth_hdr.authenticator.cksum type is not supported) then - error_out(KDC_ERR_SUMTYPE_NOSUPP); - endif - if (auth_hdr.authenticator.cksum is not both collision-proof and keyed) then - error_out(KRB_AP_ERR_INAPP_CKSUM); - endif - - set computed_checksum := checksum(req); - if (computed_checksum != auth_hdr.authenticatory.cksum) then - error_out(KRB_AP_ERR_MODIFIED); - endif - - server := lookup(req.sname,realm); - - if (!server) then - if (is_foreign_tgt_name(req.sname)) then - server := best_intermediate_tgs(req.sname); - else - /* no server in Database */ - error_out(KDC_ERR_S_PRINCIPAL_UNKNOWN); - endif - endif - - session := generate_random_session_key(); - - use_etype := first supported etype in req.etypes; - - if (no support for req.etypes) then - error_out(KDC_ERR_ETYPE_NOSUPP); - endif - - new_tkt.vno := ticket version; /* = 5 */ - new_tkt.sname := req.sname; - new_tkt.srealm := realm; - reset all flags in new_tkt.flags; - - /* It should be noted that local policy may affect the */ - /* processing of any of these flags. For example, some */ - /* realms may refuse to issue renewable tickets */ - - - -draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 - - new_tkt.caddr := tgt.caddr; - resp.caddr := NULL; /* We only include this if they change */ - if (req.kdc-options.FORWARDABLE is set) then - if (tgt.flags.FORWARDABLE is reset) then - error_out(KDC_ERR_BADOPTION); - endif - set new_tkt.flags.FORWARDABLE; - endif - if (req.kdc-options.FORWARDED is set) then - if (tgt.flags.FORWARDABLE is reset) then - error_out(KDC_ERR_BADOPTION); - endif - set new_tkt.flags.FORWARDED; - new_tkt.caddr := req.addresses; - resp.caddr := req.addresses; - endif - if (tgt.flags.FORWARDED is set) then - set new_tkt.flags.FORWARDED; - endif - - if (req.kdc-options.PROXIABLE is set) then - if (tgt.flags.PROXIABLE is reset) - error_out(KDC_ERR_BADOPTION); - endif - set new_tkt.flags.PROXIABLE; - endif - if (req.kdc-options.PROXY is set) then - if (tgt.flags.PROXIABLE is reset) then - error_out(KDC_ERR_BADOPTION); - endif - set new_tkt.flags.PROXY; - new_tkt.caddr := req.addresses; - resp.caddr := req.addresses; - endif - - if (req.kdc-options.ALLOW-POSTDATE is set) then - if (tgt.flags.MAY-POSTDATE is reset) - error_out(KDC_ERR_BADOPTION); - endif - set new_tkt.flags.MAY-POSTDATE; - endif - if (req.kdc-options.POSTDATED is set) then - if (tgt.flags.MAY-POSTDATE is reset) then - error_out(KDC_ERR_BADOPTION); - endif - set new_tkt.flags.POSTDATED; - set new_tkt.flags.INVALID; - if (against_postdate_policy(req.from)) then - error_out(KDC_ERR_POLICY); - endif - new_tkt.starttime := req.from; - endif - - if (req.kdc-options.VALIDATE is set) then - - -draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 - - if (tgt.flags.INVALID is reset) then - error_out(KDC_ERR_POLICY); - endif - if (tgt.starttime > kdc_time) then - error_out(KRB_AP_ERR_NYV); - endif - if (check_hot_list(tgt)) then - error_out(KRB_AP_ERR_REPEAT); - endif - tkt := tgt; - reset new_tkt.flags.INVALID; - endif - - if (req.kdc-options.(any flag except ENC-TKT-IN-SKEY, RENEW, - and those already processed) is set) then - error_out(KDC_ERR_BADOPTION); - endif - - new_tkt.authtime := tgt.authtime; - - if (req.kdc-options.RENEW is set) then - /* Note that if the endtime has already passed, the ticket would */ - /* have been rejected in the initial authentication stage, so */ - /* there is no need to check again here */ - if (tgt.flags.RENEWABLE is reset) then - error_out(KDC_ERR_BADOPTION); - endif - if (tgt.renew-till < kdc_time) then - error_out(KRB_AP_ERR_TKT_EXPIRED); - endif - tkt := tgt; - new_tkt.starttime := kdc_time; - old_life := tgt.endttime - tgt.starttime; - new_tkt.endtime := min(tgt.renew-till, - new_tkt.starttime + old_life); - else - new_tkt.starttime := kdc_time; - if (req.till = 0) then - till := infinity; - else - till := req.till; - endif - new_tkt.endtime := min(till, - new_tkt.starttime+client.max_life, - new_tkt.starttime+server.max_life, - new_tkt.starttime+max_life_for_realm, - tgt.endtime); - - if ((req.kdc-options.RENEWABLE-OK is set) and - (new_tkt.endtime < req.till) and - (tgt.flags.RENEWABLE is set) then - /* we set the RENEWABLE option for later processing */ - set req.kdc-options.RENEWABLE; - req.rtime := min(req.till, tgt.renew-till); - - -draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 - - endif - endif - - if (req.rtime = 0) then - rtime := infinity; - else - rtime := req.rtime; - endif - - if ((req.kdc-options.RENEWABLE is set) and - (tgt.flags.RENEWABLE is set)) then - set new_tkt.flags.RENEWABLE; - new_tkt.renew-till := min(rtime, - new_tkt.starttime+client.max_rlife, - new_tkt.starttime+server.max_rlife, - new_tkt.starttime+max_rlife_for_realm, - tgt.renew-till); - else - new_tkt.renew-till := OMIT; /* leave the renew-till field out */ - endif - if (req.enc-authorization-data is present) then - decrypt req.enc-authorization-data into decrypted_authorization_data - using auth_hdr.authenticator.subkey; - if (decrypt_error()) then - error_out(KRB_AP_ERR_BAD_INTEGRITY); - endif - endif - new_tkt.authorization_data := req.auth_hdr.ticket.authorization_data + - decrypted_authorization_data; - - new_tkt.key := session; - new_tkt.crealm := tgt.crealm; - new_tkt.cname := req.auth_hdr.ticket.cname; - - if (realm_tgt_is_for(tgt) := tgt.realm) then - /* tgt issued by local realm */ - new_tkt.transited := tgt.transited; - else - /* was issued for this realm by some other realm */ - if (tgt.transited.tr-type not supported) then - error_out(KDC_ERR_TRTYPE_NOSUPP); - endif - new_tkt.transited := compress_transited(tgt.transited + tgt.realm) - /* Don't check tranited field if TGT for foreign realm, - * or requested not to check */ - if (is_not_foreign_tgt_name(new_tkt.server) - && req.kdc-options.DISABLE-TRANSITED-CHECK not set) then - /* Check it, so end-server does not have to - * but don't fail, end-server may still accept it */ - if (check_transited_field(new_tkt.transited) == OK) - set new_tkt.flags.TRANSITED-POLICY-CHECKED; - endif - endif - endif - - -draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 - - - encode encrypted part of new_tkt into OCTET STRING; - if (req.kdc-options.ENC-TKT-IN-SKEY is set) then - if (server not specified) then - server = req.second_ticket.client; - endif - if ((req.second_ticket is not a TGT) or - (req.second_ticket.client != server)) then - error_out(KDC_ERR_POLICY); - endif - - new_tkt.enc-part := encrypt OCTET STRING using - using etype_for_key(second-ticket.key), second-ticket.key; - else - new_tkt.enc-part := encrypt OCTET STRING - using etype_for_key(server.key), server.key, server.p_kvno; - endif - - resp.pvno := 5; - resp.msg-type := KRB_TGS_REP; - resp.crealm := tgt.crealm; - resp.cname := tgt.cname; - resp.ticket := new_tkt; - - resp.key := session; - resp.nonce := req.nonce; - resp.last-req := fetch_last_request_info(client); - resp.flags := new_tkt.flags; - - resp.authtime := new_tkt.authtime; - resp.starttime := new_tkt.starttime; - resp.endtime := new_tkt.endtime; - - omit resp.key-expiration; - - resp.sname := new_tkt.sname; - resp.realm := new_tkt.realm; - - if (new_tkt.flags.RENEWABLE) then - resp.renew-till := new_tkt.renew-till; - endif - - encode body of reply into OCTET STRING; - - if (req.padata.authenticator.subkey) - resp.enc-part := encrypt OCTET STRING using use_etype, - req.padata.authenticator.subkey; - else resp.enc-part := encrypt OCTET STRING using use_etype, tgt.key; - - send(resp); - -A.7. KRB_TGS_REP verification - - decode response into resp; - - -draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 - - - if (resp.msg-type = KRB_ERROR) then - process_error(resp); - return; - endif - - /* On error, discard the response, and zero the session key from - the response immediately */ - - if (req.padata.authenticator.subkey) - unencrypted part of resp := decode of decrypt of resp.enc-part - using resp.enc-part.etype and subkey; - else unencrypted part of resp := decode of decrypt of resp.enc-part - using resp.enc-part.etype and tgt's session key; - if (common_as_rep_tgs_rep_checks fail) then - destroy resp.key; - return error; - endif - - check authorization_data as necessary; - save_for_later(ticket,session,client,server,times,flags); - -A.8. Authenticator generation - - body.authenticator-vno := authenticator vno; /* = 5 */ - body.cname, body.crealm := client name; - if (supplying checksum) then - body.cksum := checksum; - endif - get system_time; - body.ctime, body.cusec := system_time; - if (selecting sub-session key) then - select sub-session key; - body.subkey := sub-session key; - endif - if (using sequence numbers) then - select initial sequence number; - body.seq-number := initial sequence; - endif - -A.9. KRB_AP_REQ generation - - obtain ticket and session_key from cache; - - packet.pvno := protocol version; /* 5 */ - packet.msg-type := message type; /* KRB_AP_REQ */ - - if (desired(MUTUAL_AUTHENTICATION)) then - set packet.ap-options.MUTUAL-REQUIRED; - else - reset packet.ap-options.MUTUAL-REQUIRED; - endif - if (using session key for ticket) then - set packet.ap-options.USE-SESSION-KEY; - - -draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 - - else - reset packet.ap-options.USE-SESSION-KEY; - endif - packet.ticket := ticket; /* ticket */ - generate authenticator; - encode authenticator into OCTET STRING; - encrypt OCTET STRING into packet.authenticator using session_key; - -A.10. KRB_AP_REQ verification - - receive packet; - if (packet.pvno != 5) then - either process using other protocol spec - or error_out(KRB_AP_ERR_BADVERSION); - endif - if (packet.msg-type != KRB_AP_REQ) then - error_out(KRB_AP_ERR_MSG_TYPE); - endif - if (packet.ticket.tkt_vno != 5) then - either process using other protocol spec - or error_out(KRB_AP_ERR_BADVERSION); - endif - if (packet.ap_options.USE-SESSION-KEY is set) then - retrieve session key from ticket-granting ticket for - packet.ticket.{sname,srealm,enc-part.etype}; - else - retrieve service key for - packet.ticket.{sname,srealm,enc-part.etype,enc-part.skvno}; - endif - if (no_key_available) then - if (cannot_find_specified_skvno) then - error_out(KRB_AP_ERR_BADKEYVER); - else - error_out(KRB_AP_ERR_NOKEY); - endif - endif - decrypt packet.ticket.enc-part into decr_ticket using retrieved key; - if (decryption_error()) then - error_out(KRB_AP_ERR_BAD_INTEGRITY); - endif - decrypt packet.authenticator into decr_authenticator - using decr_ticket.key; - if (decryption_error()) then - error_out(KRB_AP_ERR_BAD_INTEGRITY); - endif - if (decr_authenticator.{cname,crealm} != - decr_ticket.{cname,crealm}) then - error_out(KRB_AP_ERR_BADMATCH); - endif - if (decr_ticket.caddr is present) then - if (sender_address(packet) is not in decr_ticket.caddr) then - error_out(KRB_AP_ERR_BADADDR); - endif - elseif (application requires addresses) then - - -draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 - - error_out(KRB_AP_ERR_BADADDR); - endif - if (not in_clock_skew(decr_authenticator.ctime, - decr_authenticator.cusec)) then - error_out(KRB_AP_ERR_SKEW); - endif - if (repeated(decr_authenticator.{ctime,cusec,cname,crealm})) then - error_out(KRB_AP_ERR_REPEAT); - endif - save_identifier(decr_authenticator.{ctime,cusec,cname,crealm}); - get system_time; - if ((decr_ticket.starttime-system_time > CLOCK_SKEW) or - (decr_ticket.flags.INVALID is set)) then - /* it hasn't yet become valid */ - error_out(KRB_AP_ERR_TKT_NYV); - endif - if (system_time-decr_ticket.endtime > CLOCK_SKEW) then - error_out(KRB_AP_ERR_TKT_EXPIRED); - endif - if (decr_ticket.transited) then - /* caller may ignore the TRANSITED-POLICY-CHECKED and do - * check anyway */ - if (decr_ticket.flags.TRANSITED-POLICY-CHECKED not set) then - if (check_transited_field(decr_ticket.transited) then - error_out(KDC_AP_PATH_NOT_ACCPETED); - endif - endif - endif - /* caller must check decr_ticket.flags for any pertinent details */ - return(OK, decr_ticket, packet.ap_options.MUTUAL-REQUIRED); - -A.11. KRB_AP_REP generation - - packet.pvno := protocol version; /* 5 */ - packet.msg-type := message type; /* KRB_AP_REP */ - - body.ctime := packet.ctime; - body.cusec := packet.cusec; - if (selecting sub-session key) then - select sub-session key; - body.subkey := sub-session key; - endif - if (using sequence numbers) then - select initial sequence number; - body.seq-number := initial sequence; - endif - - encode body into OCTET STRING; - - select encryption type; - encrypt OCTET STRING into packet.enc-part; - -A.12. KRB_AP_REP verification - - - -draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 - - receive packet; - if (packet.pvno != 5) then - either process using other protocol spec - or error_out(KRB_AP_ERR_BADVERSION); - endif - if (packet.msg-type != KRB_AP_REP) then - error_out(KRB_AP_ERR_MSG_TYPE); - endif - cleartext := decrypt(packet.enc-part) using ticket's session key; - if (decryption_error()) then - error_out(KRB_AP_ERR_BAD_INTEGRITY); - endif - if (cleartext.ctime != authenticator.ctime) then - error_out(KRB_AP_ERR_MUT_FAIL); - endif - if (cleartext.cusec != authenticator.cusec) then - error_out(KRB_AP_ERR_MUT_FAIL); - endif - if (cleartext.subkey is present) then - save cleartext.subkey for future use; - endif - if (cleartext.seq-number is present) then - save cleartext.seq-number for future verifications; - endif - return(AUTHENTICATION_SUCCEEDED); - -A.13. KRB_SAFE generation - - collect user data in buffer; - - /* assemble packet: */ - packet.pvno := protocol version; /* 5 */ - packet.msg-type := message type; /* KRB_SAFE */ - - body.user-data := buffer; /* DATA */ - if (using timestamp) then - get system_time; - body.timestamp, body.usec := system_time; - endif - if (using sequence numbers) then - body.seq-number := sequence number; - endif - body.s-address := sender host addresses; - if (only one recipient) then - body.r-address := recipient host address; - endif - checksum.cksumtype := checksum type; - compute checksum over body; - checksum.checksum := checksum value; /* checksum.checksum */ - packet.cksum := checksum; - packet.safe-body := body; - -A.14. KRB_SAFE verification - - - -draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 - - receive packet; - if (packet.pvno != 5) then - either process using other protocol spec - or error_out(KRB_AP_ERR_BADVERSION); - endif - if (packet.msg-type != KRB_SAFE) then - error_out(KRB_AP_ERR_MSG_TYPE); - endif - if (packet.checksum.cksumtype is not both collision-proof and keyed) then - error_out(KRB_AP_ERR_INAPP_CKSUM); - endif - if (safe_priv_common_checks_ok(packet)) then - set computed_checksum := checksum(packet.body); - if (computed_checksum != packet.checksum) then - error_out(KRB_AP_ERR_MODIFIED); - endif - return (packet, PACKET_IS_GENUINE); - else - return common_checks_error; - endif - -A.15. KRB_SAFE and KRB_PRIV common checks - - if (packet.s-address != O/S_sender(packet)) then - /* O/S report of sender not who claims to have sent it */ - error_out(KRB_AP_ERR_BADADDR); - endif - if ((packet.r-address is present) and - (packet.r-address != local_host_address)) then - /* was not sent to proper place */ - error_out(KRB_AP_ERR_BADADDR); - endif - if (((packet.timestamp is present) and - (not in_clock_skew(packet.timestamp,packet.usec))) or - (packet.timestamp is not present and timestamp expected)) then - error_out(KRB_AP_ERR_SKEW); - endif - if (repeated(packet.timestamp,packet.usec,packet.s-address)) then - error_out(KRB_AP_ERR_REPEAT); - endif - - if (((packet.seq-number is present) and - ((not in_sequence(packet.seq-number)))) or - (packet.seq-number is not present and sequence expected)) then - error_out(KRB_AP_ERR_BADORDER); - endif - if (packet.timestamp not present and packet.seq-number not present) - then - error_out(KRB_AP_ERR_MODIFIED); - endif - - save_identifier(packet.{timestamp,usec,s-address}, - sender_principal(packet)); - - return PACKET_IS_OK; - - -draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 - - -A.16. KRB_PRIV generation - - collect user data in buffer; - - /* assemble packet: */ - packet.pvno := protocol version; /* 5 */ - packet.msg-type := message type; /* KRB_PRIV */ - - packet.enc-part.etype := encryption type; - - body.user-data := buffer; - if (using timestamp) then - get system_time; - body.timestamp, body.usec := system_time; - endif - if (using sequence numbers) then - body.seq-number := sequence number; - endif - body.s-address := sender host addresses; - if (only one recipient) then - body.r-address := recipient host address; - endif - - encode body into OCTET STRING; - - select encryption type; - encrypt OCTET STRING into packet.enc-part.cipher; - -A.17. KRB_PRIV verification - - receive packet; - if (packet.pvno != 5) then - either process using other protocol spec - or error_out(KRB_AP_ERR_BADVERSION); - endif - if (packet.msg-type != KRB_PRIV) then - error_out(KRB_AP_ERR_MSG_TYPE); - endif - - cleartext := decrypt(packet.enc-part) using negotiated key; - if (decryption_error()) then - error_out(KRB_AP_ERR_BAD_INTEGRITY); - endif - - if (safe_priv_common_checks_ok(cleartext)) then - return(cleartext.DATA, PACKET_IS_GENUINE_AND_UNMODIFIED); - else - return common_checks_error; - endif - -A.18. KRB_CRED generation - - invoke KRB_TGS; /* obtain tickets to be provided to peer */ - - -draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 - - - /* assemble packet: */ - packet.pvno := protocol version; /* 5 */ - packet.msg-type := message type; /* KRB_CRED */ - - for (tickets[n] in tickets to be forwarded) do - packet.tickets[n] = tickets[n].ticket; - done - - packet.enc-part.etype := encryption type; - - for (ticket[n] in tickets to be forwarded) do - body.ticket-info[n].key = tickets[n].session; - body.ticket-info[n].prealm = tickets[n].crealm; - body.ticket-info[n].pname = tickets[n].cname; - body.ticket-info[n].flags = tickets[n].flags; - body.ticket-info[n].authtime = tickets[n].authtime; - body.ticket-info[n].starttime = tickets[n].starttime; - body.ticket-info[n].endtime = tickets[n].endtime; - body.ticket-info[n].renew-till = tickets[n].renew-till; - body.ticket-info[n].srealm = tickets[n].srealm; - body.ticket-info[n].sname = tickets[n].sname; - body.ticket-info[n].caddr = tickets[n].caddr; - done - - get system_time; - body.timestamp, body.usec := system_time; - - if (using nonce) then - body.nonce := nonce; - endif - - if (using s-address) then - body.s-address := sender host addresses; - endif - if (limited recipients) then - body.r-address := recipient host address; - endif - - encode body into OCTET STRING; - - select encryption type; - encrypt OCTET STRING into packet.enc-part.cipher - using negotiated encryption key; - -A.19. KRB_CRED verification - - receive packet; - if (packet.pvno != 5) then - either process using other protocol spec - or error_out(KRB_AP_ERR_BADVERSION); - endif - if (packet.msg-type != KRB_CRED) then - error_out(KRB_AP_ERR_MSG_TYPE); - - -draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 - - endif - - cleartext := decrypt(packet.enc-part) using negotiated key; - if (decryption_error()) then - error_out(KRB_AP_ERR_BAD_INTEGRITY); - endif - if ((packet.r-address is present or required) and - (packet.s-address != O/S_sender(packet)) then - /* O/S report of sender not who claims to have sent it */ - error_out(KRB_AP_ERR_BADADDR); - endif - if ((packet.r-address is present) and - (packet.r-address != local_host_address)) then - /* was not sent to proper place */ - error_out(KRB_AP_ERR_BADADDR); - endif - if (not in_clock_skew(packet.timestamp,packet.usec)) then - error_out(KRB_AP_ERR_SKEW); - endif - if (repeated(packet.timestamp,packet.usec,packet.s-address)) then - error_out(KRB_AP_ERR_REPEAT); - endif - if (packet.nonce is required or present) and - (packet.nonce != expected-nonce) then - error_out(KRB_AP_ERR_MODIFIED); - endif - - for (ticket[n] in tickets that were forwarded) do - save_for_later(ticket[n],key[n],principal[n], - server[n],times[n],flags[n]); - return - -A.20. KRB_ERROR generation - - /* assemble packet: */ - packet.pvno := protocol version; /* 5 */ - packet.msg-type := message type; /* KRB_ERROR */ - - get system_time; - packet.stime, packet.susec := system_time; - packet.realm, packet.sname := server name; - - if (client time available) then - packet.ctime, packet.cusec := client_time; - endif - packet.error-code := error code; - if (client name available) then - packet.cname, packet.crealm := client name; - endif - if (error text available) then - packet.e-text := error text; - endif - if (error data available) then - packet.e-data := error data; - - -draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 - - endif - -B. Definition of common authorization data elements - -This appendix contains the definitions of common authorization data -elements. These common authorization data elements are recursivly defined, -meaning the ad-data for these types will itself contain a sequence of -authorization data whose interpretation is affected by the encapsulating -element. Depending on the meaning of the encapsulating element, the -encapsulated elements may be ignored, might be interpreted as issued -directly by the KDC, or they might be stored in a separate plaintext part of -the ticket. The types of the encapsulating elements are specified as part of -the Kerberos specification ebcause the behavior based on these values should -be understood across implementations whereas other elements need only be -understood by the applications which they affect. - -In the definitions that follow, the value of the ad-type for the element -will be specified in the subsection number, and the value of the ad-data -will be as shown in the ASN.1 structure that follows the subsection heading. - -B.1. KDC Issued - -AD-KDCIssued SEQUENCE { - ad-checksum[0] Checksum, - i-realm[1] Realm OPTIONAL, - i-sname[2] PrincipalName OPTIONAL, - elements[3] AuthorizationData. -} - -ad-checksum - A checksum over the elements field using a cryptographic checksum - method that is identical to the checksum used to protect the ticket - itself (i.e. using the same hash function and the same encryption - algorithm used to encrypt the ticket) and using a key derived from the - same key used to protect the ticket. -i-realm, i-sname - The name of the issuing principal if different from the KDC itself. - This field would be used when the KDC can verify the authenticity of - elements signed by the issuing principal and it allows this KDC to - notify the application server of the validity of those elements. -elements - A sequence of authorization data elements issued by the KDC. - -The KDC-issued ad-data field is intended to provide a means for Kerberos -principal credentials to embed within themselves privilege attributes and -other mechanisms for positive authorization, amplifying the priveleges of -the principal beyond what can be done using a credentials without such an -a-data element. - -This can not be provided without this element because the definition of the -authorization-data field allows elements to be added at will by the bearer -of a TGT at the time that they request service tickets and elements may also -be added to a delegated ticket by inclusion in the authenticator. - - - -draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 - -For KDC-issued elements this is prevented because the elements are signed by -the KDC by including a checksum encrypted using the server's key (the same -key used to encrypt the ticket - or a key derived from that key). Elements -encapsulated with in the KDC-issued element will be ignored by the -application server if this "signature" is not present. Further, elements -encapsulated within this element from a ticket granting ticket may be -interpreted by the KDC, and used as a basis according to policy for -including new signed elements within derivative tickets, but they will not -be copied to a derivative ticket directly. If they are copied directly to a -derivative ticket by a KDC that is not aware of this element, the signature -will not be correct for the application ticket elements, and the field will -be ignored by the application server. - -This element and the elements it encapulates may be safely ignored by -applications, application servers, and KDCs that do not implement this -element. - -B.2. Intended for server - -AD-INTENDED-FOR-SERVER SEQUENCE { - intended-server[0] SEQUENCE OF PrincipalName - elements[1] AuthorizationData -} - -AD elements encapsulated within the intended-for-server element may be -ignored if the application server is not in the list of principal names of -intended servers. Further, a KDC issuing a ticket for an application server -can remove this element if the application server is not in the list of -intended servers. - -Application servers should check for their principal name in the -intended-server field of this element. If their principal name is not found, -this element should be ignored. If found, then the encapsulated elements -should be evaluated in the same manner as if they were present in the top -level authorization data field. Applications and application servers that do -not implement this element should reject tickets that contain authorization -data elements of this type. - -B.3. Intended for application class - -AD-INTENDED-FOR-APPLICATION-CLASS SEQUENCE { intended-application-class[0] -SEQUENCE OF GeneralString elements[1] AuthorizationData } AD elements -encapsulated within the intended-for-application-class element may be -ignored if the application server is not in one of the named classes of -application servers. Examples of application server classes include -"FILESYSTEM", and other kinds of servers. - -This element and the elements it encapulates may be safely ignored by -applications, application servers, and KDCs that do not implement this -element. - -B.4. If relevant - -AD-IF-RELEVANT AuthorizationData - - -draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 - - -AD elements encapsulated within the if-relevant element are intended for -interpretation only by application servers that understand the particular -ad-type of the embedded element. Application servers that do not understand -the type of an element embedded within the if-relevant element may ignore -the uninterpretable element. This element promotes interoperability across -implementations which may have local extensions for authorization. - -B.5. And-Or - -AD-AND-OR SEQUENCE { - condition-count[0] INTEGER, - elements[1] AuthorizationData -} - -When restrictive AD elements encapsulated within the and-or element are -encountered, only the number specified in condition-count of the -encapsulated conditions must be met in order to satisfy this element. This -element may be used to implement an "or" operation by setting the -condition-count field to 1, and it may specify an "and" operation by setting -the condition count to the number of embedded elements. Application servers -that do not implement this element must reject tickets that contain -authorization data elements of this type. - -B.6. Mandatory ticket extensions - -AD-Mandatory-Ticket-Extensions Checksum - -An authorization data element of type mandatory-ticket-extensions specifies -a collision-proof checksum using the same has angorithm used to protect the -integrity of the ticket itself. This checksum will be calculated over the -entire extensions field. If there are more than one extension, all will be -covered by the checksum. This restriction indicates that the ticket should -not be accepted if the checksum does not match that calculated over the -ticket extensions. Application servers that do not implement this element -must reject tickets that contain authorization data elements of this type. - -B.7. Authorization Data in ticket extensions - -AD-IN-Ticket-Extensions Checksum - -An authorization data element of type in-ticket-extensions specifies a -collision-proof checksum using the same has angorithm used to protect the -integrity of the ticket itself. This checksum is calculated over a separate -external AuthorizationData field carried in the ticket extensions. -Application servers that do not implement this element must reject tickets -that contain authorization data elements of this type. Application servers -that do implement this element will search the ticket extensions for -authorization data fields, calculate the specified checksum over each -authorization data field and look for one matching the checksum in this -in-ticket-extensions element. If not found, then the ticket must be -rejected. If found, the corresponding authorization data elements will be -interpreted in the same manner as if they were contained in the top level -authorization data field. - - -draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 - - -Note that if multiple external authorization data fields are present in a -ticket, each will have a corresponding element of type in-ticket-extensions -in the top level authorization data field, and the external entries will be -linked to the corresponding element by their checksums. - -C. Definition of common ticket extensions - -This appendix contains the definitions of common ticket extensions. Support -for these extensions is optional. However, certain extensions have -associated authorization data elements that may require rejection of a -ticket containing an extension by application servers that do not implement -the particular extension. Other extensions have been defined beyond those -described in this specification. Such extensions are described elswhere and -for some of those extensions the reserved number may be found in the list of -constants. - -It is known that older versions of Kerberos did not support this field, and -that some clients will strip this field from a ticket when they parse and -then reassemble a ticket as it is passed to the application servers. The -presence of the extension will not break such clients, but any functionaly -dependent on the extensions will not work when such tickets are handled by -old clients. In such situations, some implementation may use alternate -methods to transmit the information in the extensions field. - -C.1. Null ticket extension - -TE-NullExtension OctetString -- The empty Octet String - -The te-data field in the null ticket extension is an octet string of lenght -zero. This extension may be included in a ticket granting ticket so that the -KDC can determine on presentation of the ticket granting ticket whether the -client software will strip the extensions field. - -C.2. External Authorization Data - -TE-ExternalAuthorizationData AuthorizationData - -The te-data field in the external authorization data ticket extension is -field of type AuthorizationData containing one or more authorization data -elements. If present, a corresponding authorization data element will be -present in the primary authorization data for the ticket and that element -will contain a checksum of the external authorization data ticket extension. ----------------------------------------------------------------------------- -[TM] Project Athena, Athena, and Kerberos are trademarks of the -Massachusetts Institute of Technology (MIT). No commercial use of these -trademarks may be made without prior written permission of MIT. - -[1] Note, however, that many applications use Kerberos' functions only upon -the initiation of a stream-based network connection. Unless an application -subsequently provides integrity protection for the data stream, the identity -verification applies only to the initiation of the connection, and does not -guarantee that subsequent messages on the connection originate from the same -principal. - - -draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 - - -[2] Secret and private are often used interchangeably in the literature. In -our usage, it takes two (or more) to share a secret, thus a shared DES key -is a secret key. Something is only private when no one but its owner knows -it. Thus, in public key cryptosystems, one has a public and a private key. - -[3] Of course, with appropriate permission the client could arrange -registration of a separately-named prin- cipal in a remote realm, and engage -in normal exchanges with that realm's services. However, for even small -numbers of clients this becomes cumbersome, and more automatic methods as -described here are necessary. - -[4] Though it is permissible to request or issue tick- ets with no network -addresses specified. - -[5] The password-changing request must not be honored unless the requester -can provide the old password (the user's current secret key). Otherwise, it -would be possible for someone to walk up to an unattended ses- sion and -change another user's password. - -[6] To authenticate a user logging on to a local system, the credentials -obtained in the AS exchange may first be used in a TGS exchange to obtain -credentials for a local server. Those credentials must then be verified by a -local server through successful completion of the Client/Server exchange. - -[7] "Random" means that, among other things, it should be impossible to -guess the next session key based on knowledge of past session keys. This can -only be achieved in a pseudo-random number generator if it is based on -cryptographic principles. It is more desirable to use a truly random number -generator, such as one based on measurements of random physical phenomena. - -[8] Tickets contain both an encrypted and unencrypted portion, so cleartext -here refers to the entire unit, which can be copied from one message and -replayed in another without any cryptographic skill. - -[9] Note that this can make applications based on unreliable transports -difficult to code correctly. If the transport might deliver duplicated -messages, either a new authenticator must be generated for each retry, or -the application server must match requests and replies and replay the first -reply in response to a detected duplicate. - -[10] This is used for user-to-user authentication as described in [8]. - -[11] Note that the rejection here is restricted to authenticators from the -same principal to the same server. Other client principals communicating -with the same server principal should not be have their authenticators -rejected if the time and microsecond fields happen to match some other -client's authenticator. - -[12] In the Kerberos version 4 protocol, the timestamp in the reply was the -client's timestamp plus one. This is not necessary in version 5 because -version 5 messages are formatted in such a way that it is not possible to -create the reply by judicious message surgery (even in encrypted form) -without knowledge of the appropriate encryption keys. - - -draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 - - -[13] Note that for encrypting the KRB_AP_REP message, the sub-session key is -not used, even if present in the Authenticator. - -[14] Implementations of the protocol may wish to provide routines to choose -subkeys based on session keys and random numbers and to generate a -negotiated key to be returned in the KRB_AP_REP message. - -[15]This can be accomplished in several ways. It might be known beforehand -(since the realm is part of the principal identifier), it might be stored in -a nameserver, or it might be obtained from a configura- tion file. If the -realm to be used is obtained from a nameserver, there is a danger of being -spoofed if the nameservice providing the realm name is not authenti- cated. -This might result in the use of a realm which has been compromised, and -would result in an attacker's ability to compromise the authentication of -the application server to the client. - -[16] If the client selects a sub-session key, care must be taken to ensure -the randomness of the selected sub- session key. One approach would be to -generate a random number and XOR it with the session key from the -ticket-granting ticket. - -[17] This allows easy implementation of user-to-user authentication [8], -which uses ticket-granting ticket session keys in lieu of secret server keys -in situa- tions where such secret keys could be easily comprom- ised. - -[18] For the purpose of appending, the realm preceding the first listed -realm is considered to be the null realm (""). - -[19] For the purpose of interpreting null subfields, the client's realm is -considered to precede those in the transited field, and the server's realm -is considered to follow them. - -[20] This means that a client and server running on the same host and -communicating with one another using the KRB_SAFE messages should not share -a common replay cache to detect KRB_SAFE replays. - -[21] The implementation of the Kerberos server need not combine the database -and the server on the same machine; it is feasible to store the principal -database in, say, a network name service, as long as the entries stored -therein are protected from disclosure to and modification by unauthorized -parties. However, we recommend against such strategies, as they can make -system management and threat analysis quite complex. - -[22] See the discussion of the padata field in section 5.4.2 for details on -why this can be useful. - -[23] Warning for implementations that unpack and repack data structures -during the generation and verification of embedded checksums: Because any -checksums applied to data structures must be checked against the original -data the length of bit strings must be preserved within a data structure -between the time that a checksum is generated through transmission to the -time that the checksum is verified. - - - -draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 - -[24] It is NOT recommended that this time value be used to adjust the -workstation's clock since the workstation cannot reliably determine that -such a KRB_AS_REP actually came from the proper KDC in a timely manner. - -[25] Note, however, that if the time is used as the nonce, one must make -sure that the workstation time is monotonically increasing. If the time is -ever reset backwards, there is a small, but finite, probability that a nonce -will be reused. - -[27] An application code in the encrypted part of a message provides an -additional check that the message was decrypted properly. - -[29] An application code in the encrypted part of a message provides an -additional check that the message was decrypted properly. - -[31] An application code in the encrypted part of a message provides an -additional check that the message was decrypted properly. - -[32] If supported by the encryption method in use, an initialization vector -may be passed to the encryption procedure, in order to achieve proper cipher -chaining. The initialization vector might come from the last block of the -ciphertext from the previous KRB_PRIV message, but it is the application's -choice whether or not to use such an initialization vector. If left out, the -default initialization vector for the encryption algorithm will be used. - -[33] This prevents an attacker who generates an incorrect AS request from -obtaining verifiable plaintext for use in an off-line password guessing -attack. - -[35] In the above specification, UNTAGGED OCTET STRING(length) is the -notation for an octet string with its tag and length removed. It is not a -valid ASN.1 type. The tag bits and length must be removed from the -confounder since the purpose of the confounder is so that the message starts -with random data, but the tag and its length are fixed. For other fields, -the length and tag would be redundant if they were included because they are -specified by the encryption type. [36] The ordering of the fields in the -CipherText is important. Additionally, messages encoded in this format must -include a length as part of the msg-seq field. This allows the recipient to -verify that the message has not been truncated. Without a length, an -attacker could use a chosen plaintext attack to generate a message which -could be truncated, while leaving the checksum intact. Note that if the -msg-seq is an encoding of an ASN.1 SEQUENCE or OCTET STRING, then the length -is part of that encoding. - -[37] In some cases, it may be necessary to use a different "mix-in" string -for compatibility reasons; see the discussion of padata in section 5.4.2. - -[38] In some cases, it may be necessary to use a different "mix-in" string -for compatibility reasons; see the discussion of padata in section 5.4.2. - -[39] A variant of the key is used to limit the use of a key to a particular -function, separating the functions of generating a checksum from other -encryption performed using the session key. The constant F0F0F0F0F0F0F0F0 -was chosen because it maintains key parity. The properties of DES precluded - - -draft-ietf-cat-kerberos-r-01 Expires 21 May 1998 - -the use of the complement. The same constant is used for similar purpose in -the Message Integrity Check in the Privacy Enhanced Mail standard. - -[40] This error carries additional information in the e- data field. The -contents of the e-data field for this message is described in section 5.9.1. diff --git a/doc/draft-ietf-cat-kerberos-revisions-03.txt b/doc/draft-ietf-cat-kerberos-revisions-03.txt deleted file mode 100644 index 06d997d48..000000000 --- a/doc/draft-ietf-cat-kerberos-revisions-03.txt +++ /dev/null @@ -1,6766 +0,0 @@ - - - -INTERNET-DRAFT Clifford Neuman - John Kohl - Theodore Ts'o - November 18th, 1998 - -The Kerberos Network Authentication Service (V5) - -STATUS OF THIS MEMO - -This document is an Internet-Draft. Internet-Drafts are working documents -of the Internet Engineering Task Force (IETF), its areas, and its working -groups. Note that other groups may also distribute working documents as -Internet-Drafts. - -Internet-Drafts are draft documents valid for a maximum of six months and -may be updated, replaced, or obsoleted by other documents at any time. It -is inappropriate to use Internet-Drafts as reference material or to cite -them other than as 'work in progress.' - -To learn the current status of any Internet-Draft, please check the -'1id-abstracts.txt' listing contained in the Internet-Drafts Shadow -Directories on ftp.ietf.org (US East Coast), nic.nordu.net (Europe), -ftp.isi.edu (US West Coast), or munnari.oz.au (Pacific Rim). - -The distribution of this memo is unlimited. It is filed as -draft-ietf-cat-kerberos-revisions-03.txt, and expires May 18th, 1999. -Please send comments to: krb-protocol@MIT.EDU - -ABSTRACT - -This document provides an overview and specification of Version 5 of the -Kerberos protocol, and updates RFC1510 to clarify aspects of the protocol -and its intended use that require more detailed or clearer explanation than -was provided in RFC1510. This document is intended to provide a detailed -description of the protocol, suitable for implementation, together with -descriptions of the appropriate use of protocol messages and fields within -those messages. - -This document is not intended to describe Kerberos to the end user, system -administrator, or application developer. Higher level papers describing -Version 5 of the Kerberos system [NT94] and documenting version 4 [SNS88], -are available elsewhere. - -OVERVIEW - -This INTERNET-DRAFT describes the concepts and model upon which the -Kerberos network authentication system is based. It also specifies Version -5 of the Kerberos protocol. - -The motivations, goals, assumptions, and rationale behind most design -decisions are treated cursorily; they are more fully described in a paper -available in IEEE communications [NT94] and earlier in the Kerberos portion -of the Athena Technical Plan [MNSS87]. The protocols have been a proposed -standard and are being considered for advancement for draft standard -through the IETF standard process. Comments are encouraged on the -presentation, but only minor refinements to the protocol as implemented or -extensions that fit within current protocol framework will be considered at - -Neuman, Ts'o, Kohl Expires: 18 May 1999 - - -INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 - - -this time. - -Requests for addition to an electronic mailing list for discussion of -Kerberos, kerberos@MIT.EDU, may be addressed to kerberos-request@MIT.EDU. -This mailing list is gatewayed onto the Usenet as the group -comp.protocols.kerberos. Requests for further information, including -documents and code availability, may be sent to info-kerberos@MIT.EDU. - -BACKGROUND - -The Kerberos model is based in part on Needham and Schroeder's trusted -third-party authentication protocol [NS78] and on modifications suggested -by Denning and Sacco [DS81]. The original design and implementation of -Kerberos Versions 1 through 4 was the work of two former Project Athena -staff members, Steve Miller of Digital Equipment Corporation and Clifford -Neuman (now at the Information Sciences Institute of the University of -Southern California), along with Jerome Saltzer, Technical Director of -Project Athena, and Jeffrey Schiller, MIT Campus Network Manager. Many -other members of Project Athena have also contributed to the work on -Kerberos. - -Version 5 of the Kerberos protocol (described in this document) has evolved -from Version 4 based on new requirements and desires for features not -available in Version 4. The design of Version 5 of the Kerberos protocol -was led by Clifford Neuman and John Kohl with much input from the -community. The development of the MIT reference implementation was led at -MIT by John Kohl and Theodore T'so, with help and contributed code from -many others. Since RFC1510 was issued, extensions and revisions to the -protocol have been proposed by many individuals. Some of these proposals -are reflected in this document. Where such changes involved significant -effort, the document cites the contribution of the proposer. - -Reference implementations of both version 4 and version 5 of Kerberos are -publicly available and commercial implementations have been developed and -are widely used. Details on the differences between Kerberos Versions 4 and -5 can be found in [KNT92]. - -1. Introduction - -Kerberos provides a means of verifying the identities of principals, (e.g. -a workstation user or a network server) on an open (unprotected) network. -This is accomplished without relying on assertions by the host operating -system, without basing trust on host addresses, without requiring physical -security of all the hosts on the network, and under the assumption that -packets traveling along the network can be read, modified, and inserted at -will[1]. Kerberos performs authentication under these conditions as a -trusted third-party authentication service by using conventional (shared -secret key [2] cryptography. Kerberos extensions have been proposed and -implemented that provide for the use of public key cryptography during -certain phases of the authentication protocol. These extensions provide for -authentication of users registered with public key certification -authorities, and allow the system to provide certain benefits of public key -cryptography in situations where they are needed. - -The basic Kerberos authentication process proceeds as follows: A client -sends a request to the authentication server (AS) requesting 'credentials' -for a given server. The AS responds with these credentials, encrypted in -the client's key. The credentials consist of 1) a 'ticket' for the server -and 2) a temporary encryption key (often called a "session key"). The - -Neuman, Ts'o, Kohl Expires: 18 May 1999 - - -INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 - - -client transmits the ticket (which contains the client's identity and a -copy of the session key, all encrypted in the server's key) to the server. -The session key (now shared by the client and server) is used to -authenticate the client, and may optionally be used to authenticate the -server. It may also be used to encrypt further communication between the -two parties or to exchange a separate sub-session key to be used to encrypt -further communication. - -Implementation of the basic protocol consists of one or more authentication -servers running on physically secure hosts. The authentication servers -maintain a database of principals (i.e., users and servers) and their -secret keys. Code libraries provide encryption and implement the Kerberos -protocol. In order to add authentication to its transactions, a typical -network application adds one or two calls to the Kerberos library directly -or through the Generic Security Services Application Programming Interface, -GSSAPI, described in separate document. These calls result in the -transmission of the necessary messages to achieve authentication. - -The Kerberos protocol consists of several sub-protocols (or exchanges). -There are two basic methods by which a client can ask a Kerberos server for -credentials. In the first approach, the client sends a cleartext request -for a ticket for the desired server to the AS. The reply is sent encrypted -in the client's secret key. Usually this request is for a ticket-granting -ticket (TGT) which can later be used with the ticket-granting server (TGS). -In the second method, the client sends a request to the TGS. The client -uses the TGT to authenticate itself to the TGS in the same manner as if it -were contacting any other application server that requires Kerberos -authentication. The reply is encrypted in the session key from the TGT. -Though the protocol specification describes the AS and the TGS as separate -servers, they are implemented in practice as different protocol entry -points within a single Kerberos server. - -Once obtained, credentials may be used to verify the identity of the -principals in a transaction, to ensure the integrity of messages exchanged -between them, or to preserve privacy of the messages. The application is -free to choose whatever protection may be necessary. - -To verify the identities of the principals in a transaction, the client -transmits the ticket to the application server. Since the ticket is sent -"in the clear" (parts of it are encrypted, but this encryption doesn't -thwart replay) and might be intercepted and reused by an attacker, -additional information is sent to prove that the message originated with -the principal to whom the ticket was issued. This information (called the -authenticator) is encrypted in the session key, and includes a timestamp. -The timestamp proves that the message was recently generated and is not a -replay. Encrypting the authenticator in the session key proves that it was -generated by a party possessing the session key. Since no one except the -requesting principal and the server know the session key (it is never sent -over the network in the clear) this guarantees the identity of the client. - -The integrity of the messages exchanged between principals can also be -guaranteed using the session key (passed in the ticket and contained in the -credentials). This approach provides detection of both replay attacks and -message stream modification attacks. It is accomplished by generating and -transmitting a collision-proof checksum (elsewhere called a hash or digest -function) of the client's message, keyed with the session key. Privacy and -integrity of the messages exchanged between principals can be secured by -encrypting the data to be passed using the session key contained in the -ticket or the subsession key found in the authenticator. - -Neuman, Ts'o, Kohl Expires: 18 May 1999 - - -INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 - - - -The authentication exchanges mentioned above require read-only access to -the Kerberos database. Sometimes, however, the entries in the database must -be modified, such as when adding new principals or changing a principal's -key. This is done using a protocol between a client and a third Kerberos -server, the Kerberos Administration Server (KADM). There is also a protocol -for maintaining multiple copies of the Kerberos database. Neither of these -protocols are described in this document. - -1.1. Cross-Realm Operation - -The Kerberos protocol is designed to operate across organizational -boundaries. A client in one organization can be authenticated to a server -in another. Each organization wishing to run a Kerberos server establishes -its own 'realm'. The name of the realm in which a client is registered is -part of the client's name, and can be used by the end-service to decide -whether to honor a request. - -By establishing 'inter-realm' keys, the administrators of two realms can -allow a client authenticated in the local realm to prove its identity to -servers in other realms[3]. The exchange of inter-realm keys (a separate -key may be used for each direction) registers the ticket-granting service -of each realm as a principal in the other realm. A client is then able to -obtain a ticket-granting ticket for the remote realm's ticket-granting -service from its local realm. When that ticket-granting ticket is used, the -remote ticket-granting service uses the inter-realm key (which usually -differs from its own normal TGS key) to decrypt the ticket-granting ticket, -and is thus certain that it was issued by the client's own TGS. Tickets -issued by the remote ticket-granting service will indicate to the -end-service that the client was authenticated from another realm. - -A realm is said to communicate with another realm if the two realms share -an inter-realm key, or if the local realm shares an inter-realm key with an -intermediate realm that communicates with the remote realm. An -authentication path is the sequence of intermediate realms that are -transited in communicating from one realm to another. - -Realms are typically organized hierarchically. Each realm shares a key with -its parent and a different key with each child. If an inter-realm key is -not directly shared by two realms, the hierarchical organization allows an -authentication path to be easily constructed. If a hierarchical -organization is not used, it may be necessary to consult a database in -order to construct an authentication path between realms. - -Although realms are typically hierarchical, intermediate realms may be -bypassed to achieve cross-realm authentication through alternate -authentication paths (these might be established to make communication -between two realms more efficient). It is important for the end-service to -know which realms were transited when deciding how much faith to place in -the authentication process. To facilitate this decision, a field in each -ticket contains the names of the realms that were involved in -authenticating the client. - -The application server is ultimately responsible for accepting or rejecting -authentication and should check the transited field. The application server -may choose to rely on the KDC for the application server's realm to check -the transited field. The application server's KDC will set the -TRANSITED-POLICY-CHECKED flag in this case. The KDC's for intermediate -realms may also check the transited field as they issue - -Neuman, Ts'o, Kohl Expires: 18 May 1999 - - -INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 - - -ticket-granting-tickets for other realms, but they are encouraged not to do -so. A client may request that the KDC's not check the transited field by -setting the DISABLE-TRANSITED-CHECK flag. KDC's are encouraged but not -required to honor this flag. - -1.2. Authorization - -As an authentication service, Kerberos provides a means of verifying the -identity of principals on a network. Authentication is usually useful -primarily as a first step in the process of authorization, determining -whether a client may use a service, which objects the client is allowed to -access, and the type of access allowed for each. Kerberos does not, by -itself, provide authorization. Possession of a client ticket for a service -provides only for authentication of the client to that service, and in the -absence of a separate authorization procedure, it should not be considered -by an application as authorizing the use of that service. - -Such separate authorization methods may be implemented as application -specific access control functions and may be based on files such as the -application server, or on separately issued authorization credentials such -as those based on proxies [Neu93] , or on other authorization services. - -Applications should not be modified to accept the issuance of a service -ticket by the Kerberos server (even by an modified Kerberos server) as -granting authority to use the service, since such applications may become -vulnerable to the bypass of this authorization check in an environment if -they interoperate with other KDCs or where other options for application -authentication (e.g. the PKTAPP proposal) are provided. - -1.3. Environmental assumptions - -Kerberos imposes a few assumptions on the environment in which it can -properly function: - - * 'Denial of service' attacks are not solved with Kerberos. There are - places in these protocols where an intruder can prevent an application - from participating in the proper authentication steps. Detection and - solution of such attacks (some of which can appear to be nnot-uncommon - 'normal' failure modes for the system) is usually best left to the - human administrators and users. - * Principals must keep their secret keys secret. If an intruder somehow - steals a principal's key, it will be able to masquerade as that - principal or impersonate any server to the legitimate principal. - * 'Password guessing' attacks are not solved by Kerberos. If a user - chooses a poor password, it is possible for an attacker to - successfully mount an offline dictionary attack by repeatedly - attempting to decrypt, with successive entries from a dictionary, - messages obtained which are encrypted under a key derived from the - user's password. - * Each host on the network must have a clock which is 'loosely - synchronized' to the time of the other hosts; this synchronization is - used to reduce the bookkeeping needs of application servers when they - do replay detection. The degree of "looseness" can be configured on a - per-server basis, but is typically on the order of 5 minutes. If the - clocks are synchronized over the network, the clock synchronization - protocol must itself be secured from network attackers. - * Principal identifiers are not recycled on a short-term basis. A - typical mode of access control will use access control lists (ACLs) to - grant permissions to particular principals. If a stale ACL entry - -Neuman, Ts'o, Kohl Expires: 18 May 1999 - - -INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 - - - remains for a deleted principal and the principal identifier is - reused, the new principal will inherit rights specified in the stale - ACL entry. By not re-using principal identifiers, the danger of - inadvertent access is removed. - -1.4. Glossary of terms - -Below is a list of terms used throughout this document. - -Authentication - Verifying the claimed identity of a principal. -Authentication header - A record containing a Ticket and an Authenticator to be presented to a - server as part of the authentication process. -Authentication path - A sequence of intermediate realms transited in the authentication - process when communicating from one realm to another. -Authenticator - A record containing information that can be shown to have been - recently generated using the session key known only by the client and - server. -Authorization - The process of determining whether a client may use a service, which - objects the client is allowed to access, and the type of access - allowed for each. -Capability - A token that grants the bearer permission to access an object or - service. In Kerberos, this might be a ticket whose use is restricted - by the contents of the authorization data field, but which lists no - network addresses, together with the session key necessary to use the - ticket. -Ciphertext - The output of an encryption function. Encryption transforms plaintext - into ciphertext. -Client - A process that makes use of a network service on behalf of a user. - Note that in some cases a Server may itself be a client of some other - server (e.g. a print server may be a client of a file server). -Credentials - A ticket plus the secret session key necessary to successfully use - that ticket in an authentication exchange. -KDC - Key Distribution Center, a network service that supplies tickets and - temporary session keys; or an instance of that service or the host on - which it runs. The KDC services both initial ticket and - ticket-granting ticket requests. The initial ticket portion is - sometimes referred to as the Authentication Server (or service). The - ticket-granting ticket portion is sometimes referred to as the - ticket-granting server (or service). -Kerberos - Aside from the 3-headed dog guarding Hades, the name given to Project - Athena's authentication service, the protocol used by that service, or - the code used to implement the authentication service. -Plaintext - The input to an encryption function or the output of a decryption - function. Decryption transforms ciphertext into plaintext. -Principal - A uniquely named client or server instance that participates in a - network communication. - -Neuman, Ts'o, Kohl Expires: 18 May 1999 - - -INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 - - -Principal identifier - The name used to uniquely identify each different principal. -Seal - To encipher a record containing several fields in such a way that the - fields cannot be individually replaced without either knowledge of the - encryption key or leaving evidence of tampering. -Secret key - An encryption key shared by a principal and the KDC, distributed - outside the bounds of the system, with a long lifetime. In the case of - a human user's principal, the secret key is derived from a password. -Server - A particular Principal which provides a resource to network clients. - The server is sometimes refered to as the Application Server. -Service - A resource provided to network clients; often provided by more than - one server (for example, remote file service). -Session key - A temporary encryption key used between two principals, with a - lifetime limited to the duration of a single login "session". -Sub-session key - A temporary encryption key used between two principals, selected and - exchanged by the principals using the session key, and with a lifetime - limited to the duration of a single association. -Ticket - A record that helps a client authenticate itself to a server; it - contains the client's identity, a session key, a timestamp, and other - information, all sealed using the server's secret key. It only serves - to authenticate a client when presented along with a fresh - Authenticator. - -2. Ticket flag uses and requests - -Each Kerberos ticket contains a set of flags which are used to indicate -various attributes of that ticket. Most flags may be requested by a client -when the ticket is obtained; some are automatically turned on and off by a -Kerberos server as required. The following sections explain what the -various flags mean, and gives examples of reasons to use such a flag. - -2.1. Initial and pre-authenticated tickets - -The INITIAL flag indicates that a ticket was issued using the AS protocol -and not issued based on a ticket-granting ticket. Application servers that -want to require the demonstrated knowledge of a client's secret key (e.g. a -password-changing program) can insist that this flag be set in any tickets -they accept, and thus be assured that the client's key was recently -presented to the application client. - -The PRE-AUTHENT and HW-AUTHENT flags provide addition information about the -initial authentication, regardless of whether the current ticket was issued -directly (in which case INITIAL will also be set) or issued on the basis of -a ticket-granting ticket (in which case the INITIAL flag is clear, but the -PRE-AUTHENT and HW-AUTHENT flags are carried forward from the -ticket-granting ticket). - -2.2. Invalid tickets - -The INVALID flag indicates that a ticket is invalid. Application servers -must reject tickets which have this flag set. A postdated ticket will -usually be issued in this form. Invalid tickets must be validated by the - -Neuman, Ts'o, Kohl Expires: 18 May 1999 - - -INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 - - -KDC before use, by presenting them to the KDC in a TGS request with the -VALIDATE option specified. The KDC will only validate tickets after their -starttime has passed. The validation is required so that postdated tickets -which have been stolen before their starttime can be rendered permanently -invalid (through a hot-list mechanism) (see section 3.3.3.1). - -2.3. Renewable tickets - -Applications may desire to hold tickets which can be valid for long periods -of time. However, this can expose their credentials to potential theft for -equally long periods, and those stolen credentials would be valid until the -expiration time of the ticket(s). Simply using short-lived tickets and -obtaining new ones periodically would require the client to have long-term -access to its secret key, an even greater risk. Renewable tickets can be -used to mitigate the consequences of theft. Renewable tickets have two -"expiration times": the first is when the current instance of the ticket -expires, and the second is the latest permissible value for an individual -expiration time. An application client must periodically (i.e. before it -expires) present a renewable ticket to the KDC, with the RENEW option set -in the KDC request. The KDC will issue a new ticket with a new session key -and a later expiration time. All other fields of the ticket are left -unmodified by the renewal process. When the latest permissible expiration -time arrives, the ticket expires permanently. At each renewal, the KDC may -consult a hot-list to determine if the ticket had been reported stolen -since its last renewal; it will refuse to renew such stolen tickets, and -thus the usable lifetime of stolen tickets is reduced. - -The RENEWABLE flag in a ticket is normally only interpreted by the -ticket-granting service (discussed below in section 3.3). It can usually be -ignored by application servers. However, some particularly careful -application servers may wish to disallow renewable tickets. - -If a renewable ticket is not renewed by its expiration time, the KDC will -not renew the ticket. The RENEWABLE flag is reset by default, but a client -may request it be set by setting the RENEWABLE option in the KRB_AS_REQ -message. If it is set, then the renew-till field in the ticket contains the -time after which the ticket may not be renewed. - -2.4. Postdated tickets - -Applications may occasionally need to obtain tickets for use much later, -e.g. a batch submission system would need tickets to be valid at the time -the batch job is serviced. However, it is dangerous to hold valid tickets -in a batch queue, since they will be on-line longer and more prone to -theft. Postdated tickets provide a way to obtain these tickets from the KDC -at job submission time, but to leave them "dormant" until they are -activated and validated by a further request of the KDC. If a ticket theft -were reported in the interim, the KDC would refuse to validate the ticket, -and the thief would be foiled. - -The MAY-POSTDATE flag in a ticket is normally only interpreted by the -ticket-granting service. It can be ignored by application servers. This -flag must be set in a ticket-granting ticket in order to issue a postdated -ticket based on the presented ticket. It is reset by default; it may be -requested by a client by setting the ALLOW-POSTDATE option in the -KRB_AS_REQ message. This flag does not allow a client to obtain a postdated -ticket-granting ticket; postdated ticket-granting tickets can only by -obtained by requesting the postdating in the KRB_AS_REQ message. The life -(endtime-starttime) of a postdated ticket will be the remaining life of the - -Neuman, Ts'o, Kohl Expires: 18 May 1999 - - -INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 - - -ticket-granting ticket at the time of the request, unless the RENEWABLE -option is also set, in which case it can be the full life -(endtime-starttime) of the ticket-granting ticket. The KDC may limit how -far in the future a ticket may be postdated. - -The POSTDATED flag indicates that a ticket has been postdated. The -application server can check the authtime field in the ticket to see when -the original authentication occurred. Some services may choose to reject -postdated tickets, or they may only accept them within a certain period -after the original authentication. When the KDC issues a POSTDATED ticket, -it will also be marked as INVALID, so that the application client must -present the ticket to the KDC to be validated before use. - -2.5. Proxiable and proxy tickets - -At times it may be necessary for a principal to allow a service to perform -an operation on its behalf. The service must be able to take on the -identity of the client, but only for a particular purpose. A principal can -allow a service to take on the principal's identity for a particular -purpose by granting it a proxy. - -The process of granting a proxy using the proxy and proxiable flags is used -to provide credentials for use with specific services. Though conceptually -also a proxy, user's wishing to delegate their identity for ANY purpose -must use the ticket forwarding mechanism described in the next section to -forward a ticket granting ticket. - -The PROXIABLE flag in a ticket is normally only interpreted by the -ticket-granting service. It can be ignored by application servers. When -set, this flag tells the ticket-granting server that it is OK to issue a -new ticket (but not a ticket-granting ticket) with a different network -address based on this ticket. This flag is set if requested by the client -on initial authentication. By default, the client will request that it be -set when requesting a ticket granting ticket, and reset when requesting any -other ticket. - -This flag allows a client to pass a proxy to a server to perform a remote -request on its behalf, e.g. a print service client can give the print -server a proxy to access the client's files on a particular file server in -order to satisfy a print request. - -In order to complicate the use of stolen credentials, Kerberos tickets are -usually valid from only those network addresses specifically included in -the ticket[4]. When granting a proxy, the client must specify the new -network address from which the proxy is to be used, or indicate that the -proxy is to be issued for use from any address. - -The PROXY flag is set in a ticket by the TGS when it issues a proxy ticket. -Application servers may check this flag and at their option they may -require additional authentication from the agent presenting the proxy in -order to provide an audit trail. - -2.6. Forwardable tickets - -Authentication forwarding is an instance of a proxy where the service is -granted complete use of the client's identity. An example where it might be -used is when a user logs in to a remote system and wants authentication to -work from that system as if the login were local. - - -Neuman, Ts'o, Kohl Expires: 18 May 1999 - - -INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 - - -The FORWARDABLE flag in a ticket is normally only interpreted by the -ticket-granting service. It can be ignored by application servers. The -FORWARDABLE flag has an interpretation similar to that of the PROXIABLE -flag, except ticket-granting tickets may also be issued with different -network addresses. This flag is reset by default, but users may request -that it be set by setting the FORWARDABLE option in the AS request when -they request their initial ticket- granting ticket. - -This flag allows for authentication forwarding without requiring the user -to enter a password again. If the flag is not set, then authentication -forwarding is not permitted, but the same result can still be achieved if -the user engages in the AS exchange specifying the requested network -addresses and supplies a password. - -The FORWARDED flag is set by the TGS when a client presents a ticket with -the FORWARDABLE flag set and requests a forwarded ticket by specifying the -FORWARDED KDC option and supplying a set of addresses for the new ticket. -It is also set in all tickets issued based on tickets with the FORWARDED -flag set. Application servers may choose to process FORWARDED tickets -differently than non-FORWARDED tickets. - -2.7. Other KDC options - -There are two additional options which may be set in a client's request of -the KDC. The RENEWABLE-OK option indicates that the client will accept a -renewable ticket if a ticket with the requested life cannot otherwise be -provided. If a ticket with the requested life cannot be provided, then the -KDC may issue a renewable ticket with a renew-till equal to the the -requested endtime. The value of the renew-till field may still be adjusted -by site-determined limits or limits imposed by the individual principal or -server. - -The ENC-TKT-IN-SKEY option is honored only by the ticket-granting service. -It indicates that the ticket to be issued for the end server is to be -encrypted in the session key from the a additional second ticket-granting -ticket provided with the request. See section 3.3.3 for specific details. - -3. Message Exchanges - -The following sections describe the interactions between network clients -and servers and the messages involved in those exchanges. - -3.1. The Authentication Service Exchange - - Summary - Message direction Message type Section - 1. Client to Kerberos KRB_AS_REQ 5.4.1 - 2. Kerberos to client KRB_AS_REP or 5.4.2 - KRB_ERROR 5.9.1 - -The Authentication Service (AS) Exchange between the client and the -Kerberos Authentication Server is initiated by a client when it wishes to -obtain authentication credentials for a given server but currently holds no -credentials. In its basic form, the client's secret key is used for -encryption and decryption. This exchange is typically used at the -initiation of a login session to obtain credentials for a Ticket-Granting -Server which will subsequently be used to obtain credentials for other -servers (see section 3.3) without requiring further use of the client's -secret key. This exchange is also used to request credentials for services - -Neuman, Ts'o, Kohl Expires: 18 May 1999 - - -INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 - - -which must not be mediated through the Ticket-Granting Service, but rather -require a principal's secret key, such as the password-changing service[5]. -This exchange does not by itself provide any assurance of the the identity -of the user[6]. - -The exchange consists of two messages: KRB_AS_REQ from the client to -Kerberos, and KRB_AS_REP or KRB_ERROR in reply. The formats for these -messages are described in sections 5.4.1, 5.4.2, and 5.9.1. - -In the request, the client sends (in cleartext) its own identity and the -identity of the server for which it is requesting credentials. The -response, KRB_AS_REP, contains a ticket for the client to present to the -server, and a session key that will be shared by the client and the server. -The session key and additional information are encrypted in the client's -secret key. The KRB_AS_REP message contains information which can be used -to detect replays, and to associate it with the message to which it -replies. Various errors can occur; these are indicated by an error response -(KRB_ERROR) instead of the KRB_AS_REP response. The error message is not -encrypted. The KRB_ERROR message contains information which can be used to -associate it with the message to which it replies. The lack of encryption -in the KRB_ERROR message precludes the ability to detect replays, -fabrications, or modifications of such messages. - -Without preautentication, the authentication server does not know whether -the client is actually the principal named in the request. It simply sends -a reply without knowing or caring whether they are the same. This is -acceptable because nobody but the principal whose identity was given in the -request will be able to use the reply. Its critical information is -encrypted in that principal's key. The initial request supports an optional -field that can be used to pass additional information that might be needed -for the initial exchange. This field may be used for preauthentication as -described in section [hl<>]. - -3.1.1. Generation of KRB_AS_REQ message - -The client may specify a number of options in the initial request. Among -these options are whether pre-authentication is to be performed; whether -the requested ticket is to be renewable, proxiable, or forwardable; whether -it should be postdated or allow postdating of derivative tickets; and -whether a renewable ticket will be accepted in lieu of a non-renewable -ticket if the requested ticket expiration date cannot be satisfied by a -non-renewable ticket (due to configuration constraints; see section 4). See -section A.1 for pseudocode. - -The client prepares the KRB_AS_REQ message and sends it to the KDC. - -3.1.2. Receipt of KRB_AS_REQ message - -If all goes well, processing the KRB_AS_REQ message will result in the -creation of a ticket for the client to present to the server. The format -for the ticket is described in section 5.3.1. The contents of the ticket -are determined as follows. - -3.1.3. Generation of KRB_AS_REP message - -The authentication server looks up the client and server principals named -in the KRB_AS_REQ in its database, extracting their respective keys. If -required, the server pre-authenticates the request, and if the -pre-authentication check fails, an error message with the code - -Neuman, Ts'o, Kohl Expires: 18 May 1999 - - -INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 - - -KDC_ERR_PREAUTH_FAILED is returned. If the server cannot accommodate the -requested encryption type, an error message with code KDC_ERR_ETYPE_NOSUPP -is returned. Otherwise it generates a 'random' session key[7]. - -If there are multiple encryption keys registered for a client in the -Kerberos database (or if the key registered supports multiple encryption -types; e.g. DES-CBC-CRC and DES-CBC-MD5), then the etype field from the AS -request is used by the KDC to select the encryption method to be used for -encrypting the response to the client. If there is more than one supported, -strong encryption type in the etype list, the first valid etype for which -an encryption key is available is used. The encryption method used to -respond to a TGS request is taken from the keytype of the session key found -in the ticket granting ticket. - -When the etype field is present in a KDC request, whether an AS or TGS -request, the KDC will attempt to assign the type of the random session key -from the list of methods in the etype field. The KDC will select the -appropriate type using the list of methods provided together with -information from the Kerberos database indicating acceptable encryption -methods for the application server. The KDC will not issue tickets with a -weak session key encryption type. - -If the requested start time is absent, indicates a time in the past, or is -within the window of acceptable clock skew for the KDC and the POSTDATE -option has not been specified, then the start time of the ticket is set to -the authentication server's current time. If it indicates a time in the -future beyond the acceptable clock skew, but the POSTDATED option has not -been specified then the error KDC_ERR_CANNOT_POSTDATE is returned. -Otherwise the requested start time is checked against the policy of the -local realm (the administrator might decide to prohibit certain types or -ranges of postdated tickets), and if acceptable, the ticket's start time is -set as requested and the INVALID flag is set in the new ticket. The -postdated ticket must be validated before use by presenting it to the KDC -after the start time has been reached. - -The expiration time of the ticket will be set to the minimum of the -following: - - * The expiration time (endtime) requested in the KRB_AS_REQ message. - * The ticket's start time plus the maximum allowable lifetime associated - with the client principal (the authentication server's database - includes a maximum ticket lifetime field in each principal's record; - see section 4). - * The ticket's start time plus the maximum allowable lifetime associated - with the server principal. - * The ticket's start time plus the maximum lifetime set by the policy of - the local realm. - -If the requested expiration time minus the start time (as determined above) -is less than a site-determined minimum lifetime, an error message with code -KDC_ERR_NEVER_VALID is returned. If the requested expiration time for the -ticket exceeds what was determined as above, and if the 'RENEWABLE-OK' -option was requested, then the 'RENEWABLE' flag is set in the new ticket, -and the renew-till value is set as if the 'RENEWABLE' option were requested -(the field and option names are described fully in section 5.4.1). - -If the RENEWABLE option has been requested or if the RENEWABLE-OK option -has been set and a renewable ticket is to be issued, then the renew-till -field is set to the minimum of: - -Neuman, Ts'o, Kohl Expires: 18 May 1999 - - -INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 - - - - * Its requested value. - * The start time of the ticket plus the minimum of the two maximum - renewable lifetimes associated with the principals' database entries. - * The start time of the ticket plus the maximum renewable lifetime set - by the policy of the local realm. - -The flags field of the new ticket will have the following options set if -they have been requested and if the policy of the local realm allows: -FORWARDABLE, MAY-POSTDATE, POSTDATED, PROXIABLE, RENEWABLE. If the new -ticket is post-dated (the start time is in the future), its INVALID flag -will also be set. - -If all of the above succeed, the server formats a KRB_AS_REP message (see -section 5.4.2), copying the addresses in the request into the caddr of the -response, placing any required pre-authentication data into the padata of -the response, and encrypts the ciphertext part in the client's key using -the requested encryption method, and sends it to the client. See section -A.2 for pseudocode. - -3.1.4. Generation of KRB_ERROR message - -Several errors can occur, and the Authentication Server responds by -returning an error message, KRB_ERROR, to the client, with the error-code -and e-text fields set to appropriate values. The error message contents and -details are described in Section 5.9.1. - -3.1.5. Receipt of KRB_AS_REP message - -If the reply message type is KRB_AS_REP, then the client verifies that the -cname and crealm fields in the cleartext portion of the reply match what it -requested. If any padata fields are present, they may be used to derive the -proper secret key to decrypt the message. The client decrypts the encrypted -part of the response using its secret key, verifies that the nonce in the -encrypted part matches the nonce it supplied in its request (to detect -replays). It also verifies that the sname and srealm in the response match -those in the request (or are otherwise expected values), and that the host -address field is also correct. It then stores the ticket, session key, -start and expiration times, and other information for later use. The -key-expiration field from the encrypted part of the response may be checked -to notify the user of impending key expiration (the client program could -then suggest remedial action, such as a password change). See section A.3 -for pseudocode. - -Proper decryption of the KRB_AS_REP message is not sufficient to verify the -identity of the user; the user and an attacker could cooperate to generate -a KRB_AS_REP format message which decrypts properly but is not from the -proper KDC. If the host wishes to verify the identity of the user, it must -require the user to present application credentials which can be verified -using a securely-stored secret key for the host. If those credentials can -be verified, then the identity of the user can be assured. - -3.1.6. Receipt of KRB_ERROR message - -If the reply message type is KRB_ERROR, then the client interprets it as an -error and performs whatever application-specific tasks are necessary to -recover. - -3.2. The Client/Server Authentication Exchange - -Neuman, Ts'o, Kohl Expires: 18 May 1999 - - -INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 - - - - Summary -Message direction Message type Section -Client to Application server KRB_AP_REQ 5.5.1 -[optional] Application server to client KRB_AP_REP or 5.5.2 - KRB_ERROR 5.9.1 - -The client/server authentication (CS) exchange is used by network -applications to authenticate the client to the server and vice versa. The -client must have already acquired credentials for the server using the AS -or TGS exchange. - -3.2.1. The KRB_AP_REQ message - -The KRB_AP_REQ contains authentication information which should be part of -the first message in an authenticated transaction. It contains a ticket, an -authenticator, and some additional bookkeeping information (see section -5.5.1 for the exact format). The ticket by itself is insufficient to -authenticate a client, since tickets are passed across the network in -cleartext[DS90], so the authenticator is used to prevent invalid replay of -tickets by proving to the server that the client knows the session key of -the ticket and thus is entitled to use the ticket. The KRB_AP_REQ message -is referred to elsewhere as the 'authentication header.' - -3.2.2. Generation of a KRB_AP_REQ message - -When a client wishes to initiate authentication to a server, it obtains -(either through a credentials cache, the AS exchange, or the TGS exchange) -a ticket and session key for the desired service. The client may re-use any -tickets it holds until they expire. To use a ticket the client constructs a -new Authenticator from the the system time, its name, and optionally an -application specific checksum, an initial sequence number to be used in -KRB_SAFE or KRB_PRIV messages, and/or a session subkey to be used in -negotiations for a session key unique to this particular session. -Authenticators may not be re-used and will be rejected if replayed to a -server[LGDSR87]. If a sequence number is to be included, it should be -randomly chosen so that even after many messages have been exchanged it is -not likely to collide with other sequence numbers in use. - -The client may indicate a requirement of mutual authentication or the use -of a session-key based ticket by setting the appropriate flag(s) in the -ap-options field of the message. - -The Authenticator is encrypted in the session key and combined with the -ticket to form the KRB_AP_REQ message which is then sent to the end server -along with any additional application-specific information. See section A.9 -for pseudocode. - -3.2.3. Receipt of KRB_AP_REQ message - -Authentication is based on the server's current time of day (clocks must be -loosely synchronized), the authenticator, and the ticket. Several errors -are possible. If an error occurs, the server is expected to reply to the -client with a KRB_ERROR message. This message may be encapsulated in the -application protocol if its 'raw' form is not acceptable to the protocol. -The format of error messages is described in section 5.9.1. - -The algorithm for verifying authentication information is as follows. If -the message type is not KRB_AP_REQ, the server returns the - -Neuman, Ts'o, Kohl Expires: 18 May 1999 - - -INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 - - -KRB_AP_ERR_MSG_TYPE error. If the key version indicated by the Ticket in -the KRB_AP_REQ is not one the server can use (e.g., it indicates an old -key, and the server no longer possesses a copy of the old key), the -KRB_AP_ERR_BADKEYVER error is returned. If the USE-SESSION-KEY flag is set -in the ap-options field, it indicates to the server that the ticket is -encrypted in the session key from the server's ticket-granting ticket -rather than its secret key[10]. Since it is possible for the server to be -registered in multiple realms, with different keys in each, the srealm -field in the unencrypted portion of the ticket in the KRB_AP_REQ is used to -specify which secret key the server should use to decrypt that ticket. The -KRB_AP_ERR_NOKEY error code is returned if the server doesn't have the -proper key to decipher the ticket. - -The ticket is decrypted using the version of the server's key specified by -the ticket. If the decryption routines detect a modification of the ticket -(each encryption system must provide safeguards to detect modified -ciphertext; see section 6), the KRB_AP_ERR_BAD_INTEGRITY error is returned -(chances are good that different keys were used to encrypt and decrypt). - -The authenticator is decrypted using the session key extracted from the -decrypted ticket. If decryption shows it to have been modified, the -KRB_AP_ERR_BAD_INTEGRITY error is returned. The name and realm of the -client from the ticket are compared against the same fields in the -authenticator. If they don't match, the KRB_AP_ERR_BADMATCH error is -returned (they might not match, for example, if the wrong session key was -used to encrypt the authenticator). The addresses in the ticket (if any) -are then searched for an address matching the operating-system reported -address of the client. If no match is found or the server insists on ticket -addresses but none are present in the ticket, the KRB_AP_ERR_BADADDR error -is returned. - -If the local (server) time and the client time in the authenticator differ -by more than the allowable clock skew (e.g., 5 minutes), the -KRB_AP_ERR_SKEW error is returned. If the server name, along with the -client name, time and microsecond fields from the Authenticator match any -recently-seen such tuples, the KRB_AP_ERR_REPEAT error is returned[11]. The -server must remember any authenticator presented within the allowable clock -skew, so that a replay attempt is guaranteed to fail. If a server loses -track of any authenticator presented within the allowable clock skew, it -must reject all requests until the clock skew interval has passed. This -assures that any lost or re-played authenticators will fall outside the -allowable clock skew and can no longer be successfully replayed (If this is -not done, an attacker could conceivably record the ticket and authenticator -sent over the network to a server, then disable the client's host, pose as -the disabled host, and replay the ticket and authenticator to subvert the -authentication.). If a sequence number is provided in the authenticator, -the server saves it for later use in processing KRB_SAFE and/or KRB_PRIV -messages. If a subkey is present, the server either saves it for later use -or uses it to help generate its own choice for a subkey to be returned in a -KRB_AP_REP message. - -The server computes the age of the ticket: local (server) time minus the -start time inside the Ticket. If the start time is later than the current -time by more than the allowable clock skew or if the INVALID flag is set in -the ticket, the KRB_AP_ERR_TKT_NYV error is returned. Otherwise, if the -current time is later than end time by more than the allowable clock skew, -the KRB_AP_ERR_TKT_EXPIRED error is returned. - -If all these checks succeed without an error, the server is assured that - -Neuman, Ts'o, Kohl Expires: 18 May 1999 - - -INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 - - -the client possesses the credentials of the principal named in the ticket -and thus, the client has been authenticated to the server. See section A.10 -for pseudocode. - -Passing these checks provides only authentication of the named principal; -it does not imply authorization to use the named service. Applications must -make a separate authorization decisions based upon the authenticated name -of the user, the requested operation, local acces control information such -as that contained in a .k5login or .k5users file, and possibly a separate -distributed authorization service. - -3.2.4. Generation of a KRB_AP_REP message - -Typically, a client's request will include both the authentication -information and its initial request in the same message, and the server -need not explicitly reply to the KRB_AP_REQ. However, if mutual -authentication (not only authenticating the client to the server, but also -the server to the client) is being performed, the KRB_AP_REQ message will -have MUTUAL-REQUIRED set in its ap-options field, and a KRB_AP_REP message -is required in response. As with the error message, this message may be -encapsulated in the application protocol if its "raw" form is not -acceptable to the application's protocol. The timestamp and microsecond -field used in the reply must be the client's timestamp and microsecond -field (as provided in the authenticator)[12]. If a sequence number is to be -included, it should be randomly chosen as described above for the -authenticator. A subkey may be included if the server desires to negotiate -a different subkey. The KRB_AP_REP message is encrypted in the session key -extracted from the ticket. See section A.11 for pseudocode. - -3.2.5. Receipt of KRB_AP_REP message - -If a KRB_AP_REP message is returned, the client uses the session key from -the credentials obtained for the server[13] to decrypt the message, and -verifies that the timestamp and microsecond fields match those in the -Authenticator it sent to the server. If they match, then the client is -assured that the server is genuine. The sequence number and subkey (if -present) are retained for later use. See section A.12 for pseudocode. - -3.2.6. Using the encryption key - -After the KRB_AP_REQ/KRB_AP_REP exchange has occurred, the client and -server share an encryption key which can be used by the application. The -'true session key' to be used for KRB_PRIV, KRB_SAFE, or other -application-specific uses may be chosen by the application based on the -subkeys in the KRB_AP_REP message and the authenticator[14]. In some cases, -the use of this session key will be implicit in the protocol; in others the -method of use must be chosen from several alternatives. We leave the -protocol negotiations of how to use the key (e.g. selecting an encryption -or checksum type) to the application programmer; the Kerberos protocol does -not constrain the implementation options, but an example of how this might -be done follows. - -One way that an application may choose to negotiate a key to be used for -subequent integrity and privacy protection is for the client to propose a -key in the subkey field of the authenticator. The server can then choose a -key using the proposed key from the client as input, returning the new -subkey in the subkey field of the application reply. This key could then be -used for subsequent communication. To make this example more concrete, if -the encryption method in use required a 56 bit key, and for whatever - -Neuman, Ts'o, Kohl Expires: 18 May 1999 - - -INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 - - -reason, one of the parties was prevented from using a key with more than 40 -unknown bits, this method would allow the the party which is prevented from -using more than 40 bits to either propose (if the client) an initial key -with a known quantity for 16 of those bits, or to mask 16 of the bits (if -the server) with the known quantity. The application implementor is warned, -however, that this is only an example, and that an analysis of the -particular crytosystem to be used, and the reasons for limiting the key -length, must be made before deciding whether it is acceptable to mask bits -of the key. - -With both the one-way and mutual authentication exchanges, the peers should -take care not to send sensitive information to each other without proper -assurances. In particular, applications that require privacy or integrity -should use the KRB_AP_REP response from the server to client to assure both -client and server of their peer's identity. If an application protocol -requires privacy of its messages, it can use the KRB_PRIV message (section -3.5). The KRB_SAFE message (section 3.4) can be used to assure integrity. - -3.3. The Ticket-Granting Service (TGS) Exchange - - Summary - Message direction Message type Section - 1. Client to Kerberos KRB_TGS_REQ 5.4.1 - 2. Kerberos to client KRB_TGS_REP or 5.4.2 - KRB_ERROR 5.9.1 - -The TGS exchange between a client and the Kerberos Ticket-Granting Server -is initiated by a client when it wishes to obtain authentication -credentials for a given server (which might be registered in a remote -realm), when it wishes to renew or validate an existing ticket, or when it -wishes to obtain a proxy ticket. In the first case, the client must already -have acquired a ticket for the Ticket-Granting Service using the AS -exchange (the ticket-granting ticket is usually obtained when a client -initially authenticates to the system, such as when a user logs in). The -message format for the TGS exchange is almost identical to that for the AS -exchange. The primary difference is that encryption and decryption in the -TGS exchange does not take place under the client's key. Instead, the -session key from the ticket-granting ticket or renewable ticket, or -sub-session key from an Authenticator is used. As is the case for all -application servers, expired tickets are not accepted by the TGS, so once a -renewable or ticket-granting ticket expires, the client must use a separate -exchange to obtain valid tickets. - -The TGS exchange consists of two messages: A request (KRB_TGS_REQ) from the -client to the Kerberos Ticket-Granting Server, and a reply (KRB_TGS_REP or -KRB_ERROR). The KRB_TGS_REQ message includes information authenticating the -client plus a request for credentials. The authentication information -consists of the authentication header (KRB_AP_REQ) which includes the -client's previously obtained ticket-granting, renewable, or invalid ticket. -In the ticket-granting ticket and proxy cases, the request may include one -or more of: a list of network addresses, a collection of typed -authorization data to be sealed in the ticket for authorization use by the -application server, or additional tickets (the use of which are described -later). The TGS reply (KRB_TGS_REP) contains the requested credentials, -encrypted in the session key from the ticket-granting ticket or renewable -ticket, or if present, in the sub-session key from the Authenticator (part -of the authentication header). The KRB_ERROR message contains an error code -and text explaining what went wrong. The KRB_ERROR message is not -encrypted. The KRB_TGS_REP message contains information which can be used - -Neuman, Ts'o, Kohl Expires: 18 May 1999 - - -INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 - - -to detect replays, and to associate it with the message to which it -replies. The KRB_ERROR message also contains information which can be used -to associate it with the message to which it replies, but the lack of -encryption in the KRB_ERROR message precludes the ability to detect replays -or fabrications of such messages. - -3.3.1. Generation of KRB_TGS_REQ message - -Before sending a request to the ticket-granting service, the client must -determine in which realm the application server is registered[15]. If the -client does not already possess a ticket-granting ticket for the -appropriate realm, then one must be obtained. This is first attempted by -requesting a ticket-granting ticket for the destination realm from a -Kerberos server for which the client does posess a ticket-granting ticket -(using the KRB_TGS_REQ message recursively). The Kerberos server may return -a TGT for the desired realm in which case one can proceed. Alternatively, -the Kerberos server may return a TGT for a realm which is 'closer' to the -desired realm (further along the standard hierarchical path), in which case -this step must be repeated with a Kerberos server in the realm specified in -the returned TGT. If neither are returned, then the request must be retried -with a Kerberos server for a realm higher in the hierarchy. This request -will itself require a ticket-granting ticket for the higher realm which -must be obtained by recursively applying these directions. - -Once the client obtains a ticket-granting ticket for the appropriate realm, -it determines which Kerberos servers serve that realm, and contacts one. -The list might be obtained through a configuration file or network service -or it may be generated from the name of the realm; as long as the secret -keys exchanged by realms are kept secret, only denial of service results -from using a false Kerberos server. - -As in the AS exchange, the client may specify a number of options in the -KRB_TGS_REQ message. The client prepares the KRB_TGS_REQ message, providing -an authentication header as an element of the padata field, and including -the same fields as used in the KRB_AS_REQ message along with several -optional fields: the enc-authorization-data field for application server -use and additional tickets required by some options. - -In preparing the authentication header, the client can select a sub-session -key under which the response from the Kerberos server will be -encrypted[16]. If the sub-session key is not specified, the session key -from the ticket-granting ticket will be used. If the enc-authorization-data -is present, it must be encrypted in the sub-session key, if present, from -the authenticator portion of the authentication header, or if not present, -using the session key from the ticket-granting ticket. - -Once prepared, the message is sent to a Kerberos server for the destination -realm. See section A.5 for pseudocode. - -3.3.2. Receipt of KRB_TGS_REQ message - -The KRB_TGS_REQ message is processed in a manner similar to the KRB_AS_REQ -message, but there are many additional checks to be performed. First, the -Kerberos server must determine which server the accompanying ticket is for -and it must select the appropriate key to decrypt it. For a normal -KRB_TGS_REQ message, it will be for the ticket granting service, and the -TGS's key will be used. If the TGT was issued by another realm, then the -appropriate inter-realm key must be used. If the accompanying ticket is not -a ticket granting ticket for the current realm, but is for an application - -Neuman, Ts'o, Kohl Expires: 18 May 1999 - - -INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 - - -server in the current realm, the RENEW, VALIDATE, or PROXY options are -specified in the request, and the server for which a ticket is requested is -the server named in the accompanying ticket, then the KDC will decrypt the -ticket in the authentication header using the key of the server for which -it was issued. If no ticket can be found in the padata field, the -KDC_ERR_PADATA_TYPE_NOSUPP error is returned. - -Once the accompanying ticket has been decrypted, the user-supplied checksum -in the Authenticator must be verified against the contents of the request, -and the message rejected if the checksums do not match (with an error code -of KRB_AP_ERR_MODIFIED) or if the checksum is not keyed or not -collision-proof (with an error code of KRB_AP_ERR_INAPP_CKSUM). If the -checksum type is not supported, the KDC_ERR_SUMTYPE_NOSUPP error is -returned. If the authorization-data are present, they are decrypted using -the sub-session key from the Authenticator. - -If any of the decryptions indicate failed integrity checks, the -KRB_AP_ERR_BAD_INTEGRITY error is returned. - -3.3.3. Generation of KRB_TGS_REP message - -The KRB_TGS_REP message shares its format with the KRB_AS_REP -(KRB_KDC_REP), but with its type field set to KRB_TGS_REP. The detailed -specification is in section 5.4.2. - -The response will include a ticket for the requested server. The Kerberos -database is queried to retrieve the record for the requested server -(including the key with which the ticket will be encrypted). If the request -is for a ticket granting ticket for a remote realm, and if no key is shared -with the requested realm, then the Kerberos server will select the realm -"closest" to the requested realm with which it does share a key, and use -that realm instead. This is the only case where the response from the KDC -will be for a different server than that requested by the client. - -By default, the address field, the client's name and realm, the list of -transited realms, the time of initial authentication, the expiration time, -and the authorization data of the newly-issued ticket will be copied from -the ticket-granting ticket (TGT) or renewable ticket. If the transited -field needs to be updated, but the transited type is not supported, the -KDC_ERR_TRTYPE_NOSUPP error is returned. - -If the request specifies an endtime, then the endtime of the new ticket is -set to the minimum of (a) that request, (b) the endtime from the TGT, and -(c) the starttime of the TGT plus the minimum of the maximum life for the -application server and the maximum life for the local realm (the maximum -life for the requesting principal was already applied when the TGT was -issued). If the new ticket is to be a renewal, then the endtime above is -replaced by the minimum of (a) the value of the renew_till field of the -ticket and (b) the starttime for the new ticket plus the life -(endtime-starttime) of the old ticket. - -If the FORWARDED option has been requested, then the resulting ticket will -contain the addresses specified by the client. This option will only be -honored if the FORWARDABLE flag is set in the TGT. The PROXY option is -similar; the resulting ticket will contain the addresses specified by the -client. It will be honored only if the PROXIABLE flag in the TGT is set. -The PROXY option will not be honored on requests for additional -ticket-granting tickets. - - -Neuman, Ts'o, Kohl Expires: 18 May 1999 - - -INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 - - -If the requested start time is absent, indicates a time in the past, or is -within the window of acceptable clock skew for the KDC and the POSTDATE -option has not been specified, then the start time of the ticket is set to -the authentication server's current time. If it indicates a time in the -future beyond the acceptable clock skew, but the POSTDATED option has not -been specified or the MAY-POSTDATE flag is not set in the TGT, then the -error KDC_ERR_CANNOT_POSTDATE is returned. Otherwise, if the -ticket-granting ticket has the MAY-POSTDATE flag set, then the resulting -ticket will be postdated and the requested starttime is checked against the -policy of the local realm. If acceptable, the ticket's start time is set as -requested, and the INVALID flag is set. The postdated ticket must be -validated before use by presenting it to the KDC after the starttime has -been reached. However, in no case may the starttime, endtime, or renew-till -time of a newly-issued postdated ticket extend beyond the renew-till time -of the ticket-granting ticket. - -If the ENC-TKT-IN-SKEY option has been specified and an additional ticket -has been included in the request, the KDC will decrypt the additional -ticket using the key for the server to which the additional ticket was -issued and verify that it is a ticket-granting ticket. If the name of the -requested server is missing from the request, the name of the client in the -additional ticket will be used. Otherwise the name of the requested server -will be compared to the name of the client in the additional ticket and if -different, the request will be rejected. If the request succeeds, the -session key from the additional ticket will be used to encrypt the new -ticket that is issued instead of using the key of the server for which the -new ticket will be used[17]. - -If the name of the server in the ticket that is presented to the KDC as -part of the authentication header is not that of the ticket-granting server -itself, the server is registered in the realm of the KDC, and the RENEW -option is requested, then the KDC will verify that the RENEWABLE flag is -set in the ticket, that the INVALID flag is not set in the ticket, and that -the renew_till time is still in the future. If the VALIDATE option is -rqeuested, the KDC will check that the starttime has passed and the INVALID -flag is set. If the PROXY option is requested, then the KDC will check that -the PROXIABLE flag is set in the ticket. If the tests succeed, and the -ticket passes the hotlist check described in the next paragraph, the KDC -will issue the appropriate new ticket. - -3.3.3.1. Checking for revoked tickets - -Whenever a request is made to the ticket-granting server, the presented -ticket(s) is(are) checked against a hot-list of tickets which have been -canceled. This hot-list might be implemented by storing a range of issue -timestamps for 'suspect tickets'; if a presented ticket had an authtime in -that range, it would be rejected. In this way, a stolen ticket-granting -ticket or renewable ticket cannot be used to gain additional tickets -(renewals or otherwise) once the theft has been reported. Any normal ticket -obtained before it was reported stolen will still be valid (because they -require no interaction with the KDC), but only until their normal -expiration time. - -The ciphertext part of the response in the KRB_TGS_REP message is encrypted -in the sub-session key from the Authenticator, if present, or the session -key key from the ticket-granting ticket. It is not encrypted using the -client's secret key. Furthermore, the client's key's expiration date and -the key version number fields are left out since these values are stored -along with the client's database record, and that record is not needed to - -Neuman, Ts'o, Kohl Expires: 18 May 1999 - - -INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 - - -satisfy a request based on a ticket-granting ticket. See section A.6 for -pseudocode. - -3.3.3.2. Encoding the transited field - -If the identity of the server in the TGT that is presented to the KDC as -part of the authentication header is that of the ticket-granting service, -but the TGT was issued from another realm, the KDC will look up the -inter-realm key shared with that realm and use that key to decrypt the -ticket. If the ticket is valid, then the KDC will honor the request, -subject to the constraints outlined above in the section describing the AS -exchange. The realm part of the client's identity will be taken from the -ticket-granting ticket. The name of the realm that issued the -ticket-granting ticket will be added to the transited field of the ticket -to be issued. This is accomplished by reading the transited field from the -ticket-granting ticket (which is treated as an unordered set of realm -names), adding the new realm to the set, then constructing and writing out -its encoded (shorthand) form (this may involve a rearrangement of the -existing encoding). - -Note that the ticket-granting service does not add the name of its own -realm. Instead, its responsibility is to add the name of the previous -realm. This prevents a malicious Kerberos server from intentionally leaving -out its own name (it could, however, omit other realms' names). - -The names of neither the local realm nor the principal's realm are to be -included in the transited field. They appear elsewhere in the ticket and -both are known to have taken part in authenticating the principal. Since -the endpoints are not included, both local and single-hop inter-realm -authentication result in a transited field that is empty. - -Because the name of each realm transited is added to this field, it might -potentially be very long. To decrease the length of this field, its -contents are encoded. The initially supported encoding is optimized for the -normal case of inter-realm communication: a hierarchical arrangement of -realms using either domain or X.500 style realm names. This encoding -(called DOMAIN-X500-COMPRESS) is now described. - -Realm names in the transited field are separated by a ",". The ",", "\", -trailing "."s, and leading spaces (" ") are special characters, and if they -are part of a realm name, they must be quoted in the transited field by -preced- ing them with a "\". - -A realm name ending with a "." is interpreted as being prepended to the -previous realm. For example, we can encode traversal of EDU, MIT.EDU, -ATHENA.MIT.EDU, WASHINGTON.EDU, and CS.WASHINGTON.EDU as: - - "EDU,MIT.,ATHENA.,WASHINGTON.EDU,CS.". - -Note that if ATHENA.MIT.EDU, or CS.WASHINGTON.EDU were end-points, that -they would not be included in this field, and we would have: - - "EDU,MIT.,WASHINGTON.EDU" - -A realm name beginning with a "/" is interpreted as being appended to the -previous realm[18]. If it is to stand by itself, then it should be preceded -by a space (" "). For example, we can encode traversal of /COM/HP/APOLLO, -/COM/HP, /COM, and /COM/DEC as: - - -Neuman, Ts'o, Kohl Expires: 18 May 1999 - - -INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 - - - "/COM,/HP,/APOLLO, /COM/DEC". - -Like the example above, if /COM/HP/APOLLO and /COM/DEC are endpoints, they -they would not be included in this field, and we would have: - - "/COM,/HP" - -A null subfield preceding or following a "," indicates that all realms -between the previous realm and the next realm have been traversed[19]. -Thus, "," means that all realms along the path between the client and the -server have been traversed. ",EDU, /COM," means that that all realms from -the client's realm up to EDU (in a domain style hierarchy) have been -traversed, and that everything from /COM down to the server's realm in an -X.500 style has also been traversed. This could occur if the EDU realm in -one hierarchy shares an inter-realm key directly with the /COM realm in -another hierarchy. - -3.3.4. Receipt of KRB_TGS_REP message - -When the KRB_TGS_REP is received by the client, it is processed in the same -manner as the KRB_AS_REP processing described above. The primary difference -is that the ciphertext part of the response must be decrypted using the -session key from the ticket-granting ticket rather than the client's secret -key. See section A.7 for pseudocode. - -3.4. The KRB_SAFE Exchange - -The KRB_SAFE message may be used by clients requiring the ability to detect -modifications of messages they exchange. It achieves this by including a -keyed collision-proof checksum of the user data and some control -information. The checksum is keyed with an encryption key (usually the last -key negotiated via subkeys, or the session key if no negotiation has -occured). - -3.4.1. Generation of a KRB_SAFE message - -When an application wishes to send a KRB_SAFE message, it collects its data -and the appropriate control information and computes a checksum over them. -The checksum algorithm should be a keyed one-way hash function (such as the -RSA- MD5-DES checksum algorithm specified in section 6.4.5, or the DES -MAC), generated using the sub-session key if present, or the session key. -Different algorithms may be selected by changing the checksum type in the -message. Unkeyed or non-collision-proof checksums are not suitable for this -use. - -The control information for the KRB_SAFE message includes both a timestamp -and a sequence number. The designer of an application using the KRB_SAFE -message must choose at least one of the two mechanisms. This choice should -be based on the needs of the application protocol. - -Sequence numbers are useful when all messages sent will be received by -one's peer. Connection state is presently required to maintain the session -key, so maintaining the next sequence number should not present an -additional problem. - -If the application protocol is expected to tolerate lost messages without -them being resent, the use of the timestamp is the appropriate replay -detection mechanism. Using timestamps is also the appropriate mechanism for -multi-cast protocols where all of one's peers share a common sub-session - -Neuman, Ts'o, Kohl Expires: 18 May 1999 - - -INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 - - -key, but some messages will be sent to a subset of one's peers. - -After computing the checksum, the client then transmits the information and -checksum to the recipient in the message format specified in section 5.6.1. - -3.4.2. Receipt of KRB_SAFE message - -When an application receives a KRB_SAFE message, it verifies it as follows. -If any error occurs, an error code is reported for use by the application. - -The message is first checked by verifying that the protocol version and -type fields match the current version and KRB_SAFE, respectively. A -mismatch generates a KRB_AP_ERR_BADVERSION or KRB_AP_ERR_MSG_TYPE error. -The application verifies that the checksum used is a collision-proof keyed -checksum, and if it is not, a KRB_AP_ERR_INAPP_CKSUM error is generated. -The recipient verifies that the operating system's report of the sender's -address matches the sender's address in the message, and (if a recipient -address is specified or the recipient requires an address) that one of the -recipient's addresses appears as the recipient's address in the message. A -failed match for either case generates a KRB_AP_ERR_BADADDR error. Then the -timestamp and usec and/or the sequence number fields are checked. If -timestamp and usec are expected and not present, or they are present but -not current, the KRB_AP_ERR_SKEW error is generated. If the server name, -along with the client name, time and microsecond fields from the -Authenticator match any recently-seen (sent or received[20] ) such tuples, -the KRB_AP_ERR_REPEAT error is generated. If an incorrect sequence number -is included, or a sequence number is expected but not present, the -KRB_AP_ERR_BADORDER error is generated. If neither a time-stamp and usec or -a sequence number is present, a KRB_AP_ERR_MODIFIED error is generated. -Finally, the checksum is computed over the data and control information, -and if it doesn't match the received checksum, a KRB_AP_ERR_MODIFIED error -is generated. - -If all the checks succeed, the application is assured that the message was -generated by its peer and was not modi- fied in transit. - -3.5. The KRB_PRIV Exchange - -The KRB_PRIV message may be used by clients requiring confidentiality and -the ability to detect modifications of exchanged messages. It achieves this -by encrypting the messages and adding control information. - -3.5.1. Generation of a KRB_PRIV message - -When an application wishes to send a KRB_PRIV message, it collects its data -and the appropriate control information (specified in section 5.7.1) and -encrypts them under an encryption key (usually the last key negotiated via -subkeys, or the session key if no negotiation has occured). As part of the -control information, the client must choose to use either a timestamp or a -sequence number (or both); see the discussion in section 3.4.1 for -guidelines on which to use. After the user data and control information are -encrypted, the client transmits the ciphertext and some 'envelope' -information to the recipient. - -3.5.2. Receipt of KRB_PRIV message - -When an application receives a KRB_PRIV message, it verifies it as follows. -If any error occurs, an error code is reported for use by the application. - - -Neuman, Ts'o, Kohl Expires: 18 May 1999 - - -INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 - - -The message is first checked by verifying that the protocol version and -type fields match the current version and KRB_PRIV, respectively. A -mismatch generates a KRB_AP_ERR_BADVERSION or KRB_AP_ERR_MSG_TYPE error. -The application then decrypts the ciphertext and processes the resultant -plaintext. If decryption shows the data to have been modified, a -KRB_AP_ERR_BAD_INTEGRITY error is generated. The recipient verifies that -the operating system's report of the sender's address matches the sender's -address in the message, and (if a recipient address is specified or the -recipient requires an address) that one of the recipient's addresses -appears as the recipient's address in the message. A failed match for -either case generates a KRB_AP_ERR_BADADDR error. Then the timestamp and -usec and/or the sequence number fields are checked. If timestamp and usec -are expected and not present, or they are present but not current, the -KRB_AP_ERR_SKEW error is generated. If the server name, along with the -client name, time and microsecond fields from the Authenticator match any -recently-seen such tuples, the KRB_AP_ERR_REPEAT error is generated. If an -incorrect sequence number is included, or a sequence number is expected but -not present, the KRB_AP_ERR_BADORDER error is generated. If neither a -time-stamp and usec or a sequence number is present, a KRB_AP_ERR_MODIFIED -error is generated. - -If all the checks succeed, the application can assume the message was -generated by its peer, and was securely transmitted (without intruders able -to see the unencrypted contents). - -3.6. The KRB_CRED Exchange - -The KRB_CRED message may be used by clients requiring the ability to send -Kerberos credentials from one host to another. It achieves this by sending -the tickets together with encrypted data containing the session keys and -other information associated with the tickets. - -3.6.1. Generation of a KRB_CRED message - -When an application wishes to send a KRB_CRED message it first (using the -KRB_TGS exchange) obtains credentials to be sent to the remote host. It -then constructs a KRB_CRED message using the ticket or tickets so obtained, -placing the session key needed to use each ticket in the key field of the -corresponding KrbCredInfo sequence of the encrypted part of the the -KRB_CRED message. - -Other information associated with each ticket and obtained during the -KRB_TGS exchange is also placed in the corresponding KrbCredInfo sequence -in the encrypted part of the KRB_CRED message. The current time and, if -specifically required by the application the nonce, s-address, and -r-address fields, are placed in the encrypted part of the KRB_CRED message -which is then encrypted under an encryption key previosuly exchanged in the -KRB_AP exchange (usually the last key negotiated via subkeys, or the -session key if no negotiation has occured). - -3.6.2. Receipt of KRB_CRED message - -When an application receives a KRB_CRED message, it verifies it. If any -error occurs, an error code is reported for use by the application. The -message is verified by checking that the protocol version and type fields -match the current version and KRB_CRED, respectively. A mismatch generates -a KRB_AP_ERR_BADVERSION or KRB_AP_ERR_MSG_TYPE error. The application then -decrypts the ciphertext and processes the resultant plaintext. If -decryption shows the data to have been modified, a KRB_AP_ERR_BAD_INTEGRITY - -Neuman, Ts'o, Kohl Expires: 18 May 1999 - - -INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 - - -error is generated. - -If present or required, the recipient verifies that the operating system's -report of the sender's address matches the sender's address in the message, -and that one of the recipient's addresses appears as the recipient's -address in the message. A failed match for either case generates a -KRB_AP_ERR_BADADDR error. The timestamp and usec fields (and the nonce -field if required) are checked next. If the timestamp and usec are not -present, or they are present but not current, the KRB_AP_ERR_SKEW error is -generated. - -If all the checks succeed, the application stores each of the new tickets -in its ticket cache together with the session key and other information in -the corresponding KrbCredInfo sequence from the encrypted part of the -KRB_CRED message. - -4. The Kerberos Database - -The Kerberos server must have access to a database contain- ing the -principal identifiers and secret keys of principals to be -authenticated[21]. - -4.1. Database contents - -A database entry should contain at least the following fields: - -Field Value - -name Principal's identifier -key Principal's secret key -p_kvno Principal's key version -max_life Maximum lifetime for Tickets -max_renewable_life Maximum total lifetime for renewable Tickets - -The name field is an encoding of the principal's identifier. The key field -contains an encryption key. This key is the principal's secret key. (The -key can be encrypted before storage under a Kerberos "master key" to -protect it in case the database is compromised but the master key is not. -In that case, an extra field must be added to indicate the master key -version used, see below.) The p_kvno field is the key version number of the -principal's secret key. The max_life field contains the maximum allowable -lifetime (endtime - starttime) for any Ticket issued for this principal. -The max_renewable_life field contains the maximum allowable total lifetime -for any renewable Ticket issued for this principal. (See section 3.1 for a -description of how these lifetimes are used in determining the lifetime of -a given Ticket.) - -A server may provide KDC service to several realms, as long as the database -representation provides a mechanism to distinguish between principal -records with identifiers which differ only in the realm name. - -When an application server's key changes, if the change is routine (i.e. -not the result of disclosure of the old key), the old key should be -retained by the server until all tickets that had been issued using that -key have expired. Because of this, it is possible for several keys to be -active for a single principal. Ciphertext encrypted in a principal's key is -always tagged with the version of the key that was used for encryption, to -help the recipient find the proper key for decryption. - - -Neuman, Ts'o, Kohl Expires: 18 May 1999 - - -INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 - - -When more than one key is active for a particular principal, the principal -will have more than one record in the Kerberos database. The keys and key -version numbers will differ between the records (the rest of the fields may -or may not be the same). Whenever Kerberos issues a ticket, or responds to -a request for initial authentication, the most recent key (known by the -Kerberos server) will be used for encryption. This is the key with the -highest key version number. - -4.2. Additional fields - -Project Athena's KDC implementation uses additional fields in its database: - -Field Value - -K_kvno Kerberos' key version -expiration Expiration date for entry -attributes Bit field of attributes -mod_date Timestamp of last modification -mod_name Modifying principal's identifier - -The K_kvno field indicates the key version of the Kerberos master key under -which the principal's secret key is encrypted. - -After an entry's expiration date has passed, the KDC will return an error -to any client attempting to gain tickets as or for the principal. (A -database may want to maintain two expiration dates: one for the principal, -and one for the principal's current key. This allows password aging to work -independently of the principal's expiration date. However, due to the -limited space in the responses, the KDC must combine the key expiration and -principal expiration date into a single value called 'key_exp', which is -used as a hint to the user to take administrative action.) - -The attributes field is a bitfield used to govern the operations involving -the principal. This field might be useful in conjunction with user -registration procedures, for site-specific policy implementations (Project -Athena currently uses it for their user registration process controlled by -the system-wide database service, Moira [LGDSR87]), to identify whether a -principal can play the role of a client or server or both, to note whether -a server is appropriate trusted to recieve credentials delegated by a -client, or to identify the 'string to key' conversion algorithm used for a -principal's key[22]. Other bits are used to indicate that certain ticket -options should not be allowed in tickets encrypted under a principal's key -(one bit each): Disallow issuing postdated tickets, disallow issuing -forwardable tickets, disallow issuing tickets based on TGT authentication, -disallow issuing renewable tickets, disallow issuing proxiable tickets, and -disallow issuing tickets for which the principal is the server. - -The mod_date field contains the time of last modification of the entry, and -the mod_name field contains the name of the principal which last modified -the entry. - -4.3. Frequently Changing Fields - -Some KDC implementations may wish to maintain the last time that a request -was made by a particular principal. Information that might be maintained -includes the time of the last request, the time of the last request for a -ticket-granting ticket, the time of the last use of a ticket-granting -ticket, or other times. This information can then be returned to the user -in the last-req field (see section 5.2). - -Neuman, Ts'o, Kohl Expires: 18 May 1999 - - -INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 - - - -Other frequently changing information that can be maintained is the latest -expiration time for any tickets that have been issued using each key. This -field would be used to indicate how long old keys must remain valid to -allow the continued use of outstanding tickets. - -4.4. Site Constants - -The KDC implementation should have the following configurable constants or -options, to allow an administrator to make and enforce policy decisions: - - * The minimum supported lifetime (used to determine whether the - KDC_ERR_NEVER_VALID error should be returned). This constant should - reflect reasonable expectations of round-trip time to the KDC, - encryption/decryption time, and processing time by the client and - target server, and it should allow for a minimum 'useful' lifetime. - * The maximum allowable total (renewable) lifetime of a ticket - (renew_till - starttime). - * The maximum allowable lifetime of a ticket (endtime - starttime). - * Whether to allow the issue of tickets with empty address fields - (including the ability to specify that such tickets may only be issued - if the request specifies some authorization_data). - * Whether proxiable, forwardable, renewable or post-datable tickets are - to be issued. - -5. Message Specifications - -The following sections describe the exact contents and encoding of protocol -messages and objects. The ASN.1 base definitions are presented in the first -subsection. The remaining subsections specify the protocol objects (tickets -and authenticators) and messages. Specification of encryption and checksum -techniques, and the fields related to them, appear in section 6. - -Optional field in ASN.1 sequences - -For optional integer value and date fields in ASN.1 sequences where a -default value has been specified, certain default values will not be -allowed in the encoding because these values will always be represented -through defaulting by the absence of the optional field. For example, one -will not send a microsecond zero value because one must make sure that -there is only one way to encode this value. - -Additional fields in ASN.1 sequences - -Implementations receiving Kerberos messages with additional fields present -in ASN.1 sequences should carry the those fields through unmodified when -the message is forwarded. Implementation should drop such fields if the -sequence is reencoded. - -5.1. ASN.1 Distinguished Encoding Representation - -All uses of ASN.1 in Kerberos shall use the Distinguished Encoding -Representation of the data elements as described in the X.509 -specification, section 8.7 [X509-88]. - -5.3. ASN.1 Base Definitions - -The following ASN.1 base definitions are used in the rest of this section. -Note that since the underscore character (_) is not permitted in ASN.1 - -Neuman, Ts'o, Kohl Expires: 18 May 1999 - - -INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 - - -names, the hyphen (-) is used in its place for the purposes of ASN.1 names. - -Realm ::= GeneralString -PrincipalName ::= SEQUENCE { - name-type[0] INTEGER, - name-string[1] SEQUENCE OF GeneralString -} - -Kerberos realms are encoded as GeneralStrings. Realms shall not contain a -character with the code 0 (the ASCII NUL). Most realms will usually consist -of several components separated by periods (.), in the style of Internet -Domain Names, or separated by slashes (/) in the style of X.500 names. -Acceptable forms for realm names are specified in section 7. A -PrincipalName is a typed sequence of components consisting of the following -sub-fields: - -name-type - This field specifies the type of name that follows. Pre-defined values - for this field are specified in section 7.2. The name-type should be - treated as a hint. Ignoring the name type, no two names can be the - same (i.e. at least one of the components, or the realm, must be - different). This constraint may be eliminated in the future. -name-string - This field encodes a sequence of components that form a name, each - component encoded as a GeneralString. Taken together, a PrincipalName - and a Realm form a principal identifier. Most PrincipalNames will have - only a few components (typically one or two). - -KerberosTime ::= GeneralizedTime - -- Specifying UTC time zone (Z) - -The timestamps used in Kerberos are encoded as GeneralizedTimes. An -encoding shall specify the UTC time zone (Z) and shall not include any -fractional portions of the seconds. It further shall not include any -separators. Example: The only valid format for UTC time 6 minutes, 27 -seconds after 9 pm on 6 November 1985 is 19851106210627Z. - -HostAddress ::= SEQUENCE { - addr-type[0] INTEGER, - address[1] OCTET STRING -} - -HostAddresses ::= SEQUENCE OF HostAddress - -The host adddress encodings consists of two fields: - -addr-type - This field specifies the type of address that follows. Pre-defined - values for this field are specified in section 8.1. -address - This field encodes a single address of type addr-type. - -The two forms differ slightly. HostAddress contains exactly one address; -HostAddresses contains a sequence of possibly many addresses. - -AuthorizationData ::= SEQUENCE OF SEQUENCE { - ad-type[0] INTEGER, - ad-data[1] OCTET STRING -} - -Neuman, Ts'o, Kohl Expires: 18 May 1999 - - -INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 - - - -ad-data - This field contains authorization data to be interpreted according to - the value of the corresponding ad-type field. -ad-type - This field specifies the format for the ad-data subfield. All negative - values are reserved for local use. Non-negative values are reserved - for registered use. - -Each sequence of type and data is refered to as an authorization element. -Elements may be application specific, however, there is a common set of -recursive elements that should be understood by all implementations. These -elements contain other elements embedded within them, and the -interpretation of the encapsulating element determines which of the -embedded elements must be interpreted, and which may be ignored. -Definitions for these common elements may be found in Appendix B. - -TicketExtensions ::= SEQUENCE OF SEQUENCE { - te-type[0] INTEGER, - te-data[1] OCTET STRING -} - - - -te-data - This field contains opaque data that must be caried with the ticket to - support extensions to the Kerberos protocol including but not limited - to some forms of inter-realm key exchange and plaintext authorization - data. See appendix C for some common uses of this field. -te-type - This field specifies the format for the te-data subfield. All negative - values are reserved for local use. Non-negative values are reserved - for registered use. - -APOptions ::= BIT STRING - -- reserved(0), - -- use-session-key(1), - -- mutual-required(2) - -TicketFlags ::= BIT STRING - -- reserved(0), - -- forwardable(1), - -- forwarded(2), - -- proxiable(3), - -- proxy(4), - -- may-postdate(5), - -- postdated(6), - -- invalid(7), - -- renewable(8), - -- initial(9), - -- pre-authent(10), - -- hw-authent(11), - -- transited-policy-checked(12), - -- ok-as-delegate(13) - -KDCOptions ::= BIT STRING - -- reserved(0), - -- forwardable(1), - -- forwarded(2), - -Neuman, Ts'o, Kohl Expires: 18 May 1999 - - -INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 - - - -- proxiable(3), - -- proxy(4), - -- allow-postdate(5), - -- postdated(6), - -- unused7(7), - -- renewable(8), - -- unused9(9), - -- unused10(10), - -- unused11(11), - -- unused12(12), - -- unused13(13), - -- disable-transited-check(26), - -- renewable-ok(27), - -- enc-tkt-in-skey(28), - -- renew(30), - -- validate(31) - -ASN.1 Bit strings have a length and a value. When used in Kerberos for the -APOptions, TicketFlags, and KDCOptions, the length of the bit string on -generated values should be the smallest number of bits needed to include -the highest order bit that is set (1), but in no case less than 32 bits. -The ASN.1 representation of the bit strings uses unnamed bits, with the -meaning of the individual bits defined by the comments in the specification -above. Implementations should accept values of bit strings of any length -and treat the value of flags corresponding to bits beyond the end of the -bit string as if the bit were reset (0). Comparison of bit strings of -different length should treat the smaller string as if it were padded with -zeros beyond the high order bits to the length of the longer string[23]. - -LastReq ::= SEQUENCE OF SEQUENCE { - lr-type[0] INTEGER, - lr-value[1] KerberosTime -} - -lr-type - This field indicates how the following lr-value field is to be - interpreted. Negative values indicate that the information pertains - only to the responding server. Non-negative values pertain to all - servers for the realm. If the lr-type field is zero (0), then no - information is conveyed by the lr-value subfield. If the absolute - value of the lr-type field is one (1), then the lr-value subfield is - the time of last initial request for a TGT. If it is two (2), then the - lr-value subfield is the time of last initial request. If it is three - (3), then the lr-value subfield is the time of issue for the newest - ticket-granting ticket used. If it is four (4), then the lr-value - subfield is the time of the last renewal. If it is five (5), then the - lr-value subfield is the time of last request (of any type). If it is - (6), then the lr-value subfield is the time when the password will - expire. -lr-value - This field contains the time of the last request. the time must be - interpreted according to the contents of the accompanying lr-type - subfield. - -See section 6 for the definitions of Checksum, ChecksumType, EncryptedData, -EncryptionKey, EncryptionType, and KeyType. - -5.3. Tickets and Authenticators - - -Neuman, Ts'o, Kohl Expires: 18 May 1999 - - -INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 - - -This section describes the format and encryption parameters for tickets and -authenticators. When a ticket or authenticator is included in a protocol -message it is treated as an opaque object. - -5.3.1. Tickets - -A ticket is a record that helps a client authenticate to a service. A -Ticket contains the following information: - -Ticket ::= [APPLICATION 1] SEQUENCE { - tkt-vno[0] INTEGER, - realm[1] Realm, - sname[2] PrincipalName, - enc-part[3] EncryptedData, - extensions[4] TicketExtensions OPTIONAL -} - --- Encrypted part of ticket -EncTicketPart ::= [APPLICATION 3] SEQUENCE { - flags[0] TicketFlags, - key[1] EncryptionKey, - crealm[2] Realm, - cname[3] PrincipalName, - transited[4] TransitedEncoding, - authtime[5] KerberosTime, - starttime[6] KerberosTime OPTIONAL, - endtime[7] KerberosTime, - renew-till[8] KerberosTime OPTIONAL, - caddr[9] HostAddresses OPTIONAL, - authorization-data[10] AuthorizationData OPTIONAL -} --- encoded Transited field -TransitedEncoding ::= SEQUENCE { - tr-type[0] INTEGER, -- must be -registered - contents[1] OCTET STRING -} - -The encoding of EncTicketPart is encrypted in the key shared by Kerberos -and the end server (the server's secret key). See section 6 for the format -of the ciphertext. - -tkt-vno - This field specifies the version number for the ticket format. This - document describes version number 5. -realm - This field specifies the realm that issued a ticket. It also serves to - identify the realm part of the server's principal identifier. Since a - Kerberos server can only issue tickets for servers within its realm, - the two will always be identical. -sname - This field specifies the name part of the server's identity. -enc-part - This field holds the encrypted encoding of the EncTicketPart sequence. -extensions - This optional field contains a sequence of extentions that may be used - to carry information that must be carried with the ticket to support - several extensions, including but not limited to plaintext - authorization data, tokens for exchanging inter-realm keys, and other - information that must be associated with a ticket for use by the - -Neuman, Ts'o, Kohl Expires: 18 May 1999 - - -INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 - - - application server. See Appendix C for definitions of some common - extensions. - - Note that some older versions of Kerberos did not support this field. - Because this is an optional field it will not break older clients, but - older clients might strip this field from the ticket before sending it - to the application server. This limits the usefulness of this ticket - field to environments where the ticket will not be parsed and - reconstructed by these older Kerberos clients. - - If it is known that the client will strip this field from the ticket, - as an interim measure the KDC may append this field to the end of the - enc-part of the ticket and append a traler indicating the lenght of - the appended extensions field. (this paragraph is open for discussion, - including the form of the traler). -flags - This field indicates which of various options were used or requested - when the ticket was issued. It is a bit-field, where the selected - options are indicated by the bit being set (1), and the unselected - options and reserved fields being reset (0). Bit 0 is the most - significant bit. The encoding of the bits is specified in section 5.2. - The flags are described in more detail above in section 2. The - meanings of the flags are: - - Bit(s) Name Description - - 0 RESERVED - Reserved for future expansion of this - field. - - 1 FORWARDABLE - The FORWARDABLE flag is normally only - interpreted by the TGS, and can be - ignored by end servers. When set, this - flag tells the ticket-granting server - that it is OK to issue a new ticket- - granting ticket with a different network - address based on the presented ticket. - - 2 FORWARDED - When set, this flag indicates that the - ticket has either been forwarded or was - issued based on authentication involving - a forwarded ticket-granting ticket. - - 3 PROXIABLE - The PROXIABLE flag is normally only - interpreted by the TGS, and can be - ignored by end servers. The PROXIABLE - flag has an interpretation identical to - that of the FORWARDABLE flag, except - that the PROXIABLE flag tells the - ticket-granting server that only non- - ticket-granting tickets may be issued - with different network addresses. - - 4 PROXY - When set, this flag indicates that a - ticket is a proxy. - -Neuman, Ts'o, Kohl Expires: 18 May 1999 - - -INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 - - - - 5 MAY-POSTDATE - The MAY-POSTDATE flag is normally only - interpreted by the TGS, and can be - ignored by end servers. This flag tells - the ticket-granting server that a post- - dated ticket may be issued based on this - ticket-granting ticket. - - 6 POSTDATED - This flag indicates that this ticket has - been postdated. The end-service can - check the authtime field to see when the - original authentication occurred. - - 7 INVALID - This flag indicates that a ticket is - invalid, and it must be validated by the - KDC before use. Application servers - must reject tickets which have this flag - set. - - 8 RENEWABLE - The RENEWABLE flag is normally only - interpreted by the TGS, and can usually - be ignored by end servers (some particu- - larly careful servers may wish to disal- - low renewable tickets). A renewable - ticket can be used to obtain a replace- - ment ticket that expires at a later - date. - - 9 INITIAL - This flag indicates that this ticket was - issued using the AS protocol, and not - issued based on a ticket-granting - ticket. - - 10 PRE-AUTHENT - This flag indicates that during initial - authentication, the client was authenti- - cated by the KDC before a ticket was - issued. The strength of the pre- - authentication method is not indicated, - but is acceptable to the KDC. - - 11 HW-AUTHENT - This flag indicates that the protocol - employed for initial authentication - required the use of hardware expected to - be possessed solely by the named client. - The hardware authentication method is - selected by the KDC and the strength of - the method is not indicated. - - 12 TRANSITED This flag indicates that the KDC for the - POLICY-CHECKED realm has checked the transited field - against a realm defined policy for - trusted certifiers. If this flag is - -Neuman, Ts'o, Kohl Expires: 18 May 1999 - - -INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 - - - reset (0), then the application server - must check the transited field itself, - and if unable to do so it must reject - the authentication. If the flag is set - (1) then the application server may skip - its own validation of the transited - field, relying on the validation - performed by the KDC. At its option the - application server may still apply its - own validation based on a separate - policy for acceptance. - - 13 OK-AS-DELEGATE This flag indicates that the server (not - the client) specified in the ticket has - been determined by policy of the realm - to be a suitable recipient of - delegation. A client can use the - presence of this flag to help it make a - decision whether to delegate credentials - (either grant a proxy or a forwarded - ticket granting ticket) to this server. - The client is free to ignore the value - of this flag. When setting this flag, - an administrator should consider the - Security and placement of the server on - which the service will run, as well as - whether the service requires the use of - delegated credentials. - - 14 ANONYMOUS - This flag indicates that the principal - named in the ticket is a generic princi- - pal for the realm and does not identify - the individual using the ticket. The - purpose of the ticket is only to - securely distribute a session key, and - not to identify the user. Subsequent - requests using the same ticket and ses- - sion may be considered as originating - from the same user, but requests with - the same username but a different ticket - are likely to originate from different - users. - - 15-31 RESERVED - Reserved for future use. - -key - This field exists in the ticket and the KDC response and is used to - pass the session key from Kerberos to the application server and the - client. The field's encoding is described in section 6.2. -crealm - This field contains the name of the realm in which the client is - registered and in which initial authentication took place. -cname - This field contains the name part of the client's principal - identifier. -transited - This field lists the names of the Kerberos realms that took part in - -Neuman, Ts'o, Kohl Expires: 18 May 1999 - - -INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 - - - authenticating the user to whom this ticket was issued. It does not - specify the order in which the realms were transited. See section - 3.3.3.2 for details on how this field encodes the traversed realms. - When the names of CA's are to be embedded inthe transited field (as - specified for some extentions to the protocol), the X.500 names of the - CA's should be mapped into items in the transited field using the - mapping defined by RFC2253. -authtime - This field indicates the time of initial authentication for the named - principal. It is the time of issue for the original ticket on which - this ticket is based. It is included in the ticket to provide - additional information to the end service, and to provide the - necessary information for implementation of a `hot list' service at - the KDC. An end service that is particularly paranoid could refuse to - accept tickets for which the initial authentication occurred "too far" - in the past. This field is also returned as part of the response from - the KDC. When returned as part of the response to initial - authentication (KRB_AS_REP), this is the current time on the Ker- - beros server[24]. -starttime - This field in the ticket specifies the time after which the ticket is - valid. Together with endtime, this field specifies the life of the - ticket. If it is absent from the ticket, its value should be treated - as that of the authtime field. -endtime - This field contains the time after which the ticket will not be - honored (its expiration time). Note that individual services may place - their own limits on the life of a ticket and may reject tickets which - have not yet expired. As such, this is really an upper bound on the - expiration time for the ticket. -renew-till - This field is only present in tickets that have the RENEWABLE flag set - in the flags field. It indicates the maximum endtime that may be - included in a renewal. It can be thought of as the absolute expiration - time for the ticket, including all renewals. -caddr - This field in a ticket contains zero (if omitted) or more (if present) - host addresses. These are the addresses from which the ticket can be - used. If there are no addresses, the ticket can be used from any - location. The decision by the KDC to issue or by the end server to - accept zero-address tickets is a policy decision and is left to the - Kerberos and end-service administrators; they may refuse to issue or - accept such tickets. The suggested and default policy, however, is - that such tickets will only be issued or accepted when additional - information that can be used to restrict the use of the ticket is - included in the authorization_data field. Such a ticket is a - capability. - - Network addresses are included in the ticket to make it harder for an - attacker to use stolen credentials. Because the session key is not - sent over the network in cleartext, credentials can't be stolen simply - by listening to the network; an attacker has to gain access to the - session key (perhaps through operating system security breaches or a - careless user's unattended session) to make use of stolen tickets. - - It is important to note that the network address from which a - connection is received cannot be reliably determined. Even if it could - be, an attacker who has compromised the client's worksta- tion could - use the credentials from there. Including the network addresses only - -Neuman, Ts'o, Kohl Expires: 18 May 1999 - - -INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 - - - makes it more difficult, not impossible, for an attacker to walk off - with stolen credentials and then use them from a "safe" location. -authorization-data - The authorization-data field is used to pass authorization data from - the principal on whose behalf a ticket was issued to the application - service. If no authorization data is included, this field will be left - out. Experience has shown that the name of this field is confusing, - and that a better name for this field would be restrictions. - Unfortunately, it is not possible to change the name of this field at - this time. - - This field contains restrictions on any authority obtained on the - basis of authentication using the ticket. It is possible for any - principal in posession of credentials to add entries to the - authorization data field since these entries further restrict what can - be done with the ticket. Such additions can be made by specifying the - additional entries when a new ticket is obtained during the TGS - exchange, or they may be added during chained delegation using the - authorization data field of the authenticator. - - Because entries may be added to this field by the holder of - credentials, it is not allowable for the presence of an entry in the - authorization data field of a ticket to amplify the priveleges one - would obtain from using a ticket. - - The data in this field may be specific to the end service; the field - will contain the names of service specific objects, and the rights to - those objects. The format for this field is described in section 5.2. - Although Kerberos is not concerned with the format of the contents of - the sub-fields, it does carry type information (ad-type). - - By using the authorization_data field, a principal is able to issue a - proxy that is valid for a specific purpose. For example, a client - wishing to print a file can obtain a file server proxy to be passed to - the print server. By specifying the name of the file in the - authorization_data field, the file server knows that the print server - can only use the client's rights when accessing the particular file to - be printed. - - A separate service providing authorization or certifying group - membership may be built using the authorization-data field. In this - case, the entity granting authorization (not the authorized entity), - obtains a ticket in its own name (e.g. the ticket is issued in the - name of a privelege server), and this entity adds restrictions on its - own authority and delegates the restricted authority through a proxy - to the client. The client would then present this authorization - credential to the application server separately from the - authentication exchange. - - Similarly, if one specifies the authorization-data field of a proxy - and leaves the host addresses blank, the resulting ticket and session - key can be treated as a capability. See [Neu93] for some suggested - uses of this field. - - The authorization-data field is optional and does not have to be - included in a ticket. - -5.3.2. Authenticators - - -Neuman, Ts'o, Kohl Expires: 18 May 1999 - - -INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 - - -An authenticator is a record sent with a ticket to a server to certify the -client's knowledge of the encryption key in the ticket, to help the server -detect replays, and to help choose a "true session key" to use with the -particular session. The encoding is encrypted in the ticket's session key -shared by the client and the server: - --- Unencrypted authenticator -Authenticator ::= [APPLICATION 2] SEQUENCE { - authenticator-vno[0] INTEGER, - crealm[1] Realm, - cname[2] PrincipalName, - cksum[3] Checksum OPTIONAL, - cusec[4] INTEGER, - ctime[5] KerberosTime, - subkey[6] EncryptionKey OPTIONAL, - seq-number[7] INTEGER OPTIONAL, - authorization-data[8] AuthorizationData OPTIONAL -} - - -authenticator-vno - This field specifies the version number for the format of the - authenticator. This document specifies version 5. -crealm and cname - These fields are the same as those described for the ticket in section - 5.3.1. -cksum - This field contains a checksum of the the applica- tion data that - accompanies the KRB_AP_REQ. -cusec - This field contains the microsecond part of the client's timestamp. - Its value (before encryption) ranges from 0 to 999999. It often - appears along with ctime. The two fields are used together to specify - a reasonably accurate timestamp. -ctime - This field contains the current time on the client's host. -subkey - This field contains the client's choice for an encryption key which is - to be used to protect this specific application session. Unless an - application specifies otherwise, if this field is left out the session - key from the ticket will be used. -seq-number - This optional field includes the initial sequence number to be used by - the KRB_PRIV or KRB_SAFE messages when sequence numbers are used to - detect replays (It may also be used by application specific messages). - When included in the authenticator this field specifies the initial - sequence number for messages from the client to the server. When - included in the AP-REP message, the initial sequence number is that - for messages from the server to the client. When used in KRB_PRIV or - KRB_SAFE messages, it is incremented by one after each message is - sent. Sequence numbers fall in the range of 0 through 2^32 - 1 and - wrap to zero following the value 2^32 - 1. - - For sequence numbers to adequately support the detection of replays - they should be non-repeating, even across connection boundaries. The - initial sequence number should be random and uniformly distributed - across the full space of possible sequence numbers, so that it cannot - be guessed by an attacker and so that it and the successive sequence - numbers do not repeat other sequences. - -Neuman, Ts'o, Kohl Expires: 18 May 1999 - - -INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 - - -authorization-data - This field is the same as described for the ticket in section 5.3.1. - It is optional and will only appear when additional restrictions are - to be placed on the use of a ticket, beyond those carried in the - ticket itself. - -5.4. Specifications for the AS and TGS exchanges - -This section specifies the format of the messages used in the exchange -between the client and the Kerberos server. The format of possible error -messages appears in section 5.9.1. - -5.4.1. KRB_KDC_REQ definition - -The KRB_KDC_REQ message has no type of its own. Instead, its type is one of -KRB_AS_REQ or KRB_TGS_REQ depending on whether the request is for an -initial ticket or an additional ticket. In either case, the message is sent -from the client to the Authentication Server to request credentials for a -service. - -The message fields are: - -AS-REQ ::= [APPLICATION 10] KDC-REQ -TGS-REQ ::= [APPLICATION 12] KDC-REQ - -KDC-REQ ::= SEQUENCE { - pvno[1] INTEGER, - msg-type[2] INTEGER, - padata[3] SEQUENCE OF PA-DATA OPTIONAL, - req-body[4] KDC-REQ-BODY -} - -PA-DATA ::= SEQUENCE { - padata-type[1] INTEGER, - padata-value[2] OCTET STRING, - -- might be encoded AP-REQ -} - -KDC-REQ-BODY ::= SEQUENCE { - kdc-options[0] KDCOptions, - cname[1] PrincipalName OPTIONAL, - -- Used only in AS-REQ - realm[2] Realm, -- Server's realm - -- Also client's in AS-REQ - sname[3] PrincipalName OPTIONAL, - from[4] KerberosTime OPTIONAL, - till[5] KerberosTime OPTIONAL, - rtime[6] KerberosTime OPTIONAL, - nonce[7] INTEGER, - etype[8] SEQUENCE OF INTEGER, - -- EncryptionType, - -- in preference order - addresses[9] HostAddresses OPTIONAL, - enc-authorization-data[10] EncryptedData OPTIONAL, - -- Encrypted AuthorizationData - -- encoding - additional-tickets[11] SEQUENCE OF Ticket OPTIONAL -} - - -Neuman, Ts'o, Kohl Expires: 18 May 1999 - - -INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 - - -The fields in this message are: - -pvno - This field is included in each message, and specifies the protocol - version number. This document specifies protocol version 5. -msg-type - This field indicates the type of a protocol message. It will almost - always be the same as the application identifier associated with a - message. It is included to make the identifier more readily accessible - to the application. For the KDC-REQ message, this type will be - KRB_AS_REQ or KRB_TGS_REQ. -padata - The padata (pre-authentication data) field contains a sequence of - authentication information which may be needed before credentials can - be issued or decrypted. In the case of requests for additional tickets - (KRB_TGS_REQ), this field will include an element with padata-type of - PA-TGS-REQ and data of an authentication header (ticket-granting - ticket and authenticator). The checksum in the authenticator (which - must be collision-proof) is to be computed over the KDC-REQ-BODY - encoding. In most requests for initial authentication (KRB_AS_REQ) and - most replies (KDC-REP), the padata field will be left out. - - This field may also contain information needed by certain extensions - to the Kerberos protocol. For example, it might be used to initially - verify the identity of a client before any response is returned. This - is accomplished with a padata field with padata-type equal to - PA-ENC-TIMESTAMP and padata-value defined as follows: - - padata-type ::= PA-ENC-TIMESTAMP - padata-value ::= EncryptedData -- PA-ENC-TS-ENC - - PA-ENC-TS-ENC ::= SEQUENCE { - patimestamp[0] KerberosTime, -- client's time - pausec[1] INTEGER OPTIONAL - } - - with patimestamp containing the client's time and pausec containing - the microseconds which may be omitted if a client will not generate - more than one request per second. The ciphertext (padata-value) - consists of the PA-ENC-TS-ENC sequence, encrypted using the client's - secret key. - - [use-specified-kvno item is here for discussion and may be removed] It - may also be used by the client to specify the version of a key that is - being used for accompanying preauthentication, and/or which should be - used to encrypt the reply from the KDC. - - PA-USE-SPECIFIED-KVNO ::= Integer - - The KDC should only accept and abide by the value of the - use-specified-kvno preauthentication data field when the specified key - is still valid and until use of a new key is confirmed. This situation - is likely to occur primarily during the period during which an updated - key is propagating to other KDC's in a realm. - - The padata field can also contain information needed to help the KDC - or the client select the key needed for generating or decrypting the - response. This form of the padata is useful for supporting the use of - certain token cards with Kerberos. The details of such extensions are - -Neuman, Ts'o, Kohl Expires: 18 May 1999 - - -INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 - - - specified in separate documents. See [Pat92] for additional uses of - this field. -padata-type - The padata-type element of the padata field indicates the way that the - padata-value element is to be interpreted. Negative values of - padata-type are reserved for unregistered use; non-negative values are - used for a registered interpretation of the element type. -req-body - This field is a placeholder delimiting the extent of the remaining - fields. If a checksum is to be calculated over the request, it is - calculated over an encoding of the KDC-REQ-BODY sequence which is - enclosed within the req-body field. -kdc-options - This field appears in the KRB_AS_REQ and KRB_TGS_REQ requests to the - KDC and indicates the flags that the client wants set on the tickets - as well as other information that is to modify the behavior of the - KDC. Where appropriate, the name of an option may be the same as the - flag that is set by that option. Although in most case, the bit in the - options field will be the same as that in the flags field, this is not - guaranteed, so it is not acceptable to simply copy the options field - to the flags field. There are various checks that must be made before - honoring an option anyway. - - The kdc_options field is a bit-field, where the selected options are - indicated by the bit being set (1), and the unselected options and - reserved fields being reset (0). The encoding of the bits is specified - in section 5.2. The options are described in more detail above in - section 2. The meanings of the options are: - - Bit(s) Name Description - 0 RESERVED - Reserved for future expansion of -this - field. - - 1 FORWARDABLE - The FORWARDABLE option indicates -that - the ticket to be issued is to have -its - forwardable flag set. It may only -be - set on the initial request, or in a -sub- - sequent request if the -ticket-granting - ticket on which it is based is also -for- - wardable. - - 2 FORWARDED - The FORWARDED option is only -specified - in a request to the -ticket-granting - server and will only be honored if -the - ticket-granting ticket in the -request - has its FORWARDABLE bit set. -This - option indicates that this is a -request - for forwarding. The address(es) of -the - host from which the resulting ticket -is - to be valid are included in -the - addresses field of the request. - - 3 PROXIABLE - The PROXIABLE option indicates that -the - ticket to be issued is to have its -prox- - iable flag set. It may only be set -on - -Neuman, Ts'o, Kohl Expires: 18 May 1999 - - -INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 - - - the initial request, or in a -subsequent - request if the ticket-granting ticket -on - which it is based is also proxiable. - - 4 PROXY - The PROXY option indicates that this -is - a request for a proxy. This option -will - only be honored if the -ticket-granting - ticket in the request has its -PROXIABLE - bit set. The address(es) of the -host - from which the resulting ticket is to -be - valid are included in the -addresses - field of the request. - - 5 ALLOW-POSTDATE - The ALLOW-POSTDATE option indicates -that - the ticket to be issued is to have -its - MAY-POSTDATE flag set. It may only -be - set on the initial request, or in a -sub- - sequent request if the -ticket-granting - ticket on which it is based also has -its - MAY-POSTDATE flag set. - - 6 POSTDATED - The POSTDATED option indicates that -this - is a request for a postdated -ticket. - This option will only be honored if -the - ticket-granting ticket on which - it is based has its MAY-POSTDATE - flag set. - The resulting ticket will also have -its - INVALID flag set, and that flag may -be - reset by a subsequent request to the -KDC - after the starttime in the ticket -has - been reached. - - 7 UNUSED - This option is presently unused. - - 8 RENEWABLE - The RENEWABLE option indicates that -the - ticket to be issued is to have -its - RENEWABLE flag set. It may only be -set - on the initial request, or when -the - ticket-granting ticket on which -the - request is based is also renewable. -If - this option is requested, then the -rtime - field in the request contains -the - desired absolute expiration time for -the - ticket. - - 9-13 UNUSED - These options are presently unused. - - 14 REQUEST-ANONYMOUS - The REQUEST-ANONYMOUS option -indicates - that the ticket to be issued is not -to - identify the user to which it -was - issued. Instead, the principal -identif- - -Neuman, Ts'o, Kohl Expires: 18 May 1999 - - -INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 - - - ier is to be generic, as specified -by - the policy of the realm (e.g. -usually - anonymous@realm). The purpose of -the - ticket is only to securely distribute -a - session key, and not to identify -the - user. The ANONYMOUS flag on the -ticket - to be returned should be set. If -the - local realms policy does not -permit - anonymous credentials, the request is -to - be rejected. - - 15-25 RESERVED - Reserved for future use. - - 26 DISABLE-TRANSITED-CHECK - By default the KDC will check the - transited field of a ticket-granting- - ticket against the policy of the local - realm before it will issue derivative - tickets based on the ticket granting - ticket. If this flag is set in the - request, checking of the transited -field - is disabled. Tickets issued without -the - performance of this check will be -noted - by the reset (0) value of the - TRANSITED-POLICY-CHECKED flag, - indicating to the application server - that the tranisted field must be -checked - locally. KDC's are encouraged but not - required to honor the - DISABLE-TRANSITED-CHECK option. - - 27 RENEWABLE-OK - The RENEWABLE-OK option indicates that -a - renewable ticket will be acceptable if -a - ticket with the requested life -cannot - otherwise be provided. If a ticket -with - the requested life cannot be -provided, - then a renewable ticket may be -issued - with a renew-till equal to the -the - requested endtime. The value of -the - renew-till field may still be limited -by - local limits, or limits selected by -the - individual principal or server. - - 28 ENC-TKT-IN-SKEY - This option is used only by the -ticket- - granting service. The -ENC-TKT-IN-SKEY - option indicates that the ticket for -the - end server is to be encrypted in -the - session key from the additional -ticket- - granting ticket provided. - - 29 RESERVED - Reserved for future use. - - 30 RENEW - This option is used only by the -ticket- - granting service. The RENEW -option - -Neuman, Ts'o, Kohl Expires: 18 May 1999 - - -INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 - - - indicates that the present request -is - for a renewal. The ticket provided -is - encrypted in the secret key for -the - server on which it is valid. -This - option will only be honored if -the - ticket to be renewed has its -RENEWABLE - flag set and if the time in its -renew- - till field has not passed. The -ticket - to be renewed is passed in the -padata - field as part of the -authentication - header. - - 31 VALIDATE - This option is used only by the -ticket- - granting service. The VALIDATE -option - indicates that the request is to -vali- - date a postdated ticket. It will -only - be honored if the ticket presented -is - postdated, presently has its -INVALID - flag set, and would be otherwise -usable - at this time. A ticket cannot be -vali- - dated before its starttime. The -ticket - presented for validation is encrypted -in - the key of the server for which it -is - valid and is passed in the padata -field - as part of the authentication header. - -cname and sname - These fields are the same as those described for the ticket in section - 5.3.1. sname may only be absent when the ENC-TKT-IN-SKEY option is - specified. If absent, the name of the server is taken from the name of - the client in the ticket passed as additional-tickets. -enc-authorization-data - The enc-authorization-data, if present (and it can only be present in - the TGS_REQ form), is an encoding of the desired authorization-data - encrypted under the sub-session key if present in the Authenticator, - or alternatively from the session key in the ticket-granting ticket, - both from the padata field in the KRB_AP_REQ. -realm - This field specifies the realm part of the server's principal - identifier. In the AS exchange, this is also the realm part of the - client's principal identifier. -from - This field is included in the KRB_AS_REQ and KRB_TGS_REQ ticket - requests when the requested ticket is to be postdated. It specifies - the desired start time for the requested ticket. If this field is - omitted then the KDC should use the current time instead. -till - This field contains the expiration date requested by the client in a - ticket request. It is optional and if omitted the requested ticket is - to have the maximum endtime permitted according to KDC policy for the - parties to the authentication exchange as limited by expiration date - of the ticket granting ticket or other preauthentication credentials. -rtime - This field is the requested renew-till time sent from a client to the - KDC in a ticket request. It is optional. -nonce - This field is part of the KDC request and response. It it intended to - hold a random number generated by the client. If the same number is - -Neuman, Ts'o, Kohl Expires: 18 May 1999 - - -INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 - - - included in the encrypted response from the KDC, it provides evidence - that the response is fresh and has not been replayed by an attacker. - Nonces must never be re-used. Ideally, it should be generated - randomly, but if the correct time is known, it may suffice[25]. -etype - This field specifies the desired encryption algorithm to be used in - the response. -addresses - This field is included in the initial request for tickets, and - optionally included in requests for additional tickets from the - ticket-granting server. It specifies the addresses from which the - requested ticket is to be valid. Normally it includes the addresses - for the client's host. If a proxy is requested, this field will - contain other addresses. The contents of this field are usually copied - by the KDC into the caddr field of the resulting ticket. -additional-tickets - Additional tickets may be optionally included in a request to the - ticket-granting server. If the ENC-TKT-IN-SKEY option has been - specified, then the session key from the additional ticket will be - used in place of the server's key to encrypt the new ticket. If more - than one option which requires additional tickets has been specified, - then the additional tickets are used in the order specified by the - ordering of the options bits (see kdc-options, above). - -The application code will be either ten (10) or twelve (12) depending on -whether the request is for an initial ticket (AS-REQ) or for an additional -ticket (TGS-REQ). - -The optional fields (addresses, authorization-data and additional-tickets) -are only included if necessary to perform the operation specified in the -kdc-options field. - -It should be noted that in KRB_TGS_REQ, the protocol version number appears -twice and two different message types appear: the KRB_TGS_REQ message -contains these fields as does the authentication header (KRB_AP_REQ) that -is passed in the padata field. - -5.4.2. KRB_KDC_REP definition - -The KRB_KDC_REP message format is used for the reply from the KDC for -either an initial (AS) request or a subsequent (TGS) request. There is no -message type for KRB_KDC_REP. Instead, the type will be either KRB_AS_REP -or KRB_TGS_REP. The key used to encrypt the ciphertext part of the reply -depends on the message type. For KRB_AS_REP, the ciphertext is encrypted in -the client's secret key, and the client's key version number is included in -the key version number for the encrypted data. For KRB_TGS_REP, the -ciphertext is encrypted in the sub-session key from the Authenticator, or -if absent, the session key from the ticket-granting ticket used in the -request. In that case, no version number will be present in the -EncryptedData sequence. - -The KRB_KDC_REP message contains the following fields: - -AS-REP ::= [APPLICATION 11] KDC-REP -TGS-REP ::= [APPLICATION 13] KDC-REP - -KDC-REP ::= SEQUENCE { - pvno[0] INTEGER, - msg-type[1] INTEGER, - -Neuman, Ts'o, Kohl Expires: 18 May 1999 - - -INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 - - - padata[2] SEQUENCE OF PA-DATA OPTIONAL, - crealm[3] Realm, - cname[4] PrincipalName, - ticket[5] Ticket, - enc-part[6] EncryptedData -} - -EncASRepPart ::= [APPLICATION 25[27]] EncKDCRepPart -EncTGSRepPart ::= [APPLICATION 26] EncKDCRepPart - -EncKDCRepPart ::= SEQUENCE { - key[0] EncryptionKey, - last-req[1] LastReq, - nonce[2] INTEGER, - key-expiration[3] KerberosTime OPTIONAL, - flags[4] TicketFlags, - authtime[5] KerberosTime, - starttime[6] KerberosTime OPTIONAL, - endtime[7] KerberosTime, - renew-till[8] KerberosTime OPTIONAL, - srealm[9] Realm, - sname[10] PrincipalName, - caddr[11] HostAddresses OPTIONAL -} - -pvno and msg-type - These fields are described above in section 5.4.1. msg-type is either - KRB_AS_REP or KRB_TGS_REP. -padata - This field is described in detail in section 5.4.1. One possible use - for this field is to encode an alternate "mix-in" string to be used - with a string-to-key algorithm (such as is described in section - 6.3.2). This ability is useful to ease transitions if a realm name - needs to change (e.g. when a company is acquired); in such a case all - existing password-derived entries in the KDC database would be flagged - as needing a special mix-in string until the next password change. -crealm, cname, srealm and sname - These fields are the same as those described for the ticket in section - 5.3.1. -ticket - The newly-issued ticket, from section 5.3.1. -enc-part - This field is a place holder for the ciphertext and related - information that forms the encrypted part of a message. The - description of the encrypted part of the message follows each - appearance of this field. The encrypted part is encoded as described - in section 6.1. -key - This field is the same as described for the ticket in section 5.3.1. -last-req - This field is returned by the KDC and specifies the time(s) of the - last request by a principal. Depending on what information is - available, this might be the last time that a request for a - ticket-granting ticket was made, or the last time that a request based - on a ticket-granting ticket was successful. It also might cover all - servers for a realm, or just the particular server. Some - implementations may display this information to the user to aid in - discovering unauthorized use of one's identity. It is similar in - spirit to the last login time displayed when logging into timesharing - -Neuman, Ts'o, Kohl Expires: 18 May 1999 - - -INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 - - - systems. -nonce - This field is described above in section 5.4.1. -key-expiration - The key-expiration field is part of the response from the KDC and - specifies the time that the client's secret key is due to expire. The - expiration might be the result of password aging or an account - expiration. This field will usually be left out of the TGS reply since - the response to the TGS request is encrypted in a session key and no - client information need be retrieved from the KDC database. It is up - to the application client (usually the login program) to take - appropriate action (such as notifying the user) if the expiration time - is imminent. -flags, authtime, starttime, endtime, renew-till and caddr - These fields are duplicates of those found in the encrypted portion of - the attached ticket (see section 5.3.1), provided so the client may - verify they match the intended request and to assist in proper ticket - caching. If the message is of type KRB_TGS_REP, the caddr field will - only be filled in if the request was for a proxy or forwarded ticket, - or if the user is substituting a subset of the addresses from the - ticket granting ticket. If the client-requested addresses are not - present or not used, then the addresses contained in the ticket will - be the same as those included in the ticket-granting ticket. - -5.5. Client/Server (CS) message specifications - -This section specifies the format of the messages used for the -authentication of the client to the application server. - -5.5.1. KRB_AP_REQ definition - -The KRB_AP_REQ message contains the Kerberos protocol version number, the -message type KRB_AP_REQ, an options field to indicate any options in use, -and the ticket and authenticator themselves. The KRB_AP_REQ message is -often referred to as the 'authentication header'. - -AP-REQ ::= [APPLICATION 14] SEQUENCE { - pvno[0] INTEGER, - msg-type[1] INTEGER, - ap-options[2] APOptions, - ticket[3] Ticket, - authenticator[4] EncryptedData -} - -APOptions ::= BIT STRING { - reserved(0), - use-session-key(1), - mutual-required(2) -} - - - -pvno and msg-type - These fields are described above in section 5.4.1. msg-type is - KRB_AP_REQ. -ap-options - This field appears in the application request (KRB_AP_REQ) and affects - the way the request is processed. It is a bit-field, where the - selected options are indicated by the bit being set (1), and the - -Neuman, Ts'o, Kohl Expires: 18 May 1999 - - -INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 - - - unselected options and reserved fields being reset (0). The encoding - of the bits is specified in section 5.2. The meanings of the options - are: - - Bit(s) Name Description - - 0 RESERVED - Reserved for future expansion of -this - field. - - 1 USE-SESSION-KEY - The USE-SESSION-KEY option -indicates - that the ticket the client is -presenting - to a server is encrypted in the -session - key from the server's -ticket-granting - ticket. When this option is not -speci- - fied, the ticket is encrypted in -the - server's secret key. - - 2 MUTUAL-REQUIRED - The MUTUAL-REQUIRED option tells -the - server that the client requires -mutual - authentication, and that it must -respond - with a KRB_AP_REP message. - - 3-31 RESERVED - Reserved for future use. - -ticket - This field is a ticket authenticating the client to the server. -authenticator - This contains the authenticator, which includes the client's choice of - a subkey. Its encoding is described in section 5.3.2. - -5.5.2. KRB_AP_REP definition - -The KRB_AP_REP message contains the Kerberos protocol version number, the -message type, and an encrypted time- stamp. The message is sent in in -response to an application request (KRB_AP_REQ) where the mutual -authentication option has been selected in the ap-options field. - -AP-REP ::= [APPLICATION 15] SEQUENCE { - pvno[0] INTEGER, - msg-type[1] INTEGER, - enc-part[2] EncryptedData -} - -EncAPRepPart ::= [APPLICATION 27[29]] SEQUENCE { - ctime[0] KerberosTime, - cusec[1] INTEGER, - subkey[2] EncryptionKey OPTIONAL, - seq-number[3] INTEGER OPTIONAL -} - -The encoded EncAPRepPart is encrypted in the shared session key of the -ticket. The optional subkey field can be used in an application-arranged -negotiation to choose a per association session key. - -pvno and msg-type - -Neuman, Ts'o, Kohl Expires: 18 May 1999 - - -INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 - - - These fields are described above in section 5.4.1. msg-type is - KRB_AP_REP. -enc-part - This field is described above in section 5.4.2. -ctime - This field contains the current time on the client's host. -cusec - This field contains the microsecond part of the client's timestamp. -subkey - This field contains an encryption key which is to be used to protect - this specific application session. See section 3.2.6 for specifics on - how this field is used to negotiate a key. Unless an application - specifies otherwise, if this field is left out, the sub-session key - from the authenticator, or if also left out, the session key from the - ticket will be used. - -5.5.3. Error message reply - -If an error occurs while processing the application request, the KRB_ERROR -message will be sent in response. See section 5.9.1 for the format of the -error message. The cname and crealm fields may be left out if the server -cannot determine their appropriate values from the corresponding KRB_AP_REQ -message. If the authenticator was decipherable, the ctime and cusec fields -will contain the values from it. - -5.6. KRB_SAFE message specification - -This section specifies the format of a message that can be used by either -side (client or server) of an application to send a tamper-proof message to -its peer. It presumes that a session key has previously been exchanged (for -example, by using the KRB_AP_REQ/KRB_AP_REP messages). - -5.6.1. KRB_SAFE definition - -The KRB_SAFE message contains user data along with a collision-proof -checksum keyed with the last encryption key negotiated via subkeys, or the -session key if no negotiation has occured. The message fields are: - -KRB-SAFE ::= [APPLICATION 20] SEQUENCE { - pvno[0] INTEGER, - msg-type[1] INTEGER, - safe-body[2] KRB-SAFE-BODY, - cksum[3] Checksum -} - -KRB-SAFE-BODY ::= SEQUENCE { - user-data[0] OCTET STRING, - timestamp[1] KerberosTime OPTIONAL, - usec[2] INTEGER OPTIONAL, - seq-number[3] INTEGER OPTIONAL, - s-address[4] HostAddress OPTIONAL, - r-address[5] HostAddress OPTIONAL -} - -pvno and msg-type - These fields are described above in section 5.4.1. msg-type is - KRB_SAFE. -safe-body - This field is a placeholder for the body of the KRB-SAFE message. - -Neuman, Ts'o, Kohl Expires: 18 May 1999 - - -INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 - - -cksum - This field contains the checksum of the application data. Checksum - details are described in section 6.4. The checksum is computed over - the encoding of the KRB-SAFE sequence. First, the cksum is zeroed and - the checksum is computed over the encoding of the KRB-SAFE sequence, - then the checksum is set to the result of that computation, and - finally the KRB-SAFE sequence is encoded again. -user-data - This field is part of the KRB_SAFE and KRB_PRIV messages and contain - the application specific data that is being passed from the sender to - the recipient. -timestamp - This field is part of the KRB_SAFE and KRB_PRIV messages. Its contents - are the current time as known by the sender of the message. By - checking the timestamp, the recipient of the message is able to make - sure that it was recently generated, and is not a replay. -usec - This field is part of the KRB_SAFE and KRB_PRIV headers. It contains - the microsecond part of the timestamp. -seq-number - This field is described above in section 5.3.2. -s-address - This field specifies the address in use by the sender of the message. -r-address - This field specifies the address in use by the recipient of the - message. It may be omitted for some uses (such as broadcast - protocols), but the recipient may arbitrarily reject such messages. - This field along with s-address can be used to help detect messages - which have been incorrectly or maliciously delivered to the wrong - recipient. - -5.7. KRB_PRIV message specification - -This section specifies the format of a message that can be used by either -side (client or server) of an application to securely and privately send a -message to its peer. It presumes that a session key has previously been -exchanged (for example, by using the KRB_AP_REQ/KRB_AP_REP messages). - -5.7.1. KRB_PRIV definition - -The KRB_PRIV message contains user data encrypted in the Session Key. The -message fields are: - -KRB-PRIV ::= [APPLICATION 21] SEQUENCE { - pvno[0] INTEGER, - msg-type[1] INTEGER, - enc-part[3] EncryptedData -} - -EncKrbPrivPart ::= [APPLICATION 28[31]] SEQUENCE { - user-data[0] OCTET STRING, - timestamp[1] KerberosTime OPTIONAL, - usec[2] INTEGER OPTIONAL, - seq-number[3] INTEGER OPTIONAL, - s-address[4] HostAddress OPTIONAL, -- sender's -addr - r-address[5] HostAddress OPTIONAL -- recip's -addr -} - -pvno and msg-type - -Neuman, Ts'o, Kohl Expires: 18 May 1999 - - -INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 - - - These fields are described above in section 5.4.1. msg-type is - KRB_PRIV. -enc-part - This field holds an encoding of the EncKrbPrivPart sequence encrypted - under the session key[32]. This encrypted encoding is used for the - enc-part field of the KRB-PRIV message. See section 6 for the format - of the ciphertext. -user-data, timestamp, usec, s-address and r-address - These fields are described above in section 5.6.1. -seq-number - This field is described above in section 5.3.2. - -5.8. KRB_CRED message specification - -This section specifies the format of a message that can be used to send -Kerberos credentials from one principal to another. It is presented here to -encourage a common mechanism to be used by applications when forwarding -tickets or providing proxies to subordinate servers. It presumes that a -session key has already been exchanged perhaps by using the -KRB_AP_REQ/KRB_AP_REP messages. - -5.8.1. KRB_CRED definition - -The KRB_CRED message contains a sequence of tickets to be sent and -information needed to use the tickets, including the session key from each. -The information needed to use the tickets is encrypted under an encryption -key previously exchanged or transferred alongside the KRB_CRED message. The -message fields are: - -KRB-CRED ::= [APPLICATION 22] SEQUENCE { - pvno[0] INTEGER, - msg-type[1] INTEGER, -- KRB_CRED - tickets[2] SEQUENCE OF Ticket, - enc-part[3] EncryptedData -} - -EncKrbCredPart ::= [APPLICATION 29] SEQUENCE { - ticket-info[0] SEQUENCE OF KrbCredInfo, - nonce[1] INTEGER OPTIONAL, - timestamp[2] KerberosTime OPTIONAL, - usec[3] INTEGER OPTIONAL, - s-address[4] HostAddress OPTIONAL, - r-address[5] HostAddress OPTIONAL -} - -KrbCredInfo ::= SEQUENCE { - key[0] EncryptionKey, - prealm[1] Realm OPTIONAL, - pname[2] PrincipalName OPTIONAL, - flags[3] TicketFlags OPTIONAL, - authtime[4] KerberosTime OPTIONAL, - starttime[5] KerberosTime OPTIONAL, - endtime[6] KerberosTime OPTIONAL - renew-till[7] KerberosTime OPTIONAL, - srealm[8] Realm OPTIONAL, - sname[9] PrincipalName OPTIONAL, - caddr[10] HostAddresses OPTIONAL -} - - -Neuman, Ts'o, Kohl Expires: 18 May 1999 - - -INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 - - -pvno and msg-type - These fields are described above in section 5.4.1. msg-type is - KRB_CRED. -tickets - These are the tickets obtained from the KDC specifically for use by - the intended recipient. Successive tickets are paired with the - corresponding KrbCredInfo sequence from the enc-part of the KRB-CRED - message. -enc-part - This field holds an encoding of the EncKrbCredPart sequence encrypted - under the session key shared between the sender and the intended - recipient. This encrypted encoding is used for the enc-part field of - the KRB-CRED message. See section 6 for the format of the ciphertext. -nonce - If practical, an application may require the inclusion of a nonce - generated by the recipient of the message. If the same value is - included as the nonce in the message, it provides evidence that the - message is fresh and has not been replayed by an attacker. A nonce - must never be re-used; it should be generated randomly by the - recipient of the message and provided to the sender of the message in - an application specific manner. -timestamp and usec - These fields specify the time that the KRB-CRED message was generated. - The time is used to provide assurance that the message is fresh. -s-address and r-address - These fields are described above in section 5.6.1. They are used - optionally to provide additional assurance of the integrity of the - KRB-CRED message. -key - This field exists in the corresponding ticket passed by the KRB-CRED - message and is used to pass the session key from the sender to the - intended recipient. The field's encoding is described in section 6.2. - -The following fields are optional. If present, they can be associated with -the credentials in the remote ticket file. If left out, then it is assumed -that the recipient of the credentials already knows their value. - -prealm and pname - The name and realm of the delegated principal identity. -flags, authtime, starttime, endtime, renew-till, srealm, sname, and caddr - These fields contain the values of the correspond- ing fields from the - ticket found in the ticket field. Descriptions of the fields are - identical to the descriptions in the KDC-REP message. - -5.9. Error message specification - -This section specifies the format for the KRB_ERROR message. The fields -included in the message are intended to return as much information as -possible about an error. It is not expected that all the information -required by the fields will be available for all types of errors. If the -appropriate information is not available when the message is composed, the -corresponding field will be left out of the message. - -Note that since the KRB_ERROR message is not protected by any encryption, -it is quite possible for an intruder to synthesize or modify such a -message. In particular, this means that the client should not use any -fields in this message for security-critical purposes, such as setting a -system clock or generating a fresh authenticator. The message can be -useful, however, for advising a user on the reason for some failure. - -Neuman, Ts'o, Kohl Expires: 18 May 1999 - - -INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 - - - -5.9.1. KRB_ERROR definition - -The KRB_ERROR message consists of the following fields: - -KRB-ERROR ::= [APPLICATION 30] SEQUENCE { - pvno[0] INTEGER, - msg-type[1] INTEGER, - ctime[2] KerberosTime OPTIONAL, - cusec[3] INTEGER OPTIONAL, - stime[4] KerberosTime, - susec[5] INTEGER, - error-code[6] INTEGER, - crealm[7] Realm OPTIONAL, - cname[8] PrincipalName OPTIONAL, - realm[9] Realm, -- Correct realm - sname[10] PrincipalName, -- Correct name - e-text[11] GeneralString OPTIONAL, - e-data[12] OCTET STRING OPTIONAL, - e-cksum[13] Checksum OPTIONAL, - e-typed-data[14] SEQUENCE of ETypedData -OPTIONAL -} - -ETypedData ::= SEQUENCE { - e-data-type [1] INTEGER, - e-data-value [2] OCTET STRING, -} - - - -pvno and msg-type - These fields are described above in section 5.4.1. msg-type is - KRB_ERROR. -ctime - This field is described above in section 5.4.1. -cusec - This field is described above in section 5.5.2. -stime - This field contains the current time on the server. It is of type - KerberosTime. -susec - This field contains the microsecond part of the server's timestamp. - Its value ranges from 0 to 999999. It appears along with stime. The - two fields are used in conjunction to specify a reasonably accurate - timestamp. -error-code - This field contains the error code returned by Kerberos or the server - when a request fails. To interpret the value of this field see the - list of error codes in section 8. Implementations are encouraged to - provide for national language support in the display of error - messages. -crealm, cname, srealm and sname - These fields are described above in section 5.3.1. -e-text - This field contains additional text to help explain the error code - associated with the failed request (for example, it might include a - principal name which was unknown). -e-data - This field contains additional data about the error for use by the - -Neuman, Ts'o, Kohl Expires: 18 May 1999 - - -INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 - - - application to help it recover from or handle the error. If the - errorcode is KDC_ERR_PREAUTH_REQUIRED, then the e-data field will - contain an encoding of a sequence of padata fields, each corresponding - to an acceptable pre-authentication method and optionally containing - data for the method: - - METHOD-DATA ::= SEQUENCE of PA-DATA - - If the error-code is KRB_AP_ERR_METHOD, then the e-data field will - contain an encoding of the following sequence: - - METHOD-DATA ::= SEQUENCE { - method-type[0] INTEGER, - method-data[1] OCTET STRING OPTIONAL - } - - method-type will indicate the required alternate method; method-data - will contain any required additional information. -e-cksum - This field contains an optional checksum for the KRB-ERROR message. - The checksum is calculated over the Kerberos ASN.1 encoding of the - KRB-ERROR message with the checksum absent. The checksum is then added - to the KRB-ERROR structure and the message is re-encoded. The Checksum - should be calculated using the session key from the ticket granting - ticket or service ticket, where available. If the error is in response - to a TGS or AP request, the checksum should be calculated uing the the - session key from the client's ticket. If the error is in response to - an AS request, then the checksum should be calulated using the - client's secret key ONLY if there has been suitable preauthentication - to prove knowledge of the secret key by the client[33]. If a checksum - can not be computed because the key to be used is not available, no - checksum will be included. -e-typed-data - [This field for discussion, may be deleted from final spec] This field - contains optional data that may be used to help the client recover - from the indicated error. [This could contain the METHOD-DATA - specified since I don't think anyone actually uses it yet. It could - also contain the PA-DATA sequence for the preauth required error if we - had a clear way to transition to the use of this field from the use of - the untype e-data field.] For example, this field may specify the key - version of the key used to verify preauthentication: - - e-data-type := 20 -- Key version number - e-data-value := Integer -- Key version number used to verify -preauthentication - -6. Encryption and Checksum Specifications - -The Kerberos protocols described in this document are designed to use -stream encryption ciphers, which can be simulated using commonly available -block encryption ciphers, such as the Data Encryption Standard, [DES77] in -conjunction with block chaining and checksum methods [DESM80]. Encryption -is used to prove the identities of the network entities participating in -message exchanges. The Key Distribution Center for each realm is trusted by -all principals registered in that realm to store a secret key in -confidence. Proof of knowledge of this secret key is used to verify the -authenticity of a principal. - -The KDC uses the principal's secret key (in the AS exchange) or a shared -session key (in the TGS exchange) to encrypt responses to ticket requests; - -Neuman, Ts'o, Kohl Expires: 18 May 1999 - - -INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 - - -the ability to obtain the secret key or session key implies the knowledge -of the appropriate keys and the identity of the KDC. The ability of a -principal to decrypt the KDC response and present a Ticket and a properly -formed Authenticator (generated with the session key from the KDC response) -to a service verifies the identity of the principal; likewise the ability -of the service to extract the session key from the Ticket and prove its -knowledge thereof in a response verifies the identity of the service. - -The Kerberos protocols generally assume that the encryption used is secure -from cryptanalysis; however, in some cases, the order of fields in the -encrypted portions of messages are arranged to minimize the effects of -poorly chosen keys. It is still important to choose good keys. If keys are -derived from user-typed passwords, those passwords need to be well chosen -to make brute force attacks more difficult. Poorly chosen keys still make -easy targets for intruders. - -The following sections specify the encryption and checksum mechanisms -currently defined for Kerberos. The encodings, chaining, and padding -requirements for each are described. For encryption methods, it is often -desirable to place random information (often referred to as a confounder) -at the start of the message. The requirements for a confounder are -specified with each encryption mechanism. - -Some encryption systems use a block-chaining method to improve the the -security characteristics of the ciphertext. However, these chaining methods -often don't provide an integrity check upon decryption. Such systems (such -as DES in CBC mode) must be augmented with a checksum of the plain-text -which can be verified at decryption and used to detect any tampering or -damage. Such checksums should be good at detecting burst errors in the -input. If any damage is detected, the decryption routine is expected to -return an error indicating the failure of an integrity check. Each -encryption type is expected to provide and verify an appropriate checksum. -The specification of each encryption method sets out its checksum -requirements. - -Finally, where a key is to be derived from a user's password, an algorithm -for converting the password to a key of the appropriate type is included. -It is desirable for the string to key function to be one-way, and for the -mapping to be different in different realms. This is important because -users who are registered in more than one realm will often use the same -password in each, and it is desirable that an attacker compromising the -Kerberos server in one realm not obtain or derive the user's key in -another. - -For an discussion of the integrity characteristics of the candidate -encryption and checksum methods considered for Kerberos, the the reader is -referred to [SG92]. - -6.1. Encryption Specifications - -The following ASN.1 definition describes all encrypted messages. The -enc-part field which appears in the unencrypted part of messages in section -5 is a sequence consisting of an encryption type, an optional key version -number, and the ciphertext. - -EncryptedData ::= SEQUENCE { - etype[0] INTEGER, -- EncryptionType - kvno[1] INTEGER OPTIONAL, - cipher[2] OCTET STRING -- ciphertext - -Neuman, Ts'o, Kohl Expires: 18 May 1999 - - -INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 - - -} - - - -etype - This field identifies which encryption algorithm was used to encipher - the cipher. Detailed specifications for selected encryption types - appear later in this section. -kvno - This field contains the version number of the key under which data is - encrypted. It is only present in messages encrypted under long lasting - keys, such as principals' secret keys. -cipher - This field contains the enciphered text, encoded as an OCTET STRING. - -The cipher field is generated by applying the specified encryption -algorithm to data composed of the message and algorithm-specific inputs. -Encryption mechanisms defined for use with Kerberos must take sufficient -measures to guarantee the integrity of the plaintext, and we recommend they -also take measures to protect against precomputed dictionary attacks. If -the encryption algorithm is not itself capable of doing so, the protections -can often be enhanced by adding a checksum and a confounder. - -The suggested format for the data to be encrypted includes a confounder, a -checksum, the encoded plaintext, and any necessary padding. The msg-seq -field contains the part of the protocol message described in section 5 -which is to be encrypted. The confounder, checksum, and padding are all -untagged and untyped, and their length is exactly sufficient to hold the -appropriate item. The type and length is implicit and specified by the -particular encryption type being used (etype). The format for the data to -be encrypted is described in the following diagram: - - +-----------+----------+-------------+-----+ - |confounder | check | msg-seq | pad | - +-----------+----------+-------------+-----+ - -The format cannot be described in ASN.1, but for those who prefer an -ASN.1-like notation: - -CipherText ::= ENCRYPTED SEQUENCE { - confounder[0] UNTAGGED[35] OCTET STRING(conf_length) OPTIONAL, - check[1] UNTAGGED OCTET STRING(checksum_length) OPTIONAL, - msg-seq[2] MsgSequence, - pad UNTAGGED OCTET STRING(pad_length) OPTIONAL -} - -One generates a random confounder of the appropriate length, placing it in -confounder; zeroes out check; calculates the appropriate checksum over -confounder, check, and msg-seq, placing the result in check; adds the -necessary padding; then encrypts using the specified encryption type and -the appropriate key. - -Unless otherwise specified, a definition of an encryption algorithm that -specifies a checksum, a length for the confounder field, or an octet -boundary for padding uses this ciphertext format[36]. Those fields which -are not specified will be omitted. - -In the interest of allowing all implementations using a particular -encryption type to communicate with all others using that type, the - -Neuman, Ts'o, Kohl Expires: 18 May 1999 - - -INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 - - -specification of an encryption type defines any checksum that is needed as -part of the encryption process. If an alternative checksum is to be used, a -new encryption type must be defined. - -Some cryptosystems require additional information beyond the key and the -data to be encrypted. For example, DES, when used in cipher-block-chaining -mode, requires an initialization vector. If required, the description for -each encryption type must specify the source of such additional -information. 6.2. Encryption Keys - -The sequence below shows the encoding of an encryption key: - - EncryptionKey ::= SEQUENCE { - keytype[0] INTEGER, - keyvalue[1] OCTET STRING - } - -keytype - This field specifies the type of encryption key that follows in the - keyvalue field. It will almost always correspond to the encryption - algorithm used to generate the EncryptedData, though more than one - algorithm may use the same type of key (the mapping is many to one). - This might happen, for example, if the encryption algorithm uses an - alternate checksum algorithm for an integrity check, or a different - chaining mechanism. -keyvalue - This field contains the key itself, encoded as an octet string. - -All negative values for the encryption key type are reserved for local use. -All non-negative values are reserved for officially assigned type fields -and interpreta- tions. - -6.3. Encryption Systems - -6.3.1. The NULL Encryption System (null) - -If no encryption is in use, the encryption system is said to be the NULL -encryption system. In the NULL encryption system there is no checksum, -confounder or padding. The ciphertext is simply the plaintext. The NULL Key -is used by the null encryption system and is zero octets in length, with -keytype zero (0). - -6.3.2. DES in CBC mode with a CRC-32 checksum (des-cbc-crc) - -The des-cbc-crc encryption mode encrypts information under the Data -Encryption Standard [DES77] using the cipher block chaining mode [DESM80]. -A CRC-32 checksum (described in ISO 3309 [ISO3309]) is applied to the -confounder and message sequence (msg-seq) and placed in the cksum field. -DES blocks are 8 bytes. As a result, the data to be encrypted (the -concatenation of confounder, checksum, and message) must be padded to an 8 -byte boundary before encryption. The details of the encryption of this data -are identical to those for the des-cbc-md5 encryption mode. - -Note that, since the CRC-32 checksum is not collision-proof, an attacker -could use a probabilistic chosen-plaintext attack to generate a valid -message even if a confounder is used [SG92]. The use of collision-proof -checksums is recommended for environments where such attacks represent a -significant threat. The use of the CRC-32 as the checksum for ticket or -authenticator is no longer mandated as an interoperability requirement for - -Neuman, Ts'o, Kohl Expires: 18 May 1999 - - -INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 - - -Kerberos Version 5 Specification 1 (See section 9.1 for specific details). - -6.3.3. DES in CBC mode with an MD4 checksum (des-cbc-md4) - -The des-cbc-md4 encryption mode encrypts information under the Data -Encryption Standard [DES77] using the cipher block chaining mode [DESM80]. -An MD4 checksum (described in [MD492]) is applied to the confounder and -message sequence (msg-seq) and placed in the cksum field. DES blocks are 8 -bytes. As a result, the data to be encrypted (the concatenation of -confounder, checksum, and message) must be padded to an 8 byte boundary -before encryption. The details of the encryption of this data are identical -to those for the des-cbc-md5 encryption mode. - -6.3.4. DES in CBC mode with an MD5 checksum (des-cbc-md5) - -The des-cbc-md5 encryption mode encrypts information under the Data -Encryption Standard [DES77] using the cipher block chaining mode [DESM80]. -An MD5 checksum (described in [MD5-92].) is applied to the confounder and -message sequence (msg-seq) and placed in the cksum field. DES blocks are 8 -bytes. As a result, the data to be encrypted (the concatenation of -confounder, checksum, and message) must be padded to an 8 byte boundary -before encryption. - -Plaintext and DES ciphtertext are encoded as blocks of 8 octets which are -concatenated to make the 64-bit inputs for the DES algorithms. The first -octet supplies the 8 most significant bits (with the octet's MSbit used as -the DES input block's MSbit, etc.), the second octet the next 8 bits, ..., -and the eighth octet supplies the 8 least significant bits. - -Encryption under DES using cipher block chaining requires an additional -input in the form of an initialization vector. Unless otherwise specified, -zero should be used as the initialization vector. Kerberos' use of DES -requires an 8 octet confounder. - -The DES specifications identify some 'weak' and 'semi-weak' keys; those -keys shall not be used for encrypting messages for use in Kerberos. -Additionally, because of the way that keys are derived for the encryption -of checksums, keys shall not be used that yield 'weak' or 'semi-weak' keys -when eXclusive-ORed with the hexadecimal constant F0F0F0F0F0F0F0F0. - -A DES key is 8 octets of data, with keytype one (1). This consists of 56 -bits of key, and 8 parity bits (one per octet). The key is encoded as a -series of 8 octets written in MSB-first order. The bits within the key are -also encoded in MSB order. For example, if the encryption key is -(B1,B2,...,B7,P1,B8,...,B14,P2,B15,...,B49,P7,B50,...,B56,P8) where -B1,B2,...,B56 are the key bits in MSB order, and P1,P2,...,P8 are the -parity bits, the first octet of the key would be B1,B2,...,B7,P1 (with B1 -as the MSbit). [See the FIPS 81 introduction for reference.] - -String to key transformation - -To generate a DES key from a text string (password), a "salt" is -concatenated to the text string, and then padded with ASCII nulls to an 8 -byte boundary. This "salt" is normally the realm and each component of the -principal's name appended. However, sometimes different salts are used --- -for example, when a realm is renamed, or if a user changes her username, or -for compatibility with Kerberos V4 (whose string-to-key algorithm uses a -null string for the salt). This string is then fan-folded and -eXclusive-ORed with itself to form an 8 byte DES key. Before - -Neuman, Ts'o, Kohl Expires: 18 May 1999 - - -INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 - - -eXclusive-ORing a block, every byte is shifted one bit to the left to leave -the lowest bit zero. The key is the "corrected" by correcting the parity on -the key, and if the key matches a 'weak' or 'semi-weak' key as described in -the DES specification, it is eXclusive-ORed with the constant -00000000000000F0. This key is then used to generate a DES CBC checksum on -the initial string (with the salt appended). The result of the CBC checksum -is the "corrected" as described above to form the result which is return as -the key. Pseudocode follows: - - name_to_default_salt(realm, name) { - s = realm - for(each component in name) { - s = s + component; - } - return s; - } - - key_correction(key) { - fixparity(key); - if (is_weak_key_key(key)) - key = key XOR 0xF0; - return(key); - } - - string_to_key(string,salt) { - - odd = 1; - s = string + salt; - tempkey = NULL; - pad(s); /* with nulls to 8 byte boundary */ - for(8byteblock in s) { - if(odd == 0) { - odd = 1; - reverse(8byteblock) - } - else odd = 0; - left shift every byte in 8byteblock one bit; - tempkey = tempkey XOR 8byteblock; - } - tempkey = key_correction(tempkey); - key = key_correction(DES-CBC-check(s,tempkey)); - return(key); - } - -6.3.5. Triple DES with HMAC-SHA1 Kerberos Encryption Type with Key -Derivation [Horowitz] - -NOTE: This description currently refers to documents, the contents of which -might be bettered included by value in this spec. The description below was -provided by Marc Horowitz, and the form in which it will finally appear is -yet to be determined. This description is included in this version of the -draft because it does describe the implemenation ready for use with the MIT -implementation. Note also that the encryption identifier has been left -unspecified here because the value from Marc Horowitz's spec conflicted -with some other impmenentations implemented based on perevious versions of -the specification. - -This encryption type is based on the Triple DES cryptosystem, the HMAC-SHA1 -[Krawczyk96] message authentication algorithm, and key derivation for - -Neuman, Ts'o, Kohl Expires: 18 May 1999 - - -INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 - - -Kerberos V5 [HorowitzB96]. - -The des3-cbc-hmac-sha1 encryption type has been assigned the value ??. The -hmac-sha1-des3 checksum type has been assigned the value 12. - -Encryption Type des3-cbc-hmac-sha1 - -EncryptedData using this type must be generated as described in -[Horowitz96]. The encryption algorithm is Triple DES in Outer-CBC mode. The -keyed hash algorithm is HMAC-SHA1. Unless otherwise specified, a zero IV -must be used. If the length of the input data is not a multiple of the -block size, zero octets must be used to pad the plaintext to the next -eight-octet boundary. The counfounder must be eight random octets (one -block). - -Checksum Type hmac-sha1-des3 - -Checksums using this type must be generated as described in [Horowitz96]. -The keyed hash algorithm is HMAC-SHA1. - -Common Requirements - -The EncryptionKey value is 24 octets long. The 7 most significant bits of -each octet contain key bits, and the least significant bit is the inverse -of the xor of the key bits. - -For the purposes of key derivation, the block size is 64 bits, and the key -size is 168 bits. The 168 bits output by key derivation are converted to an -EncryptionKey value as follows. First, the 168 bits are divided into three -groups of 56 bits, which are expanded individually into 64 bits as follows: - - 1 2 3 4 5 6 7 p - 9 10 11 12 13 14 15 p -17 18 19 20 21 22 23 p -25 26 27 28 29 30 31 p -33 34 35 36 37 38 39 p -41 42 43 44 45 46 47 p -49 50 51 52 53 54 55 p -56 48 40 32 24 16 8 p - -The "p" bits are parity bits computed over the data bits. The output of the -three expansions are concatenated to form the EncryptionKey value. - -When the HMAC-SHA1 of a string is computed, the key is used in the -EncryptedKey form. - -Key Derivation - -In the Kerberos protocol, cryptographic keys are used in a number of -places. In order to minimize the effect of compromising a key, it is -desirable to use a different key for each of these places. Key derivation -[Horowitz96] can be used to construct different keys for each operation -from the keys transported on the network. For this to be possible, a small -change to the specification is necessary. - -This section specifies a profile for the use of key derivation [Horowitz96] -with Kerberos. For each place where a key is used, a ``key usage'' must is -specified for that purpose. The key, key usage, and encryption/checksum -type together describe the transformation from plaintext to ciphertext, or - -Neuman, Ts'o, Kohl Expires: 18 May 1999 - - -INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 - - -plaintext to checksum. - -Key Usage Values - -This is a complete list of places keys are used in the kerberos protocol, -with key usage values and RFC 1510 section numbers: - - 1. AS-REQ PA-ENC-TIMESTAMP padata timestamp, encrypted with the - client key (section 5.4.1) - 2. AS-REP Ticket and TGS-REP Ticket (includes tgs session key or - application session key), encrypted with the service key - (section 5.4.2) - 3. AS-REP encrypted part (includes tgs session key or application - session key), encrypted with the client key (section 5.4.2) - 4. TGS-REQ KDC-REQ-BODY AuthorizationData, encrypted with the tgs - session key (section 5.4.1) - 5. TGS-REQ KDC-REQ-BODY AuthorizationData, encrypted with the tgs - authenticator subkey (section 5.4.1) - 6. TGS-REQ PA-TGS-REQ padata AP-REQ Authenticator cksum, keyed - with the tgs session key (sections 5.3.2, 5.4.1) - 7. TGS-REQ PA-TGS-REQ padata AP-REQ Authenticator (includes tgs - authenticator subkey), encrypted with the tgs session key - (section 5.3.2) - 8. TGS-REP encrypted part (includes application session key), - encrypted with the tgs session key (section 5.4.2) - 9. TGS-REP encrypted part (includes application session key), - encrypted with the tgs authenticator subkey (section 5.4.2) -10. AP-REQ Authenticator cksum, keyed with the application session - key (section 5.3.2) -11. AP-REQ Authenticator (includes application authenticator - subkey), encrypted with the application session key (section - 5.3.2) -12. AP-REP encrypted part (includes application session subkey), - encrypted with the application session key (section 5.5.2) -13. KRB-PRIV encrypted part, encrypted with a key chosen by the - application (section 5.7.1) -14. KRB-CRED encrypted part, encrypted with a key chosen by the - application (section 5.6.1) -15. KRB-SAVE cksum, keyed with a key chosen by the application - (section 5.8.1) -18. KRB-ERROR checksum (e-cksum in section 5.9.1) -19. AD-KDCIssued checksum (ad-checksum in appendix B.1) -20. Checksum for Mandatory Ticket Extensions (appendix B.6) -21. Checksum in Authorization Data in Ticket Extensions (appendix B.7) - -Key usage values between 1024 and 2047 (inclusive) are reserved for -application use. Applications should use even values for encryption and odd -values for checksums within this range. - -A few of these key usages need a little clarification. A service which -receives an AP-REQ has no way to know if the enclosed Ticket was part of an -AS-REP or TGS-REP. Therefore, key usage 2 must always be used for -generating a Ticket, whether it is in response to an AS- REQ or TGS-REQ. - -There might exist other documents which define protocols in terms of the -RFC1510 encryption types or checksum types. Such documents would not know -about key usages. In order that these documents continue to be meaningful -until they are updated, key usages 1024 and 1025 must be used to derive -keys for encryption and checksums, respectively. New protocols defined in - -Neuman, Ts'o, Kohl Expires: 18 May 1999 - - -INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 - - -terms of the Kerberos encryption and checksum types should use their own -key usages. Key usages may be registered with IANA to avoid conflicts. Key -usages must be unsigned 32 bit integers. Zero is not permitted. - -Defining Cryptosystems Using Key Derivation - -Kerberos requires that the ciphertext component of EncryptedData be -tamper-resistant as well as confidential. This implies encryption and -integrity functions, which must each use their own separate keys. So, for -each key usage, two keys must be generated, one for encryption (Ke), and -one for integrity (Ki): - - Ke = DK(protocol key, key usage | 0xAA) - Ki = DK(protocol key, key usage | 0x55) - -where the protocol key is from the EncryptionKey from the wire protocol, -and the key usage is represented as a 32 bit integer in network byte order. -The ciphertest must be generated from the plaintext as follows: - - ciphertext = E(Ke, confounder | plaintext | padding) | - H(Ki, confounder | plaintext | padding) - -The confounder and padding are specific to the encryption algorithm E. - -When generating a checksum only, there is no need for a confounder or -padding. Again, a new key (Kc) must be used. Checksums must be generated -from the plaintext as follows: - - Kc = DK(protocol key, key usage | 0x99) - - MAC = H(Kc, plaintext) - -Note that each enctype is described by an encryption algorithm E and a -keyed hash algorithm H, and each checksum type is described by a keyed hash -algorithm H. HMAC, with an appropriate hash, is recommended for use as H. - -Key Derivation from Passwords - -The well-known constant for password key derivation must be the byte string -{0x6b 0x65 0x72 0x62 0x65 0x72 0x6f 0x73}. These values correspond to the -ASCII encoding for the string "kerberos". - -6.4. Checksums - -The following is the ASN.1 definition used for a checksum: - - Checksum ::= SEQUENCE { - cksumtype[0] INTEGER, - checksum[1] OCTET STRING - } - -cksumtype - This field indicates the algorithm used to generate the accompanying - checksum. -checksum - This field contains the checksum itself, encoded as an octet string. - -Detailed specification of selected checksum types appear later in this -section. Negative values for the checksum type are reserved for local use. - -Neuman, Ts'o, Kohl Expires: 18 May 1999 - - -INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 - - -All non-negative values are reserved for officially assigned type fields -and interpretations. - -Checksums used by Kerberos can be classified by two properties: whether -they are collision-proof, and whether they are keyed. It is infeasible to -find two plaintexts which generate the same checksum value for a -collision-proof checksum. A key is required to perturb or initialize the -algorithm in a keyed checksum. To prevent message-stream modification by an -active attacker, unkeyed checksums should only be used when the checksum -and message will be subsequently encrypted (e.g. the checksums defined as -part of the encryption algorithms covered earlier in this section). - -Collision-proof checksums can be made tamper-proof if the checksum value is -encrypted before inclusion in a message. In such cases, the composition of -the checksum and the encryption algorithm must be considered a separate -checksum algorithm (e.g. RSA-MD5 encrypted using DES is a new checksum -algorithm of type RSA-MD5-DES). For most keyed checksums, as well as for -the encrypted forms of unkeyed collision-proof checksums, Kerberos prepends -a confounder before the checksum is calculated. - -6.4.1. The CRC-32 Checksum (crc32) - -The CRC-32 checksum calculates a checksum based on a cyclic redundancy -check as described in ISO 3309 [ISO3309]. The resulting checksum is four -(4) octets in length. The CRC-32 is neither keyed nor collision-proof. The -use of this checksum is not recommended. An attacker using a probabilistic -chosen-plaintext attack as described in [SG92] might be able to generate an -alternative message that satisfies the checksum. The use of collision-proof -checksums is recommended for environments where such attacks represent a -significant threat. - -6.4.2. The RSA MD4 Checksum (rsa-md4) - -The RSA-MD4 checksum calculates a checksum using the RSA MD4 algorithm -[MD4-92]. The algorithm takes as input an input message of arbitrary length -and produces as output a 128-bit (16 octet) checksum. RSA-MD4 is believed -to be collision-proof. - -6.4.3. RSA MD4 Cryptographic Checksum Using DES (rsa-md4-des) - -The RSA-MD4-DES checksum calculates a keyed collision-proof checksum by -prepending an 8 octet confounder before the text, applying the RSA MD4 -checksum algorithm, and encrypting the confounder and the checksum using -DES in cipher-block-chaining (CBC) mode using a variant of the key, where -the variant is computed by eXclusive-ORing the key with the constant -F0F0F0F0F0F0F0F0[39]. The initialization vector should be zero. The -resulting checksum is 24 octets long (8 octets of which are redundant). -This checksum is tamper-proof and believed to be collision-proof. - -The DES specifications identify some weak keys' and 'semi-weak keys'; those -keys shall not be used for generating RSA-MD4 checksums for use in -Kerberos. - -The format for the checksum is described in the follow- ing diagram: - -+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ -| des-cbc(confounder + rsa-md4(confounder+msg),key=var(key),iv=0) | -+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ - - -Neuman, Ts'o, Kohl Expires: 18 May 1999 - - -INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 - - -The format cannot be described in ASN.1, but for those who prefer an -ASN.1-like notation: - -rsa-md4-des-checksum ::= ENCRYPTED UNTAGGED SEQUENCE { - confounder[0] UNTAGGED OCTET STRING(8), - check[1] UNTAGGED OCTET STRING(16) -} - -6.4.4. The RSA MD5 Checksum (rsa-md5) - -The RSA-MD5 checksum calculates a checksum using the RSA MD5 algorithm. -[MD5-92]. The algorithm takes as input an input message of arbitrary length -and produces as output a 128-bit (16 octet) checksum. RSA-MD5 is believed -to be collision-proof. - -6.4.5. RSA MD5 Cryptographic Checksum Using DES (rsa-md5-des) - -The RSA-MD5-DES checksum calculates a keyed collision-proof checksum by -prepending an 8 octet confounder before the text, applying the RSA MD5 -checksum algorithm, and encrypting the confounder and the checksum using -DES in cipher-block-chaining (CBC) mode using a variant of the key, where -the variant is computed by eXclusive-ORing the key with the hexadecimal -constant F0F0F0F0F0F0F0F0. The initialization vector should be zero. The -resulting checksum is 24 octets long (8 octets of which are redundant). -This checksum is tamper-proof and believed to be collision-proof. - -The DES specifications identify some 'weak keys' and 'semi-weak keys'; -those keys shall not be used for encrypting RSA-MD5 checksums for use in -Kerberos. - -The format for the checksum is described in the following diagram: - -+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ -| des-cbc(confounder + rsa-md5(confounder+msg),key=var(key),iv=0) | -+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ - -The format cannot be described in ASN.1, but for those who prefer an -ASN.1-like notation: - -rsa-md5-des-checksum ::= ENCRYPTED UNTAGGED SEQUENCE { - confounder[0] UNTAGGED OCTET STRING(8), - check[1] UNTAGGED OCTET STRING(16) -} - -6.4.6. DES cipher-block chained checksum (des-mac) - -The DES-MAC checksum is computed by prepending an 8 octet confounder to the -plaintext, performing a DES CBC-mode encryption on the result using the key -and an initialization vector of zero, taking the last block of the -ciphertext, prepending the same confounder and encrypting the pair using -DES in cipher-block-chaining (CBC) mode using a a variant of the key, where -the variant is computed by eXclusive-ORing the key with the hexadecimal -constant F0F0F0F0F0F0F0F0. The initialization vector should be zero. The -resulting checksum is 128 bits (16 octets) long, 64 bits of which are -redundant. This checksum is tamper-proof and collision-proof. - -The format for the checksum is described in the following diagram: - -+--+--+--+--+--+--+--+--+-----+-----+-----+-----+-----+-----+-----+-----+ - -Neuman, Ts'o, Kohl Expires: 18 May 1999 - - -INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 - - -| des-cbc(confounder + des-mac(conf+msg,iv=0,key),key=var(key),iv=0) | -+--+--+--+--+--+--+--+--+-----+-----+-----+-----+-----+-----+-----+-----+ - -The format cannot be described in ASN.1, but for those who prefer an -ASN.1-like notation: - -des-mac-checksum ::= ENCRYPTED UNTAGGED SEQUENCE { - confounder[0] UNTAGGED OCTET STRING(8), - check[1] UNTAGGED OCTET STRING(8) -} - -The DES specifications identify some 'weak' and 'semi-weak' keys; those -keys shall not be used for generating DES-MAC checksums for use in -Kerberos, nor shall a key be used whose variant is 'weak' or 'semi-weak'. - -6.4.7. RSA MD4 Cryptographic Checksum Using DES alternative (rsa-md4-des-k) - -The RSA-MD4-DES-K checksum calculates a keyed collision-proof checksum by -applying the RSA MD4 checksum algorithm and encrypting the results using -DES in cipher-block-chaining (CBC) mode using a DES key as both key and -initialization vector. The resulting checksum is 16 octets long. This -checksum is tamper-proof and believed to be collision-proof. Note that this -checksum type is the old method for encoding the RSA-MD4-DES checksum and -it is no longer recommended. - -6.4.8. DES cipher-block chained checksum alternative (des-mac-k) - -The DES-MAC-K checksum is computed by performing a DES CBC-mode encryption -of the plaintext, and using the last block of the ciphertext as the -checksum value. It is keyed with an encryption key and an initialization -vector; any uses which do not specify an additional initialization vector -will use the key as both key and initialization vector. The resulting -checksum is 64 bits (8 octets) long. This checksum is tamper-proof and -collision-proof. Note that this checksum type is the old method for -encoding the DES-MAC checksum and it is no longer recommended. The DES -specifications identify some 'weak keys' and 'semi-weak keys'; those keys -shall not be used for generating DES-MAC checksums for use in Kerberos. - -7. Naming Constraints - -7.1. Realm Names - -Although realm names are encoded as GeneralStrings and although a realm can -technically select any name it chooses, interoperability across realm -boundaries requires agreement on how realm names are to be assigned, and -what information they imply. - -To enforce these conventions, each realm must conform to the conventions -itself, and it must require that any realms with which inter-realm keys are -shared also conform to the conventions and require the same from its -neighbors. - -Kerberos realm names are case sensitive. Realm names that differ only in -the case of the characters are not equivalent. There are presently four -styles of realm names: domain, X500, other, and reserved. Examples of each -style follow: - - domain: ATHENA.MIT.EDU (example) - X500: C=US/O=OSF (example) - -Neuman, Ts'o, Kohl Expires: 18 May 1999 - - -INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 - - - other: NAMETYPE:rest/of.name=without-restrictions (example) - reserved: reserved, but will not conflict with above - -Domain names must look like domain names: they consist of components -separated by periods (.) and they contain neither colons (:) nor slashes -(/). Domain names must be converted to upper case when used as realm names. - -X.500 names contain an equal (=) and cannot contain a colon (:) before the -equal. The realm names for X.500 names will be string representations of -the names with components separated by slashes. Leading and trailing -slashes will not be included. - -Names that fall into the other category must begin with a prefix that -contains no equal (=) or period (.) and the prefix must be followed by a -colon (:) and the rest of the name. All prefixes must be assigned before -they may be used. Presently none are assigned. - -The reserved category includes strings which do not fall into the first -three categories. All names in this category are reserved. It is unlikely -that names will be assigned to this category unless there is a very strong -argument for not using the 'other' category. - -These rules guarantee that there will be no conflicts between the various -name styles. The following additional constraints apply to the assignment -of realm names in the domain and X.500 categories: the name of a realm for -the domain or X.500 formats must either be used by the organization owning -(to whom it was assigned) an Internet domain name or X.500 name, or in the -case that no such names are registered, authority to use a realm name may -be derived from the authority of the parent realm. For example, if there is -no domain name for E40.MIT.EDU, then the administrator of the MIT.EDU realm -can authorize the creation of a realm with that name. - -This is acceptable because the organization to which the parent is assigned -is presumably the organization authorized to assign names to its children -in the X.500 and domain name systems as well. If the parent assigns a realm -name without also registering it in the domain name or X.500 hierarchy, it -is the parent's responsibility to make sure that there will not in the -future exists a name identical to the realm name of the child unless it is -assigned to the same entity as the realm name. - -7.2. Principal Names - -As was the case for realm names, conventions are needed to ensure that all -agree on what information is implied by a principal name. The name-type -field that is part of the principal name indicates the kind of information -implied by the name. The name-type should be treated as a hint. Ignoring -the name type, no two names can be the same (i.e. at least one of the -components, or the realm, must be different). The following name types are -defined: - - name-type value meaning - - NT-UNKNOWN 0 Name type not known - NT-PRINCIPAL 1 General principal name (e.g. username, or DCE -principal) - NT-SRV-INST 2 Service and other unique instance (krbtgt) - NT-SRV-HST 3 Service with host name as instance (telnet, -rcommands) - NT-SRV-XHST 4 Service with slash-separated host name components - NT-UID 5 Unique ID - NT-X500-PRINCIPAL 6 Encoded X.509 Distingished name [RFC 1779] - -Neuman, Ts'o, Kohl Expires: 18 May 1999 - - -INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 - - - -When a name implies no information other than its uniqueness at a -particular time the name type PRINCIPAL should be used. The principal name -type should be used for users, and it might also be used for a unique -server. If the name is a unique machine generated ID that is guaranteed -never to be reassigned then the name type of UID should be used (note that -it is generally a bad idea to reassign names of any type since stale -entries might remain in access control lists). - -If the first component of a name identifies a service and the remaining -components identify an instance of the service in a server specified -manner, then the name type of SRV-INST should be used. An example of this -name type is the Kerberos ticket-granting service whose name has a first -component of krbtgt and a second component identifying the realm for which -the ticket is valid. - -If instance is a single component following the service name and the -instance identifies the host on which the server is running, then the name -type SRV-HST should be used. This type is typically used for Internet -services such as telnet and the Berkeley R commands. If the separate -components of the host name appear as successive components following the -name of the service, then the name type SRV-XHST should be used. This type -might be used to identify servers on hosts with X.500 names where the slash -(/) might otherwise be ambiguous. - -A name type of NT-X500-PRINCIPAL should be used when a name from an X.509 -certificiate is translated into a Kerberos name. The encoding of the X.509 -name as a Kerberos principal shall conform to the encoding rules specified -in RFC 2253. - -A name type of UNKNOWN should be used when the form of the name is not -known. When comparing names, a name of type UNKNOWN will match principals -authenticated with names of any type. A principal authenticated with a name -of type UNKNOWN, however, will only match other names of type UNKNOWN. - -Names of any type with an initial component of 'krbtgt' are reserved for -the Kerberos ticket granting service. See section 8.2.3 for the form of -such names. - -7.2.1. Name of server principals - -The principal identifier for a server on a host will generally be composed -of two parts: (1) the realm of the KDC with which the server is registered, -and (2) a two-component name of type NT-SRV-HST if the host name is an -Internet domain name or a multi-component name of type NT-SRV-XHST if the -name of the host is of a form such as X.500 that allows slash (/) -separators. The first component of the two- or multi-component name will -identify the service and the latter components will identify the host. -Where the name of the host is not case sensitive (for example, with -Internet domain names) the name of the host must be lower case. If -specified by the application protocol for services such as telnet and the -Berkeley R commands which run with system privileges, the first component -may be the string 'host' instead of a service specific identifier. When a -host has an official name and one or more aliases, the official name of the -host must be used when constructing the name of the server principal. - -8. Constants and other defined values - -8.1. Host address types - -Neuman, Ts'o, Kohl Expires: 18 May 1999 - - -INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 - - - -All negative values for the host address type are reserved for local use. -All non-negative values are reserved for officially assigned type fields -and interpretations. - -The values of the types for the following addresses are chosen to match the -defined address family constants in the Berkeley Standard Distributions of -Unix. They can be found in with symbolic names AF_xxx (where xxx is an -abbreviation of the address family name). - -Internet (IPv4) Addresses - -Internet (IPv4) addresses are 32-bit (4-octet) quantities, encoded in MSB -order. The type of IPv4 addresses is two (2). - -Internet (IPv6) Addresses [Westerlund] - -IPv6 addresses are 128-bit (16-octet) quantities, encoded in MSB order. The -type of IPv6 addresses is twenty-four (24). [RFC1883] [RFC1884]. The -following addresses (see [RFC1884]) MUST not appear in any Kerberos packet: - - * the Unspecified Address - * the Loopback Address - * Link-Local addresses - -IPv4-mapped IPv6 addresses MUST be represented as addresses of type 2. - -CHAOSnet addresses - -CHAOSnet addresses are 16-bit (2-octet) quantities, encoded in MSB order. -The type of CHAOSnet addresses is five (5). - -ISO addresses - -ISO addresses are variable-length. The type of ISO addresses is seven (7). - -Xerox Network Services (XNS) addresses - -XNS addresses are 48-bit (6-octet) quantities, encoded in MSB order. The -type of XNS addresses is six (6). - -AppleTalk Datagram Delivery Protocol (DDP) addresses - -AppleTalk DDP addresses consist of an 8-bit node number and a 16-bit -network number. The first octet of the address is the node number; the -remaining two octets encode the network number in MSB order. The type of -AppleTalk DDP addresses is sixteen (16). - -DECnet Phase IV addresses - -DECnet Phase IV addresses are 16-bit addresses, encoded in LSB order. The -type of DECnet Phase IV addresses is twelve (12). - -Netbios addresses - -Netbios addresses are 16-octet addresses typically composed of 1 to 15 -characters, trailing blank (ascii char 20) filled, with a 16th octet of -0x0. The type of Netbios addresses is 20 (0x14). - - -Neuman, Ts'o, Kohl Expires: 18 May 1999 - - -INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 - - -8.2. KDC messages - -8.2.1. UDP/IP transport - -When contacting a Kerberos server (KDC) for a KRB_KDC_REQ request using UDP -IP transport, the client shall send a UDP datagram containing only an -encoding of the request to port 88 (decimal) at the KDC's IP address; the -KDC will respond with a reply datagram containing only an encoding of the -reply message (either a KRB_ERROR or a KRB_KDC_REP) to the sending port at -the sender's IP address. Kerberos servers supporting IP transport must -accept UDP requests on port 88 (decimal). The response to a request made -through UDP/IP transport must also use UDP/IP transport. - -8.2.2. TCP/IP transport [Westerlund,Danielsson] - -Kerberos servers (KDC's) should accept TCP requests on port 88 (decimal) -and clients should support the sending of TCP requests on port 88 -(decimal). When the KRB_KDC_REQ message is sent to the KDC over a TCP -stream, a new connection will be established for each authentication -exchange (request and response). The KRB_KDC_REP or KRB_ERROR message will -be returned to the client on the same TCP stream that was established for -the request. The response to a request made through TCP/IP transport must -also use TCP/IP transport. Implementors should note that some extentions to -the Kerberos protocol will not work if any implementation not supporting -the TCP transport is involved (client or KDC). Implementors are strongly -urged to support the TCP transport on both the client and server and are -advised that the current notation of "should" support will likely change in -the future to must support. The KDC may close the TCP stream after sending -a response, but may leave the stream open if it expects a followup - in -which case it may close the stream at any time if resource constratints or -other factors make it desirable to do so. Care must be taken in managing -TCP/IP connections with the KDC to prevent denial of service attacks based -on the number of TCP/IP connections with the KDC that remain open. If -multiple exchanges with the KDC are needed for certain forms of -preauthentication, multiple TCP connections may be required. A client may -close the stream after receiving response, and should close the stream if -it does not expect to send followup messages. The client must be prepared -to have the stream closed by the KDC at anytime, in which case it must -simply connect again when it is ready to send subsequent messages. - -The first four octets of the TCP stream used to transmit the request -request will encode in network byte order the length of the request -(KRB_KDC_REQ), and the length will be followed by the request itself. The -response will similarly be preceeded by a 4 octet encoding in network byte -order of the length of the KRB_KDC_REP or the KRB_ERROR message and will be -followed by the KRB_KDC_REP or the KRB_ERROR response. If the sign bit is -set on integer represented by the first 4 octets, then the next 4 octets -will be read, extending the length of the field by another 4 octets (less 1 -bit). - -8.2.3. OSI transport - -During authentication of an OSI client to an OSI server, the mutual -authentication of an OSI server to an OSI client, the transfer of -credentials from an OSI client to an OSI server, or during exchange of -private or integrity checked messages, Kerberos protocol messages may be -treated as opaque objects and the type of the authentication mechanism will -be: - - -Neuman, Ts'o, Kohl Expires: 18 May 1999 - - -INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 - - -OBJECT IDENTIFIER ::= {iso (1), org(3), dod(6),internet(1), -security(5),kerberosv5(2)} - -Depending on the situation, the opaque object will be an authentication -header (KRB_AP_REQ), an authentication reply (KRB_AP_REP), a safe message -(KRB_SAFE), a private message (KRB_PRIV), or a credentials message -(KRB_CRED). The opaque data contains an application code as specified in -the ASN.1 description for each message. The application code may be used by -Kerberos to determine the message type. - -8.2.3. Name of the TGS - -The principal identifier of the ticket-granting service shall be composed -of three parts: (1) the realm of the KDC issuing the TGS ticket (2) a -two-part name of type NT-SRV-INST, with the first part "krbtgt" and the -second part the name of the realm which will accept the ticket-granting -ticket. For example, a ticket-granting ticket issued by the ATHENA.MIT.EDU -realm to be used to get tickets from the ATHENA.MIT.EDU KDC has a principal -identifier of "ATHENA.MIT.EDU" (realm), ("krbtgt", "ATHENA.MIT.EDU") -(name). A ticket-granting ticket issued by the ATHENA.MIT.EDU realm to be -used to get tickets from the MIT.EDU realm has a principal identifier of -"ATHENA.MIT.EDU" (realm), ("krbtgt", "MIT.EDU") (name). - -8.3. Protocol constants and associated values - -The following tables list constants used in the protocol and defines their -meanings. Ranges are specified in the "specification" section that limit -the values of constants for which values are defined here. This allows -implementations to make assumptions about the maximum values that will be -received for these constants. Implementation receiving values outside the -range specified in the "specification" section may reject the request, but -they must recover cleanly. - -Encryption type etype value block size minimum pad size confounder -size -NULL 0 1 0 0 -des-cbc-crc 1 8 4 8 -des-cbc-md4 2 8 0 8 -des-cbc-md5 3 8 0 8 - 4 -des3-cbc-md5 5 8 0 8 - 6 -des3-cbc-sha1 7 8 0 8 -sign-dsa-generate 8 (pkinit) -encrypt-rsa-priv 9 (pkinit) -encrypt-rsa-pub 10 (pkinit) -rsa-pub-md5 11 (pkinit) -rsa-pub-sha1 12 (pkinit) -des3kd-cbc-sha1 ?? 8 0 8 -ENCTYPE_PK_CROSS 48 (reserved for pkcross) - 0x8003 - -Checksum type sumtype value checksum size -CRC32 1 4 -rsa-md4 2 16 -rsa-md4-des 3 24 -des-mac 4 16 -des-mac-k 5 8 -rsa-md4-des-k 6 16 -rsa-md5 7 16 -rsa-md5-des 8 24 - -Neuman, Ts'o, Kohl Expires: 18 May 1999 - - -INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 - - -rsa-md5-des3 9 24 -hmac-sha1-des3 12 20 (I had this as 10, is it -12) - -padata type padata-type value - -PA-TGS-REQ 1 -PA-ENC-TIMESTAMP 2 -PA-PW-SALT 3 - 4 -PA-ENC-UNIX-TIME 5 -PA-SANDIA-SECUREID 6 -PA-SESAME 7 -PA-OSF-DCE 8 -PA-CYBERSAFE-SECUREID 9 -PA-AFS3-SALT 10 -PA-ETYPE-INFO 11 -SAM-CHALLENGE 12 (sam/otp) -SAM-RESPONSE 13 (sam/otp) -PA-PK-AS-REQ 14 (pkinit) -PA-PK-AS-REP 15 (pkinit) -PA-PK-AS-SIGN 16 (pkinit) -PA-PK-KEY-REQ 17 (pkinit) -PA-PK-KEY-REP 18 (pkinit) -PA-USE-SPECIFIED-KVNO 20 - -authorization data type ad-type value -AD-KDC-ISSUED 1 -AD-INTENDED-FOR-SERVER 2 -AD-INTENDED-FOR-APPLICATION-CLASS 3 -AD-IF-RELEVANT 4 -AD-OR 5 -AD-MANDATORY-TICKET-EXTENSIONS 6 -AD-IN-TICKET-EXTENSIONS 7 -reserved values 8-63 -OSF-DCE 64 -SESAME 65 - -Ticket Extension Types - -TE-TYPE-NULL 0 Null ticket extension -TE-TYPE-EXTERNAL-ADATA 1 Integrity protected authorization data - 2 TE-TYPE-PKCROSS-KDC (I have reservations) -TE-TYPE-PKCROSS-CLIENT 3 PKCROSS cross realm key ticket -TE-TYPE-CYBERSAFE-EXT 4 Assigned to CyberSafe Corp - 5 TE-TYPE-DEST-HOST (I have reservations) - -alternate authentication type method-type value -reserved values 0-63 -ATT-CHALLENGE-RESPONSE 64 - -transited encoding type tr-type value -DOMAIN-X500-COMPRESS 1 -reserved values all others - -Label Value Meaning or MIT code - -pvno 5 current Kerberos protocol version number - -message types - -Neuman, Ts'o, Kohl Expires: 18 May 1999 - - -INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 - - - -KRB_AS_REQ 10 Request for initial authentication -KRB_AS_REP 11 Response to KRB_AS_REQ request -KRB_TGS_REQ 12 Request for authentication based on TGT -KRB_TGS_REP 13 Response to KRB_TGS_REQ request -KRB_AP_REQ 14 application request to server -KRB_AP_REP 15 Response to KRB_AP_REQ_MUTUAL -KRB_SAFE 20 Safe (checksummed) application message -KRB_PRIV 21 Private (encrypted) application message -KRB_CRED 22 Private (encrypted) message to forward -credentials -KRB_ERROR 30 Error response - -name types - -KRB_NT_UNKNOWN 0 Name type not known -KRB_NT_PRINCIPAL 1 Just the name of the principal as in DCE, or for -users -KRB_NT_SRV_INST 2 Service and other unique instance (krbtgt) -KRB_NT_SRV_HST 3 Service with host name as instance (telnet, -rcommands) -KRB_NT_SRV_XHST 4 Service with host as remaining components -KRB_NT_UID 5 Unique ID -KRB_NT_X500_PRINCIPAL 6 Encoded X.509 Distingished name [RFC 2253] - -error codes - -KDC_ERR_NONE 0 No error -KDC_ERR_NAME_EXP 1 Client's entry in database has expired -KDC_ERR_SERVICE_EXP 2 Server's entry in database has expired -KDC_ERR_BAD_PVNO 3 Requested protocol version number not -supported -KDC_ERR_C_OLD_MAST_KVNO 4 Client's key encrypted in old master key -KDC_ERR_S_OLD_MAST_KVNO 5 Server's key encrypted in old master key -KDC_ERR_C_PRINCIPAL_UNKNOWN 6 Client not found in Kerberos database -KDC_ERR_S_PRINCIPAL_UNKNOWN 7 Server not found in Kerberos database -KDC_ERR_PRINCIPAL_NOT_UNIQUE 8 Multiple principal entries in database -KDC_ERR_NULL_KEY 9 The client or server has a null key -KDC_ERR_CANNOT_POSTDATE 10 Ticket not eligible for postdating -KDC_ERR_NEVER_VALID 11 Requested start time is later than end -time -KDC_ERR_POLICY 12 KDC policy rejects request -KDC_ERR_BADOPTION 13 KDC cannot accommodate requested option -KDC_ERR_ETYPE_NOSUPP 14 KDC has no support for encryption type -KDC_ERR_SUMTYPE_NOSUPP 15 KDC has no support for checksum type -KDC_ERR_PADATA_TYPE_NOSUPP 16 KDC has no support for padata type -KDC_ERR_TRTYPE_NOSUPP 17 KDC has no support for transited type -KDC_ERR_CLIENT_REVOKED 18 Clients credentials have been revoked -KDC_ERR_SERVICE_REVOKED 19 Credentials for server have been revoked -KDC_ERR_TGT_REVOKED 20 TGT has been revoked -KDC_ERR_CLIENT_NOTYET 21 Client not yet valid - try again later -KDC_ERR_SERVICE_NOTYET 22 Server not yet valid - try again later -KDC_ERR_KEY_EXPIRED 23 Password has expired - change password -to reset -KDC_ERR_PREAUTH_FAILED 24 Pre-authentication information was -invalid -KDC_ERR_PREAUTH_REQUIRED 25 Additional pre-authenticationrequired -[40] -KDC_ERR_SERVER_NOMATCH 26 Requested server and ticket don't match -KDC_ERR_MUST_USE_USER2USER 27 Server principal valid for user2user -only -KDC_ERR_PATH_NOT_ACCPETED 28 KDC Policy rejects transited path -KRB_AP_ERR_BAD_INTEGRITY 31 Integrity check on decrypted field -failed -KRB_AP_ERR_TKT_EXPIRED 32 Ticket expired -KRB_AP_ERR_TKT_NYV 33 Ticket not yet valid -KRB_AP_ERR_REPEAT 34 Request is a replay -KRB_AP_ERR_NOT_US 35 The ticket isn't for us -KRB_AP_ERR_BADMATCH 36 Ticket and authenticator don't match - -Neuman, Ts'o, Kohl Expires: 18 May 1999 - - -INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 - - -KRB_AP_ERR_SKEW 37 Clock skew too great -KRB_AP_ERR_BADADDR 38 Incorrect net address -KRB_AP_ERR_BADVERSION 39 Protocol version mismatch -KRB_AP_ERR_MSG_TYPE 40 Invalid msg type -KRB_AP_ERR_MODIFIED 41 Message stream modified -KRB_AP_ERR_BADORDER 42 Message out of order -KRB_AP_ERR_BADKEYVER 44 Specified version of key is not -available -KRB_AP_ERR_NOKEY 45 Service key not available -KRB_AP_ERR_MUT_FAIL 46 Mutual authentication failed -KRB_AP_ERR_BADDIRECTION 47 Incorrect message direction -KRB_AP_ERR_METHOD 48 Alternative authentication method -required -KRB_AP_ERR_BADSEQ 49 Incorrect sequence number in message -KRB_AP_ERR_INAPP_CKSUM 50 Inappropriate type of checksum in -message -KRB_AP_PATH_NOT_ACCEPTED 51 Policy rejects transited path -KRB_ERR_RESPONSE_TOO_BIG 52 Response too big for UDP, retry with TCP -KRB_ERR_GENERIC 60 Generic error (description in e-text) -KRB_ERR_FIELD_TOOLONG 61 Field is too long for this -implementation -KDC_ERROR_CLIENT_NOT_TRUSTED 62 (pkinit) -KDC_ERROR_KDC_NOT_TRUSTED 63 (pkinit) -KDC_ERROR_INVALID_SIG 64 (pkinit) -KDC_ERR_KEY_TOO_WEAK 65 (pkinit) -KDC_ERR_CERTIFICATE_MISMATCH 66 (pkinit) - -9. Interoperability requirements - -Version 5 of the Kerberos protocol supports a myriad of options. Among -these are multiple encryption and checksum types, alternative encoding -schemes for the transited field, optional mechanisms for -pre-authentication, the handling of tickets with no addresses, options for -mutual authentication, user to user authentication, support for proxies, -forwarding, postdating, and renewing tickets, the format of realm names, -and the handling of authorization data. - -In order to ensure the interoperability of realms, it is necessary to -define a minimal configuration which must be supported by all -implementations. This minimal configuration is subject to change as -technology does. For example, if at some later date it is discovered that -one of the required encryption or checksum algorithms is not secure, it -will be replaced. - -9.1. Specification 2 - -This section defines the second specification of these options. -Implementations which are configured in this way can be said to support -Kerberos Version 5 Specification 2 (5.1). Specification 1 (depricated) may -be found in RFC1510. - -Transport - -TCP/IP and UDP/IP transport must be supported by KDCs claiming conformance -to specification 2. Kerberos clients claiming conformance to specification -2 must support UDP/IP transport for messages with the KDC and should -support TCP/IP transport. - -Encryption and checksum methods - -The following encryption and checksum mechanisms must be supported. -Implementations may support other mechanisms as well, but the additional -mechanisms may only be used when communicating with principals known to - -Neuman, Ts'o, Kohl Expires: 18 May 1999 - - -INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 - - -also support them: This list is to be determined. - -Encryption: DES-CBC-MD5 -Checksums: CRC-32, DES-MAC, DES-MAC-K, and DES-MD5 - -Realm Names - -All implementations must understand hierarchical realms in both the -Internet Domain and the X.500 style. When a ticket granting ticket for an -unknown realm is requested, the KDC must be able to determine the names of -the intermediate realms between the KDCs realm and the requested realm. - -Transited field encoding - -DOMAIN-X500-COMPRESS (described in section 3.3.3.2) must be supported. -Alternative encodings may be supported, but they may be used only when that -encoding is supported by ALL intermediate realms. - -Pre-authentication methods - -The TGS-REQ method must be supported. The TGS-REQ method is not used on the -initial request. The PA-ENC-TIMESTAMP method must be supported by clients -but whether it is enabled by default may be determined on a realm by realm -basis. If not used in the initial request and the error -KDC_ERR_PREAUTH_REQUIRED is returned specifying PA-ENC-TIMESTAMP as an -acceptable method, the client should retry the initial request using the -PA-ENC-TIMESTAMP preauthentication method. Servers need not support the -PA-ENC-TIMESTAMP method, but if not supported the server should ignore the -presence of PA-ENC-TIMESTAMP pre-authentication in a request. - -Mutual authentication - -Mutual authentication (via the KRB_AP_REP message) must be supported. - -Ticket addresses and flags - -All KDC's must pass on tickets that carry no addresses (i.e. if a TGT -contains no addresses, the KDC will return derivative tickets), but each -realm may set its own policy for issuing such tickets, and each application -server will set its own policy with respect to accepting them. - -Proxies and forwarded tickets must be supported. Individual realms and -application servers can set their own policy on when such tickets will be -accepted. - -All implementations must recognize renewable and postdated tickets, but -need not actually implement them. If these options are not supported, the -starttime and endtime in the ticket shall specify a ticket's entire useful -life. When a postdated ticket is decoded by a server, all implementations -shall make the presence of the postdated flag visible to the calling -server. - -User-to-user authentication - -Support for user to user authentication (via the ENC-TKT-IN-SKEY KDC -option) must be provided by implementations, but individual realms may -decide as a matter of policy to reject such requests on a per-principal or -realm-wide basis. - - -Neuman, Ts'o, Kohl Expires: 18 May 1999 - - -INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 - - -Authorization data - -Implementations must pass all authorization data subfields from -ticket-granting tickets to any derivative tickets unless directed to -suppress a subfield as part of the definition of that registered subfield -type (it is never incorrect to pass on a subfield, and no registered -subfield types presently specify suppression at the KDC). - -Implementations must make the contents of any authorization data subfields -available to the server when a ticket is used. Implementations are not -required to allow clients to specify the contents of the authorization data -fields. - -Constant ranges - -All protocol constants are constrained to 32 bit (signed) values unless -further constrained by the protocol definition. This limit is provided to -allow implementations to make assumptions about the maximum values that -will be received for these constants. Implementation receiving values -outside this range may reject the request, but they must recover cleanly. - -9.2. Recommended KDC values - -Following is a list of recommended values for a KDC implementation, based -on the list of suggested configuration constants (see section 4.4). - -minimum lifetime 5 minutes -maximum renewable lifetime 1 week -maximum ticket lifetime 1 day -empty addresses only when suitable restrictions appear - in authorization data -proxiable, etc. Allowed. - -10. REFERENCES - -[NT94] B. Clifford Neuman and Theodore Y. Ts'o, "An Authenti- - cation Service for Computer Networks," IEEE Communica- - tions Magazine, Vol. 32(9), pp. 33-38 (September 1994). - -[MNSS87] S. P. Miller, B. C. Neuman, J. I. Schiller, and J. H. - Saltzer, Section E.2.1: Kerberos Authentication and - Authorization System, M.I.T. Project Athena, Cambridge, - Massachusetts (December 21, 1987). - -[SNS88] J. G. Steiner, B. C. Neuman, and J. I. Schiller, "Ker- - beros: An Authentication Service for Open Network Sys- - tems," pp. 191-202 in Usenix Conference Proceedings, - Dallas, Texas (February, 1988). - -[NS78] Roger M. Needham and Michael D. Schroeder, "Using - Encryption for Authentication in Large Networks of Com- - puters," Communications of the ACM, Vol. 21(12), - pp. 993-999 (December, 1978). - -[DS81] Dorothy E. Denning and Giovanni Maria Sacco, "Time- - stamps in Key Distribution Protocols," Communications - of the ACM, Vol. 24(8), pp. 533-536 (August 1981). - -[KNT92] John T. Kohl, B. Clifford Neuman, and Theodore Y. Ts'o, - -Neuman, Ts'o, Kohl Expires: 18 May 1999 - - -INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 - - - "The Evolution of the Kerberos Authentication Service," - in an IEEE Computer Society Text soon to be published - (June 1992). - -[Neu93] B. Clifford Neuman, "Proxy-Based Authorization and - Accounting for Distributed Systems," in Proceedings of - the 13th International Conference on Distributed Com- - puting Systems, Pittsburgh, PA (May, 1993). - -[DS90] Don Davis and Ralph Swick, "Workstation Services and - Kerberos Authentication at Project Athena," Technical - Memorandum TM-424, MIT Laboratory for Computer Science - (February 1990). - -[LGDSR87] P. J. Levine, M. R. Gretzinger, J. M. Diaz, W. E. Som- - merfeld, and K. Raeburn, Section E.1: Service Manage- - ment System, M.I.T. Project Athena, Cambridge, Mas- - sachusetts (1987). - -[X509-88] CCITT, Recommendation X.509: The Directory Authentica- - tion Framework, December 1988. - -[Pat92]. J. Pato, Using Pre-Authentication to Avoid Password - Guessing Attacks, Open Software Foundation DCE Request - for Comments 26 (December 1992). - -[DES77] National Bureau of Standards, U.S. Department of Com- - merce, "Data Encryption Standard," Federal Information - Processing Standards Publication 46, Washington, DC - (1977). - -[DESM80] National Bureau of Standards, U.S. Department of Com- - merce, "DES Modes of Operation," Federal Information - Processing Standards Publication 81, Springfield, VA - (December 1980). - -[SG92] Stuart G. Stubblebine and Virgil D. Gligor, "On Message - Integrity in Cryptographic Protocols," in Proceedings - of the IEEE Symposium on Research in Security and - Privacy, Oakland, California (May 1992). - -[IS3309] International Organization for Standardization, "ISO - Information Processing Systems - Data Communication - - High-Level Data Link Control Procedure - Frame Struc- - ture," IS 3309 (October 1984). 3rd Edition. - -[MD4-92] R. Rivest, "The MD4 Message Digest Algorithm," RFC - 1320, MIT Laboratory for Computer Science (April - 1992). - -[MD5-92] R. Rivest, "The MD5 Message Digest Algorithm," RFC - 1321, MIT Laboratory for Computer Science (April - 1992). - -[KBC96] H. Krawczyk, M. Bellare, and R. Canetti, "HMAC: Keyed- - Hashing for Message Authentication," Working Draft - draft-ietf-ipsec-hmac-md5-01.txt, (August 1996). - -[Horowitz96] Horowitz, M., "Key Derivation for Authentication, - -Neuman, Ts'o, Kohl Expires: 18 May 1999 - - -INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 - - - Integrity, and Privacy", draft-horowitz-key-derivation-02.txt, - August 1998. - -[HorowitzB96] Horowitz, M., "Key Derivation for Kerberos V5", draft- - horowitz-kerb-key-derivation-01.txt, September 1998. - -[Krawczyk96] Krawczyk, H., Bellare, and M., Canetti, R., "HMAC: - Keyed-Hashing for Message Authentication", draft-ietf-ipsec-hmac- - md5-01.txt, August, 1996. - -A. Pseudo-code for protocol processing - -This appendix provides pseudo-code describing how the messages are to be -constructed and interpreted by clients and servers. - -A.1. KRB_AS_REQ generation - - request.pvno := protocol version; /* pvno = 5 */ - request.msg-type := message type; /* type = KRB_AS_REQ */ - - if(pa_enc_timestamp_required) then - request.padata.padata-type = PA-ENC-TIMESTAMP; - get system_time; - padata-body.patimestamp,pausec = system_time; - encrypt padata-body into request.padata.padata-value - using client.key; /* derived from password */ - endif - - body.kdc-options := users's preferences; - body.cname := user's name; - body.realm := user's realm; - body.sname := service's name; /* usually "krbtgt", "localrealm" */ - if (body.kdc-options.POSTDATED is set) then - body.from := requested starting time; - else - omit body.from; - endif - body.till := requested end time; - if (body.kdc-options.RENEWABLE is set) then - body.rtime := requested final renewal time; - endif - body.nonce := random_nonce(); - body.etype := requested etypes; - if (user supplied addresses) then - body.addresses := user's addresses; - else - omit body.addresses; - endif - omit body.enc-authorization-data; - request.req-body := body; - - kerberos := lookup(name of local kerberos server (or servers)); - send(packet,kerberos); - - wait(for response); - if (timed_out) then - retry or use alternate server; - endif - - -Neuman, Ts'o, Kohl Expires: 18 May 1999 - - -INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 - - -A.2. KRB_AS_REQ verification and KRB_AS_REP generation - - decode message into req; - - client := lookup(req.cname,req.realm); - server := lookup(req.sname,req.realm); - - get system_time; - kdc_time := system_time.seconds; - - if (!client) then - /* no client in Database */ - error_out(KDC_ERR_C_PRINCIPAL_UNKNOWN); - endif - if (!server) then - /* no server in Database */ - error_out(KDC_ERR_S_PRINCIPAL_UNKNOWN); - endif - - if(client.pa_enc_timestamp_required and - pa_enc_timestamp not present) then - error_out(KDC_ERR_PREAUTH_REQUIRED(PA_ENC_TIMESTAMP)); - endif - - if(pa_enc_timestamp present) then - decrypt req.padata-value into decrypted_enc_timestamp - using client.key; - using auth_hdr.authenticator.subkey; - if (decrypt_error()) then - error_out(KRB_AP_ERR_BAD_INTEGRITY); - if(decrypted_enc_timestamp is not within allowable skew) -then - error_out(KDC_ERR_PREAUTH_FAILED); - endif - if(decrypted_enc_timestamp and usec is replay) - error_out(KDC_ERR_PREAUTH_FAILED); - endif - add decrypted_enc_timestamp and usec to replay cache; - endif - - use_etype := first supported etype in req.etypes; - - if (no support for req.etypes) then - error_out(KDC_ERR_ETYPE_NOSUPP); - endif - - new_tkt.vno := ticket version; /* = 5 */ - new_tkt.sname := req.sname; - new_tkt.srealm := req.srealm; - reset all flags in new_tkt.flags; - - /* It should be noted that local policy may affect the */ - /* processing of any of these flags. For example, some */ - /* realms may refuse to issue renewable tickets */ - - if (req.kdc-options.FORWARDABLE is set) then - set new_tkt.flags.FORWARDABLE; - endif - if (req.kdc-options.PROXIABLE is set) then - set new_tkt.flags.PROXIABLE; - -Neuman, Ts'o, Kohl Expires: 18 May 1999 - - -INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 - - - endif - - if (req.kdc-options.ALLOW-POSTDATE is set) then - set new_tkt.flags.MAY-POSTDATE; - endif - if ((req.kdc-options.RENEW is set) or - (req.kdc-options.VALIDATE is set) or - (req.kdc-options.PROXY is set) or - (req.kdc-options.FORWARDED is set) or - (req.kdc-options.ENC-TKT-IN-SKEY is set)) then - error_out(KDC_ERR_BADOPTION); - endif - - new_tkt.session := random_session_key(); - new_tkt.cname := req.cname; - new_tkt.crealm := req.crealm; - new_tkt.transited := empty_transited_field(); - - new_tkt.authtime := kdc_time; - - if (req.kdc-options.POSTDATED is set) then - if (against_postdate_policy(req.from)) then - error_out(KDC_ERR_POLICY); - endif - set new_tkt.flags.POSTDATED; - set new_tkt.flags.INVALID; - new_tkt.starttime := req.from; - else - omit new_tkt.starttime; /* treated as authtime when omitted */ - endif - if (req.till = 0) then - till := infinity; - else - till := req.till; - endif - - new_tkt.endtime := min(till, - new_tkt.starttime+client.max_life, - new_tkt.starttime+server.max_life, - new_tkt.starttime+max_life_for_realm); - - if ((req.kdc-options.RENEWABLE-OK is set) and - (new_tkt.endtime < req.till)) then - /* we set the RENEWABLE option for later processing */ - set req.kdc-options.RENEWABLE; - req.rtime := req.till; - endif - - if (req.rtime = 0) then - rtime := infinity; - else - rtime := req.rtime; - endif - - if (req.kdc-options.RENEWABLE is set) then - set new_tkt.flags.RENEWABLE; - new_tkt.renew-till := min(rtime, - -new_tkt.starttime+client.max_rlife, - -new_tkt.starttime+server.max_rlife, - -Neuman, Ts'o, Kohl Expires: 18 May 1999 - - -INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 - - - -new_tkt.starttime+max_rlife_for_realm); - else - omit new_tkt.renew-till; /* only present if RENEWABLE */ - endif - - if (req.addresses) then - new_tkt.caddr := req.addresses; - else - omit new_tkt.caddr; - endif - - new_tkt.authorization_data := empty_authorization_data(); - - encode to-be-encrypted part of ticket into OCTET STRING; - new_tkt.enc-part := encrypt OCTET STRING - using etype_for_key(server.key), server.key, server.p_kvno; - - /* Start processing the response */ - - resp.pvno := 5; - resp.msg-type := KRB_AS_REP; - resp.cname := req.cname; - resp.crealm := req.realm; - resp.ticket := new_tkt; - - resp.key := new_tkt.session; - resp.last-req := fetch_last_request_info(client); - resp.nonce := req.nonce; - resp.key-expiration := client.expiration; - resp.flags := new_tkt.flags; - - resp.authtime := new_tkt.authtime; - resp.starttime := new_tkt.starttime; - resp.endtime := new_tkt.endtime; - - if (new_tkt.flags.RENEWABLE) then - resp.renew-till := new_tkt.renew-till; - endif - - resp.realm := new_tkt.realm; - resp.sname := new_tkt.sname; - - resp.caddr := new_tkt.caddr; - - encode body of reply into OCTET STRING; - - resp.enc-part := encrypt OCTET STRING - using use_etype, client.key, client.p_kvno; - send(resp); - -A.3. KRB_AS_REP verification - - decode response into resp; - - if (resp.msg-type = KRB_ERROR) then - if(error = KDC_ERR_PREAUTH_REQUIRED(PA_ENC_TIMESTAMP)) then - set pa_enc_timestamp_required; - goto KRB_AS_REQ; - endif - -Neuman, Ts'o, Kohl Expires: 18 May 1999 - - -INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 - - - process_error(resp); - return; - endif - - /* On error, discard the response, and zero the session key */ - /* from the response immediately */ - - key = get_decryption_key(resp.enc-part.kvno, resp.enc-part.etype, - resp.padata); - unencrypted part of resp := decode of decrypt of resp.enc-part - using resp.enc-part.etype and key; - zero(key); - - if (common_as_rep_tgs_rep_checks fail) then - destroy resp.key; - return error; - endif - - if near(resp.princ_exp) then - print(warning message); - endif - save_for_later(ticket,session,client,server,times,flags); - -A.4. KRB_AS_REP and KRB_TGS_REP common checks - - if (decryption_error() or - (req.cname != resp.cname) or - (req.realm != resp.crealm) or - (req.sname != resp.sname) or - (req.realm != resp.realm) or - (req.nonce != resp.nonce) or - (req.addresses != resp.caddr)) then - destroy resp.key; - return KRB_AP_ERR_MODIFIED; - endif - - /* make sure no flags are set that shouldn't be, and that all that -*/ - /* should be are set -*/ - if (!check_flags_for_compatability(req.kdc-options,resp.flags)) then - destroy resp.key; - return KRB_AP_ERR_MODIFIED; - endif - - if ((req.from = 0) and - (resp.starttime is not within allowable skew)) then - destroy resp.key; - return KRB_AP_ERR_SKEW; - endif - if ((req.from != 0) and (req.from != resp.starttime)) then - destroy resp.key; - return KRB_AP_ERR_MODIFIED; - endif - if ((req.till != 0) and (resp.endtime > req.till)) then - destroy resp.key; - return KRB_AP_ERR_MODIFIED; - endif - - if ((req.kdc-options.RENEWABLE is set) and - (req.rtime != 0) and (resp.renew-till > req.rtime)) then - -Neuman, Ts'o, Kohl Expires: 18 May 1999 - - -INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 - - - destroy resp.key; - return KRB_AP_ERR_MODIFIED; - endif - if ((req.kdc-options.RENEWABLE-OK is set) and - (resp.flags.RENEWABLE) and - (req.till != 0) and - (resp.renew-till > req.till)) then - destroy resp.key; - return KRB_AP_ERR_MODIFIED; - endif - -A.5. KRB_TGS_REQ generation - - /* Note that make_application_request might have to recursivly -*/ - /* call this routine to get the appropriate ticket-granting ticket -*/ - - request.pvno := protocol version; /* pvno = 5 */ - request.msg-type := message type; /* type = KRB_TGS_REQ */ - - body.kdc-options := users's preferences; - /* If the TGT is not for the realm of the end-server */ - /* then the sname will be for a TGT for the end-realm */ - /* and the realm of the requested ticket (body.realm) */ - /* will be that of the TGS to which the TGT we are */ - /* sending applies */ - body.sname := service's name; - body.realm := service's realm; - - if (body.kdc-options.POSTDATED is set) then - body.from := requested starting time; - else - omit body.from; - endif - body.till := requested end time; - if (body.kdc-options.RENEWABLE is set) then - body.rtime := requested final renewal time; - endif - body.nonce := random_nonce(); - body.etype := requested etypes; - if (user supplied addresses) then - body.addresses := user's addresses; - else - omit body.addresses; - endif - - body.enc-authorization-data := user-supplied data; - if (body.kdc-options.ENC-TKT-IN-SKEY) then - body.additional-tickets_ticket := second TGT; - endif - - request.req-body := body; - check := generate_checksum (req.body,checksumtype); - - request.padata[0].padata-type := PA-TGS-REQ; - request.padata[0].padata-value := create a KRB_AP_REQ using - the TGT and checksum - - /* add in any other padata as required/supplied */ - kerberos := lookup(name of local kerberose server (or servers)); - -Neuman, Ts'o, Kohl Expires: 18 May 1999 - - -INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 - - - send(packet,kerberos); - - wait(for response); - if (timed_out) then - retry or use alternate server; - endif - -A.6. KRB_TGS_REQ verification and KRB_TGS_REP generation - - /* note that reading the application request requires first - determining the server for which a ticket was issued, and choosing -the - correct key for decryption. The name of the server appears in the - plaintext part of the ticket. */ - - if (no KRB_AP_REQ in req.padata) then - error_out(KDC_ERR_PADATA_TYPE_NOSUPP); - endif - verify KRB_AP_REQ in req.padata; - - /* Note that the realm in which the Kerberos server is operating is - determined by the instance from the ticket-granting ticket. The -realm - in the ticket-granting ticket is the realm under which the ticket - granting ticket was issued. It is possible for a single Kerberos - server to support more than one realm. */ - - auth_hdr := KRB_AP_REQ; - tgt := auth_hdr.ticket; - - if (tgt.sname is not a TGT for local realm and is not req.sname) -then - error_out(KRB_AP_ERR_NOT_US); - - realm := realm_tgt_is_for(tgt); - - decode remainder of request; - - if (auth_hdr.authenticator.cksum is missing) then - error_out(KRB_AP_ERR_INAPP_CKSUM); - endif - - if (auth_hdr.authenticator.cksum type is not supported) then - error_out(KDC_ERR_SUMTYPE_NOSUPP); - endif - if (auth_hdr.authenticator.cksum is not both collision-proof and -keyed) then - error_out(KRB_AP_ERR_INAPP_CKSUM); - endif - - set computed_checksum := checksum(req); - if (computed_checksum != auth_hdr.authenticatory.cksum) then - error_out(KRB_AP_ERR_MODIFIED); - endif - - server := lookup(req.sname,realm); - - if (!server) then - if (is_foreign_tgt_name(req.sname)) then - server := best_intermediate_tgs(req.sname); - else - /* no server in Database */ - error_out(KDC_ERR_S_PRINCIPAL_UNKNOWN); - -Neuman, Ts'o, Kohl Expires: 18 May 1999 - - -INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 - - - endif - endif - - session := generate_random_session_key(); - - use_etype := first supported etype in req.etypes; - - if (no support for req.etypes) then - error_out(KDC_ERR_ETYPE_NOSUPP); - endif - - new_tkt.vno := ticket version; /* = 5 */ - new_tkt.sname := req.sname; - new_tkt.srealm := realm; - reset all flags in new_tkt.flags; - - /* It should be noted that local policy may affect the */ - /* processing of any of these flags. For example, some */ - /* realms may refuse to issue renewable tickets */ - - new_tkt.caddr := tgt.caddr; - resp.caddr := NULL; /* We only include this if they change */ - if (req.kdc-options.FORWARDABLE is set) then - if (tgt.flags.FORWARDABLE is reset) then - error_out(KDC_ERR_BADOPTION); - endif - set new_tkt.flags.FORWARDABLE; - endif - if (req.kdc-options.FORWARDED is set) then - if (tgt.flags.FORWARDABLE is reset) then - error_out(KDC_ERR_BADOPTION); - endif - set new_tkt.flags.FORWARDED; - new_tkt.caddr := req.addresses; - resp.caddr := req.addresses; - endif - if (tgt.flags.FORWARDED is set) then - set new_tkt.flags.FORWARDED; - endif - - if (req.kdc-options.PROXIABLE is set) then - if (tgt.flags.PROXIABLE is reset) - error_out(KDC_ERR_BADOPTION); - endif - set new_tkt.flags.PROXIABLE; - endif - if (req.kdc-options.PROXY is set) then - if (tgt.flags.PROXIABLE is reset) then - error_out(KDC_ERR_BADOPTION); - endif - set new_tkt.flags.PROXY; - new_tkt.caddr := req.addresses; - resp.caddr := req.addresses; - endif - - if (req.kdc-options.ALLOW-POSTDATE is set) then - if (tgt.flags.MAY-POSTDATE is reset) - error_out(KDC_ERR_BADOPTION); - endif - -Neuman, Ts'o, Kohl Expires: 18 May 1999 - - -INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 - - - set new_tkt.flags.MAY-POSTDATE; - endif - if (req.kdc-options.POSTDATED is set) then - if (tgt.flags.MAY-POSTDATE is reset) then - error_out(KDC_ERR_BADOPTION); - endif - set new_tkt.flags.POSTDATED; - set new_tkt.flags.INVALID; - if (against_postdate_policy(req.from)) then - error_out(KDC_ERR_POLICY); - endif - new_tkt.starttime := req.from; - endif - - if (req.kdc-options.VALIDATE is set) then - if (tgt.flags.INVALID is reset) then - error_out(KDC_ERR_POLICY); - endif - if (tgt.starttime > kdc_time) then - error_out(KRB_AP_ERR_NYV); - endif - if (check_hot_list(tgt)) then - error_out(KRB_AP_ERR_REPEAT); - endif - tkt := tgt; - reset new_tkt.flags.INVALID; - endif - - if (req.kdc-options.(any flag except ENC-TKT-IN-SKEY, RENEW, - and those already processed) is set) then - error_out(KDC_ERR_BADOPTION); - endif - - new_tkt.authtime := tgt.authtime; - - if (req.kdc-options.RENEW is set) then - /* Note that if the endtime has already passed, the ticket would -*/ - /* have been rejected in the initial authentication stage, so -*/ - /* there is no need to check again here -*/ - if (tgt.flags.RENEWABLE is reset) then - error_out(KDC_ERR_BADOPTION); - endif - if (tgt.renew-till < kdc_time) then - error_out(KRB_AP_ERR_TKT_EXPIRED); - endif - tkt := tgt; - new_tkt.starttime := kdc_time; - old_life := tgt.endttime - tgt.starttime; - new_tkt.endtime := min(tgt.renew-till, - new_tkt.starttime + old_life); - else - new_tkt.starttime := kdc_time; - if (req.till = 0) then - till := infinity; - else - till := req.till; - endif - - new_tkt.endtime := min(till, - -Neuman, Ts'o, Kohl Expires: 18 May 1999 - - -INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 - - - new_tkt.starttime+client.max_life, - new_tkt.starttime+server.max_life, - new_tkt.starttime+max_life_for_realm, - tgt.endtime); - - if ((req.kdc-options.RENEWABLE-OK is set) and - (new_tkt.endtime < req.till) and - (tgt.flags.RENEWABLE is set) then - /* we set the RENEWABLE option for later processing -*/ - set req.kdc-options.RENEWABLE; - req.rtime := min(req.till, tgt.renew-till); - endif - endif - - if (req.rtime = 0) then - rtime := infinity; - else - rtime := req.rtime; - endif - - if ((req.kdc-options.RENEWABLE is set) and - (tgt.flags.RENEWABLE is set)) then - set new_tkt.flags.RENEWABLE; - new_tkt.renew-till := min(rtime, - -new_tkt.starttime+client.max_rlife, - -new_tkt.starttime+server.max_rlife, - -new_tkt.starttime+max_rlife_for_realm, - tgt.renew-till); - else - new_tkt.renew-till := OMIT; /* leave the renew-till field -out */ - endif - if (req.enc-authorization-data is present) then - decrypt req.enc-authorization-data into -decrypted_authorization_data - using auth_hdr.authenticator.subkey; - if (decrypt_error()) then - error_out(KRB_AP_ERR_BAD_INTEGRITY); - endif - endif - new_tkt.authorization_data := req.auth_hdr.ticket.authorization_data -+ - decrypted_authorization_data; - - new_tkt.key := session; - new_tkt.crealm := tgt.crealm; - new_tkt.cname := req.auth_hdr.ticket.cname; - - if (realm_tgt_is_for(tgt) := tgt.realm) then - /* tgt issued by local realm */ - new_tkt.transited := tgt.transited; - else - /* was issued for this realm by some other realm */ - if (tgt.transited.tr-type not supported) then - error_out(KDC_ERR_TRTYPE_NOSUPP); - endif - new_tkt.transited := compress_transited(tgt.transited + -tgt.realm) - /* Don't check tranited field if TGT for foreign realm, - * or requested not to check */ - if (is_not_foreign_tgt_name(new_tkt.server) - && req.kdc-options.DISABLE-TRANSITED-CHECK not set) then - - -Neuman, Ts'o, Kohl Expires: 18 May 1999 - - -INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 - - - /* Check it, so end-server does not have to - * but don't fail, end-server may still accept it */ - if (check_transited_field(new_tkt.transited) == OK) - set new_tkt.flags.TRANSITED-POLICY-CHECKED; - endif - endif - endif - - encode encrypted part of new_tkt into OCTET STRING; - if (req.kdc-options.ENC-TKT-IN-SKEY is set) then - if (server not specified) then - server = req.second_ticket.client; - endif - if ((req.second_ticket is not a TGT) or - (req.second_ticket.client != server)) then - error_out(KDC_ERR_POLICY); - endif - - new_tkt.enc-part := encrypt OCTET STRING using - using etype_for_key(second-ticket.key), -second-ticket.key; - else - new_tkt.enc-part := encrypt OCTET STRING - using etype_for_key(server.key), server.key, -server.p_kvno; - endif - - resp.pvno := 5; - resp.msg-type := KRB_TGS_REP; - resp.crealm := tgt.crealm; - resp.cname := tgt.cname; - resp.ticket := new_tkt; - - resp.key := session; - resp.nonce := req.nonce; - resp.last-req := fetch_last_request_info(client); - resp.flags := new_tkt.flags; - - resp.authtime := new_tkt.authtime; - resp.starttime := new_tkt.starttime; - resp.endtime := new_tkt.endtime; - - omit resp.key-expiration; - - resp.sname := new_tkt.sname; - resp.realm := new_tkt.realm; - - if (new_tkt.flags.RENEWABLE) then - resp.renew-till := new_tkt.renew-till; - endif - - encode body of reply into OCTET STRING; - - if (req.padata.authenticator.subkey) - resp.enc-part := encrypt OCTET STRING using use_etype, - req.padata.authenticator.subkey; - else resp.enc-part := encrypt OCTET STRING using use_etype, tgt.key; - - send(resp); - -A.7. KRB_TGS_REP verification - -Neuman, Ts'o, Kohl Expires: 18 May 1999 - - -INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 - - - - decode response into resp; - - if (resp.msg-type = KRB_ERROR) then - process_error(resp); - return; - endif - - /* On error, discard the response, and zero the session key from - the response immediately */ - - if (req.padata.authenticator.subkey) - unencrypted part of resp := decode of decrypt of -resp.enc-part - using resp.enc-part.etype and subkey; - else unencrypted part of resp := decode of decrypt of resp.enc-part - using resp.enc-part.etype and tgt's session -key; - if (common_as_rep_tgs_rep_checks fail) then - destroy resp.key; - return error; - endif - - check authorization_data as necessary; - save_for_later(ticket,session,client,server,times,flags); - -A.8. Authenticator generation - - body.authenticator-vno := authenticator vno; /* = 5 */ - body.cname, body.crealm := client name; - if (supplying checksum) then - body.cksum := checksum; - endif - get system_time; - body.ctime, body.cusec := system_time; - if (selecting sub-session key) then - select sub-session key; - body.subkey := sub-session key; - endif - if (using sequence numbers) then - select initial sequence number; - body.seq-number := initial sequence; - endif - -A.9. KRB_AP_REQ generation - - obtain ticket and session_key from cache; - - packet.pvno := protocol version; /* 5 */ - packet.msg-type := message type; /* KRB_AP_REQ */ - - if (desired(MUTUAL_AUTHENTICATION)) then - set packet.ap-options.MUTUAL-REQUIRED; - else - reset packet.ap-options.MUTUAL-REQUIRED; - endif - if (using session key for ticket) then - set packet.ap-options.USE-SESSION-KEY; - else - reset packet.ap-options.USE-SESSION-KEY; - endif - -Neuman, Ts'o, Kohl Expires: 18 May 1999 - - -INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 - - - - packet.ticket := ticket; /* ticket */ - generate authenticator; - encode authenticator into OCTET STRING; - encrypt OCTET STRING into packet.authenticator using session_key; - -A.10. KRB_AP_REQ verification - - receive packet; - if (packet.pvno != 5) then - either process using other protocol spec - or error_out(KRB_AP_ERR_BADVERSION); - endif - if (packet.msg-type != KRB_AP_REQ) then - error_out(KRB_AP_ERR_MSG_TYPE); - endif - if (packet.ticket.tkt_vno != 5) then - either process using other protocol spec - or error_out(KRB_AP_ERR_BADVERSION); - endif - if (packet.ap_options.USE-SESSION-KEY is set) then - retrieve session key from ticket-granting ticket for - packet.ticket.{sname,srealm,enc-part.etype}; - else - retrieve service key for - packet.ticket.{sname,srealm,enc-part.etype,enc-part.skvno}; - endif - if (no_key_available) then - if (cannot_find_specified_skvno) then - error_out(KRB_AP_ERR_BADKEYVER); - else - error_out(KRB_AP_ERR_NOKEY); - endif - endif - decrypt packet.ticket.enc-part into decr_ticket using retrieved key; - if (decryption_error()) then - error_out(KRB_AP_ERR_BAD_INTEGRITY); - endif - decrypt packet.authenticator into decr_authenticator - using decr_ticket.key; - if (decryption_error()) then - error_out(KRB_AP_ERR_BAD_INTEGRITY); - endif - if (decr_authenticator.{cname,crealm} != - decr_ticket.{cname,crealm}) then - error_out(KRB_AP_ERR_BADMATCH); - endif - if (decr_ticket.caddr is present) then - if (sender_address(packet) is not in decr_ticket.caddr) then - error_out(KRB_AP_ERR_BADADDR); - endif - elseif (application requires addresses) then - error_out(KRB_AP_ERR_BADADDR); - endif - if (not in_clock_skew(decr_authenticator.ctime, - decr_authenticator.cusec)) then - error_out(KRB_AP_ERR_SKEW); - endif - if (repeated(decr_authenticator.{ctime,cusec,cname,crealm})) then - -Neuman, Ts'o, Kohl Expires: 18 May 1999 - - -INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 - - - error_out(KRB_AP_ERR_REPEAT); - endif - save_identifier(decr_authenticator.{ctime,cusec,cname,crealm}); - get system_time; - if ((decr_ticket.starttime-system_time > CLOCK_SKEW) or - (decr_ticket.flags.INVALID is set)) then - /* it hasn't yet become valid */ - error_out(KRB_AP_ERR_TKT_NYV); - endif - if (system_time-decr_ticket.endtime > CLOCK_SKEW) then - error_out(KRB_AP_ERR_TKT_EXPIRED); - endif - if (decr_ticket.transited) then - /* caller may ignore the TRANSITED-POLICY-CHECKED and do - * check anyway */ - if (decr_ticket.flags.TRANSITED-POLICY-CHECKED not set) then - if (check_transited_field(decr_ticket.transited) then - error_out(KDC_AP_PATH_NOT_ACCPETED); - endif - endif - endif - /* caller must check decr_ticket.flags for any pertinent details */ - return(OK, decr_ticket, packet.ap_options.MUTUAL-REQUIRED); - -A.11. KRB_AP_REP generation - - packet.pvno := protocol version; /* 5 */ - packet.msg-type := message type; /* KRB_AP_REP */ - - body.ctime := packet.ctime; - body.cusec := packet.cusec; - if (selecting sub-session key) then - select sub-session key; - body.subkey := sub-session key; - endif - if (using sequence numbers) then - select initial sequence number; - body.seq-number := initial sequence; - endif - - encode body into OCTET STRING; - - select encryption type; - encrypt OCTET STRING into packet.enc-part; - -A.12. KRB_AP_REP verification - - receive packet; - if (packet.pvno != 5) then - either process using other protocol spec - or error_out(KRB_AP_ERR_BADVERSION); - endif - if (packet.msg-type != KRB_AP_REP) then - error_out(KRB_AP_ERR_MSG_TYPE); - endif - cleartext := decrypt(packet.enc-part) using ticket's session key; - if (decryption_error()) then - error_out(KRB_AP_ERR_BAD_INTEGRITY); - endif - -Neuman, Ts'o, Kohl Expires: 18 May 1999 - - -INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 - - - if (cleartext.ctime != authenticator.ctime) then - error_out(KRB_AP_ERR_MUT_FAIL); - endif - if (cleartext.cusec != authenticator.cusec) then - error_out(KRB_AP_ERR_MUT_FAIL); - endif - if (cleartext.subkey is present) then - save cleartext.subkey for future use; - endif - if (cleartext.seq-number is present) then - save cleartext.seq-number for future verifications; - endif - return(AUTHENTICATION_SUCCEEDED); - -A.13. KRB_SAFE generation - - collect user data in buffer; - - /* assemble packet: */ - packet.pvno := protocol version; /* 5 */ - packet.msg-type := message type; /* KRB_SAFE */ - - body.user-data := buffer; /* DATA */ - if (using timestamp) then - get system_time; - body.timestamp, body.usec := system_time; - endif - if (using sequence numbers) then - body.seq-number := sequence number; - endif - body.s-address := sender host addresses; - if (only one recipient) then - body.r-address := recipient host address; - endif - checksum.cksumtype := checksum type; - compute checksum over body; - checksum.checksum := checksum value; /* checksum.checksum */ - packet.cksum := checksum; - packet.safe-body := body; - -A.14. KRB_SAFE verification - - receive packet; - if (packet.pvno != 5) then - either process using other protocol spec - or error_out(KRB_AP_ERR_BADVERSION); - endif - if (packet.msg-type != KRB_SAFE) then - error_out(KRB_AP_ERR_MSG_TYPE); - endif - if (packet.checksum.cksumtype is not both collision-proof and keyed) -then - error_out(KRB_AP_ERR_INAPP_CKSUM); - endif - if (safe_priv_common_checks_ok(packet)) then - set computed_checksum := checksum(packet.body); - if (computed_checksum != packet.checksum) then - error_out(KRB_AP_ERR_MODIFIED); - endif - return (packet, PACKET_IS_GENUINE); - -Neuman, Ts'o, Kohl Expires: 18 May 1999 - - -INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 - - - else - return common_checks_error; - endif - -A.15. KRB_SAFE and KRB_PRIV common checks - - if (packet.s-address != O/S_sender(packet)) then - /* O/S report of sender not who claims to have sent it */ - error_out(KRB_AP_ERR_BADADDR); - endif - if ((packet.r-address is present) and - (packet.r-address != local_host_address)) then - /* was not sent to proper place */ - error_out(KRB_AP_ERR_BADADDR); - endif - if (((packet.timestamp is present) and - (not in_clock_skew(packet.timestamp,packet.usec))) or - (packet.timestamp is not present and timestamp expected)) then - error_out(KRB_AP_ERR_SKEW); - endif - if (repeated(packet.timestamp,packet.usec,packet.s-address)) then - error_out(KRB_AP_ERR_REPEAT); - endif - - if (((packet.seq-number is present) and - ((not in_sequence(packet.seq-number)))) or - (packet.seq-number is not present and sequence expected)) then - error_out(KRB_AP_ERR_BADORDER); - endif - if (packet.timestamp not present and packet.seq-number not present) -then - error_out(KRB_AP_ERR_MODIFIED); - endif - - save_identifier(packet.{timestamp,usec,s-address}, - sender_principal(packet)); - - return PACKET_IS_OK; - -A.16. KRB_PRIV generation - - collect user data in buffer; - - /* assemble packet: */ - packet.pvno := protocol version; /* 5 */ - packet.msg-type := message type; /* KRB_PRIV */ - - packet.enc-part.etype := encryption type; - - body.user-data := buffer; - if (using timestamp) then - get system_time; - body.timestamp, body.usec := system_time; - endif - if (using sequence numbers) then - body.seq-number := sequence number; - endif - body.s-address := sender host addresses; - if (only one recipient) then - body.r-address := recipient host address; - -Neuman, Ts'o, Kohl Expires: 18 May 1999 - - -INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 - - - endif - - encode body into OCTET STRING; - - select encryption type; - encrypt OCTET STRING into packet.enc-part.cipher; - -A.17. KRB_PRIV verification - - receive packet; - if (packet.pvno != 5) then - either process using other protocol spec - or error_out(KRB_AP_ERR_BADVERSION); - endif - if (packet.msg-type != KRB_PRIV) then - error_out(KRB_AP_ERR_MSG_TYPE); - endif - - cleartext := decrypt(packet.enc-part) using negotiated key; - if (decryption_error()) then - error_out(KRB_AP_ERR_BAD_INTEGRITY); - endif - - if (safe_priv_common_checks_ok(cleartext)) then - return(cleartext.DATA, PACKET_IS_GENUINE_AND_UNMODIFIED); - else - return common_checks_error; - endif - -A.18. KRB_CRED generation - - invoke KRB_TGS; /* obtain tickets to be provided to peer */ - - /* assemble packet: */ - packet.pvno := protocol version; /* 5 */ - packet.msg-type := message type; /* KRB_CRED */ - - for (tickets[n] in tickets to be forwarded) do - packet.tickets[n] = tickets[n].ticket; - done - - packet.enc-part.etype := encryption type; - - for (ticket[n] in tickets to be forwarded) do - body.ticket-info[n].key = tickets[n].session; - body.ticket-info[n].prealm = tickets[n].crealm; - body.ticket-info[n].pname = tickets[n].cname; - body.ticket-info[n].flags = tickets[n].flags; - body.ticket-info[n].authtime = tickets[n].authtime; - body.ticket-info[n].starttime = tickets[n].starttime; - body.ticket-info[n].endtime = tickets[n].endtime; - body.ticket-info[n].renew-till = tickets[n].renew-till; - body.ticket-info[n].srealm = tickets[n].srealm; - body.ticket-info[n].sname = tickets[n].sname; - body.ticket-info[n].caddr = tickets[n].caddr; - done - - get system_time; - body.timestamp, body.usec := system_time; - -Neuman, Ts'o, Kohl Expires: 18 May 1999 - - -INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 - - - - if (using nonce) then - body.nonce := nonce; - endif - - if (using s-address) then - body.s-address := sender host addresses; - endif - if (limited recipients) then - body.r-address := recipient host address; - endif - - encode body into OCTET STRING; - - select encryption type; - encrypt OCTET STRING into packet.enc-part.cipher - using negotiated encryption key; - -A.19. KRB_CRED verification - - receive packet; - if (packet.pvno != 5) then - either process using other protocol spec - or error_out(KRB_AP_ERR_BADVERSION); - endif - if (packet.msg-type != KRB_CRED) then - error_out(KRB_AP_ERR_MSG_TYPE); - endif - - cleartext := decrypt(packet.enc-part) using negotiated key; - if (decryption_error()) then - error_out(KRB_AP_ERR_BAD_INTEGRITY); - endif - if ((packet.r-address is present or required) and - (packet.s-address != O/S_sender(packet)) then - /* O/S report of sender not who claims to have sent it */ - error_out(KRB_AP_ERR_BADADDR); - endif - if ((packet.r-address is present) and - (packet.r-address != local_host_address)) then - /* was not sent to proper place */ - error_out(KRB_AP_ERR_BADADDR); - endif - if (not in_clock_skew(packet.timestamp,packet.usec)) then - error_out(KRB_AP_ERR_SKEW); - endif - if (repeated(packet.timestamp,packet.usec,packet.s-address)) then - error_out(KRB_AP_ERR_REPEAT); - endif - if (packet.nonce is required or present) and - (packet.nonce != expected-nonce) then - error_out(KRB_AP_ERR_MODIFIED); - endif - - for (ticket[n] in tickets that were forwarded) do - save_for_later(ticket[n],key[n],principal[n], - server[n],times[n],flags[n]); - return - - -Neuman, Ts'o, Kohl Expires: 18 May 1999 - - -INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 - - -A.20. KRB_ERROR generation - - /* assemble packet: */ - packet.pvno := protocol version; /* 5 */ - packet.msg-type := message type; /* KRB_ERROR */ - - get system_time; - packet.stime, packet.susec := system_time; - packet.realm, packet.sname := server name; - - if (client time available) then - packet.ctime, packet.cusec := client_time; - endif - packet.error-code := error code; - if (client name available) then - packet.cname, packet.crealm := client name; - endif - if (error text available) then - packet.e-text := error text; - endif - if (error data available) then - packet.e-data := error data; - endif - -B. Definition of common authorization data elements - -This appendix contains the definitions of common authorization data -elements. These common authorization data elements are recursivly defined, -meaning the ad-data for these types will itself contain a sequence of -authorization data whose interpretation is affected by the encapsulating -element. Depending on the meaning of the encapsulating element, the -encapsulated elements may be ignored, might be interpreted as issued -directly by the KDC, or they might be stored in a separate plaintext part -of the ticket. The types of the encapsulating elements are specified as -part of the Kerberos specification because the behavior based on these -values should be understood across implementations whereas other elements -need only be understood by the applications which they affect. - -In the definitions that follow, the value of the ad-type for the element -will be specified in the subsection number, and the value of the ad-data -will be as shown in the ASN.1 structure that follows the subsection -heading. - -B.1. KDC Issued - -AD-KDCIssued SEQUENCE { - ad-checksum[0] Checksum, - i-realm[1] Realm OPTIONAL, - i-sname[2] PrincipalName OPTIONAL, - elements[3] AuthorizationData. -} - -ad-checksum - A checksum over the elements field using a cryptographic checksum - method that is identical to the checksum used to protect the ticket - itself (i.e. using the same hash function and the same encryption - algorithm used to encrypt the ticket) and using a key derived from the - same key used to protect the ticket. -i-realm, i-sname - -Neuman, Ts'o, Kohl Expires: 18 May 1999 - - -INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 - - - The name of the issuing principal if different from the KDC itself. - This field would be used when the KDC can verify the authenticity of - elements signed by the issuing principal and it allows this KDC to - notify the application server of the validity of those elements. -elements - A sequence of authorization data elements issued by the KDC. - -The KDC-issued ad-data field is intended to provide a means for Kerberos -principal credentials to embed within themselves privilege attributes and -other mechanisms for positive authorization, amplifying the priveleges of -the principal beyond what can be done using a credentials without such an -a-data element. - -This can not be provided without this element because the definition of the -authorization-data field allows elements to be added at will by the bearer -of a TGT at the time that they request service tickets and elements may -also be added to a delegated ticket by inclusion in the authenticator. - -For KDC-issued elements this is prevented because the elements are signed -by the KDC by including a checksum encrypted using the server's key (the -same key used to encrypt the ticket - or a key derived from that key). -Elements encapsulated with in the KDC-issued element will be ignored by the -application server if this "signature" is not present. Further, elements -encapsulated within this element from a ticket granting ticket may be -interpreted by the KDC, and used as a basis according to policy for -including new signed elements within derivative tickets, but they will not -be copied to a derivative ticket directly. If they are copied directly to a -derivative ticket by a KDC that is not aware of this element, the signature -will not be correct for the application ticket elements, and the field will -be ignored by the application server. - -This element and the elements it encapulates may be safely ignored by -applications, application servers, and KDCs that do not implement this -element. - -B.2. Intended for server - -AD-INTENDED-FOR-SERVER SEQUENCE { - intended-server[0] SEQUENCE OF PrincipalName - elements[1] AuthorizationData -} - -AD elements encapsulated within the intended-for-server element may be -ignored if the application server is not in the list of principal names of -intended servers. Further, a KDC issuing a ticket for an application server -can remove this element if the application server is not in the list of -intended servers. - -Application servers should check for their principal name in the -intended-server field of this element. If their principal name is not -found, this element should be ignored. If found, then the encapsulated -elements should be evaluated in the same manner as if they were present in -the top level authorization data field. Applications and application -servers that do not implement this element should reject tickets that -contain authorization data elements of this type. - -B.3. Intended for application class - -AD-INTENDED-FOR-APPLICATION-CLASS SEQUENCE { intended-application-class[0] - -Neuman, Ts'o, Kohl Expires: 18 May 1999 - - -INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 - - -SEQUENCE OF GeneralString elements[1] AuthorizationData } AD elements -encapsulated within the intended-for-application-class element may be -ignored if the application server is not in one of the named classes of -application servers. Examples of application server classes include -"FILESYSTEM", and other kinds of servers. - -This element and the elements it encapulates may be safely ignored by -applications, application servers, and KDCs that do not implement this -element. - -B.4. If relevant - -AD-IF-RELEVANT AuthorizationData - -AD elements encapsulated within the if-relevant element are intended for -interpretation only by application servers that understand the particular -ad-type of the embedded element. Application servers that do not understand -the type of an element embedded within the if-relevant element may ignore -the uninterpretable element. This element promotes interoperability across -implementations which may have local extensions for authorization. - -B.5. And-Or - -AD-AND-OR SEQUENCE { - condition-count[0] INTEGER, - elements[1] AuthorizationData -} - -When restrictive AD elements encapsulated within the and-or element are -encountered, only the number specified in condition-count of the -encapsulated conditions must be met in order to satisfy this element. This -element may be used to implement an "or" operation by setting the -condition-count field to 1, and it may specify an "and" operation by -setting the condition count to the number of embedded elements. Application -servers that do not implement this element must reject tickets that contain -authorization data elements of this type. - -B.6. Mandatory ticket extensions - -AD-Mandatory-Ticket-Extensions Checksum - -An authorization data element of type mandatory-ticket-extensions specifies -a collision-proof checksum using the same hash algorithm used to protect -the integrity of the ticket itself. This checksum will be calculated over -an individual extension field. If there are more than one extension, -multiple Mandatory-Ticket-Extensions authorization data elements may be -present, each with a checksum for a different extension field. This -restriction indicates that the ticket should not be accepted if a ticket -extension is not present in the ticket for which the checksum does not -match that checksum specified in the authorization data element. -Application servers that do not implement this element must reject tickets -that contain authorization data elements of this type. - -B.7. Authorization Data in ticket extensions - -AD-IN-Ticket-Extensions Checksum - -An authorization data element of type in-ticket-extensions specifies a -collision-proof checksum using the same hash algorithm used to protect the - -Neuman, Ts'o, Kohl Expires: 18 May 1999 - - -INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 - - -integrity of the ticket itself. This checksum is calculated over a separate -external AuthorizationData field carried in the ticket extensions. -Application servers that do not implement this element must reject tickets -that contain authorization data elements of this type. Application servers -that do implement this element will search the ticket extensions for -authorization data fields, calculate the specified checksum over each -authorization data field and look for one matching the checksum in this -in-ticket-extensions element. If not found, then the ticket must be -rejected. If found, the corresponding authorization data elements will be -interpreted in the same manner as if they were contained in the top level -authorization data field. - -Note that if multiple external authorization data fields are present in a -ticket, each will have a corresponding element of type in-ticket-extensions -in the top level authorization data field, and the external entries will be -linked to the corresponding element by their checksums. - -C. Definition of common ticket extensions - -This appendix contains the definitions of common ticket extensions. Support -for these extensions is optional. However, certain extensions have -associated authorization data elements that may require rejection of a -ticket containing an extension by application servers that do not implement -the particular extension. Other extensions have been defined beyond those -described in this specification. Such extensions are described elswhere and -for some of those extensions the reserved number may be found in the list -of constants. - -It is known that older versions of Kerberos did not support this field, and -that some clients will strip this field from a ticket when they parse and -then reassemble a ticket as it is passed to the application servers. The -presence of the extension will not break such clients, but any functionaly -dependent on the extensions will not work when such tickets are handled by -old clients. In such situations, some implementation may use alternate -methods to transmit the information in the extensions field. - -C.1. Null ticket extension - -TE-NullExtension OctetString -- The empty Octet String - -The te-data field in the null ticket extension is an octet string of lenght -zero. This extension may be included in a ticket granting ticket so that -the KDC can determine on presentation of the ticket granting ticket whether -the client software will strip the extensions field. - -C.2. External Authorization Data - -TE-ExternalAuthorizationData AuthorizationData - -The te-data field in the external authorization data ticket extension is -field of type AuthorizationData containing one or more authorization data -elements. If present, a corresponding authorization data element will be -present in the primary authorization data for the ticket and that element -will contain a checksum of the external authorization data ticket -extension. - ------------------------------------------------------------------------ -[TM] Project Athena, Athena, and Kerberos are trademarks of the -Massachusetts Institute of Technology (MIT). No commercial use of these -trademarks may be made without prior written permission of MIT. - -Neuman, Ts'o, Kohl Expires: 18 May 1999 - - -INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 - - - -[1] Note, however, that many applications use Kerberos' functions only upon -the initiation of a stream-based network connection. Unless an application -subsequently provides integrity protection for the data stream, the -identity verification applies only to the initiation of the connection, and -does not guarantee that subsequent messages on the connection originate -from the same principal. - -[2] Secret and private are often used interchangeably in the literature. In -our usage, it takes two (or more) to share a secret, thus a shared DES key -is a secret key. Something is only private when no one but its owner knows -it. Thus, in public key cryptosystems, one has a public and a private key. - -[3] Of course, with appropriate permission the client could arrange -registration of a separately-named prin- cipal in a remote realm, and -engage in normal exchanges with that realm's services. However, for even -small numbers of clients this becomes cumbersome, and more automatic -methods as described here are necessary. - -[4] Though it is permissible to request or issue tick- ets with no network -addresses specified. - -[5] The password-changing request must not be honored unless the requester -can provide the old password (the user's current secret key). Otherwise, it -would be possible for someone to walk up to an unattended ses- sion and -change another user's password. - -[6] To authenticate a user logging on to a local system, the credentials -obtained in the AS exchange may first be used in a TGS exchange to obtain -credentials for a local server. Those credentials must then be verified by -a local server through successful completion of the Client/Server exchange. - -[7] "Random" means that, among other things, it should be impossible to -guess the next session key based on knowledge of past session keys. This -can only be achieved in a pseudo-random number generator if it is based on -cryptographic principles. It is more desirable to use a truly random number -generator, such as one based on measurements of random physical phenomena. - -[8] Tickets contain both an encrypted and unencrypted portion, so cleartext -here refers to the entire unit, which can be copied from one message and -replayed in another without any cryptographic skill. - -[9] Note that this can make applications based on unreliable transports -difficult to code correctly. If the transport might deliver duplicated -messages, either a new authenticator must be generated for each retry, or -the application server must match requests and replies and replay the first -reply in response to a detected duplicate. - -[10] This is used for user-to-user authentication as described in [8]. - -[11] Note that the rejection here is restricted to authenticators from the -same principal to the same server. Other client principals communicating -with the same server principal should not be have their authenticators -rejected if the time and microsecond fields happen to match some other -client's authenticator. - -[12] In the Kerberos version 4 protocol, the timestamp in the reply was the -client's timestamp plus one. This is not necessary in version 5 because -version 5 messages are formatted in such a way that it is not possible to - -Neuman, Ts'o, Kohl Expires: 18 May 1999 - - -INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 - - -create the reply by judicious message surgery (even in encrypted form) -without knowledge of the appropriate encryption keys. - -[13] Note that for encrypting the KRB_AP_REP message, the sub-session key -is not used, even if present in the Authenticator. - -[14] Implementations of the protocol may wish to provide routines to choose -subkeys based on session keys and random numbers and to generate a -negotiated key to be returned in the KRB_AP_REP message. - -[15]This can be accomplished in several ways. It might be known beforehand -(since the realm is part of the principal identifier), it might be stored -in a nameserver, or it might be obtained from a configura- tion file. If -the realm to be used is obtained from a nameserver, there is a danger of -being spoofed if the nameservice providing the realm name is not authenti- -cated. This might result in the use of a realm which has been compromised, -and would result in an attacker's ability to compromise the authentication -of the application server to the client. - -[16] If the client selects a sub-session key, care must be taken to ensure -the randomness of the selected sub- session key. One approach would be to -generate a random number and XOR it with the session key from the -ticket-granting ticket. - -[17] This allows easy implementation of user-to-user authentication [8], -which uses ticket-granting ticket session keys in lieu of secret server -keys in situa- tions where such secret keys could be easily comprom- ised. - -[18] For the purpose of appending, the realm preceding the first listed -realm is considered to be the null realm (""). - -[19] For the purpose of interpreting null subfields, the client's realm is -considered to precede those in the transited field, and the server's realm -is considered to follow them. - -[20] This means that a client and server running on the same host and -communicating with one another using the KRB_SAFE messages should not share -a common replay cache to detect KRB_SAFE replays. - -[21] The implementation of the Kerberos server need not combine the -database and the server on the same machine; it is feasible to store the -principal database in, say, a network name service, as long as the entries -stored therein are protected from disclosure to and modification by -unauthorized parties. However, we recommend against such strategies, as -they can make system management and threat analysis quite complex. - -[22] See the discussion of the padata field in section 5.4.2 for details on -why this can be useful. - -[23] Warning for implementations that unpack and repack data structures -during the generation and verification of embedded checksums: Because any -checksums applied to data structures must be checked against the original -data the length of bit strings must be preserved within a data structure -between the time that a checksum is generated through transmission to the -time that the checksum is verified. - -[24] It is NOT recommended that this time value be used to adjust the -workstation's clock since the workstation cannot reliably determine that -such a KRB_AS_REP actually came from the proper KDC in a timely manner. - -Neuman, Ts'o, Kohl Expires: 18 May 1999 - - -INTERNET-DRAFT draft-ietf-cat-kerberos-r-03 November 18 1998 - - - -[25] Note, however, that if the time is used as the nonce, one must make -sure that the workstation time is monotonically increasing. If the time is -ever reset backwards, there is a small, but finite, probability that a -nonce will be reused. - -[27] An application code in the encrypted part of a message provides an -additional check that the message was decrypted properly. - -[29] An application code in the encrypted part of a message provides an -additional check that the message was decrypted properly. - -[31] An application code in the encrypted part of a message provides an -additional check that the message was decrypted properly. - -[32] If supported by the encryption method in use, an initialization vector -may be passed to the encryption procedure, in order to achieve proper -cipher chaining. The initialization vector might come from the last block -of the ciphertext from the previous KRB_PRIV message, but it is the -application's choice whether or not to use such an initialization vector. -If left out, the default initialization vector for the encryption algorithm -will be used. - -[33] This prevents an attacker who generates an incorrect AS request from -obtaining verifiable plaintext for use in an off-line password guessing -attack. - -[35] In the above specification, UNTAGGED OCTET STRING(length) is the -notation for an octet string with its tag and length removed. It is not a -valid ASN.1 type. The tag bits and length must be removed from the -confounder since the purpose of the confounder is so that the message -starts with random data, but the tag and its length are fixed. For other -fields, the length and tag would be redundant if they were included because -they are specified by the encryption type. [36] The ordering of the fields -in the CipherText is important. Additionally, messages encoded in this -format must include a length as part of the msg-seq field. This allows the -recipient to verify that the message has not been truncated. Without a -length, an attacker could use a chosen plaintext attack to generate a -message which could be truncated, while leaving the checksum intact. Note -that if the msg-seq is an encoding of an ASN.1 SEQUENCE or OCTET STRING, -then the length is part of that encoding. - -[37] In some cases, it may be necessary to use a different "mix-in" string -for compatibility reasons; see the discussion of padata in section 5.4.2. - -[38] In some cases, it may be necessary to use a different "mix-in" string -for compatibility reasons; see the discussion of padata in section 5.4.2. - -[39] A variant of the key is used to limit the use of a key to a particular -function, separating the functions of generating a checksum from other -encryption performed using the session key. The constant F0F0F0F0F0F0F0F0 -was chosen because it maintains key parity. The properties of DES precluded -the use of the complement. The same constant is used for similar purpose in -the Message Integrity Check in the Privacy Enhanced Mail standard. - -[40] This error carries additional information in the e- data field. The -contents of the e-data field for this message is described in section -5.9.1. - - -Neuman, Ts'o, Kohl Expires: 18 May 1999 - diff --git a/doc/draft-ietf-cat-kerberos-revisions-04.txt b/doc/draft-ietf-cat-kerberos-revisions-04.txt deleted file mode 100644 index 16af15dbc..000000000 --- a/doc/draft-ietf-cat-kerberos-revisions-04.txt +++ /dev/null @@ -1,6780 +0,0 @@ -INTERNET-DRAFT Clifford Neuman - John Kohl - Theodore Ts'o - June 25, 1999 - Expires December 25, 1999 -draft-ietf-cat-kerberos-revisions-04.txt - -The Kerberos Network Authentication Service (V5) - -STATUS OF THIS MEMO - -This document is an Internet-Draft and is in full conformance with all -provisions of Section 10 of RFC2026. Internet-Drafts are working documents -of the Internet Engineering Task Force (IETF), its areas, and its working -groups. Note that other groups may also distribute working documents as -Internet-Drafts. - -Internet-Drafts are draft documents valid for a maximum of six months and -may be updated, replaced, or obsoleted by other documents at any time. It is -inappropriate to use Internet- Drafts as reference material or to cite them -other than as "work in progress." - -The list of current Internet-Drafts can be accessed at -http://www.ietf.org/ietf/1id-abstracts.txt - -The list of Internet-Draft Shadow Directories can be accessed at -http://www.ietf.org/shadow.html. To learn the current status of any -Internet-Draft, please check the '1id-abstracts.txt' listing contained in -the Internet-Drafts Shadow Directories. - -The distribution of this memo is unlimited. It is filed as -draft-ietf-cat-kerberos-revisions-04.txt, and expires December 25th, 1999. -Please send comments to: krb-protocol@MIT.EDU - -ABSTRACT - -This document provides an overview and specification of Version 5 of the -Kerberos protocol, and updates RFC1510 to clarify aspects of the protocol -and its intended use that require more detailed or clearer explanation than -was provided in RFC1510. This document is intended to provide a detailed -description of the protocol, suitable for implementation, together with -descriptions of the appropriate use of protocol messages and fields within -those messages. - -This document is not intended to describe Kerberos to the end user, system -administrator, or application developer. Higher level papers describing -Version 5 of the Kerberos system [NT94] and documenting version 4 [SNS88], -are available elsewhere. - -OVERVIEW - -This INTERNET-DRAFT describes the concepts and model upon which the Kerberos -network authentication system is based. It also specifies Version 5 of the -Kerberos protocol. - -Neuman, Ts'o, Kohl Expires: 25 December, -1999 - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, -1999 - -The motivations, goals, assumptions, and rationale behind most design -decisions are treated cursorily; they are more fully described in a paper -available in IEEE communications [NT94] and earlier in the Kerberos portion -of the Athena Technical Plan [MNSS87]. The protocols have been a proposed -standard and are being considered for advancement for draft standard through -the IETF standard process. Comments are encouraged on the presentation, but -only minor refinements to the protocol as implemented or extensions that fit -within current protocol framework will be considered at this time. - -Requests for addition to an electronic mailing list for discussion of -Kerberos, kerberos@MIT.EDU, may be addressed to kerberos-request@MIT.EDU. -This mailing list is gatewayed onto the Usenet as the group -comp.protocols.kerberos. Requests for further information, including -documents and code availability, may be sent to info-kerberos@MIT.EDU. - -BACKGROUND - -The Kerberos model is based in part on Needham and Schroeder's trusted -third-party authentication protocol [NS78] and on modifications suggested by -Denning and Sacco [DS81]. The original design and implementation of Kerberos -Versions 1 through 4 was the work of two former Project Athena staff -members, Steve Miller of Digital Equipment Corporation and Clifford Neuman -(now at the Information Sciences Institute of the University of Southern -California), along with Jerome Saltzer, Technical Director of Project -Athena, and Jeffrey Schiller, MIT Campus Network Manager. Many other members -of Project Athena have also contributed to the work on Kerberos. - -Version 5 of the Kerberos protocol (described in this document) has evolved -from Version 4 based on new requirements and desires for features not -available in Version 4. The design of Version 5 of the Kerberos protocol was -led by Clifford Neuman and John Kohl with much input from the community. The -development of the MIT reference implementation was led at MIT by John Kohl -and Theodore T'so, with help and contributed code from many others. Since -RFC1510 was issued, extensions and revisions to the protocol have been -proposed by many individuals. Some of these proposals are reflected in this -document. Where such changes involved significant effort, the document cites -the contribution of the proposer. - -Reference implementations of both version 4 and version 5 of Kerberos are -publicly available and commercial implementations have been developed and -are widely used. Details on the differences between Kerberos Versions 4 and -5 can be found in [KNT92]. - -1. Introduction - -Kerberos provides a means of verifying the identities of principals, (e.g. a -workstation user or a network server) on an open (unprotected) network. This -is accomplished without relying on assertions by the host operating system, -without basing trust on host addresses, without requiring physical security -of all the hosts on the network, and under the assumption that packets -traveling along the network can be read, modified, and inserted at will[1]. -Kerberos performs authentication under these conditions as a trusted -third-party authentication service by using conventional (shared secret key -[2] cryptography. Kerberos extensions have been proposed and implemented -that provide for the use of public key cryptography during certain phases of -the authentication protocol. These extensions provide for authentication of - -Neuman, Ts'o, Kohl Expires: 25 December, -1999 - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, -1999 - -users registered with public key certification authorities, and allow the -system to provide certain benefits of public key cryptography in situations -where they are needed. - -The basic Kerberos authentication process proceeds as follows: A client -sends a request to the authentication server (AS) requesting 'credentials' -for a given server. The AS responds with these credentials, encrypted in the -client's key. The credentials consist of 1) a 'ticket' for the server and 2) -a temporary encryption key (often called a "session key"). The client -transmits the ticket (which contains the client's identity and a copy of the -session key, all encrypted in the server's key) to the server. The session -key (now shared by the client and server) is used to authenticate the -client, and may optionally be used to authenticate the server. It may also -be used to encrypt further communication between the two parties or to -exchange a separate sub-session key to be used to encrypt further -communication. - -Implementation of the basic protocol consists of one or more authentication -servers running on physically secure hosts. The authentication servers -maintain a database of principals (i.e., users and servers) and their secret -keys. Code libraries provide encryption and implement the Kerberos protocol. -In order to add authentication to its transactions, a typical network -application adds one or two calls to the Kerberos library directly or -through the Generic Security Services Application Programming Interface, -GSSAPI, described in separate document. These calls result in the -transmission of the necessary messages to achieve authentication. - -The Kerberos protocol consists of several sub-protocols (or exchanges). -There are two basic methods by which a client can ask a Kerberos server for -credentials. In the first approach, the client sends a cleartext request for -a ticket for the desired server to the AS. The reply is sent encrypted in -the client's secret key. Usually this request is for a ticket-granting -ticket (TGT) which can later be used with the ticket-granting server (TGS). -In the second method, the client sends a request to the TGS. The client uses -the TGT to authenticate itself to the TGS in the same manner as if it were -contacting any other application server that requires Kerberos -authentication. The reply is encrypted in the session key from the TGT. -Though the protocol specification describes the AS and the TGS as separate -servers, they are implemented in practice as different protocol entry points -within a single Kerberos server. - -Once obtained, credentials may be used to verify the identity of the -principals in a transaction, to ensure the integrity of messages exchanged -between them, or to preserve privacy of the messages. The application is -free to choose whatever protection may be necessary. - -To verify the identities of the principals in a transaction, the client -transmits the ticket to the application server. Since the ticket is sent "in -the clear" (parts of it are encrypted, but this encryption doesn't thwart -replay) and might be intercepted and reused by an attacker, additional -information is sent to prove that the message originated with the principal -to whom the ticket was issued. This information (called the authenticator) -is encrypted in the session key, and includes a timestamp. The timestamp -proves that the message was recently generated and is not a replay. -Encrypting the authenticator in the session key proves that it was generated -by a party possessing the session key. Since no one except the requesting -principal and the server know the session key (it is never sent over the -network in the clear) this guarantees the identity of the client. - -Neuman, Ts'o, Kohl Expires: 25 December, -1999 - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, -1999 - -The integrity of the messages exchanged between principals can also be -guaranteed using the session key (passed in the ticket and contained in the -credentials). This approach provides detection of both replay attacks and -message stream modification attacks. It is accomplished by generating and -transmitting a collision-proof checksum (elsewhere called a hash or digest -function) of the client's message, keyed with the session key. Privacy and -integrity of the messages exchanged between principals can be secured by -encrypting the data to be passed using the session key contained in the -ticket or the subsession key found in the authenticator. - -The authentication exchanges mentioned above require read-only access to the -Kerberos database. Sometimes, however, the entries in the database must be -modified, such as when adding new principals or changing a principal's key. -This is done using a protocol between a client and a third Kerberos server, -the Kerberos Administration Server (KADM). There is also a protocol for -maintaining multiple copies of the Kerberos database. Neither of these -protocols are described in this document. - -1.1. Cross-Realm Operation - -The Kerberos protocol is designed to operate across organizational -boundaries. A client in one organization can be authenticated to a server in -another. Each organization wishing to run a Kerberos server establishes its -own 'realm'. The name of the realm in which a client is registered is part -of the client's name, and can be used by the end-service to decide whether -to honor a request. - -By establishing 'inter-realm' keys, the administrators of two realms can -allow a client authenticated in the local realm to prove its identity to -servers in other realms[3]. The exchange of inter-realm keys (a separate key -may be used for each direction) registers the ticket-granting service of -each realm as a principal in the other realm. A client is then able to -obtain a ticket-granting ticket for the remote realm's ticket-granting -service from its local realm. When that ticket-granting ticket is used, the -remote ticket-granting service uses the inter-realm key (which usually -differs from its own normal TGS key) to decrypt the ticket-granting ticket, -and is thus certain that it was issued by the client's own TGS. Tickets -issued by the remote ticket-granting service will indicate to the -end-service that the client was authenticated from another realm. - -A realm is said to communicate with another realm if the two realms share an -inter-realm key, or if the local realm shares an inter-realm key with an -intermediate realm that communicates with the remote realm. An -authentication path is the sequence of intermediate realms that are -transited in communicating from one realm to another. - -Realms are typically organized hierarchically. Each realm shares a key with -its parent and a different key with each child. If an inter-realm key is not -directly shared by two realms, the hierarchical organization allows an -authentication path to be easily constructed. If a hierarchical organization -is not used, it may be necessary to consult a database in order to construct -an authentication path between realms. - -Although realms are typically hierarchical, intermediate realms may be -bypassed to achieve cross-realm authentication through alternate -authentication paths (these might be established to make communication -between two realms more efficient). It is important for the end-service to - -Neuman, Ts'o, Kohl Expires: 25 December, -1999 - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, -1999 - -know which realms were transited when deciding how much faith to place in -the authentication process. To facilitate this decision, a field in each -ticket contains the names of the realms that were involved in authenticating -the client. - -The application server is ultimately responsible for accepting or rejecting -authentication and should check the transited field. The application server -may choose to rely on the KDC for the application server's realm to check -the transited field. The application server's KDC will set the -TRANSITED-POLICY-CHECKED flag in this case. The KDC's for intermediate -realms may also check the transited field as they issue -ticket-granting-tickets for other realms, but they are encouraged not to do -so. A client may request that the KDC's not check the transited field by -setting the DISABLE-TRANSITED-CHECK flag. KDC's are encouraged but not -required to honor this flag. - -1.2. Authorization - -As an authentication service, Kerberos provides a means of verifying the -identity of principals on a network. Authentication is usually useful -primarily as a first step in the process of authorization, determining -whether a client may use a service, which objects the client is allowed to -access, and the type of access allowed for each. Kerberos does not, by -itself, provide authorization. Possession of a client ticket for a service -provides only for authentication of the client to that service, and in the -absence of a separate authorization procedure, it should not be considered -by an application as authorizing the use of that service. - -Such separate authorization methods may be implemented as application -specific access control functions and may be based on files such as the -application server, or on separately issued authorization credentials such -as those based on proxies [Neu93] , or on other authorization services. - -Applications should not be modified to accept the issuance of a service -ticket by the Kerberos server (even by an modified Kerberos server) as -granting authority to use the service, since such applications may become -vulnerable to the bypass of this authorization check in an environment if -they interoperate with other KDCs or where other options for application -authentication (e.g. the PKTAPP proposal) are provided. - -1.3. Environmental assumptions - -Kerberos imposes a few assumptions on the environment in which it can -properly function: - - * 'Denial of service' attacks are not solved with Kerberos. There are - places in these protocols where an intruder can prevent an application - from participating in the proper authentication steps. Detection and - solution of such attacks (some of which can appear to be nnot-uncommon - 'normal' failure modes for the system) is usually best left to the - human administrators and users. - * Principals must keep their secret keys secret. If an intruder somehow - steals a principal's key, it will be able to masquerade as that - principal or impersonate any server to the legitimate principal. - * 'Password guessing' attacks are not solved by Kerberos. If a user - chooses a poor password, it is possible for an attacker to successfully - mount an offline dictionary attack by repeatedly attempting to decrypt, - with successive entries from a dictionary, messages obtained which are - encrypted under a key derived from the user's password. - -Neuman, Ts'o, Kohl Expires: 25 December, -1999 - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, -1999 - - * Each host on the network must have a clock which is 'loosely - synchronized' to the time of the other hosts; this synchronization is - used to reduce the bookkeeping needs of application servers when they - do replay detection. The degree of "looseness" can be configured on a - per-server basis, but is typically on the order of 5 minutes. If the - clocks are synchronized over the network, the clock synchronization - protocol must itself be secured from network attackers. - * Principal identifiers are not recycled on a short-term basis. A typical - mode of access control will use access control lists (ACLs) to grant - permissions to particular principals. If a stale ACL entry remains for - a deleted principal and the principal identifier is reused, the new - principal will inherit rights specified in the stale ACL entry. By not - re-using principal identifiers, the danger of inadvertent access is - removed. - -1.4. Glossary of terms - -Below is a list of terms used throughout this document. - -Authentication - Verifying the claimed identity of a principal. -Authentication header - A record containing a Ticket and an Authenticator to be presented to a - server as part of the authentication process. -Authentication path - A sequence of intermediate realms transited in the authentication - process when communicating from one realm to another. -Authenticator - A record containing information that can be shown to have been recently - generated using the session key known only by the client and server. -Authorization - The process of determining whether a client may use a service, which - objects the client is allowed to access, and the type of access allowed - for each. -Capability - A token that grants the bearer permission to access an object or - service. In Kerberos, this might be a ticket whose use is restricted by - the contents of the authorization data field, but which lists no - network addresses, together with the session key necessary to use the - ticket. -Ciphertext - The output of an encryption function. Encryption transforms plaintext - into ciphertext. -Client - A process that makes use of a network service on behalf of a user. Note - that in some cases a Server may itself be a client of some other server - (e.g. a print server may be a client of a file server). -Credentials - A ticket plus the secret session key necessary to successfully use that - ticket in an authentication exchange. -KDC - Key Distribution Center, a network service that supplies tickets and - temporary session keys; or an instance of that service or the host on - which it runs. The KDC services both initial ticket and ticket-granting - ticket requests. The initial ticket portion is sometimes referred to as - the Authentication Server (or service). The ticket-granting ticket - portion is sometimes referred to as the ticket-granting server (or - service). - -Neuman, Ts'o, Kohl Expires: 25 December, -1999 - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, -1999 - -Kerberos - Aside from the 3-headed dog guarding Hades, the name given to Project - Athena's authentication service, the protocol used by that service, or - the code used to implement the authentication service. -Plaintext - The input to an encryption function or the output of a decryption - function. Decryption transforms ciphertext into plaintext. -Principal - A uniquely named client or server instance that participates in a - network communication. -Principal identifier - The name used to uniquely identify each different principal. -Seal - To encipher a record containing several fields in such a way that the - fields cannot be individually replaced without either knowledge of the - encryption key or leaving evidence of tampering. -Secret key - An encryption key shared by a principal and the KDC, distributed - outside the bounds of the system, with a long lifetime. In the case of - a human user's principal, the secret key is derived from a password. -Server - A particular Principal which provides a resource to network clients. - The server is sometimes refered to as the Application Server. -Service - A resource provided to network clients; often provided by more than one - server (for example, remote file service). -Session key - A temporary encryption key used between two principals, with a lifetime - limited to the duration of a single login "session". -Sub-session key - A temporary encryption key used between two principals, selected and - exchanged by the principals using the session key, and with a lifetime - limited to the duration of a single association. -Ticket - A record that helps a client authenticate itself to a server; it - contains the client's identity, a session key, a timestamp, and other - information, all sealed using the server's secret key. It only serves - to authenticate a client when presented along with a fresh - Authenticator. - -2. Ticket flag uses and requests - -Each Kerberos ticket contains a set of flags which are used to indicate -various attributes of that ticket. Most flags may be requested by a client -when the ticket is obtained; some are automatically turned on and off by a -Kerberos server as required. The following sections explain what the various -flags mean, and gives examples of reasons to use such a flag. - -2.1. Initial and pre-authenticated tickets - -The INITIAL flag indicates that a ticket was issued using the AS protocol -and not issued based on a ticket-granting ticket. Application servers that -want to require the demonstrated knowledge of a client's secret key (e.g. a -password-changing program) can insist that this flag be set in any tickets -they accept, and thus be assured that the client's key was recently -presented to the application client. - - -Neuman, Ts'o, Kohl Expires: 25 December, -1999 - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, -1999 - -The PRE-AUTHENT and HW-AUTHENT flags provide addition information about the -initial authentication, regardless of whether the current ticket was issued -directly (in which case INITIAL will also be set) or issued on the basis of -a ticket-granting ticket (in which case the INITIAL flag is clear, but the -PRE-AUTHENT and HW-AUTHENT flags are carried forward from the -ticket-granting ticket). - -2.2. Invalid tickets - -The INVALID flag indicates that a ticket is invalid. Application servers -must reject tickets which have this flag set. A postdated ticket will -usually be issued in this form. Invalid tickets must be validated by the KDC -before use, by presenting them to the KDC in a TGS request with the VALIDATE -option specified. The KDC will only validate tickets after their starttime -has passed. The validation is required so that postdated tickets which have -been stolen before their starttime can be rendered permanently invalid -(through a hot-list mechanism) (see section 3.3.3.1). - -2.3. Renewable tickets - -Applications may desire to hold tickets which can be valid for long periods -of time. However, this can expose their credentials to potential theft for -equally long periods, and those stolen credentials would be valid until the -expiration time of the ticket(s). Simply using short-lived tickets and -obtaining new ones periodically would require the client to have long-term -access to its secret key, an even greater risk. Renewable tickets can be -used to mitigate the consequences of theft. Renewable tickets have two -"expiration times": the first is when the current instance of the ticket -expires, and the second is the latest permissible value for an individual -expiration time. An application client must periodically (i.e. before it -expires) present a renewable ticket to the KDC, with the RENEW option set in -the KDC request. The KDC will issue a new ticket with a new session key and -a later expiration time. All other fields of the ticket are left unmodified -by the renewal process. When the latest permissible expiration time arrives, -the ticket expires permanently. At each renewal, the KDC may consult a -hot-list to determine if the ticket had been reported stolen since its last -renewal; it will refuse to renew such stolen tickets, and thus the usable -lifetime of stolen tickets is reduced. - -The RENEWABLE flag in a ticket is normally only interpreted by the -ticket-granting service (discussed below in section 3.3). It can usually be -ignored by application servers. However, some particularly careful -application servers may wish to disallow renewable tickets. - -If a renewable ticket is not renewed by its expiration time, the KDC will -not renew the ticket. The RENEWABLE flag is reset by default, but a client -may request it be set by setting the RENEWABLE option in the KRB_AS_REQ -message. If it is set, then the renew-till field in the ticket contains the -time after which the ticket may not be renewed. - - -Neuman, Ts'o, Kohl Expires: 25 December, -1999 - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, -1999 - -2.4. Postdated tickets - -Applications may occasionally need to obtain tickets for use much later, -e.g. a batch submission system would need tickets to be valid at the time -the batch job is serviced. However, it is dangerous to hold valid tickets in -a batch queue, since they will be on-line longer and more prone to theft. -Postdated tickets provide a way to obtain these tickets from the KDC at job -submission time, but to leave them "dormant" until they are activated and -validated by a further request of the KDC. If a ticket theft were reported -in the interim, the KDC would refuse to validate the ticket, and the thief -would be foiled. - -The MAY-POSTDATE flag in a ticket is normally only interpreted by the -ticket-granting service. It can be ignored by application servers. This flag -must be set in a ticket-granting ticket in order to issue a postdated ticket -based on the presented ticket. It is reset by default; it may be requested -by a client by setting the ALLOW-POSTDATE option in the KRB_AS_REQ message. -This flag does not allow a client to obtain a postdated ticket-granting -ticket; postdated ticket-granting tickets can only by obtained by requesting -the postdating in the KRB_AS_REQ message. The life (endtime-starttime) of a -postdated ticket will be the remaining life of the ticket-granting ticket at -the time of the request, unless the RENEWABLE option is also set, in which -case it can be the full life (endtime-starttime) of the ticket-granting -ticket. The KDC may limit how far in the future a ticket may be postdated. - -The POSTDATED flag indicates that a ticket has been postdated. The -application server can check the authtime field in the ticket to see when -the original authentication occurred. Some services may choose to reject -postdated tickets, or they may only accept them within a certain period -after the original authentication. When the KDC issues a POSTDATED ticket, -it will also be marked as INVALID, so that the application client must -present the ticket to the KDC to be validated before use. - -2.5. Proxiable and proxy tickets - -At times it may be necessary for a principal to allow a service to perform -an operation on its behalf. The service must be able to take on the identity -of the client, but only for a particular purpose. A principal can allow a -service to take on the principal's identity for a particular purpose by -granting it a proxy. - -The process of granting a proxy using the proxy and proxiable flags is used -to provide credentials for use with specific services. Though conceptually -also a proxy, user's wishing to delegate their identity for ANY purpose must -use the ticket forwarding mechanism described in the next section to forward -a ticket granting ticket. - -The PROXIABLE flag in a ticket is normally only interpreted by the -ticket-granting service. It can be ignored by application servers. When set, -this flag tells the ticket-granting server that it is OK to issue a new -ticket (but not a ticket-granting ticket) with a different network address -based on this ticket. This flag is set if requested by the client on initial -authentication. By default, the client will request that it be set when -requesting a ticket granting ticket, and reset when requesting any other -ticket. - - -Neuman, Ts'o, Kohl Expires: 25 December, -1999 - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, -1999 - -This flag allows a client to pass a proxy to a server to perform a remote -request on its behalf, e.g. a print service client can give the print server -a proxy to access the client's files on a particular file server in order to -satisfy a print request. - -In order to complicate the use of stolen credentials, Kerberos tickets are -usually valid from only those network addresses specifically included in the -ticket[4]. When granting a proxy, the client must specify the new network -address from which the proxy is to be used, or indicate that the proxy is to -be issued for use from any address. - -The PROXY flag is set in a ticket by the TGS when it issues a proxy ticket. -Application servers may check this flag and at their option they may require -additional authentication from the agent presenting the proxy in order to -provide an audit trail. - -2.6. Forwardable tickets - -Authentication forwarding is an instance of a proxy where the service is -granted complete use of the client's identity. An example where it might be -used is when a user logs in to a remote system and wants authentication to -work from that system as if the login were local. - -The FORWARDABLE flag in a ticket is normally only interpreted by the -ticket-granting service. It can be ignored by application servers. The -FORWARDABLE flag has an interpretation similar to that of the PROXIABLE -flag, except ticket-granting tickets may also be issued with different -network addresses. This flag is reset by default, but users may request that -it be set by setting the FORWARDABLE option in the AS request when they -request their initial ticket- granting ticket. - -This flag allows for authentication forwarding without requiring the user to -enter a password again. If the flag is not set, then authentication -forwarding is not permitted, but the same result can still be achieved if -the user engages in the AS exchange specifying the requested network -addresses and supplies a password. - -The FORWARDED flag is set by the TGS when a client presents a ticket with -the FORWARDABLE flag set and requests a forwarded ticket by specifying the -FORWARDED KDC option and supplying a set of addresses for the new ticket. It -is also set in all tickets issued based on tickets with the FORWARDED flag -set. Application servers may choose to process FORWARDED tickets differently -than non-FORWARDED tickets. - -2.7. Other KDC options - -There are two additional options which may be set in a client's request of -the KDC. The RENEWABLE-OK option indicates that the client will accept a -renewable ticket if a ticket with the requested life cannot otherwise be -provided. If a ticket with the requested life cannot be provided, then the -KDC may issue a renewable ticket with a renew-till equal to the the -requested endtime. The value of the renew-till field may still be adjusted -by site-determined limits or limits imposed by the individual principal or -server. - -The ENC-TKT-IN-SKEY option is honored only by the ticket-granting service. -It indicates that the ticket to be issued for the end server is to be -encrypted in the session key from the a additional second ticket-granting -ticket provided with the request. See section 3.3.3 for specific details. - - -Neuman, Ts'o, Kohl Expires: 25 December, -1999 - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, -1999 - -3. Message Exchanges - -The following sections describe the interactions between network clients and -servers and the messages involved in those exchanges. - -3.1. The Authentication Service Exchange - - Summary - Message direction Message type Section - 1. Client to Kerberos KRB_AS_REQ 5.4.1 - 2. Kerberos to client KRB_AS_REP or 5.4.2 - KRB_ERROR 5.9.1 - -The Authentication Service (AS) Exchange between the client and the Kerberos -Authentication Server is initiated by a client when it wishes to obtain -authentication credentials for a given server but currently holds no -credentials. In its basic form, the client's secret key is used for -encryption and decryption. This exchange is typically used at the initiation -of a login session to obtain credentials for a Ticket-Granting Server which -will subsequently be used to obtain credentials for other servers (see -section 3.3) without requiring further use of the client's secret key. This -exchange is also used to request credentials for services which must not be -mediated through the Ticket-Granting Service, but rather require a -principal's secret key, such as the password-changing service[5]. This -exchange does not by itself provide any assurance of the the identity of the -user[6]. - -The exchange consists of two messages: KRB_AS_REQ from the client to -Kerberos, and KRB_AS_REP or KRB_ERROR in reply. The formats for these -messages are described in sections 5.4.1, 5.4.2, and 5.9.1. - -In the request, the client sends (in cleartext) its own identity and the -identity of the server for which it is requesting credentials. The response, -KRB_AS_REP, contains a ticket for the client to present to the server, and a -session key that will be shared by the client and the server. The session -key and additional information are encrypted in the client's secret key. The -KRB_AS_REP message contains information which can be used to detect replays, -and to associate it with the message to which it replies. Various errors can -occur; these are indicated by an error response (KRB_ERROR) instead of the -KRB_AS_REP response. The error message is not encrypted. The KRB_ERROR -message contains information which can be used to associate it with the -message to which it replies. The lack of encryption in the KRB_ERROR message -precludes the ability to detect replays, fabrications, or modifications of -such messages. - -Without preautentication, the authentication server does not know whether -the client is actually the principal named in the request. It simply sends a -reply without knowing or caring whether they are the same. This is -acceptable because nobody but the principal whose identity was given in the -request will be able to use the reply. Its critical information is encrypted -in that principal's key. The initial request supports an optional field that -can be used to pass additional information that might be needed for the -initial exchange. This field may be used for preauthentication as described -in section [hl<>]. - - -Neuman, Ts'o, Kohl Expires: 25 December, -1999 - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, -1999 - -3.1.1. Generation of KRB_AS_REQ message - -The client may specify a number of options in the initial request. Among -these options are whether pre-authentication is to be performed; whether the -requested ticket is to be renewable, proxiable, or forwardable; whether it -should be postdated or allow postdating of derivative tickets; and whether a -renewable ticket will be accepted in lieu of a non-renewable ticket if the -requested ticket expiration date cannot be satisfied by a non-renewable -ticket (due to configuration constraints; see section 4). See section A.1 -for pseudocode. - -The client prepares the KRB_AS_REQ message and sends it to the KDC. - -3.1.2. Receipt of KRB_AS_REQ message - -If all goes well, processing the KRB_AS_REQ message will result in the -creation of a ticket for the client to present to the server. The format for -the ticket is described in section 5.3.1. The contents of the ticket are -determined as follows. - -3.1.3. Generation of KRB_AS_REP message - -The authentication server looks up the client and server principals named in -the KRB_AS_REQ in its database, extracting their respective keys. If -required, the server pre-authenticates the request, and if the -pre-authentication check fails, an error message with the code -KDC_ERR_PREAUTH_FAILED is returned. If the server cannot accommodate the -requested encryption type, an error message with code KDC_ERR_ETYPE_NOSUPP -is returned. Otherwise it generates a 'random' session key[7]. - -If there are multiple encryption keys registered for a client in the -Kerberos database (or if the key registered supports multiple encryption -types; e.g. DES-CBC-CRC and DES-CBC-MD5), then the etype field from the AS -request is used by the KDC to select the encryption method to be used for -encrypting the response to the client. If there is more than one supported, -strong encryption type in the etype list, the first valid etype for which an -encryption key is available is used. The encryption method used to respond -to a TGS request is taken from the keytype of the session key found in the -ticket granting ticket. [***I will change the example keytypes to be 3DES -based examples 7/14***] - -When the etype field is present in a KDC request, whether an AS or TGS -request, the KDC will attempt to assign the type of the random session key -from the list of methods in the etype field. The KDC will select the -appropriate type using the list of methods provided together with -information from the Kerberos database indicating acceptable encryption -methods for the application server. The KDC will not issue tickets with a -weak session key encryption type. - -If the requested start time is absent, indicates a time in the past, or is -within the window of acceptable clock skew for the KDC and the POSTDATE -option has not been specified, then the start time of the ticket is set to -the authentication server's current time. If it indicates a time in the -future beyond the acceptable clock skew, but the POSTDATED option has not -been specified then the error KDC_ERR_CANNOT_POSTDATE is returned. Otherwise -the requested start time is checked against the policy of the local realm -(the administrator might decide to prohibit certain types or ranges of -postdated tickets), and if acceptable, the ticket's start time is set as - -Neuman, Ts'o, Kohl Expires: 25 December, -1999 - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, -1999 - -requested and the INVALID flag is set in the new ticket. The postdated -ticket must be validated before use by presenting it to the KDC after the -start time has been reached. - -The expiration time of the ticket will be set to the minimum of the -following: - - * The expiration time (endtime) requested in the KRB_AS_REQ message. - * The ticket's start time plus the maximum allowable lifetime associated - with the client principal (the authentication server's database - includes a maximum ticket lifetime field in each principal's record; - see section 4). - * The ticket's start time plus the maximum allowable lifetime associated - with the server principal. - * The ticket's start time plus the maximum lifetime set by the policy of - the local realm. - -If the requested expiration time minus the start time (as determined above) -is less than a site-determined minimum lifetime, an error message with code -KDC_ERR_NEVER_VALID is returned. If the requested expiration time for the -ticket exceeds what was determined as above, and if the 'RENEWABLE-OK' -option was requested, then the 'RENEWABLE' flag is set in the new ticket, -and the renew-till value is set as if the 'RENEWABLE' option were requested -(the field and option names are described fully in section 5.4.1). - -If the RENEWABLE option has been requested or if the RENEWABLE-OK option has -been set and a renewable ticket is to be issued, then the renew-till field -is set to the minimum of: - - * Its requested value. - * The start time of the ticket plus the minimum of the two maximum - renewable lifetimes associated with the principals' database entries. - * The start time of the ticket plus the maximum renewable lifetime set by - the policy of the local realm. - -The flags field of the new ticket will have the following options set if -they have been requested and if the policy of the local realm allows: -FORWARDABLE, MAY-POSTDATE, POSTDATED, PROXIABLE, RENEWABLE. If the new -ticket is post-dated (the start time is in the future), its INVALID flag -will also be set. - -If all of the above succeed, the server formats a KRB_AS_REP message (see -section 5.4.2), copying the addresses in the request into the caddr of the -response, placing any required pre-authentication data into the padata of -the response, and encrypts the ciphertext part in the client's key using the -requested encryption method, and sends it to the client. See section A.2 for -pseudocode. - -3.1.4. Generation of KRB_ERROR message - -Several errors can occur, and the Authentication Server responds by -returning an error message, KRB_ERROR, to the client, with the error-code -and e-text fields set to appropriate values. The error message contents and -details are described in Section 5.9.1. - - -Neuman, Ts'o, Kohl Expires: 25 December, -1999 - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, -1999 - -3.1.5. Receipt of KRB_AS_REP message - -If the reply message type is KRB_AS_REP, then the client verifies that the -cname and crealm fields in the cleartext portion of the reply match what it -requested. If any padata fields are present, they may be used to derive the -proper secret key to decrypt the message. The client decrypts the encrypted -part of the response using its secret key, verifies that the nonce in the -encrypted part matches the nonce it supplied in its request (to detect -replays). It also verifies that the sname and srealm in the response match -those in the request (or are otherwise expected values), and that the host -address field is also correct. It then stores the ticket, session key, start -and expiration times, and other information for later use. The -key-expiration field from the encrypted part of the response may be checked -to notify the user of impending key expiration (the client program could -then suggest remedial action, such as a password change). See section A.3 -for pseudocode. - -Proper decryption of the KRB_AS_REP message is not sufficient to verify the -identity of the user; the user and an attacker could cooperate to generate a -KRB_AS_REP format message which decrypts properly but is not from the proper -KDC. If the host wishes to verify the identity of the user, it must require -the user to present application credentials which can be verified using a -securely-stored secret key for the host. If those credentials can be -verified, then the identity of the user can be assured. - -3.1.6. Receipt of KRB_ERROR message - -If the reply message type is KRB_ERROR, then the client interprets it as an -error and performs whatever application-specific tasks are necessary to -recover. - -3.2. The Client/Server Authentication Exchange - - Summary -Message direction Message type Section -Client to Application server KRB_AP_REQ 5.5.1 -[optional] Application server to client KRB_AP_REP or 5.5.2 - KRB_ERROR 5.9.1 - -The client/server authentication (CS) exchange is used by network -applications to authenticate the client to the server and vice versa. The -client must have already acquired credentials for the server using the AS or -TGS exchange. - -3.2.1. The KRB_AP_REQ message - -The KRB_AP_REQ contains authentication information which should be part of -the first message in an authenticated transaction. It contains a ticket, an -authenticator, and some additional bookkeeping information (see section -5.5.1 for the exact format). The ticket by itself is insufficient to -authenticate a client, since tickets are passed across the network in -cleartext[DS90], so the authenticator is used to prevent invalid replay of -tickets by proving to the server that the client knows the session key of -the ticket and thus is entitled to use the ticket. The KRB_AP_REQ message is -referred to elsewhere as the 'authentication header.' - - -Neuman, Ts'o, Kohl Expires: 25 December, -1999 - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, -1999 - -3.2.2. Generation of a KRB_AP_REQ message - -When a client wishes to initiate authentication to a server, it obtains -(either through a credentials cache, the AS exchange, or the TGS exchange) a -ticket and session key for the desired service. The client may re-use any -tickets it holds until they expire. To use a ticket the client constructs a -new Authenticator from the the system time, its name, and optionally an -application specific checksum, an initial sequence number to be used in -KRB_SAFE or KRB_PRIV messages, and/or a session subkey to be used in -negotiations for a session key unique to this particular session. -Authenticators may not be re-used and will be rejected if replayed to a -server[LGDSR87]. If a sequence number is to be included, it should be -randomly chosen so that even after many messages have been exchanged it is -not likely to collide with other sequence numbers in use. - -The client may indicate a requirement of mutual authentication or the use of -a session-key based ticket by setting the appropriate flag(s) in the -ap-options field of the message. - -The Authenticator is encrypted in the session key and combined with the -ticket to form the KRB_AP_REQ message which is then sent to the end server -along with any additional application-specific information. See section A.9 -for pseudocode. - -3.2.3. Receipt of KRB_AP_REQ message - -Authentication is based on the server's current time of day (clocks must be -loosely synchronized), the authenticator, and the ticket. Several errors are -possible. If an error occurs, the server is expected to reply to the client -with a KRB_ERROR message. This message may be encapsulated in the -application protocol if its 'raw' form is not acceptable to the protocol. -The format of error messages is described in section 5.9.1. - -The algorithm for verifying authentication information is as follows. If the -message type is not KRB_AP_REQ, the server returns the KRB_AP_ERR_MSG_TYPE -error. If the key version indicated by the Ticket in the KRB_AP_REQ is not -one the server can use (e.g., it indicates an old key, and the server no -longer possesses a copy of the old key), the KRB_AP_ERR_BADKEYVER error is -returned. If the USE-SESSION-KEY flag is set in the ap-options field, it -indicates to the server that the ticket is encrypted in the session key from -the server's ticket-granting ticket rather than its secret key[10]. Since it -is possible for the server to be registered in multiple realms, with -different keys in each, the srealm field in the unencrypted portion of the -ticket in the KRB_AP_REQ is used to specify which secret key the server -should use to decrypt that ticket. The KRB_AP_ERR_NOKEY error code is -returned if the server doesn't have the proper key to decipher the ticket. - -The ticket is decrypted using the version of the server's key specified by -the ticket. If the decryption routines detect a modification of the ticket -(each encryption system must provide safeguards to detect modified -ciphertext; see section 6), the KRB_AP_ERR_BAD_INTEGRITY error is returned -(chances are good that different keys were used to encrypt and decrypt). - -The authenticator is decrypted using the session key extracted from the -decrypted ticket. If decryption shows it to have been modified, the -KRB_AP_ERR_BAD_INTEGRITY error is returned. The name and realm of the client -from the ticket are compared against the same fields in the authenticator. -If they don't match, the KRB_AP_ERR_BADMATCH error is returned (they might - -Neuman, Ts'o, Kohl Expires: 25 December, -1999 - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, -1999 - -not match, for example, if the wrong session key was used to encrypt the -authenticator). The addresses in the ticket (if any) are then searched for -an address matching the operating-system reported address of the client. If -no match is found or the server insists on ticket addresses but none are -present in the ticket, the KRB_AP_ERR_BADADDR error is returned. - -If the local (server) time and the client time in the authenticator differ -by more than the allowable clock skew (e.g., 5 minutes), the KRB_AP_ERR_SKEW -error is returned. If the server name, along with the client name, time and -microsecond fields from the Authenticator match any recently-seen such -tuples, the KRB_AP_ERR_REPEAT error is returned[11]. The server must -remember any authenticator presented within the allowable clock skew, so -that a replay attempt is guaranteed to fail. If a server loses track of any -authenticator presented within the allowable clock skew, it must reject all -requests until the clock skew interval has passed. This assures that any -lost or re-played authenticators will fall outside the allowable clock skew -and can no longer be successfully replayed (If this is not done, an attacker -could conceivably record the ticket and authenticator sent over the network -to a server, then disable the client's host, pose as the disabled host, and -replay the ticket and authenticator to subvert the authentication.). If a -sequence number is provided in the authenticator, the server saves it for -later use in processing KRB_SAFE and/or KRB_PRIV messages. If a subkey is -present, the server either saves it for later use or uses it to help -generate its own choice for a subkey to be returned in a KRB_AP_REP message. - -The server computes the age of the ticket: local (server) time minus the -start time inside the Ticket. If the start time is later than the current -time by more than the allowable clock skew or if the INVALID flag is set in -the ticket, the KRB_AP_ERR_TKT_NYV error is returned. Otherwise, if the -current time is later than end time by more than the allowable clock skew, -the KRB_AP_ERR_TKT_EXPIRED error is returned. - -If all these checks succeed without an error, the server is assured that the -client possesses the credentials of the principal named in the ticket and -thus, the client has been authenticated to the server. See section A.10 for -pseudocode. - -Passing these checks provides only authentication of the named principal; it -does not imply authorization to use the named service. Applications must -make a separate authorization decisions based upon the authenticated name of -the user, the requested operation, local acces control information such as -that contained in a .k5login or .k5users file, and possibly a separate -distributed authorization service. - -3.2.4. Generation of a KRB_AP_REP message - -Typically, a client's request will include both the authentication -information and its initial request in the same message, and the server need -not explicitly reply to the KRB_AP_REQ. However, if mutual authentication -(not only authenticating the client to the server, but also the server to -the client) is being performed, the KRB_AP_REQ message will have -MUTUAL-REQUIRED set in its ap-options field, and a KRB_AP_REP message is -required in response. As with the error message, this message may be -encapsulated in the application protocol if its "raw" form is not acceptable -to the application's protocol. The timestamp and microsecond field used in -the reply must be the client's timestamp and microsecond field (as provided -in the authenticator)[12]. If a sequence number is to be included, it should -be randomly chosen as described above for the authenticator. A subkey may be - -Neuman, Ts'o, Kohl Expires: 25 December, -1999 - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, -1999 - -included if the server desires to negotiate a different subkey. The -KRB_AP_REP message is encrypted in the session key extracted from the -ticket. See section A.11 for pseudocode. - -3.2.5. Receipt of KRB_AP_REP message - -If a KRB_AP_REP message is returned, the client uses the session key from -the credentials obtained for the server[13] to decrypt the message, and -verifies that the timestamp and microsecond fields match those in the -Authenticator it sent to the server. If they match, then the client is -assured that the server is genuine. The sequence number and subkey (if -present) are retained for later use. See section A.12 for pseudocode. - -3.2.6. Using the encryption key - -After the KRB_AP_REQ/KRB_AP_REP exchange has occurred, the client and server -share an encryption key which can be used by the application. The 'true -session key' to be used for KRB_PRIV, KRB_SAFE, or other -application-specific uses may be chosen by the application based on the -subkeys in the KRB_AP_REP message and the authenticator[14]. In some cases, -the use of this session key will be implicit in the protocol; in others the -method of use must be chosen from several alternatives. We leave the -protocol negotiations of how to use the key (e.g. selecting an encryption or -checksum type) to the application programmer; the Kerberos protocol does not -constrain the implementation options, but an example of how this might be -done follows. - -One way that an application may choose to negotiate a key to be used for -subequent integrity and privacy protection is for the client to propose a -key in the subkey field of the authenticator. The server can then choose a -key using the proposed key from the client as input, returning the new -subkey in the subkey field of the application reply. This key could then be -used for subsequent communication. To make this example more concrete, if -the encryption method in use required a 56 bit key, and for whatever reason, -one of the parties was prevented from using a key with more than 40 unknown -bits, this method would allow the the party which is prevented from using -more than 40 bits to either propose (if the client) an initial key with a -known quantity for 16 of those bits, or to mask 16 of the bits (if the -server) with the known quantity. The application implementor is warned, -however, that this is only an example, and that an analysis of the -particular crytosystem to be used, and the reasons for limiting the key -length, must be made before deciding whether it is acceptable to mask bits -of the key. - -With both the one-way and mutual authentication exchanges, the peers should -take care not to send sensitive information to each other without proper -assurances. In particular, applications that require privacy or integrity -should use the KRB_AP_REP response from the server to client to assure both -client and server of their peer's identity. If an application protocol -requires privacy of its messages, it can use the KRB_PRIV message (section -3.5). The KRB_SAFE message (section 3.4) can be used to assure integrity. - - -Neuman, Ts'o, Kohl Expires: 25 December, -1999 - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, -1999 - -3.3. The Ticket-Granting Service (TGS) Exchange - - Summary - Message direction Message type Section - 1. Client to Kerberos KRB_TGS_REQ 5.4.1 - 2. Kerberos to client KRB_TGS_REP or 5.4.2 - KRB_ERROR 5.9.1 - -The TGS exchange between a client and the Kerberos Ticket-Granting Server is -initiated by a client when it wishes to obtain authentication credentials -for a given server (which might be registered in a remote realm), when it -wishes to renew or validate an existing ticket, or when it wishes to obtain -a proxy ticket. In the first case, the client must already have acquired a -ticket for the Ticket-Granting Service using the AS exchange (the -ticket-granting ticket is usually obtained when a client initially -authenticates to the system, such as when a user logs in). The message -format for the TGS exchange is almost identical to that for the AS exchange. -The primary difference is that encryption and decryption in the TGS exchange -does not take place under the client's key. Instead, the session key from -the ticket-granting ticket or renewable ticket, or sub-session key from an -Authenticator is used. As is the case for all application servers, expired -tickets are not accepted by the TGS, so once a renewable or ticket-granting -ticket expires, the client must use a separate exchange to obtain valid -tickets. - -The TGS exchange consists of two messages: A request (KRB_TGS_REQ) from the -client to the Kerberos Ticket-Granting Server, and a reply (KRB_TGS_REP or -KRB_ERROR). The KRB_TGS_REQ message includes information authenticating the -client plus a request for credentials. The authentication information -consists of the authentication header (KRB_AP_REQ) which includes the -client's previously obtained ticket-granting, renewable, or invalid ticket. -In the ticket-granting ticket and proxy cases, the request may include one -or more of: a list of network addresses, a collection of typed authorization -data to be sealed in the ticket for authorization use by the application -server, or additional tickets (the use of which are described later). The -TGS reply (KRB_TGS_REP) contains the requested credentials, encrypted in the -session key from the ticket-granting ticket or renewable ticket, or if -present, in the sub-session key from the Authenticator (part of the -authentication header). The KRB_ERROR message contains an error code and -text explaining what went wrong. The KRB_ERROR message is not encrypted. The -KRB_TGS_REP message contains information which can be used to detect -replays, and to associate it with the message to which it replies. The -KRB_ERROR message also contains information which can be used to associate -it with the message to which it replies, but the lack of encryption in the -KRB_ERROR message precludes the ability to detect replays or fabrications of -such messages. - -3.3.1. Generation of KRB_TGS_REQ message - -Before sending a request to the ticket-granting service, the client must -determine in which realm the application server is registered[15]. If the -client does not already possess a ticket-granting ticket for the appropriate -realm, then one must be obtained. This is first attempted by requesting a -ticket-granting ticket for the destination realm from a Kerberos server for -which the client does posess a ticket-granting ticket (using the KRB_TGS_REQ -message recursively). The Kerberos server may return a TGT for the desired -realm in which case one can proceed. Alternatively, the Kerberos server may -return a TGT for a realm which is 'closer' to the desired realm (further - -Neuman, Ts'o, Kohl Expires: 25 December, -1999 - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, -1999 - -along the standard hierarchical path), in which case this step must be -repeated with a Kerberos server in the realm specified in the returned TGT. -If neither are returned, then the request must be retried with a Kerberos -server for a realm higher in the hierarchy. This request will itself require -a ticket-granting ticket for the higher realm which must be obtained by -recursively applying these directions. - -Once the client obtains a ticket-granting ticket for the appropriate realm, -it determines which Kerberos servers serve that realm, and contacts one. The -list might be obtained through a configuration file or network service or it -may be generated from the name of the realm; as long as the secret keys -exchanged by realms are kept secret, only denial of service results from -using a false Kerberos server. - -As in the AS exchange, the client may specify a number of options in the -KRB_TGS_REQ message. The client prepares the KRB_TGS_REQ message, providing -an authentication header as an element of the padata field, and including -the same fields as used in the KRB_AS_REQ message along with several -optional fields: the enc-authorization-data field for application server use -and additional tickets required by some options. - -In preparing the authentication header, the client can select a sub-session -key under which the response from the Kerberos server will be encrypted[16]. -If the sub-session key is not specified, the session key from the -ticket-granting ticket will be used. If the enc-authorization-data is -present, it must be encrypted in the sub-session key, if present, from the -authenticator portion of the authentication header, or if not present, using -the session key from the ticket-granting ticket. - -Once prepared, the message is sent to a Kerberos server for the destination -realm. See section A.5 for pseudocode. - -3.3.2. Receipt of KRB_TGS_REQ message - -The KRB_TGS_REQ message is processed in a manner similar to the KRB_AS_REQ -message, but there are many additional checks to be performed. First, the -Kerberos server must determine which server the accompanying ticket is for -and it must select the appropriate key to decrypt it. For a normal -KRB_TGS_REQ message, it will be for the ticket granting service, and the -TGS's key will be used. If the TGT was issued by another realm, then the -appropriate inter-realm key must be used. If the accompanying ticket is not -a ticket granting ticket for the current realm, but is for an application -server in the current realm, the RENEW, VALIDATE, or PROXY options are -specified in the request, and the server for which a ticket is requested is -the server named in the accompanying ticket, then the KDC will decrypt the -ticket in the authentication header using the key of the server for which it -was issued. If no ticket can be found in the padata field, the -KDC_ERR_PADATA_TYPE_NOSUPP error is returned. - -Once the accompanying ticket has been decrypted, the user-supplied checksum -in the Authenticator must be verified against the contents of the request, -and the message rejected if the checksums do not match (with an error code -of KRB_AP_ERR_MODIFIED) or if the checksum is not keyed or not -collision-proof (with an error code of KRB_AP_ERR_INAPP_CKSUM). If the -checksum type is not supported, the KDC_ERR_SUMTYPE_NOSUPP error is -returned. If the authorization-data are present, they are decrypted using -the sub-session key from the Authenticator. - -If any of the decryptions indicate failed integrity checks, the -KRB_AP_ERR_BAD_INTEGRITY error is returned. - -Neuman, Ts'o, Kohl Expires: 25 December, -1999 - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, -1999 - -3.3.3. Generation of KRB_TGS_REP message - -The KRB_TGS_REP message shares its format with the KRB_AS_REP (KRB_KDC_REP), -but with its type field set to KRB_TGS_REP. The detailed specification is in -section 5.4.2. - -The response will include a ticket for the requested server. The Kerberos -database is queried to retrieve the record for the requested server -(including the key with which the ticket will be encrypted). If the request -is for a ticket granting ticket for a remote realm, and if no key is shared -with the requested realm, then the Kerberos server will select the realm -"closest" to the requested realm with which it does share a key, and use -that realm instead. This is the only case where the response from the KDC -will be for a different server than that requested by the client. - -By default, the address field, the client's name and realm, the list of -transited realms, the time of initial authentication, the expiration time, -and the authorization data of the newly-issued ticket will be copied from -the ticket-granting ticket (TGT) or renewable ticket. If the transited field -needs to be updated, but the transited type is not supported, the -KDC_ERR_TRTYPE_NOSUPP error is returned. - -If the request specifies an endtime, then the endtime of the new ticket is -set to the minimum of (a) that request, (b) the endtime from the TGT, and -(c) the starttime of the TGT plus the minimum of the maximum life for the -application server and the maximum life for the local realm (the maximum -life for the requesting principal was already applied when the TGT was -issued). If the new ticket is to be a renewal, then the endtime above is -replaced by the minimum of (a) the value of the renew_till field of the -ticket and (b) the starttime for the new ticket plus the life -(endtime-starttime) of the old ticket. - -If the FORWARDED option has been requested, then the resulting ticket will -contain the addresses specified by the client. This option will only be -honored if the FORWARDABLE flag is set in the TGT. The PROXY option is -similar; the resulting ticket will contain the addresses specified by the -client. It will be honored only if the PROXIABLE flag in the TGT is set. The -PROXY option will not be honored on requests for additional ticket-granting -tickets. - -If the requested start time is absent, indicates a time in the past, or is -within the window of acceptable clock skew for the KDC and the POSTDATE -option has not been specified, then the start time of the ticket is set to -the authentication server's current time. If it indicates a time in the -future beyond the acceptable clock skew, but the POSTDATED option has not -been specified or the MAY-POSTDATE flag is not set in the TGT, then the -error KDC_ERR_CANNOT_POSTDATE is returned. Otherwise, if the ticket-granting -ticket has the MAY-POSTDATE flag set, then the resulting ticket will be -postdated and the requested starttime is checked against the policy of the -local realm. If acceptable, the ticket's start time is set as requested, and -the INVALID flag is set. The postdated ticket must be validated before use -by presenting it to the KDC after the starttime has been reached. However, -in no case may the starttime, endtime, or renew-till time of a newly-issued -postdated ticket extend beyond the renew-till time of the ticket-granting -ticket. - - -Neuman, Ts'o, Kohl Expires: 25 December, -1999 - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, -1999 - -If the ENC-TKT-IN-SKEY option has been specified and an additional ticket -has been included in the request, the KDC will decrypt the additional ticket -using the key for the server to which the additional ticket was issued and -verify that it is a ticket-granting ticket. If the name of the requested -server is missing from the request, the name of the client in the additional -ticket will be used. Otherwise the name of the requested server will be -compared to the name of the client in the additional ticket and if -different, the request will be rejected. If the request succeeds, the -session key from the additional ticket will be used to encrypt the new -ticket that is issued instead of using the key of the server for which the -new ticket will be used[17]. - -If the name of the server in the ticket that is presented to the KDC as part -of the authentication header is not that of the ticket-granting server -itself, the server is registered in the realm of the KDC, and the RENEW -option is requested, then the KDC will verify that the RENEWABLE flag is set -in the ticket, that the INVALID flag is not set in the ticket, and that the -renew_till time is still in the future. If the VALIDATE option is rqeuested, -the KDC will check that the starttime has passed and the INVALID flag is -set. If the PROXY option is requested, then the KDC will check that the -PROXIABLE flag is set in the ticket. If the tests succeed, and the ticket -passes the hotlist check described in the next paragraph, the KDC will issue -the appropriate new ticket. - -3.3.3.1. Checking for revoked tickets - -Whenever a request is made to the ticket-granting server, the presented -ticket(s) is(are) checked against a hot-list of tickets which have been -canceled. This hot-list might be implemented by storing a range of issue -timestamps for 'suspect tickets'; if a presented ticket had an authtime in -that range, it would be rejected. In this way, a stolen ticket-granting -ticket or renewable ticket cannot be used to gain additional tickets -(renewals or otherwise) once the theft has been reported. Any normal ticket -obtained before it was reported stolen will still be valid (because they -require no interaction with the KDC), but only until their normal expiration -time. - -The ciphertext part of the response in the KRB_TGS_REP message is encrypted -in the sub-session key from the Authenticator, if present, or the session -key key from the ticket-granting ticket. It is not encrypted using the -client's secret key. Furthermore, the client's key's expiration date and the -key version number fields are left out since these values are stored along -with the client's database record, and that record is not needed to satisfy -a request based on a ticket-granting ticket. See section A.6 for pseudocode. - -3.3.3.2. Encoding the transited field - -If the identity of the server in the TGT that is presented to the KDC as -part of the authentication header is that of the ticket-granting service, -but the TGT was issued from another realm, the KDC will look up the -inter-realm key shared with that realm and use that key to decrypt the -ticket. If the ticket is valid, then the KDC will honor the request, subject -to the constraints outlined above in the section describing the AS exchange. -The realm part of the client's identity will be taken from the -ticket-granting ticket. The name of the realm that issued the -ticket-granting ticket will be added to the transited field of the ticket to -be issued. This is accomplished by reading the transited field from the -ticket-granting ticket (which is treated as an unordered set of realm - -Neuman, Ts'o, Kohl Expires: 25 December, -1999 - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, -1999 - -names), adding the new realm to the set, then constructing and writing out -its encoded (shorthand) form (this may involve a rearrangement of the -existing encoding). - -Note that the ticket-granting service does not add the name of its own -realm. Instead, its responsibility is to add the name of the previous realm. -This prevents a malicious Kerberos server from intentionally leaving out its -own name (it could, however, omit other realms' names). - -The names of neither the local realm nor the principal's realm are to be -included in the transited field. They appear elsewhere in the ticket and -both are known to have taken part in authenticating the principal. Since the -endpoints are not included, both local and single-hop inter-realm -authentication result in a transited field that is empty. - -Because the name of each realm transited is added to this field, it might -potentially be very long. To decrease the length of this field, its contents -are encoded. The initially supported encoding is optimized for the normal -case of inter-realm communication: a hierarchical arrangement of realms -using either domain or X.500 style realm names. This encoding (called -DOMAIN-X500-COMPRESS) is now described. - -Realm names in the transited field are separated by a ",". The ",", "\", -trailing "."s, and leading spaces (" ") are special characters, and if they -are part of a realm name, they must be quoted in the transited field by -preced- ing them with a "\". - -A realm name ending with a "." is interpreted as being prepended to the -previous realm. For example, we can encode traversal of EDU, MIT.EDU, -ATHENA.MIT.EDU, WASHINGTON.EDU, and CS.WASHINGTON.EDU as: - - "EDU,MIT.,ATHENA.,WASHINGTON.EDU,CS.". - -Note that if ATHENA.MIT.EDU, or CS.WASHINGTON.EDU were end-points, that they -would not be included in this field, and we would have: - - "EDU,MIT.,WASHINGTON.EDU" - -A realm name beginning with a "/" is interpreted as being appended to the -previous realm[18]. If it is to stand by itself, then it should be preceded -by a space (" "). For example, we can encode traversal of /COM/HP/APOLLO, -/COM/HP, /COM, and /COM/DEC as: - - "/COM,/HP,/APOLLO, /COM/DEC". - -Like the example above, if /COM/HP/APOLLO and /COM/DEC are endpoints, they -they would not be included in this field, and we would have: - - "/COM,/HP" - -A null subfield preceding or following a "," indicates that all realms -between the previous realm and the next realm have been traversed[19]. Thus, -"," means that all realms along the path between the client and the server -have been traversed. ",EDU, /COM," means that that all realms from the -client's realm up to EDU (in a domain style hierarchy) have been traversed, -and that everything from /COM down to the server's realm in an X.500 style -has also been traversed. This could occur if the EDU realm in one hierarchy -shares an inter-realm key directly with the /COM realm in another hierarchy. - - -Neuman, Ts'o, Kohl Expires: 25 December, -1999 - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, -1999 - -3.3.4. Receipt of KRB_TGS_REP message - -When the KRB_TGS_REP is received by the client, it is processed in the same -manner as the KRB_AS_REP processing described above. The primary difference -is that the ciphertext part of the response must be decrypted using the -session key from the ticket-granting ticket rather than the client's secret -key. See section A.7 for pseudocode. - -3.4. The KRB_SAFE Exchange - -The KRB_SAFE message may be used by clients requiring the ability to detect -modifications of messages they exchange. It achieves this by including a -keyed collision-proof checksum of the user data and some control -information. The checksum is keyed with an encryption key (usually the last -key negotiated via subkeys, or the session key if no negotiation has -occured). - -3.4.1. Generation of a KRB_SAFE message - -When an application wishes to send a KRB_SAFE message, it collects its data -and the appropriate control information and computes a checksum over them. -The checksum algorithm should be a keyed one-way hash function (such as the -RSA- MD5-DES checksum algorithm specified in section 6.4.5, or the DES MAC), -generated using the sub-session key if present, or the session key. -Different algorithms may be selected by changing the checksum type in the -message. Unkeyed or non-collision-proof checksums are not suitable for this -use. - -The control information for the KRB_SAFE message includes both a timestamp -and a sequence number. The designer of an application using the KRB_SAFE -message must choose at least one of the two mechanisms. This choice should -be based on the needs of the application protocol. - -Sequence numbers are useful when all messages sent will be received by one's -peer. Connection state is presently required to maintain the session key, so -maintaining the next sequence number should not present an additional -problem. - -If the application protocol is expected to tolerate lost messages without -them being resent, the use of the timestamp is the appropriate replay -detection mechanism. Using timestamps is also the appropriate mechanism for -multi-cast protocols where all of one's peers share a common sub-session -key, but some messages will be sent to a subset of one's peers. - -After computing the checksum, the client then transmits the information and -checksum to the recipient in the message format specified in section 5.6.1. - -3.4.2. Receipt of KRB_SAFE message - -When an application receives a KRB_SAFE message, it verifies it as follows. -If any error occurs, an error code is reported for use by the application. - -The message is first checked by verifying that the protocol version and type -fields match the current version and KRB_SAFE, respectively. A mismatch -generates a KRB_AP_ERR_BADVERSION or KRB_AP_ERR_MSG_TYPE error. The -application verifies that the checksum used is a collision-proof keyed -checksum, and if it is not, a KRB_AP_ERR_INAPP_CKSUM error is generated. If -the sender's address was included in the control information, the recipient - -Neuman, Ts'o, Kohl Expires: 25 December, -1999 - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, -1999 - -verifies that the operating system's report of the sender's address matches -the sender's address in the message, and (if a recipient address is -specified or the recipient requires an address) that one of the recipient's -addresses appears as the recipient's address in the message. A failed match -for either case generates a KRB_AP_ERR_BADADDR error. Then the timestamp and -usec and/or the sequence number fields are checked. If timestamp and usec -are expected and not present, or they are present but not current, the -KRB_AP_ERR_SKEW error is generated. If the server name, along with the -client name, time and microsecond fields from the Authenticator match any -recently-seen (sent or received[20] ) such tuples, the KRB_AP_ERR_REPEAT -error is generated. If an incorrect sequence number is included, or a -sequence number is expected but not present, the KRB_AP_ERR_BADORDER error -is generated. If neither a time-stamp and usec or a sequence number is -present, a KRB_AP_ERR_MODIFIED error is generated. Finally, the checksum is -computed over the data and control information, and if it doesn't match the -received checksum, a KRB_AP_ERR_MODIFIED error is generated. - -If all the checks succeed, the application is assured that the message was -generated by its peer and was not modi- fied in transit. - -3.5. The KRB_PRIV Exchange - -The KRB_PRIV message may be used by clients requiring confidentiality and -the ability to detect modifications of exchanged messages. It achieves this -by encrypting the messages and adding control information. - -3.5.1. Generation of a KRB_PRIV message - -When an application wishes to send a KRB_PRIV message, it collects its data -and the appropriate control information (specified in section 5.7.1) and -encrypts them under an encryption key (usually the last key negotiated via -subkeys, or the session key if no negotiation has occured). As part of the -control information, the client must choose to use either a timestamp or a -sequence number (or both); see the discussion in section 3.4.1 for -guidelines on which to use. After the user data and control information are -encrypted, the client transmits the ciphertext and some 'envelope' -information to the recipient. - -3.5.2. Receipt of KRB_PRIV message - -When an application receives a KRB_PRIV message, it verifies it as follows. -If any error occurs, an error code is reported for use by the application. - -The message is first checked by verifying that the protocol version and type -fields match the current version and KRB_PRIV, respectively. A mismatch -generates a KRB_AP_ERR_BADVERSION or KRB_AP_ERR_MSG_TYPE error. The -application then decrypts the ciphertext and processes the resultant -plaintext. If decryption shows the data to have been modified, a -KRB_AP_ERR_BAD_INTEGRITY error is generated. If the sender's address was -included in the control information, the recipient verifies that the -operating system's report of the sender's address matches the sender's -address in the message, and (if a recipient address is specified or the -recipient requires an address) that one of the recipient's addresses appears -as the recipient's address in the message. A failed match for either case -generates a KRB_AP_ERR_BADADDR error. Then the timestamp and usec and/or the -sequence number fields are checked. If timestamp and usec are expected and -not present, or they are present but not current, the KRB_AP_ERR_SKEW error -is generated. If the server name, along with the client name, time and - -Neuman, Ts'o, Kohl Expires: 25 December, -1999 - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, -1999 - -microsecond fields from the Authenticator match any recently-seen such -tuples, the KRB_AP_ERR_REPEAT error is generated. If an incorrect sequence -number is included, or a sequence number is expected but not present, the -KRB_AP_ERR_BADORDER error is generated. If neither a time-stamp and usec or -a sequence number is present, a KRB_AP_ERR_MODIFIED error is generated. - -If all the checks succeed, the application can assume the message was -generated by its peer, and was securely transmitted (without intruders able -to see the unencrypted contents). - -3.6. The KRB_CRED Exchange - -The KRB_CRED message may be used by clients requiring the ability to send -Kerberos credentials from one host to another. It achieves this by sending -the tickets together with encrypted data containing the session keys and -other information associated with the tickets. - -3.6.1. Generation of a KRB_CRED message - -When an application wishes to send a KRB_CRED message it first (using the -KRB_TGS exchange) obtains credentials to be sent to the remote host. It then -constructs a KRB_CRED message using the ticket or tickets so obtained, -placing the session key needed to use each ticket in the key field of the -corresponding KrbCredInfo sequence of the encrypted part of the the KRB_CRED -message. - -Other information associated with each ticket and obtained during the -KRB_TGS exchange is also placed in the corresponding KrbCredInfo sequence in -the encrypted part of the KRB_CRED message. The current time and, if -specifically required by the application the nonce, s-address, and r-address -fields, are placed in the encrypted part of the KRB_CRED message which is -then encrypted under an encryption key previosuly exchanged in the KRB_AP -exchange (usually the last key negotiated via subkeys, or the session key if -no negotiation has occured). - -3.6.2. Receipt of KRB_CRED message - -When an application receives a KRB_CRED message, it verifies it. If any -error occurs, an error code is reported for use by the application. The -message is verified by checking that the protocol version and type fields -match the current version and KRB_CRED, respectively. A mismatch generates a -KRB_AP_ERR_BADVERSION or KRB_AP_ERR_MSG_TYPE error. The application then -decrypts the ciphertext and processes the resultant plaintext. If decryption -shows the data to have been modified, a KRB_AP_ERR_BAD_INTEGRITY error is -generated. - -If present or required, the recipient verifies that the operating system's -report of the sender's address matches the sender's address in the message, -and that one of the recipient's addresses appears as the recipient's address -in the message. A failed match for either case generates a -KRB_AP_ERR_BADADDR error. The timestamp and usec fields (and the nonce field -if required) are checked next. If the timestamp and usec are not present, or -they are present but not current, the KRB_AP_ERR_SKEW error is generated. - -If all the checks succeed, the application stores each of the new tickets in -its ticket cache together with the session key and other information in the -corresponding KrbCredInfo sequence from the encrypted part of the KRB_CRED -message. - - -Neuman, Ts'o, Kohl Expires: 25 December, -1999 - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, -1999 - -4. The Kerberos Database - -The Kerberos server must have access to a database contain- ing the -principal identifiers and secret keys of principals to be authenticated[21]. - -4.1. Database contents - -A database entry should contain at least the following fields: - -Field Value - -name Principal's identifier -key Principal's secret key -p_kvno Principal's key version -max_life Maximum lifetime for Tickets -max_renewable_life Maximum total lifetime for renewable Tickets - -The name field is an encoding of the principal's identifier. The key field -contains an encryption key. This key is the principal's secret key. (The key -can be encrypted before storage under a Kerberos "master key" to protect it -in case the database is compromised but the master key is not. In that case, -an extra field must be added to indicate the master key version used, see -below.) The p_kvno field is the key version number of the principal's secret -key. The max_life field contains the maximum allowable lifetime (endtime - -starttime) for any Ticket issued for this principal. The max_renewable_life -field contains the maximum allowable total lifetime for any renewable Ticket -issued for this principal. (See section 3.1 for a description of how these -lifetimes are used in determining the lifetime of a given Ticket.) - -A server may provide KDC service to several realms, as long as the database -representation provides a mechanism to distinguish between principal records -with identifiers which differ only in the realm name. - -When an application server's key changes, if the change is routine (i.e. not -the result of disclosure of the old key), the old key should be retained by -the server until all tickets that had been issued using that key have -expired. Because of this, it is possible for several keys to be active for a -single principal. Ciphertext encrypted in a principal's key is always tagged -with the version of the key that was used for encryption, to help the -recipient find the proper key for decryption. - -When more than one key is active for a particular principal, the principal -will have more than one record in the Kerberos database. The keys and key -version numbers will differ between the records (the rest of the fields may -or may not be the same). Whenever Kerberos issues a ticket, or responds to a -request for initial authentication, the most recent key (known by the -Kerberos server) will be used for encryption. This is the key with the -highest key version number. - - -Neuman, Ts'o, Kohl Expires: 25 December, -1999 - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, -1999 - -4.2. Additional fields - -Project Athena's KDC implementation uses additional fields in its database: - -Field Value - -K_kvno Kerberos' key version -expiration Expiration date for entry -attributes Bit field of attributes -mod_date Timestamp of last modification -mod_name Modifying principal's identifier - -The K_kvno field indicates the key version of the Kerberos master key under -which the principal's secret key is encrypted. - -After an entry's expiration date has passed, the KDC will return an error to -any client attempting to gain tickets as or for the principal. (A database -may want to maintain two expiration dates: one for the principal, and one -for the principal's current key. This allows password aging to work -independently of the principal's expiration date. However, due to the -limited space in the responses, the KDC must combine the key expiration and -principal expiration date into a single value called 'key_exp', which is -used as a hint to the user to take administrative action.) - -The attributes field is a bitfield used to govern the operations involving -the principal. This field might be useful in conjunction with user -registration procedures, for site-specific policy implementations (Project -Athena currently uses it for their user registration process controlled by -the system-wide database service, Moira [LGDSR87]), to identify whether a -principal can play the role of a client or server or both, to note whether a -server is appropriate trusted to recieve credentials delegated by a client, -or to identify the 'string to key' conversion algorithm used for a -principal's key[22]. Other bits are used to indicate that certain ticket -options should not be allowed in tickets encrypted under a principal's key -(one bit each): Disallow issuing postdated tickets, disallow issuing -forwardable tickets, disallow issuing tickets based on TGT authentication, -disallow issuing renewable tickets, disallow issuing proxiable tickets, and -disallow issuing tickets for which the principal is the server. - -The mod_date field contains the time of last modification of the entry, and -the mod_name field contains the name of the principal which last modified -the entry. - -4.3. Frequently Changing Fields - -Some KDC implementations may wish to maintain the last time that a request -was made by a particular principal. Information that might be maintained -includes the time of the last request, the time of the last request for a -ticket-granting ticket, the time of the last use of a ticket-granting -ticket, or other times. This information can then be returned to the user in -the last-req field (see section 5.2). - -Other frequently changing information that can be maintained is the latest -expiration time for any tickets that have been issued using each key. This -field would be used to indicate how long old keys must remain valid to allow -the continued use of outstanding tickets. - - -Neuman, Ts'o, Kohl Expires: 25 December, -1999 - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, -1999 - -4.4. Site Constants - -The KDC implementation should have the following configurable constants or -options, to allow an administrator to make and enforce policy decisions: - - * The minimum supported lifetime (used to determine whether the - KDC_ERR_NEVER_VALID error should be returned). This constant should - reflect reasonable expectations of round-trip time to the KDC, - encryption/decryption time, and processing time by the client and - target server, and it should allow for a minimum 'useful' lifetime. - * The maximum allowable total (renewable) lifetime of a ticket - (renew_till - starttime). - * The maximum allowable lifetime of a ticket (endtime - starttime). - * Whether to allow the issue of tickets with empty address fields - (including the ability to specify that such tickets may only be issued - if the request specifies some authorization_data). - * Whether proxiable, forwardable, renewable or post-datable tickets are - to be issued. - -5. Message Specifications - -The following sections describe the exact contents and encoding of protocol -messages and objects. The ASN.1 base definitions are presented in the first -subsection. The remaining subsections specify the protocol objects (tickets -and authenticators) and messages. Specification of encryption and checksum -techniques, and the fields related to them, appear in section 6. - -Optional field in ASN.1 sequences - -For optional integer value and date fields in ASN.1 sequences where a -default value has been specified, certain default values will not be allowed -in the encoding because these values will always be represented through -defaulting by the absence of the optional field. For example, one will not -send a microsecond zero value because one must make sure that there is only -one way to encode this value. - -Additional fields in ASN.1 sequences - -Implementations receiving Kerberos messages with additional fields present -in ASN.1 sequences should carry the those fields through, unmodified, when -the message is forwarded. Implementations should not drop such fields if the -sequence is reencoded. - -5.1. ASN.1 Distinguished Encoding Representation - -All uses of ASN.1 in Kerberos shall use the Distinguished Encoding -Representation of the data elements as described in the X.509 specification, -section 8.7 [X509-88]. - -5.3. ASN.1 Base Definitions - -The following ASN.1 base definitions are used in the rest of this section. -Note that since the underscore character (_) is not permitted in ASN.1 -names, the hyphen (-) is used in its place for the purposes of ASN.1 names. - -Realm ::= GeneralString -PrincipalName ::= SEQUENCE { - name-type[0] INTEGER, - name-string[1] SEQUENCE OF GeneralString -} - -Neuman, Ts'o, Kohl Expires: 25 December, -1999 - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, -1999 - -Kerberos realms are encoded as GeneralStrings. Realms shall not contain a -character with the code 0 (the ASCII NUL). Most realms will usually consist -of several components separated by periods (.), in the style of Internet -Domain Names, or separated by slashes (/) in the style of X.500 names. -Acceptable forms for realm names are specified in section 7. A PrincipalName -is a typed sequence of components consisting of the following sub-fields: - -name-type - This field specifies the type of name that follows. Pre-defined values - for this field are specified in section 7.2. The name-type should be - treated as a hint. Ignoring the name type, no two names can be the same - (i.e. at least one of the components, or the realm, must be different). - This constraint may be eliminated in the future. -name-string - This field encodes a sequence of components that form a name, each - component encoded as a GeneralString. Taken together, a PrincipalName - and a Realm form a principal identifier. Most PrincipalNames will have - only a few components (typically one or two). - -KerberosTime ::= GeneralizedTime - -- Specifying UTC time zone (Z) - -The timestamps used in Kerberos are encoded as GeneralizedTimes. An encoding -shall specify the UTC time zone (Z) and shall not include any fractional -portions of the seconds. It further shall not include any separators. -Example: The only valid format for UTC time 6 minutes, 27 seconds after 9 pm -on 6 November 1985 is 19851106210627Z. - -HostAddress ::= SEQUENCE { - addr-type[0] INTEGER, - address[1] OCTET STRING -} - -HostAddresses ::= SEQUENCE OF HostAddress - -The host adddress encodings consists of two fields: - -addr-type - This field specifies the type of address that follows. Pre-defined - values for this field are specified in section 8.1. -address - This field encodes a single address of type addr-type. - -The two forms differ slightly. HostAddress contains exactly one address; -HostAddresses contains a sequence of possibly many addresses. - -AuthorizationData ::= SEQUENCE OF SEQUENCE { - ad-type[0] INTEGER, - ad-data[1] OCTET STRING -} - -ad-data - This field contains authorization data to be interpreted according to - the value of the corresponding ad-type field. -ad-type - This field specifies the format for the ad-data subfield. All negative - values are reserved for local use. Non-negative values are reserved for - registered use. - - -Neuman, Ts'o, Kohl Expires: 25 December, -1999 - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, -1999 - -Each sequence of type and data is refered to as an authorization element. -Elements may be application specific, however, there is a common set of -recursive elements that should be understood by all implementations. These -elements contain other elements embedded within them, and the interpretation -of the encapsulating element determines which of the embedded elements must -be interpreted, and which may be ignored. Definitions for these common -elements may be found in Appendix B. - -TicketExtensions ::= SEQUENCE OF SEQUENCE { - te-type[0] INTEGER, - te-data[1] OCTET STRING -} - -te-data - This field contains opaque data that must be caried with the ticket to - support extensions to the Kerberos protocol including but not limited - to some forms of inter-realm key exchange and plaintext authorization - data. See appendix C for some common uses of this field. -te-type - This field specifies the format for the te-data subfield. All negative - values are reserved for local use. Non-negative values are reserved for - registered use. - -APOptions ::= BIT STRING - -- reserved(0), - -- use-session-key(1), - -- mutual-required(2) - -TicketFlags ::= BIT STRING - -- reserved(0), - -- forwardable(1), - -- forwarded(2), - -- proxiable(3), - -- proxy(4), - -- may-postdate(5), - -- postdated(6), - -- invalid(7), - -- renewable(8), - -- initial(9), - -- pre-authent(10), - -- hw-authent(11), - -- transited-policy-checked(12), - -- ok-as-delegate(13) - -KDCOptions ::= BIT STRING - -- reserved(0), - -- forwardable(1), - -- forwarded(2), - -- proxiable(3), - -- proxy(4), - -- allow-postdate(5), - -- postdated(6), - -- unused7(7), - -- renewable(8), - -- unused9(9), - -- unused10(10), - -Neuman, Ts'o, Kohl Expires: 25 December, -1999 - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, -1999 - - -- unused11(11), - -- unused12(12), - -- unused13(13), - -- disable-transited-check(26), - -- renewable-ok(27), - -- enc-tkt-in-skey(28), - -- renew(30), - -- validate(31) - -ASN.1 Bit strings have a length and a value. When used in Kerberos for the -APOptions, TicketFlags, and KDCOptions, the length of the bit string on -generated values should be the smallest number of bits needed to include the -highest order bit that is set (1), but in no case less than 32 bits. The -ASN.1 representation of the bit strings uses unnamed bits, with the meaning -of the individual bits defined by the comments in the specification above. -Implementations should accept values of bit strings of any length and treat -the value of flags corresponding to bits beyond the end of the bit string as -if the bit were reset (0). Comparison of bit strings of different length -should treat the smaller string as if it were padded with zeros beyond the -high order bits to the length of the longer string[23]. - -LastReq ::= SEQUENCE OF SEQUENCE { - lr-type[0] INTEGER, - lr-value[1] KerberosTime -} - -lr-type - This field indicates how the following lr-value field is to be - interpreted. Negative values indicate that the information pertains - only to the responding server. Non-negative values pertain to all - servers for the realm. If the lr-type field is zero (0), then no - information is conveyed by the lr-value subfield. If the absolute value - of the lr-type field is one (1), then the lr-value subfield is the time - of last initial request for a TGT. If it is two (2), then the lr-value - subfield is the time of last initial request. If it is three (3), then - the lr-value subfield is the time of issue for the newest - ticket-granting ticket used. If it is four (4), then the lr-value - subfield is the time of the last renewal. If it is five (5), then the - lr-value subfield is the time of last request (of any type). If it is - (6), then the lr-value subfield is the time when the password will - expire. -lr-value - This field contains the time of the last request. the time must be - interpreted according to the contents of the accompanying lr-type - subfield. - -See section 6 for the definitions of Checksum, ChecksumType, EncryptedData, -EncryptionKey, EncryptionType, and KeyType. - -5.3. Tickets and Authenticators - -This section describes the format and encryption parameters for tickets and -authenticators. When a ticket or authenticator is included in a protocol -message it is treated as an opaque object. - - -Neuman, Ts'o, Kohl Expires: 25 December, -1999 - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, -1999 - -5.3.1. Tickets - -A ticket is a record that helps a client authenticate to a service. A Ticket -contains the following information: - -Ticket ::= [APPLICATION 1] SEQUENCE { - tkt-vno[0] INTEGER, - realm[1] Realm, - sname[2] PrincipalName, - enc-part[3] EncryptedData, - extensions[4] TicketExtensions OPTIONAL -} - --- Encrypted part of ticket -EncTicketPart ::= [APPLICATION 3] SEQUENCE { - flags[0] TicketFlags, - key[1] EncryptionKey, - crealm[2] Realm, - cname[3] PrincipalName, - transited[4] TransitedEncoding, - authtime[5] KerberosTime, - starttime[6] KerberosTime OPTIONAL, - endtime[7] KerberosTime, - renew-till[8] KerberosTime OPTIONAL, - caddr[9] HostAddresses OPTIONAL, - authorization-data[10] AuthorizationData OPTIONAL -} --- encoded Transited field -TransitedEncoding ::= SEQUENCE { - tr-type[0] INTEGER, -- must be -registered - contents[1] OCTET STRING -} - -The encoding of EncTicketPart is encrypted in the key shared by Kerberos and -the end server (the server's secret key). See section 6 for the format of -the ciphertext. - -tkt-vno - This field specifies the version number for the ticket format. This - document describes version number 5. -realm - This field specifies the realm that issued a ticket. It also serves to - identify the realm part of the server's principal identifier. Since a - Kerberos server can only issue tickets for servers within its realm, - the two will always be identical. -sname - This field specifies all components of the name part of the server's - identity, including those parts that identify a specific instance of a - service. -enc-part - This field holds the encrypted encoding of the EncTicketPart sequence. -extensions - [*** This change is still subject to discussion. Several alternatives - for this - including none at all - will be distributed to the cat and - krb-protocol mailing lists before the Oslo IETF, and an alternative - will be selected and the spec modified by 7/14/99 ***] This optional - field contains a sequence of extentions that may be used to carry - information that must be carried with the ticket to support several - -Neuman, Ts'o, Kohl Expires: 25 December, -1999 - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, -1999 - - extensions, including but not limited to plaintext authorization data, - tokens for exchanging inter-realm keys, and other information that must - be associated with a ticket for use by the application server. See - Appendix C for definitions of some common extensions. - - Note that some older versions of Kerberos did not support this field. - Because this is an optional field it will not break older clients, but - older clients might strip this field from the ticket before sending it - to the application server. This limits the usefulness of this ticket - field to environments where the ticket will not be parsed and - reconstructed by these older Kerberos clients. - - If it is known that the client will strip this field from the ticket, - as an interim measure the KDC may append this field to the end of the - enc-part of the ticket and append a traler indicating the lenght of the - appended extensions field. (this paragraph is open for discussion, - including the form of the traler). -flags - This field indicates which of various options were used or requested - when the ticket was issued. It is a bit-field, where the selected - options are indicated by the bit being set (1), and the unselected - options and reserved fields being reset (0). Bit 0 is the most - significant bit. The encoding of the bits is specified in section 5.2. - The flags are described in more detail above in section 2. The meanings - of the flags are: - - Bit(s) Name Description - - 0 RESERVED - Reserved for future expansion of this - field. - - 1 FORWARDABLE - The FORWARDABLE flag is normally only - interpreted by the TGS, and can be - ignored by end servers. When set, this - flag tells the ticket-granting server - that it is OK to issue a new ticket- - granting ticket with a different network - address based on the presented ticket. - - 2 FORWARDED - When set, this flag indicates that the - ticket has either been forwarded or was - issued based on authentication involving - a forwarded ticket-granting ticket. - - 3 PROXIABLE - The PROXIABLE flag is normally only - interpreted by the TGS, and can be - ignored by end servers. The PROXIABLE - flag has an interpretation identical to - that of the FORWARDABLE flag, except - that the PROXIABLE flag tells the - ticket-granting server that only non- - ticket-granting tickets may be issued - with different network addresses. - - -Neuman, Ts'o, Kohl Expires: 25 December, -1999 - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, -1999 - - 4 PROXY - When set, this flag indicates that a - ticket is a proxy. - - 5 MAY-POSTDATE - The MAY-POSTDATE flag is normally only - interpreted by the TGS, and can be - ignored by end servers. This flag tells - the ticket-granting server that a post- - dated ticket may be issued based on this - ticket-granting ticket. - - 6 POSTDATED - This flag indicates that this ticket has - been postdated. The end-service can - check the authtime field to see when the - original authentication occurred. - - 7 INVALID - This flag indicates that a ticket is - invalid, and it must be validated by the - KDC before use. Application servers - must reject tickets which have this flag - set. - - 8 RENEWABLE - The RENEWABLE flag is normally only - interpreted by the TGS, and can usually - be ignored by end servers (some particu- - larly careful servers may wish to disal- - low renewable tickets). A renewable - ticket can be used to obtain a replace- - ment ticket that expires at a later - date. - - 9 INITIAL - This flag indicates that this ticket was - issued using the AS protocol, and not - issued based on a ticket-granting - ticket. - - 10 PRE-AUTHENT - This flag indicates that during initial - authentication, the client was authenti- - cated by the KDC before a ticket was - issued. The strength of the pre- - authentication method is not indicated, - but is acceptable to the KDC. - - 11 HW-AUTHENT - This flag indicates that the protocol - employed for initial authentication - required the use of hardware expected to - be possessed solely by the named client. - The hardware authentication method is - selected by the KDC and the strength of - the method is not indicated. - - -Neuman, Ts'o, Kohl Expires: 25 December, -1999 - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, -1999 - - 12 TRANSITED This flag indicates that the KDC for the - POLICY-CHECKED realm has checked the transited field - against a realm defined policy for - trusted certifiers. If this flag is - reset (0), then the application server - must check the transited field itself, - and if unable to do so it must reject - the authentication. If the flag is set - (1) then the application server may skip - its own validation of the transited - field, relying on the validation - performed by the KDC. At its option the - application server may still apply its - own validation based on a separate - policy for acceptance. - - 13 OK-AS-DELEGATE This flag indicates that the server (not - the client) specified in the ticket has - been determined by policy of the realm - to be a suitable recipient of - delegation. A client can use the - presence of this flag to help it make a - decision whether to delegate credentials - (either grant a proxy or a forwarded - ticket granting ticket) to this server. - The client is free to ignore the value - of this flag. When setting this flag, - an administrator should consider the - Security and placement of the server on - which the service will run, as well as - whether the service requires the use of - delegated credentials. - - 14 ANONYMOUS - This flag indicates that the principal - named in the ticket is a generic princi- - pal for the realm and does not identify - the individual using the ticket. The - purpose of the ticket is only to - securely distribute a session key, and - not to identify the user. Subsequent - requests using the same ticket and ses- - sion may be considered as originating - from the same user, but requests with - the same username but a different ticket - are likely to originate from different - users. - - 15-31 RESERVED - Reserved for future use. - -key - This field exists in the ticket and the KDC response and is used to - pass the session key from Kerberos to the application server and the - client. The field's encoding is described in section 6.2. -crealm - This field contains the name of the realm in which the client is - registered and in which initial authentication took place. - -Neuman, Ts'o, Kohl Expires: 25 December, -1999 - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, -1999 - -cname - This field contains the name part of the client's principal identifier. -transited - This field lists the names of the Kerberos realms that took part in - authenticating the user to whom this ticket was issued. It does not - specify the order in which the realms were transited. See section - 3.3.3.2 for details on how this field encodes the traversed realms. - When the names of CA's are to be embedded inthe transited field (as - specified for some extentions to the protocol), the X.500 names of the - CA's should be mapped into items in the transited field using the - mapping defined by RFC2253. -authtime - This field indicates the time of initial authentication for the named - principal. It is the time of issue for the original ticket on which - this ticket is based. It is included in the ticket to provide - additional information to the end service, and to provide the necessary - information for implementation of a `hot list' service at the KDC. An - end service that is particularly paranoid could refuse to accept - tickets for which the initial authentication occurred "too far" in the - past. This field is also returned as part of the response from the KDC. - When returned as part of the response to initial authentication - (KRB_AS_REP), this is the current time on the Ker- beros server[24]. -starttime - This field in the ticket specifies the time after which the ticket is - valid. Together with endtime, this field specifies the life of the - ticket. If it is absent from the ticket, its value should be treated as - that of the authtime field. -endtime - This field contains the time after which the ticket will not be honored - (its expiration time). Note that individual services may place their - own limits on the life of a ticket and may reject tickets which have - not yet expired. As such, this is really an upper bound on the - expiration time for the ticket. -renew-till - This field is only present in tickets that have the RENEWABLE flag set - in the flags field. It indicates the maximum endtime that may be - included in a renewal. It can be thought of as the absolute expiration - time for the ticket, including all renewals. -caddr - This field in a ticket contains zero (if omitted) or more (if present) - host addresses. These are the addresses from which the ticket can be - used. If there are no addresses, the ticket can be used from any - location. The decision by the KDC to issue or by the end server to - accept zero-address tickets is a policy decision and is left to the - Kerberos and end-service administrators; they may refuse to issue or - accept such tickets. The suggested and default policy, however, is that - such tickets will only be issued or accepted when additional - information that can be used to restrict the use of the ticket is - included in the authorization_data field. Such a ticket is a - capability. - - Network addresses are included in the ticket to make it harder for an - attacker to use stolen credentials. Because the session key is not sent - over the network in cleartext, credentials can't be stolen simply by - listening to the network; an attacker has to gain access to the session - key (perhaps through operating system security breaches or a careless - user's unattended session) to make use of stolen tickets. - - -Neuman, Ts'o, Kohl Expires: 25 December, -1999 - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, -1999 - - It is important to note that the network address from which a - connection is received cannot be reliably determined. Even if it could - be, an attacker who has compromised the client's workstation could use - the credentials from there. Including the network addresses only makes - it more difficult, not impossible, for an attacker to walk off with - stolen credentials and then use them from a "safe" location. -authorization-data - The authorization-data field is used to pass authorization data from - the principal on whose behalf a ticket was issued to the application - service. If no authorization data is included, this field will be left - out. Experience has shown that the name of this field is confusing, and - that a better name for this field would be restrictions. Unfortunately, - it is not possible to change the name of this field at this time. - - This field contains restrictions on any authority obtained on the basis - of authentication using the ticket. It is possible for any principal in - posession of credentials to add entries to the authorization data field - since these entries further restrict what can be done with the ticket. - Such additions can be made by specifying the additional entries when a - new ticket is obtained during the TGS exchange, or they may be added - during chained delegation using the authorization data field of the - authenticator. - - Because entries may be added to this field by the holder of - credentials, it is not allowable for the presence of an entry in the - authorization data field of a ticket to amplify the priveleges one - would obtain from using a ticket. - - The data in this field may be specific to the end service; the field - will contain the names of service specific objects, and the rights to - those objects. The format for this field is described in section 5.2. - Although Kerberos is not concerned with the format of the contents of - the sub-fields, it does carry type information (ad-type). - - By using the authorization_data field, a principal is able to issue a - proxy that is valid for a specific purpose. For example, a client - wishing to print a file can obtain a file server proxy to be passed to - the print server. By specifying the name of the file in the - authorization_data field, the file server knows that the print server - can only use the client's rights when accessing the particular file to - be printed. - - A separate service providing authorization or certifying group - membership may be built using the authorization-data field. In this - case, the entity granting authorization (not the authorized entity), - obtains a ticket in its own name (e.g. the ticket is issued in the name - of a privelege server), and this entity adds restrictions on its own - authority and delegates the restricted authority through a proxy to the - client. The client would then present this authorization credential to - the application server separately from the authentication exchange. - - Similarly, if one specifies the authorization-data field of a proxy and - leaves the host addresses blank, the resulting ticket and session key - can be treated as a capability. See [Neu93] for some suggested uses of - this field. - - The authorization-data field is optional and does not have to be - included in a ticket. - - -Neuman, Ts'o, Kohl Expires: 25 December, -1999 - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, -1999 - -5.3.2. Authenticators - -An authenticator is a record sent with a ticket to a server to certify the -client's knowledge of the encryption key in the ticket, to help the server -detect replays, and to help choose a "true session key" to use with the -particular session. The encoding is encrypted in the ticket's session key -shared by the client and the server: - --- Unencrypted authenticator -Authenticator ::= [APPLICATION 2] SEQUENCE { - authenticator-vno[0] INTEGER, - crealm[1] Realm, - cname[2] PrincipalName, - cksum[3] Checksum OPTIONAL, - cusec[4] INTEGER, - ctime[5] KerberosTime, - subkey[6] EncryptionKey OPTIONAL, - seq-number[7] INTEGER OPTIONAL, - authorization-data[8] AuthorizationData OPTIONAL -} - -authenticator-vno - This field specifies the version number for the format of the - authenticator. This document specifies version 5. -crealm and cname - These fields are the same as those described for the ticket in section - 5.3.1. -cksum - This field contains a checksum of the the applica- tion data that - accompanies the KRB_AP_REQ. -cusec - This field contains the microsecond part of the client's timestamp. Its - value (before encryption) ranges from 0 to 999999. It often appears - along with ctime. The two fields are used together to specify a - reasonably accurate timestamp. -ctime - This field contains the current time on the client's host. -subkey - This field contains the client's choice for an encryption key which is - to be used to protect this specific application session. Unless an - application specifies otherwise, if this field is left out the session - key from the ticket will be used. -seq-number - This optional field includes the initial sequence number to be used by - the KRB_PRIV or KRB_SAFE messages when sequence numbers are used to - detect replays (It may also be used by application specific messages). - When included in the authenticator this field specifies the initial - sequence number for messages from the client to the server. When - included in the AP-REP message, the initial sequence number is that for - messages from the server to the client. When used in KRB_PRIV or - KRB_SAFE messages, it is incremented by one after each message is sent. - Sequence numbers fall in the range of 0 through 2^32 - 1 and wrap to - zero following the value 2^32 - 1. - - For sequence numbers to adequately support the detection of replays - they should be non-repeating, even across connection boundaries. The - initial sequence number should be random and uniformly distributed - -Neuman, Ts'o, Kohl Expires: 25 December, -1999 - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, -1999 - - across the full space of possible sequence numbers, so that it cannot - be guessed by an attacker and so that it and the successive sequence - numbers do not repeat other sequences. -authorization-data - This field is the same as described for the ticket in section 5.3.1. It - is optional and will only appear when additional restrictions are to be - placed on the use of a ticket, beyond those carried in the ticket - itself. - -5.4. Specifications for the AS and TGS exchanges - -This section specifies the format of the messages used in the exchange -between the client and the Kerberos server. The format of possible error -messages appears in section 5.9.1. - -5.4.1. KRB_KDC_REQ definition - -The KRB_KDC_REQ message has no type of its own. Instead, its type is one of -KRB_AS_REQ or KRB_TGS_REQ depending on whether the request is for an initial -ticket or an additional ticket. In either case, the message is sent from the -client to the Authentication Server to request credentials for a service. - -The message fields are: - -AS-REQ ::= [APPLICATION 10] KDC-REQ -TGS-REQ ::= [APPLICATION 12] KDC-REQ - -KDC-REQ ::= SEQUENCE { - pvno[1] INTEGER, - msg-type[2] INTEGER, - padata[3] SEQUENCE OF PA-DATA OPTIONAL, - req-body[4] KDC-REQ-BODY -} - -PA-DATA ::= SEQUENCE { - padata-type[1] INTEGER, - padata-value[2] OCTET STRING, - -- might be encoded AP-REQ -} - -KDC-REQ-BODY ::= SEQUENCE { - kdc-options[0] KDCOptions, - cname[1] PrincipalName OPTIONAL, - -- Used only in AS-REQ - realm[2] Realm, -- Server's realm - -- Also client's in AS-REQ - sname[3] PrincipalName OPTIONAL, - from[4] KerberosTime OPTIONAL, - till[5] KerberosTime OPTIONAL, - rtime[6] KerberosTime OPTIONAL, - nonce[7] INTEGER, - etype[8] SEQUENCE OF INTEGER, - -- EncryptionType, - -- in preference order - addresses[9] HostAddresses OPTIONAL, - enc-authorization-data[10] EncryptedData OPTIONAL, - -- Encrypted AuthorizationData - -- encoding - additional-tickets[11] SEQUENCE OF Ticket OPTIONAL -} - - -Neuman, Ts'o, Kohl Expires: 25 December, -1999 - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, -1999 - -The fields in this message are: - -pvno - This field is included in each message, and specifies the protocol - version number. This document specifies protocol version 5. -msg-type - This field indicates the type of a protocol message. It will almost - always be the same as the application identifier associated with a - message. It is included to make the identifier more readily accessible - to the application. For the KDC-REQ message, this type will be - KRB_AS_REQ or KRB_TGS_REQ. -padata - The padata (pre-authentication data) field contains a sequence of - authentication information which may be needed before credentials can - be issued or decrypted. In the case of requests for additional tickets - (KRB_TGS_REQ), this field will include an element with padata-type of - PA-TGS-REQ and data of an authentication header (ticket-granting ticket - and authenticator). The checksum in the authenticator (which must be - collision-proof) is to be computed over the KDC-REQ-BODY encoding. In - most requests for initial authentication (KRB_AS_REQ) and most replies - (KDC-REP), the padata field will be left out. - - This field may also contain information needed by certain extensions to - the Kerberos protocol. For example, it might be used to initially - verify the identity of a client before any response is returned. This - is accomplished with a padata field with padata-type equal to - PA-ENC-TIMESTAMP and padata-value defined as follows: - - padata-type ::= PA-ENC-TIMESTAMP - padata-value ::= EncryptedData -- PA-ENC-TS-ENC - - PA-ENC-TS-ENC ::= SEQUENCE { - patimestamp[0] KerberosTime, -- client's time - pausec[1] INTEGER OPTIONAL - } - - with patimestamp containing the client's time and pausec containing the - microseconds which may be omitted if a client will not generate more - than one request per second. The ciphertext (padata-value) consists of - the PA-ENC-TS-ENC sequence, encrypted using the client's secret key. - - [use-specified-kvno item is here for discussion and may be removed] It - may also be used by the client to specify the version of a key that is - being used for accompanying preauthentication, and/or which should be - used to encrypt the reply from the KDC. - - PA-USE-SPECIFIED-KVNO ::= Integer - - The KDC should only accept and abide by the value of the - use-specified-kvno preauthentication data field when the specified key - is still valid and until use of a new key is confirmed. This situation - is likely to occur primarily during the period during which an updated - key is propagating to other KDC's in a realm. - - The padata field can also contain information needed to help the KDC or - the client select the key needed for generating or decrypting the - response. This form of the padata is useful for supporting the use of - certain token cards with Kerberos. The details of such extensions are - specified in separate documents. See [Pat92] for additional uses of - this field. - -Neuman, Ts'o, Kohl Expires: 25 December, -1999 - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, -1999 - -padata-type - The padata-type element of the padata field indicates the way that the - padata-value element is to be interpreted. Negative values of - padata-type are reserved for unregistered use; non-negative values are - used for a registered interpretation of the element type. -req-body - This field is a placeholder delimiting the extent of the remaining - fields. If a checksum is to be calculated over the request, it is - calculated over an encoding of the KDC-REQ-BODY sequence which is - enclosed within the req-body field. -kdc-options - This field appears in the KRB_AS_REQ and KRB_TGS_REQ requests to the - KDC and indicates the flags that the client wants set on the tickets as - well as other information that is to modify the behavior of the KDC. - Where appropriate, the name of an option may be the same as the flag - that is set by that option. Although in most case, the bit in the - options field will be the same as that in the flags field, this is not - guaranteed, so it is not acceptable to simply copy the options field to - the flags field. There are various checks that must be made before - honoring an option anyway. - - The kdc_options field is a bit-field, where the selected options are - indicated by the bit being set (1), and the unselected options and - reserved fields being reset (0). The encoding of the bits is specified - in section 5.2. The options are described in more detail above in - section 2. The meanings of the options are: - - Bit(s) Name Description - 0 RESERVED - Reserved for future expansion of -this - field. - - 1 FORWARDABLE - The FORWARDABLE option indicates -that - the ticket to be issued is to have -its - forwardable flag set. It may only -be - set on the initial request, or in a -sub- - sequent request if the -ticket-granting - ticket on which it is based is also -for- - wardable. - - 2 FORWARDED - The FORWARDED option is only -specified - in a request to the -ticket-granting - server and will only be honored if -the - ticket-granting ticket in the -request - has its FORWARDABLE bit set. -This - option indicates that this is a -request - for forwarding. The address(es) of -the - host from which the resulting ticket -is - to be valid are included in -the - addresses field of the request. - - -Neuman, Ts'o, Kohl Expires: 25 December, -1999 - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, -1999 - - 3 PROXIABLE - The PROXIABLE option indicates that -the - ticket to be issued is to have its -prox- - iable flag set. It may only be set -on - the initial request, or in a -subsequent - request if the ticket-granting ticket -on - which it is based is also proxiable. - - 4 PROXY - The PROXY option indicates that this -is - a request for a proxy. This option -will - only be honored if the -ticket-granting - ticket in the request has its -PROXIABLE - bit set. The address(es) of the -host - from which the resulting ticket is to -be - valid are included in the -addresses - field of the request. - - 5 ALLOW-POSTDATE - The ALLOW-POSTDATE option indicates -that - the ticket to be issued is to have -its - MAY-POSTDATE flag set. It may only -be - set on the initial request, or in a -sub- - sequent request if the -ticket-granting - ticket on which it is based also has -its - MAY-POSTDATE flag set. - - 6 POSTDATED - The POSTDATED option indicates that -this - is a request for a postdated -ticket. - This option will only be honored if -the - ticket-granting ticket on which it -is - based has its MAY-POSTDATE flag -set. - The resulting ticket will also have -its - INVALID flag set, and that flag may -be - reset by a subsequent request to the -KDC - after the starttime in the ticket -has - been reached. - - 7 UNUSED - This option is presently unused. - - 8 RENEWABLE - The RENEWABLE option indicates that -the - ticket to be issued is to have -its - RENEWABLE flag set. It may only be -set - on the initial request, or when -the - ticket-granting ticket on which -the - request is based is also renewable. -If - this option is requested, then the -rtime - field in the request contains -the - desired absolute expiration time for -the - ticket. - - 9-13 UNUSED - These options are presently unused. - - -Neuman, Ts'o, Kohl Expires: 25 December, -1999 - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, -1999 - - 14 REQUEST-ANONYMOUS - The REQUEST-ANONYMOUS option -indicates - that the ticket to be issued is not -to - identify the user to which it -was - issued. Instead, the principal -identif- - ier is to be generic, as specified -by - the policy of the realm (e.g. -usually - anonymous@realm). The purpose of -the - ticket is only to securely distribute -a - session key, and not to identify -the - user. The ANONYMOUS flag on the -ticket - to be returned should be set. If -the - local realms policy does not -permit - anonymous credentials, the request is -to - be rejected. - - 15-25 RESERVED - Reserved for future use. - - 26 DISABLE-TRANSITED-CHECK - By default the KDC will check the - transited field of a ticket-granting- - ticket against the policy of the local - realm before it will issue derivative - tickets based on the ticket granting - ticket. If this flag is set in the - request, checking of the transited -field - is disabled. Tickets issued without -the - performance of this check will be -noted - by the reset (0) value of the - TRANSITED-POLICY-CHECKED flag, - indicating to the application server - that the tranisted field must be -checked - locally. KDC's are encouraged but not - required to honor the - DISABLE-TRANSITED-CHECK option. - - 27 RENEWABLE-OK - The RENEWABLE-OK option indicates that -a - renewable ticket will be acceptable if -a - ticket with the requested life -cannot - otherwise be provided. If a ticket -with - the requested life cannot be -provided, - then a renewable ticket may be -issued - with a renew-till equal to the -the - requested endtime. The value of -the - renew-till field may still be limited -by - local limits, or limits selected by -the - individual principal or server. - - 28 ENC-TKT-IN-SKEY - This option is used only by the -ticket- - granting service. The -ENC-TKT-IN-SKEY - option indicates that the ticket for -the - end server is to be encrypted in -the - session key from the additional -ticket- - granting ticket provided. - - -Neuman, Ts'o, Kohl Expires: 25 December, -1999 - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, -1999 - - 29 RESERVED - Reserved for future use. - - 30 RENEW - This option is used only by the -ticket- - granting service. The RENEW -option - indicates that the present request -is - for a renewal. The ticket provided -is - encrypted in the secret key for -the - server on which it is valid. -This - option will only be honored if -the - ticket to be renewed has its -RENEWABLE - flag set and if the time in its -renew- - till field has not passed. The -ticket - to be renewed is passed in the -padata - field as part of the -authentication - header. - - 31 VALIDATE - This option is used only by the -ticket- - granting service. The VALIDATE -option - indicates that the request is to -vali- - date a postdated ticket. It will -only - be honored if the ticket presented -is - postdated, presently has its -INVALID - flag set, and would be otherwise -usable - at this time. A ticket cannot be -vali- - dated before its starttime. The -ticket - presented for validation is encrypted -in - the key of the server for which it -is - valid and is passed in the padata -field - as part of the authentication header. - -cname and sname - These fields are the same as those described for the ticket in section - 5.3.1. sname may only be absent when the ENC-TKT-IN-SKEY option is - specified. If absent, the name of the server is taken from the name of - the client in the ticket passed as additional-tickets. -enc-authorization-data - The enc-authorization-data, if present (and it can only be present in - the TGS_REQ form), is an encoding of the desired authorization-data - encrypted under the sub-session key if present in the Authenticator, or - alternatively from the session key in the ticket-granting ticket, both - from the padata field in the KRB_AP_REQ. -realm - This field specifies the realm part of the server's principal - identifier. In the AS exchange, this is also the realm part of the - client's principal identifier. -from - This field is included in the KRB_AS_REQ and KRB_TGS_REQ ticket - requests when the requested ticket is to be postdated. It specifies the - desired start time for the requested ticket. If this field is omitted - then the KDC should use the current time instead. -till - This field contains the expiration date requested by the client in a - ticket request. It is optional and if omitted the requested ticket is - to have the maximum endtime permitted according to KDC policy for the - parties to the authentication exchange as limited by expiration date of - the ticket granting ticket or other preauthentication credentials. - -Neuman, Ts'o, Kohl Expires: 25 December, -1999 - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, -1999 - -rtime - This field is the requested renew-till time sent from a client to the - KDC in a ticket request. It is optional. -nonce - This field is part of the KDC request and response. It it intended to - hold a random number generated by the client. If the same number is - included in the encrypted response from the KDC, it provides evidence - that the response is fresh and has not been replayed by an attacker. - Nonces must never be re-used. Ideally, it should be generated randomly, - but if the correct time is known, it may suffice[25]. -etype - This field specifies the desired encryption algorithm to be used in the - response. -addresses - This field is included in the initial request for tickets, and - optionally included in requests for additional tickets from the - ticket-granting server. It specifies the addresses from which the - requested ticket is to be valid. Normally it includes the addresses for - the client's host. If a proxy is requested, this field will contain - other addresses. The contents of this field are usually copied by the - KDC into the caddr field of the resulting ticket. -additional-tickets - Additional tickets may be optionally included in a request to the - ticket-granting server. If the ENC-TKT-IN-SKEY option has been - specified, then the session key from the additional ticket will be used - in place of the server's key to encrypt the new ticket. If more than - one option which requires additional tickets has been specified, then - the additional tickets are used in the order specified by the ordering - of the options bits (see kdc-options, above). - -The application code will be either ten (10) or twelve (12) depending on -whether the request is for an initial ticket (AS-REQ) or for an additional -ticket (TGS-REQ). - -The optional fields (addresses, authorization-data and additional-tickets) -are only included if necessary to perform the operation specified in the -kdc-options field. - -It should be noted that in KRB_TGS_REQ, the protocol version number appears -twice and two different message types appear: the KRB_TGS_REQ message -contains these fields as does the authentication header (KRB_AP_REQ) that is -passed in the padata field. - -5.4.2. KRB_KDC_REP definition - -The KRB_KDC_REP message format is used for the reply from the KDC for either -an initial (AS) request or a subsequent (TGS) request. There is no message -type for KRB_KDC_REP. Instead, the type will be either KRB_AS_REP or -KRB_TGS_REP. The key used to encrypt the ciphertext part of the reply -depends on the message type. For KRB_AS_REP, the ciphertext is encrypted in -the client's secret key, and the client's key version number is included in -the key version number for the encrypted data. For KRB_TGS_REP, the -ciphertext is encrypted in the sub-session key from the Authenticator, or if -absent, the session key from the ticket-granting ticket used in the request. -In that case, no version number will be present in the EncryptedData -sequence. - - -Neuman, Ts'o, Kohl Expires: 25 December, -1999 - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, -1999 - -The KRB_KDC_REP message contains the following fields: - -AS-REP ::= [APPLICATION 11] KDC-REP -TGS-REP ::= [APPLICATION 13] KDC-REP - -KDC-REP ::= SEQUENCE { - pvno[0] INTEGER, - msg-type[1] INTEGER, - padata[2] SEQUENCE OF PA-DATA OPTIONAL, - crealm[3] Realm, - cname[4] PrincipalName, - ticket[5] Ticket, - enc-part[6] EncryptedData -} - -EncASRepPart ::= [APPLICATION 25[27]] EncKDCRepPart -EncTGSRepPart ::= [APPLICATION 26] EncKDCRepPart - -EncKDCRepPart ::= SEQUENCE { - key[0] EncryptionKey, - last-req[1] LastReq, - nonce[2] INTEGER, - key-expiration[3] KerberosTime OPTIONAL, - flags[4] TicketFlags, - authtime[5] KerberosTime, - starttime[6] KerberosTime OPTIONAL, - endtime[7] KerberosTime, - renew-till[8] KerberosTime OPTIONAL, - srealm[9] Realm, - sname[10] PrincipalName, - caddr[11] HostAddresses OPTIONAL -} - -pvno and msg-type - These fields are described above in section 5.4.1. msg-type is either - KRB_AS_REP or KRB_TGS_REP. -padata - This field is described in detail in section 5.4.1. One possible use - for this field is to encode an alternate "mix-in" string to be used - with a string-to-key algorithm (such as is described in section 6.3.2). - This ability is useful to ease transitions if a realm name needs to - change (e.g. when a company is acquired); in such a case all existing - password-derived entries in the KDC database would be flagged as - needing a special mix-in string until the next password change. -crealm, cname, srealm and sname - These fields are the same as those described for the ticket in section - 5.3.1. -ticket - The newly-issued ticket, from section 5.3.1. -enc-part - This field is a place holder for the ciphertext and related information - that forms the encrypted part of a message. The description of the - encrypted part of the message follows each appearance of this field. - The encrypted part is encoded as described in section 6.1. -key - This field is the same as described for the ticket in section 5.3.1. - -Neuman, Ts'o, Kohl Expires: 25 December, -1999 - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, -1999 - -last-req - This field is returned by the KDC and specifies the time(s) of the last - request by a principal. Depending on what information is available, - this might be the last time that a request for a ticket-granting ticket - was made, or the last time that a request based on a ticket-granting - ticket was successful. It also might cover all servers for a realm, or - just the particular server. Some implementations may display this - information to the user to aid in discovering unauthorized use of one's - identity. It is similar in spirit to the last login time displayed when - logging into timesharing systems. -nonce - This field is described above in section 5.4.1. -key-expiration - The key-expiration field is part of the response from the KDC and - specifies the time that the client's secret key is due to expire. The - expiration might be the result of password aging or an account - expiration. This field will usually be left out of the TGS reply since - the response to the TGS request is encrypted in a session key and no - client information need be retrieved from the KDC database. It is up to - the application client (usually the login program) to take appropriate - action (such as notifying the user) if the expiration time is imminent. -flags, authtime, starttime, endtime, renew-till and caddr - These fields are duplicates of those found in the encrypted portion of - the attached ticket (see section 5.3.1), provided so the client may - verify they match the intended request and to assist in proper ticket - caching. If the message is of type KRB_TGS_REP, the caddr field will - only be filled in if the request was for a proxy or forwarded ticket, - or if the user is substituting a subset of the addresses from the - ticket granting ticket. If the client-requested addresses are not - present or not used, then the addresses contained in the ticket will be - the same as those included in the ticket-granting ticket. - -5.5. Client/Server (CS) message specifications - -This section specifies the format of the messages used for the -authentication of the client to the application server. - -5.5.1. KRB_AP_REQ definition - -The KRB_AP_REQ message contains the Kerberos protocol version number, the -message type KRB_AP_REQ, an options field to indicate any options in use, -and the ticket and authenticator themselves. The KRB_AP_REQ message is often -referred to as the 'authentication header'. - -AP-REQ ::= [APPLICATION 14] SEQUENCE { - pvno[0] INTEGER, - msg-type[1] INTEGER, - ap-options[2] APOptions, - ticket[3] Ticket, - authenticator[4] EncryptedData -} - -APOptions ::= BIT STRING { - reserved(0), - use-session-key(1), - mutual-required(2) -} - - -Neuman, Ts'o, Kohl Expires: 25 December, -1999 - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, -1999 - -pvno and msg-type - These fields are described above in section 5.4.1. msg-type is - KRB_AP_REQ. -ap-options - This field appears in the application request (KRB_AP_REQ) and affects - the way the request is processed. It is a bit-field, where the selected - options are indicated by the bit being set (1), and the unselected - options and reserved fields being reset (0). The encoding of the bits - is specified in section 5.2. The meanings of the options are: - - Bit(s) Name Description - - 0 RESERVED - Reserved for future expansion of this - field. - - 1 USE-SESSION-KEY - The USE-SESSION-KEY option indicates - that the ticket the client is presenting - to a server is encrypted in the session - key from the server's ticket-granting - ticket. When this option is not speci- - fied, the ticket is encrypted in the - server's secret key. - - 2 MUTUAL-REQUIRED - The MUTUAL-REQUIRED option tells the - server that the client requires mutual - authentication, and that it must respond - with a KRB_AP_REP message. - - 3-31 RESERVED - Reserved for future use. - -ticket - This field is a ticket authenticating the client to the server. -authenticator - This contains the authenticator, which includes the client's choice of - a subkey. Its encoding is described in section 5.3.2. - -5.5.2. KRB_AP_REP definition - -The KRB_AP_REP message contains the Kerberos protocol version number, the -message type, and an encrypted time- stamp. The message is sent in in -response to an application request (KRB_AP_REQ) where the mutual -authentication option has been selected in the ap-options field. - -AP-REP ::= [APPLICATION 15] SEQUENCE { - pvno[0] INTEGER, - msg-type[1] INTEGER, - enc-part[2] EncryptedData -} - -EncAPRepPart ::= [APPLICATION 27[29]] SEQUENCE { - ctime[0] KerberosTime, - cusec[1] INTEGER, - subkey[2] EncryptionKey OPTIONAL, - seq-number[3] INTEGER OPTIONAL -} - -Neuman, Ts'o, Kohl Expires: 25 December, -1999 - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, -1999 - -The encoded EncAPRepPart is encrypted in the shared session key of the -ticket. The optional subkey field can be used in an application-arranged -negotiation to choose a per association session key. - -pvno and msg-type - These fields are described above in section 5.4.1. msg-type is - KRB_AP_REP. -enc-part - This field is described above in section 5.4.2. -ctime - This field contains the current time on the client's host. -cusec - This field contains the microsecond part of the client's timestamp. -subkey - This field contains an encryption key which is to be used to protect - this specific application session. See section 3.2.6 for specifics on - how this field is used to negotiate a key. Unless an application - specifies otherwise, if this field is left out, the sub-session key - from the authenticator, or if also left out, the session key from the - ticket will be used. - -5.5.3. Error message reply - -If an error occurs while processing the application request, the KRB_ERROR -message will be sent in response. See section 5.9.1 for the format of the -error message. The cname and crealm fields may be left out if the server -cannot determine their appropriate values from the corresponding KRB_AP_REQ -message. If the authenticator was decipherable, the ctime and cusec fields -will contain the values from it. - -5.6. KRB_SAFE message specification - -This section specifies the format of a message that can be used by either -side (client or server) of an application to send a tamper-proof message to -its peer. It presumes that a session key has previously been exchanged (for -example, by using the KRB_AP_REQ/KRB_AP_REP messages). - -5.6.1. KRB_SAFE definition - -The KRB_SAFE message contains user data along with a collision-proof -checksum keyed with the last encryption key negotiated via subkeys, or the -session key if no negotiation has occured. The message fields are: - -KRB-SAFE ::= [APPLICATION 20] SEQUENCE { - pvno[0] INTEGER, - msg-type[1] INTEGER, - safe-body[2] KRB-SAFE-BODY, - cksum[3] Checksum -} - -KRB-SAFE-BODY ::= SEQUENCE { - user-data[0] OCTET STRING, - timestamp[1] KerberosTime OPTIONAL, - usec[2] INTEGER OPTIONAL, - seq-number[3] INTEGER OPTIONAL, - s-address[4] HostAddress OPTIONAL, - r-address[5] HostAddress OPTIONAL -} - - -Neuman, Ts'o, Kohl Expires: 25 December, -1999 - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, -1999 - -pvno and msg-type - These fields are described above in section 5.4.1. msg-type is - KRB_SAFE. -safe-body - This field is a placeholder for the body of the KRB-SAFE message. -cksum - This field contains the checksum of the application data. Checksum - details are described in section 6.4. The checksum is computed over the - encoding of the KRB-SAFE sequence. First, the cksum is zeroed and the - checksum is computed over the encoding of the KRB-SAFE sequence, then - the checksum is set to the result of that computation, and finally the - KRB-SAFE sequence is encoded again. -user-data - This field is part of the KRB_SAFE and KRB_PRIV messages and contain - the application specific data that is being passed from the sender to - the recipient. -timestamp - This field is part of the KRB_SAFE and KRB_PRIV messages. Its contents - are the current time as known by the sender of the message. By checking - the timestamp, the recipient of the message is able to make sure that - it was recently generated, and is not a replay. -usec - This field is part of the KRB_SAFE and KRB_PRIV headers. It contains - the microsecond part of the timestamp. -seq-number - This field is described above in section 5.3.2. -s-address - This field specifies the address in use by the sender of the message. - It may be omitted if not required by the application protocol. The - application designer considering omission of this field is warned, that - the inclusion of this address prevents some kinds of replay attacks - (e.g., reflection attacks) and that it is only acceptable to omit this - address if there is sufficient information in the integrity protected - part of the application message for the recipient to unambiguously - determine if it was the intended recipient. -r-address - This field specifies the address in use by the recipient of the - message. It may be omitted for some uses (such as broadcast protocols), - but the recipient may arbitrarily reject such messages. This field - along with s-address can be used to help detect messages which have - been incorrectly or maliciously delivered to the wrong recipient. - -5.7. KRB_PRIV message specification - -This section specifies the format of a message that can be used by either -side (client or server) of an application to securely and privately send a -message to its peer. It presumes that a session key has previously been -exchanged (for example, by using the KRB_AP_REQ/KRB_AP_REP messages). - -5.7.1. KRB_PRIV definition - -The KRB_PRIV message contains user data encrypted in the Session Key. The -message fields are: - -KRB-PRIV ::= [APPLICATION 21] SEQUENCE { - pvno[0] INTEGER, - msg-type[1] INTEGER, - enc-part[3] EncryptedData -} - - -Neuman, Ts'o, Kohl Expires: 25 December, -1999 - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, -1999 - -EncKrbPrivPart ::= [APPLICATION 28[31]] SEQUENCE { - user-data[0] OCTET STRING, - timestamp[1] KerberosTime OPTIONAL, - usec[2] INTEGER OPTIONAL, - seq-number[3] INTEGER OPTIONAL, - s-address[4] HostAddress OPTIONAL, -- sender's -addr - r-address[5] HostAddress OPTIONAL -- recip's -addr -} - -pvno and msg-type - These fields are described above in section 5.4.1. msg-type is - KRB_PRIV. -enc-part - This field holds an encoding of the EncKrbPrivPart sequence encrypted - under the session key[32]. This encrypted encoding is used for the - enc-part field of the KRB-PRIV message. See section 6 for the format of - the ciphertext. -user-data, timestamp, usec, s-address and r-address - These fields are described above in section 5.6.1. -seq-number - This field is described above in section 5.3.2. - -5.8. KRB_CRED message specification - -This section specifies the format of a message that can be used to send -Kerberos credentials from one principal to another. It is presented here to -encourage a common mechanism to be used by applications when forwarding -tickets or providing proxies to subordinate servers. It presumes that a -session key has already been exchanged perhaps by using the -KRB_AP_REQ/KRB_AP_REP messages. - -5.8.1. KRB_CRED definition - -The KRB_CRED message contains a sequence of tickets to be sent and -information needed to use the tickets, including the session key from each. -The information needed to use the tickets is encrypted under an encryption -key previously exchanged or transferred alongside the KRB_CRED message. The -message fields are: - -KRB-CRED ::= [APPLICATION 22] SEQUENCE { - pvno[0] INTEGER, - msg-type[1] INTEGER, -- KRB_CRED - tickets[2] SEQUENCE OF Ticket, - enc-part[3] EncryptedData -} - -EncKrbCredPart ::= [APPLICATION 29] SEQUENCE { - ticket-info[0] SEQUENCE OF KrbCredInfo, - nonce[1] INTEGER OPTIONAL, - timestamp[2] KerberosTime OPTIONAL, - usec[3] INTEGER OPTIONAL, - s-address[4] HostAddress OPTIONAL, - r-address[5] HostAddress OPTIONAL -} - -KrbCredInfo ::= SEQUENCE { - key[0] EncryptionKey, - prealm[1] Realm OPTIONAL, - -Neuman, Ts'o, Kohl Expires: 25 December, -1999 - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, -1999 - - pname[2] PrincipalName OPTIONAL, - flags[3] TicketFlags OPTIONAL, - authtime[4] KerberosTime OPTIONAL, - starttime[5] KerberosTime OPTIONAL, - endtime[6] KerberosTime OPTIONAL - renew-till[7] KerberosTime OPTIONAL, - srealm[8] Realm OPTIONAL, - sname[9] PrincipalName OPTIONAL, - caddr[10] HostAddresses OPTIONAL -} - -pvno and msg-type - These fields are described above in section 5.4.1. msg-type is - KRB_CRED. -tickets - These are the tickets obtained from the KDC specifically for use by the - intended recipient. Successive tickets are paired with the - corresponding KrbCredInfo sequence from the enc-part of the KRB-CRED - message. -enc-part - This field holds an encoding of the EncKrbCredPart sequence encrypted - under the session key shared between the sender and the intended - recipient. This encrypted encoding is used for the enc-part field of - the KRB-CRED message. See section 6 for the format of the ciphertext. -nonce - If practical, an application may require the inclusion of a nonce - generated by the recipient of the message. If the same value is - included as the nonce in the message, it provides evidence that the - message is fresh and has not been replayed by an attacker. A nonce must - never be re-used; it should be generated randomly by the recipient of - the message and provided to the sender of the message in an application - specific manner. -timestamp and usec - These fields specify the time that the KRB-CRED message was generated. - The time is used to provide assurance that the message is fresh. -s-address and r-address - These fields are described above in section 5.6.1. They are used - optionally to provide additional assurance of the integrity of the - KRB-CRED message. -key - This field exists in the corresponding ticket passed by the KRB-CRED - message and is used to pass the session key from the sender to the - intended recipient. The field's encoding is described in section 6.2. - -The following fields are optional. If present, they can be associated with -the credentials in the remote ticket file. If left out, then it is assumed -that the recipient of the credentials already knows their value. - -prealm and pname - The name and realm of the delegated principal identity. -flags, authtime, starttime, endtime, renew-till, srealm, sname, and caddr - These fields contain the values of the correspond- ing fields from the - ticket found in the ticket field. Descriptions of the fields are - identical to the descriptions in the KDC-REP message. - - -Neuman, Ts'o, Kohl Expires: 25 December, -1999 - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, -1999 - -5.9. Error message specification - -This section specifies the format for the KRB_ERROR message. The fields -included in the message are intended to return as much information as -possible about an error. It is not expected that all the information -required by the fields will be available for all types of errors. If the -appropriate information is not available when the message is composed, the -corresponding field will be left out of the message. - -Note that since the KRB_ERROR message is only optionally integrity -protected, it is quite possible for an intruder to synthesize or modify such -a message. In particular, this means that unless appropriate integrity -protection mechanisms have been applied to the KRB_ERROR message, the client -should not use any fields in this message for security-critical purposes, -such as setting a system clock or generating a fresh authenticator. The -message can be useful, however, for advising a user on the reason for some -failure. - -5.9.1. KRB_ERROR definition - -The KRB_ERROR message consists of the following fields: - -KRB-ERROR ::= [APPLICATION 30] SEQUENCE { - pvno[0] INTEGER, - msg-type[1] INTEGER, - ctime[2] KerberosTime OPTIONAL, - cusec[3] INTEGER OPTIONAL, - stime[4] KerberosTime, - susec[5] INTEGER, - error-code[6] INTEGER, - crealm[7] Realm OPTIONAL, - cname[8] PrincipalName OPTIONAL, - realm[9] Realm, -- Correct realm - sname[10] PrincipalName, -- Correct name - e-text[11] GeneralString OPTIONAL, - e-data[12] OCTET STRING OPTIONAL, - e-cksum[13] Checksum OPTIONAL, -(*REMOVE7/14*) e-typed-data[14] SEQUENCE of ETypedData -OPTIONAL -} - -pvno and msg-type - These fields are described above in section 5.4.1. msg-type is - KRB_ERROR. -ctime - This field is described above in section 5.4.1. -cusec - This field is described above in section 5.5.2. -stime - This field contains the current time on the server. It is of type - KerberosTime. -susec - This field contains the microsecond part of the server's timestamp. Its - value ranges from 0 to 999999. It appears along with stime. The two - fields are used in conjunction to specify a reasonably accurate - timestamp. - -Neuman, Ts'o, Kohl Expires: 25 December, -1999 - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, -1999 - -error-code - This field contains the error code returned by Kerberos or the server - when a request fails. To interpret the value of this field see the list - of error codes in section 8. Implementations are encouraged to provide - for national language support in the display of error messages. -crealm, cname, srealm and sname - These fields are described above in section 5.3.1. -e-text - This field contains additional text to help explain the error code - associated with the failed request (for example, it might include a - principal name which was unknown). -e-data - This field contains additional data about the error for use by the - application to help it recover from or handle the error. If present, - this field will contain the encoding of a sequence of TypedData - (TYPED-DATA below), unless the errorcode is KDC_ERR_PREAUTH_REQUIRED, - in which case it will contain the encoding of a sequence of of padata - fields (METHOD-DATA below), each corresponding to an acceptable - pre-authentication method and optionally containing data for the - method: - - TYPED-DATA ::= SEQUENCE of TypeData - METHOD-DATA ::= SEQUENCE of PA-DATA - - TypedData ::= SEQUENCE { - data-type[0] INTEGER, - data-value[1] OCTET STRING OPTIONAL - } - - Note that e-data-types have been reserved for all PA data types defined - prior to July 1999. For the KDC_ERR_PREAUTH_REQUIRED message, when - using new PA data types defined in July 1999 or later, the METHOD-DATA - sequence must itself be encapsulated in an TypedData element of type - TD-PADATA. All new implementations interpreting the METHOD-DATA field - for the KDC_ERR_PREAUTH_REQUIRED message must accept a type of - TD-PADATA, extract the typed data field and interpret the use any - elements encapsulated in the TD-PADATA elements as if they were present - in the METHOD-DATA sequence. -e-cksum - This field contains an optional checksum for the KRB-ERROR message. The - checksum is calculated over the Kerberos ASN.1 encoding of the - KRB-ERROR message with the checksum absent. The checksum is then added - to the KRB-ERROR structure and the message is re-encoded. The Checksum - should be calculated using the session key from the ticket granting - ticket or service ticket, where available. If the error is in response - to a TGS or AP request, the checksum should be calculated uing the the - session key from the client's ticket. If the error is in response to an - AS request, then the checksum should be calulated using the client's - secret key ONLY if there has been suitable preauthentication to prove - knowledge of the secret key by the client[33]. If a checksum can not be - computed because the key to be used is not available, no checksum will - be included. -e-typed-data - [***Will be deleted 7/14***] This field contains optional data that may - be used to help the client recover from the indicated error. [This - could contain the METHOD-DATA specified since I don't think anyone - actually uses it yet. It could also contain the PA-DATA sequence for - the preauth required error if we had a clear way to transition to the - -Neuman, Ts'o, Kohl Expires: 25 December, -1999 - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, -1999 - - use of this field from the use of the untyped e-data field.] For - example, this field may specify the key version of the key used to - verify preauthentication: - - e-data-type := 20 -- Key version number - e-data-value := Integer -- Key version number used to - verify preauthentication - -6. Encryption and Checksum Specifications - -The Kerberos protocols described in this document are designed to use stream -encryption ciphers, which can be simulated using commonly available block -encryption ciphers, such as the Data Encryption Standard, [DES77] in -conjunction with block chaining and checksum methods [DESM80]. Encryption is -used to prove the identities of the network entities participating in -message exchanges. The Key Distribution Center for each realm is trusted by -all principals registered in that realm to store a secret key in confidence. -Proof of knowledge of this secret key is used to verify the authenticity of -a principal. [*** Discussion above will change to use 3DES as example -7/14/99 ***] - -The KDC uses the principal's secret key (in the AS exchange) or a shared -session key (in the TGS exchange) to encrypt responses to ticket requests; -the ability to obtain the secret key or session key implies the knowledge of -the appropriate keys and the identity of the KDC. The ability of a principal -to decrypt the KDC response and present a Ticket and a properly formed -Authenticator (generated with the session key from the KDC response) to a -service verifies the identity of the principal; likewise the ability of the -service to extract the session key from the Ticket and prove its knowledge -thereof in a response verifies the identity of the service. - -The Kerberos protocols generally assume that the encryption used is secure -from cryptanalysis; however, in some cases, the order of fields in the -encrypted portions of messages are arranged to minimize the effects of -poorly chosen keys. It is still important to choose good keys. If keys are -derived from user-typed passwords, those passwords need to be well chosen to -make brute force attacks more difficult. Poorly chosen keys still make easy -targets for intruders. - -The following sections specify the encryption and checksum mechanisms -currently defined for Kerberos. The encodings, chaining, and padding -requirements for each are described. For encryption methods, it is often -desirable to place random information (often referred to as a confounder) at -the start of the message. The requirements for a confounder are specified -with each encryption mechanism. - -Some encryption systems use a block-chaining method to improve the the -security characteristics of the ciphertext. However, these chaining methods -often don't provide an integrity check upon decryption. Such systems (such -as DES in CBC mode) must be augmented with a checksum of the plain-text -which can be verified at decryption and used to detect any tampering or -damage. Such checksums should be good at detecting burst errors in the -input. If any damage is detected, the decryption routine is expected to -return an error indicating the failure of an integrity check. Each -encryption type is expected to provide and verify an appropriate checksum. -The specification of each encryption method sets out its checksum -requirements. - - -Neuman, Ts'o, Kohl Expires: 25 December, -1999 - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, -1999 - -Finally, where a key is to be derived from a user's password, an algorithm -for converting the password to a key of the appropriate type is included. It -is desirable for the string to key function to be one-way, and for the -mapping to be different in different realms. This is important because users -who are registered in more than one realm will often use the same password -in each, and it is desirable that an attacker compromising the Kerberos -server in one realm not obtain or derive the user's key in another. - -For an discussion of the integrity characteristics of the candidate -encryption and checksum methods considered for Kerberos, the reader is -referred to [SG92]. - -6.1. Encryption Specifications - -The following ASN.1 definition describes all encrypted messages. The -enc-part field which appears in the unencrypted part of messages in section -5 is a sequence consisting of an encryption type, an optional key version -number, and the ciphertext. - -EncryptedData ::= SEQUENCE { - etype[0] INTEGER, -- EncryptionType - kvno[1] INTEGER OPTIONAL, - cipher[2] OCTET STRING -- ciphertext -} - -etype - This field identifies which encryption algorithm was used to encipher - the cipher. Detailed specifications for selected encryption types - appear later in this section. -kvno - This field contains the version number of the key under which data is - encrypted. It is only present in messages encrypted under long lasting - keys, such as principals' secret keys. -cipher - This field contains the enciphered text, encoded as an OCTET STRING. - -The cipher field is generated by applying the specified encryption algorithm -to data composed of the message and algorithm-specific inputs. Encryption -mechanisms defined for use with Kerberos must take sufficient measures to -guarantee the integrity of the plaintext, and we recommend they also take -measures to protect against precomputed dictionary attacks. If the -encryption algorithm is not itself capable of doing so, the protections can -often be enhanced by adding a checksum and a confounder. - -The suggested format for the data to be encrypted includes a confounder, a -checksum, the encoded plaintext, and any necessary padding. The msg-seq -field contains the part of the protocol message described in section 5 which -is to be encrypted. The confounder, checksum, and padding are all untagged -and untyped, and their length is exactly sufficient to hold the appropriate -item. The type and length is implicit and specified by the particular -encryption type being used (etype). The format for the data to be encrypted -is described in the following diagram: - - -Neuman, Ts'o, Kohl Expires: 25 December, -1999 - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, -1999 - - +-----------+----------+-------------+-----+ - |confounder | check | msg-seq | pad | - +-----------+----------+-------------+-----+ - -The format cannot be described in ASN.1, but for those who prefer an -ASN.1-like notation: - -CipherText ::= ENCRYPTED SEQUENCE { - confounder[0] UNTAGGED[35] OCTET STRING(conf_length) OPTIONAL, - check[1] UNTAGGED OCTET STRING(checksum_length) OPTIONAL, - msg-seq[2] MsgSequence, - pad UNTAGGED OCTET STRING(pad_length) OPTIONAL -} - -One generates a random confounder of the appropriate length, placing it in -confounder; zeroes out check; calculates the appropriate checksum over -confounder, check, and msg-seq, placing the result in check; adds the -necessary padding; then encrypts using the specified encryption type and the -appropriate key. - -Unless otherwise specified, a definition of an encryption algorithm that -specifies a checksum, a length for the confounder field, or an octet -boundary for padding uses this ciphertext format[36]. Those fields which are -not specified will be omitted. - -In the interest of allowing all implementations using a particular -encryption type to communicate with all others using that type, the -specification of an encryption type defines any checksum that is needed as -part of the encryption process. If an alternative checksum is to be used, a -new encryption type must be defined. - -Some cryptosystems require additional information beyond the key and the -data to be encrypted. For example, DES, when used in cipher-block-chaining -mode, requires an initialization vector. If required, the description for -each encryption type must specify the source of such additional information. -6.2. Encryption Keys - -The sequence below shows the encoding of an encryption key: - - EncryptionKey ::= SEQUENCE { - keytype[0] INTEGER, - keyvalue[1] OCTET STRING - } - -keytype - This field specifies the type of encryption that is to be performed - using the key that follows in the keyvalue field. It will always - correspond to the etype to be used to generate or decode the - EncryptedData. In cases when multiple algorithms use a common kind of - key (e.g., if the encryption algorithm uses an alternate checksum - algorithm for an integrity check, or a different chaining mechanism), - the keytype provides information needed to determine which algorithm is - to be used. -keyvalue - This field contains the key itself, encoded as an octet string. - -All negative values for the encryption key type are reserved for local use. -All non-negative values are reserved for officially assigned type fields and -interpreta- tions. - - -Neuman, Ts'o, Kohl Expires: 25 December, -1999 - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, -1999 - -6.3. Encryption Systems - -6.3.1. The NULL Encryption System (null) - -If no encryption is in use, the encryption system is said to be the NULL -encryption system. In the NULL encryption system there is no checksum, -confounder or padding. The ciphertext is simply the plaintext. The NULL Key -is used by the null encryption system and is zero octets in length, with -keytype zero (0). - -6.3.2. DES in CBC mode with a CRC-32 checksum (des-cbc-crc) - -The des-cbc-crc encryption mode encrypts information under the Data -Encryption Standard [DES77] using the cipher block chaining mode [DESM80]. A -CRC-32 checksum (described in ISO 3309 [ISO3309]) is applied to the -confounder and message sequence (msg-seq) and placed in the cksum field. DES -blocks are 8 bytes. As a result, the data to be encrypted (the concatenation -of confounder, checksum, and message) must be padded to an 8 byte boundary -before encryption. The details of the encryption of this data are identical -to those for the des-cbc-md5 encryption mode. - -Note that, since the CRC-32 checksum is not collision-proof, an attacker -could use a probabilistic chosen-plaintext attack to generate a valid -message even if a confounder is used [SG92]. The use of collision-proof -checksums is recommended for environments where such attacks represent a -significant threat. The use of the CRC-32 as the checksum for ticket or -authenticator is no longer mandated as an interoperability requirement for -Kerberos Version 5 Specification 1 (See section 9.1 for specific details). - -6.3.3. DES in CBC mode with an MD4 checksum (des-cbc-md4) - -The des-cbc-md4 encryption mode encrypts information under the Data -Encryption Standard [DES77] using the cipher block chaining mode [DESM80]. -An MD4 checksum (described in [MD492]) is applied to the confounder and -message sequence (msg-seq) and placed in the cksum field. DES blocks are 8 -bytes. As a result, the data to be encrypted (the concatenation of -confounder, checksum, and message) must be padded to an 8 byte boundary -before encryption. The details of the encryption of this data are identical -to those for the des-cbc-md5 encryption mode. - -6.3.4. DES in CBC mode with an MD5 checksum (des-cbc-md5) - -The des-cbc-md5 encryption mode encrypts information under the Data -Encryption Standard [DES77] using the cipher block chaining mode [DESM80]. -An MD5 checksum (described in [MD5-92].) is applied to the confounder and -message sequence (msg-seq) and placed in the cksum field. DES blocks are 8 -bytes. As a result, the data to be encrypted (the concatenation of -confounder, checksum, and message) must be padded to an 8 byte boundary -before encryption. - -Plaintext and DES ciphtertext are encoded as blocks of 8 octets which are -concatenated to make the 64-bit inputs for the DES algorithms. The first -octet supplies the 8 most significant bits (with the octet's MSbit used as -the DES input block's MSbit, etc.), the second octet the next 8 bits, ..., -and the eighth octet supplies the 8 least significant bits. - - -Neuman, Ts'o, Kohl Expires: 25 December, -1999 - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, -1999 - -Encryption under DES using cipher block chaining requires an additional -input in the form of an initialization vector. Unless otherwise specified, -zero should be used as the initialization vector. Kerberos' use of DES -requires an 8 octet confounder. - -The DES specifications identify some 'weak' and 'semi-weak' keys; those keys -shall not be used for encrypting messages for use in Kerberos. Additionally, -because of the way that keys are derived for the encryption of checksums, -keys shall not be used that yield 'weak' or 'semi-weak' keys when -eXclusive-ORed with the hexadecimal constant F0F0F0F0F0F0F0F0. - -A DES key is 8 octets of data, with keytype one (1). This consists of 56 -bits of key, and 8 parity bits (one per octet). The key is encoded as a -series of 8 octets written in MSB-first order. The bits within the key are -also encoded in MSB order. For example, if the encryption key is -(B1,B2,...,B7,P1,B8,...,B14,P2,B15,...,B49,P7,B50,...,B56,P8) where -B1,B2,...,B56 are the key bits in MSB order, and P1,P2,...,P8 are the parity -bits, the first octet of the key would be B1,B2,...,B7,P1 (with B1 as the -MSbit). [See the FIPS 81 introduction for reference.] - -String to key transformation - -To generate a DES key from a text string (password), a "salt" is -concatenated to the text string, and then padded with ASCII nulls to an 8 -byte boundary. This "salt" is normally the realm and each component of the -principal's name appended. However, sometimes different salts are used --- -for example, when a realm is renamed, or if a user changes her username, or -for compatibility with Kerberos V4 (whose string-to-key algorithm uses a -null string for the salt). This string is then fan-folded and eXclusive-ORed -with itself to form an 8 byte DES key. Before eXclusive-ORing a block, every -byte is shifted one bit to the left to leave the lowest bit zero. The key is -the "corrected" by correcting the parity on the key, and if the key matches -a 'weak' or 'semi-weak' key as described in the DES specification, it is -eXclusive-ORed with the constant 00000000000000F0. This key is then used to -generate a DES CBC checksum on the initial string (with the salt appended). -The result of the CBC checksum is the "corrected" as described above to form -the result which is return as the key. Pseudocode follows: - - name_to_default_salt(realm, name) { - s = realm - for(each component in name) { - s = s + component; - } - return s; - } - - key_correction(key) { - fixparity(key); - if (is_weak_key_key(key)) - key = key XOR 0xF0; - return(key); - } - - string_to_key(string,salt) { - - odd = 1; - s = string + salt; - tempkey = NULL; - -Neuman, Ts'o, Kohl Expires: 25 December, -1999 - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, -1999 - - pad(s); /* with nulls to 8 byte boundary */ - for(8byteblock in s) { - if(odd == 0) { - odd = 1; - reverse(8byteblock) - } - else odd = 0; - left shift every byte in 8byteblock one bit; - tempkey = tempkey XOR 8byteblock; - } - tempkey = key_correction(tempkey); - key = key_correction(DES-CBC-check(s,tempkey)); - return(key); - } - -6.3.5. Triple DES with HMAC-SHA1 Kerberos Encryption Type with Key -Derivation [Horowitz] - -[*** Note that there are several 3DES varients in use in different Kerberos -implemenations, updates to this section will be sent to the cat list and -krb-protocol list prior to the Oslo IETF, including the key derivation and -non-key derivation varients ***] NOTE: This description currently refers to -documents, the contents of which might be bettered included by value in this -spec. The description below was provided by Marc Horowitz, and the form in -which it will finally appear is yet to be determined. This description is -included in this version of the draft because it does describe the -implemenation ready for use with the MIT implementation. Note also that the -encryption identifier has been left unspecified here because the value from -Marc Horowitz's spec conflicted with some other impmenentations implemented -based on perevious versions of the specification. - -This encryption type is based on the Triple DES cryptosystem, the HMAC-SHA1 -[Krawczyk96] message authentication algorithm, and key derivation for -Kerberos V5 [HorowitzB96]. - -The des3-cbc-hmac-sha1 encryption type has been assigned the value ??. The -hmac-sha1-des3 checksum type has been assigned the value 12. - -Encryption Type des3-cbc-hmac-sha1 - -EncryptedData using this type must be generated as described in -[Horowitz96]. The encryption algorithm is Triple DES in Outer-CBC mode. The -keyed hash algorithm is HMAC-SHA1. Unless otherwise specified, a zero IV -must be used. If the length of the input data is not a multiple of the block -size, zero octets must be used to pad the plaintext to the next eight-octet -boundary. The counfounder must be eight random octets (one block). - -Checksum Type hmac-sha1-des3 - -Checksums using this type must be generated as described in [Horowitz96]. -The keyed hash algorithm is HMAC-SHA1. - -Common Requirements - -The EncryptionKey value is 24 octets long. The 7 most significant bits of -each octet contain key bits, and the least significant bit is the inverse of -the xor of the key bits. - - -Neuman, Ts'o, Kohl Expires: 25 December, -1999 - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, -1999 - -For the purposes of key derivation, the block size is 64 bits, and the key -size is 168 bits. The 168 bits output by key derivation are converted to an -EncryptionKey value as follows. First, the 168 bits are divided into three -groups of 56 bits, which are expanded individually into 64 bits as follows: - - 1 2 3 4 5 6 7 p - 9 10 11 12 13 14 15 p -17 18 19 20 21 22 23 p -25 26 27 28 29 30 31 p -33 34 35 36 37 38 39 p -41 42 43 44 45 46 47 p -49 50 51 52 53 54 55 p -56 48 40 32 24 16 8 p - -The "p" bits are parity bits computed over the data bits. The output of the -three expansions are concatenated to form the EncryptionKey value. - -When the HMAC-SHA1 of a string is computed, the key is used in the -EncryptedKey form. - -Key Derivation - -In the Kerberos protocol, cryptographic keys are used in a number of places. -In order to minimize the effect of compromising a key, it is desirable to -use a different key for each of these places. Key derivation [Horowitz96] -can be used to construct different keys for each operation from the keys -transported on the network. For this to be possible, a small change to the -specification is necessary. - -This section specifies a profile for the use of key derivation [Horowitz96] -with Kerberos. For each place where a key is used, a ``key usage'' must is -specified for that purpose. The key, key usage, and encryption/checksum type -together describe the transformation from plaintext to ciphertext, or -plaintext to checksum. - -Key Usage Values - -This is a complete list of places keys are used in the kerberos protocol, -with key usage values and RFC 1510 section numbers: - - 1. AS-REQ PA-ENC-TIMESTAMP padata timestamp, encrypted with the - client key (section 5.4.1) - 2. AS-REP Ticket and TGS-REP Ticket (includes tgs session key or - application session key), encrypted with the service key - (section 5.4.2) - 3. AS-REP encrypted part (includes tgs session key or application - session key), encrypted with the client key (section 5.4.2) - 4. TGS-REQ KDC-REQ-BODY AuthorizationData, encrypted with the tgs - session key (section 5.4.1) - 5. TGS-REQ KDC-REQ-BODY AuthorizationData, encrypted with the tgs - authenticator subkey (section 5.4.1) - 6. TGS-REQ PA-TGS-REQ padata AP-REQ Authenticator cksum, keyed - with the tgs session key (sections 5.3.2, 5.4.1) - 7. TGS-REQ PA-TGS-REQ padata AP-REQ Authenticator (includes tgs - authenticator subkey), encrypted with the tgs session key - (section 5.3.2) - 8. TGS-REP encrypted part (includes application session key), - encrypted with the tgs session key (section 5.4.2) - -Neuman, Ts'o, Kohl Expires: 25 December, -1999 - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, -1999 - - 9. TGS-REP encrypted part (includes application session key), - encrypted with the tgs authenticator subkey (section 5.4.2) -10. AP-REQ Authenticator cksum, keyed with the application session - key (section 5.3.2) -11. AP-REQ Authenticator (includes application authenticator - subkey), encrypted with the application session key (section - 5.3.2) -12. AP-REP encrypted part (includes application session subkey), - encrypted with the application session key (section 5.5.2) -13. KRB-PRIV encrypted part, encrypted with a key chosen by the - application (section 5.7.1) -14. KRB-CRED encrypted part, encrypted with a key chosen by the - application (section 5.6.1) -15. KRB-SAVE cksum, keyed with a key chosen by the application - (section 5.8.1) -18. KRB-ERROR checksum (e-cksum in section 5.9.1) -19. AD-KDCIssued checksum (ad-checksum in appendix B.1) -20. Checksum for Mandatory Ticket Extensions (appendix B.6) -21. Checksum in Authorization Data in Ticket Extensions (appendix B.7) - -Key usage values between 1024 and 2047 (inclusive) are reserved for -application use. Applications should use even values for encryption and odd -values for checksums within this range. - -A few of these key usages need a little clarification. A service which -receives an AP-REQ has no way to know if the enclosed Ticket was part of an -AS-REP or TGS-REP. Therefore, key usage 2 must always be used for generating -a Ticket, whether it is in response to an AS- REQ or TGS-REQ. - -There might exist other documents which define protocols in terms of the -RFC1510 encryption types or checksum types. Such documents would not know -about key usages. In order that these documents continue to be meaningful -until they are updated, key usages 1024 and 1025 must be used to derive keys -for encryption and checksums, respectively. New protocols defined in terms -of the Kerberos encryption and checksum types should use their own key -usages. Key usages may be registered with IANA to avoid conflicts. Key -usages must be unsigned 32 bit integers. Zero is not permitted. - -Defining Cryptosystems Using Key Derivation - -Kerberos requires that the ciphertext component of EncryptedData be -tamper-resistant as well as confidential. This implies encryption and -integrity functions, which must each use their own separate keys. So, for -each key usage, two keys must be generated, one for encryption (Ke), and one -for integrity (Ki): - - Ke = DK(protocol key, key usage | 0xAA) - Ki = DK(protocol key, key usage | 0x55) - -where the protocol key is from the EncryptionKey from the wire protocol, and -the key usage is represented as a 32 bit integer in network byte order. The -ciphertest must be generated from the plaintext as follows: - - ciphertext = E(Ke, confounder | plaintext | padding) | - H(Ki, confounder | plaintext | padding) - -The confounder and padding are specific to the encryption algorithm E. - - -Neuman, Ts'o, Kohl Expires: 25 December, -1999 - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, -1999 - -When generating a checksum only, there is no need for a confounder or -padding. Again, a new key (Kc) must be used. Checksums must be generated -from the plaintext as follows: - - Kc = DK(protocol key, key usage | 0x99) - - MAC = H(Kc, plaintext) - -Note that each enctype is described by an encryption algorithm E and a keyed -hash algorithm H, and each checksum type is described by a keyed hash -algorithm H. HMAC, with an appropriate hash, is recommended for use as H. - -Key Derivation from Passwords - -The well-known constant for password key derivation must be the byte string -{0x6b 0x65 0x72 0x62 0x65 0x72 0x6f 0x73}. These values correspond to the -ASCII encoding for the string "kerberos". - -6.4. Checksums - -The following is the ASN.1 definition used for a checksum: - - Checksum ::= SEQUENCE { - cksumtype[0] INTEGER, - checksum[1] OCTET STRING - } - -cksumtype - This field indicates the algorithm used to generate the accompanying - checksum. -checksum - This field contains the checksum itself, encoded as an octet string. - -Detailed specification of selected checksum types appear later in this -section. Negative values for the checksum type are reserved for local use. -All non-negative values are reserved for officially assigned type fields and -interpretations. - -Checksums used by Kerberos can be classified by two properties: whether they -are collision-proof, and whether they are keyed. It is infeasible to find -two plaintexts which generate the same checksum value for a collision-proof -checksum. A key is required to perturb or initialize the algorithm in a -keyed checksum. To prevent message-stream modification by an active -attacker, unkeyed checksums should only be used when the checksum and -message will be subsequently encrypted (e.g. the checksums defined as part -of the encryption algorithms covered earlier in this section). - -Collision-proof checksums can be made tamper-proof if the checksum value is -encrypted before inclusion in a message. In such cases, the composition of -the checksum and the encryption algorithm must be considered a separate -checksum algorithm (e.g. RSA-MD5 encrypted using DES is a new checksum -algorithm of type RSA-MD5-DES). For most keyed checksums, as well as for the -encrypted forms of unkeyed collision-proof checksums, Kerberos prepends a -confounder before the checksum is calculated. - - -Neuman, Ts'o, Kohl Expires: 25 December, -1999 - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, -1999 - -6.4.1. The CRC-32 Checksum (crc32) - -The CRC-32 checksum calculates a checksum based on a cyclic redundancy check -as described in ISO 3309 [ISO3309]. The resulting checksum is four (4) -octets in length. The CRC-32 is neither keyed nor collision-proof. The use -of this checksum is not recommended. An attacker using a probabilistic -chosen-plaintext attack as described in [SG92] might be able to generate an -alternative message that satisfies the checksum. The use of collision-proof -checksums is recommended for environments where such attacks represent a -significant threat. - -6.4.2. The RSA MD4 Checksum (rsa-md4) - -The RSA-MD4 checksum calculates a checksum using the RSA MD4 algorithm -[MD4-92]. The algorithm takes as input an input message of arbitrary length -and produces as output a 128-bit (16 octet) checksum. RSA-MD4 is believed to -be collision-proof. - -6.4.3. RSA MD4 Cryptographic Checksum Using DES (rsa-md4-des) - -The RSA-MD4-DES checksum calculates a keyed collision-proof checksum by -prepending an 8 octet confounder before the text, applying the RSA MD4 -checksum algorithm, and encrypting the confounder and the checksum using DES -in cipher-block-chaining (CBC) mode using a variant of the key, where the -variant is computed by eXclusive-ORing the key with the constant -F0F0F0F0F0F0F0F0[39]. The initialization vector should be zero. The -resulting checksum is 24 octets long (8 octets of which are redundant). This -checksum is tamper-proof and believed to be collision-proof. - -The DES specifications identify some weak keys' and 'semi-weak keys'; those -keys shall not be used for generating RSA-MD4 checksums for use in Kerberos. - -The format for the checksum is described in the follow- ing diagram: - -+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ -| des-cbc(confounder + rsa-md4(confounder+msg),key=var(key),iv=0) | -+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ - -The format cannot be described in ASN.1, but for those who prefer an -ASN.1-like notation: - -rsa-md4-des-checksum ::= ENCRYPTED UNTAGGED SEQUENCE { - confounder[0] UNTAGGED OCTET STRING(8), - check[1] UNTAGGED OCTET STRING(16) -} - -6.4.4. The RSA MD5 Checksum (rsa-md5) - -The RSA-MD5 checksum calculates a checksum using the RSA MD5 algorithm. -[MD5-92]. The algorithm takes as input an input message of arbitrary length -and produces as output a 128-bit (16 octet) checksum. RSA-MD5 is believed to -be collision-proof. - -6.4.5. RSA MD5 Cryptographic Checksum Using DES (rsa-md5-des) - -The RSA-MD5-DES checksum calculates a keyed collision-proof checksum by -prepending an 8 octet confounder before the text, applying the RSA MD5 -checksum algorithm, and encrypting the confounder and the checksum using DES - -Neuman, Ts'o, Kohl Expires: 25 December, -1999 - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, -1999 - -in cipher-block-chaining (CBC) mode using a variant of the key, where the -variant is computed by eXclusive-ORing the key with the hexadecimal constant -F0F0F0F0F0F0F0F0. The initialization vector should be zero. The resulting -checksum is 24 octets long (8 octets of which are redundant). This checksum -is tamper-proof and believed to be collision-proof. - -The DES specifications identify some 'weak keys' and 'semi-weak keys'; those -keys shall not be used for encrypting RSA-MD5 checksums for use in Kerberos. - -The format for the checksum is described in the following diagram: - -+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ -| des-cbc(confounder + rsa-md5(confounder+msg),key=var(key),iv=0) | -+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ - -The format cannot be described in ASN.1, but for those who prefer an -ASN.1-like notation: - -rsa-md5-des-checksum ::= ENCRYPTED UNTAGGED SEQUENCE { - confounder[0] UNTAGGED OCTET STRING(8), - check[1] UNTAGGED OCTET STRING(16) -} - -6.4.6. DES cipher-block chained checksum (des-mac) - -The DES-MAC checksum is computed by prepending an 8 octet confounder to the -plaintext, performing a DES CBC-mode encryption on the result using the key -and an initialization vector of zero, taking the last block of the -ciphertext, prepending the same confounder and encrypting the pair using DES -in cipher-block-chaining (CBC) mode using a a variant of the key, where the -variant is computed by eXclusive-ORing the key with the hexadecimal constant -F0F0F0F0F0F0F0F0. The initialization vector should be zero. The resulting -checksum is 128 bits (16 octets) long, 64 bits of which are redundant. This -checksum is tamper-proof and collision-proof. - -The format for the checksum is described in the following diagram: - -+--+--+--+--+--+--+--+--+-----+-----+-----+-----+-----+-----+-----+-----+ -| des-cbc(confounder + des-mac(conf+msg,iv=0,key),key=var(key),iv=0) | -+--+--+--+--+--+--+--+--+-----+-----+-----+-----+-----+-----+-----+-----+ - -The format cannot be described in ASN.1, but for those who prefer an -ASN.1-like notation: - -des-mac-checksum ::= ENCRYPTED UNTAGGED SEQUENCE { - confounder[0] UNTAGGED OCTET STRING(8), - check[1] UNTAGGED OCTET STRING(8) -} - -The DES specifications identify some 'weak' and 'semi-weak' keys; those keys -shall not be used for generating DES-MAC checksums for use in Kerberos, nor -shall a key be used whose variant is 'weak' or 'semi-weak'. - -6.4.7. RSA MD4 Cryptographic Checksum Using DES alternative (rsa-md4-des-k) - -The RSA-MD4-DES-K checksum calculates a keyed collision-proof checksum by -applying the RSA MD4 checksum algorithm and encrypting the results using DES -in cipher-block-chaining (CBC) mode using a DES key as both key and - -Neuman, Ts'o, Kohl Expires: 25 December, -1999 - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, -1999 - -initialization vector. The resulting checksum is 16 octets long. This -checksum is tamper-proof and believed to be collision-proof. Note that this -checksum type is the old method for encoding the RSA-MD4-DES checksum and it -is no longer recommended. - -6.4.8. DES cipher-block chained checksum alternative (des-mac-k) - -The DES-MAC-K checksum is computed by performing a DES CBC-mode encryption -of the plaintext, and using the last block of the ciphertext as the checksum -value. It is keyed with an encryption key and an initialization vector; any -uses which do not specify an additional initialization vector will use the -key as both key and initialization vector. The resulting checksum is 64 bits -(8 octets) long. This checksum is tamper-proof and collision-proof. Note -that this checksum type is the old method for encoding the DES-MAC checksum -and it is no longer recommended. The DES specifications identify some 'weak -keys' and 'semi-weak keys'; those keys shall not be used for generating -DES-MAC checksums for use in Kerberos. - -7. Naming Constraints - -7.1. Realm Names - -Although realm names are encoded as GeneralStrings and although a realm can -technically select any name it chooses, interoperability across realm -boundaries requires agreement on how realm names are to be assigned, and -what information they imply. - -To enforce these conventions, each realm must conform to the conventions -itself, and it must require that any realms with which inter-realm keys are -shared also conform to the conventions and require the same from its -neighbors. - -Kerberos realm names are case sensitive. Realm names that differ only in the -case of the characters are not equivalent. There are presently four styles -of realm names: domain, X500, other, and reserved. Examples of each style -follow: - - domain: ATHENA.MIT.EDU (example) - X500: C=US/O=OSF (example) - other: NAMETYPE:rest/of.name=without-restrictions (example) - reserved: reserved, but will not conflict with above - -Domain names must look like domain names: they consist of components -separated by periods (.) and they contain neither colons (:) nor slashes -(/). Domain names must be converted to upper case when used as realm names. - -X.500 names contain an equal (=) and cannot contain a colon (:) before the -equal. The realm names for X.500 names will be string representations of the -names with components separated by slashes. Leading and trailing slashes -will not be included. - -Names that fall into the other category must begin with a prefix that -contains no equal (=) or period (.) and the prefix must be followed by a -colon (:) and the rest of the name. All prefixes must be assigned before -they may be used. Presently none are assigned. - - -Neuman, Ts'o, Kohl Expires: 25 December, -1999 - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, -1999 - -The reserved category includes strings which do not fall into the first -three categories. All names in this category are reserved. It is unlikely -that names will be assigned to this category unless there is a very strong -argument for not using the 'other' category. - -These rules guarantee that there will be no conflicts between the various -name styles. The following additional constraints apply to the assignment of -realm names in the domain and X.500 categories: the name of a realm for the -domain or X.500 formats must either be used by the organization owning (to -whom it was assigned) an Internet domain name or X.500 name, or in the case -that no such names are registered, authority to use a realm name may be -derived from the authority of the parent realm. For example, if there is no -domain name for E40.MIT.EDU, then the administrator of the MIT.EDU realm can -authorize the creation of a realm with that name. - -This is acceptable because the organization to which the parent is assigned -is presumably the organization authorized to assign names to its children in -the X.500 and domain name systems as well. If the parent assigns a realm -name without also registering it in the domain name or X.500 hierarchy, it -is the parent's responsibility to make sure that there will not in the -future exists a name identical to the realm name of the child unless it is -assigned to the same entity as the realm name. - -7.2. Principal Names - -As was the case for realm names, conventions are needed to ensure that all -agree on what information is implied by a principal name. The name-type -field that is part of the principal name indicates the kind of information -implied by the name. The name-type should be treated as a hint. Ignoring the -name type, no two names can be the same (i.e. at least one of the -components, or the realm, must be different). The following name types are -defined: - - name-type value meaning - - NT-UNKNOWN 0 Name type not known - NT-PRINCIPAL 1 General principal name (e.g. username, or DCE -principal) - NT-SRV-INST 2 Service and other unique instance (krbtgt) - NT-SRV-HST 3 Service with host name as instance (telnet, -rcommands) - NT-SRV-XHST 4 Service with slash-separated host name components - NT-UID 5 Unique ID - NT-X500-PRINCIPAL 6 Encoded X.509 Distingished name [RFC 1779] - -When a name implies no information other than its uniqueness at a particular -time the name type PRINCIPAL should be used. The principal name type should -be used for users, and it might also be used for a unique server. If the -name is a unique machine generated ID that is guaranteed never to be -reassigned then the name type of UID should be used (note that it is -generally a bad idea to reassign names of any type since stale entries might -remain in access control lists). - -If the first component of a name identifies a service and the remaining -components identify an instance of the service in a server specified manner, -then the name type of SRV-INST should be used. An example of this name type -is the Kerberos ticket-granting service whose name has a first component of -krbtgt and a second component identifying the realm for which the ticket is -valid. - - -Neuman, Ts'o, Kohl Expires: 25 December, -1999 - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, -1999 - -If instance is a single component following the service name and the -instance identifies the host on which the server is running, then the name -type SRV-HST should be used. This type is typically used for Internet -services such as telnet and the Berkeley R commands. If the separate -components of the host name appear as successive components following the -name of the service, then the name type SRV-XHST should be used. This type -might be used to identify servers on hosts with X.500 names where the slash -(/) might otherwise be ambiguous. - -A name type of NT-X500-PRINCIPAL should be used when a name from an X.509 -certificiate is translated into a Kerberos name. The encoding of the X.509 -name as a Kerberos principal shall conform to the encoding rules specified -in RFC 2253. - -A name type of UNKNOWN should be used when the form of the name is not -known. When comparing names, a name of type UNKNOWN will match principals -authenticated with names of any type. A principal authenticated with a name -of type UNKNOWN, however, will only match other names of type UNKNOWN. - -Names of any type with an initial component of 'krbtgt' are reserved for the -Kerberos ticket granting service. See section 8.2.3 for the form of such -names. - -7.2.1. Name of server principals - -The principal identifier for a server on a host will generally be composed -of two parts: (1) the realm of the KDC with which the server is registered, -and (2) a two-component name of type NT-SRV-HST if the host name is an -Internet domain name or a multi-component name of type NT-SRV-XHST if the -name of the host is of a form such as X.500 that allows slash (/) -separators. The first component of the two- or multi-component name will -identify the service and the latter components will identify the host. Where -the name of the host is not case sensitive (for example, with Internet -domain names) the name of the host must be lower case. If specified by the -application protocol for services such as telnet and the Berkeley R commands -which run with system privileges, the first component may be the string -'host' instead of a service specific identifier. When a host has an official -name and one or more aliases, the official name of the host must be used -when constructing the name of the server principal. - -8. Constants and other defined values - -8.1. Host address types - -All negative values for the host address type are reserved for local use. -All non-negative values are reserved for officially assigned type fields and -interpretations. - -The values of the types for the following addresses are chosen to match the -defined address family constants in the Berkeley Standard Distributions of -Unix. They can be found in with symbolic names AF_xxx (where xxx is an -abbreviation of the address family name). - -Internet (IPv4) Addresses - -Internet (IPv4) addresses are 32-bit (4-octet) quantities, encoded in MSB -order. The type of IPv4 addresses is two (2). - - -Neuman, Ts'o, Kohl Expires: 25 December, -1999 - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, -1999 - -Internet (IPv6) Addresses [Westerlund] - -IPv6 addresses are 128-bit (16-octet) quantities, encoded in MSB order. The -type of IPv6 addresses is twenty-four (24). [RFC1883] [RFC1884]. The -following addresses (see [RFC1884]) MUST not appear in any Kerberos packet: - - * the Unspecified Address - * the Loopback Address - * Link-Local addresses - -IPv4-mapped IPv6 addresses MUST be represented as addresses of type 2. - -CHAOSnet addresses - -CHAOSnet addresses are 16-bit (2-octet) quantities, encoded in MSB order. -The type of CHAOSnet addresses is five (5). - -ISO addresses - -ISO addresses are variable-length. The type of ISO addresses is seven (7). - -Xerox Network Services (XNS) addresses - -XNS addresses are 48-bit (6-octet) quantities, encoded in MSB order. The -type of XNS addresses is six (6). - -AppleTalk Datagram Delivery Protocol (DDP) addresses - -AppleTalk DDP addresses consist of an 8-bit node number and a 16-bit network -number. The first octet of the address is the node number; the remaining two -octets encode the network number in MSB order. The type of AppleTalk DDP -addresses is sixteen (16). - -DECnet Phase IV addresses - -DECnet Phase IV addresses are 16-bit addresses, encoded in LSB order. The -type of DECnet Phase IV addresses is twelve (12). - -Netbios addresses - -Netbios addresses are 16-octet addresses typically composed of 1 to 15 -characters, trailing blank (ascii char 20) filled, with a 16th octet of 0x0. -The type of Netbios addresses is 20 (0x14). - -8.2. KDC messages - -8.2.1. UDP/IP transport - -When contacting a Kerberos server (KDC) for a KRB_KDC_REQ request using UDP -IP transport, the client shall send a UDP datagram containing only an -encoding of the request to port 88 (decimal) at the KDC's IP address; the -KDC will respond with a reply datagram containing only an encoding of the -reply message (either a KRB_ERROR or a KRB_KDC_REP) to the sending port at -the sender's IP address. Kerberos servers supporting IP transport must -accept UDP requests on port 88 (decimal). The response to a request made -through UDP/IP transport must also use UDP/IP transport. - - -Neuman, Ts'o, Kohl Expires: 25 December, -1999 - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, -1999 - -8.2.2. TCP/IP transport [Westerlund,Danielsson] - -Kerberos servers (KDC's) should accept TCP requests on port 88 (decimal) and -clients should support the sending of TCP requests on port 88 (decimal). -When the KRB_KDC_REQ message is sent to the KDC over a TCP stream, a new -connection will be established for each authentication exchange (request and -response). The KRB_KDC_REP or KRB_ERROR message will be returned to the -client on the same TCP stream that was established for the request. The -response to a request made through TCP/IP transport must also use TCP/IP -transport. Implementors should note that some extentions to the Kerberos -protocol will not work if any implementation not supporting the TCP -transport is involved (client or KDC). Implementors are strongly urged to -support the TCP transport on both the client and server and are advised that -the current notation of "should" support will likely change in the future to -must support. The KDC may close the TCP stream after sending a response, but -may leave the stream open if it expects a followup - in which case it may -close the stream at any time if resource constratints or other factors make -it desirable to do so. Care must be taken in managing TCP/IP connections -with the KDC to prevent denial of service attacks based on the number of -TCP/IP connections with the KDC that remain open. If multiple exchanges with -the KDC are needed for certain forms of preauthentication, multiple TCP -connections may be required. A client may close the stream after receiving -response, and should close the stream if it does not expect to send followup -messages. The client must be prepared to have the stream closed by the KDC -at anytime, in which case it must simply connect again when it is ready to -send subsequent messages. - -The first four octets of the TCP stream used to transmit the request request -will encode in network byte order the length of the request (KRB_KDC_REQ), -and the length will be followed by the request itself. The response will -similarly be preceeded by a 4 octet encoding in network byte order of the -length of the KRB_KDC_REP or the KRB_ERROR message and will be followed by -the KRB_KDC_REP or the KRB_ERROR response. If the sign bit is set on the -integer represented by the first 4 octets, then the next 4 octets will be -read, extending the length of the field by another 4 octets (less the sign -bit which is reserved for future expansion). - -8.2.3. OSI transport - -During authentication of an OSI client to an OSI server, the mutual -authentication of an OSI server to an OSI client, the transfer of -credentials from an OSI client to an OSI server, or during exchange of -private or integrity checked messages, Kerberos protocol messages may be -treated as opaque objects and the type of the authentication mechanism will -be: - -OBJECT IDENTIFIER ::= {iso (1), org(3), dod(6),internet(1), - security(5),kerberosv5(2)} - -Depending on the situation, the opaque object will be an authentication -header (KRB_AP_REQ), an authentication reply (KRB_AP_REP), a safe message -(KRB_SAFE), a private message (KRB_PRIV), or a credentials message -(KRB_CRED). The opaque data contains an application code as specified in the -ASN.1 description for each message. The application code may be used by -Kerberos to determine the message type. - - -Neuman, Ts'o, Kohl Expires: 25 December, -1999 - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, -1999 - -8.2.3. Name of the TGS - -The principal identifier of the ticket-granting service shall be composed of -three parts: (1) the realm of the KDC issuing the TGS ticket (2) a two-part -name of type NT-SRV-INST, with the first part "krbtgt" and the second part -the name of the realm which will accept the ticket-granting ticket. For -example, a ticket-granting ticket issued by the ATHENA.MIT.EDU realm to be -used to get tickets from the ATHENA.MIT.EDU KDC has a principal identifier -of "ATHENA.MIT.EDU" (realm), ("krbtgt", "ATHENA.MIT.EDU") (name). A -ticket-granting ticket issued by the ATHENA.MIT.EDU realm to be used to get -tickets from the MIT.EDU realm has a principal identifier of -"ATHENA.MIT.EDU" (realm), ("krbtgt", "MIT.EDU") (name). - -8.3. Protocol constants and associated values - -The following tables list constants used in the protocol and defines their -meanings. Ranges are specified in the "specification" section that limit the -values of constants for which values are defined here. This allows -implementations to make assumptions about the maximum values that will be -received for these constants. Implementation receiving values outside the -range specified in the "specification" section may reject the request, but -they must recover cleanly. - -Encryption type etype value block size minimum pad size confounder -size -NULL 0 1 0 0 -des-cbc-crc 1 8 4 8 -des-cbc-md4 2 8 0 8 -des-cbc-md5 3 8 0 8 - 4 -des3-cbc-md5 5 8 0 8 - 6 -des3-cbc-sha1 7 8 0 8 -sign-dsa-generate 8 -(old-pkinit-will-remove) -dsaWithSHA1-CmsOID 9 (pkinit) -md5WithRSAEncryption-CmsOID 10 (pkinit) -sha1WithRSAEncryption-CmsOID 11 (pkinit) -rc2CBC-EnvOID 12 (pkinit) -rsaEncryption-EnvOID 13 (pkinit from PKCS#1 -v1.5) -rsaES-OAEP-ENV-OID 14 (pkinit from PKCS#1 -v2.0) -des-ede3-cbc-Env-OID 15 (pkinit) -des3kd-cbc-sha1 ?? 8 0 8 -ENCTYPE_PK_CROSS 48 (reserved for pkcross) - 0x8003 - -Checksum type sumtype value checksum size -CRC32 1 4 -rsa-md4 2 16 -rsa-md4-des 3 24 -des-mac 4 16 -des-mac-k 5 8 -rsa-md4-des-k 6 16 -rsa-md5 7 16 -rsa-md5-des 8 24 -rsa-md5-des3 9 24 -hmac-sha1-des3 12 20 (I had this as 10, is it -12) - - -Neuman, Ts'o, Kohl Expires: 25 December, -1999 - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, -1999 - -padata type padata-type value - -PA-TGS-REQ 1 -PA-ENC-TIMESTAMP 2 -PA-PW-SALT 3 - 4 -PA-ENC-UNIX-TIME 5 -PA-SANDIA-SECUREID 6 -PA-SESAME 7 -PA-OSF-DCE 8 -PA-CYBERSAFE-SECUREID 9 -PA-AFS3-SALT 10 -PA-ETYPE-INFO 11 -SAM-CHALLENGE 12 (sam/otp) -SAM-RESPONSE 13 (sam/otp) -PA-PK-AS-REQ 14 (pkinit) -PA-PK-AS-REP 15 (pkinit) -PA-PK-AS-SIGN 16 (***remove on 7/14***) -PA-PK-KEY-REQ 17 (***remove on 7/14***) -PA-PK-KEY-REP 18 (***remove on 7/14***) -PA-USE-SPECIFIED-KVNO 20 -SAM-REDIRECT 21 (sam/otp) -PA-GET-FROM-TYPED-DATA 22 - -data-type value form of typed-data - - 1-21 -TD-PADATA 22 -TD-PKINIT-CMS-CERTIFICATES 101 CertificateSet from CMS -TD-KRB-PRINCIPAL 102 -TD-KRB-REALM 103 -TD-TRUSTED-CERTIFIERS 104 -TD-CERTIFICATE-INDEX 105 - -authorization data type ad-type value -AD-IF-RELEVANT 1 -AD-INTENDED-FOR-SERVER 2 -AD-INTENDED-FOR-APPLICATION-CLASS 3 -AD-KDC-ISSUED 4 -AD-OR 5 -AD-MANDATORY-TICKET-EXTENSIONS 6 -AD-IN-TICKET-EXTENSIONS 7 -reserved values 8-63 -OSF-DCE 64 -SESAME 65 - -Ticket Extension Types - -TE-TYPE-NULL 0 Null ticket extension -TE-TYPE-EXTERNAL-ADATA 1 Integrity protected authorization data - 2 TE-TYPE-PKCROSS-KDC (I have reservations) -TE-TYPE-PKCROSS-CLIENT 3 PKCROSS cross realm key ticket -TE-TYPE-CYBERSAFE-EXT 4 Assigned to CyberSafe Corp - 5 TE-TYPE-DEST-HOST (I have reservations) - - -Neuman, Ts'o, Kohl Expires: 25 December, -1999 - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, -1999 - -alternate authentication type method-type value -reserved values 0-63 -ATT-CHALLENGE-RESPONSE 64 - -transited encoding type tr-type value -DOMAIN-X500-COMPRESS 1 -reserved values all others - -Label Value Meaning or MIT code - -pvno 5 current Kerberos protocol version number - -message types - -KRB_AS_REQ 10 Request for initial authentication -KRB_AS_REP 11 Response to KRB_AS_REQ request -KRB_TGS_REQ 12 Request for authentication based on TGT -KRB_TGS_REP 13 Response to KRB_TGS_REQ request -KRB_AP_REQ 14 application request to server -KRB_AP_REP 15 Response to KRB_AP_REQ_MUTUAL -KRB_SAFE 20 Safe (checksummed) application message -KRB_PRIV 21 Private (encrypted) application message -KRB_CRED 22 Private (encrypted) message to forward -credentials -KRB_ERROR 30 Error response - -name types - -KRB_NT_UNKNOWN 0 Name type not known -KRB_NT_PRINCIPAL 1 Just the name of the principal as in DCE, or for -users -KRB_NT_SRV_INST 2 Service and other unique instance (krbtgt) -KRB_NT_SRV_HST 3 Service with host name as instance (telnet, -rcommands) -KRB_NT_SRV_XHST 4 Service with host as remaining components -KRB_NT_UID 5 Unique ID -KRB_NT_X500_PRINCIPAL 6 Encoded X.509 Distingished name [RFC 2253] - -error codes - -KDC_ERR_NONE 0 No error -KDC_ERR_NAME_EXP 1 Client's entry in database has expired -KDC_ERR_SERVICE_EXP 2 Server's entry in database has expired -KDC_ERR_BAD_PVNO 3 Requested protocol version # not -supported -KDC_ERR_C_OLD_MAST_KVNO 4 Client's key encrypted in old master key -KDC_ERR_S_OLD_MAST_KVNO 5 Server's key encrypted in old master key -KDC_ERR_C_PRINCIPAL_UNKNOWN 6 Client not found in Kerberos database -KDC_ERR_S_PRINCIPAL_UNKNOWN 7 Server not found in Kerberos database -KDC_ERR_PRINCIPAL_NOT_UNIQUE 8 Multiple principal entries in database -KDC_ERR_NULL_KEY 9 The client or server has a null key -KDC_ERR_CANNOT_POSTDATE 10 Ticket not eligible for postdating -KDC_ERR_NEVER_VALID 11 Requested start time is later than end -time -KDC_ERR_POLICY 12 KDC policy rejects request -KDC_ERR_BADOPTION 13 KDC cannot accommodate requested option -KDC_ERR_ETYPE_NOSUPP 14 KDC has no support for encryption type -KDC_ERR_SUMTYPE_NOSUPP 15 KDC has no support for checksum type -KDC_ERR_PADATA_TYPE_NOSUPP 16 KDC has no support for padata type -KDC_ERR_TRTYPE_NOSUPP 17 KDC has no support for transited type -KDC_ERR_CLIENT_REVOKED 18 Clients credentials have been revoked -KDC_ERR_SERVICE_REVOKED 19 Credentials for server have been revoked -KDC_ERR_TGT_REVOKED 20 TGT has been revoked - -Neuman, Ts'o, Kohl Expires: 25 December, -1999 - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, -1999 - -KDC_ERR_CLIENT_NOTYET 21 Client not yet valid - try again later -KDC_ERR_SERVICE_NOTYET 22 Server not yet valid - try again later -KDC_ERR_KEY_EXPIRED 23 Password has expired - change password -KDC_ERR_PREAUTH_FAILED 24 Pre-authentication information was -invalid -KDC_ERR_PREAUTH_REQUIRED 25 Additional pre-authenticationrequired -[40] -KDC_ERR_SERVER_NOMATCH 26 Requested server and ticket don't match -KDC_ERR_MUST_USE_USER2USER 27 Server principal valid for user2user -only -KDC_ERR_PATH_NOT_ACCPETED 28 KDC Policy rejects transited path -KDC_ERR_SVC_UNAVAILABLE 29 A service is not available -KRB_AP_ERR_BAD_INTEGRITY 31 Integrity check on decrypted field -failed -KRB_AP_ERR_TKT_EXPIRED 32 Ticket expired -KRB_AP_ERR_TKT_NYV 33 Ticket not yet valid -KRB_AP_ERR_REPEAT 34 Request is a replay -KRB_AP_ERR_NOT_US 35 The ticket isn't for us -KRB_AP_ERR_BADMATCH 36 Ticket and authenticator don't match -KRB_AP_ERR_SKEW 37 Clock skew too great -KRB_AP_ERR_BADADDR 38 Incorrect net address -KRB_AP_ERR_BADVERSION 39 Protocol version mismatch -KRB_AP_ERR_MSG_TYPE 40 Invalid msg type -KRB_AP_ERR_MODIFIED 41 Message stream modified -KRB_AP_ERR_BADORDER 42 Message out of order -KRB_AP_ERR_BADKEYVER 44 Specified version of key is not -available -KRB_AP_ERR_NOKEY 45 Service key not available -KRB_AP_ERR_MUT_FAIL 46 Mutual authentication failed -KRB_AP_ERR_BADDIRECTION 47 Incorrect message direction -KRB_AP_ERR_METHOD 48 Alternative authentication method -required -KRB_AP_ERR_BADSEQ 49 Incorrect sequence number in message -KRB_AP_ERR_INAPP_CKSUM 50 Inappropriate type of checksum in -message -KRB_AP_PATH_NOT_ACCEPTED 51 Policy rejects transited path -KRB_ERR_RESPONSE_TOO_BIG 52 Response too big for UDP, retry with TCP -KRB_ERR_GENERIC 60 Generic error (description in e-text) -KRB_ERR_FIELD_TOOLONG 61 Field is too long for this -implementation -KDC_ERROR_CLIENT_NOT_TRUSTED 62 (pkinit) -KDC_ERROR_KDC_NOT_TRUSTED 63 (pkinit) -KDC_ERROR_INVALID_SIG 64 (pkinit) -KDC_ERR_KEY_TOO_WEAK 65 (pkinit) -KDC_ERR_CERTIFICATE_MISMATCH 66 (pkinit) -KRB_AP_ERR_NO_TGT 67 (user-to-user) -KDC_ERR_WRONG_REALM 68 (user-to-user) -KRB_AP_ERR_USER_TO_USER_REQUIRED 69 (user-to-user) -KDC_ERR_CANT_VERIFY_CERTIFICATE 70 (pkinit) -KDC_ERR_INVALID_CERTIFICATE 71 (pkinit) -KDC_ERR_REVOKED_CERTIFICATE 72 (pkinit) -KDC_ERR_REVOCATION_STATUS_UNKNOWN 73 (pkinit) -KDC_ERR_REVOCATION_STATUS_UNAVAILABLE 74 (pkinit) -KDC_ERR_CLIENT_NAME_MISMATCH 75 (pkinit) -KDC_ERR_KDC_NAME_MISMATCH 76 (pkinit) - -9. Interoperability requirements - -Version 5 of the Kerberos protocol supports a myriad of options. Among these -are multiple encryption and checksum types, alternative encoding schemes for -the transited field, optional mechanisms for pre-authentication, the -handling of tickets with no addresses, options for mutual authentication, -user to user authentication, support for proxies, forwarding, postdating, -and renewing tickets, the format of realm names, and the handling of -authorization data. - - -Neuman, Ts'o, Kohl Expires: 25 December, -1999 - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, -1999 - -In order to ensure the interoperability of realms, it is necessary to define -a minimal configuration which must be supported by all implementations. This -minimal configuration is subject to change as technology does. For example, -if at some later date it is discovered that one of the required encryption -or checksum algorithms is not secure, it will be replaced. - -9.1. Specification 2 - -This section defines the second specification of these options. -Implementations which are configured in this way can be said to support -Kerberos Version 5 Specification 2 (5.1). Specification 1 (depricated) may -be found in RFC1510. - -Transport - -TCP/IP and UDP/IP transport must be supported by KDCs claiming conformance -to specification 2. Kerberos clients claiming conformance to specification 2 -must support UDP/IP transport for messages with the KDC and should support -TCP/IP transport. - -Encryption and checksum methods - -The following encryption and checksum mechanisms must be supported. -Implementations may support other mechanisms as well, but the additional -mechanisms may only be used when communicating with principals known to also -support them: This list is to be determined. [***This section will change, -and alternatives will be sent to the cat and krb-protocol list prior to the -Oslo IETF - change will be made 7/14/99 ***] - -Encryption: DES-CBC-MD5 -Checksums: CRC-32, DES-MAC, DES-MAC-K, and DES-MD5 - -Realm Names - -All implementations must understand hierarchical realms in both the Internet -Domain and the X.500 style. When a ticket granting ticket for an unknown -realm is requested, the KDC must be able to determine the names of the -intermediate realms between the KDCs realm and the requested realm. - -Transited field encoding - -DOMAIN-X500-COMPRESS (described in section 3.3.3.2) must be supported. -Alternative encodings may be supported, but they may be used only when that -encoding is supported by ALL intermediate realms. - -Pre-authentication methods - -The TGS-REQ method must be supported. The TGS-REQ method is not used on the -initial request. The PA-ENC-TIMESTAMP method must be supported by clients -but whether it is enabled by default may be determined on a realm by realm -basis. If not used in the initial request and the error -KDC_ERR_PREAUTH_REQUIRED is returned specifying PA-ENC-TIMESTAMP as an -acceptable method, the client should retry the initial request using the -PA-ENC-TIMESTAMP preauthentication method. Servers need not support the -PA-ENC-TIMESTAMP method, but if not supported the server should ignore the -presence of PA-ENC-TIMESTAMP pre-authentication in a request. - - -Neuman, Ts'o, Kohl Expires: 25 December, -1999 - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, -1999 - -Mutual authentication - -Mutual authentication (via the KRB_AP_REP message) must be supported. - -Ticket addresses and flags - -All KDC's must pass on tickets that carry no addresses (i.e. if a TGT -contains no addresses, the KDC will return derivative tickets), but each -realm may set its own policy for issuing such tickets, and each application -server will set its own policy with respect to accepting them. - -Proxies and forwarded tickets must be supported. Individual realms and -application servers can set their own policy on when such tickets will be -accepted. - -All implementations must recognize renewable and postdated tickets, but need -not actually implement them. If these options are not supported, the -starttime and endtime in the ticket shall specify a ticket's entire useful -life. When a postdated ticket is decoded by a server, all implementations -shall make the presence of the postdated flag visible to the calling server. - -User-to-user authentication - -Support for user to user authentication (via the ENC-TKT-IN-SKEY KDC option) -must be provided by implementations, but individual realms may decide as a -matter of policy to reject such requests on a per-principal or realm-wide -basis. - -Authorization data - -Implementations must pass all authorization data subfields from -ticket-granting tickets to any derivative tickets unless directed to -suppress a subfield as part of the definition of that registered subfield -type (it is never incorrect to pass on a subfield, and no registered -subfield types presently specify suppression at the KDC). - -Implementations must make the contents of any authorization data subfields -available to the server when a ticket is used. Implementations are not -required to allow clients to specify the contents of the authorization data -fields. - -Constant ranges - -All protocol constants are constrained to 32 bit (signed) values unless -further constrained by the protocol definition. This limit is provided to -allow implementations to make assumptions about the maximum values that will -be received for these constants. Implementation receiving values outside -this range may reject the request, but they must recover cleanly. - -9.2. Recommended KDC values - -Following is a list of recommended values for a KDC implementation, based on -the list of suggested configuration constants (see section 4.4). - -minimum lifetime 5 minutes -maximum renewable lifetime 1 week -maximum ticket lifetime 1 day -empty addresses only when suitable restrictions appear - in authorization data -proxiable, etc. Allowed. - - -Neuman, Ts'o, Kohl Expires: 25 December, -1999 - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, -1999 - -10. REFERENCES - -[NT94] B. Clifford Neuman and Theodore Y. Ts'o, "An Authenti- - cation Service for Computer Networks," IEEE Communica- - tions Magazine, Vol. 32(9), pp. 33-38 (September 1994). - -[MNSS87] S. P. Miller, B. C. Neuman, J. I. Schiller, and J. H. - Saltzer, Section E.2.1: Kerberos Authentication and - Authorization System, M.I.T. Project Athena, Cambridge, - Massachusetts (December 21, 1987). - -[SNS88] J. G. Steiner, B. C. Neuman, and J. I. Schiller, "Ker- - beros: An Authentication Service for Open Network Sys- - tems," pp. 191-202 in Usenix Conference Proceedings, - Dallas, Texas (February, 1988). - -[NS78] Roger M. Needham and Michael D. Schroeder, "Using - Encryption for Authentication in Large Networks of Com- - puters," Communications of the ACM, Vol. 21(12), - pp. 993-999 (December, 1978). - -[DS81] Dorothy E. Denning and Giovanni Maria Sacco, "Time- - stamps in Key Distribution Protocols," Communications - of the ACM, Vol. 24(8), pp. 533-536 (August 1981). - -[KNT92] John T. Kohl, B. Clifford Neuman, and Theodore Y. Ts'o, - "The Evolution of the Kerberos Authentication Service," - in an IEEE Computer Society Text soon to be published - (June 1992). - -[Neu93] B. Clifford Neuman, "Proxy-Based Authorization and - Accounting for Distributed Systems," in Proceedings of - the 13th International Conference on Distributed Com- - puting Systems, Pittsburgh, PA (May, 1993). - -[DS90] Don Davis and Ralph Swick, "Workstation Services and - Kerberos Authentication at Project Athena," Technical - Memorandum TM-424, MIT Laboratory for Computer Science - (February 1990). - -[LGDSR87] P. J. Levine, M. R. Gretzinger, J. M. Diaz, W. E. Som- - merfeld, and K. Raeburn, Section E.1: Service Manage- - ment System, M.I.T. Project Athena, Cambridge, Mas- - sachusetts (1987). - -[X509-88] CCITT, Recommendation X.509: The Directory Authentica- - tion Framework, December 1988. - -[Pat92]. J. Pato, Using Pre-Authentication to Avoid Password - Guessing Attacks, Open Software Foundation DCE Request - for Comments 26 (December 1992). - -[DES77] National Bureau of Standards, U.S. Department of Com- - merce, "Data Encryption Standard," Federal Information - Processing Standards Publication 46, Washington, DC - (1977). - - -Neuman, Ts'o, Kohl Expires: 25 December, -1999 - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, -1999 - -[DESM80] National Bureau of Standards, U.S. Department of Com- - merce, "DES Modes of Operation," Federal Information - Processing Standards Publication 81, Springfield, VA - (December 1980). - -[SG92] Stuart G. Stubblebine and Virgil D. Gligor, "On Message - Integrity in Cryptographic Protocols," in Proceedings - of the IEEE Symposium on Research in Security and - Privacy, Oakland, California (May 1992). - -[IS3309] International Organization for Standardization, "ISO - Information Processing Systems - Data Communication - - High-Level Data Link Control Procedure - Frame Struc- - ture," IS 3309 (October 1984). 3rd Edition. - -[MD4-92] R. Rivest, "The MD4 Message Digest Algorithm," RFC - 1320, MIT Laboratory for Computer Science (April - 1992). - -[MD5-92] R. Rivest, "The MD5 Message Digest Algorithm," RFC - 1321, MIT Laboratory for Computer Science (April - 1992). - -[KBC96] H. Krawczyk, M. Bellare, and R. Canetti, "HMAC: Keyed- - Hashing for Message Authentication," Working Draft - draft-ietf-ipsec-hmac-md5-01.txt, (August 1996). - -[Horowitz96] Horowitz, M., "Key Derivation for Authentication, - Integrity, and Privacy", draft-horowitz-key-derivation-02.txt, - August 1998. - -[HorowitzB96] Horowitz, M., "Key Derivation for Kerberos V5", draft- - horowitz-kerb-key-derivation-01.txt, September 1998. - -[Krawczyk96] Krawczyk, H., Bellare, and M., Canetti, R., "HMAC: - Keyed-Hashing for Message Authentication", draft-ietf-ipsec-hmac- - md5-01.txt, August, 1996. - - -Neuman, Ts'o, Kohl Expires: 25 December, -1999 - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, -1999 - -A. Pseudo-code for protocol processing - -This appendix provides pseudo-code describing how the messages are to be -constructed and interpreted by clients and servers. - -A.1. KRB_AS_REQ generation - - request.pvno := protocol version; /* pvno = 5 */ - request.msg-type := message type; /* type = KRB_AS_REQ */ - - if(pa_enc_timestamp_required) then - request.padata.padata-type = PA-ENC-TIMESTAMP; - get system_time; - padata-body.patimestamp,pausec = system_time; - encrypt padata-body into request.padata.padata-value - using client.key; /* derived from password */ - endif - - body.kdc-options := users's preferences; - body.cname := user's name; - body.realm := user's realm; - body.sname := service's name; /* usually "krbtgt", "localrealm" */ - if (body.kdc-options.POSTDATED is set) then - body.from := requested starting time; - else - omit body.from; - endif - body.till := requested end time; - if (body.kdc-options.RENEWABLE is set) then - body.rtime := requested final renewal time; - endif - body.nonce := random_nonce(); - body.etype := requested etypes; - if (user supplied addresses) then - body.addresses := user's addresses; - else - omit body.addresses; - endif - omit body.enc-authorization-data; - request.req-body := body; - - kerberos := lookup(name of local kerberos server (or servers)); - send(packet,kerberos); - - wait(for response); - if (timed_out) then - retry or use alternate server; - endif - - -Neuman, Ts'o, Kohl Expires: 25 December, -1999 - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, -1999 - -A.2. KRB_AS_REQ verification and KRB_AS_REP generation - - decode message into req; - - client := lookup(req.cname,req.realm); - server := lookup(req.sname,req.realm); - - get system_time; - kdc_time := system_time.seconds; - - if (!client) then - /* no client in Database */ - error_out(KDC_ERR_C_PRINCIPAL_UNKNOWN); - endif - if (!server) then - /* no server in Database */ - error_out(KDC_ERR_S_PRINCIPAL_UNKNOWN); - endif - - if(client.pa_enc_timestamp_required and - pa_enc_timestamp not present) then - error_out(KDC_ERR_PREAUTH_REQUIRED(PA_ENC_TIMESTAMP)); - endif - - if(pa_enc_timestamp present) then - decrypt req.padata-value into decrypted_enc_timestamp - using client.key; - using auth_hdr.authenticator.subkey; - if (decrypt_error()) then - error_out(KRB_AP_ERR_BAD_INTEGRITY); - if(decrypted_enc_timestamp is not within allowable skew) -then - error_out(KDC_ERR_PREAUTH_FAILED); - endif - if(decrypted_enc_timestamp and usec is replay) - error_out(KDC_ERR_PREAUTH_FAILED); - endif - add decrypted_enc_timestamp and usec to replay cache; - endif - - use_etype := first supported etype in req.etypes; - - if (no support for req.etypes) then - error_out(KDC_ERR_ETYPE_NOSUPP); - endif - - new_tkt.vno := ticket version; /* = 5 */ - new_tkt.sname := req.sname; - new_tkt.srealm := req.srealm; - reset all flags in new_tkt.flags; - - /* It should be noted that local policy may affect the */ - /* processing of any of these flags. For example, some */ - /* realms may refuse to issue renewable tickets */ - - if (req.kdc-options.FORWARDABLE is set) then - set new_tkt.flags.FORWARDABLE; - endif - if (req.kdc-options.PROXIABLE is set) then - -Neuman, Ts'o, Kohl Expires: 25 December, -1999 - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, -1999 - - set new_tkt.flags.PROXIABLE; - endif - - if (req.kdc-options.ALLOW-POSTDATE is set) then - set new_tkt.flags.MAY-POSTDATE; - endif - if ((req.kdc-options.RENEW is set) or - (req.kdc-options.VALIDATE is set) or - (req.kdc-options.PROXY is set) or - (req.kdc-options.FORWARDED is set) or - (req.kdc-options.ENC-TKT-IN-SKEY is set)) then - error_out(KDC_ERR_BADOPTION); - endif - - new_tkt.session := random_session_key(); - new_tkt.cname := req.cname; - new_tkt.crealm := req.crealm; - new_tkt.transited := empty_transited_field(); - - new_tkt.authtime := kdc_time; - - if (req.kdc-options.POSTDATED is set) then - if (against_postdate_policy(req.from)) then - error_out(KDC_ERR_POLICY); - endif - set new_tkt.flags.POSTDATED; - set new_tkt.flags.INVALID; - new_tkt.starttime := req.from; - else - omit new_tkt.starttime; /* treated as authtime when omitted */ - endif - if (req.till = 0) then - till := infinity; - else - till := req.till; - endif - - new_tkt.endtime := min(till, - new_tkt.starttime+client.max_life, - new_tkt.starttime+server.max_life, - new_tkt.starttime+max_life_for_realm); - - if ((req.kdc-options.RENEWABLE-OK is set) and - (new_tkt.endtime < req.till)) then - /* we set the RENEWABLE option for later processing */ - set req.kdc-options.RENEWABLE; - req.rtime := req.till; - endif - - if (req.rtime = 0) then - rtime := infinity; - else - rtime := req.rtime; - endif - - if (req.kdc-options.RENEWABLE is set) then - set new_tkt.flags.RENEWABLE; - new_tkt.renew-till := min(rtime, - -Neuman, Ts'o, Kohl Expires: 25 December, -1999 - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, -1999 - - new_tkt.starttime+client.max_rlife, - new_tkt.starttime+server.max_rlife, - new_tkt.starttime+max_rlife_for_realm); - else - omit new_tkt.renew-till; /* only present if RENEWABLE */ - endif - - if (req.addresses) then - new_tkt.caddr := req.addresses; - else - omit new_tkt.caddr; - endif - - new_tkt.authorization_data := empty_authorization_data(); - - encode to-be-encrypted part of ticket into OCTET STRING; - new_tkt.enc-part := encrypt OCTET STRING - using etype_for_key(server.key), server.key, server.p_kvno; - - /* Start processing the response */ - - resp.pvno := 5; - resp.msg-type := KRB_AS_REP; - resp.cname := req.cname; - resp.crealm := req.realm; - resp.ticket := new_tkt; - - resp.key := new_tkt.session; - resp.last-req := fetch_last_request_info(client); - resp.nonce := req.nonce; - resp.key-expiration := client.expiration; - resp.flags := new_tkt.flags; - - resp.authtime := new_tkt.authtime; - resp.starttime := new_tkt.starttime; - resp.endtime := new_tkt.endtime; - - if (new_tkt.flags.RENEWABLE) then - resp.renew-till := new_tkt.renew-till; - endif - - resp.realm := new_tkt.realm; - resp.sname := new_tkt.sname; - - resp.caddr := new_tkt.caddr; - - encode body of reply into OCTET STRING; - - resp.enc-part := encrypt OCTET STRING - using use_etype, client.key, client.p_kvno; - send(resp); - - -Neuman, Ts'o, Kohl Expires: 25 December, -1999 - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, -1999 - -A.3. KRB_AS_REP verification - - decode response into resp; - - if (resp.msg-type = KRB_ERROR) then - if(error = KDC_ERR_PREAUTH_REQUIRED(PA_ENC_TIMESTAMP)) then - set pa_enc_timestamp_required; - goto KRB_AS_REQ; - endif - process_error(resp); - return; - endif - - /* On error, discard the response, and zero the session key */ - /* from the response immediately */ - - key = get_decryption_key(resp.enc-part.kvno, resp.enc-part.etype, - resp.padata); - unencrypted part of resp := decode of decrypt of resp.enc-part - using resp.enc-part.etype and key; - zero(key); - - if (common_as_rep_tgs_rep_checks fail) then - destroy resp.key; - return error; - endif - - if near(resp.princ_exp) then - print(warning message); - endif - save_for_later(ticket,session,client,server,times,flags); - -A.4. KRB_AS_REP and KRB_TGS_REP common checks - - if (decryption_error() or - (req.cname != resp.cname) or - (req.realm != resp.crealm) or - (req.sname != resp.sname) or - (req.realm != resp.realm) or - (req.nonce != resp.nonce) or - (req.addresses != resp.caddr)) then - destroy resp.key; - return KRB_AP_ERR_MODIFIED; - endif - - /* make sure no flags are set that shouldn't be, and that all that -*/ - /* should be are set -*/ - if (!check_flags_for_compatability(req.kdc-options,resp.flags)) then - destroy resp.key; - return KRB_AP_ERR_MODIFIED; - endif - - if ((req.from = 0) and - (resp.starttime is not within allowable skew)) then - destroy resp.key; - return KRB_AP_ERR_SKEW; - endif - if ((req.from != 0) and (req.from != resp.starttime)) then - -Neuman, Ts'o, Kohl Expires: 25 December, -1999 - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, -1999 - - destroy resp.key; - return KRB_AP_ERR_MODIFIED; - endif - if ((req.till != 0) and (resp.endtime > req.till)) then - destroy resp.key; - return KRB_AP_ERR_MODIFIED; - endif - - if ((req.kdc-options.RENEWABLE is set) and - (req.rtime != 0) and (resp.renew-till > req.rtime)) then - destroy resp.key; - return KRB_AP_ERR_MODIFIED; - endif - if ((req.kdc-options.RENEWABLE-OK is set) and - (resp.flags.RENEWABLE) and - (req.till != 0) and - (resp.renew-till > req.till)) then - destroy resp.key; - return KRB_AP_ERR_MODIFIED; - endif - -A.5. KRB_TGS_REQ generation - - /* Note that make_application_request might have to recursivly -*/ - /* call this routine to get the appropriate ticket-granting ticket -*/ - - request.pvno := protocol version; /* pvno = 5 */ - request.msg-type := message type; /* type = KRB_TGS_REQ */ - - body.kdc-options := users's preferences; - /* If the TGT is not for the realm of the end-server */ - /* then the sname will be for a TGT for the end-realm */ - /* and the realm of the requested ticket (body.realm) */ - /* will be that of the TGS to which the TGT we are */ - /* sending applies */ - body.sname := service's name; - body.realm := service's realm; - - if (body.kdc-options.POSTDATED is set) then - body.from := requested starting time; - else - omit body.from; - endif - body.till := requested end time; - if (body.kdc-options.RENEWABLE is set) then - body.rtime := requested final renewal time; - endif - body.nonce := random_nonce(); - body.etype := requested etypes; - if (user supplied addresses) then - body.addresses := user's addresses; - else - omit body.addresses; - endif - - body.enc-authorization-data := user-supplied data; - if (body.kdc-options.ENC-TKT-IN-SKEY) then - body.additional-tickets_ticket := second TGT; - -Neuman, Ts'o, Kohl Expires: 25 December, -1999 - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, -1999 - - endif - - request.req-body := body; - check := generate_checksum (req.body,checksumtype); - - request.padata[0].padata-type := PA-TGS-REQ; - request.padata[0].padata-value := create a KRB_AP_REQ using - the TGT and checksum - - /* add in any other padata as required/supplied */ - - kerberos := lookup(name of local kerberose server (or servers)); - send(packet,kerberos); - - wait(for response); - if (timed_out) then - retry or use alternate server; - endif - -A.6. KRB_TGS_REQ verification and KRB_TGS_REP generation - - /* note that reading the application request requires first - determining the server for which a ticket was issued, and choosing -the - correct key for decryption. The name of the server appears in the - plaintext part of the ticket. */ - - if (no KRB_AP_REQ in req.padata) then - error_out(KDC_ERR_PADATA_TYPE_NOSUPP); - endif - verify KRB_AP_REQ in req.padata; - - /* Note that the realm in which the Kerberos server is operating is - determined by the instance from the ticket-granting ticket. The -realm - in the ticket-granting ticket is the realm under which the ticket - granting ticket was issued. It is possible for a single Kerberos - server to support more than one realm. */ - - auth_hdr := KRB_AP_REQ; - tgt := auth_hdr.ticket; - - if (tgt.sname is not a TGT for local realm and is not req.sname) -then - error_out(KRB_AP_ERR_NOT_US); - - realm := realm_tgt_is_for(tgt); - - decode remainder of request; - - if (auth_hdr.authenticator.cksum is missing) then - error_out(KRB_AP_ERR_INAPP_CKSUM); - endif - - if (auth_hdr.authenticator.cksum type is not supported) then - error_out(KDC_ERR_SUMTYPE_NOSUPP); - endif - if (auth_hdr.authenticator.cksum is not both collision-proof and - keyed) then - error_out(KRB_AP_ERR_INAPP_CKSUM); - endif - -Neuman, Ts'o, Kohl Expires: 25 December, -1999 - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, -1999 - - set computed_checksum := checksum(req); - if (computed_checksum != auth_hdr.authenticatory.cksum) then - error_out(KRB_AP_ERR_MODIFIED); - endif - - server := lookup(req.sname,realm); - - if (!server) then - if (is_foreign_tgt_name(req.sname)) then - server := best_intermediate_tgs(req.sname); - else - /* no server in Database */ - error_out(KDC_ERR_S_PRINCIPAL_UNKNOWN); - endif - endif - - session := generate_random_session_key(); - - use_etype := first supported etype in req.etypes; - - if (no support for req.etypes) then - error_out(KDC_ERR_ETYPE_NOSUPP); - endif - - new_tkt.vno := ticket version; /* = 5 */ - new_tkt.sname := req.sname; - new_tkt.srealm := realm; - reset all flags in new_tkt.flags; - - /* It should be noted that local policy may affect the */ - /* processing of any of these flags. For example, some */ - /* realms may refuse to issue renewable tickets */ - - new_tkt.caddr := tgt.caddr; - resp.caddr := NULL; /* We only include this if they change */ - if (req.kdc-options.FORWARDABLE is set) then - if (tgt.flags.FORWARDABLE is reset) then - error_out(KDC_ERR_BADOPTION); - endif - set new_tkt.flags.FORWARDABLE; - endif - if (req.kdc-options.FORWARDED is set) then - if (tgt.flags.FORWARDABLE is reset) then - error_out(KDC_ERR_BADOPTION); - endif - set new_tkt.flags.FORWARDED; - new_tkt.caddr := req.addresses; - resp.caddr := req.addresses; - endif - if (tgt.flags.FORWARDED is set) then - set new_tkt.flags.FORWARDED; - endif - - if (req.kdc-options.PROXIABLE is set) then - if (tgt.flags.PROXIABLE is reset) - error_out(KDC_ERR_BADOPTION); - endif - -Neuman, Ts'o, Kohl Expires: 25 December, -1999 - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, -1999 - - set new_tkt.flags.PROXIABLE; - endif - if (req.kdc-options.PROXY is set) then - if (tgt.flags.PROXIABLE is reset) then - error_out(KDC_ERR_BADOPTION); - endif - set new_tkt.flags.PROXY; - new_tkt.caddr := req.addresses; - resp.caddr := req.addresses; - endif - - if (req.kdc-options.ALLOW-POSTDATE is set) then - if (tgt.flags.MAY-POSTDATE is reset) - error_out(KDC_ERR_BADOPTION); - endif - set new_tkt.flags.MAY-POSTDATE; - endif - if (req.kdc-options.POSTDATED is set) then - if (tgt.flags.MAY-POSTDATE is reset) then - error_out(KDC_ERR_BADOPTION); - endif - set new_tkt.flags.POSTDATED; - set new_tkt.flags.INVALID; - if (against_postdate_policy(req.from)) then - error_out(KDC_ERR_POLICY); - endif - new_tkt.starttime := req.from; - endif - - if (req.kdc-options.VALIDATE is set) then - if (tgt.flags.INVALID is reset) then - error_out(KDC_ERR_POLICY); - endif - if (tgt.starttime > kdc_time) then - error_out(KRB_AP_ERR_NYV); - endif - if (check_hot_list(tgt)) then - error_out(KRB_AP_ERR_REPEAT); - endif - tkt := tgt; - reset new_tkt.flags.INVALID; - endif - - if (req.kdc-options.(any flag except ENC-TKT-IN-SKEY, RENEW, - and those already processed) is set) then - error_out(KDC_ERR_BADOPTION); - endif - - new_tkt.authtime := tgt.authtime; - - if (req.kdc-options.RENEW is set) then - /* Note that if the endtime has already passed, the ticket would -*/ - /* have been rejected in the initial authentication stage, so -*/ - /* there is no need to check again here -*/ - if (tgt.flags.RENEWABLE is reset) then - error_out(KDC_ERR_BADOPTION); - endif - if (tgt.renew-till < kdc_time) then - -Neuman, Ts'o, Kohl Expires: 25 December, -1999 - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, -1999 - - error_out(KRB_AP_ERR_TKT_EXPIRED); - endif - tkt := tgt; - new_tkt.starttime := kdc_time; - old_life := tgt.endttime - tgt.starttime; - new_tkt.endtime := min(tgt.renew-till, - new_tkt.starttime + old_life); - else - new_tkt.starttime := kdc_time; - if (req.till = 0) then - till := infinity; - else - till := req.till; - endif - new_tkt.endtime := min(till, - new_tkt.starttime+client.max_life, - new_tkt.starttime+server.max_life, - new_tkt.starttime+max_life_for_realm, - tgt.endtime); - - if ((req.kdc-options.RENEWABLE-OK is set) and - (new_tkt.endtime < req.till) and - (tgt.flags.RENEWABLE is set) then - /* we set the RENEWABLE option for later processing -*/ - set req.kdc-options.RENEWABLE; - req.rtime := min(req.till, tgt.renew-till); - endif - endif - - if (req.rtime = 0) then - rtime := infinity; - else - rtime := req.rtime; - endif - - if ((req.kdc-options.RENEWABLE is set) and - (tgt.flags.RENEWABLE is set)) then - set new_tkt.flags.RENEWABLE; - new_tkt.renew-till := min(rtime, - new_tkt.starttime+client.max_rlife, - new_tkt.starttime+server.max_rlife, - new_tkt.starttime+max_rlife_for_realm, - tgt.renew-till); - else - new_tkt.renew-till := OMIT; /* leave the renew-till field out -*/ - endif - if (req.enc-authorization-data is present) then - decrypt req.enc-authorization-data into -decrypted_authorization_data - using auth_hdr.authenticator.subkey; - if (decrypt_error()) then - error_out(KRB_AP_ERR_BAD_INTEGRITY); - endif - endif - new_tkt.authorization_data := req.auth_hdr.ticket.authorization_data -+ - decrypted_authorization_data; - - new_tkt.key := session; - new_tkt.crealm := tgt.crealm; - -Neuman, Ts'o, Kohl Expires: 25 December, -1999 - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, -1999 - - new_tkt.cname := req.auth_hdr.ticket.cname; - - if (realm_tgt_is_for(tgt) := tgt.realm) then - /* tgt issued by local realm */ - new_tkt.transited := tgt.transited; - else - /* was issued for this realm by some other realm */ - if (tgt.transited.tr-type not supported) then - error_out(KDC_ERR_TRTYPE_NOSUPP); - endif - new_tkt.transited := compress_transited(tgt.transited + -tgt.realm) - /* Don't check tranited field if TGT for foreign realm, - * or requested not to check */ - if (is_not_foreign_tgt_name(new_tkt.server) - && req.kdc-options.DISABLE-TRANSITED-CHECK not set) then - /* Check it, so end-server does not have to - * but don't fail, end-server may still accept it */ - if (check_transited_field(new_tkt.transited) == OK) - set new_tkt.flags.TRANSITED-POLICY-CHECKED; - endif - endif - endif - - encode encrypted part of new_tkt into OCTET STRING; - if (req.kdc-options.ENC-TKT-IN-SKEY is set) then - if (server not specified) then - server = req.second_ticket.client; - endif - if ((req.second_ticket is not a TGT) or - (req.second_ticket.client != server)) then - error_out(KDC_ERR_POLICY); - endif - - new_tkt.enc-part := encrypt OCTET STRING using - using etype_for_key(second-ticket.key), second-ticket.key; - else - new_tkt.enc-part := encrypt OCTET STRING - using etype_for_key(server.key), server.key, server.p_kvno; - endif - - resp.pvno := 5; - resp.msg-type := KRB_TGS_REP; - resp.crealm := tgt.crealm; - resp.cname := tgt.cname; - resp.ticket := new_tkt; - - resp.key := session; - resp.nonce := req.nonce; - resp.last-req := fetch_last_request_info(client); - resp.flags := new_tkt.flags; - - resp.authtime := new_tkt.authtime; - resp.starttime := new_tkt.starttime; - resp.endtime := new_tkt.endtime; - - omit resp.key-expiration; - - resp.sname := new_tkt.sname; - -Neuman, Ts'o, Kohl Expires: 25 December, -1999 - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, -1999 - - resp.realm := new_tkt.realm; - - if (new_tkt.flags.RENEWABLE) then - resp.renew-till := new_tkt.renew-till; - endif - - encode body of reply into OCTET STRING; - - if (req.padata.authenticator.subkey) - resp.enc-part := encrypt OCTET STRING using use_etype, - req.padata.authenticator.subkey; - else resp.enc-part := encrypt OCTET STRING using use_etype, tgt.key; - - send(resp); - -A.7. KRB_TGS_REP verification - - decode response into resp; - - if (resp.msg-type = KRB_ERROR) then - process_error(resp); - return; - endif - - /* On error, discard the response, and zero the session key from - the response immediately */ - - if (req.padata.authenticator.subkey) - unencrypted part of resp := decode of decrypt of -resp.enc-part - using resp.enc-part.etype and subkey; - else unencrypted part of resp := decode of decrypt of resp.enc-part - using resp.enc-part.etype and tgt's session key; - if (common_as_rep_tgs_rep_checks fail) then - destroy resp.key; - return error; - endif - - check authorization_data as necessary; - save_for_later(ticket,session,client,server,times,flags); - -A.8. Authenticator generation - - body.authenticator-vno := authenticator vno; /* = 5 */ - body.cname, body.crealm := client name; - if (supplying checksum) then - body.cksum := checksum; - endif - get system_time; - body.ctime, body.cusec := system_time; - if (selecting sub-session key) then - select sub-session key; - body.subkey := sub-session key; - endif - if (using sequence numbers) then - select initial sequence number; - body.seq-number := initial sequence; - endif - - -Neuman, Ts'o, Kohl Expires: 25 December, -1999 - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, -1999 - -A.9. KRB_AP_REQ generation - - obtain ticket and session_key from cache; - - packet.pvno := protocol version; /* 5 */ - packet.msg-type := message type; /* KRB_AP_REQ */ - - if (desired(MUTUAL_AUTHENTICATION)) then - set packet.ap-options.MUTUAL-REQUIRED; - else - reset packet.ap-options.MUTUAL-REQUIRED; - endif - if (using session key for ticket) then - set packet.ap-options.USE-SESSION-KEY; - else - reset packet.ap-options.USE-SESSION-KEY; - endif - packet.ticket := ticket; /* ticket */ - generate authenticator; - encode authenticator into OCTET STRING; - encrypt OCTET STRING into packet.authenticator using session_key; - -A.10. KRB_AP_REQ verification - - receive packet; - if (packet.pvno != 5) then - either process using other protocol spec - or error_out(KRB_AP_ERR_BADVERSION); - endif - if (packet.msg-type != KRB_AP_REQ) then - error_out(KRB_AP_ERR_MSG_TYPE); - endif - if (packet.ticket.tkt_vno != 5) then - either process using other protocol spec - or error_out(KRB_AP_ERR_BADVERSION); - endif - if (packet.ap_options.USE-SESSION-KEY is set) then - retrieve session key from ticket-granting ticket for - packet.ticket.{sname,srealm,enc-part.etype}; - else - retrieve service key for - packet.ticket.{sname,srealm,enc-part.etype,enc-part.skvno}; - endif - if (no_key_available) then - if (cannot_find_specified_skvno) then - error_out(KRB_AP_ERR_BADKEYVER); - else - error_out(KRB_AP_ERR_NOKEY); - endif - endif - decrypt packet.ticket.enc-part into decr_ticket using retrieved key; - if (decryption_error()) then - error_out(KRB_AP_ERR_BAD_INTEGRITY); - endif - decrypt packet.authenticator into decr_authenticator - using decr_ticket.key; - if (decryption_error()) then - error_out(KRB_AP_ERR_BAD_INTEGRITY); - -Neuman, Ts'o, Kohl Expires: 25 December, -1999 - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, -1999 - - endif - if (decr_authenticator.{cname,crealm} != - decr_ticket.{cname,crealm}) then - error_out(KRB_AP_ERR_BADMATCH); - endif - if (decr_ticket.caddr is present) then - if (sender_address(packet) is not in decr_ticket.caddr) then - error_out(KRB_AP_ERR_BADADDR); - endif - elseif (application requires addresses) then - error_out(KRB_AP_ERR_BADADDR); - endif - if (not in_clock_skew(decr_authenticator.ctime, - decr_authenticator.cusec)) then - error_out(KRB_AP_ERR_SKEW); - endif - if (repeated(decr_authenticator.{ctime,cusec,cname,crealm})) then - error_out(KRB_AP_ERR_REPEAT); - endif - save_identifier(decr_authenticator.{ctime,cusec,cname,crealm}); - get system_time; - if ((decr_ticket.starttime-system_time > CLOCK_SKEW) or - (decr_ticket.flags.INVALID is set)) then - /* it hasn't yet become valid */ - error_out(KRB_AP_ERR_TKT_NYV); - endif - if (system_time-decr_ticket.endtime > CLOCK_SKEW) then - error_out(KRB_AP_ERR_TKT_EXPIRED); - endif - if (decr_ticket.transited) then - /* caller may ignore the TRANSITED-POLICY-CHECKED and do - * check anyway */ - if (decr_ticket.flags.TRANSITED-POLICY-CHECKED not set) then - if (check_transited_field(decr_ticket.transited) then - error_out(KDC_AP_PATH_NOT_ACCPETED); - endif - endif - endif - /* caller must check decr_ticket.flags for any pertinent details */ - return(OK, decr_ticket, packet.ap_options.MUTUAL-REQUIRED); - - -Neuman, Ts'o, Kohl Expires: 25 December, -1999 - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, -1999 - -A.11. KRB_AP_REP generation - - packet.pvno := protocol version; /* 5 */ - packet.msg-type := message type; /* KRB_AP_REP */ - - body.ctime := packet.ctime; - body.cusec := packet.cusec; - if (selecting sub-session key) then - select sub-session key; - body.subkey := sub-session key; - endif - if (using sequence numbers) then - select initial sequence number; - body.seq-number := initial sequence; - endif - - encode body into OCTET STRING; - - select encryption type; - encrypt OCTET STRING into packet.enc-part; - -A.12. KRB_AP_REP verification - - receive packet; - if (packet.pvno != 5) then - either process using other protocol spec - or error_out(KRB_AP_ERR_BADVERSION); - endif - if (packet.msg-type != KRB_AP_REP) then - error_out(KRB_AP_ERR_MSG_TYPE); - endif - cleartext := decrypt(packet.enc-part) using ticket's session key; - if (decryption_error()) then - error_out(KRB_AP_ERR_BAD_INTEGRITY); - endif - if (cleartext.ctime != authenticator.ctime) then - error_out(KRB_AP_ERR_MUT_FAIL); - endif - if (cleartext.cusec != authenticator.cusec) then - error_out(KRB_AP_ERR_MUT_FAIL); - endif - if (cleartext.subkey is present) then - save cleartext.subkey for future use; - endif - if (cleartext.seq-number is present) then - save cleartext.seq-number for future verifications; - endif - return(AUTHENTICATION_SUCCEEDED); - - -Neuman, Ts'o, Kohl Expires: 25 December, -1999 - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, -1999 - -A.13. KRB_SAFE generation - - collect user data in buffer; - - /* assemble packet: */ - packet.pvno := protocol version; /* 5 */ - packet.msg-type := message type; /* KRB_SAFE */ - - body.user-data := buffer; /* DATA */ - if (using timestamp) then - get system_time; - body.timestamp, body.usec := system_time; - endif - if (using sequence numbers) then - body.seq-number := sequence number; - endif - body.s-address := sender host addresses; - if (only one recipient) then - body.r-address := recipient host address; - endif - checksum.cksumtype := checksum type; - compute checksum over body; - checksum.checksum := checksum value; /* checksum.checksum */ - packet.cksum := checksum; - packet.safe-body := body; - -A.14. KRB_SAFE verification - - receive packet; - if (packet.pvno != 5) then - either process using other protocol spec - or error_out(KRB_AP_ERR_BADVERSION); - endif - if (packet.msg-type != KRB_SAFE) then - error_out(KRB_AP_ERR_MSG_TYPE); - endif - if (packet.checksum.cksumtype is not both collision-proof - and keyed) then - error_out(KRB_AP_ERR_INAPP_CKSUM); - endif - if (safe_priv_common_checks_ok(packet)) then - set computed_checksum := checksum(packet.body); - if (computed_checksum != packet.checksum) then - error_out(KRB_AP_ERR_MODIFIED); - endif - return (packet, PACKET_IS_GENUINE); - else - return common_checks_error; - endif - -A.15. KRB_SAFE and KRB_PRIV common checks - - if (packet.s-address != O/S_sender(packet)) then - /* O/S report of sender not who claims to have sent it */ - error_out(KRB_AP_ERR_BADADDR); - endif - if ((packet.r-address is present) and - (packet.r-address != local_host_address)) then - -Neuman, Ts'o, Kohl Expires: 25 December, -1999 - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, -1999 - - /* was not sent to proper place */ - error_out(KRB_AP_ERR_BADADDR); - endif - if (((packet.timestamp is present) and - (not in_clock_skew(packet.timestamp,packet.usec))) or - (packet.timestamp is not present and timestamp expected)) then - error_out(KRB_AP_ERR_SKEW); - endif - if (repeated(packet.timestamp,packet.usec,packet.s-address)) then - error_out(KRB_AP_ERR_REPEAT); - endif - - if (((packet.seq-number is present) and - ((not in_sequence(packet.seq-number)))) or - (packet.seq-number is not present and sequence expected)) then - error_out(KRB_AP_ERR_BADORDER); - endif - if (packet.timestamp not present and packet.seq-number - not present) then - error_out(KRB_AP_ERR_MODIFIED); - endif - - save_identifier(packet.{timestamp,usec,s-address}, - sender_principal(packet)); - - return PACKET_IS_OK; - -A.16. KRB_PRIV generation - - collect user data in buffer; - - /* assemble packet: */ - packet.pvno := protocol version; /* 5 */ - packet.msg-type := message type; /* KRB_PRIV */ - - packet.enc-part.etype := encryption type; - - body.user-data := buffer; - if (using timestamp) then - get system_time; - body.timestamp, body.usec := system_time; - endif - if (using sequence numbers) then - body.seq-number := sequence number; - endif - body.s-address := sender host addresses; - if (only one recipient) then - body.r-address := recipient host address; - endif - - encode body into OCTET STRING; - - select encryption type; - encrypt OCTET STRING into packet.enc-part.cipher; - - -Neuman, Ts'o, Kohl Expires: 25 December, -1999 - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, -1999 - -A.17. KRB_PRIV verification - - receive packet; - if (packet.pvno != 5) then - either process using other protocol spec - or error_out(KRB_AP_ERR_BADVERSION); - endif - if (packet.msg-type != KRB_PRIV) then - error_out(KRB_AP_ERR_MSG_TYPE); - endif - - cleartext := decrypt(packet.enc-part) using negotiated key; - if (decryption_error()) then - error_out(KRB_AP_ERR_BAD_INTEGRITY); - endif - - if (safe_priv_common_checks_ok(cleartext)) then - return(cleartext.DATA, PACKET_IS_GENUINE_AND_UNMODIFIED); - else - return common_checks_error; - endif - -A.18. KRB_CRED generation - - invoke KRB_TGS; /* obtain tickets to be provided to peer */ - - /* assemble packet: */ - packet.pvno := protocol version; /* 5 */ - packet.msg-type := message type; /* KRB_CRED */ - - for (tickets[n] in tickets to be forwarded) do - packet.tickets[n] = tickets[n].ticket; - done - - packet.enc-part.etype := encryption type; - - for (ticket[n] in tickets to be forwarded) do - body.ticket-info[n].key = tickets[n].session; - body.ticket-info[n].prealm = tickets[n].crealm; - body.ticket-info[n].pname = tickets[n].cname; - body.ticket-info[n].flags = tickets[n].flags; - body.ticket-info[n].authtime = tickets[n].authtime; - body.ticket-info[n].starttime = tickets[n].starttime; - body.ticket-info[n].endtime = tickets[n].endtime; - body.ticket-info[n].renew-till = tickets[n].renew-till; - body.ticket-info[n].srealm = tickets[n].srealm; - body.ticket-info[n].sname = tickets[n].sname; - body.ticket-info[n].caddr = tickets[n].caddr; - done - - get system_time; - body.timestamp, body.usec := system_time; - - if (using nonce) then - body.nonce := nonce; - endif - - if (using s-address) then - -Neuman, Ts'o, Kohl Expires: 25 December, -1999 - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, -1999 - - body.s-address := sender host addresses; - endif - if (limited recipients) then - body.r-address := recipient host address; - endif - - encode body into OCTET STRING; - - select encryption type; - encrypt OCTET STRING into packet.enc-part.cipher - using negotiated encryption key; - -A.19. KRB_CRED verification - - receive packet; - if (packet.pvno != 5) then - either process using other protocol spec - or error_out(KRB_AP_ERR_BADVERSION); - endif - if (packet.msg-type != KRB_CRED) then - error_out(KRB_AP_ERR_MSG_TYPE); - endif - - cleartext := decrypt(packet.enc-part) using negotiated key; - if (decryption_error()) then - error_out(KRB_AP_ERR_BAD_INTEGRITY); - endif - if ((packet.r-address is present or required) and - (packet.s-address != O/S_sender(packet)) then - /* O/S report of sender not who claims to have sent it */ - error_out(KRB_AP_ERR_BADADDR); - endif - if ((packet.r-address is present) and - (packet.r-address != local_host_address)) then - /* was not sent to proper place */ - error_out(KRB_AP_ERR_BADADDR); - endif - if (not in_clock_skew(packet.timestamp,packet.usec)) then - error_out(KRB_AP_ERR_SKEW); - endif - if (repeated(packet.timestamp,packet.usec,packet.s-address)) then - error_out(KRB_AP_ERR_REPEAT); - endif - if (packet.nonce is required or present) and - (packet.nonce != expected-nonce) then - error_out(KRB_AP_ERR_MODIFIED); - endif - - for (ticket[n] in tickets that were forwarded) do - save_for_later(ticket[n],key[n],principal[n], - server[n],times[n],flags[n]); - return - - -Neuman, Ts'o, Kohl Expires: 25 December, -1999 - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, -1999 - -A.20. KRB_ERROR generation - - /* assemble packet: */ - packet.pvno := protocol version; /* 5 */ - packet.msg-type := message type; /* KRB_ERROR */ - - get system_time; - packet.stime, packet.susec := system_time; - packet.realm, packet.sname := server name; - - if (client time available) then - packet.ctime, packet.cusec := client_time; - endif - packet.error-code := error code; - if (client name available) then - packet.cname, packet.crealm := client name; - endif - if (error text available) then - packet.e-text := error text; - endif - if (error data available) then - packet.e-data := error data; - endif - - -Neuman, Ts'o, Kohl Expires: 25 December, -1999 - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, -1999 - -B. Definition of common authorization data elements - -This appendix contains the definitions of common authorization data -elements. These common authorization data elements are recursivly defined, -meaning the ad-data for these types will itself contain a sequence of -authorization data whose interpretation is affected by the encapsulating -element. Depending on the meaning of the encapsulating element, the -encapsulated elements may be ignored, might be interpreted as issued -directly by the KDC, or they might be stored in a separate plaintext part of -the ticket. The types of the encapsulating elements are specified as part of -the Kerberos specification because the behavior based on these values should -be understood across implementations whereas other elements need only be -understood by the applications which they affect. - -In the definitions that follow, the value of the ad-type for the element -will be specified in the subsection number, and the value of the ad-data -will be as shown in the ASN.1 structure that follows the subsection heading. - -B.1. If relevant - -AD-IF-RELEVANT AuthorizationData - -AD elements encapsulated within the if-relevant element are intended for -interpretation only by application servers that understand the particular -ad-type of the embedded element. Application servers that do not understand -the type of an element embedded within the if-relevant element may ignore -the uninterpretable element. This element promotes interoperability across -implementations which may have local extensions for authorization. - -B.2. Intended for server - -AD-INTENDED-FOR-SERVER SEQUENCE { - intended-server[0] SEQUENCE OF PrincipalName - elements[1] AuthorizationData -} - -AD elements encapsulated within the intended-for-server element may be -ignored if the application server is not in the list of principal names of -intended servers. Further, a KDC issuing a ticket for an application server -can remove this element if the application server is not in the list of -intended servers. - -Application servers should check for their principal name in the -intended-server field of this element. If their principal name is not found, -this element should be ignored. If found, then the encapsulated elements -should be evaluated in the same manner as if they were present in the top -level authorization data field. Applications and application servers that do -not implement this element should reject tickets that contain authorization -data elements of this type. - - -Neuman, Ts'o, Kohl Expires: 25 December, -1999 - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, -1999 - -B.3. Intended for application class - -AD-INTENDED-FOR-APPLICATION-CLASS SEQUENCE { intended-application-class[0] -SEQUENCE OF GeneralString elements[1] AuthorizationData } AD elements -encapsulated within the intended-for-application-class element may be -ignored if the application server is not in one of the named classes of -application servers. Examples of application server classes include -"FILESYSTEM", and other kinds of servers. - -This element and the elements it encapulates may be safely ignored by -applications, application servers, and KDCs that do not implement this -element. - -B.4. KDC Issued - -AD-KDCIssued SEQUENCE { - ad-checksum[0] Checksum, - i-realm[1] Realm OPTIONAL, - i-sname[2] PrincipalName OPTIONAL, - elements[3] AuthorizationData. -} - -ad-checksum - A checksum over the elements field using a cryptographic checksum - method that is identical to the checksum used to protect the ticket - itself (i.e. using the same hash function and the same encryption - algorithm used to encrypt the ticket) and using a key derived from the - same key used to protect the ticket. -i-realm, i-sname - The name of the issuing principal if different from the KDC itself. - This field would be used when the KDC can verify the authenticity of - elements signed by the issuing principal and it allows this KDC to - notify the application server of the validity of those elements. -elements - A sequence of authorization data elements issued by the KDC. - -The KDC-issued ad-data field is intended to provide a means for Kerberos -principal credentials to embed within themselves privilege attributes and -other mechanisms for positive authorization, amplifying the priveleges of -the principal beyond what can be done using a credentials without such an -a-data element. - -This can not be provided without this element because the definition of the -authorization-data field allows elements to be added at will by the bearer -of a TGT at the time that they request service tickets and elements may also -be added to a delegated ticket by inclusion in the authenticator. - -For KDC-issued elements this is prevented because the elements are signed by -the KDC by including a checksum encrypted using the server's key (the same -key used to encrypt the ticket - or a key derived from that key). Elements -encapsulated with in the KDC-issued element will be ignored by the -application server if this "signature" is not present. Further, elements -encapsulated within this element from a ticket granting ticket may be -interpreted by the KDC, and used as a basis according to policy for -including new signed elements within derivative tickets, but they will not -be copied to a derivative ticket directly. If they are copied directly to a -derivative ticket by a KDC that is not aware of this element, the signature -will not be correct for the application ticket elements, and the field will -be ignored by the application server. - -This element and the elements it encapulates may be safely ignored by -applications, application servers, and KDCs that do not implement this -element. - - -Neuman, Ts'o, Kohl Expires: 25 December, -1999 - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, -1999 - -B.5. And-Or - -AD-AND-OR SEQUENCE { - condition-count[0] INTEGER, - elements[1] AuthorizationData -} - -When restrictive AD elements encapsulated within the and-or element are -encountered, only the number specified in condition-count of the -encapsulated conditions must be met in order to satisfy this element. This -element may be used to implement an "or" operation by setting the -condition-count field to 1, and it may specify an "and" operation by setting -the condition count to the number of embedded elements. Application servers -that do not implement this element must reject tickets that contain -authorization data elements of this type. - -B.6. Mandatory ticket extensions - -AD-Mandatory-Ticket-Extensions Checksum - -An authorization data element of type mandatory-ticket-extensions specifies -a collision-proof checksum using the same hash algorithm used to protect the -integrity of the ticket itself. This checksum will be calculated over an -individual extension field. If there are more than one extension, multiple -Mandatory-Ticket-Extensions authorization data elements may be present, each -with a checksum for a different extension field. This restriction indicates -that the ticket should not be accepted if a ticket extension is not present -in the ticket for which the checksum does not match that checksum specified -in the authorization data element. Application servers that do not implement -this element must reject tickets that contain authorization data elements of -this type. - -B.7. Authorization Data in ticket extensions - -AD-IN-Ticket-Extensions Checksum - -An authorization data element of type in-ticket-extensions specifies a -collision-proof checksum using the same hash algorithm used to protect the -integrity of the ticket itself. This checksum is calculated over a separate -external AuthorizationData field carried in the ticket extensions. -Application servers that do not implement this element must reject tickets -that contain authorization data elements of this type. Application servers -that do implement this element will search the ticket extensions for -authorization data fields, calculate the specified checksum over each -authorization data field and look for one matching the checksum in this -in-ticket-extensions element. If not found, then the ticket must be -rejected. If found, the corresponding authorization data elements will be -interpreted in the same manner as if they were contained in the top level -authorization data field. - -Note that if multiple external authorization data fields are present in a -ticket, each will have a corresponding element of type in-ticket-extensions -in the top level authorization data field, and the external entries will be -linked to the corresponding element by their checksums. - - -Neuman, Ts'o, Kohl Expires: 25 December, -1999 - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, -1999 - -C. Definition of common ticket extensions - -This appendix contains the definitions of common ticket extensions. Support -for these extensions is optional. However, certain extensions have -associated authorization data elements that may require rejection of a -ticket containing an extension by application servers that do not implement -the particular extension. Other extensions have been defined beyond those -described in this specification. Such extensions are described elswhere and -for some of those extensions the reserved number may be found in the list of -constants. - -It is known that older versions of Kerberos did not support this field, and -that some clients will strip this field from a ticket when they parse and -then reassemble a ticket as it is passed to the application servers. The -presence of the extension will not break such clients, but any functionaly -dependent on the extensions will not work when such tickets are handled by -old clients. In such situations, some implementation may use alternate -methods to transmit the information in the extensions field. - -C.1. Null ticket extension - -TE-NullExtension OctetString -- The empty Octet String - -The te-data field in the null ticket extension is an octet string of lenght -zero. This extension may be included in a ticket granting ticket so that the -KDC can determine on presentation of the ticket granting ticket whether the -client software will strip the extensions field. - -C.2. External Authorization Data - -TE-ExternalAuthorizationData AuthorizationData - -The te-data field in the external authorization data ticket extension is -field of type AuthorizationData containing one or more authorization data -elements. If present, a corresponding authorization data element will be -present in the primary authorization data for the ticket and that element -will contain a checksum of the external authorization data ticket extension. - ------------------------------------------------------------------------ -[TM] Project Athena, Athena, and Kerberos are trademarks of the -Massachusetts Institute of Technology (MIT). No commercial use of these -trademarks may be made without prior written permission of MIT. - -[1] Note, however, that many applications use Kerberos' functions only upon -the initiation of a stream-based network connection. Unless an application -subsequently provides integrity protection for the data stream, the identity -verification applies only to the initiation of the connection, and does not -guarantee that subsequent messages on the connection originate from the same -principal. - -[2] Secret and private are often used interchangeably in the literature. In -our usage, it takes two (or more) to share a secret, thus a shared DES key -is a secret key. Something is only private when no one but its owner knows -it. Thus, in public key cryptosystems, one has a public and a private key. - -[3] Of course, with appropriate permission the client could arrange -registration of a separately-named prin- cipal in a remote realm, and engage -in normal exchanges with that realm's services. However, for even small -numbers of clients this becomes cumbersome, and more automatic methods as -described here are necessary. - - -Neuman, Ts'o, Kohl Expires: 25 December, -1999 - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, -1999 - -[4] Though it is permissible to request or issue tick- ets with no network -addresses specified. - -[5] The password-changing request must not be honored unless the requester -can provide the old password (the user's current secret key). Otherwise, it -would be possible for someone to walk up to an unattended ses- sion and -change another user's password. - -[6] To authenticate a user logging on to a local system, the credentials -obtained in the AS exchange may first be used in a TGS exchange to obtain -credentials for a local server. Those credentials must then be verified by a -local server through successful completion of the Client/Server exchange. - -[7] "Random" means that, among other things, it should be impossible to -guess the next session key based on knowledge of past session keys. This can -only be achieved in a pseudo-random number generator if it is based on -cryptographic principles. It is more desirable to use a truly random number -generator, such as one based on measurements of random physical phenomena. - -[8] Tickets contain both an encrypted and unencrypted portion, so cleartext -here refers to the entire unit, which can be copied from one message and -replayed in another without any cryptographic skill. - -[9] Note that this can make applications based on unreliable transports -difficult to code correctly. If the transport might deliver duplicated -messages, either a new authenticator must be generated for each retry, or -the application server must match requests and replies and replay the first -reply in response to a detected duplicate. - -[10] This is used for user-to-user authentication as described in [8]. - -[11] Note that the rejection here is restricted to authenticators from the -same principal to the same server. Other client principals communicating -with the same server principal should not be have their authenticators -rejected if the time and microsecond fields happen to match some other -client's authenticator. - -[12] In the Kerberos version 4 protocol, the timestamp in the reply was the -client's timestamp plus one. This is not necessary in version 5 because -version 5 messages are formatted in such a way that it is not possible to -create the reply by judicious message surgery (even in encrypted form) -without knowledge of the appropriate encryption keys. - -[13] Note that for encrypting the KRB_AP_REP message, the sub-session key is -not used, even if present in the Authenticator. - -[14] Implementations of the protocol may wish to provide routines to choose -subkeys based on session keys and random numbers and to generate a -negotiated key to be returned in the KRB_AP_REP message. - -[15]This can be accomplished in several ways. It might be known beforehand -(since the realm is part of the principal identifier), it might be stored in -a nameserver, or it might be obtained from a configura- tion file. If the -realm to be used is obtained from a nameserver, there is a danger of being -spoofed if the nameservice providing the realm name is not authenti- cated. -This might result in the use of a realm which has been compromised, and -would result in an attacker's ability to compromise the authentication of -the application server to the client. - - -Neuman, Ts'o, Kohl Expires: 25 December, -1999 - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, -1999 - -[16] If the client selects a sub-session key, care must be taken to ensure -the randomness of the selected sub- session key. One approach would be to -generate a random number and XOR it with the session key from the -ticket-granting ticket. - -[17] This allows easy implementation of user-to-user authentication [8], -which uses ticket-granting ticket session keys in lieu of secret server keys -in situa- tions where such secret keys could be easily comprom- ised. - -[18] For the purpose of appending, the realm preceding the first listed -realm is considered to be the null realm (""). - -[19] For the purpose of interpreting null subfields, the client's realm is -considered to precede those in the transited field, and the server's realm -is considered to follow them. - -[20] This means that a client and server running on the same host and -communicating with one another using the KRB_SAFE messages should not share -a common replay cache to detect KRB_SAFE replays. - -[21] The implementation of the Kerberos server need not combine the database -and the server on the same machine; it is feasible to store the principal -database in, say, a network name service, as long as the entries stored -therein are protected from disclosure to and modification by unauthorized -parties. However, we recommend against such strategies, as they can make -system management and threat analysis quite complex. - -[22] See the discussion of the padata field in section 5.4.2 for details on -why this can be useful. - -[23] Warning for implementations that unpack and repack data structures -during the generation and verification of embedded checksums: Because any -checksums applied to data structures must be checked against the original -data the length of bit strings must be preserved within a data structure -between the time that a checksum is generated through transmission to the -time that the checksum is verified. - -[24] It is NOT recommended that this time value be used to adjust the -workstation's clock since the workstation cannot reliably determine that -such a KRB_AS_REP actually came from the proper KDC in a timely manner. - -[25] Note, however, that if the time is used as the nonce, one must make -sure that the workstation time is monotonically increasing. If the time is -ever reset backwards, there is a small, but finite, probability that a nonce -will be reused. - -[27] An application code in the encrypted part of a message provides an -additional check that the message was decrypted properly. - -[29] An application code in the encrypted part of a message provides an -additional check that the message was decrypted properly. - -[31] An application code in the encrypted part of a message provides an -additional check that the message was decrypted properly. - - -Neuman, Ts'o, Kohl Expires: 25 December, -1999 - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-04 June 25, -1999 - -[32] If supported by the encryption method in use, an initialization vector -may be passed to the encryption procedure, in order to achieve proper cipher -chaining. The initialization vector might come from the last block of the -ciphertext from the previous KRB_PRIV message, but it is the application's -choice whether or not to use such an initialization vector. If left out, the -default initialization vector for the encryption algorithm will be used. - -[33] This prevents an attacker who generates an incorrect AS request from -obtaining verifiable plaintext for use in an off-line password guessing -attack. - -[35] In the above specification, UNTAGGED OCTET STRING(length) is the -notation for an octet string with its tag and length removed. It is not a -valid ASN.1 type. The tag bits and length must be removed from the -confounder since the purpose of the confounder is so that the message starts -with random data, but the tag and its length are fixed. For other fields, -the length and tag would be redundant if they were included because they are -specified by the encryption type. [36] The ordering of the fields in the -CipherText is important. Additionally, messages encoded in this format must -include a length as part of the msg-seq field. This allows the recipient to -verify that the message has not been truncated. Without a length, an -attacker could use a chosen plaintext attack to generate a message which -could be truncated, while leaving the checksum intact. Note that if the -msg-seq is an encoding of an ASN.1 SEQUENCE or OCTET STRING, then the length -is part of that encoding. - -[37] In some cases, it may be necessary to use a different "mix-in" string -for compatibility reasons; see the discussion of padata in section 5.4.2. - -[38] In some cases, it may be necessary to use a different "mix-in" string -for compatibility reasons; see the discussion of padata in section 5.4.2. - -[39] A variant of the key is used to limit the use of a key to a particular -function, separating the functions of generating a checksum from other -encryption performed using the session key. The constant F0F0F0F0F0F0F0F0 -was chosen because it maintains key parity. The properties of DES precluded -the use of the complement. The same constant is used for similar purpose in -the Message Integrity Check in the Privacy Enhanced Mail standard. - -[40] This error carries additional information in the e- data field. The -contents of the e-data field for this message is described in section 5.9.1. diff --git a/doc/draft-ietf-cat-krb-dns-locate-00.txt b/doc/draft-ietf-cat-krb-dns-locate-00.txt deleted file mode 100644 index e76a0e402..000000000 --- a/doc/draft-ietf-cat-krb-dns-locate-00.txt +++ /dev/null @@ -1,250 +0,0 @@ -INTERNET-DRAFT Ken Hornstein - NRL -June 21, 1999 Jeffrey Altman -Expires: December 21, 1999 Columbia University - - Distributing Kerberos KDC and Realm Information with DNS - -Status of this Memo - - This document is an Internet-Draft and is in full conformance with - all provisions of Section 10 of RFC2026. - - Internet-Drafts are working documents of the Internet Engineering - Task Force (IETF), its areas, and its working groups. Note that - other groups may also distribute working documents as Internet- - Drafts. - - Internet-Drafts are draft documents valid for a maximum of six months - and may be updated, replaced, or obsoleted by other documents at any - time. It is inappropriate to use Internet- Drafts as reference - material or to cite them other than as "work in progress." - - The list of current Internet-Drafts can be accessed at - http://www.ietf.org/ietf/1id-abstracts.txt - - The list of Internet-Draft Shadow Directories can be accessed at - http://www.ietf.org/shadow.html. - - Distribution of this memo is unlimited. It is filed as , and expires on December 21, 1999. Please - send comments to the authors. - -Abstract - - Neither the Kerberos V5 protocol [RFC1510] nor the Kerberos V4 proto- - col [RFC????] describe any mechanism for clients to learn critical - configuration information necessary for proper operation of the pro- - tocol. Such information includes the location of Kerberos key dis- - tribution centers or a mapping between DNS domains and Kerberos - realms. - - Current Kerberos implementations generally store such configuration - information in a file on each client machine. Experience has shown - this method of storing configuration information presents problems - with out-of-date information and scaling problems, especially when - -Hornstein, Altman [Page 1] - -RFC DRAFT June 21, 1999 - - using cross-realm authentication. - - This memo describes a method for using the Domain Name System - [RFC1035] for storing such configuration information. Specifically, - methods for storing KDC location and hostname/domain name to realm - mapping information are discussed. - -Overview - KDC location information - - KDC location information is to be stored using the DNS SRV RR [RFC - 2052]. The format of this RR is as follows: - - Service.Proto.Realm TTL Class SRV Priority Weight Port Target - - The Service name for Kerberos is always "_kerberos". - - The Proto can be either "_udp" or "_tcp". If these records are to be - used, a "_udp" record MUST be included. If the Kerberos implementa- - tion supports TCP transport, a "_tcp" record SHOULD be included. - - The Realm is the Kerberos realm that this record corresponds to. - - TTL, Class, SRV, Priority, Weight, Port, and Target have the standard - meaning as defined in RFC 2052. - -Example - KDC location information - - These are DNS records for a Kerberos realm ASDF.COM. It has two Ker- - beros servers, kdc1.asdf.com and kdc2.asdf.com. Queries should be - directed to kdc1.asdf.com first as per the specified priority. - Weights are not used in these records. - - _kerberos._udp.ASDF.COM. IN SRV 0 0 88 kdc1.asdf.com. - _kerberos._udp.ASDF.COM. IN SRV 1 0 88 kdc2.asdf.com. - -Overview - KAdmin location information - - Kadmin location information is to be stored using the DNS SRV RR [RFC - 2052]. The format of this RR is as follows: - - Service.Proto.Realm TTL Class SRV Priority Weight Port Target - - The Service name for Kadmin is always "_kadmin". - - The Proto can be either "_udp" or "_tcp". If these records are to be - used, a "_tcp" record MUST be included. If the Kadmin implementation - supports UDP transport, a "_udp" record SHOULD be included. - -Hornstein, Altman [Page 2] - -RFC DRAFT June 21, 1999 - - The Realm is the Kerberos realm that this record corresponds to. - - TTL, Class, SRV, Priority, Weight, Port, and Target have the standard - meaning as defined in RFC 2052. - -Example - Kadmin location information - - These are DNS records for a Kerberos realm ASDF.COM. It has one Kad- - min server, kdc1.asdf.com. - - _kadmin._tcp.ASDF.COM. IN SRV 0 0 88 kdc1.asdf.com. - -Overview - Hostname/domain name to Kerberos realm mapping - - Information on the mapping of DNS hostnames and domain names to Ker- - beros realms is stored using DNS TXT records [RFC 1035]. These - records have the following format. - - Service.Name TTL Class TXT Realm - - The Service field is always "_kerberos", and prefixes all entries of - this type. - - The Name is a DNS hostname or domain name. This is explained in - greater detail below. - - TTL, Class, and TXT have the standard DNS meaning as defined in RFC - 1035. - - The Realm is the data for the TXT RR, and consists simply of the Ker- - beros realm that corresponds to the Name specified. - - When a Kerberos client wishes to utilize a host-specific service, it - will perform a DNS TXT query, using the hostname in the Name field of - the DNS query. If the record is not found, the first label of the - name is stripped and the query is retried. - - Compliant implementations MUST query the full hostname and the most - specific domain name (the hostname with the first label removed). - Compliant implementations SHOULD try stripping all subsequent labels - until a match is found or the Name field is empty. - -Example - Hostname/domain name to Kerberos realm mapping - - For the previously mentioned ASDF.COM realm and domain, some sample - records might be as follows: - - _kerberos.asdf.com. IN TXT "ASDF.COM" - -Hornstein, Altman [Page 3] - -RFC DRAFT June 21, 1999 - - _kerberos.mrkserver.asdf.com. IN TXT "MARKETING.ASDF.COM" - _kerberos.salesserver.asdf.com. IN TXT "SALES.ASDF.COM" - - Let us suppose that in this case, a Kerberos client wishes to use a - Kerberized service on the host foo.asdf.com. It would first query: - - _kerberos.foo.asdf.com. IN TXT - - Finding no match, it would then query: - - _kerberos.asdf.com. IN TXT - - And find an answer of ASDF.COM. This would be the realm that - foo.asdf.com resides in. - - If another Kerberos client wishes to use a Kerberized service on the - host salesserver.asdf.com, it would query: - - _kerberos.salesserver.asdf.com IN TXT - - And find an answer of SALES.ASDF.COM. - -Security considerations - - As DNS is deployed today, it is an unsecure service. Thus the infor- - mation returned by it cannot be trusted. However, the use of DNS to - store this configuration information does not introduce any new secu- - rity risks to the Kerberos protocol. - - Current practice is to use hostnames to indicate KDC hosts (stored in - some implementation-dependent location, but generally a local config - file). These hostnames are vulnerable to the standard set of DNS - attacks (denial of service, spoofed entries, etc). The design of the - Kerberos protocol limits attacks of this sort to denial of service. - However, the use of SRV records does not change this attack in any - way. They have the same vulnerabilities that already exist in the - common practice of using hostnames for KDC locations. - - The same holds true for the TXT records used to indicate the domain - name to realm mapping. Current practice is to configure these map- - pings locally. But this again is vulnerable to spoofing via CNAME - records that point to hosts in other domains. This has the same - effect as a spoofed TXT record. - - While the described protocol does not introduce any new security - risks to the best of our knowledge, implementations SHOULD provide a - way of specifying this information locally without the use of DNS. - However, to make this feature worthwhile a lack of any configuration - -Hornstein, Altman [Page 4] - -RFC DRAFT June 21, 1999 - - information on a client should be interpretted as permission to use - DNS. - -Expiration - - This Internet-Draft expires on December 21, 1999. - -References - - [RFC1510] - The Kerberos Network Authentication System; Kohl, Newman; Sep- - tember 1993. - - [RFC1035] - Domain Names - Implementation and Specification; Mockapetris; - November 1987 - - [RFC2052] - A DNS RR for specifying the location of services (DNS SRV); Gul- - brandsen, Vixie; October 1996 - -Authors' Addresses - - Ken Hornstein - US Naval Research Laboratory - Bldg A-49, Room 2 - 4555 Overlook Avenue - Washington DC 20375 USA - - Phone: +1 (202) 404-4765 - EMail: kenh@cmf.nrl.navy.mil - - Jeffrey Altman - The Kermit Project - Columbia University - 612 West 115th Street #716 - New York NY 10025-7799 USA - - Phone: +1 (212) 854-1344 - EMail: jaltman@columbia.edu - -Hornstein, Altman [Page 5] diff --git a/doc/draft-ietf-ftpext-mlst-08.txt b/doc/draft-ietf-ftpext-mlst-08.txt deleted file mode 100644 index 885cf4967..000000000 --- a/doc/draft-ietf-ftpext-mlst-08.txt +++ /dev/null @@ -1,3415 +0,0 @@ -FTPEXT Working Group R. Elz -Internet Draft University of Melbourne -Expiration Date: April 2000 - P. Hethmon - Hethmon Brothers - - October 1999 - - - Extensions to FTP - - - draft-ietf-ftpext-mlst-08.txt - -Status of this Memo - - This document is an Internet-Draft and is NOT offered in accordance - with Section 10 of RFC2026, and the author does not provide the IETF - with any rights other than to publish as an Internet-Draft. - - Internet-Drafts are working documents of the Internet Engineering - Task Force (IETF), its areas, and its working groups. Note that - other groups may also distribute working documents as Internet- - Drafts. - - Internet-Drafts are draft documents valid for a maximum of six months - and may be updated, replaced, or obsoleted by other documents at any - time. It is inappropriate to use Internet-Drafts as reference - material or to cite them other than as "work in progress." - - The list of current Internet-Drafts can be accessed at - http://www.ietf.org/ietf/1id-abstracts.txt. - - To view the list Internet-Draft Shadow Directories, see - http://www.ietf.org/shadow.html. - - This entire section has been prepended to this document automatically - during formatting without any direct involvement by the author(s) of - this draft. - - - - - - - - - - - - -Elz & Hethmon [Expires April 2000] [Page 1] - - -Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 - - -Abstract - - In order to overcome the problems caused by the undefined format of - the current FTP LIST command output, a new command is needed to - transfer standardized listing information from Server-FTP to User- - FTP. Commands to enable this are defined in this document. - - In order to allow consenting clients and servers to interact more - freely, a quite basic, and optional, virtual file store structure is - defined. - - This proposal also extends the FTP protocol to allow character sets - other than US-ASCII[1] by allowing the transmission of 8-bit - characters and the recommended use of UTF-8[2] encoding. - - Much implemented, but long undocumented, mechanisms to permit - restarts of interrupted data transfers in STREAM mode, are also - included here. - - Lastly, the HOST command has been added to allow a style of "virtual - site" to be constructed. - - Changed in this version of this document: Minor corrections as - discussed on the mailing list, including fixing many typographical - errors; Additional examples. This paragraph will be deleted from the - final version of this document. - - - - - - - - - - - - - - - - - - - - - - - - - -Elz & Hethmon [Expires April 2000] [Page 2] - - -Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 - - - - -Table of Contents - - Abstract ................................................ 2 - 1 Introduction ............................................ 4 - 2 Document Conventions .................................... 4 - 2.1 Basic Tokens ............................................ 5 - 2.2 Pathnames ............................................... 5 - 2.3 Times ................................................... 7 - 2.4 Server Replies .......................................... 8 - 3 File Modification Time (MDTM) ........................... 8 - 3.1 Syntax .................................................. 9 - 3.2 Error responses ......................................... 9 - 3.3 FEAT response for MDTM .................................. 9 - 3.4 MDTM Examples ........................................... 10 - 4 File SIZE ............................................... 11 - 4.1 Syntax .................................................. 11 - 4.2 Error responses ......................................... 11 - 4.3 FEAT response for SIZE .................................. 12 - 4.4 Size Examples ........................................... 12 - 5 Restart of Interrupted Transfer (REST) .................. 13 - 5.1 Restarting in STREAM Mode ............................... 13 - 5.2 Error Recovery and Restart .............................. 14 - 5.3 Syntax .................................................. 14 - 5.4 FEAT response for REST .................................. 16 - 5.5 REST Example ............................................ 16 - 6 Virtual FTP servers ..................................... 16 - 6.1 The HOST command ........................................ 18 - 6.2 Syntax of the HOST command .............................. 18 - 6.3 HOST command semantics .................................. 19 - 6.4 HOST command errors ..................................... 21 - 6.5 FEAT response for HOST command .......................... 22 - 7 A Trivial Virtual File Store (TVFS) ..................... 23 - 7.1 TVFS File Names ......................................... 23 - 7.2 TVFS Path Names ......................................... 24 - 7.3 FEAT Response for TVFS .................................. 25 - 7.4 OPTS for TVFS ........................................... 26 - 7.5 TVFS Examples ........................................... 26 - 8 Listings for Machine Processing (MLST and MLSD) ......... 28 - 8.1 Format of MLSx Requests ................................. 29 - 8.2 Format of MLSx Response ................................. 29 - 8.3 Filename encoding ....................................... 32 - 8.4 Format of Facts ......................................... 33 - 8.5 Standard Facts .......................................... 33 - 8.6 System Dependent and Local Facts ........................ 41 - 8.7 MLSx Examples ........................................... 42 - 8.8 FEAT response for MLSx .................................. 50 - - - -Elz & Hethmon [Expires April 2000] [Page 3] - - -Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 - - - 8.9 OPTS parameters for MLST ................................ 51 - 9 Impact On Other FTP Commands ............................ 55 - 10 Character sets and Internationalization ................. 56 - 11 IANA Considerations ..................................... 56 - 11.1 The OS specific fact registry ........................... 56 - 11.2 The OS specific filetype registry ....................... 57 - 12 Security Considerations ................................. 57 - 13 References .............................................. 58 - Acknowledgments ......................................... 59 - Copyright ............................................... 60 - Editors' Addresses ...................................... 60 - - - - -1. Introduction - - This document amends the File Transfer Protocol (FTP) [3]. Five new - commands are added: "SIZE", "HOST", "MDTM", "MLST", and "MLSD". The - existing command "REST" is modified. Of those, the "SIZE" and "MDTM" - commands, and the modifications to "REST" have been in wide use for - many years. The others are new. - - These commands allow a client to restart an interrupted transfer in - transfer modes not previously supported in any documented way, to - support the notion of virtual hosts, and to obtain a directory - listing in a machine friendly, predictable, format. - - An optional structure for the server's file store (NVFS) is also - defined, allowing servers that support such a structure to convey - that information to clients in a standard way, thus allowing clients - more certainty in constructing and interpreting path names. - -2. Document Conventions - - This document makes use of the document conventions defined in BCP14 - [4]. That provides the interpretation of capitalized imperative - words like MUST, SHOULD, etc. - - This document also uses notation defined in STD 9 [3]. In - particular, the terms "reply", "user", "NVFS", "file", "pathname", - "FTP commands", "DTP", "user-FTP process", "user-PI", "user-DTP", - "server-FTP process", "server-PI", "server-DTP", "mode", "type", - "NVT", "control connection", "data connection", and "ASCII", are all - used here as defined there. - - Syntax required is defined using the Augmented BNF defined in [5]. - Some general ABNF definitions are required throughout the document, - - - -Elz & Hethmon [Expires April 2000] [Page 4] - - -Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 - - - those will be defined later in this section. At first reading, it - may be wise to simply recall that these definitions exist here, and - skip to the next section. - -2.1. Basic Tokens - - This document imports the core definitions given in Appendix A of - [5]. There definitions will be found for basic ABNF elements like - ALPHA, DIGIT, SP, etc. To that, the following terms are added for - use in this document. - - TCHAR = VCHAR / SP / HTAB ; visible plus white space - RCHAR = ALPHA / DIGIT / "," / "." / ":" / "!" / - "@" / "#" / "$" / "%" / "^" / - "&" / "(" / ")" / "-" / "_" / - "+" / "?" / "/" / "\" / "'" / - DQUOTE ; <"> -- double quote character (%x22) - - The VCHAR (from [5]), TCHAR, and RCHAR types give basic character - types from varying sub-sets of the ASCII character set for use in - various commands and responses. - - token = 1*RCHAR - - A "token" is a string whose precise meaning depends upon the context - in which it is used. In some cases it will be a value from a set of - possible values maintained elsewhere. In others it might be a string - invented by one party to an FTP conversation from whatever sources it - finds relevant. - - Note that in ABNF, string literals are case insensitive. That - convention is preserved in this document, and implies that FTP - commands added by this specification have names that can be - represented in any case. That is, "MDTM" is the same as "mdtm", - "Mdtm" and "MdTm" etc. However note that ALPHA, in particular, is - case sensitive. That implies that a "token" is a case sensitive - value. That implication is correct. - -2.2. Pathnames - - Various FTP commands take pathnames as arguments, or return pathnames - in responses. When the MLST command is supported, as indicated in - the response to the FEAT command [6], pathnames are to be transferred - in one of the following two formats. - - - - - - - -Elz & Hethmon [Expires April 2000] [Page 5] - - -Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 - - - pathname = utf-8-name / raw - utf-8-name = - raw = - - Which format is used is at the option of the user-PI or server-PI - sending the pathname. UTF-8 encodings [2] contain enough internal - structure that it is always, in practice, possible to determine - whether a UTF-8 or raw encoding has been used, in those cases where - it matters. While it is useful for the user-PI to be able to - correctly display a pathname received from the server-PI to the user, - it is far more important for the user-PI to be able to retain and - retransmit the identical pathname when required. Implementations are - advised against converting a UTF-8 pathname to a local encoding, and - then attempting to invert the encoding later. Note that ASCII is a - subset of UTF-8. - - Unless otherwise specified, the pathname is terminated by the CRLF - that terminates the FTP command, or by the CRLF that ends a reply. - Any trailing spaces preceding that CRLF form part of the name. - Exactly one space will precede the pathname and serve as a separator - from the preceding syntax element. Any additional spaces form part - of the pathname. See [7] for a fuller explanation of the character - encoding issues. All implementations supporting MLST MUST support - [7]. - - Implementations should also beware that the control connection uses - Telnet NVT conventions [8], and that the Telnet IAC character, if - part of a pathname sent over the control connection, MUST be - correctly escaped as defined by the Telnet protocol. - - Implementors should also be aware that although Telnet NVT - conventions are used over the control connections, Telnet option - negotiation MUST NOT be attempted. See section 4.1.2.12 of [9]. - -2.2.1. Pathname Syntax - - Except where TVFS is supported (see section 7) this specification - imposes no syntax upon pathnames. Nor does it restrict the character - set from which pathnames are created. This does not imply that the - NVFS is required to make sense of all possible pathnames. Server-PIs - may restrict the syntax of valid pathnames in their NVFS in any - manner appropriate to their implementation or underlying file system. - Similarly, a server-PI may parse the pathname, and assign meaning to - the components detected. - - - - - - - -Elz & Hethmon [Expires April 2000] [Page 6] - - -Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 - - -2.2.2. Wildcarding - - For the commands defined in this specification, all pathnames are to - be treated literally. That is, for a pathname given as a parameter - to a command, the file whose name is identical to the pathname given - is implied. No characters from the pathname may be treated as - special or "magic", thus no pattern matching (other than for exact - equality) between the pathname given and the files present in the - NVFS of the Server-FTP is permitted. - - Clients that desire some form of pattern matching functionality must - obtain a listing of the relevant directory, or directories, and - implement their own filename selection procedures. - -2.3. Times - - The syntax of a time value is: - - time-val = 14DIGIT [ "." 1*DIGIT ] - - The leading, mandatory, fourteen digits are to be interpreted as, in - order from the leftmost, four digits giving the year, with a range of - 1000-9999, two digits giving the month of the year, with a range of - 01-12, two digits giving the day of the month, with a range of 01-31, - two digits giving the hour of the day, with a range of 00-23, two - digits giving minutes past the hour, with a range of 00-59, and - finally, two digits giving seconds past the minute, with a range of - 00-60 (with 60 being used only at a leap second). Years in the tenth - century, and earlier, cannot be expressed. This is not considered a - serious defect of the protocol. - - The optional digits, which are preceded by a period, give decimal - fractions of a second. These may be given to whatever precision is - appropriate to the circumstance, however implementations MUST NOT add - precision to time-vals where that precision does not exist in the - underlying value being transmitted. - - Symbolically, a time-val may be viewed as - - YYYYMMDDHHMMSS.sss - - The "." and subsequent digits ("sss") are optional. However the "." - MUST NOT appear unless at least one following digit also appears. - - Time values are always represented in UTC (GMT), and in the Gregorian - calendar regardless of what calendar may have been in use at the date - and time indicated at the location of the server-PI. - - - - -Elz & Hethmon [Expires April 2000] [Page 7] - - -Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 - - - The technical differences between GMT, TAI, UTC, UT1, UT2, etc, are - not considered here. A server-FTP process should always use the same - time reference, so the times it returns will be consistent. Clients - are not expected to be time synchronized with the server, so the - possible difference in times that might be reported by the different - time standards is not considered important. - -2.4. Server Replies - - Section 4.2 of [3] defines the format and meaning of replies by the - server-PI to FTP commands from the user-PI. Those reply conventions - are used here without change. - - error-response = error-code SP *TCHAR CRLF - error-code = ("4" / "5") 2DIGIT - - Implementors should note that the ABNF syntax (which was not used in - [3]) used in this document, and other FTP related documents, - sometimes shows replies using the one line format. Unless otherwise - explicitly stated, that is not intended to imply that multi-line - responses are not permitted. Implementors should assume that, unless - stated to the contrary, any reply to any FTP command (including QUIT) - may be of the multi-line format described in [3]. - - Throughout this document, replies will be identified by the three - digit code that is their first element. Thus the term "500 reply" - means a reply from the server-PI using the three digit code "500". - -3. File Modification Time (MDTM) - - The FTP command, MODIFICATION TIME (MDTM), can be used to determine - when a file in the server NVFS was last modified. This command has - existed in many FTP servers for many years, as an adjunct to the REST - command for STREAM mode, thus is widely available. However, where - supported, the "modify" fact which can be provided in the result from - the new MLST command is recommended as a superior alternative. - - When attempting to restart a RETRieve, if the User-FTP makes use of - the MDTM command, or "modify" fact, it can check and see if the - modification time of the source file is more recent than the - modification time of the partially transferred file. If it is, then - most likely the source file has changed and it would be unsafe to - restart the previously incomplete file transfer. - - When attempting to restart a STORe, the User FTP can use the MDTM - command to discover the modification time of the partially - transferred file. If it is older than the modification time of the - file that is about to be STORed, then most likely the source file has - - - -Elz & Hethmon [Expires April 2000] [Page 8] - - -Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 - - - changed and it would be unsafe to restart the file transfer. - - Note that using MLST (described below) where available, can provide - this information, and much more, thus giving an even better - indication that a file has changed, and that restarting a transfer - would not give valid results. - - Note that this is applicable to any RESTart attempt, regardless of - the mode of the file transfer. - -3.1. Syntax - - The syntax for the MDTM command is: - - mdtm = "MdTm" SP pathname CRLF - - As with all FTP commands, the "MDTM" command label is interpreted in - a case insensitive manner. - - The "pathname" specifies an object in the NVFS which may be the - object of a RETR command. Attempts to query the modification time of - files that are unable to be retrieved generate undefined responses. - - The server-PI will respond to the MDTM command with a 213 reply - giving the last modification time of the file whose pathname was - supplied, or a 550 reply if the file does not exist, the modification - time is unavailable, or some other error has occurred. - - mdtm-response = "213" SP time-val CRLF / - error-response - -3.2. Error responses - - Where the command is correctly parsed, but the modification time is - not available, either because the pathname identifies no existing - entity, or because the information is not available for the entity - named, then a 550 reply should be sent. Where the command cannot be - correctly parsed, a 500 or 501 reply should be sent, as specified in - [3]. - -3.3. FEAT response for MDTM - - When replying to the FEAT command [6], an FTP server process that - supports the MDTM command MUST include a line containing the single - word "MDTM". This MAY be sent in upper or lower case, or a mixture - of both (it is case insensitive) but SHOULD be transmitted in upper - case only. That is, the response SHOULD be - - - - -Elz & Hethmon [Expires April 2000] [Page 9] - - -Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 - - - C> Feat - S> 211- - S> ... - S> MDTM - S> ... - S> 211 End - - The ellipses indicate place holders where other features may be - included, and are not required. The one space indentation of the - feature lines is mandatory [6]. - -3.4. MDTM Examples - - If we assume the existence of three files, A B and C, and a directory - D, and no other files at all, then the MTDM command may behave as - indicated. The "C>" lines are commands from user-PI to server-PI, - the "S>" lines are server-PI replies. - - C> MDTM A - S> 213 19980615100045.014 - C> MDTM B - S> 213 19980615100045.014 - C> MDTM C - S> 213 19980705132316 - C> MDTM D - S> 550 D is not retrievable - C> MDTM E - S> 550 No file named "E" - C> mdtm file6 - S> 213 19990929003355 - C> MdTm 19990929043300 File6 - S> 213 19991005213102 - C> MdTm 19990929043300 file6 - S> 550 19990929043300 file6: No such file or directory. - - From that we can conclude that both A and B were last modified at the - same time (to the nearest millisecond), and that C was modified 21 - days and several hours later. - - The times are in GMT, so file A was modified on the 15th of June, - 1998, at approximately 11am in London (summer time was then in - effect), or perhaps at 8pm in Melbourne, Australia, or at 6am in New - York. All of those represent the same absolute time of course. The - location where the file was modified, and consequently the local wall - clock time at that location, is not available. - - There is no file named "E" in the current directory, but there are - files named both "file6" and "19990929043300 File6". The - - - -Elz & Hethmon [Expires April 2000] [Page 10] - - -Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 - - - modification times of those files were obtained. There is no file - named "19990929043300 file6". - -4. File SIZE - - The FTP command, SIZE OF FILE (SIZE), is used to obtain the transfer - size of a file from the server-FTP process. That is, the exact - number of octets (8 bit bytes) which would be transmitted over the - data connection should that file be transmitted. This value will - change depending on the current STRUcture, MODE and TYPE of the data - connection, or a data connection which would be created were one - created now. Thus, the result of the SIZE command is dependent on - the currently established STRU, MODE and TYPE parameters. - - The SIZE command returns how many octets would be transferred if the - file were to be transferred using the current transfer structure, - mode and type. This command is normally used in conjunction with the - RESTART (REST) command. The server-PI might need to read the - partially transferred file, do any appropriate conversion, and count - the number of octets that would be generated when sending the file in - order to correctly respond to this command. Estimates of the file - transfer size MUST NOT be returned, only precise information is - acceptable. - -4.1. Syntax - - The syntax of the SIZE command is: - - size = "Size" SP pathname CRLF - - The server-PI will respond to the SIZE command with a 213 reply - giving the transfer size of the file whose pathname was supplied, or - an error response if the file does not exist, the size is - unavailable, or some other error has occurred. The value returned is - in a format suitable for use with the RESTART (REST) command for mode - STREAM, provided the transfer mode and type are not altered. - - size-response = "213" SP 1*DIGIT CRLF / - error-response - -4.2. Error responses - - Where the command is correctly parsed, but the size is not available, - either because the pathname identifies no existing entity, or because - the entity named cannot be transferred in the current MODE and TYPE - (or at all), then a 550 reply should be sent. Where the command - cannot be correctly parsed, a 500 or 501 reply should be sent, as - specified in [3]. - - - -Elz & Hethmon [Expires April 2000] [Page 11] - - -Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 - - -4.3. FEAT response for SIZE - - When replying to the FEAT command [6], an FTP server process that - supports the SIZE command MUST include a line containing the single - word "SIZE". This word is case insensitive, and MAY be sent in any - mixture of upper or lower case, however it SHOULD be sent in upper - case. That is, the response SHOULD be - - C> FEAT - S> 211- - S> ... - S> SIZE - S> ... - S> 211 END - - The ellipses indicate place holders where other features may be - included, and are not required. The one space indentation of the - feature lines is mandatory [6]. - -4.4. Size Examples - - Consider a text file "Example" stored on a Unix(TM) server where each - end of line is represented by a single octet. Assume the file - contains 112 lines, and 1830 octets total. Then the SIZE command - would produce: - - C> TYPE I - S> 200 Type set to I. - C> size Example - S> 213 1830 - C> TYPE A - S> 200 Type set to A. - C> Size Example - S> 213 1942 - - Notice that with TYPE=A the SIZE command reports an extra 112 octets. - Those are the extra octets that need to be inserted, one at the end - of each line, to provide correct end of line semantics for a transfer - using TYPE=A. Other systems might need to make other changes to the - transfer format of files when converting between TYPEs and MODEs. - The SIZE command takes all of that into account. - - Since calculating the size of a file with this degree of precision - may take considerable effort on the part of the server-PI, user-PIs - should not used this command unless this precision is essential (such - as when about to restart an interrupted transfer). For other uses, - the "Size" fact of the MLST command (see section 8.5.7) ought be - requested. - - - -Elz & Hethmon [Expires April 2000] [Page 12] - - -Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 - - -5. Restart of Interrupted Transfer (REST) - - To avoid having to resend the entire file if the file is only - partially transferred, both sides need some way to be able to agree - on where in the data stream to restart the data transfer. - - The FTP specification [3] includes three modes of data transfer, - Stream, Block and Compressed. In Block and Compressed modes, the - data stream that is transferred over the data connection is - formatted, allowing the embedding of restart markers into the stream. - The sending DTP can include a restart marker with whatever - information it needs to be able to restart a file transfer at that - point. The receiving DTP can keep a list of these restart markers, - and correlate them with how the file is being saved. To restart the - file transfer, the receiver just sends back that last restart marker, - and both sides know how to resume the data transfer. Note that there - are some flaws in the description of the restart mechanism in RFC 959 - [3]. See section 4.1.3.4 of RFC 1123 [9] for the corrections. - -5.1. Restarting in STREAM Mode - - In Stream mode, the data connection contains just a stream of - unformatted octets of data. Explicit restart markers thus cannot be - inserted into the data stream, they would be indistinguishable from - data. For this reason, the FTP specification [3] did not provide the - ability to do restarts in stream mode. However, there is not really - a need to have explicit restart markers in this case, as restart - markers can be implied by the octet offset into the data stream. - - Because the data stream defines the file in STREAM mode, a different - data stream would represent a different file. Thus, an offset will - always represent the same position within a file. On the other hand, - in other modes than STREAM, the same file can be transferred using - quite different octet sequences, and yet be reconstructed into the - one identical file. Thus an offset into the data stream in transfer - modes other than STREAM would not give an unambiguous restart point. - - If the data representation TYPE is IMAGE, and the STRUcture is File, - for many systems the file will be stored exactly in the same format - as it is sent across the data connection. It is then usually very - easy for the receiver to determine how much data was previously - received, and notify the sender of the offset where the transfer - should be restarted. In other representation types and structures - more effort will be required, but it remains always possible to - determine the offset with finite, but perhaps non-negligible, effort. - In the worst case an FTP process may need to open a data connection - to itself, set the appropriate transfer type and structure, and - actually transmit the file, counting the transmitted octets. - - - -Elz & Hethmon [Expires April 2000] [Page 13] - - -Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 - - - If the user-FTP process is intending to restart a retrieve, it will - directly calculate the restart marker, and send that information in - the RESTart command. However, if the user-FTP process is intending - to restart sending the file, it needs to be able to determine how - much data was previously sent, and correctly received and saved. A - new FTP command is needed to get this information. This is the - purpose of the SIZE command, as documented in section 4. - -5.2. Error Recovery and Restart - - STREAM MODE transfers with FILE STRUcture may be restarted even - though no restart marker has been transferred in addition to the data - itself. This is done by using the SIZE command, if needed, in - combination with the RESTART (REST) command, and one of the standard - file transfer commands. - - When using TYPE ASCII or IMAGE, the SIZE command will return the - number of octets that would actually be transferred if the file were - to be sent between the two systems. I.e. with type IMAGE, the SIZE - normally would be the number of octets in the file. With type ASCII, - the SIZE would be the number of octets in the file including any - modifications required to satisfy the TYPE ASCII CR-LF end of line - convention. - -5.3. Syntax - - The syntax for the REST command when the current transfer mode is - STREAM is: - - rest = "Rest" SP 1*DIGIT CRLF - - The numeric value gives the number of octets of the immediately - following transfer to not actually send, effectively causing the - transmission to be restarted at a later point. A value of zero - effectively disables restart, causing the entire file to be - transmitted. The server-PI will respond to the REST command with a - 350 reply, indicating that the REST parameter has been saved, and - that another command, which should be either RETR or STOR, should - then follow to complete the restart. - - rest-response = "350" SP *TCHAR CRLF / - error-response - - Server-FTP processes may permit transfer commands other than RETR and - STOR, such as APPE and STOU, to complete a restart, however, this is - not recommended. STOU (store unique) is undefined in this usage, as - storing the remainder of a file into a unique filename is rarely - going to be useful. If APPE (append) is permitted, it MUST act - - - -Elz & Hethmon [Expires April 2000] [Page 14] - - -Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 - - - identically to STOR when a restart marker has been set. That is, in - both cases, octets from the data connection are placed into the file - at the location indicated by the restart marker value. - - The REST command is intended to complete a failed transfer. Use with - RETR is comparatively well defined in all cases, as the client bears - the responsibility of merging the retrieved data with the partially - retrieved file. If it chooses to use the data obtained other than to - complete an earlier transfer, or if it chooses to re-retrieve data - that had been retrieved before, that is its choice. With STOR, - however, the server must insert the data into the file named. The - results are undefined if a client uses REST to do other than restart - to complete a transfer of a file which had previously failed to - completely transfer. In particular, if the restart marker set with a - REST command is not at the end of the data currently stored at the - server, as reported by the server, or if insufficient data are - provided in a STOR that follows a REST to extend the destination file - to at least its previous size, then the effects are undefined. - - The REST command must be the last command issued before the data - transfer command which is to cause a restarted rather than complete - file transfer. The effect of issuing a REST command at any other - time is undefined. The server-PI may react to a badly positioned - REST command by issuing an error response to the following command, - not being a restartable data transfer command, or it may save the - restart value and apply it to the next data transfer command, or it - may silently ignore the inappropriate restart attempt. Because of - this, a user-PI that has issued a REST command, but which has not - successfully transmitted the following data transfer command for any - reason, should send another REST command before the next data - transfer command. If that transfer is not to be restarted, then - "REST 0" should be issued. - - An error-response will follow a REST command only when the server - does not implement the command, or the restart marker value is - syntactically invalid for the current transfer mode. That is, in - STREAM mode, if something other than one or more digits appears in - the parameter to the REST command. Any other errors, including such - problems as restart marker out of range, should be reported when the - following transfer command is issued. Such errors will cause that - transfer request to be rejected with an error indicating the invalid - restart attempt. - - - - - - - - - -Elz & Hethmon [Expires April 2000] [Page 15] - - -Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 - - -5.4. FEAT response for REST - - Where a server-FTP process supports RESTart in STREAM mode, as - specified here, it MUST include in the response to the FEAT command - [6], a line containing exactly the string "REST STREAM". This string - is not case sensitive, but SHOULD be transmitted in upper case. - Where REST is not supported at all, or supported only in block or - compressed modes, the REST line MUST NOT be included in the FEAT - response. Where required, the response SHOULD be - - C> feat - S> 211- - S> ... - S> REST STREAM - S> ... - S> 211 end - - The ellipses indicate place holders where other features may be - included, and are not required. The one space indentation of the - feature lines is mandatory [6]. - -5.5. REST Example - - Assume that the transfer of a largish file has previously been - interrupted after 802816 octets had been received, that the previous - transfer was with TYPE=I, and that it has been verified that the file - on the server has not since changed. - - C> TYPE I - S> 200 Type set to I. - C> PORT 127,0,0,1,15,107 - S> 200 PORT command successful. - C> REST 802816 - S> 350 Restarting at 802816. Send STORE or RETRIEVE - C> RETR cap60.pl198.tar - S> 150 Opening BINARY mode data connection - [...] - S> 226 Transfer complete. - -6. Virtual FTP servers - - It has become common in the Internet for many domain names to be - allocated to a single IP address. This has introduced the concept of - a "virtual host", where a host appears to exist as an independent - entity, but in reality shares all of its resources with one, or more, - other such hosts. - - - - - -Elz & Hethmon [Expires April 2000] [Page 16] - - -Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 - - - Such an arrangement presents some problems for FTP Servers, as all - the FTP Server can detect is an incoming FTP connection to a - particular IP address. That is, all domain names which share the IP - address also share the FTP server, and more importantly, its NVFS. - This means that the various virtual hosts cannot offer different - virtual file systems to clients, nor can they offer different - authentication systems. - - No scheme can overcome this without modifications of some kind to the - user-PI and the user-FTP process. That process is the only entity - that knows which virtual host is required. It has performed the - domain name to IP address translation, and thus has the original - domain name available. - - One method which could be used to allow a style of virtual host would - be for the client to simply send a "CWD" command after connecting, - using the virtual host name as the argument to the CWD command. This - would allow the server-FTP process to implement the file stores of - the virtual hosts as sub-directories in its NVFS. This is simple, - and supported by essentially all server-FTP implementations without - requiring any code changes. - - While that method is simple to describe, and to implement, it suffers - from several drawbacks. First, the "CWD" command is available only - after the user-PI has authenticated itself to the server-FTP process. - Thus, all virtual hosts would be required to share a common - authentication scheme. Second, either the server-FTP process needs - to be modified to understand the special nature of this first CWD - command, negating most of the advantage of this scheme, or all users - must see the same identical NVFS view upon connecting (they must - connect in the same initial directory) or the NVFS must implement the - full set of virtual host directories at each possible initial - directory for any possible user, or the virtual host will not be - truly transparent. Third, and again unless the server is specially - modified, a user connecting this way to a virtual host would be able - to trivially move to any other virtual host supported at the same - server-FTP process, exposing the nature of the virtual host. - - Other schemes overloading other existing FTP commands have also been - proposed. None of those have sufficient merit to be worth - discussion. - - The conclusion from the examination of the possibilities seems to be - that to obtain an adequate emulation of "real" FTP servers, server - modifications to support virtual hosts are required. A new command - seems most likely to provide the support required. - - - - - -Elz & Hethmon [Expires April 2000] [Page 17] - - -Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 - - -6.1. The HOST command - - A new command "HOST" is added to the FTP command set to allow - server-FTP process to determine to which of possibly many virtual - hosts the client wishes to connect. This command is intended to be - issued before the user is authenticated, allowing the authentication - scheme, and set of legal users, to be dependent upon the virtual host - chosen. Server-FTP processes may, if they desire, permit the HOST - command to be issued after the user has been authenticated, or may - treat that as an erroneous sequence of commands. The behavior of the - server-FTP process which does allow late HOST commands is undefined. - One reasonable interpretation would be for the user-PI to be returned - to the state that existed after the TCP connection was first - established, before user authentication. - - Servers should note that the response to the HOST command is a - sensible time to send their "welcome" message. This allows the - message to be personalized for any virtual hosts that are supported, - and also allows the client to have determined supported languages, or - representations, for the message, and other messages, via the FEAT - response, and selected an appropriate one via the LANG command. See - [7] for more information. - -6.2. Syntax of the HOST command - - The HOST command is defined as follows. - - host-command = "Host" SP hostname CRLF - hostname = 1*DNCHAR 1*( "." 1*DNCHAR ) [ "." ] - DNCHAR = ALPHA / DIGIT / "-" / "_" / "$" / - "!" / "%" / "[" / "]" / ":" - host-response = host-ok / error-response - host-ok = "220" [ SP *TCHAR ] CRLF - - As with all FTP commands, the "host" command word is case - independent, and may be specified in any character case desired. - - The "hostname" given as a parameter specifies the virtual host to - which access is desired. It should normally be the same name that - was used to obtain the IP address to which the FTP control connection - was made, after any client conversions to convert an abbreviated or - local alias to a complete (fully qualified) domain name, but before - resolving a DNS alias (owner of a CNAME resource record) to its - canonical name. - - If the client was given a network literal address, and consequently - was not required to derive it from a hostname, it should send the - HOST command with the network address, as specified to it, enclosed - - - -Elz & Hethmon [Expires April 2000] [Page 18] - - -Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 - - - in brackets (after eliminating any syntax, which might also be - brackets, but is not required to be, from which the server deduced - that a literal address had been specified.) That is, for example - - HOST [10.1.2.3] - - should be sent if the client had been instructed to connect to - "10.1.2.3", or "[10.1.2.3]", or perhaps even IPv4:10.1.2.3. The - method of indicating to a client that a literal address is to be used - is beyond the scope of this specification. - - The parameter is otherwise to be treated as a "complete domain name", - as that term is defined in section 3.1 of RFC 1034 [10]. That - implies that the name is to be treated as a case independent string, - in that upper case ASCII characters are to be treated as equivalent - to the corresponding lower case ASCII characters, but otherwise - preserved as given. It also implies some limits on the length of the - parameter and of the components that create its internal structure. - Those limits are not altered in any way here. - - RFC 1034 imposes no other restrictions upon what kinds of names can - be stored in the DNS. Nor does RFC 1035. This specification, - however, allows only a restricted set of names for the purposes of - the HOST command. Those restrictions can be inferred from the ABNF - grammar given for the "hostname". - -6.3. HOST command semantics - - Upon receiving the HOST command, before authenticating the user-PI, a - server-FTP process should validate that the hostname given represents - a valid virtual host for that server, and if so, establish the - appropriate environment for that virtual host. The meaning of that - is not specified here, and may range from doing nothing at all, or - performing a simple change of working directory, to much more - elaborate state changes, as required. - - If the hostname specified is unknown at the server, or if the server - is otherwise unwilling to treat the particular connection as a - connection to the hostname specified, the server will respond with a - 504 reply. - - Note: servers may require that the name specified is in some sense - equivalent to the particular network address that was used to reach - the server. - - If the hostname specified would normally be acceptable, but for any - reason is temporarily unavailable, the server SHOULD reply to the - HOST command with a 434 reply. - - - -Elz & Hethmon [Expires April 2000] [Page 19] - - -Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 - - - The "220" reply code for the HOST command is the same as the code - used on the initial connection established "welcome" message. This - is done deliberately so as to allow the implementation to implement - the front end FTP server as a wrapper which simply waits for the HOST - command, and then invokes an older, RFC959 compliant, server in the - appropriate environment for the particular hostname received. - -6.3.1. The REIN command - - As specified in [3], the REIN command returns the state of the - connection to that it was immediately after the transport connection - was opened. That is not changed here. The effect of a HOST command - will be lost if a REIN command is performed, a new HOST command must - be issued. - - Implementors of user-FTP should be aware that server-FTP - implementations which implement the HOST command as a wrapper around - older implementations will be unable to correctly implement the REIN - command. In such an implementation, REIN will typically return the - server-FTP to the state that existed immediately after the HOST - command was issued, instead of to the state immediately after the - connection was opened. - -6.3.2. User-PI usage of HOST - - A user-PI that conforms to this specification, MUST send the HOST - command after opening the transport connection, or after any REIN - command, before attempting to authenticate the user with the USER - command. - - The following state diagram shows a typical sequence of flow of - control, where the "B" (begin) state is assumed to occur after the - transport connection has opened, or a REIN command has succeeded. - Other commands (such as FEAT [6]) which require no authentication may - have intervened. This diagram is modeled upon (and largely borrowed - from) the similar diagram in section 6 of [3]. - - In this diagram, a three digit reply indicates that precise server - reply code, a single digit on a reply path indicates any server reply - beginning with that digit, other than any three digit replies that - might take another path. - - - - - - - - - - -Elz & Hethmon [Expires April 2000] [Page 20] - - -Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 - - - - +---+ HOST +---+ 1,3,5 - | B |---------->| W |----------------- - +---+ +---+ | - | | | - 2,500,502 | | 4,501,503,504 | - -------------- ------------- | - | | | - V 1 | V - +---+ USER +---+-------------->+---+ - | |---------->| W | 2 ----->| E | - +---+ +---+------ | --->+---+ - | | | | | | - 3 | | 4,5 | | | | - -------------- ----- | | | | - | | | | | | - | | | | | | - | --------- | | - | 1| | | | | - V | | | | | - +---+ PASS +---+ 2 | ------->+---+ - | |---------->| W |-------------->| S | - +---+ +---+ ----------->+---+ - | | | | | | - 3 | |4,5| | | | - -------------- -------- | | - | | | | | ---- - | | | | | | - | ----------- | - | 1,3| | | | | - V | 2| | | V - +---+ ACCT +---+-- | ------>+---+ - | |---------->| W | 4,5 --------->| F | - +---+ +---+-------------->+---+ - -6.4. HOST command errors - - The server-PI shall reply with a 500 or 502 reply if the HOST command - is unrecognized or unimplemented. A 503 reply may be sent if the - HOST command is given after a previous HOST command, or after a user - has been authenticated. Alternately, the server may accept the - command at such a time, with server defined behavior. A 501 reply - should be sent if the hostname given is syntactically invalid, and a - 504 reply if a syntactically valid hostname is not a valid virtual - host name for the server. - - In all such cases the server-FTP process should act as if no HOST - command had been given. - - - -Elz & Hethmon [Expires April 2000] [Page 21] - - -Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 - - - A user-PI receiving a 500 or 502 reply should assume that the - server-PI does not implement the HOST command style virtual server. - It may then proceed to login as if the HOST command had succeeded, - and perhaps, attempt a CWD command to the hostname after - authenticating the user. - - A user-PI receiving some other error reply should assume that the - virtual HOST is unavailable, and terminate communications. - - A server-PI that receives a USER command, beginning the - authentication sequence, without having received a HOST command - SHOULD NOT reject the USER command. Clients conforming to earlier - FTP specifications do not send HOST commands. In this case the - server may act as if some default virtual host had been explicitly - selected, or may enter an environment different from that of all - supported virtual hosts, perhaps one in which a union of all - available accounts exists, and which presents a NVFS which appears to - contain sub-directories containing the NVFS for all virtual hosts - supported. - -6.5. FEAT response for HOST command - - A server-FTP process that supports the host command, and virtual FTP - servers, MUST include in the response to the FEAT command [6], a - feature line indicating that the HOST command is supported. This - line should contain the single word "HOST". This MAY be sent in - upper or lower case, or a mixture of both (it is case insensitive) - but SHOULD be transmitted in upper case only. That is, the response - SHOULD be - - C> Feat - S> 211- - S> ... - S> HOST - S> ... - S> 211 End - - The ellipses indicate place holders where other features may be - included, and are not required. The one space indentation of the - feature lines is mandatory [6]. - - - - - - - - - - - -Elz & Hethmon [Expires April 2000] [Page 22] - - -Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 - - -7. A Trivial Virtual File Store (TVFS) - - Traditionally, FTP has placed almost no constraints upon the file - store (NVFS) provided by a server. This specification does not alter - that. However, it has become common for servers to attempt to - provide at least file system naming conventions modeled loosely upon - those of the UNIX(TM) file system. That is, a tree structured file - system, built of directories, each of which can contain other - directories, or other kinds of files, or both. Each file and - directory has a file name relative to the directory that contains it, - except for the directory at the root of the tree, which is contained - in no other directory, and hence has no name of its own. - - That which has so far been described is perfectly consistent with the - standard FTP NVFS and access mechanisms. The "CWD" command is used - to move from one directory to an embedded directory. "CDUP" may be - provided to return to the parent directory, and the various file - manipulation commands ("RETR", "STOR", the rename commands, etc) are - used to manipulate files within the current directory. - - However, it is often useful to be able to reference files other than - by changing directories, especially as FTP provides no guaranteed - mechanism to return to a previous directory. The Trivial Virtual - File Store (TVFS), if implemented, provides that mechanism. - -7.1. TVFS File Names - - Where a server implements the TVFS, no elementary filename shall - contain the character "/". Where the underlying natural file store - permits files, or directories, to contain the "/" character in their - names, a server-PI implementing TVFS must encode that character in - some manner whenever file or directory names are being returned to - the user-PI, and reverse that encoding whenever such names are being - accepted from the user-PI. - - The encoding method to be used is not specified here. Where some - other character is illegal in file and directory names in the - underlying file store, a simple transliteration may be sufficient. - Where there is no suitable substitute character a more complex - encoding scheme, possibly using an escape character, is likely to be - required. - - With the one exception of the unnamed root directory, a TVFS file - name may not be empty. That is, all other file names contain at - least one character. - - With the sole exception of the "/" character, any valid IS10646 - character [11] may be used in a TVFS filename. When transmitted, - - - -Elz & Hethmon [Expires April 2000] [Page 23] - - -Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 - - - file name characters are encoded using the UTF-8 encoding [2]. - -7.2. TVFS Path Names - - A TVFS "Path Name" combines the file or directory name of a target - file or directory, with the directory names of zero or more enclosing - directories, so as to allow the target file or directory to be - referenced other than when the server's "current working directory" - is the directory directly containing the target file or directory. - - By definition, every TVFS file or directory name is also a TVFS path - name. Such a path name is valid to reference the file from the - directory containing the name, that is, when that directory is the - server-FTP's current working directory. - - Other TVFS path names are constructed by prefixing a path name by a - name of a directory from which the path is valid, and separating the - two with the "/" character. Such a path name is valid to reference - the file or directory from the directory containing the newly added - directory name. - - Where a path name has been extended to the point where the directory - added is the unnamed root directory, the path name will begin with - the "/" character. Such a path is known as a fully qualified path - name. Fully qualified paths may, obviously, not be further extended, - as, by definition, no directory contains the root directory. Being - unnamed, it cannot be represented in any other directory. A fully - qualified path name is valid to reference the named file or directory - from any location (that is, regardless of what the current working - directory may be) in the virtual file store. - - Any path name which is not a fully qualified path name may be - referred to as a "relative path name" and will only correctly - reference the intended file when the current working directory of the - server-FTP is a directory from which the relative path name is valid. - - As a special case, the path name "/" is defined to be a fully - qualified path name referring to the root directory. That is, the - root directory does not have a directory (or file) name, but does - have a path name. This special path name may be used only as is as a - reference to the root directory. It may not be combined with other - path names using the rules above, as doing so would lead to a path - name containing two consecutive "/" characters, which is an undefined - sequence. - - - - - - - -Elz & Hethmon [Expires April 2000] [Page 24] - - -Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 - - -7.2.1. Notes - - + It is not required, or expected, that there be only one fully - qualified path name that will reference any particular file or - directory. - + As a caveat, though the TVFS file store is basically tree - structured, there is no requirement that any file or directory - have only one parent directory. - + As defined, no TVFS path name will ever contain two consecutive - "/" characters. Such a name is not illegal however, and may be - defined by the server for any purpose that suits it. Clients - implementing this specification should not assume any semantics - at all for such names. - + Similarly, other than the special case path that refers to the - root directory, no TVFS path name constructed as defined here - will ever end with the "/" character. Such names are also not - illegal, but are undefined. - + While any legal IS10646 character is permitted to occur in a TVFS - file or directory name, other than "/", server FTP - implementations are not required to support all possible IS10646 - characters. The subset supported is entirely at the discretion - of the server. The case (where it exists) of the characters that - make up file, directory, and path names may be significant. - Unless determined otherwise by means unspecified here, clients - should assume that all such names are comprised of characters - whose case is significant. Servers are free to treat case (or - any other attribute) of a name as irrelevant, and hence map two - names which appear to be distinct onto the same underlying file. - + There are no defined "magic" names, like ".", ".." or "C:". - Servers may implement such names, with any semantics they choose, - but are not required to do so. - + TVFS imposes no particular semantics or properties upon files, - guarantees no access control schemes, or any of the other common - properties of a file store. Only the naming scheme is defined. - -7.3. FEAT Response for TVFS - - In response to the FEAT command [6] a server that wishes to indicate - support for the TVFS as defined here will include a line that begins - with the four characters "TVFS" (in any case, or mixture of cases, - upper case is not required). Servers SHOULD send upper case. - - Such a response to the FEAT command MUST NOT be returned unless the - server implements TVFS as defined here. - - Later specifications may add to the TVFS definition. Such additions - should be notified by means of additional text appended to the TVFS - feature line. Such specifications, if any, will define the extra - - - -Elz & Hethmon [Expires April 2000] [Page 25] - - -Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 - - - text. - - Until such a specification is defined, servers should not include - anything after "TVFS" in the TVFS feature line. Clients, however, - should be prepared to deal with arbitrary text following the four - defined characters, and simply ignore it if unrecognized. - - A typical response to the FEAT command issued by a server - implementing only this specification would be: - - C> feat - S> 211- - S> ... - S> TVFS - S> ... - S> 211 end - - The ellipses indicate place holders where other features may be - included, and are not required. The one space indentation of the - feature lines is mandatory [6], and is not counted as one of the - first four characters for the purposes of this feature listing. - - The TVFS feature adds no new commands to the FTP command repertoire. - -7.4. OPTS for TVFS - - There are no options in this TVFS specification, and hence there is - no OPTS command defined. - -7.5. TVFS Examples - - Assume a TVFS file store is comprised of a root directory, which - contains two directories (A and B) and two non-directory files (X and - Y). The A directory contains two directories (C and D) and one other - file (Z). The B directory contains just two non-directory files (P - and Q) and the C directory also two non-directory files (also named P - and Q, by chance). The D directory is empty, that is, contains no - files or directories. - - - - - - - - - - - - - -Elz & Hethmon [Expires April 2000] [Page 26] - - -Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 - - - This structure may depicted graphically as... - - (unnamed root) - / | \ \ - / | \ \ - A X B Y - /|\ / \ - / | \ / \ - C D Z P Q - / \ - / \ - P Q - - Given this structure, the following fully qualified path names exist. - - / - /A - /B - /X - /Y - /A/C - /A/D - /A/Z - /A/C/P - /A/C/Q - /B/P - /B/Q - - It is clear that none of the paths / /A /B or /A/D refer to the same - directory, as the contents of each is different. Nor do any of / /A - /A/C or /A/D. However /A/C and /B might be the same directory, there - is insufficient information given to tell. Any of the other path - names (/X /Y /A/Z /A/C/P /A/C/Q /B/P and /B/Q) may refer to the same - underlying files, in almost any combination. - - If the current working directory of the server-FTP is /A then the - following path names, in addition to all the fully qualified path - names, are valid - - C - D - Z - C/P - C/Q - - These all refer to the same files or directories as the corresponding - fully qualified path with "/A/" prepended. - - - - -Elz & Hethmon [Expires April 2000] [Page 27] - - -Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 - - - That those path names all exist does not imply that the TVFS sever - will necessarily grant any kind of access rights to the named paths, - or that access to the same file via different path names will - necessarily be granted equal rights. - - None of the following relative paths are valid when the current - directory is /A - - A - B - X - Y - B/P - B/Q - P - Q - - Any of those could be made valid by changing the server-FTP's current - working directory to the appropriate directory. Note that the paths - "P" and "Q" might refer to different files depending upon which - directory is selected to cause those to become valid TVFS relative - paths. - -8. Listings for Machine Processing (MLST and MLSD) - - The MLST and MLSD commands are intended to standardize the file and - directory information returned by the Server-FTP process. These - commands differ from the LIST command in that the format of the - replies is strictly defined although extensible. - - Two commands are defined, MLST which provides data about exactly the - object named on its command line, and no others. MLSD on the other - hand will list the contents of a directory if a directory is named, - otherwise a 501 reply will be returned. In either case, if no object - is named, the current directory is assumed. That will cause MLST to - send a one line response, describing the current directory itself, - and MLSD to list the contents of the current directory. - - In the following, the term MLSx will be used wherever either MLST or - MLSD may be inserted. - - The MLST and MLSD commands also extend the FTP protocol as presented - in RFC 959 [3] and RFC 1123 [9] to allow that transmission of 8-bit - data over the control connection. Note this is not specifying - character sets which are 8-bit, but specifying that FTP - implementations are to specifically allow the transmission and - reception of 8-bit bytes, with all bits significant, over the control - connection. That is, all 256 possible octet values are permitted. - - - -Elz & Hethmon [Expires April 2000] [Page 28] - - -Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 - - - The MLSx command allows both UTF-8/Unicode and "raw" forms as - arguments, and in responses both to the MLST and MLSD commands, and - all other FTP commands which take pathnames as arguments. - -8.1. Format of MLSx Requests - - The MLST and MLSD commands each allow a single optional argument. - This argument may be either a directory name or, for MLST only, a - filename. For these purposes, a "filename" is the name of any entity - in the server NVFS which is not a directory. Where TVFS is - supported, any TVFS relative path name valid in the current working - directory, or any TVFS fully qualified path name, may be given. If a - directory name is given then MLSD must return a listing of the - contents of the named directory, otherwise it issues a 501 reply, and - does not open a data connection. In all cases for MLST, a single set - of fact lines (usually a single fact line) containing the information - about the named file or directory shall be returned over the control - connection, without opening a data connection. - - If no argument is given then MLSD must return a listing of the - contents of the current working directory, and MLST must return a - listing giving information about the current working directory - itself. For these purposes, the contents of a directory are whatever - filenames (not pathnames) the server-PI will allow to be referenced - when the current working directory is the directory named, and which - the server-PI desires to reveal to the user-PI. - - No title, header, or summary, lines, or any other formatting, other - than as is specified below, is ever returned in the output of an MLST - or MLSD command. - - If the Client-FTP sends an invalid argument, the Server-FTP MUST - reply with an error code of 501. - - The syntax for the MLSx command is: - - mlst = "MLst" [ SP pathname ] CRLF - mlsd = "MLsD" [ SP pathname ] CRLF - -8.2. Format of MLSx Response - - The format of a response to an MLSx command is as follows: - - mlst-response = control-response / error-response - mlsd-response = ( initial-response final-response ) / - error-response - - - - - -Elz & Hethmon [Expires April 2000] [Page 29] - - -Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 - - - control-response = "250-" [ response-message ] CRLF - 1*( SP entry CRLF ) - "250" [ SP response-message ] CRLF - - initial-response = "150" [ SP response-message ] CRLF - final-response = "226" SP response-message CRLF - - response-message = *TCHAR - - data-response = *( entry CRLF ) - - entry = [ facts ] SP pathname - facts = 1*( fact ";" ) - fact = factname "=" value - factname = "Size" / "Modify" / "Create" / - "Type" / "Unique" / "Perm" / - "Lang" / "Media-Type" / "CharSet" / - os-depend-fact / local-fact - os-depend-fact = "." token - local-fact = "X." token - value = *RCHAR - - Upon receipt of a MLSx command, the server will verify the parameter, - and if invalid return an error-response. For this purpose, the - parameter should be considered to be invalid if the client issuing - the command does not have permission to perform the request - operation. - - If valid, then for an MLST command, the server-PI will send the first - (leading) line of the control response, the entry for the pathname - given, or the current directory if no pathname was provided, and the - terminating line. Normally exactly one entry would be returned, more - entries are permitted only when required to represent a file that is - to have multiple "Type" facts returned. - - Note that for MLST the fact set is preceded by a space. That is - provided to guarantee that the fact set cannot be accidentally - interpreted as the terminating line of the control response, but is - required even when that would not be possible. Exactly one space - exists between the set of facts and the pathname. Where no facts are - present, there will be exactly two leading spaces before the - pathname. No spaces are permitted in the facts, any other spaces in - the response are to be treated as being a part of the pathname. - - If the command was an MLSD command, the server will open a data - connection as indicated in section 3.2 of RFC959 [3]. If that fails, - the server will return an error-response. If all is OK, the server - will return the initial-response, send the appropriate data-response - - - -Elz & Hethmon [Expires April 2000] [Page 30] - - -Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 - - - over the new data connection, close that connection, and then send - the final-response over the control connection. The grammar above - defines the format for the data-response, which defines the format of - the data returned over the data connection established. - - The data connection opened for a MLSD response shall be a connection - as if the "TYPE L 8", "MODE S", and "STRU F" commands had been given, - whatever FTP transfer type, mode and structure had actually been set, - and without causing those settings to be altered for future commands. - That is, this transfer type shall be set for the duration of the data - connection established for this command only. While the content of - the data sent can be viewed as a series of lines, implementations - should note that there is no maximum line length defined. - Implementations should be prepared to deal with arbitrarily long - lines. - - The facts part of the specification would contain a series of "file - facts" about the file or directory named on the same line. Typical - information to be presented would include file size, last - modification time, creation time, a unique identifier, and a - file/directory flag. - - The complete format for a successful reply to the MLSD command would - be: - - facts SP pathname CRLF - facts SP pathname CRLF - facts SP pathname CRLF - ... - - Note that the format is intended for machine processing, not human - viewing, and as such the format is very rigid. Implementations MUST - NOT vary the format by, for example, inserting extra spaces for - readability, replacing spaces by tabs, including header or title - lines, or inserting blank lines, or in any other way alter this - format. Exactly one space is always required after the set of facts - (which may be empty). More spaces may be present on a line if, and - only if, the file name presented contains significant spaces. The - set of facts must not contain any spaces anywhere inside it. Facts - should be provided in each output line only if they both provide - relevant information about the file named on the same line, and they - are in the set requested by the user-PI. There is no requirement - that the same set of facts be provided for each file, or that the - facts presented occur in the same order for each file. - - - - - - - -Elz & Hethmon [Expires April 2000] [Page 31] - - -Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 - - -8.3. Filename encoding - - An FTP implementation supporting the MLSx commands must be 8-bit - clean. This is necessary in order to transmit UTF-8 encoded - filenames. This specification recommends the use of UTF-8 encoded - filenames. FTP implementations SHOULD use UTF-8 whenever possible to - encourage the maximum interoperability. - - Filenames are not restricted to UTF-8, however treatment of arbitrary - character encodings is not specified by this standard. Applications - are encouraged to treat non-UTF-8 encodings of filenames as octet - sequences. - - Note that this encoding is unrelated to that of the contents of the - file, even if the file contains character data. - - Further information about filename encoding for FTP may be found in - "Internationalization of the File Transfer Protocol" [7]. - -8.3.1. Notes about the Filename - - The filename returned in the MLST response should be the same name as - was specified in the MLST command, or, where TVFS is supported, a - fully qualified TVFS path naming the same file. Where no argument - was given to the MLST command, the server-PI may either include an - empty filename in the response, or it may supply a name that refers - to the current directory, if such a name is available. Where TVFS is - supported, a fully qualified path name of the current directory - SHOULD be returned. - - Filenames returned in the output from an MLSD command SHOULD be - unqualified names within the directory named, or the current - directory if no argument was given. That is, the directory named in - the MLSD command SHOULD NOT appear as a component of the filenames - returned. - - If the server-FTP process is able, and the "type" fact is being - returned, it MAY return in the MLSD response, an entry whose type is - "cdir", which names the directory from which the contents of the - listing were obtained. Where TVFS is supported, the name MAY be the - fully qualified path name of the directory, or MAY be any other path - name which is valid to refer to that directory from the current - working directory of the server-FTP. Where more than one name - exists, multiple of these entries may be returned. In a sense, the - "cdir" entry can be viewed as a heading for the MLSD output. - However, it is not required to be the first entry returned, and may - occur anywhere within the listing. - - - - -Elz & Hethmon [Expires April 2000] [Page 32] - - -Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 - - - When TVFS is supported, a user-PI can refer to any file or directory - in the listing by combining a type "cdir" name, with the appropriate - name from the directory listing using the procedure defined in - section 7.2. - - Alternatively, whether TVFS is supported or not, the user-PI can - issue a CWD command ([3]) giving a name of type "cdir" from the - listing returned, and from that point reference the files returned in - the MLSD response from which the cdir was obtained by using the - filename components of the listing. - -8.4. Format of Facts - - The "facts" for a file in a reply to a MLSx command consist of - information about that file. The facts are a series of keyword=value - pairs each followed by semi-colon (";") characters. An individual - fact may not contain a semi-colon in its name or value. The complete - series of facts may not contain the space character. See the - definition or "RCHAR" in section 2.1 for a list of the characters - that can occur in a fact value. Not all are applicable to all facts. - - A sample of a typical series of facts would be: (spread over two - lines for presentation here only) - - size=4161;lang=en-US;modify=19970214165800;create=19961001124534; - type=file;x.myfact=foo,bar; - -8.5. Standard Facts - - This document defines a standard set of facts as follows: - - size -- Size in octets - modify -- Last modification time - create -- Creation time - type -- Entry type - unique -- Unique id of file/directory - perm -- File permissions, whether read, write, execute is - allowed for the login id. - lang -- Language of the filename per IANA[12] registry. - media-type -- MIME media-type of file contents per IANA registry. - charset -- Character set per IANA registry (if not UTF-8) - - Fact names are case-insensitive. Size, size, SIZE, and SiZe are the - same fact. - - Further operating system specific keywords could be specified by - using the IANA operating system name as a prefix (examples only): - - - - -Elz & Hethmon [Expires April 2000] [Page 33] - - -Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 - - - OS/2.ea -- OS/2 extended attributes - MACOS.rf -- MacIntosh resource forks - UNIX.mode -- Unix file modes (permissions) - - Implementations may define keywords for experimental, or private use. - All such keywords MUST begin with the two character sequence "x.". - As type names are case independent, "x." and "X." are equivalent. - For example: - - x.ver -- Version information - x.desc -- File description - x.type -- File type - -8.5.1. The type Fact - - The type fact needs a special description. Part of the problem with - current practices is deciding when a file is a directory. If it is a - directory, is it the current directory, a regular directory, or a - parent directory? The MLST specification makes this unambiguous - using the type fact. The type fact given specifies information about - the object listed on the same line of the MLST response. - - Five values are possible for the type fact: - - file -- a file entry - cdir -- the listed directory - pdir -- a parent directory - dir -- a directory or sub-directory - OS.name=type -- an OS or file system dependent file type - - The syntax is defined to be: - - type-fact = type-label "=" type-val - type-label = "Type" - type-val = "File" / "cdir" / "pdir" / "dir" / - os-type - -8.5.1.1. type=file - - The presence of the type=file fact indicates the listed entry is a - file containing non-system data. That is, it may be transferred from - one system to another of quite different characteristics, and perhaps - still be meaningful. - -8.5.1.2. type=cdir - - The type=cdir fact indicates the listed entry contains a pathname of - the directory whose contents are listed. An entry of this type will - - - -Elz & Hethmon [Expires April 2000] [Page 34] - - -Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 - - - only be returned as a part of the result of an MLSD command when the - type fact is included, and provides a name for the listed directory, - and facts about that directory. In a sense, it can be viewed as - representing the title of the listing, in a machine friendly format. - It may appear at any point of the listing, it is not restricted to - appearing at the start, though frequently may do so, and may occur - multiple times. It MUST NOT be included if the type fact is not - included, or there would be no way for the user-PI to distinguish the - name of the directory from an entry in the directory. - - Where TVFS is supported by the server-FTP, this name may be used to - construct path names with which to refer to the files and directories - returned in the same MLSD output (see section 7.2). These path names - are only expected to work when the server-PI's position in the NVFS - file tree is the same as its position when the MLSD command was - issued, unless a fully qualified path name results. - - Where TVFS is not supported, the only defined semantics associated - with a "type=cdir" entry are that, provided the current working - directory of the server-PI has not been changed, a pathname of type - "cdir" may be used as an argument to a CWD command, which will cause - the current directory of the server-PI to change so that the - directory which was listed in its current working directory. - -8.5.1.3. type=dir - - If present, the type=dir entry gives the name of a directory. Such - an entry typically cannot be transferred from one system to another - using RETR, etc, but should (permissions permitting) be able to be - the object of an MLSD command. - -8.5.1.4. type=pdir - - If present, which will occur only in the response to a MLSD command - when the type fact is included, the type=pdir entry represents a - pathname of the parent directory of the listed directory. As well as - having the properties of a type=dir, a CWD command that uses the - pathname from this entry should change the user to a parent directory - of the listed directory. If the listed directory is the current - directory, a CDUP command may also have the effect of changing to the - named directory. User-FTP processes should note not all responses - will include this information, and that some systems may provide - multiple type=pdir responses. - - Where TVFS is supported, a "type=pdir" name may be a relative path - name, or a fully qualified path name. A relative path name will be - relative to the directory being listed, not to the current directory - of the server-PI at the time. - - - -Elz & Hethmon [Expires April 2000] [Page 35] - - -Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 - - - For the purposes of this type value, a "parent directory" is any - directory in which there is an entry of type=dir which refers to the - directory in which the type=pdir entity was found. Thus it is not - required that all entities with type=pdir refer to the same - directory. The "unique" fact (if supported) can be used to determine - whether there is a relationship between the type=pdir entries or not. - -8.5.1.5. System defined types - - Files types that are specific to a specific operating system, or file - system, can be encoded using the "OS." type names. The format is: - - os-type = "OS." os-name "=" os-type - os-name = - os-type = token - - The "os-name" indicates the specific system type which supports the - particular localtype. OS specific types are registered by the IANA - using the procedures specified in section 11. The "os-type" provides - the system dependent information as to the type of the file listed. - The os-name and os-type strings in an os-type are case independent. - "OS.unix=block" and "OS.Unix=BLOCK" represent the same type (or - would, if such a type were registered.) - - Note: Where the underlying system supports a file type which is - essentially an indirect pointer to another file, the NVFS - representation of that type should normally be to represent the file - which the reference indicates. That is, the underlying basic file - will appear more than once in the NVFS, each time with the "unique" - fact (see immediately following section) containing the same value, - indicating that the same file is represented by all such names. - User-PIs transferring the file need then transfer it only once, and - then insert their own form of indirect reference to construct - alternate names where desired, or perhaps even copy the local file if - that is the only way to provide two names with the same content. A - file which would be a reference to another file, if only the other - file actually existed, may be represented in any OS dependent manner - appropriate, or not represented at all. - -8.5.1.6. Multiple types - - Where a file is such that it may validly, and sensibly, treated by - the server-PI as being of more than one of the above types, then - multiple entries should be returned, each with its own "Type" fact of - the appropriate type, and each containing the same pathname. This - may occur, for example, with a structured file, which may contain - sub-files, and where the server-PI permits the structured file to be - treated as a unit, or treated as a directory allowing the sub-files - - - -Elz & Hethmon [Expires April 2000] [Page 36] - - -Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 - - - within it to be referenced. - -8.5.2. The unique Fact - - The unique fact is used to present a unique identifier for a file or - directory in the NVFS accessed via a server-FTP process. The value - of this fact should be the same for any number of pathnames that - refer to the same underlying file. The fact should have different - values for names which reference distinct files. The mapping between - files, and unique fact tokens should be maintained, and remain - consistent, for at least the lifetime of the control connection from - user-PI to server-PI. - - unique-fact = "Unique" "=" token - - This fact would be expected to be used by Server-FTPs whose host - system allows things such as symbolic links so that the same file may - be represented in more than one directory on the server. The only - conclusion that should be drawn is that if two different names each - have the same value for the unique fact, they refer to the same - underlying object. The value of the unique fact (the token) should - be considered an opaque string for comparison purposes, and is a case - dependent value. The tokens "A" and "a" do not represent the same - underlying object. - -8.5.3. The modify Fact - - The modify fact is used to determine the last time the content of the - file (or directory) indicated was modified. Any change of substance - to the file should cause this value to alter. That is, if a change - is made to a file such that the results of a RETR command would - differ, then the value of the modify fact should alter. User-PIs - should not assume that a different modify fact value indicates that - the file contents are necessarily different than when last retrieved. - Some systems may alter the value of the modify fact for other - reasons, though this is discouraged wherever possible. Also a file - may alter, and then be returned to its previous content, which would - often be indicated as two incremental alterations to the value of the - modify fact. - - For directories, this value should alter whenever a change occurs to - the directory such that different filenames would (or might) be - included in MLSD output of that directory. - - - - - - - - -Elz & Hethmon [Expires April 2000] [Page 37] - - -Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 - - - modify-fact = "Modify" "=" time-val - -8.5.4. The create Fact - - The create fact indicates when a file, or directory, was first - created. Exactly what "creation" is for this purpose is not - specified here, and may vary from server to server. About all that - can be said about the value returned is that it can never indicate a - later time than the modify fact. - - create-fact = "Create" "=" time-val - - Implementation Note: Implementors of this fact on UNIX(TM) systems - should note that the unix "stat" "st_ctime" field does not give - creation time, and that unix file systems do not record creation - time at all. Unix (and POSIX) implementations will normally not - include this fact. - -8.5.5. The perm Fact - - The perm fact is used to indicate access rights the current FTP user - has over the object listed. Its value is always an unordered - sequence of alphabetic characters. - - perm-fact = "Perm" "=" *pvals - pvals = "a" / "c" / "d" / "e" / "f" / - "l" / "m" / "p" / "r" / "w" - - There are ten permission indicators currently defined. Many are - meaningful only when used with a particular type of object. The - indicators are case independent, "d" and "D" are the same indicator. - - The "a" permission applies to objects of type=file, and indicates - that the APPE (append) command may be applied to the file named. - - The "c" permission applies to objects of type=dir (and type=pdir, - type=cdir). It indicates that files may be created in the directory - named. That is, that a STOU command is likely to succeed, and that - STOR and APPE commands might succeed if the file named did not - previously exist, but is to be created in the directory object that - has the "c" permission. It also indicates that the RNTO command is - likely to succeed for names in the directory. - - The "d" permission applies to all types. It indicates that the - object named may be deleted, that is, that the RMD command may be - applied to it if it is a directory, and otherwise that the DELE - command may be applied to it. - - - - -Elz & Hethmon [Expires April 2000] [Page 38] - - -Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 - - - The "e" permission applies to the directory types. When set on an - object of type=dir, type=cdir, or type=pdir it indicates that a CWD - command naming the object should succeed, and the user should be able - to enter the directory named. For type=pdir it also indicates that - the CDUP command may succeed (if this particular pathname is the one - to which a CDUP would apply.) - - The "f" permission for objects indicates that the object named may be - renamed - that is, may be the object of an RNFR command. - - The "l" permission applies to the directory file types, and indicates - that the listing commands, LIST, NLST, and MLSD may be applied to the - directory in question. - - The "m" permission applies to directory types, and indicates that the - MKD command may be used to create a new directory within the - directory under consideration. - - The "p" permission applies to directory types, and indicates that - objects in the directory may be deleted, or (stretching naming a - little) that the directory may be purged. Note: it does not indicate - that the RMD command may be used to remove the directory named - itself, the "d" permission indicator indicates that. - - The "r" permission applies to type=file objects, and for some - systems, perhaps to other types of objects, and indicates that the - RETR command may be applied to that object. - - The "w" permission applies to type=file objects, and for some - systems, perhaps to other types of objects, and indicates that the - STOR command may be applied to the object named. - - Note: That a permission indicator is set can never imply that the - appropriate command is guaranteed to work - just that it might. - Other system specific limitations, such as limitations on - available space for storing files, may cause an operation to - fail, where the permission flags may have indicated that it was - likely to succeed. The permissions are a guide only. - - Implementation note: The permissions are described here as they apply - to FTP commands. They may not map easily into particular - permissions available on the server's operating system. Servers - are expected to synthesize these permission bits from the - permission information available from operating system. For - example, to correctly determine whether the "D" permission bit - should be set on a directory for a server running on the - UNIX(TM) operating system, the server should check that the - directory named is empty, and that the user has write permission - - - -Elz & Hethmon [Expires April 2000] [Page 39] - - -Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 - - - on both the directory under consideration, and its parent - directory. - - Some systems may have more specific permissions than those - listed here, such systems should map those to the flags defined - as best they are able. Other systems may have only more broad - access controls. They will generally have just a few possible - permutations of permission flags, however they should attempt to - correctly represent what is permitted. - -8.5.6. The lang Fact - - The lang fact describes the natural language of the filename for use - in display purposes. Values used here should be taken from the - language registry of the IANA. See [13] for the syntax, and - procedures, related to language tags. - - lang-fact = "Lang" "=" token - - Server-FTP implementations MUST NOT guess language values. Language - values must be determined in an unambiguous way such as file system - tagging of language or by user configuration. Note that the lang - fact provides no information at all about the content of a file, only - about the encoding of its name. - -8.5.7. The size Fact - - The size fact applies to non-directory file types and should always - reflect the approximate size of the file. This should be as accurate - as the server can make it, without going to extraordinary lengths, - such as reading the entire file. The size is expressed in units of - octets of data in the file. - - Given limitations in some systems, Client-FTP implementations must - understand this size may not be precise and may change between the - time of a MLST and RETR operation. - - Clients that need highly accurate size information for some - particular reason should use the SIZE command as defined in section - 4. The most common need for this accuracy is likely to be in - conjunction with the REST command described in section 5. The size - fact, on the other hand, should be used for purposes such as - indicating to a human user the approximate size of the file to be - transferred, and perhaps to give an idea of expected transfer - completion time. - - - - - - -Elz & Hethmon [Expires April 2000] [Page 40] - - -Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 - - - size-fact = "Size" "=" 1*DIGIT - -8.5.8. The media-type Fact - - The media-type fact represents the IANA media type of the file named, - and applies only to non-directory types. The list of values used - must follow the guidelines set by the IANA registry. - - media-type = "Media-Type" "=" - - Server-FTP implementations MUST NOT guess media type values. Media - type values must be determined in an unambiguous way such as file - system tagging of media-type or by user configuration. This fact - gives information about the content of the file named. Both the - primary media type, and any appropriate subtype should be given, - separated by a slash "/" as is traditional. - -8.5.9. The charset Fact - - The charset fact provides the IANA character set name, or alias, for - the encoded pathnames in a MLSx response. The default character set - is UTF-8 unless specified otherwise. FTP implementations SHOULD use - UTF-8 if possible to encourage maximum interoperability. The value - of this fact applies to the pathname only, and provides no - information about the contents of the file. - - charset-type = "Charset" "=" token - -8.5.10. Required facts - - Servers are not required to support any particular set of the - available facts. However, servers SHOULD, if conceivably possible, - support at least the type, perm, size, unique, and modify facts. - -8.6. System Dependent and Local Facts - - By using an system dependent fact, or a local fact, a server-PI may - communicate to the user-PI information about the file named which is - peculiar to the underlying file system. - -8.6.1. System Dependent Facts - - System dependent fact names are labeled by prefixing a label - identifying the specific information returned by the name of the - appropriate operating system from the IANA maintained list of - operating system names. - - - - - -Elz & Hethmon [Expires April 2000] [Page 41] - - -Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 - - - The value of an OS dependent fact may be whatever is appropriate to - convey the information available. It must be encoded as a "token" as - defined in section 2.1 however. - - In order to allow reliable interoperation between users of system - dependent facts, the IANA will maintain a registry of system - dependent fact names, their syntax, and the interpretation to be - given to their values. Registrations of system dependent facts are - to be accomplished according to the procedures of section 11. - -8.6.2. Local Facts - - Implementations may also make available other facts of their own - choosing. As the method of interpretation of such information will - generally not be widely understood, server-PIs should be aware that - clients will typically ignore any local facts provided. As there is - no registration of locally defined facts, it is entirely possible - that different servers will use the same local fact name to provide - vastly different information. Hence user-PIs should be hesitant - about making any use of any information in a locally defined fact - without some other specific assurance that the particular fact is one - that they do comprehend. - - Local fact names all begin with the sequence "X.". The rest of the - name is a "token" (see section 2.1). The value of a local fact can - be anything at all, provided it can be encoded as a "token". - -8.7. MLSx Examples - - The following examples are all taken from dialogues between existing - FTP clients and servers. Because of this, not all possible - variations of possible response formats are shown in the examples. - This should not be taken as limiting the options of other server - implementors. Where the examples show OS dependent information, that - is to be treated as being purely for the purposes of demonstration of - some possible OS specific information that could be defined. As at - the time of the writing of this document, no OS specific facts or - file types have been defined, the examples shown here should not be - treated as in any way to be preferred over other possible similar - definitions. Consult the IANA registries to determine what types and - facts have been defined. - - In the examples shown, only relevant commands and responses have been - included. This is not to imply that other commands (including - authentication, directory modification, PORT or PASV commands, or - similar) would not be present in an actual connection, or were not, - in fact, actually used in the examples before editing. Note also - that the formats shown are those that are transmitted between client - - - -Elz & Hethmon [Expires April 2000] [Page 42] - - -Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 - - - and server, not formats which would normally ever be reported to the - user of the client. - - In the examples, lines that begin "C> " were sent over the control - connection from the client to the server, lines that begin "S> " were - sent over the control connection from the server to the client, and - lines that begin "D> " were sent from the server to the client over a - data connection created just to send those lines and closed - immediately after. No examples here show data transferred over a - data connection from the client to the server. In all cases, the - prefixes shown above, including the one space, have been added for - the purposes of this document, and are not a part of the data - exchanged between client and server. - -8.7.1. Simple MLST - - C> PWD - S> 257 "/tmp" is current directory. - C> MLst cap60.pl198.tar.gz - S> 250- Listing cap60.pl198.tar.gz - S> Type=file;Size=1024990;Perm=r; /tmp/cap60.pl198.tar.gz - S> 250 End - - The client first asked to be told the current directory of the - server. This was purely for the purposes of clarity of this example. - The client then requested facts about a specific file. The server - returned the "250-" first control-response line, followed by a single - line of facts about the file, followed by the terminating "250 " - line. The text on the control-response line and the terminating line - can be anything the server decides to send. Notice that the fact - line is indented by a single space. Notice also that there are no - spaces in the set of facts returned, until the single space before - the filename. The filename returned on the fact line is a fully - qualified pathname of the file listed. The facts returned show that - the line refers to a file, that file contains approximately 1024990 - bytes, though more or less than that may be transferred if the file - is retrieved, and a different number may be required to store the - file at the client's file store, and the connected user has - permission to retrieve the file but not to do anything else - particularly interesting. - -8.7.2. MLST of a directory - - C> PWD - S> 257 "/" is current directory. - C> MLst tmp - S> 250- Listing tmp - S> Type=dir;Modify=19981107085215;Perm=el; /tmp - - - -Elz & Hethmon [Expires April 2000] [Page 43] - - -Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 - - - S> 250 End - - Again the PWD is just for the purposes of demonstration for the - example. The MLST fact line this time shows that the file listed is - a directory, that it was last modified at 08:52:15 on the 7th of - November, 1998 UTC, and that the user has permission to enter the - directory, and to list its contents, but not to modify it in any way. - Again, the fully qualified path name of the directory listed is - given. - -8.7.3. MLSD of a directory - - C> MLSD tmp - S> 150 BINARY connection open for MLSD tmp - D> Type=cdir;Modify=19981107085215;Perm=el; tmp - D> Type=cdir;Modify=19981107085215;Perm=el; /tmp - D> Type=pdir;Modify=19990112030508;Perm=el; .. - D> Type=file;Size=25730;Modify=19940728095854;Perm=; capmux.tar.z - D> Type=file;Size=1830;Modify=19940916055648;Perm=r; hatch.c - D> Type=file;Size=25624;Modify=19951003165342;Perm=r; MacIP-02.txt - D> Type=file;Size=2154;Modify=19950501105033;Perm=r; uar.netbsd.patch - D> Type=file;Size=54757;Modify=19951105101754;Perm=r; iptnnladev.1.0.sit.hqx - D> Type=file;Size=226546;Modify=19970515023901;Perm=r; melbcs.tif - D> Type=file;Size=12927;Modify=19961025135602;Perm=r; tardis.1.6.sit.hqx - D> Type=file;Size=17867;Modify=19961025135602;Perm=r; timelord.1.4.sit.hqx - D> Type=file;Size=224907;Modify=19980615100045;Perm=r; uar.1.2.3.sit.hqx - D> Type=file;Size=1024990;Modify=19980130010322;Perm=r; cap60.pl198.tar.gz - S> 226 MLSD completed - - In this example notice that there is no leading space on the fact - lines returned over the data connection. Also notice that two lines - of "type=cdir" have been given. These show two alternate names for - the directory listed, one a fully qualified pathname, and the other a - local name relative to the servers current directory when the MLSD - was performed. Note that all other filenames in the output are - relative to the directory listed, though the server could, if it - chose, give a fully qualified path name for the "type=pdir" line. - This server has chosen not to. The other files listed present a - fairly boring set of files that are present in the listed directory. - Note that there is no particular order in which they are listed. - They are not sorted by filename, by size, or by modify time. Note - also that the "perm" fact has an empty value for the file - "capmux.tar.z" indicating that the connected user has no permissions - at all for that file. This server has chosen to present the "cdir" - and "pdir" lines before the lines showing the content of the - directory, it is not required to do so. The "size" fact does not - provide any meaningful information for a directory, so is not - included in the fact lines for the directory types shown. - - - -Elz & Hethmon [Expires April 2000] [Page 44] - - -Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 - - -8.7.4. A more complex example - - C> MLst test - S> 250- Listing test - S> Type=dir;Perm=el;Unique=keVO1+ZF4 test - S> 250 End - C> MLSD test - S> 150 BINARY connection open for MLSD test - D> Type=cdir;Perm=el;Unique=keVO1+ZF4; test - D> Type=pdir;Perm=e;Unique=keVO1+d?3; .. - D> Type=OS.unix=slink:/foobar;Perm=;Unique=keVO1+4G4; foobar - D> Type=OS.unix=chr-13/29;Perm=;Unique=keVO1+5G4; device - D> Type=OS.unix=blk-11/108;Perm=;Unique=keVO1+6G4; block - D> Type=file;Perm=awr;Unique=keVO1+8G4; writable - D> Type=dir;Perm=cpmel;Unique=keVO1+7G4; promiscuous - D> Type=dir;Perm=;Unique=keVO1+1t2; no-exec - D> Type=file;Perm=r;Unique=keVO1+EG4; two words - D> Type=file;Perm=r;Unique=keVO1+IH4; leading space - D> Type=file;Perm=r;Unique=keVO1+1G4; file1 - D> Type=dir;Perm=cpmel;Unique=keVO1+7G4; incoming - D> Type=file;Perm=r;Unique=keVO1+1G4; file2 - D> Type=file;Perm=r;Unique=keVO1+1G4; file3 - D> Type=file;Perm=r;Unique=keVO1+1G4; file4 - S> 226 MLSD completed - C> MLSD test/incoming - S> 150 BINARY connection open for MLSD test/incoming - D> Type=cdir;Perm=cpmel;Unique=keVO1+7G4; test/incoming - D> Type=pdir;Perm=el;Unique=keVO1+ZF4; .. - D> Type=file;Perm=awdrf;Unique=keVO1+EH4; bar - D> Type=file;Perm=awdrf;Unique=keVO1+LH4; - D> Type=file;Perm=rf;Unique=keVO1+1G4; file5 - D> Type=file;Perm=rf;Unique=keVO1+1G4; file6 - D> Type=dir;Perm=cpmdelf;Unique=keVO1+!s2; empty - S> 226 MLSD completed - - For the purposes of this example the fact set requested has been - modified to delete the "size" and "modify" facts, and add the - "unique" fact. First, facts about a filename have been obtained via - MLST. Note that no fully qualified path name was given this time. - That was because the server was unable to determine that information. - Then having determined that the filename represents a directory, that - directory has been listed. That listing also shows no fully - qualified path name, for the same reason, thus has but a single - "type=cdir" line. This directory (which was created especially for - the purpose) contains several interesting files. There are some with - OS dependent file types, several sub-directories, and several - ordinary files. - - - - -Elz & Hethmon [Expires April 2000] [Page 45] - - -Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 - - - Not much can be said here about the OS dependent file types, as none - of the information shown there should be treated as any more than - possibilities. It can be seen that the OS type of the server is - "unix" though, which is one of the OS types in the IANA registry of - Operating System names. - - Of the three directories listed, "no-exec" has no permission granted - to this user to access at all. From the "Unique" fact values, it can - be determined that "promiscuous" and "incoming" in fact represent the - same directory. Its permissions show that the connected user has - permission to do essentially anything other than to delete the - directory. That directory was later listed. It happens that the - directory can not be deleted because it is not empty. - - Of the normal files listed, two contain spaces in their names. The - file called " leading space" actually contains two spaces in its - name, one before the "l" and one between the "g" and the "s". The - two spaces that separate the facts from the visible part of the path - name make that clear. The file "writable" has the "a" and "w" - permission bits set, and consequently the connected user should be - able to STOR or APPE to that file. - - The other four file names, "file1", "file2", "file3", and "file4" all - represent the same underlying file, as can be seen from the values of - the "unique" facts of each. It happens that "file1" and "file2" are - Unix "hard" links, and that "file3" and "file4" are "soft" or - "symbolic" links to the first two. None of that information is - available via standard MLST facts, it is sufficient for the purposes - of FTP to note that all represent the same file, and that the same - data would be fetched no matter which of them was retrieved, and that - all would be simultaneously modified were data stored in any. - - Finally, the sub-directory "incoming" is listed. Since "promiscuous" - is the same directory there would be no point listing it as well. In - that directory, the files "file5" and "file6" represent still more - names for the "file1" file we have seen before. Notice the entry - between that for "bar" and "file5". Though it is not possible to - easily represent it in this document, that shows a file with a name - comprising exactly three spaces (" "). A client will have no - difficulty determining that name from the output presented to it - however. The directory "empty" is, as its name implies, empty, - though that is not shown here. It can, however, be deleted, as can - file "bar" and the file whose name is three spaces. All the files - that reside in this directory can be renamed. This is a consequence - of the UNIX semantics of the directory that contains them being - modifiable. - - - - - -Elz & Hethmon [Expires April 2000] [Page 46] - - -Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 - - -8.7.5. More accurate time information - - C> MLst file1 - S> 250- Listing file1 - S> Type=file;Modify=19990929003355.237; file1 - S> 250 End - - In this example, the server-FTP is indicating that "file1" was last - modified 237 milliseconds after 00:33:55 UTC on the 29th of - September, 1999. - -8.7.6. A different server - - C> MLST - S> 250-Begin - S> type=dir;unique=AQkAAAAAAAABCAAA; / - S> 250 End. - C> MLSD . - S> 150 Opening ASCII mode data connection for MLS. - D> type=cdir;unique=AQkAAAAAAAABCAAA; / - D> type=dir;unique=AQkAAAAAAAABEAAA; bin - D> type=dir;unique=AQkAAAAAAAABGAAA; etc - D> type=dir;unique=AQkAAAAAAAAB8AwA; halflife - D> type=dir;unique=AQkAAAAAAAABoAAA; incoming - D> type=dir;unique=AQkAAAAAAAABIAAA; lib - D> type=dir;unique=AQkAAAAAAAABWAEA; linux - D> type=dir;unique=AQkAAAAAAAABKAEA; ncftpd - D> type=dir;unique=AQkAAAAAAAABGAEA; outbox - D> type=dir;unique=AQkAAAAAAAABuAAA; quake2 - D> type=dir;unique=AQkAAAAAAAABQAEA; winstuff - S> 226 Listing completed. - C> MLSD linux - S> 150 Opening ASCII mode data connection for MLS. - D> type=cdir;unique=AQkAAAAAAAABWAEA; /linux - D> type=pdir;unique=AQkAAAAAAAABCAAA; / - D> type=dir;unique=AQkAAAAAAAABeAEA; firewall - D> type=file;size=12;unique=AQkAAAAAAAACWAEA; helo_world - D> type=dir;unique=AQkAAAAAAAABYAEA; kernel - D> type=dir;unique=AQkAAAAAAAABmAEA; scripts - D> type=dir;unique=AQkAAAAAAAABkAEA; security - S> 226 Listing completed. - C> MLSD linux/kernel - S> 150 Opening ASCII mode data connection for MLS. - D> type=cdir;unique=AQkAAAAAAAABYAEA; /linux/kernel - D> type=pdir;unique=AQkAAAAAAAABWAEA; /linux - D> type=file;size=6704;unique=AQkAAAAAAAADYAEA; k.config - D> type=file;size=7269221;unique=AQkAAAAAAAACYAEA; linux-2.0.36.tar.gz - D> type=file;size=12514594;unique=AQkAAAAAAAAEYAEA; linux-2.1.130.tar.gz - - - -Elz & Hethmon [Expires April 2000] [Page 47] - - -Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 - - - S> 226 Listing completed. - - Note that this server returns its "unique" fact value in quite a - different format. It also returns fully qualified path names for the - "pdir" entry. - -8.7.7. Some IANA files - - C> MLSD . - S> 150 BINARY connection open for MLSD . - D> Type=cdir;Modify=19990219183438; /iana/assignments - D> Type=pdir;Modify=19990112030453; .. - D> Type=dir;Modify=19990219073522; media-types - D> Type=dir;Modify=19990112033515; character-set-info - D> Type=dir;Modify=19990112033529; languages - D> Type=file;Size=44242;Modify=19990217230400; character-sets - D> Type=file;Size=1947;Modify=19990209215600; operating-system-names - S> 226 MLSD completed - C> MLSD media-types - S> 150 BINARY connection open for MLSD media-types - D> Type=cdir;Modify=19990219073522; media-types - D> Type=cdir;Modify=19990219073522; /iana/assignments/media-types - D> Type=pdir;Modify=19990219183438; .. - D> Type=dir;Modify=19990112033045; text - D> Type=dir;Modify=19990219183442; image - D> Type=dir;Modify=19990112033216; multipart - D> Type=dir;Modify=19990112033254; video - D> Type=file;Size=30249;Modify=19990218032700; media-types - S> 226 MLSD completed - C> MLSD character-set-info - S> 150 BINARY connection open for MLSD character-set-info - D> Type=cdir;Modify=19990112033515; character-set-info - D> Type=cdir;Modify=19990112033515; /iana/assignments/character-set-info - D> Type=pdir;Modify=19990219183438; .. - D> Type=file;Size=1234;Modify=19980903020400; windows-1251 - D> Type=file;Size=4557;Modify=19980922001400; tis-620 - D> Type=file;Size=801;Modify=19970324130000; ibm775 - D> Type=file;Size=552;Modify=19970320130000; ibm866 - D> Type=file;Size=922;Modify=19960505140000; windows-1258 - S> 226 MLSD completed - C> MLSD languages - S> 150 BINARY connection open for MLSD languages - D> Type=cdir;Modify=19990112033529; languages - D> Type=cdir;Modify=19990112033529; /iana/assignments/languages - D> Type=pdir;Modify=19990219183438; .. - D> Type=file;Size=2391;Modify=19980309130000; default - D> Type=file;Size=943;Modify=19980309130000; tags - D> Type=file;Size=870;Modify=19971026130000; navajo - - - -Elz & Hethmon [Expires April 2000] [Page 48] - - -Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 - - - D> Type=file;Size=699;Modify=19950911140000; no-bok - S> 226 MLSD completed - C> PWD - S> 257 "/iana/assignments" is current directory. - - This example shows some of the IANA maintained files that are - relevant for this specification in MLSD format. Note that these - listings have been edited by deleting many entries, the actual - listings are much longer. - -8.7.8. A stress test of case (in)dependence - - The following example is intended to make clear some cases where case - dependent strings are permitted in the MLSx commands, and where case - independent strings are required. - - C> MlsD . - S> 150 BINARY connection open for MLSD . - D> Type=pdir;Modify=19990929011228;Perm=el;Unique=keVO1+ZF4; .. - D> Type=file;Size=4096;Modify=19990929011440;Perm=r;Unique=keVO1+Bd8; FILE2 - D> Type=file;Size=4096;Modify=19990929011440;Perm=r;Unique=keVO1+aG8; file3 - D> Type=file;Size=4096;Modify=19990929011440;Perm=r;Unique=keVO1+ag8; FILE3 - D> Type=file;Size=4096;Modify=19990929011440;Perm=r;Unique=keVO1+bD8; file1 - D> Type=file;Size=4096;Modify=19990929011440;Perm=r;Unique=keVO1+bD8; file2 - D> Type=file;Size=4096;Modify=19990929011440;Perm=r;Unique=keVO1+Ag8; File3 - D> Type=file;Size=4096;Modify=19990929011440;Perm=r;Unique=keVO1+bD8; File1 - D> Type=file;Size=4096;Modify=19990929011440;Perm=r;Unique=keVO1+Bd8; File2 - D> Type=file;Size=4096;Modify=19990929011440;Perm=r;Unique=keVO1+bd8; FILE1 - S> 226 MLSD completed - - Note first that the "MLSD" command, shown here as "MlsD" is case - independent. Clients may issue this command in any case, or - combination of cases, they desire. This is the case for all FTP - commands. - - Next, notice the labels of the facts. These are also case - independent strings, Server-FTP is permitted to return them in any - case they desire. User-FTP must be prepared to deal with any case, - though it may do this by mapping the labels to a common case if - desired. - - Then, notice that there are nine objects of "type" file returned. In - a case independent NVFS these would represent three different file - names, "file1", "file2", and "file3". With a case dependent NVFS all - nine represent different file names. Either is possible, server-FTPs - may implement a case dependent or a case independent NVFS. User-FTPs - must allow for case dependent selection of files to manipulate on the - server. - - - -Elz & Hethmon [Expires April 2000] [Page 49] - - -Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 - - - Lastly, notice that the value of the "unique" fact is case dependent. - In the example shown, "file1", "File1", and "file2" all have the same - "unique" fact value "keVO1+bD8", and thus all represent the same - underlying file. On the other hand, "FILE1" has a different "unique" - fact value ("keVO1+bd8") and hence represents a different file. - Similarly, "FILE2" and "File2" are two names for the same underlying - file, whereas "file3", "File3" and "FILE3" all represent different - underlying files. - - That the approximate sizes ("size" fact) and last modification times - ("modify" fact) are the same in all cases might be no more than a - coincidence. - - It is not suggested that the operators of server-FTPs create NVFS - which stress the protocols to this extent, however both user and - server implementations must be prepared to deal with such extreme - examples. - -8.8. FEAT response for MLSx - - When responding to the FEAT command, a server-FTP process that - supports MLST, and MLSD, plus internationalization of pathnames, MUST - indicate that this support exists. It does this by including a MLST - feature line. As well as indicating the basic support, the MLST - feature line indicates which MLST facts are available from the - server, and which of those will be returned if no subsequent "OPTS - MLST" command is sent. - - mlst-feat = SP "MLST" [SP factlist] CRLF - factlist = 1*( factname ["*"] ";" ) - - The initial space shown in the mlst-feat response is that required by - the FEAT command, two spaces are not permitted. If no factlist is - given, then the server-FTP process is indicating that it supports - MLST, but implements no facts. Only pathnames can be returned. This - would be a minimal MLST implementation, and useless for most - practical purposes. Where the factlist is present, the factnames - included indicate the facts supported by the server. Where the - optional asterisk appears after a factname, that fact will be - included in MLST format responses, until an "OPTS MLST" is given to - alter the list of facts returned. After that, subsequent FEAT - commands will return the asterisk to show the facts selected by the - most recent "OPTS MLST". - - Note that there is no distinct FEAT output for MLSD. The presence of - the MLST feature indicates that both MLST and MLSD are supported. - - - - - -Elz & Hethmon [Expires April 2000] [Page 50] - - -Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 - - -8.8.1. Examples - - C> Feat - S> 211- Features supported - S> REST STREAM - S> MDTM - S> SIZE - S> TVFS - S> UTF8 - S> MLST Type*;Size*;Modify*;Perm*;Unique*;UNIX.mode;UNIX.chgd;X.hidden; - S> 211 End - - Aside from some features irrelevant here, this server indicates that - it supports MLST including several, but not all, standard facts, all - of which it will send by default. It also supports two OS dependent - facts, and one locally defined fact. The latter three must be - requested expressly by the client for this server to supply them. - - C> Feat - S> 211-Extensions supported: - S> CLNT - S> MDTM - S> MLST type*;size*;modify*;UNIX.mode*;UNIX.owner;UNIX.group;unique; - S> PASV - S> REST STREAM - S> SIZE - S> TVFS - S> Compliance Level: 19981201 (IETF mlst-05) - S> 211 End. - - Again, in addition to some irrelevant features here, this server - indicates that it supports MLST, four of the standard facts, one of - which ("unique") is not enabled by default, and several OS dependent - facts, one of which is provided by the server by default. This - server actually supported more OS dependent facts. Others were - deleted for the purposes of this document to comply with document - formatting restrictions. - -8.9. OPTS parameters for MLST - - For the MLSx commands, the Client-FTP may specify a list of facts it - wishes to be returned in all subsequent MLSx commands until another - OPTS MLST command is sent. The format is specified by: - - - - - - - - -Elz & Hethmon [Expires April 2000] [Page 51] - - -Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 - - - mlst-opts = "OPTS" SP "MLST" - [ SP 1*( factname ";" ) ] - - By sending the "OPTS MLST" command, the client requests the server to - include only the facts listed as arguments to the command in - subsequent output from MLSx commands. Facts not included in the - "OPTS MLST" command MUST NOT be returned by the server. Facts that - are included should be returned for each entry returned from the MLSx - command where they meaningfully apply. Facts requested that are not - supported, or which are inappropriate to the file or directory being - listed should simply be omitted from the MLSx output. This is not an - error. Note that where no factname arguments are present, the client - is requesting that only the file names be returned. In this case, - and in any other case where no facts are included in the result, the - space that separates the fact names and their values from the file - name is still required. That is, the first character of the output - line will be a space, (or two characters will be spaces when the line - is returned over the control connection,) and the file name will - start immediately thereafter. - - Clients should note that generating values for some facts can be - possible, but very expensive, for some servers. It is generally - acceptable to retrieve any of the facts that the server offers as its - default set before any "OPTS MLST" command has been given, however - clients should use particular caution before requesting any facts not - in that set. That is, while other facts may be available from the - server, clients should refrain from requesting such facts unless - there is a particular operational requirement for that particular - information, which ought be more significant than perhaps simply - improving the information displayed to an end user. - - Note, there is no "OPTS MLSD" command, the fact names set with the - "OPTS MLST" command apply to both MLST and MLSD commands. - - Servers are not required to accept "OPTS MLST" commands before - authentication of the user-PI, but may choose to permit them. - -8.9.1. OPTS MLST Response - - The "response-message" from [6] to a successful OPTS MLST command has - the following syntax. - - mlst-opt-resp = "MLST OPTS" [ SP 1*( factname ";" ) ] - - This defines the "response-message" as used in the "opts-good" - message in RFC2389 [6]. - - - - - -Elz & Hethmon [Expires April 2000] [Page 52] - - -Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 - - - The facts named in the response are those which the server will now - include in MLST (and MLSD) response, after the processing of the - "OPTS MLST" command. Any facts from the request not supported by the - server will be omitted from this response message. If no facts will - be included, the list of facts will be empty. Note that the list of - facts returned will be the same as those marked by a trailing - asterisk ("*") in a subsequent FEAT command response. There is no - requirement that the order of the facts returned be the same as that - in which they were requested, or that in which they will be listed in - a FEAT command response, or that in which facts are returned in MLST - responses. The fixed string "MLST OPTS" in the response may be - returned in any case, or mixture of cases. - -8.9.2. Examples - - C> Feat - S> 211- Features supported - S> MLST Type*;Size;Modify*;Perm;Unique;UNIX.mode;UNIX.chgd;X.hidden; - S> 211 End - C> OptS Mlst Type;UNIX.mode;Perm; - S> 201 MLST OPTS Type;Perm;UNIX.mode; - C> Feat - S> 211- Features supported - S> MLST Type*;Size;Modify;Perm*;Unique;UNIX.mode*;UNIX.chgd;X.hidden; - S> 211 End - C> opts MLst lang;type;charset;create; - S> 201 MLST OPTS Type; - C> Feat - S> 211- Features supported - S> MLST Type*;Size;Modify;Perm;Unique;UNIX.mode;UNIX.chgd;X.hidden; - S> 211 End - C> OPTS mlst size;frogs; - S> 201 MLST OPTS Size; - C> Feat - S> 211- Features supported - S> MLST Type;Size*;Modify;Perm;Unique;UNIX.mode;UNIX.chgd;X.hidden; - S> 211 End - C> opts MLst unique type; - S> 501 Invalid MLST options - C> Feat - S> 211- Features supported - S> MLST Type;Size*;Modify;Perm;Unique;UNIX.mode;UNIX.chgd;X.hidden; - S> 211 End - - For the purposes of this example, features other than MLST have been - deleted from the output to avoid clutter. The example shows the - initial default feature output for MLST. The facts requested are - then changed by the client. The first change shows facts that are - - - -Elz & Hethmon [Expires April 2000] [Page 53] - - -Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 - - - available from the server being selected. Subsequent FEAT output - shows the altered features as being returned. The client then - attempts to select some standard features which the server does not - support. This is not an error, however the server simply ignores the - requests for unsupported features, as the FEAT output that follows - shows. Then, the client attempts to request a non-standard, and - unsupported, feature. The server ignores that, and selects only the - supported features requested. Lastly, the client sends a request - containing a syntax error (spaces cannot appear in the factlist.) The - server-FTP sends an error response and completely ignores the - request, leaving the fact set selected as it had been previously. - - Note that in all cases, except the error response, the response lists - the facts that have been selected. - - C> Feat - S> 211- Features supported - S> MLST Type*;Size*;Modify*;Perm*;Unique*;UNIX.mode;UNIX.chgd;X.hidden; - S> 211 End - C> Opts MLST - S> 201 MLST OPTS - C> Feat - S> 211- Features supported - S> MLST Type;Size;Modify;Perm;Unique;UNIX.mode;UNIX.chgd;X.hidden; - S> 211 End - C> MLst tmp - S> 250- Listing tmp - S> /tmp - S> 250 End - C> OPTS mlst unique;size; - S> 201 MLST OPTS Size;Unique; - C> MLst tmp - S> 250- Listing tmp - S> Unique=keVO1+YZ5; /tmp - S> 250 End - C> OPTS mlst unique;type;modify; - S> 201 MLST OPTS Type;Modify;Unique; - C> MLst tmp - S> 250- Listing tmp - S> Type=dir;Modify=19990930152225;Unique=keVO1+YZ5; /tmp - S> 250 End - C> OPTS mlst fish;cakes; - S> 201 MLST OPTS - C> MLst tmp - S> 250- Listing tmp - S> /tmp - S> 250 End - C> OptS Mlst Modify;Unique; - - - -Elz & Hethmon [Expires April 2000] [Page 54] - - -Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 - - - S> 201 MLST OPTS Modify;Unique; - C> MLst tmp - S> 250- Listing tmp - S> Modify=19990930152225;Unique=keVO1+YZ5; /tmp - S> 250 End - C> opts MLst fish cakes; - S> 501 Invalid MLST options - C> MLst tmp - S> 250- Listing tmp - S> Modify=19990930152225;Unique=keVO1+YZ5; /tmp - S> 250 End - - This example shows the effect of changing the facts requested upon - subsequent MLST commands. Notice that a syntax error leaves the set - of selected facts unchanged. Also notice exactly two spaces - preceding the pathname when no facts were selected, either - deliberately, or because none of the facts requested were available. - -9. Impact On Other FTP Commands - - Along with the introduction of MLST, traditional FTP commands must be - extended to allow for the use of more than US-ASCII or EBCDIC - character sets. In general, the support of MLST requires support for - arbitrary character sets wherever filenames and directory names are - allowed. This applies equally to both arguments given to the - following commands and to the replies from them, as appropriate. - - CWD - RETR - STOR - STOU - APPE - RNFR - RNTO - DELE - RMD - MKD - PWD - STAT - - The arguments to all of these commands should be processed the same - way that MLST commands and responses are processed with respect to - handling embedded spaces, CRs and NULs. See section 2.2. - - - - - - - - -Elz & Hethmon [Expires April 2000] [Page 55] - - -Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 - - -10. Character sets and Internationalization - - FTP commands are protocol elements, and are always expressed in - ASCII. FTP responses are composed of the numeric code, which is a - protocol element, and a message, which is often expected to convey - information to the user. It is not expected that users normally - interact directly with the protocol elements, rather the user FTP- - process constructs the commands, and interprets the results, in the - manner best suited for the particular user. Explanatory text in - responses generally has no particular meaning to the protocol. The - numeric codes provide all necessary information. Server-PIs are free - to provide the text in any language that can be adequately - represented in ASCII, or where an alternative language and - representation has been negotiated (see [7]) in that language and - representation. - - Pathnames are expected to be encoded in UTF-8 allowing essentially - any character to be represented in a pathname. Meaningful pathnames - are defined by the server NVFS. - - No restrictions at all are placed upon the contents of files - transferred using the FTP protocols. Unless the "media-type" fact is - provided in a MLSx response nor is any advice given here which would - allow determining the content type. That information is assumed to - be obtained via other means. - -11. IANA Considerations - - This specification makes use of some lists of values currently - maintained by the IANA, and creates two new lists for the IANA to - maintain. It does not add any values to any existing registries. - - The existing IANA registries used by this specification are modified - using mechanisms specified elsewhere. - -11.1. The OS specific fact registry - - A registry of OS specific fact names shall be maintained by the IANA. - The OS names for the OS portion of the fact name must be taken from - the IANA's list of registered OS names. To add a fact name to this - OS specific registry of OS specific facts, an applicant must send to - the IANA a request, in which is specified the OS name, the OS - specific fact name, a definition of the syntax of the fact value, - which must conform to the syntax of a token as given in this - document, and a specification of the semantics to be associated with - the particular fact and its values. Upon receipt of such an - application, and if the combination of OS name and OS specific fact - name has not been previously defined, the IANA will add the - - - -Elz & Hethmon [Expires April 2000] [Page 56] - - -Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 - - - specification to the registry. - - Any examples of OS specific facts found in this document are to be - treated as examples of possible OS specific facts, and do not form a - part of the IANA's registry merely because of being included in this - document. - -11.2. The OS specific filetype registry - - A registry of OS specific file types shall be maintained by the IANA. - The OS names for the OS portion of the fact name must be taken from - the IANA's list of registered OS names. To add a file type to this - OS specific registry of OS specific file types, an applicant must - send to the IANA a request, in which is specified the OS name, the OS - specific file type, a definition of the syntax of the fact value, - which must conform to the syntax of a token as given in this - document, and a specification of the semantics to be associated with - the particular fact and its values. Upon receipt of such an - application, and if the combination of OS name and OS specific file - type has not been previously defined, the IANA will add the - specification to the registry. - - Any examples of OS specific file types found in this document are to - be treated as potential OS specific file types only, and do not form - a part of the IANA's registry merely because of being included in - this document. - -12. Security Considerations - - This memo does not directly concern security. It is not believed - that any of the mechanisms documented here impact in any particular - way upon the security of FTP. - - Implementing the SIZE command, and perhaps some of the facts of the - MDLx commands, may impose a considerable load on the server, which - could lead to denial of service attacks. Servers have, however, - implemented this for many years, without significant reported - difficulties. - - With the introduction of virtual hosts to FTP, and the possible - accompanying multiple authentication environments, server - implementors will need to take some care to ensure that integrity is - maintained. - - The FEAT and OPTS commands may be issued before the FTP - authentication has occurred [6]. This allows unauthenticated clients - to determine which of the features defined here are supported, and to - negotiate the fact list for MLSx output. No actual MLSx commands may - - - -Elz & Hethmon [Expires April 2000] [Page 57] - - -Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 - - - be issued however, and no problems with permitting the selection of - the format prior to authentication are foreseen. - - A general discussion of issues related to the security of FTP can be - found in [14]. - -13. References - - [1] Coded Character Set--7-bit American Standard Code for Information - Interchange, ANSI X3.4-1986. - - [2] Yergeau, F., "UTF-8, a transformation format of Unicode and ISO - 10646", RFC 2044, October 1996. - - [3] Postel, J., Reynolds, J., "File Transfer Protocol (FTP)", - STD 9, RFC 959, October 1985 - - [4] Bradner, S., "Key words for use in RFCs to Indicate - Requirement Levels", BCP 14, RFC 2119, March 1997 - - [5] Crocker, D., Overell, P., "Augmented BNF for Syntax - Specifications: ABNF", RFC 2234, November 1997 - - [6] Hethmon, P., Elz, R., "Feature negotiation mechanism for the - File Transfer Protocol", RFC 2389, August 1998 - - [7] Curtin, W., "Internationalization of the File Transfer Protocol", - RFC 2640, July 1999 - - [8] Postel, J., Reynolds, J., "Telnet protocol Specification" - STD 8, RFC 854, May 1983 - - [9] Braden, R,. "Requirements for Internet Hosts -- Application - and Support", STD 3, RFC 1123, October 1989 - - [10] Mockapetris, P., "Domain Names - Concepts and Facilities" - STD 13, RFC 1034, November 1987 - - [11] ISO/IEC 10646-1:1993 "Universal multiple-octet coded character set - (UCS) -- Part 1: Architecture and basic multilingual plane", - International Standard -- Information Technology, 1993 - - [12] Internet Assigned Numbers Authority. http://www.iana.org - Email: iana@iana.org. - - [13] Alvestrand, H., "Tags for the Identification of Languages" - RFC 1766, March 1995 - - - - -Elz & Hethmon [Expires April 2000] [Page 58] - - -Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 - - - [14] Allman, M., Ostermann, S., "FTP Security Considerations" - RFC 2577, May 1999 - -Acknowledgments - - This document is a product of the FTPEXT working group of the IETF. - - The following people are among those who have contributed to this - document: - - Alex Belits - D. J. Bernstein - Dave Cridland - Martin J. Duerst - Mike Gleason - Mark Harris - Alun Jones - James Matthews - Luke Mewburn - Jan Mikkelsen - Keith Moore - Buz Owen - Mark Symons - Stephen Tihor - and the entire FTPEXT working group of the IETF. - - Apologies are offered to any inadvertently omitted. - - Bernhard Rosenkraenzer suggested the HOST command, and initially - described it. - - The description of the modifications to the REST command and the MDTM - and SIZE commands comes from a set of modifications suggested for - RFC959 by Rick Adams in 1989. A draft containing just those - commands, edited by David Borman, has been merged with this document. - - Mike Gleason provided access to the FTP server used in some of the - examples. - - All of the examples in this document are taken from actual - client/server exchanges, though some have been edited for brevity, or - to meet document formatting requirements. - - - - - - - - - -Elz & Hethmon [Expires April 2000] [Page 59] - - -Internet Draft draft-ietf-ftpext-mlst-08.txt October 1999 - - -Copyright - - This document is in the public domain. Any and all copyright - protection that might apply in any jurisdiction is expressly - disclaimed. - -Editors' Addresses - - Robert Elz - University of Melbourne - Department of Computer Science - Parkville, Vic 3052 - Australia - - Email: kre@munnari.OZ.AU - - - Paul Hethmon - Hethmon Brothers - 2305 Chukar Road - Knoxville, TN 37923 USA - - Phone: +1 423 690 8990 - Email: phethmon@hethmon.com - - - - - - - - - - - - - - - - - - - - - - - - - - - -Elz & Hethmon [Expires April 2000] [Page 60] diff --git a/doc/rfc1508.txt b/doc/rfc1508.txt deleted file mode 100644 index 132b855e0..000000000 --- a/doc/rfc1508.txt +++ /dev/null @@ -1,2747 +0,0 @@ - - - - - - -Network Working Group J. Linn -Request for Comments: 1508 Geer Zolot Associates - September 1993 - - - Generic Security Service Application Program Interface - -Status of this Memo - - This RFC specifies an Internet standards track protocol for the - Internet community, and requests discussion and suggestions for - improvements. Please refer to the current edition of the "Internet - Official Protocol Standards" for the standardization state and status - of this protocol. Distribution of this memo is unlimited. - -Abstract - - This Generic Security Service Application Program Interface (GSS-API) - definition provides security services to callers in a generic - fashion, supportable with a range of underlying mechanisms and - technologies and hence allowing source-level portability of - applications to different environments. This specification defines - GSS-API services and primitives at a level independent of underlying - mechanism and programming language environment, and is to be - complemented by other, related specifications: - - documents defining specific parameter bindings for particular - language environments - - documents defining token formats, protocols, and procedures to - be implemented in order to realize GSS-API services atop - particular security mechanisms - -Table of Contents - - 1. GSS-API Characteristics and Concepts ....................... 2 - 1.1. GSS-API Constructs ....................................... 5 - 1.1.1. Credentials ........................................... 5 - 1.1.2. Tokens ................................................ 6 - 1.1.3. Security Contexts ..................................... 7 - 1.1.4. Mechanism Types ....................................... 8 - 1.1.5. Naming ................................................ 9 - 1.1.6. Channel Bindings ...................................... 10 - 1.2. GSS-API Features and Issues ............................. 11 - 1.2.1. Status Reporting ...................................... 11 - 1.2.2. Per-Message Security Service Availability ............. 12 - 1.2.3. Per-Message Replay Detection and Sequencing ........... 13 - 1.2.4. Quality of Protection ................................. 15 - - - -Linn [Page 1] - -RFC 1508 Generic Security Interface September 1993 - - - 2. Interface Descriptions ..................................... 15 - 2.1. Credential management calls ............................. 17 - 2.1.1. GSS_Acquire_cred call ................................. 17 - 2.1.2. GSS_Release_cred call ................................. 19 - 2.1.3. GSS_Inquire_cred call ................................. 20 - 2.2. Context-level calls ..................................... 21 - 2.2.1. GSS_Init_sec_context call ............................. 21 - 2.2.2. GSS_Accept_sec_context call ........................... 26 - 2.2.3. GSS_Delete_sec_context call ........................... 29 - 2.2.4. GSS_Process_context_token call ........................ 30 - 2.2.5. GSS_Context_time call ................................. 31 - 2.3. Per-message calls ....................................... 32 - 2.3.1. GSS_Sign call ......................................... 32 - 2.3.2. GSS_Verify call ....................................... 33 - 2.3.3. GSS_Seal call ......................................... 35 - 2.3.4. GSS_Unseal call ....................................... 36 - 2.4. Support calls ........................................... 37 - 2.4.1. GSS_Display_status call ............................... 37 - 2.4.2. GSS_Indicate_mechs call ............................... 38 - 2.4.3. GSS_Compare_name call ................................. 38 - 2.4.4. GSS_Display_name call ................................. 39 - 2.4.5. GSS_Import_name call .................................. 40 - 2.4.6. GSS_Release_name call ................................. 41 - 2.4.7. GSS_Release_buffer call ............................... 41 - 2.4.8. GSS_Release_oid_set call .............................. 42 - 3. Mechanism-Specific Example Scenarios ....................... 42 - 3.1. Kerberos V5, single-TGT ................................. 43 - 3.2. Kerberos V5, double-TGT ................................. 43 - 3.3. X.509 Authentication Framework .......................... 44 - 4. Related Activities ......................................... 45 - 5. Acknowledgments ............................................ 46 - 6. Security Considerations .................................... 46 - 7. Author's Address ........................................... 46 - Appendix A .................................................... 47 - Appendix B .................................................... 48 - Appendix C .................................................... 49 - -1. GSS-API Characteristics and Concepts - - The operational paradigm in which GSS-API operates is as follows. A - typical GSS-API caller is itself a communications protocol, calling - on GSS-API in order to protect its communications with - authentication, integrity, and/or confidentiality security services. - A GSS-API caller accepts tokens provided to it by its local GSS-API - implementation and transfers the tokens to a peer on a remote system; - that peer passes the received tokens to its local GSS-API - implementation for processing. The security services available - through GSS-API in this fashion are implementable (and have been - - - -Linn [Page 2] - -RFC 1508 Generic Security Interface September 1993 - - - implemented) over a range of underlying mechanisms based on secret- - key and public-key cryptographic technologies. - - The GSS-API separates the operations of initializing a security - context between peers, achieving peer entity authentication (This - security service definition, and other definitions used in this - document, corresponds to that provided in International Standard ISO - 7498-2-1988(E), Security Architecture.) (GSS_Init_sec_context() and - GSS_Accept_sec_context() calls), from the operations of providing - per-message data origin authentication and data integrity protection - (GSS_Sign() and GSS_Verify() calls) for messages subsequently - transferred in conjunction with that context. Per-message GSS_Seal() - and GSS_Unseal() calls provide the data origin authentication and - data integrity services which GSS_Sign() and GSS_Verify() offer, and - also support selection of confidentiality services as a caller - option. Additional calls provide supportive functions to the GSS- - API's users. - - The following paragraphs provide an example illustrating the - dataflows involved in use of the GSS-API by a client and server in a - mechanism-independent fashion, establishing a security context and - transferring a protected message. The example assumes that credential - acquisition has already been completed. The example assumes that the - underlying authentication technology is capable of authenticating a - client to a server using elements carried within a single token, and - of authenticating the server to the client (mutual authentication) - with a single returned token; this assumption holds for presently- - documented CAT mechanisms but is not necessarily true for other - cryptographic technologies and associated protocols. - - The client calls GSS_Init_sec_context() to establish a security - context to the server identified by targ_name, and elects to set the - mutual_req_flag so that mutual authentication is performed in the - course of context establishment. GSS_Init_sec_context() returns an - output_token to be passed to the server, and indicates - GSS_CONTINUE_NEEDED status pending completion of the mutual - authentication sequence. Had mutual_req_flag not been set, the - initial call to GSS_Init_sec_context() would have returned - GSS_COMPLETE status. The client sends the output_token to the server. - - The server passes the received token as the input_token parameter to - GSS_Accept_sec_context(). GSS_Accept_sec_context indicates - GSS_COMPLETE status, provides the client's authenticated identity in - the src_name result, and provides an output_token to be passed to the - client. The server sends the output_token to the client. - - The client passes the received token as the input_token parameter to - a successor call to GSS_Init_sec_context(), which processes data - - - -Linn [Page 3] - -RFC 1508 Generic Security Interface September 1993 - - - included in the token in order to achieve mutual authentication from - the client's viewpoint. This call to GSS_Init_sec_context() returns - GSS_COMPLETE status, indicating successful mutual authentication and - the completion of context establishment for this example. - - The client generates a data message and passes it to GSS_Seal(). - GSS_Seal() performs data origin authentication, data integrity, and - (optionally) confidentiality processing on the message and - encapsulates the result into output_message, indicating GSS_COMPLETE - status. The client sends the output_message to the server. - - The server passes the received message to GSS_Unseal(). GSS_Unseal - inverts the encapsulation performed by GSS_Seal(), deciphers the - message if the optional confidentiality feature was applied, and - validates the data origin authentication and data integrity checking - quantities. GSS_Unseal() indicates successful validation by - returning GSS_COMPLETE status along with the resultant - output_message. - - For purposes of this example, we assume that the server knows by - out-of-band means that this context will have no further use after - one protected message is transferred from client to server. Given - this premise, the server now calls GSS_Delete_sec_context() to flush - context-level information. GSS_Delete_sec_context() returns a - context_token for the server to pass to the client. - - The client passes the returned context_token to - GSS_Process_context_token(), which returns GSS_COMPLETE status after - deleting context-level information at the client system. - - The GSS-API design assumes and addresses several basic goals, - including: - - Mechanism independence: The GSS-API defines an interface to - cryptographically implemented strong authentication and other - security services at a generic level which is independent of - particular underlying mechanisms. For example, GSS-API-provided - services can be implemented by secret-key technologies (e.g., - Kerberos) or public-key approaches (e.g., X.509). - - Protocol environment independence: The GSS-API is independent of - the communications protocol suites with which it is employed, - permitting use in a broad range of protocol environments. In - appropriate environments, an intermediate implementation "veneer" - which is oriented to a particular communication protocol (e.g., - Remote Procedure Call (RPC)) may be interposed between - applications which call that protocol and the GSS-API, thereby - invoking GSS-API facilities in conjunction with that protocol's - - - -Linn [Page 4] - -RFC 1508 Generic Security Interface September 1993 - - - communications invocations. - - Protocol association independence: The GSS-API's security context - construct is independent of communications protocol association - constructs. This characteristic allows a single GSS-API - implementation to be utilized by a variety of invoking protocol - modules on behalf of those modules' calling applications. GSS-API - services can also be invoked directly by applications, wholly - independent of protocol associations. - - Suitability to a range of implementation placements: GSS-API - clients are not constrained to reside within any Trusted Computing - Base (TCB) perimeter defined on a system where the GSS-API is - implemented; security services are specified in a manner suitable - to both intra-TCB and extra-TCB callers. - -1.1. GSS-API Constructs - - This section describes the basic elements comprising the GSS-API. - -1.1.1. Credentials - - Credentials structures provide the prerequisites enabling peers to - establish security contexts with each other. A caller may designate - that its default credential be used for context establishment calls - without presenting an explicit handle to that credential. - Alternately, those GSS-API callers which need to make explicit - selection of particular credentials structures may make references to - those credentials through GSS-API-provided credential handles - ("cred_handles"). - - A single credential structure may be used for initiation of outbound - contexts and acceptance of inbound contexts. Callers needing to - operate in only one of these modes may designate this fact when - credentials are acquired for use, allowing underlying mechanisms to - optimize their processing and storage requirements. The credential - elements defined by a particular mechanism may contain multiple - cryptographic keys, e.g., to enable authentication and message - encryption to be performed with different algorithms. - - A single credential structure may accommodate credential information - associated with multiple underlying mechanisms (mech_types); a - credential structure's contents will vary depending on the set of - mech_types supported by a particular GSS-API implementation. - Commonly, a single mech_type will be used for all security contexts - established by a particular initiator to a particular target; the - primary motivation for supporting credential sets representing - multiple mech_types is to allow initiators on systems which are - - - -Linn [Page 5] - -RFC 1508 Generic Security Interface September 1993 - - - equipped to handle multiple types to initiate contexts to targets on - other systems which can accommodate only a subset of the set - supported at the initiator's system. - - It is the responsibility of underlying system-specific mechanisms and - OS functions below the GSS-API to ensure that the ability to acquire - and use credentials associated with a given identity is constrained - to appropriate processes within a system. This responsibility should - be taken seriously by implementors, as the ability for an entity to - utilize a principal's credentials is equivalent to the entity's - ability to successfully assert that principal's identity. - - Once a set of GSS-API credentials is established, the transferability - of that credentials set to other processes or analogous constructs - within a system is a local matter, not defined by the GSS-API. An - example local policy would be one in which any credentials received - as a result of login to a given user account, or of delegation of - rights to that account, are accessible by, or transferable to, - processes running under that account. - - The credential establishment process (particularly when performed on - behalf of users rather than server processes) is likely to require - access to passwords or other quantities which should be protected - locally and exposed for the shortest time possible. As a result, it - will often be appropriate for preliminary credential establishment to - be performed through local means at user login time, with the - result(s) cached for subsequent reference. These preliminary - credentials would be set aside (in a system-specific fashion) for - subsequent use, either: - - to be accessed by an invocation of the GSS-API GSS_Acquire_cred() - call, returning an explicit handle to reference that credential - - as the default credentials installed on behalf of a process - -1.1.2. Tokens - - Tokens are data elements transferred between GSS-API callers, and are - divided into two classes. Context-level tokens are exchanged in order - to establish and manage a security context between peers. Per-message - tokens are exchanged in conjunction with an established context to - provide protective security services for corresponding data messages. - The internal contents of both classes of tokens are specific to the - particular underlying mechanism used to support the GSS-API; Appendix - B of this document provides a uniform recommendation for designers of - GSS-API support mechanisms, encapsulating mechanism-specific - information along with a globally-interpretable mechanism identifier. - - - - -Linn [Page 6] - -RFC 1508 Generic Security Interface September 1993 - - - Tokens are opaque from the viewpoint of GSS-API callers. They are - generated within the GSS-API implementation at an end system, - provided to a GSS-API caller to be transferred to the peer GSS-API - caller at a remote end system, and processed by the GSS-API - implementation at that remote end system. Tokens may be output by - GSS-API primitives (and are to be transferred to GSS-API peers) - independent of the status indications which those primitives - indicate. Token transfer may take place in an in-band manner, - integrated into the same protocol stream used by the GSS-API callers - for other data transfers, or in an out-of-band manner across a - logically separate channel. - - Development of GSS-API support primitives based on a particular - underlying cryptographic technique and protocol does not necessarily - imply that GSS-API callers invoking that GSS-API mechanism type will - be able to interoperate with peers invoking the same technique and - protocol outside the GSS-API paradigm. For example, the format of - GSS-API tokens defined in conjunction with a particular mechanism, - and the techniques used to integrate those tokens into callers' - protocols, may not be the same as those used by non-GSS-API callers - of the same underlying technique. - -1.1.3. Security Contexts - - Security contexts are established between peers, using credentials - established locally in conjunction with each peer or received by - peers via delegation. Multiple contexts may exist simultaneously - between a pair of peers, using the same or different sets of - credentials. Coexistence of multiple contexts using different - credentials allows graceful rollover when credentials expire. - Distinction among multiple contexts based on the same credentials - serves applications by distinguishing different message streams in a - security sense. - - The GSS-API is independent of underlying protocols and addressing - structure, and depends on its callers to transport GSS-API-provided - data elements. As a result of these factors, it is a caller - responsibility to parse communicated messages, separating GSS-API- - related data elements from caller-provided data. The GSS-API is - independent of connection vs. connectionless orientation of the - underlying communications service. - - No correlation between security context and communications protocol - association is dictated. (The optional channel binding facility, - discussed in Section 1.1.6 of this document, represents an - intentional exception to this rule, supporting additional protection - features within GSS-API supporting mechanisms.) This separation - allows the GSS-API to be used in a wide range of communications - - - -Linn [Page 7] - -RFC 1508 Generic Security Interface September 1993 - - - environments, and also simplifies the calling sequences of the - individual calls. In many cases (depending on underlying security - protocol, associated mechanism, and availability of cached - information), the state information required for context setup can be - sent concurrently with initial signed user data, without interposing - additional message exchanges. - -1.1.4. Mechanism Types - - In order to successfully establish a security context with a target - peer, it is necessary to identify an appropriate underlying mechanism - type (mech_type) which both initiator and target peers support. The - definition of a mechanism embodies not only the use of a particular - cryptographic technology (or a hybrid or choice among alternative - cryptographic technologies), but also definition of the syntax and - semantics of data element exchanges which that mechanism will employ - in order to support security services. - - It is recommended that callers initiating contexts specify the - "default" mech_type value, allowing system-specific functions within - or invoked by the GSS-API implementation to select the appropriate - mech_type, but callers may direct that a particular mech_type be - employed when necessary. - - The means for identifying a shared mech_type to establish a security - context with a peer will vary in different environments and - circumstances; examples include (but are not limited to): - - use of a fixed mech_type, defined by configuration, within an - environment - - syntactic convention on a target-specific basis, through - examination of a target's name - - lookup of a target's name in a naming service or other database in - order to identify mech_types supported by that target - - explicit negotiation between GSS-API callers in advance of - security context setup - - When transferred between GSS-API peers, mech_type specifiers (per - Appendix B, represented as Object Identifiers (OIDs)) serve to - qualify the interpretation of associated tokens. (The structure and - encoding of Object Identifiers is defined in ISO/IEC 8824, - "Specification of Abstract Syntax Notation One (ASN.1)" and in - ISO/IEC 8825, "Specification of Basic Encoding Rules for Abstract - Syntax Notation One (ASN.1)".) Use of hierarchically structured OIDs - serves to preclude ambiguous interpretation of mech_type specifiers. - - - -Linn [Page 8] - -RFC 1508 Generic Security Interface September 1993 - - - The OID representing the DASS MechType, for example, is - 1.3.12.2.1011.7.5. - -1.1.5. Naming - - The GSS-API avoids prescription of naming structures, treating the - names transferred across the interface in order to initiate and - accept security contexts as opaque octet string quantities. This - approach supports the GSS-API's goal of implementability atop a range - of underlying security mechanisms, recognizing the fact that - different mechanisms process and authenticate names which are - presented in different forms. Generalized services offering - translation functions among arbitrary sets of naming environments are - outside the scope of the GSS-API; availability and use of local - conversion functions to translate among the naming formats supported - within a given end system is anticipated. - - Two distinct classes of name representations are used in conjunction - with different GSS-API parameters: - - a printable form (denoted by OCTET STRING), for acceptance from - and presentation to users; printable name forms are accompanied by - OID tags identifying the namespace to which they correspond - - an internal form (denoted by INTERNAL NAME), opaque to callers and - defined by individual GSS-API implementations; GSS-API - implementations supporting multiple namespace types are - responsible for maintaining internal tags to disambiguate the - interpretation of particular names - - Tagging of printable names allows GSS-API callers and underlying - GSS-API mechanisms to disambiguate name types and to determine - whether an associated name's type is one which they are capable of - processing, avoiding aliasing problems which could result from - misinterpreting a name of one type as a name of another type. - - In addition to providing means for names to be tagged with types, - this specification defines primitives to support a level of naming - environment independence for certain calling applications. To provide - basic services oriented towards the requirements of callers which - need not themselves interpret the internal syntax and semantics of - names, GSS-API calls for name comparison (GSS_Compare_name()), - human-readable display (GSS_Display_name()), input conversion - (GSS_Import_name()), and internal name deallocation - (GSS_Release_name()) functions are defined. (It is anticipated that - these proposed GSS-API calls will be implemented in many end systems - based on system-specific name manipulation primitives already extant - within those end systems; inclusion within the GSS-API is intended to - - - -Linn [Page 9] - -RFC 1508 Generic Security Interface September 1993 - - - offer GSS-API callers a portable means to perform specific - operations, supportive of authorization and audit requirements, on - authenticated names.) - - GSS_Import_name() implementations can, where appropriate, support - more than one printable syntax corresponding to a given namespace - (e.g., alternative printable representations for X.500 Distinguished - Names), allowing flexibility for their callers to select among - alternative representations. GSS_Display_name() implementations - output a printable syntax selected as appropriate to their - operational environments; this selection is a local matter. Callers - desiring portability across alternative printable syntaxes should - refrain from implementing comparisons based on printable name forms - and should instead use the GSS_Compare_name() call to determine - whether or not one internal-format name matches another. - -1.1.6. Channel Bindings - - The GSS-API accommodates the concept of caller-provided channel - binding ("chan_binding") information, used by GSS-API callers to bind - the establishment of a security context to relevant characteristics - (e.g., addresses, transformed representations of encryption keys) of - the underlying communications channel and of protection mechanisms - applied to that communications channel. Verification by one peer of - chan_binding information provided by the other peer to a context - serves to protect against various active attacks. The caller - initiating a security context must determine the chan_binding values - before making the GSS_Init_sec_context() call, and consistent values - must be provided by both peers to a context. Callers should not - assume that underlying mechanisms provide confidentiality protection - for channel binding information. - - Use or non-use of the GSS-API channel binding facility is a caller - option, and GSS-API supporting mechanisms can support operation in an - environment where NULL channel bindings are presented. When non-NULL - channel bindings are used, certain mechanisms will offer enhanced - security value by interpreting the bindings' content (rather than - simply representing those bindings, or signatures computed on them, - within tokens) and will therefore depend on presentation of specific - data in a defined format. To this end, agreements among mechanism - implementors are defining conventional interpretations for the - contents of channel binding arguments, including address specifiers - (with content dependent on communications protocol environment) for - context initiators and acceptors. (These conventions are being - incorporated into related documents.) In order for GSS-API callers to - be portable across multiple mechanisms and achieve the full security - functionality available from each mechanism, it is strongly - recommended that GSS-API callers provide channel bindings consistent - - - -Linn [Page 10] - -RFC 1508 Generic Security Interface September 1993 - - - with these conventions and those of the networking environment in - which they operate. - -1.2. GSS-API Features and Issues - - This section describes aspects of GSS-API operations, of the security - services which the GSS-API provides, and provides commentary on - design issues. - -1.2.1. Status Reporting - - Each GSS-API call provides two status return values. Major_status - values provide a mechanism-independent indication of call status - (e.g., GSS_COMPLETE, GSS_FAILURE, GSS_CONTINUE_NEEDED), sufficient to - drive normal control flow within the caller in a generic fashion. - Table 1 summarizes the defined major_status return codes in tabular - fashion. - - Table 1: GSS-API Major Status Codes - - FATAL ERROR CODES - - GSS_BAD_BINDINGS channel binding mismatch - GSS_BAD_MECH unsupported mechanism requested - GSS_BAD_NAME invalid name provided - GSS_BAD_NAMETYPE name of unsupported type provided - GSS_BAD_STATUS invalid input status selector - GSS_BAD_SIG token had invalid signature - GSS_CONTEXT_EXPIRED specified security context expired - GSS_CREDENTIALS_EXPIRED expired credentials detected - GSS_DEFECTIVE_CREDENTIAL defective credential detected - GSS_DEFECTIVE_TOKEN defective token detected - GSS_FAILURE failure, unspecified at GSS-API - level - GSS_NO_CONTEXT no valid security context specified - GSS_NO_CRED no valid credentials provided - - INFORMATORY STATUS CODES - - GSS_COMPLETE normal completion - GSS_CONTINUE_NEEDED continuation call to routine - required - GSS_DUPLICATE_TOKEN duplicate per-message token - detected - GSS_OLD_TOKEN timed-out per-message token - detected - GSS_UNSEQ_TOKEN out-of-order per-message token - detected - - - -Linn [Page 11] - -RFC 1508 Generic Security Interface September 1993 - - - Minor_status provides more detailed status information which may - include status codes specific to the underlying security mechanism. - Minor_status values are not specified in this document. - - GSS_CONTINUE_NEEDED major_status returns, and optional message - outputs, are provided in GSS_Init_sec_context() and - GSS_Accept_sec_context() calls so that different mechanisms' - employment of different numbers of messages within their - authentication sequences need not be reflected in separate code paths - within calling applications. Instead, such cases are accomodated with - sequences of continuation calls to GSS_Init_sec_context() and - GSS_Accept_sec_context(). The same mechanism is used to encapsulate - mutual authentication within the GSS-API's context initiation calls. - - For mech_types which require interactions with third-party servers in - order to establish a security context, GSS-API context establishment - calls may block pending completion of such third-party interactions. - On the other hand, no GSS-API calls pend on serialized interactions - with GSS-API peer entities. As a result, local GSS-API status - returns cannot reflect unpredictable or asynchronous exceptions - occurring at remote peers, and reflection of such status information - is a caller responsibility outside the GSS-API. - -1.2.2. Per-Message Security Service Availability - - When a context is established, two flags are returned to indicate the - set of per-message protection security services which will be - available on the context: - - the integ_avail flag indicates whether per-message integrity and - data origin authentication services are available - - the conf_avail flag indicates whether per-message confidentiality - services are available, and will never be returned TRUE unless the - integ_avail flag is also returned TRUE - - GSS-API callers desiring per-message security services should - check the values of these flags at context establishment time, and - must be aware that a returned FALSE value for integ_avail means - that invocation of GSS_Sign() or GSS_Seal() primitives on the - associated context will apply no cryptographic protection to user - data messages. - - The GSS-API per-message protection service primitives, as the - category name implies, are oriented to operation at the granularity - of protocol data units. They perform cryptographic operations on the - data units, transfer cryptographic control information in tokens, - and, in the case of GSS_Seal(), encapsulate the protected data unit. - - - -Linn [Page 12] - -RFC 1508 Generic Security Interface September 1993 - - - As such, these primitives are not oriented to efficient data - protection for stream-paradigm protocols (e.g., Telnet) if - cryptography must be applied on an octet-by-octet basis. - -1.2.3. Per-Message Replay Detection and Sequencing - - Certain underlying mech_types are expected to offer support for - replay detection and/or sequencing of messages transferred on the - contexts they support. These optionally-selectable protection - features are distinct from replay detection and sequencing features - applied to the context establishment operation itself; the presence - or absence of context-level replay or sequencing features is wholly a - function of the underlying mech_type's capabilities, and is not - selected or omitted as a caller option. - - The caller initiating a context provides flags (replay_det_req_flag - and sequence_req_flag) to specify whether the use of per-message - replay detection and sequencing features is desired on the context - being established. The GSS-API implementation at the initiator system - can determine whether these features are supported (and whether they - are optionally selectable) as a function of mech_type, without need - for bilateral negotiation with the target. When enabled, these - features provide recipients with indicators as a result of GSS-API - processing of incoming messages, identifying whether those messages - were detected as duplicates or out-of-sequence. Detection of such - events does not prevent a suspect message from being provided to a - recipient; the appropriate course of action on a suspect message is a - matter of caller policy. - - The semantics of the replay detection and sequencing services applied - to received messages, as visible across the interface which the GSS- - API provides to its clients, are as follows: - - When replay_det_state is TRUE, the possible major_status returns for - well-formed and correctly signed messages are as follows: - - 1. GSS_COMPLETE indicates that the message was within the window - (of time or sequence space) allowing replay events to be detected, - and that the message was not a replay of a previously-processed - message within that window. - - 2. GSS_DUPLICATE_TOKEN indicates that the signature on the - received message was correct, but that the message was recognized - as a duplicate of a previously-processed message. - - 3. GSS_OLD_TOKEN indicates that the signature on the received - message was correct, but that the message is too old to be checked - for duplication. - - - -Linn [Page 13] - -RFC 1508 Generic Security Interface September 1993 - - - When sequence_state is TRUE, the possible major_status returns for - well-formed and correctly signed messages are as follows: - - 1. GSS_COMPLETE indicates that the message was within the window - (of time or sequence space) allowing replay events to be detected, - and that the message was not a replay of a previously-processed - message within that window. - - 2. GSS_DUPLICATE_TOKEN indicates that the signature on the - received message was correct, but that the message was recognized - as a duplicate of a previously-processed message. - - 3. GSS_OLD_TOKEN indicates that the signature on the received - message was correct, but that the token is too old to be checked - for duplication. - - 4. GSS_UNSEQ_TOKEN indicates that the signature on the received - message was correct, but that it is earlier in a sequenced stream - than a message already processed on the context. [Note: - Mechanisms can be architected to provide a stricter form of - sequencing service, delivering particular messages to recipients - only after all predecessor messages in an ordered stream have been - delivered. This type of support is incompatible with the GSS-API - paradigm in which recipients receive all messages, whether in - order or not, and provide them (one at a time, without intra-GSS- - API message buffering) to GSS-API routines for validation. GSS- - API facilities provide supportive functions, aiding clients to - achieve strict message stream integrity in an efficient manner in - conjunction with sequencing provisions in communications - protocols, but the GSS-API does not offer this level of message - stream integrity service by itself.] - - As the message stream integrity features (especially sequencing) may - interfere with certain applications' intended communications - paradigms, and since support for such features is likely to be - resource intensive, it is highly recommended that mech_types - supporting these features allow them to be activated selectively on - initiator request when a context is established. A context initiator - and target are provided with corresponding indicators - (replay_det_state and sequence_state), signifying whether these - features are active on a given context. - - An example mech_type supporting per-message replay detection could - (when replay_det_state is TRUE) implement the feature as follows: The - underlying mechanism would insert timestamps in data elements output - by GSS_Sign() and GSS_Seal(), and would maintain (within a time- - limited window) a cache (qualified by originator-recipient pair) - identifying received data elements processed by GSS_Verify() and - - - -Linn [Page 14] - -RFC 1508 Generic Security Interface September 1993 - - - GSS_Unseal(). When this feature is active, exception status returns - (GSS_DUPLICATE_TOKEN, GSS_ OLD_TOKEN) will be provided when - GSS_Verify() or GSS_Unseal() is presented with a message which is - either a detected duplicate of a prior message or which is too old to - validate against a cache of recently received messages. - -1.2.4. Quality of Protection - - Some mech_types will provide their users with fine granularity - control over the means used to provide per-message protection, - allowing callers to trade off security processing overhead - dynamically against the protection requirements of particular - messages. A per-message quality-of-protection parameter (analogous to - quality-of-service, or QOS) selects among different QOP options - supported by that mechanism. On context establishment for a multi-QOP - mech_type, context-level data provides the prerequisite data for a - range of protection qualities. - - It is expected that the majority of callers will not wish to exert - explicit mechanism-specific QOP control and will therefore request - selection of a default QOP. Definitions of, and choices among, non- - default QOP values are mechanism-specific, and no ordered sequences - of QOP values can be assumed equivalent across different mechanisms. - Meaningful use of non-default QOP values demands that callers be - familiar with the QOP definitions of an underlying mechanism or - mechanisms, and is therefore a non-portable construct. - -2. Interface Descriptions - - This section describes the GSS-API's service interface, dividing the - set of calls offered into four groups. Credential management calls - are related to the acquisition and release of credentials by - principals. Context-level calls are related to the management of - security contexts between principals. Per-message calls are related - to the protection of individual messages on established security - contexts. Support calls provide ancillary functions useful to GSS-API - callers. Table 2 groups and summarizes the calls in tabular fashion. - - - - - - - - - - - - - - -Linn [Page 15] - -RFC 1508 Generic Security Interface September 1993 - - - Table 2: GSS-API Calls - - CREDENTIAL MANAGEMENT - - GSS_Acquire_cred acquire credentials for use - GSS_Release_cred release credentials after use - GSS_Inquire_cred display information about - credentials - - CONTEXT-LEVEL CALLS - - GSS_Init_sec_context initiate outbound security context - GSS_Accept_sec_context accept inbound security context - GSS_Delete_sec_context flush context when no longer needed - GSS_Process_context_token process received control token on - context - GSS_Context_time indicate validity time remaining on - context - - PER-MESSAGE CALLS - - GSS_Sign apply signature, receive as token - separate from message - GSS_Verify validate signature token along with - message - GSS_Seal sign, optionally encrypt, - encapsulate - GSS_Unseal decapsulate, decrypt if needed, - validate signature - - SUPPORT CALLS - - GSS_Display_status translate status codes to printable - form - GSS_Indicate_mechs indicate mech_types supported on - local system - GSS_Compare_name compare two names for equality - GSS_Display_name translate name to printable form - GSS_Import_name convert printable name to - normalized form - GSS_Release_name free storage of normalized-form - name - GSS_Release_buffer free storage of printable name - GSS_Release_oid_set free storage of OID set object - - - - - - - -Linn [Page 16] - -RFC 1508 Generic Security Interface September 1993 - - -2.1. Credential management calls - - These GSS-API calls provide functions related to the management of - credentials. Their characterization with regard to whether or not - they may block pending exchanges with other network entities (e.g., - directories or authentication servers) depends in part on OS-specific - (extra-GSS-API) issues, so is not specified in this document. - - The GSS_Acquire_cred() call is defined within the GSS-API in support - of application portability, with a particular orientation towards - support of portable server applications. It is recognized that (for - certain systems and mechanisms) credentials for interactive users may - be managed differently from credentials for server processes; in such - environments, it is the GSS-API implementation's responsibility to - distinguish these cases and the procedures for making this - distinction are a local matter. The GSS_Release_cred() call provides - a means for callers to indicate to the GSS-API that use of a - credentials structure is no longer required. The GSS_Inquire_cred() - call allows callers to determine information about a credentials - structure. - -2.1.1. GSS_Acquire_cred call - - Inputs: - - o desired_name INTERNAL NAME, -NULL requests locally-determined - default - - o lifetime_req INTEGER,-in seconds; 0 requests default - - o desired_mechs SET OF OBJECT IDENTIFIER,-empty set requests - system-selected default - - o cred_usage INTEGER-0=INITIATE-AND-ACCEPT, 1=INITIATE-ONLY, - 2=ACCEPT-ONLY - - Outputs: - - o major_status INTEGER, - - o minor_status INTEGER, - - o output_cred_handle OCTET STRING, - - o actual_mechs SET OF OBJECT IDENTIFIER, - - o lifetime_rec INTEGER -in seconds, or reserved value for - INDEFINITE - - - -Linn [Page 17] - -RFC 1508 Generic Security Interface September 1993 - - - Return major_status codes: - - o GSS_COMPLETE indicates that requested credentials were - successfully established, for the duration indicated in - lifetime_rec, suitable for the usage requested in cred_usage, for - the set of mech_types indicated in actual_mechs, and that those - credentials can be referenced for subsequent use with the handle - returned in output_cred_handle. - - o GSS_BAD_MECH indicates that a mech_type unsupported by the GSS-API - implementation type was requested, causing the credential - establishment operation to fail. - - o GSS_BAD_NAMETYPE indicates that the provided desired_name is - uninterpretable or of a type unsupported by the supporting GSS-API - implementation, so no credentials could be established for the - accompanying desired_name. - - o GSS_BAD_NAME indicates that the provided desired_name is - inconsistent in terms of internally-incorporated type specifier - information, so no credentials could be established for the - accompanying desired_name. - - o GSS_FAILURE indicates that credential establishment failed for - reasons unspecified at the GSS-API level, including lack of - authorization to establish and use credentials associated with the - identity named in the input desired_name argument. - - GSS_Acquire_cred() is used to acquire credentials so that a - principal can (as a function of the input cred_usage parameter) - initiate and/or accept security contexts under the identity - represented by the desired_name input argument. On successful - completion, the returned output_cred_handle result provides a handle - for subsequent references to the acquired credentials. Typically, - single-user client processes using only default credentials for - context establishment purposes will have no need to invoke this call. - - A caller may provide the value NULL for desired_name, signifying a - request for credentials corresponding to a default principal - identity. The procedures used by GSS-API implementations to select - the appropriate principal identity in response to this form of - request are local matters. It is possible that multiple pre- - established credentials may exist for the same principal identity - (for example, as a result of multiple user login sessions) when - GSS_Acquire_cred() is called; the means used in such cases to select - a specific credential are local matters. The input lifetime_req - argument to GSS_Acquire_cred() may provide useful information for - local GSS-API implementations to employ in making this disambiguation - - - -Linn [Page 18] - -RFC 1508 Generic Security Interface September 1993 - - - in a manner which will best satisfy a caller's intent. - - The lifetime_rec result indicates the length of time for which the - acquired credentials will be valid, as an offset from the present. A - mechanism may return a reserved value indicating INDEFINITE if no - constraints on credential lifetime are imposed. A caller of - GSS_Acquire_cred() can request a length of time for which acquired - credentials are to be valid (lifetime_req argument), beginning at the - present, or can request credentials with a default validity interval. - (Requests for postdated credentials are not supported within the - GSS-API.) Certain mechanisms and implementations may bind in - credential validity period specifiers at a point preliminary to - invocation of the GSS_Acquire_cred() call (e.g., in conjunction with - user login procedures). As a result, callers requesting non-default - values for lifetime_req must recognize that such requests cannot - always be honored and must be prepared to accommodate the use of - returned credentials with different lifetimes as indicated in - lifetime_rec. - - The caller of GSS_Acquire_cred() can explicitly specify a set of - mech_types which are to be accommodated in the returned credentials - (desired_mechs argument), or can request credentials for a system- - defined default set of mech_types. Selection of the system-specified - default set is recommended in the interests of application - portability. The actual_mechs return value may be interrogated by the - caller to determine the set of mechanisms with which the returned - credentials may be used. - -2.1.2. GSS_Release_cred call - - Input: - - o cred_handle OCTET STRING-NULL specifies default credentials - - Outputs: - - o major_status INTEGER, - - o minor_status INTEGER - - Return major_status codes: - - o GSS_COMPLETE indicates that the credentials referenced by the - input cred_handle were released for purposes of subsequent access - by the caller. The effect on other processes which may be - authorized shared access to such credentials is a local matter. - - - - - -Linn [Page 19] - -RFC 1508 Generic Security Interface September 1993 - - - o GSS_NO_CRED indicates that no release operation was performed, - either because the input cred_handle was invalid or because the - caller lacks authorization to access the referenced credentials. - - o GSS_FAILURE indicates that the release operation failed for - reasons unspecified at the GSS-API level. - - Provides a means for a caller to explicitly request that credentials - be released when their use is no longer required. Note that system- - specific credential management functions are also likely to exist, - for example to assure that credentials shared among processes are - properly deleted when all affected processes terminate, even if no - explicit release requests are issued by those processes. Given the - fact that multiple callers are not precluded from gaining authorized - access to the same credentials, invocation of GSS_Release_cred() - cannot be assumed to delete a particular set of credentials on a - system-wide basis. - -2.1.3. GSS_Inquire_cred call - - Input: - - o cred_handle OCTET STRING -NULL specifies default credentials - - Outputs: - - o major_status INTEGER, - - o minor_status INTEGER, - - o cred_name INTERNAL NAME, - - o lifetime_rec INTEGER -in seconds, or reserved value for - INDEFINITE - - o cred_usage INTEGER, -0=INITIATE-AND-ACCEPT, 1=INITIATE-ONLY, - 2=ACCEPT-ONLY - - o mech_set SET OF OBJECT IDENTIFIER - - Return major_status codes: - - o GSS_COMPLETE indicates that the credentials referenced by the - input cred_handle argument were valid, and that the output - cred_name, lifetime_rec, and cred_usage values represent, - respectively, the credentials' associated principal name, - remaining lifetime, suitable usage modes, and supported - mechanism types. - - - -Linn [Page 20] - -RFC 1508 Generic Security Interface September 1993 - - - o GSS_NO_CRED indicates that no information could be returned - about the referenced credentials, either because the input - cred_handle was invalid or because the caller lacks - authorization to access the referenced credentials. - - o GSS_FAILURE indicates that the release operation failed for - reasons unspecified at the GSS-API level. - - The GSS_Inquire_cred() call is defined primarily for the use of - those callers which make use of default credentials rather than - acquiring credentials explicitly with GSS_Acquire_cred(). It enables - callers to determine a credential structure's associated principal - name, remaining validity period, usability for security context - initiation and/or acceptance, and supported mechanisms. - -2.2. Context-level calls - - This group of calls is devoted to the establishment and management of - security contexts between peers. A context's initiator calls - GSS_Init_sec_context(), resulting in generation of a token which the - caller passes to the target. At the target, that token is passed to - GSS_Accept_sec_context(). Depending on the underlying mech_type and - specified options, additional token exchanges may be performed in the - course of context establishment; such exchanges are accommodated by - GSS_CONTINUE_NEEDED status returns from GSS_Init_sec_context() and - GSS_Accept_sec_context(). Either party to an established context may - invoke GSS_Delete_sec_context() to flush context information when a - context is no longer required. GSS_Process_context_token() is used - to process received tokens carrying context-level control - information. GSS_Context_time() allows a caller to determine the - length of time for which an established context will remain valid. - -2.2.1. GSS_Init_sec_context call - - Inputs: - - o claimant_cred_handle OCTET STRING, -NULL specifies "use - default" - - o input_context_handle INTEGER, -0 specifies "none assigned - yet" - - o targ_name INTERNAL NAME, - - o mech_type OBJECT IDENTIFIER, -NULL parameter specifies "use - default" - - o deleg_req_flag BOOLEAN, - - - -Linn [Page 21] - -RFC 1508 Generic Security Interface September 1993 - - - o mutual_req_flag BOOLEAN, - - o replay_det_req_flag BOOLEAN, - - o sequence_req_flag BOOLEAN, - - o lifetime_req INTEGER,-0 specifies default lifetime - - o chan_bindings OCTET STRING, - - o input_token OCTET STRING-NULL or token received from target - - Outputs: - - o major_status INTEGER, - - o minor_status INTEGER, - - o output_context_handle INTEGER, - - o mech_type OBJECT IDENTIFIER, -actual mechanism always - indicated, never NULL - - o output_token OCTET STRING, -NULL or token to pass to context - target - - o deleg_state BOOLEAN, - - o mutual_state BOOLEAN, - - o replay_det_state BOOLEAN, - - o sequence_state BOOLEAN, - - o conf_avail BOOLEAN, - - o integ_avail BOOLEAN, - - o lifetime_rec INTEGER - in seconds, or reserved value for - INDEFINITE - - This call may block pending network interactions for those mech_types - in which an authentication server or other network entity must be - consulted on behalf of a context initiator in order to generate an - output_token suitable for presentation to a specified target. - - Return major_status codes: - - - - -Linn [Page 22] - -RFC 1508 Generic Security Interface September 1993 - - - o GSS_COMPLETE indicates that context-level information was - successfully initialized, and that the returned output_token will - provide sufficient information for the target to perform per- - message processing on the newly-established context. - - o GSS_CONTINUE_NEEDED indicates that control information in the - returned output_token must be sent to the target, and that a reply - must be received and passed as the input_token argument to a - continuation call to GSS_Init_sec_context(), before per-message - processing can be performed in conjunction with this context. - - o GSS_DEFECTIVE_TOKEN indicates that consistency checks performed on - the input_token failed, preventing further processing from being - performed based on that token. - - o GSS_DEFECTIVE_CREDENTIAL indicates that consistency checks - performed on the credential structure referenced by - claimant_cred_handle failed, preventing further processing from - being performed using that credential structure. - - o GSS_BAD_SIG indicates that the received input_token contains an - incorrect signature, so context setup cannot be accomplished. - - o GSS_NO_CRED indicates that no context was established, either - because the input cred_handle was invalid, because the referenced - credentials are valid for context acceptor use only, or because - the caller lacks authorization to access the referenced - credentials. - - o GSS_CREDENTIALS_EXPIRED indicates that the credentials provided - through the input claimant_cred_handle argument are no longer - valid, so context establishment cannot be completed. - - o GSS_BAD_BINDINGS indicates that a mismatch between the caller- - provided chan_bindings and those extracted from the input_token - was detected, signifying a security-relevant event and preventing - context establishment. (This result will be returned by - GSS_Init_sec_context only for contexts where mutual_state is - TRUE.) - - o GSS_NO_CONTEXT indicates that no valid context was recognized for - the input context_handle provided; this major status will be - returned only for successor calls following GSS_CONTINUE_NEEDED - status returns. - - o GSS_BAD_NAMETYPE indicates that the provided targ_name is of a - type uninterpretable or unsupported by the supporting GSS-API - implementation, so context establishment cannot be completed. - - - -Linn [Page 23] - -RFC 1508 Generic Security Interface September 1993 - - - o GSS_BAD_NAME indicates that the provided targ_name is inconsistent - in terms of internally-incorporated type specifier information, so - context establishment cannot be accomplished. - - o GSS_FAILURE indicates that context setup could not be accomplished - for reasons unspecified at the GSS-API level, and that no - interface-defined recovery action is available. - - This routine is used by a context initiator, and ordinarily emits one - (or, for the case of a multi-step exchange, more than one) - output_token suitable for use by the target within the selected - mech_type's protocol. Using information in the credentials structure - referenced by claimant_cred_handle, GSS_Init_sec_context() - initializes the data structures required to establish a security - context with target targ_name. The claimant_cred_handle must - correspond to the same valid credentials structure on the initial - call to GSS_Init_sec_context() and on any successor calls resulting - from GSS_CONTINUE_NEEDED status returns; different protocol sequences - modeled by the GSS_CONTINUE_NEEDED mechanism will require access to - credentials at different points in the context establishment - sequence. - - The input_context_handle argument is 0, specifying "not yet - assigned", on the first GSS_Init_sec_context() call relating to a - given context. That call returns an output_context_handle for future - references to this context. When continuation attempts to - GSS_Init_sec_context() are needed to perform context establishment, - the previously-returned non-zero handle value is entered into the - input_context_handle argument and will be echoed in the returned - output_context_handle argument. On such continuation attempts (and - only on continuation attempts) the input_token value is used, to - provide the token returned from the context's target. - - The chan_bindings argument is used by the caller to provide - information binding the security context to security-related - characteristics (e.g., addresses, cryptographic keys) of the - underlying communications channel. See Section 1.1.6 of this document - for more discussion of this argument's usage. - - The input_token argument contains a message received from the target, - and is significant only on a call to GSS_Init_sec_context() which - follows a previous return indicating GSS_CONTINUE_NEEDED - major_status. - - It is the caller's responsibility to establish a communications path - to the target, and to transmit any returned output_token (independent - of the accompanying returned major_status value) to the target over - that path. The output_token can, however, be transmitted along with - - - -Linn [Page 24] - -RFC 1508 Generic Security Interface September 1993 - - - the first application-provided input message to be processed by - GSS_Sign() or GSS_Seal() in conjunction with a successfully- - established context. - - The initiator may request various context-level functions through - input flags: the deleg_req_flag requests delegation of access rights, - the mutual_req_flag requests mutual authentication, the - replay_det_req_flag requests that replay detection features be - applied to messages transferred on the established context, and the - sequence_req_flag requests that sequencing be enforced. (See Section - 1.2.3 for more information on replay detection and sequencing - features.) - - Not all of the optionally-requestable features will be available in - all underlying mech_types; the corresponding return state values - (deleg_state, mutual_state, replay_det_state, sequence_state) - indicate, as a function of mech_type processing capabilities and - initiator-provided input flags, the set of features which will be - active on the context. These state indicators' values are undefined - unless the routine's major_status indicates COMPLETE. Failure to - provide the precise set of features requested by the caller does not - cause context establishment to fail; it is the caller's prerogative - to delete the context if the feature set provided is unsuitable for - the caller's use. The returned mech_type value indicates the - specific mechanism employed on the context, and will never indicate - the value for "default". - - The conf_avail return value indicates whether the context supports - per-message confidentiality services, and so informs the caller - whether or not a request for encryption through the conf_req_flag - input to GSS_Seal() can be honored. In similar fashion, the - integ_avail return value indicates whether per-message integrity - services are available (through either GSS_Sign() or GSS_Seal()) on - the established context. - - The lifetime_req input specifies a desired upper bound for the - lifetime of the context to be established, with a value of 0 used to - request a default lifetime. The lifetime_rec return value indicates - the length of time for which the context will be valid, expressed as - an offset from the present; depending on mechanism capabilities, - credential lifetimes, and local policy, it may not correspond to the - value requested in lifetime_req. If no constraints on context - lifetime are imposed, this may be indicated by returning a reserved - value representing INDEFINITE lifetime_req. The values of conf_avail, - integ_avail, and lifetime_rec are undefined unless the routine's - major_status indicates COMPLETE. - - If the mutual_state is TRUE, this fact will be reflected within the - - - -Linn [Page 25] - -RFC 1508 Generic Security Interface September 1993 - - - output_token. A call to GSS_Accept_sec_context() at the target in - conjunction with such a context will return a token, to be processed - by a continuation call to GSS_Init_sec_context(), in order to achieve - mutual authentication. - -2.2.2. GSS_Accept_sec_context call - - Inputs: - - o acceptor_cred_handle OCTET STRING,-NULL specifies "use - default" - - o input_context_handle INTEGER, -0 specifies "not yet assigned" - - o chan_bindings OCTET STRING, - - o input_token OCTET STRING - - Outputs: - - o major_status INTEGER, - - o minor_status INTEGER, - - o src_name INTERNAL NAME, - - o mech_type OBJECT IDENTIFIER, - - o output_context_handle INTEGER, - - o deleg_state BOOLEAN, - - o mutual_state BOOLEAN, - - o replay_det_state BOOLEAN, - - o sequence_state BOOLEAN, - - o conf_avail BOOLEAN, - - o integ_avail BOOLEAN, - - o lifetime_rec INTEGER, - in seconds, or reserved value for - INDEFINITE - - o delegated_cred_handle OCTET STRING, - - o output_token OCTET STRING -NULL or token to pass to context - - - -Linn [Page 26] - -RFC 1508 Generic Security Interface September 1993 - - - initiator - - This call may block pending network interactions for those mech_types - in which a directory service or other network entity must be - consulted on behalf of a context acceptor in order to validate a - received input_token. - - Return major_status codes: - - o GSS_COMPLETE indicates that context-level data structures were - successfully initialized, and that per-message processing can now - be performed in conjunction with this context. - - o GSS_CONTINUE_NEEDED indicates that control information in the - returned output_token must be sent to the initiator, and that a - response must be received and passed as the input_token argument - to a continuation call to GSS_Accept_sec_context(), before per- - message processing can be performed in conjunction with this - context. - - o GSS_DEFECTIVE_TOKEN indicates that consistency checks performed on - the input_token failed, preventing further processing from being - performed based on that token. - - o GSS_DEFECTIVE_CREDENTIAL indicates that consistency checks - performed on the credential structure referenced by - acceptor_cred_handle failed, preventing further processing from - being performed using that credential structure. - - o GSS_BAD_SIG indicates that the received input_token contains an - incorrect signature, so context setup cannot be accomplished. - - o GSS_DUPLICATE_TOKEN indicates that the signature on the received - input_token was correct, but that the input_token was recognized - as a duplicate of an input_token already processed. No new context - is established. - - o GSS_OLD_TOKEN indicates that the signature on the received - input_token was correct, but that the input_token is too old to be - checked for duplication against previously-processed input_tokens. - No new context is established. - - o GSS_NO_CRED indicates that no context was established, either - because the input cred_handle was invalid, because the referenced - credentials are valid for context initiator use only, or because - the caller lacks authorization to access the referenced - credentials. - - - - -Linn [Page 27] - -RFC 1508 Generic Security Interface September 1993 - - - o GSS_CREDENTIALS_EXPIRED indicates that the credentials provided - through the input acceptor_cred_handle argument are no longer - valid, so context establishment cannot be completed. - - o GSS_BAD_BINDINGS indicates that a mismatch between the caller- - provided chan_bindings and those extracted from the input_token - was detected, signifying a security-relevant event and preventing - context establishment. - - o GSS_NO_CONTEXT indicates that no valid context was recognized for - the input context_handle provided; this major status will be - returned only for successor calls following GSS_CONTINUE_NEEDED - status returns. - - o GSS_FAILURE indicates that context setup could not be accomplished - for reasons unspecified at the GSS-API level, and that no - interface-defined recovery action is available. - - The GSS_Accept_sec_context() routine is used by a context target. - Using information in the credentials structure referenced by the - input acceptor_cred_handle, it verifies the incoming input_token and - (following the successful completion of a context establishment - sequence) returns the authenticated src_name and the mech_type used. - The acceptor_cred_handle must correspond to the same valid - credentials structure on the initial call to GSS_Accept_sec_context() - and on any successor calls resulting from GSS_CONTINUE_NEEDED status - returns; different protocol sequences modeled by the - GSS_CONTINUE_NEEDED mechanism will require access to credentials at - different points in the context establishment sequence. - - The input_context_handle argument is 0, specifying "not yet - assigned", on the first GSS_Accept_sec_context() call relating to a - given context. That call returns an output_context_handle for future - references to this context; when continuation attempts to - GSS_Accept_sec_context() are needed to perform context - establishment, that handle value will be entered into the - input_context_handle argument. - - The chan_bindings argument is used by the caller to provide - information binding the security context to security-related - characteristics (e.g., addresses, cryptographic keys) of the - underlying communications channel. See Section 1.1.6 of this document - for more discussion of this argument's usage. - - The returned state results (deleg_state, mutual_state, - replay_det_state, and sequence_state) reflect the same context state - values as returned to GSS_Init_sec_context()'s caller at the - initiator system. - - - -Linn [Page 28] - -RFC 1508 Generic Security Interface September 1993 - - - The conf_avail return value indicates whether the context supports - per-message confidentiality services, and so informs the caller - whether or not a request for encryption through the conf_req_flag - input to GSS_Seal() can be honored. In similar fashion, the - integ_avail return value indicates whether per-message integrity - services are available (through either GSS_Sign() or GSS_Seal()) on - the established context. - - The lifetime_rec return value indicates the length of time for which - the context will be valid, expressed as an offset from the present. - The values of deleg_state, mutual_state, replay_det_state, - sequence_state, conf_avail, integ_avail, and lifetime_rec are - undefined unless the accompanying major_status indicates COMPLETE. - - The delegated_cred_handle result is significant only when deleg_state - is TRUE, and provides a means for the target to reference the - delegated credentials. The output_token result, when non-NULL, - provides a context-level token to be returned to the context - initiator to continue a multi-step context establishment sequence. As - noted with GSS_Init_sec_context(), any returned token should be - transferred to the context's peer (in this case, the context - initiator), independent of the value of the accompanying returned - major_status. - - Note: A target must be able to distinguish a context-level - input_token, which is passed to GSS_Accept_sec_context(), from the - per-message data elements passed to GSS_Verify() or GSS_Unseal(). - These data elements may arrive in a single application message, and - GSS_Accept_sec_context() must be performed before per-message - processing can be performed successfully. - -2.2.3. GSS_Delete_sec_context call - - Input: - - o context_handle INTEGER - - Outputs: - - o major_status INTEGER, - - o minor_status INTEGER, - - o output_context_token OCTET STRING - - Return major_status codes: - - - - - -Linn [Page 29] - -RFC 1508 Generic Security Interface September 1993 - - - o GSS_COMPLETE indicates that the context was recognized, that - relevant context-specific information was flushed, and that the - returned output_context_token is ready for transfer to the - context's peer. - - o GSS_NO_CONTEXT indicates that no valid context was recognized for - the input context_handle provide, so no deletion was performed. - - o GSS_FAILURE indicates that the context is recognized, but that the - GSS_Delete_sec_context() operation could not be performed for - reasons unspecified at the GSS-API level. - - This call may block pending network interactions for mech_types in - which active notification must be made to a central server when a - security context is to be deleted. - - This call can be made by either peer in a security context, to flush - context-specific information and to return an output_context_token - which can be passed to the context's peer informing it that the - peer's corresponding context information can also be flushed. (Once a - context is established, the peers involved are expected to retain - cached credential and context-related information until the - information's expiration time is reached or until a - GSS_Delete_sec_context() call is made.) Attempts to perform per- - message processing on a deleted context will result in error returns. - -2.2.4. GSS_Process_context_token call - - Inputs: - - o context_handle INTEGER, - - o input_context_token OCTET STRING - - Outputs: - - o major_status INTEGER, - - o minor_status INTEGER, - - Return major_status codes: - - o GSS_COMPLETE indicates that the input_context_token was - successfully processed in conjunction with the context referenced - by context_handle. - - o GSS_DEFECTIVE_TOKEN indicates that consistency checks performed on - the received context_token failed, preventing further processing - - - -Linn [Page 30] - -RFC 1508 Generic Security Interface September 1993 - - - from being performed with that token. - - o GSS_NO_CONTEXT indicates that no valid context was recognized for - the input context_handle provided. - - o GSS_FAILURE indicates that the context is recognized, but that the - GSS_Process_context_token() operation could not be performed for - reasons unspecified at the GSS-API level. - - This call is used to process context_tokens received from a peer once - a context has been established, with corresponding impact on - context-level state information. One use for this facility is - processing of the context_tokens generated by - GSS_Delete_sec_context(); GSS_Process_context_token() will not block - pending network interactions for that purpose. Another use is to - process tokens indicating remote-peer context establishment failures - after the point where the local GSS-API implementation has already - indicated GSS_COMPLETE status. - -2.2.5. GSS_Context_time call - - Input: - - o context_handle INTEGER, - - Outputs: - - o major_status INTEGER, - - o minor_status INTEGER, - - o lifetime_rec INTEGER - in seconds, or reserved value for - INDEFINITE - - Return major_status codes: - - o GSS_COMPLETE indicates that the referenced context is valid, and - will remain valid for the amount of time indicated in - lifetime_rec. - - o GSS_CONTEXT_EXPIRED indicates that data items related to the - referenced context have expired. - - o GSS_CREDENTIALS_EXPIRED indicates that the context is recognized, - but that its associated credentials have expired. - - o GSS_NO_CONTEXT indicates that no valid context was recognized for - the input context_handle provided. - - - -Linn [Page 31] - -RFC 1508 Generic Security Interface September 1993 - - - o GSS_FAILURE indicates that the requested operation failed for - reasons unspecified at the GSS-API level. - - This call is used to determine the amount of time for which a - currently established context will remain valid. - -2.3. Per-message calls - - This group of calls is used to perform per-message protection - processing on an established security context. None of these calls - block pending network interactions. These calls may be invoked by a - context's initiator or by the context's target. The four members of - this group should be considered as two pairs; the output from - GSS_Sign() is properly input to GSS_Verify(), and the output from - GSS_Seal() is properly input to GSS_Unseal(). - - GSS_Sign() and GSS_Verify() support data origin authentication and - data integrity services. When GSS_Sign() is invoked on an input - message, it yields a per-message token containing data items which - allow underlying mechanisms to provide the specified security - services. The original message, along with the generated per-message - token, is passed to the remote peer; these two data elements are - processed by GSS_Verify(), which validates the message in - conjunction with the separate token. - - GSS_Seal() and GSS_Unseal() support caller-requested confidentiality - in addition to the data origin authentication and data integrity - services offered by GSS_Sign() and GSS_Verify(). GSS_Seal() outputs - a single data element, encapsulating optionally enciphered user data - as well as associated token data items. The data element output from - GSS_Seal() is passed to the remote peer and processed by - GSS_Unseal() at that system. GSS_Unseal() combines decipherment (as - required) with validation of data items related to authentication and - integrity. - -2.3.1. GSS_Sign call - - Inputs: - - o context_handle INTEGER, - - o qop_req INTEGER,-0 specifies default QOP - - o message OCTET STRING - - Outputs: - - o major_status INTEGER, - - - -Linn [Page 32] - -RFC 1508 Generic Security Interface September 1993 - - - o minor_status INTEGER, - - o per_msg_token OCTET STRING - - Return major_status codes: - - o GSS_COMPLETE indicates that a signature, suitable for an - established security context, was successfully applied and that - the message and corresponding per_msg_token are ready for - transmission. - - o GSS_CONTEXT_EXPIRED indicates that context-related data items have - expired, so that the requested operation cannot be performed. - - o GSS_CREDENTIALS_EXPIRED indicates that the context is recognized, - but that its associated credentials have expired, so that the - requested operation cannot be performed. - - o GSS_NO_CONTEXT indicates that no valid context was recognized for - the input context_handle provided. - - o GSS_FAILURE indicates that the context is recognized, but that the - requested operation could not be performed for reasons unspecified - at the GSS-API level. - - Using the security context referenced by context_handle, apply a - signature to the input message (along with timestamps and/or other - data included in support of mech_type-specific mechanisms) and return - the result in per_msg_token. The qop_req parameter allows quality- - of-protection control. The caller passes the message and the - per_msg_token to the target. - - The GSS_Sign() function completes before the message and - per_msg_token is sent to the peer; successful application of - GSS_Sign() does not guarantee that a corresponding GSS_Verify() has - been (or can necessarily be) performed successfully when the message - arrives at the destination. - -2.3.2. GSS_Verify call - - Inputs: - - o context_handle INTEGER, - - o message OCTET STRING, - - o per_msg_token OCTET STRING - - - - -Linn [Page 33] - -RFC 1508 Generic Security Interface September 1993 - - - Outputs: - - o qop_state INTEGER, - - o major_status INTEGER, - - o minor_status INTEGER, - - Return major_status codes: - - o GSS_COMPLETE indicates that the message was successfully verified. - - o GSS_DEFECTIVE_TOKEN indicates that consistency checks performed on - the received per_msg_token failed, preventing further processing - from being performed with that token. - - o GSS_BAD_SIG indicates that the received per_msg_token contains an - incorrect signature for the message. - - o GSS_DUPLICATE_TOKEN, GSS_OLD_TOKEN, and GSS_UNSEQ_TOKEN values - appear in conjunction with the optional per-message replay - detection features described in Section 1.2.3; their semantics are - described in that section. - - o GSS_CONTEXT_EXPIRED indicates that context-related data items have - expired, so that the requested operation cannot be performed. - - o GSS_CREDENTIALS_EXPIRED indicates that the context is recognized, - but that its associated credentials have expired, so that the - requested operation cannot be performed. - - o GSS_NO_CONTEXT indicates that no valid context was recognized for - the input context_handle provided. - - o GSS_FAILURE indicates that the context is recognized, but that the - GSS_Verify() operation could not be performed for reasons - unspecified at the GSS-API level. - - Using the security context referenced by context_handle, verify that - the input per_msg_token contains an appropriate signature for the - input message, and apply any active replay detection or sequencing - features. Return an indication of the quality-of-protection applied - to the processed message in the qop_state result. - - - - - - - - -Linn [Page 34] - -RFC 1508 Generic Security Interface September 1993 - - -2.3.3. GSS_Seal call - - Inputs: - - o context_handle INTEGER, - - o conf_req_flag BOOLEAN, - - o qop_req INTEGER,-0 specifies default QOP - - o input_message OCTET STRING - - Outputs: - - o major_status INTEGER, - - o minor_status INTEGER, - - o conf_state BOOLEAN, - - o output_message OCTET STRING - - Return major_status codes: - - o GSS_COMPLETE indicates that the input_message was successfully - processed and that the output_message is ready for transmission. - - o GSS_CONTEXT_EXPIRED indicates that context-related data items have - expired, so that the requested operation cannot be performed. - - o GSS_CREDENTIALS_EXPIRED indicates that the context is recognized, - but that its associated credentials have expired, so that the - requested operation cannot be performed. - - o GSS_NO_CONTEXT indicates that no valid context was recognized for - the input context_handle provided. - - o GSS_FAILURE indicates that the context is recognized, but that the - GSS_Seal() operation could not be performed for reasons - unspecified at the GSS-API level. - - Performs the data origin authentication and data integrity functions - of GSS_Sign(). If the input conf_req_flag is TRUE, requests that - confidentiality be applied to the input_message. Confidentiality may - not be supported in all mech_types or by all implementations; the - returned conf_state flag indicates whether confidentiality was - provided for the input_message. The qop_req parameter allows - quality-of-protection control. - - - -Linn [Page 35] - -RFC 1508 Generic Security Interface September 1993 - - - In all cases, the GSS_Seal() call yields a single output_message - data element containing (optionally enciphered) user data as well as - control information. - -2.3.4. GSS_Unseal call - - Inputs: - - o context_handle INTEGER, - - o input_message OCTET STRING - - Outputs: - - o conf_state BOOLEAN, - - o qop_state INTEGER, - - o major_status INTEGER, - - o minor_status INTEGER, - - o output_message OCTET STRING - - Return major_status codes: - - o GSS_COMPLETE indicates that the input_message was successfully - processed and that the resulting output_message is available. - - o GSS_DEFECTIVE_TOKEN indicates that consistency checks performed on - the per_msg_token extracted from the input_message failed, - preventing further processing from being performed. - - o GSS_BAD_SIG indicates that an incorrect signature was detected for - the message. - - o GSS_DUPLICATE_TOKEN, GSS_OLD_TOKEN, and GSS_UNSEQ_TOKEN values - appear in conjunction with the optional per-message replay - detection features described in Section 1.2.3; their semantics are - described in that section. - - o GSS_CONTEXT_EXPIRED indicates that context-related data items have - expired, so that the requested operation cannot be performed. - - o GSS_CREDENTIALS_EXPIRED indicates that the context is recognized, - but that its associated credentials have expired, so that the - requested operation cannot be performed. - - - - -Linn [Page 36] - -RFC 1508 Generic Security Interface September 1993 - - - o GSS_NO_CONTEXT indicates that no valid context was recognized for - the input context_handle provided. - - o GSS_FAILURE indicates that the context is recognized, but that the - GSS_Unseal() operation could not be performed for reasons - unspecified at the GSS-API level. - - Processes a data element generated (and optionally enciphered) by - GSS_Seal(), provided as input_message. The returned conf_state value - indicates whether confidentiality was applied to the input_message. - If conf_state is TRUE, GSS_Unseal() deciphers the input_message. - Returns an indication of the quality-of-protection applied to the - processed message in the qop_state result. GSS_Seal() performs the - data integrity and data origin authentication checking functions of - GSS_Verify() on the plaintext data. Plaintext data is returned in - output_message. - -2.4. Support calls - - This group of calls provides support functions useful to GSS-API - callers, independent of the state of established contexts. Their - characterization with regard to blocking or non-blocking status in - terms of network interactions is unspecified. - -2.4.1. GSS_Display_status call - - Inputs: - - o status_value INTEGER,-GSS-API major_status or minor_status - return value - - o status_type INTEGER,-1 if major_status, 2 if minor_status - - o mech_type OBJECT IDENTIFIER-mech_type to be used for minor_ - status translation - - Outputs: - - o major_status INTEGER, - - o minor_status INTEGER, - - o status_string_set SET OF OCTET STRING - - Return major_status codes: - - o GSS_COMPLETE indicates that a valid printable status - representation (possibly representing more than one status event - - - -Linn [Page 37] - -RFC 1508 Generic Security Interface September 1993 - - - encoded within the status_value) is available in the returned - status_string_set. - - o GSS_BAD_MECH indicates that translation in accordance with an - unsupported mech_type was requested, so translation could not be - performed. - - o GSS_BAD_STATUS indicates that the input status_value was invalid, - or that the input status_type carried a value other than 1 or 2, - so translation could not be performed. - - o GSS_FAILURE indicates that the requested operation could not be - performed for reasons unspecified at the GSS-API level. - - Provides a means for callers to translate GSS-API-returned major and - minor status codes into printable string representations. - -2.4.2. GSS_Indicate_mechs call - - Input: - - o (none) - - Outputs: - - o major_status INTEGER, - - o minor_status INTEGER, - - o mech_set SET OF OBJECT IDENTIFIER - - Return major_status codes: - - o GSS_COMPLETE indicates that a set of available mechanisms has - been returned in mech_set. - - o GSS_FAILURE indicates that the requested operation could not - be performed for reasons unspecified at the GSS-API level. - - Allows callers to determine the set of mechanism types available on - the local system. This call is intended for support of specialized - callers who need to request non-default mech_type sets from - GSS_Acquire_cred(), and should not be needed by other callers. - -2.4.3. GSS_Compare_name call - - Inputs: - - - - -Linn [Page 38] - -RFC 1508 Generic Security Interface September 1993 - - - o name1 INTERNAL NAME, - - o name2 INTERNAL NAME - - Outputs: - - o major_status INTEGER, - - o minor_status INTEGER, - - o name_equal BOOLEAN - - Return major_status codes: - - o GSS_COMPLETE indicates that name1 and name2 were comparable, and - that the name_equal result indicates whether name1 and name2 were - equal or unequal. - - o GSS_BAD_NAMETYPE indicates that one or both of name1 and name2 - contained internal type specifiers uninterpretable by the - supporting GSS-API implementation, or that the two names' types - are different and incomparable, so the equality comparison could - not be completed. - - o GSS_BAD_NAME indicates that one or both of the input names was - ill-formed in terms of its internal type specifier, so the - equality comparison could not be completed. - - o GSS_FAILURE indicates that the requested operation could not be - performed for reasons unspecified at the GSS-API level. - - Allows callers to compare two internal name representations for - equality. - -2.4.4. GSS_Display_name call - - Inputs: - - o name INTERNAL NAME - - Outputs: - - o major_status INTEGER, - - o minor_status INTEGER, - - o name_string OCTET STRING, - - - - -Linn [Page 39] - -RFC 1508 Generic Security Interface September 1993 - - - o name_type OBJECT IDENTIFIER - - Return major_status codes: - - o GSS_COMPLETE indicates that a valid printable name representation - is available in the returned name_string. - - o GSS_BAD_NAMETYPE indicates that the provided name was of a type - uninterpretable by the supporting GSS-API implementation, so no - printable representation could be generated. - - o GSS_BAD_NAME indicates that the contents of the provided name were - inconsistent with the internally-indicated name type, so no - printable representation could be generated. - - o GSS_FAILURE indicates that the requested operation could not be - performed for reasons unspecified at the GSS-API level. - - Allows callers to translate an internal name representation into a - printable form with associated namespace type descriptor. The syntax - of the printable form is a local matter. - -2.4.5. GSS_Import_name call - - Inputs: - - o input_name_string OCTET STRING, - - o input_name_type OBJECT IDENTIFIER - - Outputs: - - o major_status INTEGER, - - o minor_status INTEGER, - - o output_name INTERNAL NAME - - Return major_status codes: - - o GSS_COMPLETE indicates that a valid name representation is output - in output_name and described by the type value in - output_name_type. - - o GSS_BAD_NAMETYPE indicates that the input_name_type is unsupported - by the GSS-API implementation, so the import operation could not - be completed. - - - - -Linn [Page 40] - -RFC 1508 Generic Security Interface September 1993 - - - o GSS_BAD_NAME indicates that the provided input_name_string is - ill-formed in terms of the input_name_type, so the import - operation could not be completed. - - o GSS_FAILURE indicates that the requested operation could not be - performed for reasons unspecified at the GSS-API level. - - Allows callers to provide a printable name representation, designate - the type of namespace in conjunction with which it should be parsed, - and convert that printable representation to an internal form - suitable for input to other GSS-API routines. The syntax of the - input_name is a local matter. - -2.4.6. GSS_Release_name call - - Inputs: - - o name INTERNAL NAME - - Outputs: - - o major_status INTEGER, - - o minor_status INTEGER - - Return major_status codes: - - o GSS_COMPLETE indicates that the storage associated with the input - name was successfully released. - - o GSS_BAD_NAME indicates that the input name argument did not - contain a valid name. - - o GSS_FAILURE indicates that the requested operation could not be - performed for reasons unspecified at the GSS-API level. - - Allows callers to release the storage associated with an internal - name representation. - -2.4.7. GSS_Release_buffer call - - Inputs: - - o buffer OCTET STRING - - Outputs: - - o major_status INTEGER, - - - -Linn [Page 41] - -RFC 1508 Generic Security Interface September 1993 - - - o minor_status INTEGER - - Return major_status codes: - - o GSS_COMPLETE indicates that the storage associated with the input - buffer was successfully released. - - o GSS_FAILURE indicates that the requested operation could not be - performed for reasons unspecified at the GSS-API level. - - Allows callers to release the storage associated with an OCTET STRING - buffer allocated by another GSS-API call. - -2.4.8. GSS_Release_oid_set call - - Inputs: - - o buffer SET OF OBJECT IDENTIFIER - - Outputs: - - o major_status INTEGER, - - o minor_status INTEGER - - Return major_status codes: - - o GSS_COMPLETE indicates that the storage associated with the input - object identifier set was successfully released. - - o GSS_FAILURE indicates that the requested operation could not be - performed for reasons unspecified at the GSS-API level. - - Allows callers to release the storage associated with an object - identifier set object allocated by another GSS-API call. - -3. Mechanism-Specific Example Scenarios - - This section provides illustrative overviews of the use of various - candidate mechanism types to support the GSS-API. These discussions - are intended primarily for readers familiar with specific security - technologies, demonstrating how GSS-API functions can be used and - implemented by candidate underlying mechanisms. They should not be - regarded as constrictive to implementations or as defining the only - means through which GSS-API functions can be realized with a - particular underlying technology, and do not demonstrate all GSS-API - features with each technology. - - - - -Linn [Page 42] - -RFC 1508 Generic Security Interface September 1993 - - -3.1. Kerberos V5, single-TGT - - OS-specific login functions yield a TGT to the local realm Kerberos - server; TGT is placed in a credentials structure for the client. - Client calls GSS_Acquire_cred() to acquire a cred_handle in order to - reference the credentials for use in establishing security contexts. - - Client calls GSS_Init_sec_context(). If the requested service is - located in a different realm, GSS_Init_sec_context() gets the - necessary TGT/key pairs needed to traverse the path from local to - target realm; these data are placed in the owner's TGT cache. After - any needed remote realm resolution, GSS_Init_sec_context() yields a - service ticket to the requested service with a corresponding session - key; these data are stored in conjunction with the context. GSS-API - code sends KRB_TGS_REQ request(s) and receives KRB_TGS_REP - response(s) (in the successful case) or KRB_ERROR. - - Assuming success, GSS_Init_sec_context() builds a Kerberos-formatted - KRB_AP_REQ message, and returns it in output_token. The client sends - the output_token to the service. - - The service passes the received token as the input_token argument to - GSS_Accept_sec_context(), which verifies the authenticator, provides - the service with the client's authenticated name, and returns an - output_context_handle. - - Both parties now hold the session key associated with the service - ticket, and can use this key in subsequent GSS_Sign(), GSS_Verify(), - GSS_Seal(), and GSS_Unseal() operations. - -3.2. Kerberos V5, double-TGT - - TGT acquisition as above. - - Note: To avoid unnecessary frequent invocations of error paths when - implementing the GSS-API atop Kerberos V5, it seems appropriate to - represent "single-TGT K-V5" and "double-TGT K-V5" with separate - mech_types, and this discussion makes that assumption. - - Based on the (specified or defaulted) mech_type, - GSS_Init_sec_context() determines that the double-TGT protocol - should be employed for the specified target. GSS_Init_sec_context() - returns GSS_CONTINUE_NEEDED major_status, and its returned - output_token contains a request to the service for the service's TGT. - (If a service TGT with suitably long remaining lifetime already - exists in a cache, it may be usable, obviating the need for this - step.) The client passes the output_token to the service. Note: this - scenario illustrates a different use for the GSS_CONTINUE_NEEDED - - - -Linn [Page 43] - -RFC 1508 Generic Security Interface September 1993 - - - status return facility than for support of mutual authentication; - note that both uses can coexist as successive operations within a - single context establishment operation. - - The service passes the received token as the input_token argument to - GSS_Accept_sec_context(), which recognizes it as a request for TGT. - (Note that current Kerberos V5 defines no intra-protocol mechanism to - represent such a request.) GSS_Accept_sec_context() returns - GSS_CONTINUE_NEEDED major_status and provides the service's TGT in - its output_token. The service sends the output_token to the client. - - The client passes the received token as the input_token argument to a - continuation of GSS_Init_sec_context(). GSS_Init_sec_context() caches - the received service TGT and uses it as part of a service ticket - request to the Kerberos authentication server, storing the returned - service ticket and session key in conjunction with the context. - GSS_Init_sec_context() builds a Kerberos-formatted authenticator, - and returns it in output_token along with GSS_COMPLETE return - major_status. The client sends the output_token to the service. - - Service passes the received token as the input_token argument to a - continuation call to GSS_Accept_sec_context(). - GSS_Accept_sec_context() verifies the authenticator, provides the - service with the client's authenticated name, and returns - major_status GSS_COMPLETE. - - GSS_Sign(), GSS_Verify(), GSS_Seal(), and GSS_Unseal() as above. - -3.3. X.509 Authentication Framework - - This example illustrates use of the GSS-API in conjunction with - public-key mechanisms, consistent with the X.509 Directory - Authentication Framework. - - The GSS_Acquire_cred() call establishes a credentials structure, - making the client's private key accessible for use on behalf of the - client. - - The client calls GSS_Init_sec_context(), which interrogates the - Directory to acquire (and validate) a chain of public-key - certificates, thereby collecting the public key of the service. The - certificate validation operation determines that suitable signatures - were applied by trusted authorities and that those certificates have - not expired. GSS_Init_sec_context() generates a secret key for use - in per-message protection operations on the context, and enciphers - that secret key under the service's public key. - - The enciphered secret key, along with an authenticator quantity - - - -Linn [Page 44] - -RFC 1508 Generic Security Interface September 1993 - - - signed with the client's private key, is included in the output_token - from GSS_Init_sec_context(). The output_token also carries a - certification path, consisting of a certificate chain leading from - the service to the client; a variant approach would defer this path - resolution to be performed by the service instead of being asserted - by the client. The client application sends the output_token to the - service. - - The service passes the received token as the input_token argument to - GSS_Accept_sec_context(). GSS_Accept_sec_context() validates the - certification path, and as a result determines a certified binding - between the client's distinguished name and the client's public key. - Given that public key, GSS_Accept_sec_context() can process the - input_token's authenticator quantity and verify that the client's - private key was used to sign the input_token. At this point, the - client is authenticated to the service. The service uses its private - key to decipher the enciphered secret key provided to it for per- - message protection operations on the context. - - The client calls GSS_Sign() or GSS_Seal() on a data message, which - causes per-message authentication, integrity, and (optional) - confidentiality facilities to be applied to that message. The service - uses the context's shared secret key to perform corresponding - GSS_Verify() and GSS_Unseal() calls. - -4. Related Activities - - In order to implement the GSS-API atop existing, emerging, and future - security mechanisms: - - object identifiers must be assigned to candidate GSS-API - mechanisms and the name types which they support - - concrete data element formats must be defined for candidate - mechanisms - - Calling applications must implement formatting conventions which will - enable them to distinguish GSS-API tokens from other data carried in - their application protocols. - - Concrete language bindings are required for the programming - environments in which the GSS-API is to be employed; such bindings - for the C language are available in an associated RFC. - - - - - - - - -Linn [Page 45] - -RFC 1508 Generic Security Interface September 1993 - - -5. Acknowledgments - - This proposal is the result of a collaborative effort. - Acknowledgments are due to the many members of the IETF Security Area - Advisory Group (SAAG) and the Common Authentication Technology (CAT) - Working Group for their contributions at meetings and by electronic - mail. Acknowledgments are also due to Kannan Alagappan, Doug Barlow, - Bill Brown, Cliff Kahn, Charlie Kaufman, Butler Lampson, Richard - Pitkin, Joe Tardo, and John Wray of Digital Equipment Corporation, - and John Carr, John Kohl, Jon Rochlis, Jeff Schiller, and Ted T'so of - MIT and Project Athena. Joe Pato and Bill Sommerfeld of HP/Apollo, - Walt Tuvell of OSF, and Bill Griffith and Mike Merritt of AT&T, - provided inputs which helped to focus and clarify directions. - Precursor work by Richard Pitkin, presented to meetings of the - Trusted Systems Interoperability Group (TSIG), helped to demonstrate - the value of a generic, mechanism-independent security service API. - -6. Security Considerations - - Security issues are discussed throughout this memo. - -7. Author's Address - - John Linn - Geer Zolot Associates - One Main St. - Cambridge, MA 02142 USA - - Phone: +1 617.374.3700 - Email: Linn@gza.com - - - - - - - - - - - - - - - - - - - - - -Linn [Page 46] - -RFC 1508 Generic Security Interface September 1993 - - -APPENDIX A - -PACS AND AUTHORIZATION SERVICES - - Consideration has been given to modifying the GSS-API service - interface to recognize and manipulate Privilege Attribute - Certificates (PACs) as in ECMA 138, carrying authorization data as a - side effect of establishing a security context, but no such - modifications have been incorporated at this time. This appendix - provides rationale for this decision and discusses compatibility - alternatives between PACs and the GSS-API which do not require that - PACs be made visible to GSS-API callers. - - Existing candidate mechanism types such as Kerberos and X.509 do not - incorporate PAC manipulation features, and exclusion of such - mechanisms from the set of candidates equipped to fully support the - GSS-API seems inappropriate. Inclusion (and GSS-API visibility) of a - feature supported by only a limited number of mechanisms could - encourage the development of ostensibly portable applications which - would in fact have only limited portability. - - The status quo, in which PACs are not visible across the GSS-API - interface, does not preclude implementations in which PACs are - carried transparently, within the tokens defined and used for certain - mech_types, and stored within peers' credentials and context-level - data structures. While invisible to API callers, such PACs could be - used by operating system or other local functions as inputs in the - course of mediating access requests made by callers. This course of - action allows dynamic selection of PAC contents, if such selection is - administratively-directed rather than caller-directed. - - In a distributed computing environment, authentication must span - different systems; the need for such authentication provides - motivation for GSS-API definition and usage. Heterogeneous systems in - a network can intercommunicate, with globally authenticated names - comprising the common bond between locally defined access control - policies. Access control policies to which authentication provides - inputs are often local, or specific to particular operating systems - or environments. If the GSS-API made particular authorization models - visible across its service interface, its scope of application would - become less general. The current GSS-API paradigm is consistent with - the precedent set by Kerberos, neither defining the interpretation of - authorization-related data nor enforcing access controls based on - such data. - - The GSS-API is a general interface, whose callers may reside inside - or outside any defined TCB or NTCB boundaries. Given this - characteristic, it appears more realistic to provide facilities which - - - -Linn [Page 47] - -RFC 1508 Generic Security Interface September 1993 - - - provide "value-added" security services to its callers than to offer - facilities which enforce restrictions on those callers. Authorization - decisions must often be mediated below the GSS-API level in a local - manner against (or in spite of) applications, and cannot be - selectively invoked or omitted at those applications' discretion. - Given that the GSS-API's placement prevents it from providing a - comprehensive solution to the authorization issue, the value of a - partial contribution specific to particular authorization models is - debatable. - -APPENDIX B - -MECHANISM-INDEPENDENT TOKEN FORMAT - - This appendix specifies a mechanism-independent level of - encapsulating representation for the initial token of a GSS-API - context establishment sequence, incorporating an identifier of the - mechanism type to be used on that context. Use of this format (with - ASN.1-encoded data elements represented in BER, constrained in the - interests of parsing simplicity to the Distinguished Encoding Rule - (DER) BER subset defined in X.509, clause 8.7) is recommended to the - designers of GSS-API implementations based on various mechanisms, so - that tokens can be interpreted unambiguously at GSS-API peers. There - is no requirement that the mechanism-specific innerContextToken, - innerMsgToken, and sealedUserData data elements be encoded in ASN.1 - BER. - - -- optional top-level token definitions to - -- frame different mechanisms - - GSS-API DEFINITIONS ::= - - BEGIN - - MechType ::= OBJECT IDENTIFIER - -- data structure definitions - - -- callers must be able to distinguish among - -- InitialContextToken, SubsequentContextToken, - -- PerMsgToken, and SealedMessage data elements - -- based on the usage in which they occur - - InitialContextToken ::= - -- option indication (delegation, etc.) indicated within - -- mechanism-specific token - [APPLICATION 0] IMPLICIT SEQUENCE { - thisMech MechType, - innerContextToken ANY DEFINED BY thisMech - - - -Linn [Page 48] - -RFC 1508 Generic Security Interface September 1993 - - - -- contents mechanism-specific - } - - SubsequentContextToken ::= innerContextToken ANY - -- interpretation based on predecessor InitialContextToken - - PerMsgToken ::= - -- as emitted by GSS_Sign and processed by GSS_Verify - innerMsgToken ANY - - SealedMessage ::= - -- as emitted by GSS_Seal and processed by GSS_Unseal - -- includes internal, mechanism-defined indicator - -- of whether or not encrypted - sealedUserData ANY - - END - -APPENDIX C - -MECHANISM DESIGN CONSTRAINTS - - The following constraints on GSS-API mechanism designs are adopted in - response to observed caller protocol requirements, and adherence - thereto is anticipated in subsequent descriptions of GSS-API - mechanisms to be documented in standards-track Internet - specifications. - - Use of the approach defined in Appendix B of this specification, - applying a mechanism type tag to the InitialContextToken, is - required. - - It is strongly recommended that mechanisms offering per-message - protection services also offer at least one of the replay detection - and sequencing services, as mechanisms offering neither of the latter - will fail to satisfy recognized requirements of certain candidate - caller protocols. - - - - - - - - - - - - - - -Linn [Page 49] - \ No newline at end of file diff --git a/doc/rfc1509.txt b/doc/rfc1509.txt deleted file mode 100644 index f36cd80e6..000000000 --- a/doc/rfc1509.txt +++ /dev/null @@ -1,2691 +0,0 @@ - - - - - - -Network Working Group J. Wray -Request for Comments: 1509 Digital Equipment Corporation - September 1993 - - - Generic Security Service API : C-bindings - -Status of this Memo - - This RFC specifies an Internet standards track protocol for the - Internet community, and requests discussion and suggestions for - improvements. Please refer to the current edition of the "Internet - Official Protocol Standards" for the standardization state and status - of this protocol. Distribution of this memo is unlimited. - -Abstract - - This document specifies C language bindings for the Generic Security - Service Application Program Interface (GSS-API), which is described - at a language-independent conceptual level in other documents. - - The Generic Security Service Application Programming Interface (GSS- - API) provides security services to its callers, and is intended for - implementation atop alternative underlying cryptographic mechanisms. - Typically, GSS-API callers will be application protocols into which - security enhancements are integrated through invocation of services - provided by the GSS-API. The GSS-API allows a caller application to - authenticate a principal identity associated with a peer application, - to delegate rights to a peer, and to apply security services such as - confidentiality and integrity on a per-message basis. - -1. INTRODUCTION - - The Generic Security Service Application Programming Interface [1] - provides security services to calling applications. It allows a - communicating application to authenticate the user associated with - another application, to delegate rights to another application, and - to apply security services such as confidentiality and integrity on a - per-message basis. - - There are four stages to using the GSSAPI: - - (a) The application acquires a set of credentials with which it may - prove its identity to other processes. The application's - credentials vouch for its global identity, which may or may not - be related to the local username under which it is running. - - - - - -Wray [Page 1] - -RFC 1509 GSSAPI - Overview and C bindings September 1993 - - - (b) A pair of communicating applications establish a joint security - context using their credentials. The security context is a - pair of GSSAPI data structures that contain shared state - information, which is required in order that per-message - security services may be provided. As part of the - establishment of a security context, the context initiator is - authenticated to the responder, and may require that the - responder is authenticated in turn. The initiator may - optionally give the responder the right to initiate further - security contexts. This transfer of rights is termed - delegation, and is achieved by creating a set of credentials, - similar to those used by the originating application, but which - may be used by the responder. To establish and maintain the - shared information that makes up the security context, certain - GSSAPI calls will return a token data structure, which is a - cryptographically protected opaque data type. The caller of - such a GSSAPI routine is responsible for transferring the token - to the peer application, which should then pass it to a - corresponding GSSAPI routine which will decode it and extract - the information. - - (c) Per-message services are invoked to apply either: - - (i) integrity and data origin authentication, or - - (ii) confidentiality, integrity and data origin authentication - to application data, which are treated by GSSAPI as - arbitrary octet-strings. The application transmitting a - message that it wishes to protect will call the appropriate - GSSAPI routine (sign or seal) to apply protection, specifying - the appropriate security context, and send the result to the - receiving application. The receiver will pass the received - data to the corresponding decoding routine (verify or unseal) - to remove the protection and validate the data. - - (d) At the completion of a communications session (which may extend - across several connections), the peer applications call GSSAPI - routines to delete the security context. Multiple contexts may - also be used (either successively or simultaneously) within a - single communications association. - -2. GSSAPI Routines - - This section lists the functions performed by each of the GSSAPI - routines and discusses their major parameters, describing how they - are to be passed to the routines. The routines are listed in figure - 4-1. - - - - -Wray [Page 2] - -RFC 1509 GSSAPI - Overview and C bindings September 1993 - - - Figure 4-1 GSSAPI Routines - - - Routine Function - - gss_acquire_cred Assume a global identity - - gss_release_cred Discard credentials - - gss_init_sec_context Initiate a security context - with a peer application - - gss_accept_sec_context Accept a security context - initiated by a peer - application - - gss_process_context_token Process a token on a security - context from a peer - application - - gss_delete_sec_context Discard a security context - - gss_context_time Determine for how long a - context will remain valid - - gss_sign Sign a message; integrity - service - - gss_verify Check signature on a message - - gss_seal Sign (optionally encrypt) a - message; confidentiality - service - - gss_unseal Verify (optionally decrypt) - message - - gss_display_status Convert an API status code - to text - - gss_indicate_mechs Determine underlying - authentication mechanism - - gss_compare_name Compare two internal-form - names - - gss_display_name Convert opaque name to text - - - - -Wray [Page 3] - -RFC 1509 GSSAPI - Overview and C bindings September 1993 - - - gss_import_name Convert a textual name to - internal-form - - gss_release_name Discard an internal-form - name - - gss_release_buffer Discard a buffer - - gss_release_oid_set Discard a set of object - identifiers - - gss_inquire_cred Determine information about - a credential - - Individual GSSAPI implementations may augment these routines by - providing additional mechanism-specific routines if required - functionality is not available from the generic forms. Applications - are encouraged to use the generic routines wherever possible on - portability grounds. - -2.1. Data Types and Calling Conventions - - The following conventions are used by the GSSAPI: - -2.1.1. Structured data types - - Wherever these GSSAPI C-bindings describe structured data, only - fields that must be provided by all GSSAPI implementation are - documented. Individual implementations may provide additional - fields, either for internal use within GSSAPI routines, or for use by - non-portable applications. - -2.1.2. Integer types - - GSSAPI defines the following integer data type: - - OM_uint32 32-bit unsigned integer - - Where guaranteed minimum bit-count is important, this portable data - type is used by the GSSAPI routine definitions. Individual GSSAPI - implementations will include appropriate typedef definitions to map - this type onto a built-in data type. - -2.1.3. String and similar data - - Many of the GSSAPI routines take arguments and return values that - describe contiguous multiple-byte data. All such data is passed - between the GSSAPI and the caller using the gss_buffer_t data type. - - - -Wray [Page 4] - -RFC 1509 GSSAPI - Overview and C bindings September 1993 - - - This data type is a pointer to a buffer descriptor, which consists of - a length field that contains the total number of bytes in the datum, - and a value field which contains a pointer to the actual datum: - - typedef struct gss_buffer_desc_struct { - size_t length; - void *value; - } gss_buffer_desc, *gss_buffer_t; - - Storage for data passed to the application by a GSSAPI routine using - the gss_buffer_t conventions is allocated by the GSSAPI routine. The - application may free this storage by invoking the gss_release_buffer - routine. Allocation of the gss_buffer_desc object is always the - responsibility of the application; Unused gss_buffer_desc objects - may be initialized to the value GSS_C_EMPTY_BUFFER. - -2.1.3.1. Opaque data types - - Certain multiple-word data items are considered opaque data types at - the GSSAPI, because their internal structure has no significance - either to the GSSAPI or to the caller. Examples of such opaque data - types are the input_token parameter to gss_init_sec_context (which is - opaque to the caller), and the input_message parameter to gss_seal - (which is opaque to the GSSAPI). Opaque data is passed between the - GSSAPI and the application using the gss_buffer_t datatype. - -2.1.3.2. Character strings - - Certain multiple-word data items may be regarded as simple ISO - Latin-1 character strings. An example of this is the - input_name_buffer parameter to gss_import_name. Some GSSAPI routines - also return character strings. Character strings are passed between - the application and the GSSAPI using the gss_buffer_t datatype, - defined earlier. - -2.1.4. Object Identifiers - - Certain GSSAPI procedures take parameters of the type gss_OID, or - Object identifier. This is a type containing ISO-defined tree- - structured values, and is used by the GSSAPI caller to select an - underlying security mechanism. A value of type gss_OID has the - following structure: - - typedef struct gss_OID_desc_struct { - OM_uint32 length; - void *elements; - } gss_OID_desc, *gss_OID; - - - - -Wray [Page 5] - -RFC 1509 GSSAPI - Overview and C bindings September 1993 - - - The elements field of this structure points to the first byte of an - octet string containing the ASN.1 BER encoding of the value of the - gss_OID. The length field contains the number of bytes in this - value. For example, the gss_OID value corresponding to {iso(1) - identified- oganization(3) icd-ecma(12) member-company(2) dec(1011) - cryptoAlgorithms(7) SPX(5)} meaning SPX (Digital's X.509 - authentication mechanism) has a length field of 7 and an elements - field pointing to seven octets containing the following octal values: - 53,14,2,207,163,7,5. GSSAPI implementations should provide constant - gss_OID values to allow callers to request any supported mechanism, - although applications are encouraged on portability grounds to accept - the default mechanism. gss_OID values should also be provided to - allow applications to specify particular name types (see section - 2.1.10). Applications should treat gss_OID_desc values returned by - GSSAPI routines as read-only. In particular, the application should - not attempt to deallocate them. The gss_OID_desc datatype is - equivalent to the X/Open OM_object_identifier datatype [2]. - -2.1.5. Object Identifier Sets - - Certain GSSAPI procedures take parameters of the type gss_OID_set. - This type represents one or more object identifiers (section 2.1.4). - A gss_OID_set object has the following structure: - - typedef struct gss_OID_set_desc_struct { - int count; - gss_OID elements; - } gss_OID_set_desc, *gss_OID_set; - - The count field contains the number of OIDs within the set. The - elements field is a pointer to an array of gss_OID_desc objects, each - of which describes a single OID. gss_OID_set values are used to name - the available mechanisms supported by the GSSAPI, to request the use - of specific mechanisms, and to indicate which mechanisms a given - credential supports. Storage associated with gss_OID_set values - returned to the application by the GSSAPI may be deallocated by the - gss_release_oid_set routine. - -2.1.6. Credentials - - A credential handle is a caller-opaque atomic datum that identifies a - GSSAPI credential data structure. It is represented by the caller- - opaque type gss_cred_id_t, which may be implemented as either an - arithmetic or a pointer type. Credentials describe a principal, and - they give their holder the ability to act as that principal. The - GSSAPI does not make the actual credentials available to - applications; instead the credential handle is used to identify a - particular credential, held internally by GSSAPI or underlying - - - -Wray [Page 6] - -RFC 1509 GSSAPI - Overview and C bindings September 1993 - - - mechanism. Thus the credential handle contains no security-relavent - information, and requires no special protection by the application. - Depending on the implementation, a given credential handle may refer - to different credentials when presented to the GSSAPI by different - callers. Individual GSSAPI implementations should define both the - scope of a credential handle and the scope of a credential itself - (which must be at least as wide as that of a handle). Possibilities - for credential handle scope include the process that acquired the - handle, the acquiring process and its children, or all processes - sharing some local identification information (e.g., UID). If no - handles exist by which a given credential may be reached, the GSSAPI - may delete the credential. - - Certain routines allow credential handle parameters to be omitted to - indicate the use of a default credential. The mechanism by which a - default credential is established and its scope should be defined by - the individual GSSAPI implementation. - -2.1.7. Contexts - - The gss_ctx_id_t data type contains a caller-opaque atomic value that - identifies one end of a GSSAPI security context. It may be - implemented as either an arithmetic or a pointer type. Depending on - the implementation, a given gss_ctx_id_t value may refer to different - GSSAPI security contexts when presented to the GSSAPI by different - callers. The security context holds state information about each end - of a peer communication, including cryptographic state information. - Individual GSSAPI implementations should define the scope of a - context. Since no way is provided by which a new gss_ctx_id_t value - may be obtained for an existing context, the scope of a context - should be the same as the scope of a gss_ctx_id_t. - -2.1.8. Authentication tokens - - A token is a caller-opaque type that GSSAPI uses to maintain - synchronization between the context data structures at each end of a - GSSAPI security context. The token is a cryptographically protected - bit-string, generated by the underlying mechanism at one end of a - GSSAPI security context for use by the peer mechanism at the other - end. Encapsulation (if required) and transfer of the token are the - responsibility of the peer applications. A token is passed between - the GSSAPI and the application using the gss_buffer_t conventions. - -2.1.9. Status values - - One or more status codes are returned by each GSSAPI routine. Two - distinct sorts of status codes are returned. These are termed GSS - status codes and Mechanism status codes. - - - -Wray [Page 7] - -RFC 1509 GSSAPI - Overview and C bindings September 1993 - - -2.1.9.1. GSS status codes - - GSSAPI routines return GSS status codes as their OM_uint32 function - value. These codes indicate errors that are independent of the - underlying mechanism used to provide the security service. The - errors that can be indicated via a GSS status code are either generic - API routine errors (errors that are defined in the GSSAPI - specification) or calling errors (errors that are specific to these - bindings). - - A GSS status code can indicate a single fatal generic API error from - the routine and a single calling error. In addition, supplementary - status information may be indicated via the setting of bits in the - supplementary info field of a GSS status code. - - These errors are encoded into the 32-bit GSS status code as follows: - - MSB LSB - |------------------------------------------------------------| - | Calling Error | Routine Error | Supplementary Info | - |------------------------------------------------------------| - Bit 31 24 23 16 15 0 - - Hence if a GSSAPI routine returns a GSS status code whose upper 16 - bits contain a non-zero value, the call failed. If the calling error - field is non-zero, the invoking application's call of the routine was - erroneous. Calling errors are defined in table 5-1. If the routine - error field is non-zero, the routine failed for one of the routine- - specific reasons listed below in table 5-2. Whether or not the upper - 16 bits indicate a failure or a success, the routine may indicate - additional information by setting bits in the supplementary info - field of the status code. The meaning of individual bits is listed - below in table 5-3. - - Table 5-1 Calling Errors - - Name Value in Meaning - Field - GSS_S_CALL_INACCESSIBLE_READ 1 A required input - parameter could - not be read. - GSS_S_CALL_INACCESSIBLE_WRITE 2 A required output - parameter could - not be written. - GSS_S_CALL_BAD_STRUCTURE 3 A parameter was - malformed - - - - - -Wray [Page 8] - -RFC 1509 GSSAPI - Overview and C bindings September 1993 - - - Table 5-2 Routine Errors - - Name Value in Meaning - Field - - GSS_S_BAD_MECH 1 An unsupported mechanism was - requested - GSS_S_BAD_NAME 2 An invalid name was supplied - GSS_S_BAD_NAMETYPE 3 A supplied name was of an - unsupported type - GSS_S_BAD_BINDINGS 4 Incorrect channel bindings - were supplied - GSS_S_BAD_STATUS 5 An invalid status code was - supplied - - GSS_S_BAD_SIG 6 A token had an invalid - signature - GSS_S_NO_CRED 7 No credentials were supplied - GSS_S_NO_CONTEXT 8 No context has been - established - GSS_S_DEFECTIVE_TOKEN 9 A token was invalid - GSS_S_DEFECTIVE_CREDENTIAL 10 A credential was invalid - GSS_S_CREDENTIALS_EXPIRED 11 The referenced credentials - have expired - GSS_S_CONTEXT_EXPIRED 12 The context has expired - GSS_S_FAILURE 13 Miscellaneous failure - (see text) - - Table 5-3 Supplementary Status Bits - - Name Bit Number Meaning - GSS_S_CONTINUE_NEEDED 0 (LSB) The routine must be called - again to complete its - function. - See routine documentation for - detailed description. - GSS_S_DUPLICATE_TOKEN 1 The token was a duplicate of - an earlier token - GSS_S_OLD_TOKEN 2 The token's validity period - has expired - GSS_S_UNSEQ_TOKEN 3 A later token has already been - processed - - The routine documentation also uses the name GSS_S_COMPLETE, which is - a zero value, to indicate an absence of any API errors or - supplementary information bits. - - - - - -Wray [Page 9] - -RFC 1509 GSSAPI - Overview and C bindings September 1993 - - - All GSS_S_xxx symbols equate to complete OM_uint32 status codes, - rather than to bitfield values. For example, the actual value of the - symbol GSS_S_BAD_NAMETYPE (value 3 in the routine error field) is 3 - << 16. - - The macros GSS_CALLING_ERROR(), GSS_ROUTINE_ERROR() and - GSS_SUPPLEMENTARY_INFO() are provided, each of which takes a GSS - status code and removes all but the relevant field. For example, the - value obtained by applying GSS_ROUTINE_ERROR to a status code removes - the calling errors and supplementary info fields, leaving only the - routine errors field. The values delivered by these macros may be - directly compared with a GSS_S_xxx symbol of the appropriate type. - The macro GSS_ERROR() is also provided, which when applied to a GSS - status code returns a non-zero value if the status code indicated a - calling or routine error, and a zero value otherwise. - - A GSSAPI implementation may choose to signal calling errors in a - platform-specific manner instead of, or in addition to the routine - value; routine errors and supplementary info should be returned via - routine status values only. - -2.1.9.2. Mechanism-specific status codes - - GSSAPI routines return a minor_status parameter, which is used to - indicate specialized errors from the underlying security mechanism. - This parameter may contain a single mechanism-specific error, - indicated by a OM_uint32 value. - - The minor_status parameter will always be set by a GSSAPI routine, - even if it returns a calling error or one of the generic API errors - indicated above as fatal, although other output parameters may remain - unset in such cases. However, output parameters that are expected to - return pointers to storage allocated by a routine must always set set - by the routine, even in the event of an error, although in such cases - the GSSAPI routine may elect to set the returned parameter value to - NULL to indicate that no storage was actually allocated. Any length - field associated with such pointers (as in a gss_buffer_desc - structure) should also be set to zero in such cases. - - The GSS status code GSS_S_FAILURE is used to indicate that the - underlying mechanism detected an error for which no specific GSS - status code is defined. The mechanism status code will provide more - details about the error. - -2.1.10. Names - - A name is used to identify a person or entity. GSSAPI authenticates - the relationship between a name and the entity claiming the name. - - - -Wray [Page 10] - -RFC 1509 GSSAPI - Overview and C bindings September 1993 - - - Two distinct representations are defined for names: - - (a) A printable form, for presentation to a user - - (b) An internal form, for presentation at the API - - The syntax of a printable name is defined by the GSSAPI - implementation, and may be dependent on local system configuration, - or on individual user preference. The internal form provides a - canonical representation of the name that is independent of - configuration. - - A given GSSAPI implementation may support names drawn from multiple - namespaces. In such an implementation, the internal form of the name - must include fields that identify the namespace from which the name - is drawn. The namespace from which a printable name is drawn is - specified by an accompanying object identifier. - - Routines (gss_import_name and gss_display_name) are provided to - convert names between their printable representations and the - gss_name_t type. gss_import_name may support multiple syntaxes for - each supported namespace, allowing users the freedom to choose a - preferred name representation. gss_display_name should use an - implementation-chosen preferred syntax for each supported name-type. - - Comparison of internal-form names is accomplished via the - gss_compare_names routine. This removes the need for the application - program to understand the syntaxes of the various printable names - that a given GSSAPI implementation may support. - - Storage is allocated by routines that return gss_name_t values. A - procedure, gss_release_name, is provided to free storage associated - with a name. - -2.1.11. Channel Bindings - - GSSAPI supports the use of user-specified tags to identify a given - context to the peer application. These tags are used to identify the - particular communications channel that carries the context. Channel - bindings are communicated to the GSSAPI using the following - structure: - - - - - - - - - - -Wray [Page 11] - -RFC 1509 GSSAPI - Overview and C bindings September 1993 - - - typedef struct gss_channel_bindings_struct { - OM_uint32 initiator_addrtype; - gss_buffer_desc initiator_address; - OM_uint32 acceptor_addrtype; - gss_buffer_desc acceptor_address; - gss_buffer_desc application_data; - } *gss_channel_bindings_t; - - The initiator_addrtype and acceptor_addrtype fields denote the type - of addresses contained in the initiator_address and acceptor_address - buffers. The address type should be one of the following: - - GSS_C_AF_UNSPEC Unspecified address type - GSS_C_AF_LOCAL Host-local address type - GSS_C_AF_INET DARPA Internet address type - GSS_C_AF_IMPLINK ARPAnet IMP address type (eg IP) - GSS_C_AF_PUP pup protocols (eg BSP) address type - GSS_C_AF_CHAOS MIT CHAOS protocol address type - GSS_C_AF_NS XEROX NS address type - GSS_C_AF_NBS nbs address type - GSS_C_AF_ECMA ECMA address type - GSS_C_AF_DATAKIT datakit protocols address type - GSS_C_AF_CCITT CCITT protocols (eg X.25) - GSS_C_AF_SNA IBM SNA address type - GSS_C_AF_DECnet DECnet address type - GSS_C_AF_DLI Direct data link interface address type - GSS_C_AF_LAT LAT address type - GSS_C_AF_HYLINK NSC Hyperchannel address type - GSS_C_AF_APPLETALK AppleTalk address type - GSS_C_AF_BSC BISYNC 2780/3780 address type - GSS_C_AF_DSS Distributed system services address type - GSS_C_AF_OSI OSI TP4 address type - GSS_C_AF_X25 X25 - GSS_C_AF_NULLADDR No address specified - - Note that these name address families rather than specific addressing - formats. For address families that contain several alternative - address forms, the initiator_address and acceptor_address fields must - contain sufficient information to determine which address form is - used. When not otherwise specified, addresses should be specified in - network byte-order. - - Conceptually, the GSSAPI concatenates the initiator_addrtype, - initiator_address, acceptor_addrtype, acceptor_address and - application_data to form an octet string. The mechanism signs this - octet string, and binds the signature to the context establishment - token emitted by gss_init_sec_context. The same bindings are - presented by the context acceptor to gss_accept_sec_context, and a - - - -Wray [Page 12] - -RFC 1509 GSSAPI - Overview and C bindings September 1993 - - - signature is calculated in the same way. The calculated signature is - compared with that found in the token, and if the signatures differ, - gss_accept_sec_context will return a GSS_S_BAD_BINDINGS error, and - the context will not be established. Some mechanisms may include the - actual channel binding data in the token (rather than just a - signature); applications should therefore not use confidential data - as channel-binding components. Individual mechanisms may impose - additional constraints on addresses and address types that may appear - in channel bindings. For example, a mechanism may verify that the - initiator_address field of the channel bindings presented to - gss_init_sec_context contains the correct network address of the host - system. - -2.1.12. Optional parameters - - Various parameters are described as optional. This means that they - follow a convention whereby a default value may be requested. The - following conventions are used for omitted parameters. These - conventions apply only to those parameters that are explicitly - documented as optional. - -2.1.12.1. gss_buffer_t types - - Specify GSS_C_NO_BUFFER as a value. For an input parameter this - signifies that default behavior is requested, while for an output - parameter it indicates that the information that would be returned - via the parameter is not required by the application. - -2.1.12.2. Integer types (input) - - Individual parameter documentation lists values to be used to - indicate default actions. - -2.1.12.3. Integer types (output) - - Specify NULL as the value for the pointer. - -2.1.12.4. Pointer types - - Specify NULL as the value. - -2.1.12.5. Object IDs - - Specify GSS_C_NULL_OID as the value. - -2.1.12.6. Object ID Sets - - Specify GSS_C_NULL_OID_SET as the value. - - - -Wray [Page 13] - -RFC 1509 GSSAPI - Overview and C bindings September 1993 - - -2.1.12.7. Credentials - - Specify GSS_C_NO_CREDENTIAL to use the default credential handle. - -2.1.12.8. Channel Bindings - - Specify GSS_C_NO_CHANNEL_BINDINGS to indicate that channel bindings - are not to be used. - -3. GSSAPI routine descriptions - -2.1. gss_acquire_cred - - OM_uint32 gss_acquire_cred ( - OM_uint32 * minor_status, - gss_name_t desired_name, - OM_uint32 time_req, - gss_OID_set desired_mechs, - int cred_usage, - gss_cred_id_t * output_cred_handle, - gss_OID_set * actual_mechs, - OM_int32 * time_rec) - Purpose: - - Allows an application to acquire a handle for a pre-existing - credential by name. GSSAPI implementations must impose a local - access-control policy on callers of this routine to prevent - unauthorized callers from acquiring credentials to which they are not - entitled. This routine is not intended to provide a "login to the - network" function, as such a function would result in the creation of - new credentials rather than merely acquiring a handle to existing - credentials. Such functions, if required, should be defined in - implementation-specific extensions to the API. - - If credential acquisition is time-consuming for a mechanism, the - mechanism may chooses to delay the actual acquisition until the - credential is required (e.g., by gss_init_sec_context or - gss_accept_sec_context). Such mechanism-specific implementation - decisions should be invisible to the calling application; thus a call - of gss_inquire_cred immediately following the call of - gss_acquire_cred must return valid credential data, and may therefore - incur the overhead of a deferred credential acquisition. - - Parameters: - - desired_name gss_name_t, read - Name of principal whose credential - should be acquired - - - -Wray [Page 14] - -RFC 1509 GSSAPI - Overview and C bindings September 1993 - - - time_req integer, read - number of seconds that credentials - should remain valid - - desired_mechs Set of Object IDs, read - set of underlying security mechanisms that - may be used. GSS_C_NULL_OID_SET may be used - to obtain an implementation-specific default. - - cred_usage integer, read - GSS_C_BOTH - Credentials may be used - either to initiate or accept - security contexts. - GSS_C_INITIATE - Credentials will only be - used to initiate security - contexts. - GSS_C_ACCEPT - Credentials will only be used to - accept security contexts. - - output_cred_handle gss_cred_id_t, modify - The returned credential handle. - - actual_mechs Set of Object IDs, modify, optional - The set of mechanisms for which the - credential is valid. Specify NULL - if not required. - - time_rec Integer, modify, optional - Actual number of seconds for which the - returned credentials will remain valid. If the - implementation does not support expiration of - credentials, the value GSS_C_INDEFINITE will - be returned. Specify NULL if not required - - minor_status Integer, modify - Mechanism specific status code. - Function value: - - GSS status code: - - GSS_S_COMPLETE Successful completion - - GSS_S_BAD_MECH Unavailable mechanism requested - - GSS_S_BAD_NAMETYPE Type contained within desired_name parameter is - not supported - - GSS_S_BAD_NAME Value supplied for desired_name parameter is - - - -Wray [Page 15] - -RFC 1509 GSSAPI - Overview and C bindings September 1993 - - - ill-formed. - - GSS_S_FAILURE Unspecified failure. The minor_status parameter - contains more detailed information - -3.2. gss_release_cred - - OM_uint32 gss_release_cred ( - OM_uint32 * minor_status, - gss_cred_id_t * cred_handle) - - Purpose: - - Informs GSSAPI that the specified credential handle is no longer - required by the process. When all processes have released a - credential, it will be deleted. - - Parameters: - - cred_handle gss_cred_id_t, modify, optional - buffer containing opaque credential - handle. If GSS_C_NO_CREDENTIAL is supplied, - the default credential will be released - - minor_status integer, modify - Mechanism specific status code. - - Function value: - - GSS status code: - - GSS_S_COMPLETE Successful completion - - GSS_S_NO_CRED Credentials could not be accessed. - - - - - - - - - - - - - - - - - -Wray [Page 16] - -RFC 1509 GSSAPI - Overview and C bindings September 1993 - - -3.3. gss_init_sec_context - - OM_uint32 gss_init_sec_context ( - OM_uint32 * minor_status, - gss_cred_id_t claimant_cred_handle, - gss_ctx_id_t * context_handle, - gss_name_t target_name, - gss_OID mech_type, - int req_flags, - int time_req, - gss_channel_bindings_t - input_chan_bindings, - gss_buffer_t input_token - gss_OID * actual_mech_type, - gss_buffer_t output_token, - int * ret_flags, - OM_uint32 * time_rec ) - - Purpose: - - Initiates the establishment of a security context between the - application and a remote peer. Initially, the input_token parameter - should be specified as GSS_C_NO_BUFFER. The routine may return a - output_token which should be transferred to the peer application, - where the peer application will present it to gss_accept_sec_context. - If no token need be sent, gss_init_sec_context will indicate this by - setting the length field of the output_token argument to zero. To - complete the context establishment, one or more reply tokens may be - required from the peer application; if so, gss_init_sec_context will - return a status indicating GSS_S_CONTINUE_NEEDED in which case it - should be called again when the reply token is received from the peer - application, passing the token to gss_init_sec_context via the - input_token parameters. - - The values returned via the ret_flags and time_rec parameters are not - defined unless the routine returns GSS_S_COMPLETE. - - Parameters: - - claimant_cred_handle gss_cred_id_t, read, optional - handle for credentials claimed. Supply - GSS_C_NO_CREDENTIAL to use default - credentials. - - context_handle gss_ctx_id_t, read/modify - context handle for new context. Supply - GSS_C_NO_CONTEXT for first call; use value - returned by first call in continuation calls. - - - -Wray [Page 17] - -RFC 1509 GSSAPI - Overview and C bindings September 1993 - - - target_name gss_name_t, read - Name of target - - mech_type OID, read, optional - Object ID of desired mechanism. Supply - GSS_C_NULL_OID to obtain an implementation - specific default - - req_flags bit-mask, read - Contains four independent flags, each of - which requests that the context support a - specific service option. Symbolic - names are provided for each flag, and the - symbolic names corresponding to the required - flags should be logically-ORed - together to form the bit-mask value. The - flags are: - - GSS_C_DELEG_FLAG - True - Delegate credentials to remote peer - False - Don't delegate - GSS_C_MUTUAL_FLAG - True - Request that remote peer - authenticate itself - False - Authenticate self to remote peer - only - GSS_C_REPLAY_FLAG - True - Enable replay detection for signed - or sealed messages - False - Don't attempt to detect - replayed messages - GSS_C_SEQUENCE_FLAG - True - Enable detection of out-of-sequence - signed or sealed messages - False - Don't attempt to detect - out-of-sequence messages - - time_req integer, read - Desired number of seconds for which context - should remain valid. Supply 0 to request a - default validity period. - - input_chan_bindings channel bindings, read - Application-specified bindings. Allows - application to securely bind channel - identification information to the security - context. - - - - -Wray [Page 18] - -RFC 1509 GSSAPI - Overview and C bindings September 1993 - - - input_token buffer, opaque, read, optional (see text) - Token received from peer application. - Supply GSS_C_NO_BUFFER on initial call. - - actual_mech_type OID, modify - actual mechanism used. - - output_token buffer, opaque, modify - token to be sent to peer application. If - the length field of the returned buffer is - zero, no token need be sent to the peer - application. - - ret_flags bit-mask, modify - Contains six independent flags, each of which - indicates that the context supports a specific - service option. Symbolic names are provided - for each flag, and the symbolic names - corresponding to the required flags should be - logically-ANDed with the ret_flags value to test - whether a given option is supported by the - context. The flags are: - - GSS_C_DELEG_FLAG - True - Credentials were delegated to - the remote peer - False - No credentials were delegated - GSS_C_MUTUAL_FLAG - True - Remote peer has been asked to - authenticated itself - False - Remote peer has not been asked to - authenticate itself - GSS_C_REPLAY_FLAG - True - replay of signed or sealed messages - will be detected - False - replayed messages will not be - detected - GSS_C_SEQUENCE_FLAG - True - out-of-sequence signed or sealed - messages will be detected - False - out-of-sequence messages will not - be detected - GSS_C_CONF_FLAG - True - Confidentiality service may be - invoked by calling seal routine - False - No confidentiality service (via - seal) available. seal will provide - message encapsulation, data-origin - - - -Wray [Page 19] - -RFC 1509 GSSAPI - Overview and C bindings September 1993 - - - authentication and integrity - services only. - GSS_C_INTEG_FLAG - True - Integrity service may be invoked by - calling either gss_sign or gss_seal - routines. - False - Per-message integrity service - unavailable. - - time_rec integer, modify, optional - number of seconds for which the context - will remain valid. If the implementation does - not support credential expiration, the value - GSS_C_INDEFINITE will be returned. Specify - NULL if not required. - - minor_status integer, modify - Mechanism specific status code. - - Function value: - - GSS status code: - - GSS_S_COMPLETE Successful completion - - GSS_S_CONTINUE_NEEDED Indicates that a token from the peer - application is required to complete thecontext, and - that gss_init_sec_context must be called again with - that token. - - GSS_S_DEFECTIVE_TOKEN Indicates that consistency checks performed on - the input_token failed - - GSS_S_DEFECTIVE_CREDENTIAL Indicates that consistency checks - performed on the credential failed. - - GSS_S_NO_CRED The supplied credentials were not valid for context - initiation, or the credential handle did not - reference any credentials. - - GSS_S_CREDENTIALS_EXPIRED The referenced credentials have expired - - GSS_S_BAD_BINDINGS The input_token contains different channel - bindings to those specified via the - input_chan_bindings parameter - - GSS_S_BAD_SIG The input_token contains an invalid signature, or a - signature that could not be verified - - - -Wray [Page 20] - -RFC 1509 GSSAPI - Overview and C bindings September 1993 - - - GSS_S_OLD_TOKEN The input_token was too old. This is a fatal error - during context establishment - - GSS_S_DUPLICATE_TOKEN The input_token is valid, but is a duplicate of - a token already processed. This is a fatal error - during context establishment. - - GSS_S_NO_CONTEXT Indicates that the supplied context handle did not - refer to a valid context - - GSS_S_BAD_NAMETYPE The provided target_name parameter contained an - invalid or unsupported type of name - - GSS_S_BAD_NAME The provided target_name parameter was ill-formed. - - GSS_S_FAILURE Failure. See minor_status for more information - -3.4. gss_accept_sec_context - - OM_uint32 gss_accept_sec_context ( - OM_uint32 * minor_status, - gss_ctx_id_t * context_handle, - gss_cred_id_t verifier_cred_handle, - gss_buffer_t input_token_buffer - gss_channel_bindings_t - input_chan_bindings, - gss_name_t * src_name, - gss_OID * mech_type, - gss_buffer_t output_token, - int * ret_flags, - OM_uint32 * time_rec, - gss_cred_id_t * delegated_cred_handle) - - Purpose: - - Allows a remotely initiated security context between the application - and a remote peer to be established. The routine may return a - output_token which should be transferred to the peer application, - where the peer application will present it to gss_init_sec_context. - If no token need be sent, gss_accept_sec_context will indicate this - by setting the length field of the output_token argument to zero. To - complete the context establishment, one or more reply tokens may be - required from the peer application; if so, gss_accept_sec_context - will return a status flag of GSS_S_CONTINUE_NEEDED, in which case it - should be called again when the reply token is received from the peer - application, passing the token to gss_accept_sec_context via the - input_token parameters. - - - - -Wray [Page 21] - -RFC 1509 GSSAPI - Overview and C bindings September 1993 - - - The values returned via the src_name, ret_flags, time_rec, and - delegated_cred_handle parameters are not defined unless the routine - returns GSS_S_COMPLETE. - - Parameters: - - context_handle gss_ctx_id_t, read/modify - context handle for new context. Supply - GSS_C_NO_CONTEXT for first call; use value - returned in subsequent calls. - - verifier_cred_handle gss_cred_id_t, read, optional - Credential handle claimed by context - acceptor. - Specify GSS_C_NO_CREDENTIAL to use default - credentials. If GSS_C_NO_CREDENTIAL is - specified, but the caller has no default - credentials established, an - implementation-defined default credential - may be used. - - input_token_buffer buffer, opaque, read - token obtained from remote application - - input_chan_bindings channel bindings, read - Application-specified bindings. Allows - application to securely bind channel - identification information to the security - context. - - src_name gss_name_t, modify, optional - Authenticated name of context initiator. - After use, this name should be deallocated by - passing it to gss_release_name. If not required, - specify NULL. - - mech_type Object ID, modify - Security mechanism used. The returned - OID value will be a pointer into static - storage, and should be treated as read-only - by the caller. - - output_token buffer, opaque, modify - Token to be passed to peer application. If the - length field of the returned token buffer is 0, - then no token need be passed to the peer - application. - - - - -Wray [Page 22] - -RFC 1509 GSSAPI - Overview and C bindings September 1993 - - - ret_flags bit-mask, modify - Contains six independent flags, each of - which indicates that the context supports a - specific service option. Symbolic names are - provided for each flag, and the symbolic names - corresponding to the required flags - should be logically-ANDed with the ret_flags - value to test whether a given option is - supported by the context. The flags are: - GSS_C_DELEG_FLAG - True - Delegated credentials are available - via the delegated_cred_handle - parameter - False - No credentials were delegated - GSS_C_MUTUAL_FLAG - True - Remote peer asked for mutual - authentication - False - Remote peer did not ask for mutual - authentication - GSS_C_REPLAY_FLAG - True - replay of signed or sealed messages - will be detected - False - replayed messages will not be - detected - GSS_C_SEQUENCE_FLAG - True - out-of-sequence signed or sealed - messages will be detected - False - out-of-sequence messages will not - be detected - GSS_C_CONF_FLAG - True - Confidentiality service may be - invoked by calling seal routine - False - No confidentiality service (via - seal) available. seal will - provide message encapsulation, - data-origin authentication and - integrity services only. - GSS_C_INTEG_FLAG - True - Integrity service may be invoked - by calling either gss_sign or - gss_seal routines. - False - Per-message integrity service - unavailable. - - time_rec integer, modify, optional - number of seconds for which the context - will remain valid. Specify NULL if not required. - - - - -Wray [Page 23] - -RFC 1509 GSSAPI - Overview and C bindings September 1993 - - - delegated_cred_handle - gss_cred_id_t, modify - credential handle for credentials received from - context initiator. Only valid if deleg_flag in - ret_flags is true. - - minor_status integer, modify - Mechanism specific status code. - - Function value: - - GSS status code: - - GSS_S_COMPLETE Successful completion - - GSS_S_CONTINUE_NEEDED Indicates that a token from the peer - application is required to complete the context, - and that gss_accept_sec_context must be called - again with that token. - - GSS_S_DEFECTIVE_TOKEN Indicates that consistency checks - performed on the input_token failed. - - GSS_S_DEFECTIVE_CREDENTIAL Indicates that consistency checks - performed on the credential failed. - - GSS_S_NO_CRED The supplied credentials were not valid for - context acceptance, or the credential handle - did not reference any credentials. - - GSS_S_CREDENTIALS_EXPIRED The referenced credentials have - expired. - - GSS_S_BAD_BINDINGS The input_token contains different channel - bindings to those specified via the - input_chan_bindings parameter. - - GSS_S_NO_CONTEXT Indicates that the supplied context handle did - not refer to a valid context. - - GSS_S_BAD_SIG The input_token contains an invalid signature. - - GSS_S_OLD_TOKEN The input_token was too old. This is a fatal - error during context establishment. - - GSS_S_DUPLICATE_TOKEN The input_token is valid, but is a - duplicate of a token already processed. This - is a fatal error during context establishment. - - - -Wray [Page 24] - -RFC 1509 GSSAPI - Overview and C bindings September 1993 - - - GSS_S_FAILURE Failure. See minor_status for more information. - -3.5. gss_process_context_token - - OM_uint32 gss_process_context_token ( - OM_uint32 * minor_status, - gss_ctx_id_t context_handle, - gss_buffer_t token_buffer) - - Purpose: - - Provides a way to pass a token to the security service. Usually, - tokens are associated either with context establishment (when they - would be passed to gss_init_sec_context or gss_accept_sec_context) or - with per-message security service (when they would be passed to - gss_verify or gss_unseal). Occasionally, tokens may be received at - other times, and gss_process_context_token allows such tokens to be - passed to the underlying security service for processing. At - present, such additional tokens may only be generated by - gss_delete_sec_context. GSSAPI implementation may use this service - to implement deletion of the security context. - - Parameters: - - context_handle gss_ctx_id_t, read - context handle of context on which token is to - be processed - - token_buffer buffer, opaque, read - pointer to first byte of token to process - - minor_status integer, modify - Implementation specific status code. - - Function value: - - GSS status code: - - GSS_S_COMPLETE Successful completion - - GSS_S_DEFECTIVE_TOKEN Indicates that consistency checks - performed on the token failed - - GSS_S_FAILURE Failure. See minor_status for more information - - GSS_S_NO_CONTEXT The context_handle did not refer to a valid - context - - - - -Wray [Page 25] - -RFC 1509 GSSAPI - Overview and C bindings September 1993 - - -3.6. gss_delete_sec_context - - OM_uint32 gss_delete_sec_context ( - OM_uint32 * minor_status, - gss_ctx_id_t * context_handle, - gss_buffer_t output_token) - - Purpose: - - Delete a security context. gss_delete_sec_context will delete the - local data structures associated with the specified security context, - and generate an output_token, which when passed to the peer - gss_process_context_token will instruct it to do likewise. No - further security services may be obtained using the context specified - by context_handle. - - Parameters: - - minor_status integer, modify - Mechanism specific status code. - - context_handle gss_ctx_id_t, modify - context handle identifying context to delete. - - output_token buffer, opaque, modify - token to be sent to remote application to - instruct it to also delete the context - - Function value: - - GSS status code: - - GSS_S_COMPLETE Successful completion - - GSS_S_FAILURE Failure, see minor_status for more information - - GSS_S_NO_CONTEXT No valid context was supplied - -3.7. gss_context_time - - OM_uint32 gss_context_time ( - OM_uint32 * minor_status, - gss_ctx_id_t context_handle, - OM_uint32 * time_rec) - Purpose: - - Determines the number of seconds for which the specified context will - remain valid. - - - -Wray [Page 26] - -RFC 1509 GSSAPI - Overview and C bindings September 1993 - - - Parameters: - - minor_status integer, modify - Implementation specific status code. - - context_handle gss_ctx_id_t, read - Identifies the context to be interrogated. - - time_rec integer, modify - Number of seconds that the context will remain - valid. If the context has already expired, - zero will be returned. - Function value: - - GSS status code: - - GSS_S_COMPLETE Successful completion - - GSS_S_CONTEXT_EXPIRED The context has already expired - - GSS_S_CREDENTIALS_EXPIRED The context is recognized, but - associated credentials have expired - - GSS_S_NO_CONTEXT The context_handle parameter did not identify a - valid context - -3.8. gss_sign - - OM_uint32 gss_sign ( - OM_uint32 * minor_status, - gss_ctx_id_t context_handle, - int qop_req, - gss_buffer_t message_buffer, - gss_buffer_t msg_token) - Purpose: - - Generates a cryptographic signature for the supplied message, and - places the signature in a token for transfer to the peer application. - The qop_req parameter allows a choice between several cryptographic - algorithms, if supported by the chosen mechanism. - - Parameters: - - minor_status integer, modify - Implementation specific status code. - - context_handle gss_ctx_id_t, read - identifies the context on which the message - - - -Wray [Page 27] - -RFC 1509 GSSAPI - Overview and C bindings September 1993 - - - will be sent - - qop_req integer, read, optional - Specifies requested quality of protection. - Callers are encouraged, on portability grounds, - to accept the default quality of protection - offered by the chosen mechanism, which may be - requested by specifying GSS_C_QOP_DEFAULT for - this parameter. If an unsupported protection - strength is requested, gss_sign will return a - major_status of GSS_S_FAILURE. - - message_buffer buffer, opaque, read - message to be signed - - msg_token buffer, opaque, modify - buffer to receive token - - Function value: - - GSS status code: - - GSS_S_COMPLETE Successful completion - - GSS_S_CONTEXT_EXPIRED The context has already expired - - GSS_S_CREDENTIALS_EXPIRED The context is recognized, but - associated credentials have expired - - GSS_S_NO_CONTEXT The context_handle parameter did not identify a - valid context - - GSS_S_FAILURE Failure. See minor_status for more information. - -3.9. gss_verify - - OM_uint32 gss_verify ( - OM_uint32 * minor_status, - gss_ctx_id_t context_handle, - gss_buffer_t message_buffer, - gss_buffer_t token_buffer, - int * qop_state) - Purpose: - - Verifies that a cryptographic signature, contained in the token - parameter, fits the supplied message. The qop_state parameter allows - a message recipient to determine the strength of protection that was - applied to the message. - - - -Wray [Page 28] - -RFC 1509 GSSAPI - Overview and C bindings September 1993 - - - Parameters: - - minor_status integer, modify - Mechanism specific status code. - - context_handle gss_ctx_id_t, read - identifies the context on which the message - arrived - - message_buffer buffer, opaque, read - message to be verified - - token_buffer buffer, opaque, read - token associated with message - - qop_state integer, modify - quality of protection gained from signature - - Function value: - - GSS status code: - - GSS_S_COMPLETE Successful completion - - GSS_S_DEFECTIVE_TOKEN The token failed consistency checks - - GSS_S_BAD_SIG The signature was incorrect - - GSS_S_DUPLICATE_TOKEN The token was valid, and contained a correct - signature for the message, but it had already - been processed - - GSS_S_OLD_TOKEN The token was valid, and contained a correct - signature for the message, but it is too old - - GSS_S_UNSEQ_TOKEN The token was valid, and contained a correct - signature for the message, but has been - verified out of sequence; an earlier token has - been signed or sealed by the remote - application, but not yet been processed - locally. - - GSS_S_CONTEXT_EXPIRED The context has already expired - - GSS_S_CREDENTIALS_EXPIRED The context is recognized, but - associated credentials have expired - - - - - -Wray [Page 29] - -RFC 1509 GSSAPI - Overview and C bindings September 1993 - - - GSS_S_NO_CONTEXT The context_handle parameter did not identify a - valid context - - GSS_S_FAILURE Failure. See minor_status for more information. - -3.10. gss_seal - - OM_uint32 gss_seal ( - OM_uint32 * minor_status, - gss_ctx_id_t context_handle, - int conf_req_flag, - int qop_req - gss_buffer_t input_message_buffer, - int * conf_state, - gss_buffer_t output_message_buffer) - - Purpose: - - Cryptographically signs and optionally encrypts the specified - input_message. The output_message contains both the signature and - the message. The qop_req parameter allows a choice between several - cryptographic algorithms, if supported by the chosen mechanism. - - Parameters: - - minor_status integer, modify - Mechanism specific status code. - - context_handle gss_ctx_id_t, read - identifies the context on which the message - will be sent - - conf_req_flag boolean, read - True - Both confidentiality and integrity - services are requested - False - Only integrity service is requested - - qop_req integer, read, optional - Specifies required quality of protection. A - mechanism-specific default may be requested by - setting qop_req to GSS_C_QOP_DEFAULT. If an - unsupported protection strength is requested, - gss_seal will return a major_status of - GSS_S_FAILURE. - - input_message_buffer buffer, opaque, read - message to be sealed - - - - -Wray [Page 30] - -RFC 1509 GSSAPI - Overview and C bindings September 1993 - - - conf_state boolean, modify - True - Confidentiality, data origin - authentication and integrity services - have been applied - False - Integrity and data origin services only - has been applied. - - output_message_buffer buffer, opaque, modify - buffer to receive sealed message - - Function value: - - GSS status code: - - GSS_S_COMPLETE Successful completion - - GSS_S_CONTEXT_EXPIRED The context has already expired - - GSS_S_CREDENTIALS_EXPIRED The context is recognized, but - associated credentials have expired - - GSS_S_NO_CONTEXT The context_handle parameter did not identify a - valid context - - GSS_S_FAILURE Failure. See minor_status for more information. - -3.11. gss_unseal - - OM_uint32 gss_unseal ( - OM_uint32 * minor_status, - gss_ctx_id_t context_handle, - gss_buffer_t input_message_buffer, - gss_buffer_t output_message_buffer, - int * conf_state, - int * qop_state) - - Purpose: - - Converts a previously sealed message back to a usable form, verifying - the embedded signature. The conf_state parameter indicates whether - the message was encrypted; the qop_state parameter indicates the - strength of protection that was used to provide the confidentiality - and integrity services. - - Parameters: - - minor_status integer, modify - Mechanism specific status code. - - - -Wray [Page 31] - -RFC 1509 GSSAPI - Overview and C bindings September 1993 - - - context_handle gss_ctx_id_t, read - identifies the context on which the message - arrived - - input_message_buffer buffer, opaque, read - sealed message - - output_message_buffer buffer, opaque, modify - buffer to receive unsealed message - - conf_state boolean, modify - True - Confidentiality and integrity protection - were used - False - Inteegrity service only was used - - qop_state integer, modify - quality of protection gained from signature - - Function value: - - GSS status code: - - GSS_S_COMPLETE Successful completion - - GSS_S_DEFECTIVE_TOKEN The token failed consistency checks - - GSS_S_BAD_SIG The signature was incorrect - - GSS_S_DUPLICATE_TOKEN The token was valid, and contained a - correct signature for the message, but it had - already been processed - - GSS_S_OLD_TOKEN The token was valid, and contained a correct - signature for the message, but it is too old - - GSS_S_UNSEQ_TOKEN The token was valid, and contained a correct - signature for the message, but has been - verified out of sequence; an earlier token has - been signed or sealed by the remote - application, but not yet been processed - locally. - - GSS_S_CONTEXT_EXPIRED The context has already expired - - GSS_S_CREDENTIALS_EXPIRED The context is recognized, but - associated credentials have expired - - - - - -Wray [Page 32] - -RFC 1509 GSSAPI - Overview and C bindings September 1993 - - - GSS_S_NO_CONTEXT The context_handle parameter did not identify a - valid context - - GSS_S_FAILURE Failure. See minor_status for more information. - -3.12. gss_display_status - - OM_uint32 gss_display_status ( - OM_uint32 * minor_status, - int status_value, - int status_type, - gss_OID mech_type, - int * message_context, - gss_buffer_t status_string) - - Purpose: - - Allows an application to obtain a textual representation of a GSSAPI - status code, for display to the user or for logging purposes. Since - some status values may indicate multiple errors, applications may - need to call gss_display_status multiple times, each call generating - a single text string. The message_context parameter is used to - indicate which error message should be extracted from a given - status_value; message_context should be initialized to 0, and - gss_display_status will return a non-zero value if there are further - messages to extract. - - Parameters: - - minor_status integer, modify - Mechanism specific status code. - - status_value integer, read - Status value to be converted - - status_type integer, read - GSS_C_GSS_CODE - status_value is a GSS status - code - GSS_C_MECH_CODE - status_value is a mechanism - status code - - mech_type Object ID, read, optional - Underlying mechanism (used to interpret a - minor status value) Supply GSS_C_NULL_OID to - obtain the system default. - - message_context integer, read/modify - Should be initialized to zero by caller - - - -Wray [Page 33] - -RFC 1509 GSSAPI - Overview and C bindings September 1993 - - - on first call. If further messages are - contained in the status_value parameter, - message_context will be non-zero on return, - and this value should be passed back to - subsequent calls, along with the same - status_value, status_type and mech_type - parameters. - - status_string buffer, character string, modify - textual interpretation of the status_value - - Function value: - - GSS status code: - - GSS_S_COMPLETE Successful completion - - GSS_S_BAD_MECH Indicates that translation in accordance with - an unsupported mechanism type was requested - - GSS_S_BAD_STATUS The status value was not recognized, or the - status type was neither GSS_C_GSS_CODE nor - GSS_C_MECH_CODE. - - -3.13. gss_indicate_mechs - - OM_uint32 gss_indicate_mechs ( - OM_uint32 * minor_status, - gss_OID_set * mech_set) - - Purpose: - - Allows an application to determine which underlying security - mechanisms are available. - - Parameters: - - minor_status integer, modify - Mechanism specific status code. - - mech_set set of Object IDs, modify - set of implementation-supported mechanisms. - The returned gss_OID_set value will be a - pointer into static storage, and should be - treated as read-only by the caller. - - - - - -Wray [Page 34] - -RFC 1509 GSSAPI - Overview and C bindings September 1993 - - - Function value: - - GSS status code: - - GSS_S_COMPLETE Successful completion - -3.14. gss_compare_name - - OM_uint32 gss_compare_name ( - OM_uint32 * minor_status, - gss_name_t name1, - gss_name_t name2, - int * name_equal) - - Purpose: - - Allows an application to compare two internal-form names to determine - whether they refer to the same entity. - - Parameters: - - minor_status integer, modify - Mechanism specific status code. - - name1 gss_name_t, read - internal-form name - - name2 gss_name_t, read - internal-form name - - name_equal boolean, modify - True - names refer to same entity - False - names refer to different entities - (strictly, the names are not known to - refer to the same identity). - Function value: - - GSS status code: - - GSS_S_COMPLETE Successful completion - - GSS_S_BAD_NAMETYPE The type contained within either name1 or - name2 was unrecognized, or the names were of - incomparable types. - - GSS_S_BAD_NAME One or both of name1 or name2 was ill-formed - - - - - -Wray [Page 35] - -RFC 1509 GSSAPI - Overview and C bindings September 1993 - - -3.15. gss_display_name - - OM_uint32 gss_display_name ( - OM_uint32 * minor_status, - gss_name_t input_name, - gss_buffer_t output_name_buffer, - gss_OID * output_name_type) - - Purpose: - - Allows an application to obtain a textual representation of an opaque - internal-form name for display purposes. The syntax of a printable - name is defined by the GSSAPI implementation. - - Parameters: - - minor_status integer, modify - Mechanism specific status code. - - input_name gss_name_t, read - name to be displayed - - output_name_buffer buffer, character-string, modify - buffer to receive textual name string - - output_name_type Object ID, modify - The type of the returned name. The returned - gss_OID will be a pointer into static storage, - and should be treated as read-only by the caller - - Function value: - - GSS status code: - - GSS_S_COMPLETE Successful completion - - GSS_S_BAD_NAMETYPE The type of input_name was not recognized - - GSS_S_BAD_NAME input_name was ill-formed - -3.16. gss_import_name - - OM_uint32 gss_import_name ( - OM_uint32 * minor_status, - gss_buffer_t input_name_buffer, - gss_OID input_name_type, - gss_name_t * output_name) - - - - -Wray [Page 36] - -RFC 1509 GSSAPI - Overview and C bindings September 1993 - - - Purpose: - - Convert a printable name to internal form. - - Parameters: - - minor_status integer, modify - Mechanism specific status code - - input_name_buffer buffer, character-string, read - buffer containing printable name to convert - - input_name_type Object ID, read, optional - Object Id specifying type of printable - name. Applications may specify either - GSS_C_NULL_OID to use a local system-specific - printable syntax, or an OID registered by the - GSSAPI implementation to name a particular - namespace. - - output_name gss_name_t, modify - returned name in internal form - - Function value: - - GSS status code - - GSS_S_COMPLETE Successful completion - - GSS_S_BAD_NAMETYPE The input_name_type was unrecognized - - GSS_S_BAD_NAME The input_name parameter could not be - interpreted as a name of the specified type - -3.17. gss_release_name - - OM_uint32 gss_release_name ( - OM_uint32 * minor_status, - gss_name_t * name) - - Purpose: - - Free GSSAPI-allocated storage associated with an internal form name. - - Parameters: - - minor_status integer, modify - Mechanism specific status code - - - -Wray [Page 37] - -RFC 1509 GSSAPI - Overview and C bindings September 1993 - - - name gss_name_t, modify - The name to be deleted - - Function value: - - GSS status code - - GSS_S_COMPLETE Successful completion - - GSS_S_BAD_NAME The name parameter did not contain a valid name - -3.18. gss_release_buffer - - OM_uint32 gss_release_buffer ( - OM_uint32 * minor_status, - gss_buffer_t buffer) - - Purpose: - - Free storage associated with a buffer format name. The storage must - have been allocated by a GSSAPI routine. In addition to freeing the - associated storage, the routine will zero the length field in the - buffer parameter. - - Parameters: - - minor_status integer, modify - Mechanism specific status code - - buffer buffer, modify - The storage associated with the buffer will be - deleted. The gss_buffer_desc object will not - be freed, but its length field will be zeroed. - - Function value: - - GSS status code - - GSS_S_COMPLETE Successful completion - -3.19. gss_release_oid_set - - OM_uint32 gss_release_oid_set ( - OM_uint32 * minor_status, - gss_OID_set * set) - - Purpose: - - - - -Wray [Page 38] - -RFC 1509 GSSAPI - Overview and C bindings September 1993 - - - Free storage associated with a gss_OID_set object. The storage must - have been allocated by a GSSAPI routine. - - Parameters: - - minor_status integer, modify - Mechanism specific status code - - set Set of Object IDs, modify - The storage associated with the gss_OID_set - will be deleted. - - Function value: - - GSS status code - - GSS_S_COMPLETE Successful completion - -3.20. gss_inquire_cred - - OM_uint32 gss_inquire_cred ( - OM_uint32 * minor_status, - gss_cred_id_t cred_handle, - gss_name_t * name, - OM_uint32 * lifetime, - int * cred_usage, - gss_OID_set * mechanisms ) - - Purpose: - - Obtains information about a credential. The caller must already have - obtained a handle that refers to the credential. - - Parameters: - - minor_status integer, modify - Mechanism specific status code - - cred_handle gss_cred_id_t, read - A handle that refers to the target credential. - Specify GSS_C_NO_CREDENTIAL to inquire about - the default credential. - - name gss_name_t, modify - The name whose identity the credential asserts. - Specify NULL if not required. - - lifetime Integer, modify - - - -Wray [Page 39] - -RFC 1509 GSSAPI - Overview and C bindings September 1993 - - - The number of seconds for which the credential - will remain valid. If the credential has - expired, this parameter will be set to zero. - If the implementation does not support - credential expiration, the value - GSS_C_INDEFINITE will be returned. Specify - NULL if not required. - - cred_usage Integer, modify - How the credential may be used. One of the - following: - GSS_C_INITIATE - GSS_C_ACCEPT - GSS_C_BOTH - Specify NULL if not required. - - mechanisms gss_OID_set, modify - Set of mechanisms supported by the credential. - Specify NULL if not required. - - Function value: - - GSS status code - - GSS_S_COMPLETE Successful completion - - GSS_S_NO_CRED The referenced credentials could not be - accessed. - - GSS_S_DEFECTIVE_CREDENTIAL The referenced credentials were - invalid. - - GSS_S_CREDENTIALS_EXPIRED The referenced credentials have expired. - If the lifetime parameter was not passed as - NULL, it will be set to 0. - - - #ifndef GSSAPI_H_ - #define GSSAPI_H_ - - /* - * First, define the platform-dependent types. - */ - typedef OM_uint32; - typedef gss_ctx_id_t; - typedef gss_cred_id_t; - typedef gss_name_t; - - - - -Wray [Page 40] - -RFC 1509 GSSAPI - Overview and C bindings September 1993 - - - /* - * Note that a platform supporting the xom.h X/Open header file - * may make use of that header for the definitions of OM_uint32 - * and the structure to which gss_OID_desc equates. - */ - - typedef struct gss_OID_desc_struct { - OM_uint32 length; - void *elements; - } gss_OID_desc, *gss_OID; - - typedef struct gss_OID_set_desc_struct { - int count; - gss_OID elements; - } gss_OID_set_desc, *gss_OID_set; - - typedef struct gss_buffer_desc_struct { - size_t length; - void *value; - } gss_buffer_desc, *gss_buffer_t; - - typedef struct gss_channel_bindings_struct { - OM_uint32 initiator_addrtype; - gss_buffer_desc initiator_address; - OM_uint32 acceptor_addrtype; - gss_buffer_desc acceptor_address; - gss_buffer_desc application_data; - } *gss_channel_bindings_t; - - - /* - * Six independent flags each of which indicates that a context - * supports a specific service option. - */ - #define GSS_C_DELEG_FLAG 1 - #define GSS_C_MUTUAL_FLAG 2 - #define GSS_C_REPLAY_FLAG 4 - #define GSS_C_SEQUENCE_FLAG 8 - #define GSS_C_CONF_FLAG 16 - #define GSS_C_INTEG_FLAG 32 - - - /* - * Credential usage options - */ - #define GSS_C_BOTH 0 - #define GSS_C_INITIATE 1 - #define GSS_C_ACCEPT 2 - - - -Wray [Page 41] - -RFC 1509 GSSAPI - Overview and C bindings September 1993 - - - /* - * Status code types for gss_display_status - */ - #define GSS_C_GSS_CODE 1 - #define GSS_C_MECH_CODE 2 - - /* - * The constant definitions for channel-bindings address families - */ - #define GSS_C_AF_UNSPEC 0; - #define GSS_C_AF_LOCAL 1; - #define GSS_C_AF_INET 2; - #define GSS_C_AF_IMPLINK 3; - #define GSS_C_AF_PUP 4; - #define GSS_C_AF_CHAOS 5; - #define GSS_C_AF_NS 6; - #define GSS_C_AF_NBS 7; - #define GSS_C_AF_ECMA 8; - #define GSS_C_AF_DATAKIT 9; - #define GSS_C_AF_CCITT 10; - #define GSS_C_AF_SNA 11; - #define GSS_C_AF_DECnet 12; - #define GSS_C_AF_DLI 13; - #define GSS_C_AF_LAT 14; - #define GSS_C_AF_HYLINK 15; - #define GSS_C_AF_APPLETALK 16; - #define GSS_C_AF_BSC 17; - #define GSS_C_AF_DSS 18; - #define GSS_C_AF_OSI 19; - #define GSS_C_AF_X25 21; - - #define GSS_C_AF_NULLADDR 255; - - #define GSS_C_NO_BUFFER ((gss_buffer_t) 0) - #define GSS_C_NULL_OID ((gss_OID) 0) - #define GSS_C_NULL_OID_SET ((gss_OID_set) 0) - #define GSS_C_NO_CONTEXT ((gss_ctx_id_t) 0) - #define GSS_C_NO_CREDENTIAL ((gss_cred_id_t) 0) - #define GSS_C_NO_CHANNEL_BINDINGS ((gss_channel_bindings_t) 0) - #define GSS_C_EMPTY_BUFFER {0, NULL} - - /* - * Define the default Quality of Protection for per-message - * services. Note that an implementation that offers multiple - * levels of QOP may either reserve a value (for example zero, - * as assumed here) to mean "default protection", or alternatively - * may simply equate GSS_C_QOP_DEFAULT to a specific explicit QOP - * value. - - - -Wray [Page 42] - -RFC 1509 GSSAPI - Overview and C bindings September 1993 - - - */ - #define GSS_C_QOP_DEFAULT 0 - - /* - * Expiration time of 2^32-1 seconds means infinite lifetime for a - * credential or security context - */ - #define GSS_C_INDEFINITE 0xfffffffful - - - /* Major status codes */ - - #define GSS_S_COMPLETE 0 - - /* - * Some "helper" definitions to make the status code macros obvious. - */ - #define GSS_C_CALLING_ERROR_OFFSET 24 - #define GSS_C_ROUTINE_ERROR_OFFSET 16 - #define GSS_C_SUPPLEMENTARY_OFFSET 0 - #define GSS_C_CALLING_ERROR_MASK 0377ul - #define GSS_C_ROUTINE_ERROR_MASK 0377ul - #define GSS_C_SUPPLEMENTARY_MASK 0177777ul - - /* - * The macros that test status codes for error conditions - */ - #define GSS_CALLING_ERROR(x) \ - (x & (GSS_C_CALLING_ERROR_MASK << GSS_C_CALLING_ERROR_OFFSET)) - #define GSS_ROUTINE_ERROR(x) \ - (x & (GSS_C_ROUTINE_ERROR_MASK << GSS_C_ROUTINE_ERROR_OFFSET)) - #define GSS_SUPPLEMENTARY_INFO(x) \ - (x & (GSS_C_SUPPLEMENTARY_MASK << GSS_C_SUPPLEMENTARY_OFFSET)) - #define GSS_ERROR(x) \ - ((GSS_CALLING_ERROR(x) != 0) || (GSS_ROUTINE_ERROR(x) != 0)) - - - /* - * Now the actual status code definitions - */ - - /* - * Calling errors: - */ - #define GSS_S_CALL_INACCESSIBLE_READ \ - (1ul << GSS_C_CALLING_ERROR_OFFSET) - #define GSS_S_CALL_INACCESSIBLE_WRITE \ - (2ul << GSS_C_CALLING_ERROR_OFFSET) - - - -Wray [Page 43] - -RFC 1509 GSSAPI - Overview and C bindings September 1993 - - - #define GSS_S_CALL_BAD_STRUCTURE \ - (3ul << GSS_C_CALLING_ERROR_OFFSET) - - /* - * Routine errors: - */ - #define GSS_S_BAD_MECH (1ul << GSS_C_ROUTINE_ERROR_OFFSET) - #define GSS_S_BAD_NAME (2ul << GSS_C_ROUTINE_ERROR_OFFSET) - #define GSS_S_BAD_NAMETYPE (3ul << GSS_C_ROUTINE_ERROR_OFFSET) - #define GSS_S_BAD_BINDINGS (4ul << GSS_C_ROUTINE_ERROR_OFFSET) - #define GSS_S_BAD_STATUS (5ul << GSS_C_ROUTINE_ERROR_OFFSET) - #define GSS_S_BAD_SIG (6ul << GSS_C_ROUTINE_ERROR_OFFSET) - #define GSS_S_NO_CRED (7ul << GSS_C_ROUTINE_ERROR_OFFSET) - #define GSS_S_NO_CONTEXT (8ul << GSS_C_ROUTINE_ERROR_OFFSET) - #define GSS_S_DEFECTIVE_TOKEN (9ul << GSS_C_ROUTINE_ERROR_OFFSET) - #define GSS_S_DEFECTIVE_CREDENTIAL (10ul << GSS_C_ROUTINE_ERROR_OFFSET) - #define GSS_S_CREDENTIALS_EXPIRED (11ul << GSS_C_ROUTINE_ERROR_OFFSET) - #define GSS_S_CONTEXT_EXPIRED (12ul << GSS_C_ROUTINE_ERROR_OFFSET) - #define GSS_S_FAILURE (13ul << GSS_C_ROUTINE_ERROR_OFFSET) - - /* - * Supplementary info bits: - */ - #define GSS_S_CONTINUE_NEEDED (1ul << (GSS_C_SUPPLEMENTARY_OFFSET + 0)) - #define GSS_S_DUPLICATE_TOKEN (1ul << (GSS_C_SUPPLEMENTARY_OFFSET + 1)) - #define GSS_S_OLD_TOKEN (1ul << (GSS_C_SUPPLEMENTARY_OFFSET + 2)) - #define GSS_S_UNSEQ_TOKEN (1ul << (GSS_C_SUPPLEMENTARY_OFFSET + 3)) - - - /* - * Finally, function prototypes for the GSSAPI routines. - */ - - OM_uint32 gss_acquire_cred - (OM_uint32*, /* minor_status */ - gss_name_t, /* desired_name */ - OM_uint32, /* time_req */ - gss_OID_set, /* desired_mechs */ - int, /* cred_usage */ - gss_cred_id_t*, /* output_cred_handle */ - gss_OID_set*, /* actual_mechs */ - OM_uint32* /* time_rec */ - ); - - OM_uint32 gss_release_cred, - (OM_uint32*, /* minor_status */ - gss_cred_id_t* /* cred_handle */ - ); - - - -Wray [Page 44] - -RFC 1509 GSSAPI - Overview and C bindings September 1993 - - - OM_uint32 gss_init_sec_context - (OM_uint32*, /* minor_status */ - gss_cred_id_t, /* claimant_cred_handle */ - gss_ctx_id_t*, /* context_handle */ - gss_name_t, /* target_name */ - gss_OID, /* mech_type */ - int, /* req_flags */ - OM_uint32, /* time_req */ - gss_channel_bindings_t, - /* input_chan_bindings */ - gss_buffer_t, /* input_token */ - gss_OID*, /* actual_mech_type */ - gss_buffer_t, /* output_token */ - int*, /* ret_flags */ - OM_uint32* /* time_rec */ - ); - - OM_uint32 gss_accept_sec_context - (OM_uint32*, /* minor_status */ - gss_ctx_id_t*, /* context_handle */ - gss_cred_id_t, /* verifier_cred_handle */ - gss_buffer_t, /* input_token_buffer */ - gss_channel_bindings_t, - /* input_chan_bindings */ - gss_name_t*, /* src_name */ - gss_OID*, /* mech_type */ - gss_buffer_t, /* output_token */ - int*, /* ret_flags */ - OM_uint32*, /* time_rec */ - gss_cred_id_t* /* delegated_cred_handle */ - ); - - OM_uint32 gss_process_context_token - (OM_uint32*, /* minor_status */ - gss_ctx_id_t, /* context_handle */ - gss_buffer_t /* token_buffer */ - ); - - OM_uint32 gss_delete_sec_context - (OM_uint32*, /* minor_status */ - gss_ctx_id_t*, /* context_handle */ - gss_buffer_t /* output_token */ - ); - - - - - - - - -Wray [Page 45] - -RFC 1509 GSSAPI - Overview and C bindings September 1993 - - - OM_uint32 gss_context_time - (OM_uint32*, /* minor_status */ - gss_ctx_id_t, /* context_handle */ - OM_uint32* /* time_rec */ - ); - - OM_uint32 gss_sign - (OM_uint32*, /* minor_status */ - gss_ctx_id_t, /* context_handle */ - int, /* qop_req */ - gss_buffer_t, /* message_buffer */ - gss_buffer_t /* message_token */ - ); - - OM_uitn32 gss_verify - (OM_uint32*, /* minor_status */ - gss_ctx_id_t, /* context_handle */ - gss_buffer_t, /* message_buffer */ - gss_buffer_t, /* token_buffer */ - int* /* qop_state */ - ); - - OM_uint32 gss_seal - (OM_uint32*, /* minor_status */ - gss_ctx_id_t, /* context_handle */ - int, /* conf_req_flag */ - int, /* qop_req */ - gss_buffer_t, /* input_message_buffer */ - int*, /* conf_state */ - gss_buffer_t /* output_message_buffer */ - ); - - OM_uint32 gss_unseal - (OM_uint32*, /* minor_status */ - gss_ctx_id_t, /* context_handle */ - gss_buffer_t, /* input_message_buffer */ - gss_buffer_t, /* output_message_buffer */ - int*, /* conf_state */ - int* /* qop_state */ - ); - - - - - - - - - - - -Wray [Page 46] - -RFC 1509 GSSAPI - Overview and C bindings September 1993 - - - OM_uint32 gss_display_status - (OM_uint32*, /* minor_status */ - OM_uint32, /* status_value */ - int, /* status_type */ - gss_OID, /* mech_type */ - int*, /* message_context */ - gss_buffer_t /* status_string */ - ); - - OM_uint32 gss_indicate_mechs - (OM_uint32*, /* minor_status */ - gss_OID_set* /* mech_set */ - ); - - OM_uint32 gss_compare_name - (OM_uint32*, /* minor_status */ - gss_name_t, /* name1 */ - gss_name_t, /* name2 */ - int* /* name_equal */ - ); - - OM_uint32 gss_display_name, - (OM_uint32*, /* minor_status */ - gss_name_t, /* input_name */ - gss_buffer_t, /* output_name_buffer */ - gss_OID* /* output_name_type */ - ); - - OM_uint32 gss_import_name - (OM_uint32*, /* minor_status */ - gss_buffer_t, /* input_name_buffer */ - gss_OID, /* input_name_type */ - gss_name_t* /* output_name */ - ); - - OM_uint32 gss_release_name - (OM_uint32*, /* minor_status */ - gss_name_t* /* input_name */ - ); - - OM_uint32 gss_release_buffer - (OM_uint32*, /* minor_status */ - gss_buffer_t /* buffer */ - ); - - OM_uint32 gss_release_oid_set - (OM_uint32*, /* minor_status */ - gss_OID_set* /* set */ - - - -Wray [Page 47] - -RFC 1509 GSSAPI - Overview and C bindings September 1993 - - - ); - - OM_uint32 gss_inquire_cred - (OM_uint32 *, /* minor_status */ - gss_cred_id_t, /* cred_handle */ - gss_name_t *, /* name */ - OM_uint32 *, /* lifetime */ - int *, /* cred_usage */ - gss_OID_set * /* mechanisms */ - ); - - - - #endif /* GSSAPI_H_ */ - -References - - [1] Linn, J., "Generic Security Service Application Program - Interface", RFC 1508, Geer Zolot Associate, September 1993. - - [2] "OSI Object Management API Specification, Version 2.0 t", X.400 - API Association & X/Open Company Limited, August 24, 1990. - Specification of datatypes and routines for manipulating - information objects. - -Security Considerations - - Security issues are discussed throughout this memo. - -Author's Address - - John Wray - Digital Equipment Corporation - 550 King Street, LKG2-2/AA6 - Littleton, MA 01460 - USA - - Phone: +1-508-486-5210 - EMail: Wray@tuxedo.enet.dec.com - - - - - - - - - - - - -Wray [Page 48] - \ No newline at end of file diff --git a/doc/rfc1510.txt b/doc/rfc1510.txt deleted file mode 100644 index bc810cc50..000000000 --- a/doc/rfc1510.txt +++ /dev/null @@ -1,6275 +0,0 @@ - - - - - - -Network Working Group J. Kohl -Request for Comments: 1510 Digital Equipment Corporation - C. Neuman - ISI - September 1993 - - - The Kerberos Network Authentication Service (V5) - -Status of this Memo - - This RFC specifies an Internet standards track protocol for the - Internet community, and requests discussion and suggestions for - improvements. Please refer to the current edition of the "Internet - Official Protocol Standards" for the standardization state and status - of this protocol. Distribution of this memo is unlimited. - -Abstract - - This document gives an overview and specification of Version 5 of the - protocol for the Kerberos network authentication system. Version 4, - described elsewhere [1,2], is presently in production use at MIT's - Project Athena, and at other Internet sites. - -Overview - - Project Athena, Athena, Athena MUSE, Discuss, Hesiod, Kerberos, - Moira, and Zephyr are trademarks of the Massachusetts Institute of - Technology (MIT). No commercial use of these trademarks may be made - without prior written permission of MIT. - - This RFC describes the concepts and model upon which the Kerberos - network authentication system is based. It also specifies Version 5 - of the Kerberos protocol. - - The motivations, goals, assumptions, and rationale behind most design - decisions are treated cursorily; for Version 4 they are fully - described in the Kerberos portion of the Athena Technical Plan [1]. - The protocols are under review, and are not being submitted for - consideration as an Internet standard at this time. Comments are - encouraged. Requests for addition to an electronic mailing list for - discussion of Kerberos, kerberos@MIT.EDU, may be addressed to - kerberos-request@MIT.EDU. This mailing list is gatewayed onto the - Usenet as the group comp.protocols.kerberos. Requests for further - information, including documents and code availability, may be sent - to info-kerberos@MIT.EDU. - - - - - -Kohl & Neuman [Page 1] - -RFC 1510 Kerberos September 1993 - - -Background - - The Kerberos model is based in part on Needham and Schroeder's - trusted third-party authentication protocol [3] and on modifications - suggested by Denning and Sacco [4]. The original design and - implementation of Kerberos Versions 1 through 4 was the work of two - former Project Athena staff members, Steve Miller of Digital - Equipment Corporation and Clifford Neuman (now at the Information - Sciences Institute of the University of Southern California), along - with Jerome Saltzer, Technical Director of Project Athena, and - Jeffrey Schiller, MIT Campus Network Manager. Many other members of - Project Athena have also contributed to the work on Kerberos. - Version 4 is publicly available, and has seen wide use across the - Internet. - - Version 5 (described in this document) has evolved from Version 4 - based on new requirements and desires for features not available in - Version 4. Details on the differences between Kerberos Versions 4 - and 5 can be found in [5]. - -Table of Contents - - 1. Introduction ....................................... 5 - 1.1. Cross-Realm Operation ............................ 7 - 1.2. Environmental assumptions ........................ 8 - 1.3. Glossary of terms ................................ 9 - 2. Ticket flag uses and requests ...................... 12 - 2.1. Initial and pre-authenticated tickets ............ 12 - 2.2. Invalid tickets .................................. 12 - 2.3. Renewable tickets ................................ 12 - 2.4. Postdated tickets ................................ 13 - 2.5. Proxiable and proxy tickets ...................... 14 - 2.6. Forwardable tickets .............................. 15 - 2.7. Other KDC options ................................ 15 - 3. Message Exchanges .................................. 16 - 3.1. The Authentication Service Exchange .............. 16 - 3.1.1. Generation of KRB_AS_REQ message ............... 17 - 3.1.2. Receipt of KRB_AS_REQ message .................. 17 - 3.1.3. Generation of KRB_AS_REP message ............... 17 - 3.1.4. Generation of KRB_ERROR message ................ 19 - 3.1.5. Receipt of KRB_AS_REP message .................. 19 - 3.1.6. Receipt of KRB_ERROR message ................... 20 - 3.2. The Client/Server Authentication Exchange ........ 20 - 3.2.1. The KRB_AP_REQ message ......................... 20 - 3.2.2. Generation of a KRB_AP_REQ message ............. 20 - 3.2.3. Receipt of KRB_AP_REQ message .................. 21 - 3.2.4. Generation of a KRB_AP_REP message ............. 23 - 3.2.5. Receipt of KRB_AP_REP message .................. 23 - - - -Kohl & Neuman [Page 2] - -RFC 1510 Kerberos September 1993 - - - 3.2.6. Using the encryption key ....................... 24 - 3.3. The Ticket-Granting Service (TGS) Exchange ....... 24 - 3.3.1. Generation of KRB_TGS_REQ message .............. 25 - 3.3.2. Receipt of KRB_TGS_REQ message ................. 26 - 3.3.3. Generation of KRB_TGS_REP message .............. 27 - 3.3.3.1. Encoding the transited field ................. 29 - 3.3.4. Receipt of KRB_TGS_REP message ................. 31 - 3.4. The KRB_SAFE Exchange ............................ 31 - 3.4.1. Generation of a KRB_SAFE message ............... 31 - 3.4.2. Receipt of KRB_SAFE message .................... 32 - 3.5. The KRB_PRIV Exchange ............................ 33 - 3.5.1. Generation of a KRB_PRIV message ............... 33 - 3.5.2. Receipt of KRB_PRIV message .................... 33 - 3.6. The KRB_CRED Exchange ............................ 34 - 3.6.1. Generation of a KRB_CRED message ............... 34 - 3.6.2. Receipt of KRB_CRED message .................... 34 - 4. The Kerberos Database .............................. 35 - 4.1. Database contents ................................ 35 - 4.2. Additional fields ................................ 36 - 4.3. Frequently Changing Fields ....................... 37 - 4.4. Site Constants ................................... 37 - 5. Message Specifications ............................. 38 - 5.1. ASN.1 Distinguished Encoding Representation ...... 38 - 5.2. ASN.1 Base Definitions ........................... 38 - 5.3. Tickets and Authenticators ....................... 42 - 5.3.1. Tickets ........................................ 42 - 5.3.2. Authenticators ................................. 47 - 5.4. Specifications for the AS and TGS exchanges ...... 49 - 5.4.1. KRB_KDC_REQ definition ......................... 49 - 5.4.2. KRB_KDC_REP definition ......................... 56 - 5.5. Client/Server (CS) message specifications ........ 58 - 5.5.1. KRB_AP_REQ definition .......................... 58 - 5.5.2. KRB_AP_REP definition .......................... 60 - 5.5.3. Error message reply ............................ 61 - 5.6. KRB_SAFE message specification ................... 61 - 5.6.1. KRB_SAFE definition ............................ 61 - 5.7. KRB_PRIV message specification ................... 62 - 5.7.1. KRB_PRIV definition ............................ 62 - 5.8. KRB_CRED message specification ................... 63 - 5.8.1. KRB_CRED definition ............................ 63 - 5.9. Error message specification ...................... 65 - 5.9.1. KRB_ERROR definition ........................... 66 - 6. Encryption and Checksum Specifications ............. 67 - 6.1. Encryption Specifications ........................ 68 - 6.2. Encryption Keys .................................. 71 - 6.3. Encryption Systems ............................... 71 - 6.3.1. The NULL Encryption System (null) .............. 71 - 6.3.2. DES in CBC mode with a CRC-32 checksum (descbc-crc)71 - - - -Kohl & Neuman [Page 3] - -RFC 1510 Kerberos September 1993 - - - 6.3.3. DES in CBC mode with an MD4 checksum (descbc-md4) 72 - 6.3.4. DES in CBC mode with an MD5 checksum (descbc-md5) 72 - 6.4. Checksums ........................................ 74 - 6.4.1. The CRC-32 Checksum (crc32) .................... 74 - 6.4.2. The RSA MD4 Checksum (rsa-md4) ................. 75 - 6.4.3. RSA MD4 Cryptographic Checksum Using DES - (rsa-md4-des) ......................................... 75 - 6.4.4. The RSA MD5 Checksum (rsa-md5) ................. 76 - 6.4.5. RSA MD5 Cryptographic Checksum Using DES - (rsa-md5-des) ......................................... 76 - 6.4.6. DES cipher-block chained checksum (des-mac) - 6.4.7. RSA MD4 Cryptographic Checksum Using DES - alternative (rsa-md4-des-k) ........................... 77 - 6.4.8. DES cipher-block chained checksum alternative - (des-mac-k) ........................................... 77 - 7. Naming Constraints ................................. 78 - 7.1. Realm Names ...................................... 77 - 7.2. Principal Names .................................. 79 - 7.2.1. Name of server principals ...................... 80 - 8. Constants and other defined values ................. 80 - 8.1. Host address types ............................... 80 - 8.2. KDC messages ..................................... 81 - 8.2.1. IP transport ................................... 81 - 8.2.2. OSI transport .................................. 82 - 8.2.3. Name of the TGS ................................ 82 - 8.3. Protocol constants and associated values ......... 82 - 9. Interoperability requirements ...................... 86 - 9.1. Specification 1 .................................. 86 - 9.2. Recommended KDC values ........................... 88 - 10. Acknowledgments ................................... 88 - 11. References ........................................ 89 - 12. Security Considerations ........................... 90 - 13. Authors' Addresses ................................ 90 - A. Pseudo-code for protocol processing ................ 91 - A.1. KRB_AS_REQ generation ............................ 91 - A.2. KRB_AS_REQ verification and KRB_AS_REP generation 92 - A.3. KRB_AS_REP verification .......................... 95 - A.4. KRB_AS_REP and KRB_TGS_REP common checks ......... 96 - A.5. KRB_TGS_REQ generation ........................... 97 - A.6. KRB_TGS_REQ verification and KRB_TGS_REP generation 98 - A.7. KRB_TGS_REP verification ......................... 104 - A.8. Authenticator generation ......................... 104 - A.9. KRB_AP_REQ generation ............................ 105 - A.10. KRB_AP_REQ verification ......................... 105 - A.11. KRB_AP_REP generation ........................... 106 - A.12. KRB_AP_REP verification ......................... 107 - A.13. KRB_SAFE generation ............................. 107 - A.14. KRB_SAFE verification ........................... 108 - - - -Kohl & Neuman [Page 4] - -RFC 1510 Kerberos September 1993 - - - A.15. KRB_SAFE and KRB_PRIV common checks ............. 108 - A.16. KRB_PRIV generation ............................. 109 - A.17. KRB_PRIV verification ........................... 110 - A.18. KRB_CRED generation ............................. 110 - A.19. KRB_CRED verification ........................... 111 - A.20. KRB_ERROR generation ............................ 112 - -1. Introduction - - Kerberos provides a means of verifying the identities of principals, - (e.g., a workstation user or a network server) on an open - (unprotected) network. This is accomplished without relying on - authentication by the host operating system, without basing trust on - host addresses, without requiring physical security of all the hosts - on the network, and under the assumption that packets traveling along - the network can be read, modified, and inserted at will. (Note, - however, that many applications use Kerberos' functions only upon the - initiation of a stream-based network connection, and assume the - absence of any "hijackers" who might subvert such a connection. Such - use implicitly trusts the host addresses involved.) Kerberos - performs authentication under these conditions as a trusted third- - party authentication service by using conventional cryptography, - i.e., shared secret key. (shared secret key - Secret and private are - often used interchangeably in the literature. In our usage, it takes - two (or more) to share a secret, thus a shared DES key is a secret - key. Something is only private when no one but its owner knows it. - Thus, in public key cryptosystems, one has a public and a private - key.) - - The authentication process proceeds as follows: A client sends a - request to the authentication server (AS) requesting "credentials" - for a given server. The AS responds with these credentials, - encrypted in the client's key. The credentials consist of 1) a - "ticket" for the server and 2) a temporary encryption key (often - called a "session key"). The client transmits the ticket (which - contains the client's identity and a copy of the session key, all - encrypted in the server's key) to the server. The session key (now - shared by the client and server) is used to authenticate the client, - and may optionally be used to authenticate the server. It may also - be used to encrypt further communication between the two parties or - to exchange a separate sub-session key to be used to encrypt further - communication. - - The implementation consists of one or more authentication servers - running on physically secure hosts. The authentication servers - maintain a database of principals (i.e., users and servers) and their - secret keys. Code libraries provide encryption and implement the - Kerberos protocol. In order to add authentication to its - - - -Kohl & Neuman [Page 5] - -RFC 1510 Kerberos September 1993 - - - transactions, a typical network application adds one or two calls to - the Kerberos library, which results in the transmission of the - necessary messages to achieve authentication. - - The Kerberos protocol consists of several sub-protocols (or - exchanges). There are two methods by which a client can ask a - Kerberos server for credentials. In the first approach, the client - sends a cleartext request for a ticket for the desired server to the - AS. The reply is sent encrypted in the client's secret key. Usually - this request is for a ticket-granting ticket (TGT) which can later be - used with the ticket-granting server (TGS). In the second method, - the client sends a request to the TGS. The client sends the TGT to - the TGS in the same manner as if it were contacting any other - application server which requires Kerberos credentials. The reply is - encrypted in the session key from the TGT. - - Once obtained, credentials may be used to verify the identity of the - principals in a transaction, to ensure the integrity of messages - exchanged between them, or to preserve privacy of the messages. The - application is free to choose whatever protection may be necessary. - - To verify the identities of the principals in a transaction, the - client transmits the ticket to the server. Since the ticket is sent - "in the clear" (parts of it are encrypted, but this encryption - doesn't thwart replay) and might be intercepted and reused by an - attacker, additional information is sent to prove that the message - was originated by the principal to whom the ticket was issued. This - information (called the authenticator) is encrypted in the session - key, and includes a timestamp. The timestamp proves that the message - was recently generated and is not a replay. Encrypting the - authenticator in the session key proves that it was generated by a - party possessing the session key. Since no one except the requesting - principal and the server know the session key (it is never sent over - the network in the clear) this guarantees the identity of the client. - - The integrity of the messages exchanged between principals can also - be guaranteed using the session key (passed in the ticket and - contained in the credentials). This approach provides detection of - both replay attacks and message stream modification attacks. It is - accomplished by generating and transmitting a collision-proof - checksum (elsewhere called a hash or digest function) of the client's - message, keyed with the session key. Privacy and integrity of the - messages exchanged between principals can be secured by encrypting - the data to be passed using the session key passed in the ticket, and - contained in the credentials. - - The authentication exchanges mentioned above require read-only access - to the Kerberos database. Sometimes, however, the entries in the - - - -Kohl & Neuman [Page 6] - -RFC 1510 Kerberos September 1993 - - - database must be modified, such as when adding new principals or - changing a principal's key. This is done using a protocol between a - client and a third Kerberos server, the Kerberos Administration - Server (KADM). The administration protocol is not described in this - document. There is also a protocol for maintaining multiple copies of - the Kerberos database, but this can be considered an implementation - detail and may vary to support different database technologies. - -1.1. Cross-Realm Operation - - The Kerberos protocol is designed to operate across organizational - boundaries. A client in one organization can be authenticated to a - server in another. Each organization wishing to run a Kerberos - server establishes its own "realm". The name of the realm in which a - client is registered is part of the client's name, and can be used by - the end-service to decide whether to honor a request. - - By establishing "inter-realm" keys, the administrators of two realms - can allow a client authenticated in the local realm to use its - authentication remotely (Of course, with appropriate permission the - client could arrange registration of a separately-named principal in - a remote realm, and engage in normal exchanges with that realm's - services. However, for even small numbers of clients this becomes - cumbersome, and more automatic methods as described here are - necessary). The exchange of inter-realm keys (a separate key may be - used for each direction) registers the ticket-granting service of - each realm as a principal in the other realm. A client is then able - to obtain a ticket-granting ticket for the remote realm's ticket- - granting service from its local realm. When that ticket-granting - ticket is used, the remote ticket-granting service uses the inter- - realm key (which usually differs from its own normal TGS key) to - decrypt the ticket-granting ticket, and is thus certain that it was - issued by the client's own TGS. Tickets issued by the remote ticket- - granting service will indicate to the end-service that the client was - authenticated from another realm. - - A realm is said to communicate with another realm if the two realms - share an inter-realm key, or if the local realm shares an inter-realm - key with an intermediate realm that communicates with the remote - realm. An authentication path is the sequence of intermediate realms - that are transited in communicating from one realm to another. - - Realms are typically organized hierarchically. Each realm shares a - key with its parent and a different key with each child. If an - inter-realm key is not directly shared by two realms, the - hierarchical organization allows an authentication path to be easily - constructed. If a hierarchical organization is not used, it may be - necessary to consult some database in order to construct an - - - -Kohl & Neuman [Page 7] - -RFC 1510 Kerberos September 1993 - - - authentication path between realms. - - Although realms are typically hierarchical, intermediate realms may - be bypassed to achieve cross-realm authentication through alternate - authentication paths (these might be established to make - communication between two realms more efficient). It is important - for the end-service to know which realms were transited when deciding - how much faith to place in the authentication process. To facilitate - this decision, a field in each ticket contains the names of the - realms that were involved in authenticating the client. - -1.2. Environmental assumptions - - Kerberos imposes a few assumptions on the environment in which it can - properly function: - - + "Denial of service" attacks are not solved with Kerberos. There - are places in these protocols where an intruder intruder can - prevent an application from participating in the proper - authentication steps. Detection and solution of such attacks - (some of which can appear to be not-uncommon "normal" failure - modes for the system) is usually best left to the human - administrators and users. - - + Principals must keep their secret keys secret. If an intruder - somehow steals a principal's key, it will be able to masquerade - as that principal or impersonate any server to the legitimate - principal. - - + "Password guessing" attacks are not solved by Kerberos. If a - user chooses a poor password, it is possible for an attacker to - successfully mount an offline dictionary attack by repeatedly - attempting to decrypt, with successive entries from a - dictionary, messages obtained which are encrypted under a key - derived from the user's password. - - + Each host on the network must have a clock which is "loosely - synchronized" to the time of the other hosts; this - synchronization is used to reduce the bookkeeping needs of - application servers when they do replay detection. The degree - of "looseness" can be configured on a per-server basis. If the - clocks are synchronized over the network, the clock - synchronization protocol must itself be secured from network - attackers. - - + Principal identifiers are not recycled on a short-term basis. A - typical mode of access control will use access control lists - (ACLs) to grant permissions to particular principals. If a - - - -Kohl & Neuman [Page 8] - -RFC 1510 Kerberos September 1993 - - - stale ACL entry remains for a deleted principal and the - principal identifier is reused, the new principal will inherit - rights specified in the stale ACL entry. By not re-using - principal identifiers, the danger of inadvertent access is - removed. - -1.3. Glossary of terms - - Below is a list of terms used throughout this document. - - - Authentication Verifying the claimed identity of a - principal. - - - Authentication header A record containing a Ticket and an - Authenticator to be presented to a - server as part of the authentication - process. - - - Authentication path A sequence of intermediate realms transited - in the authentication process when - communicating from one realm to another. - - Authenticator A record containing information that can - be shown to have been recently generated - using the session key known only by the - client and server. - - - Authorization The process of determining whether a - client may use a service, which objects - the client is allowed to access, and the - type of access allowed for each. - - - Capability A token that grants the bearer permission - to access an object or service. In - Kerberos, this might be a ticket whose - use is restricted by the contents of the - authorization data field, but which - lists no network addresses, together - with the session key necessary to use - the ticket. - - - - - - -Kohl & Neuman [Page 9] - -RFC 1510 Kerberos September 1993 - - - Ciphertext The output of an encryption function. - Encryption transforms plaintext into - ciphertext. - - - Client A process that makes use of a network - service on behalf of a user. Note that - in some cases a Server may itself be a - client of some other server (e.g., a - print server may be a client of a file - server). - - - Credentials A ticket plus the secret session key - necessary to successfully use that - ticket in an authentication exchange. - - - KDC Key Distribution Center, a network service - that supplies tickets and temporary - session keys; or an instance of that - service or the host on which it runs. - The KDC services both initial ticket and - ticket-granting ticket requests. The - initial ticket portion is sometimes - referred to as the Authentication Server - (or service). The ticket-granting - ticket portion is sometimes referred to - as the ticket-granting server (or service). - - Kerberos Aside from the 3-headed dog guarding - Hades, the name given to Project - Athena's authentication service, the - protocol used by that service, or the - code used to implement the authentication - service. - - - Plaintext The input to an encryption function or - the output of a decryption function. - Decryption transforms ciphertext into - plaintext. - - - Principal A uniquely named client or server - instance that participates in a network - communication. - - - - -Kohl & Neuman [Page 10] - -RFC 1510 Kerberos September 1993 - - - Principal identifier The name used to uniquely identify each - different principal. - - - Seal To encipher a record containing several - fields in such a way that the fields - cannot be individually replaced without - either knowledge of the encryption key - or leaving evidence of tampering. - - - Secret key An encryption key shared by a principal - and the KDC, distributed outside the - bounds of the system, with a long lifetime. - In the case of a human user's - principal, the secret key is derived - from a password. - - - Server A particular Principal which provides a - resource to network clients. - - - Service A resource provided to network clients; - often provided by more than one server - (for example, remote file service). - - - Session key A temporary encryption key used between - two principals, with a lifetime limited - to the duration of a single login "session". - - - Sub-session key A temporary encryption key used between - two principals, selected and exchanged - by the principals using the session key, - and with a lifetime limited to the duration - of a single association. - - - Ticket A record that helps a client authenticate - itself to a server; it contains the - client's identity, a session key, a - timestamp, and other information, all - sealed using the server's secret key. - It only serves to authenticate a client - when presented along with a fresh - Authenticator. - - - -Kohl & Neuman [Page 11] - -RFC 1510 Kerberos September 1993 - - -2. Ticket flag uses and requests - - Each Kerberos ticket contains a set of flags which are used to - indicate various attributes of that ticket. Most flags may be - requested by a client when the ticket is obtained; some are - automatically turned on and off by a Kerberos server as required. - The following sections explain what the various flags mean, and gives - examples of reasons to use such a flag. - -2.1. Initial and pre-authenticated tickets - - The INITIAL flag indicates that a ticket was issued using the AS - protocol and not issued based on a ticket-granting ticket. - Application servers that want to require the knowledge of a client's - secret key (e.g., a passwordchanging program) can insist that this - flag be set in any tickets they accept, and thus be assured that the - client's key was recently presented to the application client. - - The PRE-AUTHENT and HW-AUTHENT flags provide addition information - about the initial authentication, regardless of whether the current - ticket was issued directly (in which case INITIAL will also be set) - or issued on the basis of a ticket-granting ticket (in which case the - INITIAL flag is clear, but the PRE-AUTHENT and HW-AUTHENT flags are - carried forward from the ticket-granting ticket). - -2.2. Invalid tickets - - The INVALID flag indicates that a ticket is invalid. Application - servers must reject tickets which have this flag set. A postdated - ticket will usually be issued in this form. Invalid tickets must be - validated by the KDC before use, by presenting them to the KDC in a - TGS request with the VALIDATE option specified. The KDC will only - validate tickets after their starttime has passed. The validation is - required so that postdated tickets which have been stolen before - their starttime can be rendered permanently invalid (through a hot- - list mechanism). - -2.3. Renewable tickets - - Applications may desire to hold tickets which can be valid for long - periods of time. However, this can expose their credentials to - potential theft for equally long periods, and those stolen - credentials would be valid until the expiration time of the - ticket(s). Simply using shortlived tickets and obtaining new ones - periodically would require the client to have long-term access to its - secret key, an even greater risk. Renewable tickets can be used to - mitigate the consequences of theft. Renewable tickets have two - "expiration times": the first is when the current instance of the - - - -Kohl & Neuman [Page 12] - -RFC 1510 Kerberos September 1993 - - - ticket expires, and the second is the latest permissible value for an - individual expiration time. An application client must periodically - (i.e., before it expires) present a renewable ticket to the KDC, with - the RENEW option set in the KDC request. The KDC will issue a new - ticket with a new session key and a later expiration time. All other - fields of the ticket are left unmodified by the renewal process. - When the latest permissible expiration time arrives, the ticket - expires permanently. At each renewal, the KDC may consult a hot-list - to determine if the ticket had been reported stolen since its last - renewal; it will refuse to renew such stolen tickets, and thus the - usable lifetime of stolen tickets is reduced. - - The RENEWABLE flag in a ticket is normally only interpreted by the - ticket-granting service (discussed below in section 3.3). It can - usually be ignored by application servers. However, some - particularly careful application servers may wish to disallow - renewable tickets. - - If a renewable ticket is not renewed by its expiration time, the KDC - will not renew the ticket. The RENEWABLE flag is reset by default, - but a client may request it be set by setting the RENEWABLE option - in the KRB_AS_REQ message. If it is set, then the renew-till field - in the ticket contains the time after which the ticket may not be - renewed. - -2.4. Postdated tickets - - Applications may occasionally need to obtain tickets for use much - later, e.g., a batch submission system would need tickets to be valid - at the time the batch job is serviced. However, it is dangerous to - hold valid tickets in a batch queue, since they will be on-line - longer and more prone to theft. Postdated tickets provide a way to - obtain these tickets from the KDC at job submission time, but to - leave them "dormant" until they are activated and validated by a - further request of the KDC. If a ticket theft were reported in the - interim, the KDC would refuse to validate the ticket, and the thief - would be foiled. - - The MAY-POSTDATE flag in a ticket is normally only interpreted by the - ticket-granting service. It can be ignored by application servers. - This flag must be set in a ticket-granting ticket in order to issue a - postdated ticket based on the presented ticket. It is reset by - default; it may be requested by a client by setting the ALLOW- - POSTDATE option in the KRB_AS_REQ message. This flag does not allow - a client to obtain a postdated ticket-granting ticket; postdated - ticket-granting tickets can only by obtained by requesting the - postdating in the KRB_AS_REQ message. The life (endtime-starttime) - of a postdated ticket will be the remaining life of the ticket- - - - -Kohl & Neuman [Page 13] - -RFC 1510 Kerberos September 1993 - - - granting ticket at the time of the request, unless the RENEWABLE - option is also set, in which case it can be the full life (endtime- - starttime) of the ticket-granting ticket. The KDC may limit how far - in the future a ticket may be postdated. - - The POSTDATED flag indicates that a ticket has been postdated. The - application server can check the authtime field in the ticket to see - when the original authentication occurred. Some services may choose - to reject postdated tickets, or they may only accept them within a - certain period after the original authentication. When the KDC issues - a POSTDATED ticket, it will also be marked as INVALID, so that the - application client must present the ticket to the KDC to be validated - before use. - -2.5. Proxiable and proxy tickets - - At times it may be necessary for a principal to allow a service to - perform an operation on its behalf. The service must be able to take - on the identity of the client, but only for a particular purpose. A - principal can allow a service to take on the principal's identity for - a particular purpose by granting it a proxy. - - The PROXIABLE flag in a ticket is normally only interpreted by the - ticket-granting service. It can be ignored by application servers. - When set, this flag tells the ticket-granting server that it is OK to - issue a new ticket (but not a ticket-granting ticket) with a - different network address based on this ticket. This flag is set by - default. - - This flag allows a client to pass a proxy to a server to perform a - remote request on its behalf, e.g., a print service client can give - the print server a proxy to access the client's files on a particular - file server in order to satisfy a print request. - - In order to complicate the use of stolen credentials, Kerberos - tickets are usually valid from only those network addresses - specifically included in the ticket (It is permissible to request or - issue tickets with no network addresses specified, but we do not - recommend it). For this reason, a client wishing to grant a proxy - must request a new ticket valid for the network address of the - service to be granted the proxy. - - The PROXY flag is set in a ticket by the TGS when it issues a - proxy ticket. Application servers may check this flag and require - additional authentication from the agent presenting the proxy in - order to provide an audit trail. - - - - - -Kohl & Neuman [Page 14] - -RFC 1510 Kerberos September 1993 - - -2.6. Forwardable tickets - - Authentication forwarding is an instance of the proxy case where the - service is granted complete use of the client's identity. An example - where it might be used is when a user logs in to a remote system and - wants authentication to work from that system as if the login were - local. - - The FORWARDABLE flag in a ticket is normally only interpreted by the - ticket-granting service. It can be ignored by application servers. - The FORWARDABLE flag has an interpretation similar to that of the - PROXIABLE flag, except ticket-granting tickets may also be issued - with different network addresses. This flag is reset by default, but - users may request that it be set by setting the FORWARDABLE option in - the AS request when they request their initial ticket-granting - ticket. - - This flag allows for authentication forwarding without requiring the - user to enter a password again. If the flag is not set, then - authentication forwarding is not permitted, but the same end result - can still be achieved if the user engages in the AS exchange with the - requested network addresses and supplies a password. - - The FORWARDED flag is set by the TGS when a client presents a ticket - with the FORWARDABLE flag set and requests it be set by specifying - the FORWARDED KDC option and supplying a set of addresses for the new - ticket. It is also set in all tickets issued based on tickets with - the FORWARDED flag set. Application servers may wish to process - FORWARDED tickets differently than non-FORWARDED tickets. - -2.7. Other KDC options - - There are two additional options which may be set in a client's - request of the KDC. The RENEWABLE-OK option indicates that the - client will accept a renewable ticket if a ticket with the requested - life cannot otherwise be provided. If a ticket with the requested - life cannot be provided, then the KDC may issue a renewable ticket - with a renew-till equal to the the requested endtime. The value of - the renew-till field may still be adjusted by site-determined limits - or limits imposed by the individual principal or server. - - The ENC-TKT-IN-SKEY option is honored only by the ticket-granting - service. It indicates that the to-be-issued ticket for the end - server is to be encrypted in the session key from the additional - ticket-granting ticket provided with the request. See section 3.3.3 - for specific details. - - - - - -Kohl & Neuman [Page 15] - -RFC 1510 Kerberos September 1993 - - -3. Message Exchanges - - The following sections describe the interactions between network - clients and servers and the messages involved in those exchanges. - -3.1. The Authentication Service Exchange - - Summary - - Message direction Message type Section - 1. Client to Kerberos KRB_AS_REQ 5.4.1 - 2. Kerberos to client KRB_AS_REP or 5.4.2 - KRB_ERROR 5.9.1 - - The Authentication Service (AS) Exchange between the client and the - Kerberos Authentication Server is usually initiated by a client when - it wishes to obtain authentication credentials for a given server but - currently holds no credentials. The client's secret key is used for - encryption and decryption. This exchange is typically used at the - initiation of a login session, to obtain credentials for a Ticket- - Granting Server, which will subsequently be used to obtain - credentials for other servers (see section 3.3) without requiring - further use of the client's secret key. This exchange is also used - to request credentials for services which must not be mediated - through the Ticket-Granting Service, but rather require a principal's - secret key, such as the password-changing service. (The password- - changing request must not be honored unless the requester can provide - the old password (the user's current secret key). Otherwise, it - would be possible for someone to walk up to an unattended session and - change another user's password.) This exchange does not by itself - provide any assurance of the the identity of the user. (To - authenticate a user logging on to a local system, the credentials - obtained in the AS exchange may first be used in a TGS exchange to - obtain credentials for a local server. Those credentials must then - be verified by the local server through successful completion of the - Client/Server exchange.) - - The exchange consists of two messages: KRB_AS_REQ from the client to - Kerberos, and KRB_AS_REP or KRB_ERROR in reply. The formats for these - messages are described in sections 5.4.1, 5.4.2, and 5.9.1. - - In the request, the client sends (in cleartext) its own identity and - the identity of the server for which it is requesting credentials. - The response, KRB_AS_REP, contains a ticket for the client to present - to the server, and a session key that will be shared by the client - and the server. The session key and additional information are - encrypted in the client's secret key. The KRB_AS_REP message - contains information which can be used to detect replays, and to - - - -Kohl & Neuman [Page 16] - -RFC 1510 Kerberos September 1993 - - - associate it with the message to which it replies. Various errors - can occur; these are indicated by an error response (KRB_ERROR) - instead of the KRB_AS_REP response. The error message is not - encrypted. The KRB_ERROR message also contains information which can - be used to associate it with the message to which it replies. The - lack of encryption in the KRB_ERROR message precludes the ability to - detect replays or fabrications of such messages. - - In the normal case the authentication server does not know whether - the client is actually the principal named in the request. It simply - sends a reply without knowing or caring whether they are the same. - This is acceptable because nobody but the principal whose identity - was given in the request will be able to use the reply. Its critical - information is encrypted in that principal's key. The initial - request supports an optional field that can be used to pass - additional information that might be needed for the initial exchange. - This field may be used for preauthentication if desired, but the - mechanism is not currently specified. - -3.1.1. Generation of KRB_AS_REQ message - - The client may specify a number of options in the initial request. - Among these options are whether preauthentication is to be performed; - whether the requested ticket is to be renewable, proxiable, or - forwardable; whether it should be postdated or allow postdating of - derivative tickets; and whether a renewable ticket will be accepted - in lieu of a non-renewable ticket if the requested ticket expiration - date cannot be satisfied by a nonrenewable ticket (due to - configuration constraints; see section 4). See section A.1 for - pseudocode. - - The client prepares the KRB_AS_REQ message and sends it to the KDC. - -3.1.2. Receipt of KRB_AS_REQ message - - If all goes well, processing the KRB_AS_REQ message will result in - the creation of a ticket for the client to present to the server. - The format for the ticket is described in section 5.3.1. The - contents of the ticket are determined as follows. - -3.1.3. Generation of KRB_AS_REP message - - The authentication server looks up the client and server principals - named in the KRB_AS_REQ in its database, extracting their respective - keys. If required, the server pre-authenticates the request, and if - the pre-authentication check fails, an error message with the code - KDC_ERR_PREAUTH_FAILED is returned. If the server cannot accommodate - the requested encryption type, an error message with code - - - -Kohl & Neuman [Page 17] - -RFC 1510 Kerberos September 1993 - - - KDC_ERR_ETYPE_NOSUPP is returned. Otherwise it generates a "random" - session key ("Random" means that, among other things, it should be - impossible to guess the next session key based on knowledge of past - session keys. This can only be achieved in a pseudo-random number - generator if it is based on cryptographic principles. It would be - more desirable to use a truly random number generator, such as one - based on measurements of random physical phenomena.). - - If the requested start time is absent or indicates a time in the - past, then the start time of the ticket is set to the authentication - server's current time. If it indicates a time in the future, but the - POSTDATED option has not been specified, then the error - KDC_ERR_CANNOT_POSTDATE is returned. Otherwise the requested start - time is checked against the policy of the local realm (the - administrator might decide to prohibit certain types or ranges of - postdated tickets), and if acceptable, the ticket's start time is set - as requested and the INVALID flag is set in the new ticket. The - postdated ticket must be validated before use by presenting it to the - KDC after the start time has been reached. - - The expiration time of the ticket will be set to the minimum of the - following: - - +The expiration time (endtime) requested in the KRB_AS_REQ - message. - - +The ticket's start time plus the maximum allowable lifetime - associated with the client principal (the authentication - server's database includes a maximum ticket lifetime field - in each principal's record; see section 4). - - +The ticket's start time plus the maximum allowable lifetime - associated with the server principal. - - +The ticket's start time plus the maximum lifetime set by - the policy of the local realm. - - If the requested expiration time minus the start time (as determined - above) is less than a site-determined minimum lifetime, an error - message with code KDC_ERR_NEVER_VALID is returned. If the requested - expiration time for the ticket exceeds what was determined as above, - and if the "RENEWABLE-OK" option was requested, then the "RENEWABLE" - flag is set in the new ticket, and the renew-till value is set as if - the "RENEWABLE" option were requested (the field and option names are - described fully in section 5.4.1). If the RENEWABLE option has been - requested or if the RENEWABLE-OK option has been set and a renewable - ticket is to be issued, then the renew-till field is set to the - minimum of: - - - -Kohl & Neuman [Page 18] - -RFC 1510 Kerberos September 1993 - - - +Its requested value. - - +The start time of the ticket plus the minimum of the two - maximum renewable lifetimes associated with the principals' - database entries. - - +The start time of the ticket plus the maximum renewable - lifetime set by the policy of the local realm. - - The flags field of the new ticket will have the following options set - if they have been requested and if the policy of the local realm - allows: FORWARDABLE, MAY-POSTDATE, POSTDATED, PROXIABLE, RENEWABLE. - If the new ticket is postdated (the start time is in the future), its - INVALID flag will also be set. - - If all of the above succeed, the server formats a KRB_AS_REP message - (see section 5.4.2), copying the addresses in the request into the - caddr of the response, placing any required pre-authentication data - into the padata of the response, and encrypts the ciphertext part in - the client's key using the requested encryption method, and sends it - to the client. See section A.2 for pseudocode. - -3.1.4. Generation of KRB_ERROR message - - Several errors can occur, and the Authentication Server responds by - returning an error message, KRB_ERROR, to the client, with the - error-code and e-text fields set to appropriate values. The error - message contents and details are described in Section 5.9.1. - -3.1.5. Receipt of KRB_AS_REP message - - If the reply message type is KRB_AS_REP, then the client verifies - that the cname and crealm fields in the cleartext portion of the - reply match what it requested. If any padata fields are present, - they may be used to derive the proper secret key to decrypt the - message. The client decrypts the encrypted part of the response - using its secret key, verifies that the nonce in the encrypted part - matches the nonce it supplied in its request (to detect replays). It - also verifies that the sname and srealm in the response match those - in the request, and that the host address field is also correct. It - then stores the ticket, session key, start and expiration times, and - other information for later use. The key-expiration field from the - encrypted part of the response may be checked to notify the user of - impending key expiration (the client program could then suggest - remedial action, such as a password change). See section A.3 for - pseudocode. - - Proper decryption of the KRB_AS_REP message is not sufficient to - - - -Kohl & Neuman [Page 19] - -RFC 1510 Kerberos September 1993 - - - verify the identity of the user; the user and an attacker could - cooperate to generate a KRB_AS_REP format message which decrypts - properly but is not from the proper KDC. If the host wishes to - verify the identity of the user, it must require the user to present - application credentials which can be verified using a securely-stored - secret key. If those credentials can be verified, then the identity - of the user can be assured. - -3.1.6. Receipt of KRB_ERROR message - - If the reply message type is KRB_ERROR, then the client interprets it - as an error and performs whatever application-specific tasks are - necessary to recover. - -3.2. The Client/Server Authentication Exchange - - Summary - - Message direction Message type Section - Client to Application server KRB_AP_REQ 5.5.1 - [optional] Application server to client KRB_AP_REP or 5.5.2 - KRB_ERROR 5.9.1 - - The client/server authentication (CS) exchange is used by network - applications to authenticate the client to the server and vice versa. - The client must have already acquired credentials for the server - using the AS or TGS exchange. - -3.2.1. The KRB_AP_REQ message - - The KRB_AP_REQ contains authentication information which should be - part of the first message in an authenticated transaction. It - contains a ticket, an authenticator, and some additional bookkeeping - information (see section 5.5.1 for the exact format). The ticket by - itself is insufficient to authenticate a client, since tickets are - passed across the network in cleartext(Tickets contain both an - encrypted and unencrypted portion, so cleartext here refers to the - entire unit, which can be copied from one message and replayed in - another without any cryptographic skill.), so the authenticator is - used to prevent invalid replay of tickets by proving to the server - that the client knows the session key of the ticket and thus is - entitled to use it. The KRB_AP_REQ message is referred to elsewhere - as the "authentication header." - -3.2.2. Generation of a KRB_AP_REQ message - - When a client wishes to initiate authentication to a server, it - obtains (either through a credentials cache, the AS exchange, or the - - - -Kohl & Neuman [Page 20] - -RFC 1510 Kerberos September 1993 - - - TGS exchange) a ticket and session key for the desired service. The - client may re-use any tickets it holds until they expire. The client - then constructs a new Authenticator from the the system time, its - name, and optionally an application specific checksum, an initial - sequence number to be used in KRB_SAFE or KRB_PRIV messages, and/or a - session subkey to be used in negotiations for a session key unique to - this particular session. Authenticators may not be re-used and will - be rejected if replayed to a server (Note that this can make - applications based on unreliable transports difficult to code - correctly, if the transport might deliver duplicated messages. In - such cases, a new authenticator must be generated for each retry.). - If a sequence number is to be included, it should be randomly chosen - so that even after many messages have been exchanged it is not likely - to collide with other sequence numbers in use. - - The client may indicate a requirement of mutual authentication or the - use of a session-key based ticket by setting the appropriate flag(s) - in the ap-options field of the message. - - The Authenticator is encrypted in the session key and combined with - the ticket to form the KRB_AP_REQ message which is then sent to the - end server along with any additional application-specific - information. See section A.9 for pseudocode. - -3.2.3. Receipt of KRB_AP_REQ message - - Authentication is based on the server's current time of day (clocks - must be loosely synchronized), the authenticator, and the ticket. - Several errors are possible. If an error occurs, the server is - expected to reply to the client with a KRB_ERROR message. This - message may be encapsulated in the application protocol if its "raw" - form is not acceptable to the protocol. The format of error messages - is described in section 5.9.1. - - The algorithm for verifying authentication information is as follows. - If the message type is not KRB_AP_REQ, the server returns the - KRB_AP_ERR_MSG_TYPE error. If the key version indicated by the Ticket - in the KRB_AP_REQ is not one the server can use (e.g., it indicates - an old key, and the server no longer possesses a copy of the old - key), the KRB_AP_ERR_BADKEYVER error is returned. If the USE- - SESSION-KEY flag is set in the ap-options field, it indicates to the - server that the ticket is encrypted in the session key from the - server's ticket-granting ticket rather than its secret key (This is - used for user-to-user authentication as described in [6]). Since it - is possible for the server to be registered in multiple realms, with - different keys in each, the srealm field in the unencrypted portion - of the ticket in the KRB_AP_REQ is used to specify which secret key - the server should use to decrypt that ticket. The KRB_AP_ERR_NOKEY - - - -Kohl & Neuman [Page 21] - -RFC 1510 Kerberos September 1993 - - - error code is returned if the server doesn't have the proper key to - decipher the ticket. - - The ticket is decrypted using the version of the server's key - specified by the ticket. If the decryption routines detect a - modification of the ticket (each encryption system must provide - safeguards to detect modified ciphertext; see section 6), the - KRB_AP_ERR_BAD_INTEGRITY error is returned (chances are good that - different keys were used to encrypt and decrypt). - - The authenticator is decrypted using the session key extracted from - the decrypted ticket. If decryption shows it to have been modified, - the KRB_AP_ERR_BAD_INTEGRITY error is returned. The name and realm - of the client from the ticket are compared against the same fields in - the authenticator. If they don't match, the KRB_AP_ERR_BADMATCH - error is returned (they might not match, for example, if the wrong - session key was used to encrypt the authenticator). The addresses in - the ticket (if any) are then searched for an address matching the - operating-system reported address of the client. If no match is - found or the server insists on ticket addresses but none are present - in the ticket, the KRB_AP_ERR_BADADDR error is returned. - - If the local (server) time and the client time in the authenticator - differ by more than the allowable clock skew (e.g., 5 minutes), the - KRB_AP_ERR_SKEW error is returned. If the server name, along with - the client name, time and microsecond fields from the Authenticator - match any recently-seen such tuples, the KRB_AP_ERR_REPEAT error is - returned (Note that the rejection here is restricted to - authenticators from the same principal to the same server. Other - client principals communicating with the same server principal should - not be have their authenticators rejected if the time and microsecond - fields happen to match some other client's authenticator.). The - server must remember any authenticator presented within the allowable - clock skew, so that a replay attempt is guaranteed to fail. If a - server loses track of any authenticator presented within the - allowable clock skew, it must reject all requests until the clock - skew interval has passed. This assures that any lost or re-played - authenticators will fall outside the allowable clock skew and can no - longer be successfully replayed (If this is not done, an attacker - could conceivably record the ticket and authenticator sent over the - network to a server, then disable the client's host, pose as the - disabled host, and replay the ticket and authenticator to subvert the - authentication.). If a sequence number is provided in the - authenticator, the server saves it for later use in processing - KRB_SAFE and/or KRB_PRIV messages. If a subkey is present, the - server either saves it for later use or uses it to help generate its - own choice for a subkey to be returned in a KRB_AP_REP message. - - - - -Kohl & Neuman [Page 22] - -RFC 1510 Kerberos September 1993 - - - The server computes the age of the ticket: local (server) time minus - the start time inside the Ticket. If the start time is later than - the current time by more than the allowable clock skew or if the - INVALID flag is set in the ticket, the KRB_AP_ERR_TKT_NYV error is - returned. Otherwise, if the current time is later than end time by - more than the allowable clock skew, the KRB_AP_ERR_TKT_EXPIRED error - is returned. - - If all these checks succeed without an error, the server is assured - that the client possesses the credentials of the principal named in - the ticket and thus, the client has been authenticated to the server. - See section A.10 for pseudocode. - -3.2.4. Generation of a KRB_AP_REP message - - Typically, a client's request will include both the authentication - information and its initial request in the same message, and the - server need not explicitly reply to the KRB_AP_REQ. However, if - mutual authentication (not only authenticating the client to the - server, but also the server to the client) is being performed, the - KRB_AP_REQ message will have MUTUAL-REQUIRED set in its ap-options - field, and a KRB_AP_REP message is required in response. As with the - error message, this message may be encapsulated in the application - protocol if its "raw" form is not acceptable to the application's - protocol. The timestamp and microsecond field used in the reply must - be the client's timestamp and microsecond field (as provided in the - authenticator). [Note: In the Kerberos version 4 protocol, the - timestamp in the reply was the client's timestamp plus one. This is - not necessary in version 5 because version 5 messages are formatted - in such a way that it is not possible to create the reply by - judicious message surgery (even in encrypted form) without knowledge - of the appropriate encryption keys.] If a sequence number is to be - included, it should be randomly chosen as described above for the - authenticator. A subkey may be included if the server desires to - negotiate a different subkey. The KRB_AP_REP message is encrypted in - the session key extracted from the ticket. See section A.11 for - pseudocode. - -3.2.5. Receipt of KRB_AP_REP message - - If a KRB_AP_REP message is returned, the client uses the session key - from the credentials obtained for the server (Note that for - encrypting the KRB_AP_REP message, the sub-session key is not used, - even if present in the Authenticator.) to decrypt the message, and - verifies that the timestamp and microsecond fields match those in the - Authenticator it sent to the server. If they match, then the client - is assured that the server is genuine. The sequence number and subkey - (if present) are retained for later use. See section A.12 for - - - -Kohl & Neuman [Page 23] - -RFC 1510 Kerberos September 1993 - - - pseudocode. - -3.2.6. Using the encryption key - - After the KRB_AP_REQ/KRB_AP_REP exchange has occurred, the client and - server share an encryption key which can be used by the application. - The "true session key" to be used for KRB_PRIV, KRB_SAFE, or other - application-specific uses may be chosen by the application based on - the subkeys in the KRB_AP_REP message and the authenticator - (Implementations of the protocol may wish to provide routines to - choose subkeys based on session keys and random numbers and to - orchestrate a negotiated key to be returned in the KRB_AP_REP - message.). In some cases, the use of this session key will be - implicit in the protocol; in others the method of use must be chosen - from a several alternatives. We leave the protocol negotiations of - how to use the key (e.g., selecting an encryption or checksum type) - to the application programmer; the Kerberos protocol does not - constrain the implementation options. - - With both the one-way and mutual authentication exchanges, the peers - should take care not to send sensitive information to each other - without proper assurances. In particular, applications that require - privacy or integrity should use the KRB_AP_REP or KRB_ERROR responses - from the server to client to assure both client and server of their - peer's identity. If an application protocol requires privacy of its - messages, it can use the KRB_PRIV message (section 3.5). The KRB_SAFE - message (section 3.4) can be used to assure integrity. - -3.3. The Ticket-Granting Service (TGS) Exchange - - Summary - - Message direction Message type Section - 1. Client to Kerberos KRB_TGS_REQ 5.4.1 - 2. Kerberos to client KRB_TGS_REP or 5.4.2 - KRB_ERROR 5.9.1 - - The TGS exchange between a client and the Kerberos Ticket-Granting - Server is initiated by a client when it wishes to obtain - authentication credentials for a given server (which might be - registered in a remote realm), when it wishes to renew or validate an - existing ticket, or when it wishes to obtain a proxy ticket. In the - first case, the client must already have acquired a ticket for the - Ticket-Granting Service using the AS exchange (the ticket-granting - ticket is usually obtained when a client initially authenticates to - the system, such as when a user logs in). The message format for the - TGS exchange is almost identical to that for the AS exchange. The - primary difference is that encryption and decryption in the TGS - - - -Kohl & Neuman [Page 24] - -RFC 1510 Kerberos September 1993 - - - exchange does not take place under the client's key. Instead, the - session key from the ticket-granting ticket or renewable ticket, or - sub-session key from an Authenticator is used. As is the case for - all application servers, expired tickets are not accepted by the TGS, - so once a renewable or ticket-granting ticket expires, the client - must use a separate exchange to obtain valid tickets. - - The TGS exchange consists of two messages: A request (KRB_TGS_REQ) - from the client to the Kerberos Ticket-Granting Server, and a reply - (KRB_TGS_REP or KRB_ERROR). The KRB_TGS_REQ message includes - information authenticating the client plus a request for credentials. - The authentication information consists of the authentication header - (KRB_AP_REQ) which includes the client's previously obtained ticket- - granting, renewable, or invalid ticket. In the ticket-granting - ticket and proxy cases, the request may include one or more of: a - list of network addresses, a collection of typed authorization data - to be sealed in the ticket for authorization use by the application - server, or additional tickets (the use of which are described later). - The TGS reply (KRB_TGS_REP) contains the requested credentials, - encrypted in the session key from the ticket-granting ticket or - renewable ticket, or if present, in the subsession key from the - Authenticator (part of the authentication header). The KRB_ERROR - message contains an error code and text explaining what went wrong. - The KRB_ERROR message is not encrypted. The KRB_TGS_REP message - contains information which can be used to detect replays, and to - associate it with the message to which it replies. The KRB_ERROR - message also contains information which can be used to associate it - with the message to which it replies, but the lack of encryption in - the KRB_ERROR message precludes the ability to detect replays or - fabrications of such messages. - -3.3.1. Generation of KRB_TGS_REQ message - - Before sending a request to the ticket-granting service, the client - must determine in which realm the application server is registered - [Note: This can be accomplished in several ways. It might be known - beforehand (since the realm is part of the principal identifier), or - it might be stored in a nameserver. Presently, however, this - information is obtained from a configuration file. If the realm to - be used is obtained from a nameserver, there is a danger of being - spoofed if the nameservice providing the realm name is not - authenticated. This might result in the use of a realm which has - been compromised, and would result in an attacker's ability to - compromise the authentication of the application server to the - client.]. If the client does not already possess a ticket-granting - ticket for the appropriate realm, then one must be obtained. This is - first attempted by requesting a ticket-granting ticket for the - destination realm from the local Kerberos server (using the - - - -Kohl & Neuman [Page 25] - -RFC 1510 Kerberos September 1993 - - - KRB_TGS_REQ message recursively). The Kerberos server may return a - TGT for the desired realm in which case one can proceed. - Alternatively, the Kerberos server may return a TGT for a realm which - is "closer" to the desired realm (further along the standard - hierarchical path), in which case this step must be repeated with a - Kerberos server in the realm specified in the returned TGT. If - neither are returned, then the request must be retried with a - Kerberos server for a realm higher in the hierarchy. This request - will itself require a ticket-granting ticket for the higher realm - which must be obtained by recursively applying these directions. - - Once the client obtains a ticket-granting ticket for the appropriate - realm, it determines which Kerberos servers serve that realm, and - contacts one. The list might be obtained through a configuration file - or network service; as long as the secret keys exchanged by realms - are kept secret, only denial of service results from a false Kerberos - server. - - As in the AS exchange, the client may specify a number of options in - the KRB_TGS_REQ message. The client prepares the KRB_TGS_REQ - message, providing an authentication header as an element of the - padata field, and including the same fields as used in the KRB_AS_REQ - message along with several optional fields: the enc-authorization- - data field for application server use and additional tickets required - by some options. - - In preparing the authentication header, the client can select a sub- - session key under which the response from the Kerberos server will be - encrypted (If the client selects a sub-session key, care must be - taken to ensure the randomness of the selected subsession key. One - approach would be to generate a random number and XOR it with the - session key from the ticket-granting ticket.). If the sub-session key - is not specified, the session key from the ticket-granting ticket - will be used. If the enc-authorization-data is present, it must be - encrypted in the sub-session key, if present, from the authenticator - portion of the authentication header, or if not present in the - session key from the ticket-granting ticket. - - Once prepared, the message is sent to a Kerberos server for the - destination realm. See section A.5 for pseudocode. - -3.3.2. Receipt of KRB_TGS_REQ message - - The KRB_TGS_REQ message is processed in a manner similar to the - KRB_AS_REQ message, but there are many additional checks to be - performed. First, the Kerberos server must determine which server - the accompanying ticket is for and it must select the appropriate key - to decrypt it. For a normal KRB_TGS_REQ message, it will be for the - - - -Kohl & Neuman [Page 26] - -RFC 1510 Kerberos September 1993 - - - ticket granting service, and the TGS's key will be used. If the TGT - was issued by another realm, then the appropriate inter-realm key - must be used. If the accompanying ticket is not a ticket granting - ticket for the current realm, but is for an application server in the - current realm, the RENEW, VALIDATE, or PROXY options are specified in - the request, and the server for which a ticket is requested is the - server named in the accompanying ticket, then the KDC will decrypt - the ticket in the authentication header using the key of the server - for which it was issued. If no ticket can be found in the padata - field, the KDC_ERR_PADATA_TYPE_NOSUPP error is returned. - - Once the accompanying ticket has been decrypted, the user-supplied - checksum in the Authenticator must be verified against the contents - of the request, and the message rejected if the checksums do not - match (with an error code of KRB_AP_ERR_MODIFIED) or if the checksum - is not keyed or not collision-proof (with an error code of - KRB_AP_ERR_INAPP_CKSUM). If the checksum type is not supported, the - KDC_ERR_SUMTYPE_NOSUPP error is returned. If the authorization-data - are present, they are decrypted using the sub-session key from the - Authenticator. - - If any of the decryptions indicate failed integrity checks, the - KRB_AP_ERR_BAD_INTEGRITY error is returned. - -3.3.3. Generation of KRB_TGS_REP message - - The KRB_TGS_REP message shares its format with the KRB_AS_REP - (KRB_KDC_REP), but with its type field set to KRB_TGS_REP. The - detailed specification is in section 5.4.2. - - The response will include a ticket for the requested server. The - Kerberos database is queried to retrieve the record for the requested - server (including the key with which the ticket will be encrypted). - If the request is for a ticket granting ticket for a remote realm, - and if no key is shared with the requested realm, then the Kerberos - server will select the realm "closest" to the requested realm with - which it does share a key, and use that realm instead. This is the - only case where the response from the KDC will be for a different - server than that requested by the client. - - By default, the address field, the client's name and realm, the list - of transited realms, the time of initial authentication, the - expiration time, and the authorization data of the newly-issued - ticket will be copied from the ticket-granting ticket (TGT) or - renewable ticket. If the transited field needs to be updated, but - the transited type is not supported, the KDC_ERR_TRTYPE_NOSUPP error - is returned. - - - - -Kohl & Neuman [Page 27] - -RFC 1510 Kerberos September 1993 - - - If the request specifies an endtime, then the endtime of the new - ticket is set to the minimum of (a) that request, (b) the endtime - from the TGT, and (c) the starttime of the TGT plus the minimum of - the maximum life for the application server and the maximum life for - the local realm (the maximum life for the requesting principal was - already applied when the TGT was issued). If the new ticket is to be - a renewal, then the endtime above is replaced by the minimum of (a) - the value of the renew_till field of the ticket and (b) the starttime - for the new ticket plus the life (endtimestarttime) of the old - ticket. - - If the FORWARDED option has been requested, then the resulting ticket - will contain the addresses specified by the client. This option will - only be honored if the FORWARDABLE flag is set in the TGT. The PROXY - option is similar; the resulting ticket will contain the addresses - specified by the client. It will be honored only if the PROXIABLE - flag in the TGT is set. The PROXY option will not be honored on - requests for additional ticket-granting tickets. - - If the requested start time is absent or indicates a time in the - past, then the start time of the ticket is set to the authentication - server's current time. If it indicates a time in the future, but the - POSTDATED option has not been specified or the MAY-POSTDATE flag is - not set in the TGT, then the error KDC_ERR_CANNOT_POSTDATE is - returned. Otherwise, if the ticket-granting ticket has the - MAYPOSTDATE flag set, then the resulting ticket will be postdated and - the requested starttime is checked against the policy of the local - realm. If acceptable, the ticket's start time is set as requested, - and the INVALID flag is set. The postdated ticket must be validated - before use by presenting it to the KDC after the starttime has been - reached. However, in no case may the starttime, endtime, or renew- - till time of a newly-issued postdated ticket extend beyond the - renew-till time of the ticket-granting ticket. - - If the ENC-TKT-IN-SKEY option has been specified and an additional - ticket has been included in the request, the KDC will decrypt the - additional ticket using the key for the server to which the - additional ticket was issued and verify that it is a ticket-granting - ticket. If the name of the requested server is missing from the - request, the name of the client in the additional ticket will be - used. Otherwise the name of the requested server will be compared to - the name of the client in the additional ticket and if different, the - request will be rejected. If the request succeeds, the session key - from the additional ticket will be used to encrypt the new ticket - that is issued instead of using the key of the server for which the - new ticket will be used (This allows easy implementation of user-to- - user authentication [6], which uses ticket-granting ticket session - keys in lieu of secret server keys in situations where such secret - - - -Kohl & Neuman [Page 28] - -RFC 1510 Kerberos September 1993 - - - keys could be easily compromised.). - - If the name of the server in the ticket that is presented to the KDC - as part of the authentication header is not that of the ticket- - granting server itself, and the server is registered in the realm of - the KDC, If the RENEW option is requested, then the KDC will verify - that the RENEWABLE flag is set in the ticket and that the renew_till - time is still in the future. If the VALIDATE option is rqeuested, - the KDC will check that the starttime has passed and the INVALID flag - is set. If the PROXY option is requested, then the KDC will check - that the PROXIABLE flag is set in the ticket. If the tests succeed, - the KDC will issue the appropriate new ticket. - - Whenever a request is made to the ticket-granting server, the - presented ticket(s) is(are) checked against a hot-list of tickets - which have been canceled. This hot-list might be implemented by - storing a range of issue dates for "suspect tickets"; if a presented - ticket had an authtime in that range, it would be rejected. In this - way, a stolen ticket-granting ticket or renewable ticket cannot be - used to gain additional tickets (renewals or otherwise) once the - theft has been reported. Any normal ticket obtained before it was - reported stolen will still be valid (because they require no - interaction with the KDC), but only until their normal expiration - time. - - The ciphertext part of the response in the KRB_TGS_REP message is - encrypted in the sub-session key from the Authenticator, if present, - or the session key key from the ticket-granting ticket. It is not - encrypted using the client's secret key. Furthermore, the client's - key's expiration date and the key version number fields are left out - since these values are stored along with the client's database - record, and that record is not needed to satisfy a request based on a - ticket-granting ticket. See section A.6 for pseudocode. - -3.3.3.1. Encoding the transited field - - If the identity of the server in the TGT that is presented to the KDC - as part of the authentication header is that of the ticket-granting - service, but the TGT was issued from another realm, the KDC will look - up the inter-realm key shared with that realm and use that key to - decrypt the ticket. If the ticket is valid, then the KDC will honor - the request, subject to the constraints outlined above in the section - describing the AS exchange. The realm part of the client's identity - will be taken from the ticket-granting ticket. The name of the realm - that issued the ticket-granting ticket will be added to the transited - field of the ticket to be issued. This is accomplished by reading - the transited field from the ticket-granting ticket (which is treated - as an unordered set of realm names), adding the new realm to the set, - - - -Kohl & Neuman [Page 29] - -RFC 1510 Kerberos September 1993 - - - then constructing and writing out its encoded (shorthand) form (this - may involve a rearrangement of the existing encoding). - - Note that the ticket-granting service does not add the name of its - own realm. Instead, its responsibility is to add the name of the - previous realm. This prevents a malicious Kerberos server from - intentionally leaving out its own name (it could, however, omit other - realms' names). - - The names of neither the local realm nor the principal's realm are to - be included in the transited field. They appear elsewhere in the - ticket and both are known to have taken part in authenticating the - principal. Since the endpoints are not included, both local and - single-hop inter-realm authentication result in a transited field - that is empty. - - Because the name of each realm transited is added to this field, - it might potentially be very long. To decrease the length of this - field, its contents are encoded. The initially supported encoding is - optimized for the normal case of inter-realm communication: a - hierarchical arrangement of realms using either domain or X.500 style - realm names. This encoding (called DOMAIN-X500-COMPRESS) is now - described. - - Realm names in the transited field are separated by a ",". The ",", - "\", trailing "."s, and leading spaces (" ") are special characters, - and if they are part of a realm name, they must be quoted in the - transited field by preceding them with a "\". - - A realm name ending with a "." is interpreted as being prepended to - the previous realm. For example, we can encode traversal of EDU, - MIT.EDU, ATHENA.MIT.EDU, WASHINGTON.EDU, and CS.WASHINGTON.EDU as: - - "EDU,MIT.,ATHENA.,WASHINGTON.EDU,CS.". - - Note that if ATHENA.MIT.EDU, or CS.WASHINGTON.EDU were endpoints, - that they would not be included in this field, and we would have: - - "EDU,MIT.,WASHINGTON.EDU" - - A realm name beginning with a "/" is interpreted as being appended to - the previous realm (For the purpose of appending, the realm preceding - the first listed realm is considered to be the null realm ("")). If - it is to stand by itself, then it should be preceded by a space (" - "). For example, we can encode traversal of /COM/HP/APOLLO, /COM/HP, - /COM, and /COM/DEC as: - - "/COM,/HP,/APOLLO, /COM/DEC". - - - -Kohl & Neuman [Page 30] - -RFC 1510 Kerberos September 1993 - - - Like the example above, if /COM/HP/APOLLO and /COM/DEC are endpoints, - they they would not be included in this field, and we would have: - - "/COM,/HP" - - A null subfield preceding or following a "," indicates that all - realms between the previous realm and the next realm have been - traversed (For the purpose of interpreting null subfields, the - client's realm is considered to precede those in the transited field, - and the server's realm is considered to follow them.). Thus, "," - means that all realms along the path between the client and the - server have been traversed. ",EDU, /COM," means that that all realms - from the client's realm up to EDU (in a domain style hierarchy) have - been traversed, and that everything from /COM down to the server's - realm in an X.500 style has also been traversed. This could occur if - the EDU realm in one hierarchy shares an inter-realm key directly - with the /COM realm in another hierarchy. - -3.3.4. Receipt of KRB_TGS_REP message - - When the KRB_TGS_REP is received by the client, it is processed in - the same manner as the KRB_AS_REP processing described above. The - primary difference is that the ciphertext part of the response must - be decrypted using the session key from the ticket-granting ticket - rather than the client's secret key. See section A.7 for pseudocode. - -3.4. The KRB_SAFE Exchange - - The KRB_SAFE message may be used by clients requiring the ability to - detect modifications of messages they exchange. It achieves this by - including a keyed collisionproof checksum of the user data and some - control information. The checksum is keyed with an encryption key - (usually the last key negotiated via subkeys, or the session key if - no negotiation has occured). - -3.4.1. Generation of a KRB_SAFE message - - When an application wishes to send a KRB_SAFE message, it collects - its data and the appropriate control information and computes a - checksum over them. The checksum algorithm should be some sort of - keyed one-way hash function (such as the RSA-MD5-DES checksum - algorithm specified in section 6.4.5, or the DES MAC), generated - using the sub-session key if present, or the session key. Different - algorithms may be selected by changing the checksum type in the - message. Unkeyed or non-collision-proof checksums are not suitable - for this use. - - The control information for the KRB_SAFE message includes both a - - - -Kohl & Neuman [Page 31] - -RFC 1510 Kerberos September 1993 - - - timestamp and a sequence number. The designer of an application - using the KRB_SAFE message must choose at least one of the two - mechanisms. This choice should be based on the needs of the - application protocol. - - Sequence numbers are useful when all messages sent will be received - by one's peer. Connection state is presently required to maintain - the session key, so maintaining the next sequence number should not - present an additional problem. - - If the application protocol is expected to tolerate lost messages - without them being resent, the use of the timestamp is the - appropriate replay detection mechanism. Using timestamps is also the - appropriate mechanism for multi-cast protocols where all of one's - peers share a common sub-session key, but some messages will be sent - to a subset of one's peers. - - After computing the checksum, the client then transmits the - information and checksum to the recipient in the message format - specified in section 5.6.1. - -3.4.2. Receipt of KRB_SAFE message - - When an application receives a KRB_SAFE message, it verifies it as - follows. If any error occurs, an error code is reported for use by - the application. - - The message is first checked by verifying that the protocol version - and type fields match the current version and KRB_SAFE, respectively. - A mismatch generates a KRB_AP_ERR_BADVERSION or KRB_AP_ERR_MSG_TYPE - error. The application verifies that the checksum used is a - collisionproof keyed checksum, and if it is not, a - KRB_AP_ERR_INAPP_CKSUM error is generated. The recipient verifies - that the operating system's report of the sender's address matches - the sender's address in the message, and (if a recipient address is - specified or the recipient requires an address) that one of the - recipient's addresses appears as the recipient's address in the - message. A failed match for either case generates a - KRB_AP_ERR_BADADDR error. Then the timestamp and usec and/or the - sequence number fields are checked. If timestamp and usec are - expected and not present, or they are present but not current, the - KRB_AP_ERR_SKEW error is generated. If the server name, along with - the client name, time and microsecond fields from the Authenticator - match any recently-seen such tuples, the KRB_AP_ERR_REPEAT error is - generated. If an incorrect sequence number is included, or a - sequence number is expected but not present, the KRB_AP_ERR_BADORDER - error is generated. If neither a timestamp and usec or a sequence - number is present, a KRB_AP_ERR_MODIFIED error is generated. - - - -Kohl & Neuman [Page 32] - -RFC 1510 Kerberos September 1993 - - - Finally, the checksum is computed over the data and control - information, and if it doesn't match the received checksum, a - KRB_AP_ERR_MODIFIED error is generated. - - If all the checks succeed, the application is assured that the - message was generated by its peer and was not modified in transit. - -3.5. The KRB_PRIV Exchange - - The KRB_PRIV message may be used by clients requiring confidentiality - and the ability to detect modifications of exchanged messages. It - achieves this by encrypting the messages and adding control - information. - -3.5.1. Generation of a KRB_PRIV message - - When an application wishes to send a KRB_PRIV message, it collects - its data and the appropriate control information (specified in - section 5.7.1) and encrypts them under an encryption key (usually the - last key negotiated via subkeys, or the session key if no negotiation - has occured). As part of the control information, the client must - choose to use either a timestamp or a sequence number (or both); see - the discussion in section 3.4.1 for guidelines on which to use. - After the user data and control information are encrypted, the client - transmits the ciphertext and some "envelope" information to the - recipient. - -3.5.2. Receipt of KRB_PRIV message - - When an application receives a KRB_PRIV message, it verifies it as - follows. If any error occurs, an error code is reported for use by - the application. - - The message is first checked by verifying that the protocol version - and type fields match the current version and KRB_PRIV, respectively. - A mismatch generates a KRB_AP_ERR_BADVERSION or KRB_AP_ERR_MSG_TYPE - error. The application then decrypts the ciphertext and processes - the resultant plaintext. If decryption shows the data to have been - modified, a KRB_AP_ERR_BAD_INTEGRITY error is generated. The - recipient verifies that the operating system's report of the sender's - address matches the sender's address in the message, and (if a - recipient address is specified or the recipient requires an address) - that one of the recipient's addresses appears as the recipient's - address in the message. A failed match for either case generates a - KRB_AP_ERR_BADADDR error. Then the timestamp and usec and/or the - sequence number fields are checked. If timestamp and usec are - expected and not present, or they are present but not current, the - KRB_AP_ERR_SKEW error is generated. If the server name, along with - - - -Kohl & Neuman [Page 33] - -RFC 1510 Kerberos September 1993 - - - the client name, time and microsecond fields from the Authenticator - match any recently-seen such tuples, the KRB_AP_ERR_REPEAT error is - generated. If an incorrect sequence number is included, or a - sequence number is expected but not present, the KRB_AP_ERR_BADORDER - error is generated. If neither a timestamp and usec or a sequence - number is present, a KRB_AP_ERR_MODIFIED error is generated. - - If all the checks succeed, the application can assume the message was - generated by its peer, and was securely transmitted (without - intruders able to see the unencrypted contents). - -3.6. The KRB_CRED Exchange - - The KRB_CRED message may be used by clients requiring the ability to - send Kerberos credentials from one host to another. It achieves this - by sending the tickets together with encrypted data containing the - session keys and other information associated with the tickets. - -3.6.1. Generation of a KRB_CRED message - - When an application wishes to send a KRB_CRED message it first (using - the KRB_TGS exchange) obtains credentials to be sent to the remote - host. It then constructs a KRB_CRED message using the ticket or - tickets so obtained, placing the session key needed to use each - ticket in the key field of the corresponding KrbCredInfo sequence of - the encrypted part of the the KRB_CRED message. - - Other information associated with each ticket and obtained during the - KRB_TGS exchange is also placed in the corresponding KrbCredInfo - sequence in the encrypted part of the KRB_CRED message. The current - time and, if specifically required by the application the nonce, s- - address, and raddress fields, are placed in the encrypted part of the - KRB_CRED message which is then encrypted under an encryption key - previosuly exchanged in the KRB_AP exchange (usually the last key - negotiated via subkeys, or the session key if no negotiation has - occured). - -3.6.2. Receipt of KRB_CRED message - - When an application receives a KRB_CRED message, it verifies it. If - any error occurs, an error code is reported for use by the - application. The message is verified by checking that the protocol - version and type fields match the current version and KRB_CRED, - respectively. A mismatch generates a KRB_AP_ERR_BADVERSION or - KRB_AP_ERR_MSG_TYPE error. The application then decrypts the - ciphertext and processes the resultant plaintext. If decryption shows - the data to have been modified, a KRB_AP_ERR_BAD_INTEGRITY error is - generated. - - - -Kohl & Neuman [Page 34] - -RFC 1510 Kerberos September 1993 - - - If present or required, the recipient verifies that the operating - system's report of the sender's address matches the sender's address - in the message, and that one of the recipient's addresses appears as - the recipient's address in the message. A failed match for either - case generates a KRB_AP_ERR_BADADDR error. The timestamp and usec - fields (and the nonce field if required) are checked next. If the - timestamp and usec are not present, or they are present but not - current, the KRB_AP_ERR_SKEW error is generated. - - If all the checks succeed, the application stores each of the new - tickets in its ticket cache together with the session key and other - information in the corresponding KrbCredInfo sequence from the - encrypted part of the KRB_CRED message. - -4. The Kerberos Database - - The Kerberos server must have access to a database containing the - principal identifiers and secret keys of principals to be - authenticated (The implementation of the Kerberos server need not - combine the database and the server on the same machine; it is - feasible to store the principal database in, say, a network name - service, as long as the entries stored therein are protected from - disclosure to and modification by unauthorized parties. However, we - recommend against such strategies, as they can make system management - and threat analysis quite complex.). - -4.1. Database contents - - A database entry should contain at least the following fields: - - Field Value - - name Principal's identifier - key Principal's secret key - p_kvno Principal's key version - max_life Maximum lifetime for Tickets - max_renewable_life Maximum total lifetime for renewable - Tickets - - The name field is an encoding of the principal's identifier. The key - field contains an encryption key. This key is the principal's secret - key. (The key can be encrypted before storage under a Kerberos - "master key" to protect it in case the database is compromised but - the master key is not. In that case, an extra field must be added to - indicate the master key version used, see below.) The p_kvno field is - the key version number of the principal's secret key. The max_life - field contains the maximum allowable lifetime (endtime - starttime) - for any Ticket issued for this principal. The max_renewable_life - - - -Kohl & Neuman [Page 35] - -RFC 1510 Kerberos September 1993 - - - field contains the maximum allowable total lifetime for any renewable - Ticket issued for this principal. (See section 3.1 for a description - of how these lifetimes are used in determining the lifetime of a - given Ticket.) - - A server may provide KDC service to several realms, as long as the - database representation provides a mechanism to distinguish between - principal records with identifiers which differ only in the realm - name. - - When an application server's key changes, if the change is routine - (i.e., not the result of disclosure of the old key), the old key - should be retained by the server until all tickets that had been - issued using that key have expired. Because of this, it is possible - for several keys to be active for a single principal. Ciphertext - encrypted in a principal's key is always tagged with the version of - the key that was used for encryption, to help the recipient find the - proper key for decryption. - - When more than one key is active for a particular principal, the - principal will have more than one record in the Kerberos database. - The keys and key version numbers will differ between the records (the - rest of the fields may or may not be the same). Whenever Kerberos - issues a ticket, or responds to a request for initial authentication, - the most recent key (known by the Kerberos server) will be used for - encryption. This is the key with the highest key version number. - -4.2. Additional fields - - Project Athena's KDC implementation uses additional fields in its - database: - - Field Value - - K_kvno Kerberos' key version - expiration Expiration date for entry - attributes Bit field of attributes - mod_date Timestamp of last modification - mod_name Modifying principal's identifier - - The K_kvno field indicates the key version of the Kerberos master key - under which the principal's secret key is encrypted. - - After an entry's expiration date has passed, the KDC will return an - error to any client attempting to gain tickets as or for the - principal. (A database may want to maintain two expiration dates: - one for the principal, and one for the principal's current key. This - allows password aging to work independently of the principal's - - - -Kohl & Neuman [Page 36] - -RFC 1510 Kerberos September 1993 - - - expiration date. However, due to the limited space in the responses, - the KDC must combine the key expiration and principal expiration date - into a single value called "key_exp", which is used as a hint to the - user to take administrative action.) - - The attributes field is a bitfield used to govern the operations - involving the principal. This field might be useful in conjunction - with user registration procedures, for site-specific policy - implementations (Project Athena currently uses it for their user - registration process controlled by the system-wide database service, - Moira [7]), or to identify the "string to key" conversion algorithm - used for a principal's key. (See the discussion of the padata field - in section 5.4.2 for details on why this can be useful.) Other bits - are used to indicate that certain ticket options should not be - allowed in tickets encrypted under a principal's key (one bit each): - Disallow issuing postdated tickets, disallow issuing forwardable - tickets, disallow issuing tickets based on TGT authentication, - disallow issuing renewable tickets, disallow issuing proxiable - tickets, and disallow issuing tickets for which the principal is the - server. - - The mod_date field contains the time of last modification of the - entry, and the mod_name field contains the name of the principal - which last modified the entry. - -4.3. Frequently Changing Fields - - Some KDC implementations may wish to maintain the last time that a - request was made by a particular principal. Information that might - be maintained includes the time of the last request, the time of the - last request for a ticket-granting ticket, the time of the last use - of a ticket-granting ticket, or other times. This information can - then be returned to the user in the last-req field (see section 5.2). - - Other frequently changing information that can be maintained is the - latest expiration time for any tickets that have been issued using - each key. This field would be used to indicate how long old keys - must remain valid to allow the continued use of outstanding tickets. - -4.4. Site Constants - - The KDC implementation should have the following configurable - constants or options, to allow an administrator to make and enforce - policy decisions: - - + The minimum supported lifetime (used to determine whether the - KDC_ERR_NEVER_VALID error should be returned). This constant - should reflect reasonable expectations of round-trip time to the - - - -Kohl & Neuman [Page 37] - -RFC 1510 Kerberos September 1993 - - - KDC, encryption/decryption time, and processing time by the client - and target server, and it should allow for a minimum "useful" - lifetime. - - + The maximum allowable total (renewable) lifetime of a ticket - (renew_till - starttime). - - + The maximum allowable lifetime of a ticket (endtime - starttime). - - + Whether to allow the issue of tickets with empty address fields - (including the ability to specify that such tickets may only be - issued if the request specifies some authorization_data). - - + Whether proxiable, forwardable, renewable or post-datable tickets - are to be issued. - -5. Message Specifications - - The following sections describe the exact contents and encoding of - protocol messages and objects. The ASN.1 base definitions are - presented in the first subsection. The remaining subsections specify - the protocol objects (tickets and authenticators) and messages. - Specification of encryption and checksum techniques, and the fields - related to them, appear in section 6. - -5.1. ASN.1 Distinguished Encoding Representation - - All uses of ASN.1 in Kerberos shall use the Distinguished Encoding - Representation of the data elements as described in the X.509 - specification, section 8.7 [8]. - -5.2. ASN.1 Base Definitions - - The following ASN.1 base definitions are used in the rest of this - section. Note that since the underscore character (_) is not - permitted in ASN.1 names, the hyphen (-) is used in its place for the - purposes of ASN.1 names. - - Realm ::= GeneralString - PrincipalName ::= SEQUENCE { - name-type[0] INTEGER, - name-string[1] SEQUENCE OF GeneralString - } - - Kerberos realms are encoded as GeneralStrings. Realms shall not - contain a character with the code 0 (the ASCII NUL). Most realms - will usually consist of several components separated by periods (.), - in the style of Internet Domain Names, or separated by slashes (/) in - - - -Kohl & Neuman [Page 38] - -RFC 1510 Kerberos September 1993 - - - the style of X.500 names. Acceptable forms for realm names are - specified in section 7. A PrincipalName is a typed sequence of - components consisting of the following sub-fields: - - name-type This field specifies the type of name that follows. - Pre-defined values for this field are - specified in section 7.2. The name-type should be - treated as a hint. Ignoring the name type, no two - names can be the same (i.e., at least one of the - components, or the realm, must be different). - This constraint may be eliminated in the future. - - name-string This field encodes a sequence of components that - form a name, each component encoded as a General - String. Taken together, a PrincipalName and a Realm - form a principal identifier. Most PrincipalNames - will have only a few components (typically one or two). - - KerberosTime ::= GeneralizedTime - -- Specifying UTC time zone (Z) - - The timestamps used in Kerberos are encoded as GeneralizedTimes. An - encoding shall specify the UTC time zone (Z) and shall not include - any fractional portions of the seconds. It further shall not include - any separators. Example: The only valid format for UTC time 6 - minutes, 27 seconds after 9 pm on 6 November 1985 is 19851106210627Z. - - HostAddress ::= SEQUENCE { - addr-type[0] INTEGER, - address[1] OCTET STRING - } - - HostAddresses ::= SEQUENCE OF SEQUENCE { - addr-type[0] INTEGER, - address[1] OCTET STRING - } - - - The host adddress encodings consists of two fields: - - addr-type This field specifies the type of address that - follows. Pre-defined values for this field are - specified in section 8.1. - - - address This field encodes a single address of type addr-type. - - The two forms differ slightly. HostAddress contains exactly one - - - -Kohl & Neuman [Page 39] - -RFC 1510 Kerberos September 1993 - - - address; HostAddresses contains a sequence of possibly many - addresses. - - AuthorizationData ::= SEQUENCE OF SEQUENCE { - ad-type[0] INTEGER, - ad-data[1] OCTET STRING - } - - - ad-data This field contains authorization data to be - interpreted according to the value of the - corresponding ad-type field. - - ad-type This field specifies the format for the ad-data - subfield. All negative values are reserved for - local use. Non-negative values are reserved for - registered use. - - APOptions ::= BIT STRING { - reserved(0), - use-session-key(1), - mutual-required(2) - } - - - TicketFlags ::= BIT STRING { - reserved(0), - forwardable(1), - forwarded(2), - proxiable(3), - proxy(4), - may-postdate(5), - postdated(6), - invalid(7), - renewable(8), - initial(9), - pre-authent(10), - hw-authent(11) - } - - KDCOptions ::= BIT STRING { - reserved(0), - forwardable(1), - forwarded(2), - proxiable(3), - proxy(4), - allow-postdate(5), - postdated(6), - - - -Kohl & Neuman [Page 40] - -RFC 1510 Kerberos September 1993 - - - unused7(7), - renewable(8), - unused9(9), - unused10(10), - unused11(11), - renewable-ok(27), - enc-tkt-in-skey(28), - renew(30), - validate(31) - } - - - LastReq ::= SEQUENCE OF SEQUENCE { - lr-type[0] INTEGER, - lr-value[1] KerberosTime - } - - lr-type This field indicates how the following lr-value - field is to be interpreted. Negative values indicate - that the information pertains only to the - responding server. Non-negative values pertain to - all servers for the realm. - - If the lr-type field is zero (0), then no information - is conveyed by the lr-value subfield. If the - absolute value of the lr-type field is one (1), - then the lr-value subfield is the time of last - initial request for a TGT. If it is two (2), then - the lr-value subfield is the time of last initial - request. If it is three (3), then the lr-value - subfield is the time of issue for the newest - ticket-granting ticket used. If it is four (4), - then the lr-value subfield is the time of the last - renewal. If it is five (5), then the lr-value - subfield is the time of last request (of any - type). - - lr-value This field contains the time of the last request. - The time must be interpreted according to the contents - of the accompanying lr-type subfield. - - See section 6 for the definitions of Checksum, ChecksumType, - EncryptedData, EncryptionKey, EncryptionType, and KeyType. - - - - - - - - -Kohl & Neuman [Page 41] - -RFC 1510 Kerberos September 1993 - - -5.3. Tickets and Authenticators - - This section describes the format and encryption parameters for - tickets and authenticators. When a ticket or authenticator is - included in a protocol message it is treated as an opaque object. - -5.3.1. Tickets - - A ticket is a record that helps a client authenticate to a service. - A Ticket contains the following information: - -Ticket ::= [APPLICATION 1] SEQUENCE { - tkt-vno[0] INTEGER, - realm[1] Realm, - sname[2] PrincipalName, - enc-part[3] EncryptedData -} --- Encrypted part of ticket -EncTicketPart ::= [APPLICATION 3] SEQUENCE { - flags[0] TicketFlags, - key[1] EncryptionKey, - crealm[2] Realm, - cname[3] PrincipalName, - transited[4] TransitedEncoding, - authtime[5] KerberosTime, - starttime[6] KerberosTime OPTIONAL, - endtime[7] KerberosTime, - renew-till[8] KerberosTime OPTIONAL, - caddr[9] HostAddresses OPTIONAL, - authorization-data[10] AuthorizationData OPTIONAL -} --- encoded Transited field -TransitedEncoding ::= SEQUENCE { - tr-type[0] INTEGER, -- must be registered - contents[1] OCTET STRING -} - - The encoding of EncTicketPart is encrypted in the key shared by - Kerberos and the end server (the server's secret key). See section 6 - for the format of the ciphertext. - - tkt-vno This field specifies the version number for the ticket - format. This document describes version number 5. - - realm This field specifies the realm that issued a ticket. It - also serves to identify the realm part of the server's - principal identifier. Since a Kerberos server can only - issue tickets for servers within its realm, the two will - - - -Kohl & Neuman [Page 42] - -RFC 1510 Kerberos September 1993 - - - always be identical. - - sname This field specifies the name part of the server's - identity. - - enc-part This field holds the encrypted encoding of the - EncTicketPart sequence. - - flags This field indicates which of various options were used or - requested when the ticket was issued. It is a bit-field, - where the selected options are indicated by the bit being - set (1), and the unselected options and reserved fields - being reset (0). Bit 0 is the most significant bit. The - encoding of the bits is specified in section 5.2. The - flags are described in more detail above in section 2. The - meanings of the flags are: - - Bit(s) Name Description - - 0 RESERVED Reserved for future expansion of this - field. - - 1 FORWARDABLE The FORWARDABLE flag is normally only - interpreted by the TGS, and can be - ignored by end servers. When set, - this flag tells the ticket-granting - server that it is OK to issue a new - ticket- granting ticket with a - different network address based on - the presented ticket. - - 2 FORWARDED When set, this flag indicates that - the ticket has either been forwarded - or was issued based on authentication - involving a forwarded ticket-granting - ticket. - - 3 PROXIABLE The PROXIABLE flag is normally only - interpreted by the TGS, and can be - ignored by end servers. The PROXIABLE - flag has an interpretation identical - to that of the FORWARDABLE flag, - except that the PROXIABLE flag tells - the ticket-granting server that only - non- ticket-granting tickets may be - issued with different network - addresses. - - - - -Kohl & Neuman [Page 43] - -RFC 1510 Kerberos September 1993 - - - 4 PROXY When set, this flag indicates that a - ticket is a proxy. - - 5 MAY-POSTDATE The MAY-POSTDATE flag is normally - only interpreted by the TGS, and can - be ignored by end servers. This flag - tells the ticket-granting server that - a post- dated ticket may be issued - based on this ticket-granting ticket. - - 6 POSTDATED This flag indicates that this ticket - has been postdated. The end-service - can check the authtime field to see - when the original authentication - occurred. - - 7 INVALID This flag indicates that a ticket is - invalid, and it must be validated by - the KDC before use. Application - servers must reject tickets which - have this flag set. - - 8 RENEWABLE The RENEWABLE flag is normally only - interpreted by the TGS, and can - usually be ignored by end servers - (some particularly careful servers - may wish to disallow renewable - tickets). A renewable ticket can be - used to obtain a replacement ticket - that expires at a later date. - - 9 INITIAL This flag indicates that this ticket - was issued using the AS protocol, and - not issued based on a ticket-granting - ticket. - - 10 PRE-AUTHENT This flag indicates that during - initial authentication, the client - was authenticated by the KDC before a - ticket was issued. The strength of - the preauthentication method is not - indicated, but is acceptable to the - KDC. - - 11 HW-AUTHENT This flag indicates that the protocol - employed for initial authentication - required the use of hardware expected - to be possessed solely by the named - - - -Kohl & Neuman [Page 44] - -RFC 1510 Kerberos September 1993 - - - client. The hardware authentication - method is selected by the KDC and the - strength of the method is not - indicated. - - 12-31 RESERVED Reserved for future use. - - key This field exists in the ticket and the KDC response and is - used to pass the session key from Kerberos to the - application server and the client. The field's encoding is - described in section 6.2. - - crealm This field contains the name of the realm in which the - client is registered and in which initial authentication - took place. - - cname This field contains the name part of the client's principal - identifier. - - transited This field lists the names of the Kerberos realms that took - part in authenticating the user to whom this ticket was - issued. It does not specify the order in which the realms - were transited. See section 3.3.3.1 for details on how - this field encodes the traversed realms. - - authtime This field indicates the time of initial authentication for - the named principal. It is the time of issue for the - original ticket on which this ticket is based. It is - included in the ticket to provide additional information to - the end service, and to provide the necessary information - for implementation of a `hot list' service at the KDC. An - end service that is particularly paranoid could refuse to - accept tickets for which the initial authentication - occurred "too far" in the past. - - This field is also returned as part of the response from - the KDC. When returned as part of the response to initial - authentication (KRB_AS_REP), this is the current time on - the Kerberos server (It is NOT recommended that this time - value be used to adjust the workstation's clock since the - workstation cannot reliably determine that such a - KRB_AS_REP actually came from the proper KDC in a timely - manner.). - - starttime This field in the ticket specifies the time after which the - ticket is valid. Together with endtime, this field - specifies the life of the ticket. If it is absent from - the ticket, its value should be treated as that of the - - - -Kohl & Neuman [Page 45] - -RFC 1510 Kerberos September 1993 - - - authtime field. - - endtime This field contains the time after which the ticket will - not be honored (its expiration time). Note that individual - services may place their own limits on the life of a ticket - and may reject tickets which have not yet expired. As - such, this is really an upper bound on the expiration time - for the ticket. - - renew-till This field is only present in tickets that have the - RENEWABLE flag set in the flags field. It indicates the - maximum endtime that may be included in a renewal. It can - be thought of as the absolute expiration time for the - ticket, including all renewals. - - caddr This field in a ticket contains zero (if omitted) or more - (if present) host addresses. These are the addresses from - which the ticket can be used. If there are no addresses, - the ticket can be used from any location. The decision - by the KDC to issue or by the end server to accept zero- - address tickets is a policy decision and is left to the - Kerberos and end-service administrators; they may refuse to - issue or accept such tickets. The suggested and default - policy, however, is that such tickets will only be issued - or accepted when additional information that can be used to - restrict the use of the ticket is included in the - authorization_data field. Such a ticket is a capability. - - Network addresses are included in the ticket to make it - harder for an attacker to use stolen credentials. Because - the session key is not sent over the network in cleartext, - credentials can't be stolen simply by listening to the - network; an attacker has to gain access to the session key - (perhaps through operating system security breaches or a - careless user's unattended session) to make use of stolen - tickets. - - It is important to note that the network address from which - a connection is received cannot be reliably determined. - Even if it could be, an attacker who has compromised the - client's workstation could use the credentials from there. - Including the network addresses only makes it more - difficult, not impossible, for an attacker to walk off with - stolen credentials and then use them from a "safe" - location. - - - - - - -Kohl & Neuman [Page 46] - -RFC 1510 Kerberos September 1993 - - - authorization-data The authorization-data field is used to pass - authorization data from the principal on whose behalf a - ticket was issued to the application service. If no - authorization data is included, this field will be left - out. The data in this field are specific to the end - service. It is expected that the field will contain the - names of service specific objects, and the rights to those - objects. The format for this field is described in section - 5.2. Although Kerberos is not concerned with the format of - the contents of the subfields, it does carry type - information (ad-type). - - By using the authorization_data field, a principal is able - to issue a proxy that is valid for a specific purpose. For - example, a client wishing to print a file can obtain a file - server proxy to be passed to the print server. By - specifying the name of the file in the authorization_data - field, the file server knows that the print server can only - use the client's rights when accessing the particular file - to be printed. - - It is interesting to note that if one specifies the - authorization-data field of a proxy and leaves the host - addresses blank, the resulting ticket and session key can - be treated as a capability. See [9] for some suggested - uses of this field. - - The authorization-data field is optional and does not have - to be included in a ticket. - -5.3.2. Authenticators - - An authenticator is a record sent with a ticket to a server to - certify the client's knowledge of the encryption key in the ticket, - to help the server detect replays, and to help choose a "true session - key" to use with the particular session. The encoding is encrypted - in the ticket's session key shared by the client and the server: - --- Unencrypted authenticator -Authenticator ::= [APPLICATION 2] SEQUENCE { - authenticator-vno[0] INTEGER, - crealm[1] Realm, - cname[2] PrincipalName, - cksum[3] Checksum OPTIONAL, - cusec[4] INTEGER, - ctime[5] KerberosTime, - subkey[6] EncryptionKey OPTIONAL, - seq-number[7] INTEGER OPTIONAL, - - - -Kohl & Neuman [Page 47] - -RFC 1510 Kerberos September 1993 - - - authorization-data[8] AuthorizationData OPTIONAL - } - - authenticator-vno This field specifies the version number for the - format of the authenticator. This document specifies - version 5. - - crealm and cname These fields are the same as those described for the - ticket in section 5.3.1. - - cksum This field contains a checksum of the the application data - that accompanies the KRB_AP_REQ. - - cusec This field contains the microsecond part of the client's - timestamp. Its value (before encryption) ranges from 0 to - 999999. It often appears along with ctime. The two fields - are used together to specify a reasonably accurate - timestamp. - - ctime This field contains the current time on the client's host. - - subkey This field contains the client's choice for an encryption - key which is to be used to protect this specific - application session. Unless an application specifies - otherwise, if this field is left out the session key from - the ticket will be used. - - seq-number This optional field includes the initial sequence number - to be used by the KRB_PRIV or KRB_SAFE messages when - sequence numbers are used to detect replays (It may also be - used by application specific messages). When included in - the authenticator this field specifies the initial sequence - number for messages from the client to the server. When - included in the AP-REP message, the initial sequence number - is that for messages from the server to the client. When - used in KRB_PRIV or KRB_SAFE messages, it is incremented by - one after each message is sent. - - For sequence numbers to adequately support the detection of - replays they should be non-repeating, even across - connection boundaries. The initial sequence number should - be random and uniformly distributed across the full space - of possible sequence numbers, so that it cannot be guessed - by an attacker and so that it and the successive sequence - numbers do not repeat other sequences. - - - - - - -Kohl & Neuman [Page 48] - -RFC 1510 Kerberos September 1993 - - - authorization-data This field is the same as described for the ticket - in section 5.3.1. It is optional and will only appear when - additional restrictions are to be placed on the use of a - ticket, beyond those carried in the ticket itself. - -5.4. Specifications for the AS and TGS exchanges - - This section specifies the format of the messages used in exchange - between the client and the Kerberos server. The format of possible - error messages appears in section 5.9.1. - -5.4.1. KRB_KDC_REQ definition - - The KRB_KDC_REQ message has no type of its own. Instead, its type is - one of KRB_AS_REQ or KRB_TGS_REQ depending on whether the request is - for an initial ticket or an additional ticket. In either case, the - message is sent from the client to the Authentication Server to - request credentials for a service. - -The message fields are: - -AS-REQ ::= [APPLICATION 10] KDC-REQ -TGS-REQ ::= [APPLICATION 12] KDC-REQ - -KDC-REQ ::= SEQUENCE { - pvno[1] INTEGER, - msg-type[2] INTEGER, - padata[3] SEQUENCE OF PA-DATA OPTIONAL, - req-body[4] KDC-REQ-BODY -} - -PA-DATA ::= SEQUENCE { - padata-type[1] INTEGER, - padata-value[2] OCTET STRING, - -- might be encoded AP-REQ -} - -KDC-REQ-BODY ::= SEQUENCE { - kdc-options[0] KDCOptions, - cname[1] PrincipalName OPTIONAL, - -- Used only in AS-REQ - realm[2] Realm, -- Server's realm - -- Also client's in AS-REQ - sname[3] PrincipalName OPTIONAL, - from[4] KerberosTime OPTIONAL, - till[5] KerberosTime, - rtime[6] KerberosTime OPTIONAL, - nonce[7] INTEGER, - - - -Kohl & Neuman [Page 49] - -RFC 1510 Kerberos September 1993 - - - etype[8] SEQUENCE OF INTEGER, -- EncryptionType, - -- in preference order - addresses[9] HostAddresses OPTIONAL, - enc-authorization-data[10] EncryptedData OPTIONAL, - -- Encrypted AuthorizationData encoding - additional-tickets[11] SEQUENCE OF Ticket OPTIONAL -} - - The fields in this message are: - - pvno This field is included in each message, and specifies the - protocol version number. This document specifies protocol - version 5. - - msg-type This field indicates the type of a protocol message. It - will almost always be the same as the application - identifier associated with a message. It is included to - make the identifier more readily accessible to the - application. For the KDC-REQ message, this type will be - KRB_AS_REQ or KRB_TGS_REQ. - - padata The padata (pre-authentication data) field contains a of - authentication information which may be needed before - credentials can be issued or decrypted. In the case of - requests for additional tickets (KRB_TGS_REQ), this field - will include an element with padata-type of PA-TGS-REQ and - data of an authentication header (ticket-granting ticket - and authenticator). The checksum in the authenticator - (which must be collisionproof) is to be computed over the - KDC-REQ-BODY encoding. In most requests for initial - authentication (KRB_AS_REQ) and most replies (KDC-REP), the - padata field will be left out. - - This field may also contain information needed by certain - extensions to the Kerberos protocol. For example, it might - be used to initially verify the identity of a client before - any response is returned. This is accomplished with a - padata field with padata-type equal to PA-ENC-TIMESTAMP and - padata-value defined as follows: - - padata-type ::= PA-ENC-TIMESTAMP - padata-value ::= EncryptedData -- PA-ENC-TS-ENC - - PA-ENC-TS-ENC ::= SEQUENCE { - patimestamp[0] KerberosTime, -- client's time - pausec[1] INTEGER OPTIONAL - } - - - - -Kohl & Neuman [Page 50] - -RFC 1510 Kerberos September 1993 - - - with patimestamp containing the client's time and pausec - containing the microseconds which may be omitted if a - client will not generate more than one request per second. - The ciphertext (padata-value) consists of the PA-ENC-TS-ENC - sequence, encrypted using the client's secret key. - - The padata field can also contain information needed to - help the KDC or the client select the key needed for - generating or decrypting the response. This form of the - padata is useful for supporting the use of certain - "smartcards" with Kerberos. The details of such extensions - are beyond the scope of this specification. See [10] for - additional uses of this field. - - padata-type The padata-type element of the padata field indicates the - way that the padata-value element is to be interpreted. - Negative values of padata-type are reserved for - unregistered use; non-negative values are used for a - registered interpretation of the element type. - - req-body This field is a placeholder delimiting the extent of the - remaining fields. If a checksum is to be calculated over - the request, it is calculated over an encoding of the KDC- - REQ-BODY sequence which is enclosed within the req-body - field. - - kdc-options This field appears in the KRB_AS_REQ and KRB_TGS_REQ - requests to the KDC and indicates the flags that the client - wants set on the tickets as well as other information that - is to modify the behavior of the KDC. Where appropriate, - the name of an option may be the same as the flag that is - set by that option. Although in most case, the bit in the - options field will be the same as that in the flags field, - this is not guaranteed, so it is not acceptable to simply - copy the options field to the flags field. There are - various checks that must be made before honoring an option - anyway. - - The kdc_options field is a bit-field, where the selected - options are indicated by the bit being set (1), and the - unselected options and reserved fields being reset (0). - The encoding of the bits is specified in section 5.2. The - options are described in more detail above in section 2. - The meanings of the options are: - - - - - - - -Kohl & Neuman [Page 51] - -RFC 1510 Kerberos September 1993 - - - Bit(s) Name Description - - 0 RESERVED Reserved for future expansion of this - field. - - 1 FORWARDABLE The FORWARDABLE option indicates that - the ticket to be issued is to have its - forwardable flag set. It may only be - set on the initial request, or in a - subsequent request if the ticket- - granting ticket on which it is based - is also forwardable. - - 2 FORWARDED The FORWARDED option is only specified - in a request to the ticket-granting - server and will only be honored if the - ticket-granting ticket in the request - has its FORWARDABLE bit set. This - option indicates that this is a - request for forwarding. The - address(es) of the host from which the - resulting ticket is to be valid are - included in the addresses field of the - request. - - - 3 PROXIABLE The PROXIABLE option indicates that - the ticket to be issued is to have its - proxiable flag set. It may only be set - on the initial request, or in a - subsequent request if the ticket- - granting ticket on which it is based - is also proxiable. - - 4 PROXY The PROXY option indicates that this - is a request for a proxy. This option - will only be honored if the ticket- - granting ticket in the request has its - PROXIABLE bit set. The address(es) of - the host from which the resulting - ticket is to be valid are included in - the addresses field of the request. - - 5 ALLOW-POSTDATE The ALLOW-POSTDATE option indicates - that the ticket to be issued is to - have its MAY-POSTDATE flag set. It - may only be set on the initial - request, or in a subsequent request if - - - -Kohl & Neuman [Page 52] - -RFC 1510 Kerberos September 1993 - - - the ticket-granting ticket on which it - is based also has its MAY-POSTDATE - flag set. - - 6 POSTDATED The POSTDATED option indicates that - this is a request for a postdated - ticket. This option will only be - honored if the ticket-granting ticket - on which it is based has its MAY- - POSTDATE flag set. The resulting - ticket will also have its INVALID flag - set, and that flag may be reset by a - subsequent request to the KDC after - the starttime in the ticket has been - reached. - - 7 UNUSED This option is presently unused. - - 8 RENEWABLE The RENEWABLE option indicates that - the ticket to be issued is to have its - RENEWABLE flag set. It may only be - set on the initial request, or when - the ticket-granting ticket on which - the request is based is also - renewable. If this option is - requested, then the rtime field in the - request contains the desired absolute - expiration time for the ticket. - - 9-26 RESERVED Reserved for future use. - - 27 RENEWABLE-OK The RENEWABLE-OK option indicates that - a renewable ticket will be acceptable - if a ticket with the requested life - cannot otherwise be provided. If a - ticket with the requested life cannot - be provided, then a renewable ticket - may be issued with a renew-till equal - to the the requested endtime. The - value of the renew-till field may - still be limited by local limits, or - limits selected by the individual - principal or server. - - 28 ENC-TKT-IN-SKEY This option is used only by the - ticket-granting service. The ENC- - TKT-IN-SKEY option indicates that the - ticket for the end server is to be - - - -Kohl & Neuman [Page 53] - -RFC 1510 Kerberos September 1993 - - - encrypted in the session key from the - additional ticket-granting ticket - provided. - - 29 RESERVED Reserved for future use. - - 30 RENEW This option is used only by the - ticket-granting service. The RENEW - option indicates that the present - request is for a renewal. The ticket - provided is encrypted in the secret - key for the server on which it is - valid. This option will only be - honored if the ticket to be renewed - has its RENEWABLE flag set and if the - time in its renew till field has not - passed. The ticket to be renewed is - passed in the padata field as part of - the authentication header. - - 31 VALIDATE This option is used only by the - ticket-granting service. The VALIDATE - option indicates that the request is - to validate a postdated ticket. It - will only be honored if the ticket - presented is postdated, presently has - its INVALID flag set, and would be - otherwise usable at this time. A - ticket cannot be validated before its - starttime. The ticket presented for - validation is encrypted in the key of - the server for which it is valid and - is passed in the padata field as part - of the authentication header. - - cname and sname These fields are the same as those described for the - ticket in section 5.3.1. sname may only be absent when the - ENC-TKT-IN-SKEY option is specified. If absent, the name - of the server is taken from the name of the client in the - ticket passed as additional-tickets. - - enc-authorization-data The enc-authorization-data, if present (and it - can only be present in the TGS_REQ form), is an encoding of - the desired authorization-data encrypted under the sub- - session key if present in the Authenticator, or - alternatively from the session key in the ticket-granting - ticket, both from the padata field in the KRB_AP_REQ. - - - - -Kohl & Neuman [Page 54] - -RFC 1510 Kerberos September 1993 - - - realm This field specifies the realm part of the server's - principal identifier. In the AS exchange, this is also the - realm part of the client's principal identifier. - - from This field is included in the KRB_AS_REQ and KRB_TGS_REQ - ticket requests when the requested ticket is to be - postdated. It specifies the desired start time for the - requested ticket. - - till This field contains the expiration date requested by the - client in a ticket request. - - rtime This field is the requested renew-till time sent from a - client to the KDC in a ticket request. It is optional. - - nonce This field is part of the KDC request and response. It it - intended to hold a random number generated by the client. - If the same number is included in the encrypted response - from the KDC, it provides evidence that the response is - fresh and has not been replayed by an attacker. Nonces - must never be re-used. Ideally, it should be gen erated - randomly, but if the correct time is known, it may suffice - (Note, however, that if the time is used as the nonce, one - must make sure that the workstation time is monotonically - increasing. If the time is ever reset backwards, there is - a small, but finite, probability that a nonce will be - reused.). - - etype This field specifies the desired encryption algorithm to be - used in the response. - - addresses This field is included in the initial request for tickets, - and optionally included in requests for additional tickets - from the ticket-granting server. It specifies the - addresses from which the requested ticket is to be valid. - Normally it includes the addresses for the client's host. - If a proxy is requested, this field will contain other - addresses. The contents of this field are usually copied - by the KDC into the caddr field of the resulting ticket. - - additional-tickets Additional tickets may be optionally included in a - request to the ticket-granting server. If the ENC-TKT-IN- - SKEY option has been specified, then the session key from - the additional ticket will be used in place of the server's - key to encrypt the new ticket. If more than one option - which requires additional tickets has been specified, then - the additional tickets are used in the order specified by - the ordering of the options bits (see kdc-options, above). - - - -Kohl & Neuman [Page 55] - -RFC 1510 Kerberos September 1993 - - - The application code will be either ten (10) or twelve (12) depending - on whether the request is for an initial ticket (AS-REQ) or for an - additional ticket (TGS-REQ). - - The optional fields (addresses, authorization-data and additional- - tickets) are only included if necessary to perform the operation - specified in the kdc-options field. - - It should be noted that in KRB_TGS_REQ, the protocol version number - appears twice and two different message types appear: the KRB_TGS_REQ - message contains these fields as does the authentication header - (KRB_AP_REQ) that is passed in the padata field. - -5.4.2. KRB_KDC_REP definition - - The KRB_KDC_REP message format is used for the reply from the KDC for - either an initial (AS) request or a subsequent (TGS) request. There - is no message type for KRB_KDC_REP. Instead, the type will be either - KRB_AS_REP or KRB_TGS_REP. The key used to encrypt the ciphertext - part of the reply depends on the message type. For KRB_AS_REP, the - ciphertext is encrypted in the client's secret key, and the client's - key version number is included in the key version number for the - encrypted data. For KRB_TGS_REP, the ciphertext is encrypted in the - sub-session key from the Authenticator, or if absent, the session key - from the ticket-granting ticket used in the request. In that case, - no version number will be present in the EncryptedData sequence. - - The KRB_KDC_REP message contains the following fields: - - AS-REP ::= [APPLICATION 11] KDC-REP - TGS-REP ::= [APPLICATION 13] KDC-REP - - KDC-REP ::= SEQUENCE { - pvno[0] INTEGER, - msg-type[1] INTEGER, - padata[2] SEQUENCE OF PA-DATA OPTIONAL, - crealm[3] Realm, - cname[4] PrincipalName, - ticket[5] Ticket, - enc-part[6] EncryptedData - } - - EncASRepPart ::= [APPLICATION 25[25]] EncKDCRepPart - EncTGSRepPart ::= [APPLICATION 26] EncKDCRepPart - - EncKDCRepPart ::= SEQUENCE { - key[0] EncryptionKey, - last-req[1] LastReq, - - - -Kohl & Neuman [Page 56] - -RFC 1510 Kerberos September 1993 - - - nonce[2] INTEGER, - key-expiration[3] KerberosTime OPTIONAL, - flags[4] TicketFlags, - authtime[5] KerberosTime, - starttime[6] KerberosTime OPTIONAL, - endtime[7] KerberosTime, - renew-till[8] KerberosTime OPTIONAL, - srealm[9] Realm, - sname[10] PrincipalName, - caddr[11] HostAddresses OPTIONAL - } - - NOTE: In EncASRepPart, the application code in the encrypted - part of a message provides an additional check that - the message was decrypted properly. - - pvno and msg-type These fields are described above in section 5.4.1. - msg-type is either KRB_AS_REP or KRB_TGS_REP. - - padata This field is described in detail in section 5.4.1. One - possible use for this field is to encode an alternate - "mix-in" string to be used with a string-to-key algorithm - (such as is described in section 6.3.2). This ability is - useful to ease transitions if a realm name needs to change - (e.g., when a company is acquired); in such a case all - existing password-derived entries in the KDC database would - be flagged as needing a special mix-in string until the - next password change. - - crealm, cname, srealm and sname These fields are the same as those - described for the ticket in section 5.3.1. - - ticket The newly-issued ticket, from section 5.3.1. - - enc-part This field is a place holder for the ciphertext and related - information that forms the encrypted part of a message. - The description of the encrypted part of the message - follows each appearance of this field. The encrypted part - is encoded as described in section 6.1. - - key This field is the same as described for the ticket in - section 5.3.1. - - last-req This field is returned by the KDC and specifies the time(s) - of the last request by a principal. Depending on what - information is available, this might be the last time that - a request for a ticket-granting ticket was made, or the - last time that a request based on a ticket-granting ticket - - - -Kohl & Neuman [Page 57] - -RFC 1510 Kerberos September 1993 - - - was successful. It also might cover all servers for a - realm, or just the particular server. Some implementations - may display this information to the user to aid in - discovering unauthorized use of one's identity. It is - similar in spirit to the last login time displayed when - logging into timesharing systems. - - nonce This field is described above in section 5.4.1. - - key-expiration The key-expiration field is part of the response from - the KDC and specifies the time that the client's secret key - is due to expire. The expiration might be the result of - password aging or an account expiration. This field will - usually be left out of the TGS reply since the response to - the TGS request is encrypted in a session key and no client - information need be retrieved from the KDC database. It is - up to the application client (usually the login program) to - take appropriate action (such as notifying the user) if the - expira tion time is imminent. - - flags, authtime, starttime, endtime, renew-till and caddr These - fields are duplicates of those found in the encrypted - portion of the attached ticket (see section 5.3.1), - provided so the client may verify they match the intended - request and to assist in proper ticket caching. If the - message is of type KRB_TGS_REP, the caddr field will only - be filled in if the request was for a proxy or forwarded - ticket, or if the user is substituting a subset of the - addresses from the ticket granting ticket. If the client- - requested addresses are not present or not used, then the - addresses contained in the ticket will be the same as those - included in the ticket-granting ticket. - -5.5. Client/Server (CS) message specifications - - This section specifies the format of the messages used for the - authentication of the client to the application server. - -5.5.1. KRB_AP_REQ definition - - The KRB_AP_REQ message contains the Kerberos protocol version number, - the message type KRB_AP_REQ, an options field to indicate any options - in use, and the ticket and authenticator themselves. The KRB_AP_REQ - message is often referred to as the "authentication header". - - AP-REQ ::= [APPLICATION 14] SEQUENCE { - pvno[0] INTEGER, - msg-type[1] INTEGER, - - - -Kohl & Neuman [Page 58] - -RFC 1510 Kerberos September 1993 - - - ap-options[2] APOptions, - ticket[3] Ticket, - authenticator[4] EncryptedData - } - - APOptions ::= BIT STRING { - reserved(0), - use-session-key(1), - mutual-required(2) - } - - pvno and msg-type These fields are described above in section 5.4.1. - msg-type is KRB_AP_REQ. - - ap-options This field appears in the application request (KRB_AP_REQ) - and affects the way the request is processed. It is a - bit-field, where the selected options are indicated by the - bit being set (1), and the unselected options and reserved - fields being reset (0). The encoding of the bits is - specified in section 5.2. The meanings of the options are: - - Bit(s) Name Description - - 0 RESERVED Reserved for future expansion of - this field. - - 1 USE-SESSION-KEYThe USE-SESSION-KEY option indicates - that the ticket the client is - presenting to a server is encrypted in - the session key from the server's - ticket-granting ticket. When this - option is not specified, the ticket is - encrypted in the server's secret key. - - 2 MUTUAL-REQUIREDThe MUTUAL-REQUIRED option tells the - server that the client requires mutual - authentication, and that it must - respond with a KRB_AP_REP message. - - 3-31 RESERVED Reserved for future use. - - ticket This field is a ticket authenticating the client to the - server. - - authenticator This contains the authenticator, which includes the - client's choice of a subkey. Its encoding is described in - section 5.3.2. - - - - -Kohl & Neuman [Page 59] - -RFC 1510 Kerberos September 1993 - - -5.5.2. KRB_AP_REP definition - - The KRB_AP_REP message contains the Kerberos protocol version number, - the message type, and an encrypted timestamp. The message is sent in - in response to an application request (KRB_AP_REQ) where the mutual - authentication option has been selected in the ap-options field. - - AP-REP ::= [APPLICATION 15] SEQUENCE { - pvno[0] INTEGER, - msg-type[1] INTEGER, - enc-part[2] EncryptedData - } - - EncAPRepPart ::= [APPLICATION 27] SEQUENCE { - ctime[0] KerberosTime, - cusec[1] INTEGER, - subkey[2] EncryptionKey OPTIONAL, - seq-number[3] INTEGER OPTIONAL - } - - NOTE: in EncAPRepPart, the application code in the encrypted part of - a message provides an additional check that the message was decrypted - properly. - - The encoded EncAPRepPart is encrypted in the shared session key of - the ticket. The optional subkey field can be used in an - application-arranged negotiation to choose a per association session - key. - - pvno and msg-type These fields are described above in section 5.4.1. - msg-type is KRB_AP_REP. - - enc-part This field is described above in section 5.4.2. - - ctime This field contains the current time on the client's host. - - cusec This field contains the microsecond part of the client's - timestamp. - - subkey This field contains an encryption key which is to be used - to protect this specific application session. See section - 3.2.6 for specifics on how this field is used to negotiate - a key. Unless an application specifies otherwise, if this - field is left out, the sub-session key from the - authenticator, or if also left out, the session key from - the ticket will be used. - - - - - -Kohl & Neuman [Page 60] - -RFC 1510 Kerberos September 1993 - - -5.5.3. Error message reply - - If an error occurs while processing the application request, the - KRB_ERROR message will be sent in response. See section 5.9.1 for - the format of the error message. The cname and crealm fields may be - left out if the server cannot determine their appropriate values from - the corresponding KRB_AP_REQ message. If the authenticator was - decipherable, the ctime and cusec fields will contain the values from - it. - -5.6. KRB_SAFE message specification - - This section specifies the format of a message that can be used by - either side (client or server) of an application to send a tamper- - proof message to its peer. It presumes that a session key has - previously been exchanged (for example, by using the - KRB_AP_REQ/KRB_AP_REP messages). - -5.6.1. KRB_SAFE definition - - The KRB_SAFE message contains user data along with a collision-proof - checksum keyed with the session key. The message fields are: - - KRB-SAFE ::= [APPLICATION 20] SEQUENCE { - pvno[0] INTEGER, - msg-type[1] INTEGER, - safe-body[2] KRB-SAFE-BODY, - cksum[3] Checksum - } - - KRB-SAFE-BODY ::= SEQUENCE { - user-data[0] OCTET STRING, - timestamp[1] KerberosTime OPTIONAL, - usec[2] INTEGER OPTIONAL, - seq-number[3] INTEGER OPTIONAL, - s-address[4] HostAddress, - r-address[5] HostAddress OPTIONAL - } - - pvno and msg-type These fields are described above in section 5.4.1. - msg-type is KRB_SAFE. - - safe-body This field is a placeholder for the body of the KRB-SAFE - message. It is to be encoded separately and then have the - checksum computed over it, for use in the cksum field. - - cksum This field contains the checksum of the application data. - Checksum details are described in section 6.4. The - - - -Kohl & Neuman [Page 61] - -RFC 1510 Kerberos September 1993 - - - checksum is computed over the encoding of the KRB-SAFE-BODY - sequence. - - user-data This field is part of the KRB_SAFE and KRB_PRIV messages - and contain the application specific data that is being - passed from the sender to the recipient. - - timestamp This field is part of the KRB_SAFE and KRB_PRIV messages. - Its contents are the current time as known by the sender of - the message. By checking the timestamp, the recipient of - the message is able to make sure that it was recently - generated, and is not a replay. - - usec This field is part of the KRB_SAFE and KRB_PRIV headers. - It contains the microsecond part of the timestamp. - - seq-number This field is described above in section 5.3.2. - - s-address This field specifies the address in use by the sender of - the message. - - r-address This field specifies the address in use by the recipient of - the message. It may be omitted for some uses (such as - broadcast protocols), but the recipient may arbitrarily - reject such messages. This field along with s-address can - be used to help detect messages which have been incorrectly - or maliciously delivered to the wrong recipient. - -5.7. KRB_PRIV message specification - - This section specifies the format of a message that can be used by - either side (client or server) of an application to securely and - privately send a message to its peer. It presumes that a session key - has previously been exchanged (for example, by using the - KRB_AP_REQ/KRB_AP_REP messages). - -5.7.1. KRB_PRIV definition - - The KRB_PRIV message contains user data encrypted in the Session Key. - The message fields are: - - KRB-PRIV ::= [APPLICATION 21] SEQUENCE { - pvno[0] INTEGER, - msg-type[1] INTEGER, - enc-part[3] EncryptedData - } - - - - - -Kohl & Neuman [Page 62] - -RFC 1510 Kerberos September 1993 - - - EncKrbPrivPart ::= [APPLICATION 28] SEQUENCE { - user-data[0] OCTET STRING, - timestamp[1] KerberosTime OPTIONAL, - usec[2] INTEGER OPTIONAL, - seq-number[3] INTEGER OPTIONAL, - s-address[4] HostAddress, -- sender's addr - r-address[5] HostAddress OPTIONAL - -- recip's addr - } - - NOTE: In EncKrbPrivPart, the application code in the encrypted part - of a message provides an additional check that the message was - decrypted properly. - - pvno and msg-type These fields are described above in section 5.4.1. - msg-type is KRB_PRIV. - - enc-part This field holds an encoding of the EncKrbPrivPart sequence - encrypted under the session key (If supported by the - encryption method in use, an initialization vector may be - passed to the encryption procedure, in order to achieve - proper cipher chaining. The initialization vector might - come from the last block of the ciphertext from the - previous KRB_PRIV message, but it is the application's - choice whether or not to use such an initialization vector. - If left out, the default initialization vector for the - encryption algorithm will be used.). This encrypted - encoding is used for the enc-part field of the KRB-PRIV - message. See section 6 for the format of the ciphertext. - - user-data, timestamp, usec, s-address and r-address These fields are - described above in section 5.6.1. - - seq-number This field is described above in section 5.3.2. - -5.8. KRB_CRED message specification - - This section specifies the format of a message that can be used to - send Kerberos credentials from one principal to another. It is - presented here to encourage a common mechanism to be used by - applications when forwarding tickets or providing proxies to - subordinate servers. It presumes that a session key has already been - exchanged perhaps by using the KRB_AP_REQ/KRB_AP_REP messages. - -5.8.1. KRB_CRED definition - - The KRB_CRED message contains a sequence of tickets to be sent and - information needed to use the tickets, including the session key from - - - -Kohl & Neuman [Page 63] - -RFC 1510 Kerberos September 1993 - - - each. The information needed to use the tickets is encryped under an - encryption key previously exchanged. The message fields are: - - KRB-CRED ::= [APPLICATION 22] SEQUENCE { - pvno[0] INTEGER, - msg-type[1] INTEGER, -- KRB_CRED - tickets[2] SEQUENCE OF Ticket, - enc-part[3] EncryptedData - } - - EncKrbCredPart ::= [APPLICATION 29] SEQUENCE { - ticket-info[0] SEQUENCE OF KrbCredInfo, - nonce[1] INTEGER OPTIONAL, - timestamp[2] KerberosTime OPTIONAL, - usec[3] INTEGER OPTIONAL, - s-address[4] HostAddress OPTIONAL, - r-address[5] HostAddress OPTIONAL - } - - KrbCredInfo ::= SEQUENCE { - key[0] EncryptionKey, - prealm[1] Realm OPTIONAL, - pname[2] PrincipalName OPTIONAL, - flags[3] TicketFlags OPTIONAL, - authtime[4] KerberosTime OPTIONAL, - starttime[5] KerberosTime OPTIONAL, - endtime[6] KerberosTime OPTIONAL - renew-till[7] KerberosTime OPTIONAL, - srealm[8] Realm OPTIONAL, - sname[9] PrincipalName OPTIONAL, - caddr[10] HostAddresses OPTIONAL - } - - - pvno and msg-type These fields are described above in section 5.4.1. - msg-type is KRB_CRED. - - tickets - These are the tickets obtained from the KDC specifically - for use by the intended recipient. Successive tickets are - paired with the corresponding KrbCredInfo sequence from the - enc-part of the KRB-CRED message. - - enc-part This field holds an encoding of the EncKrbCredPart sequence - encrypted under the session key shared between the sender - and the intended recipient. This encrypted encoding is - used for the enc-part field of the KRB-CRED message. See - section 6 for the format of the ciphertext. - - - -Kohl & Neuman [Page 64] - -RFC 1510 Kerberos September 1993 - - - nonce If practical, an application may require the inclusion of a - nonce generated by the recipient of the message. If the - same value is included as the nonce in the message, it - provides evidence that the message is fresh and has not - been replayed by an attacker. A nonce must never be re- - used; it should be generated randomly by the recipient of - the message and provided to the sender of the mes sage in - an application specific manner. - - timestamp and usec These fields specify the time that the KRB-CRED - message was generated. The time is used to provide - assurance that the message is fresh. - - s-address and r-address These fields are described above in section - 5.6.1. They are used optionally to provide additional - assurance of the integrity of the KRB-CRED message. - - key This field exists in the corresponding ticket passed by the - KRB-CRED message and is used to pass the session key from - the sender to the intended recipient. The field's encoding - is described in section 6.2. - - The following fields are optional. If present, they can be - associated with the credentials in the remote ticket file. If left - out, then it is assumed that the recipient of the credentials already - knows their value. - - prealm and pname The name and realm of the delegated principal - identity. - - flags, authtime, starttime, endtime, renew-till, srealm, sname, - and caddr These fields contain the values of the - corresponding fields from the ticket found in the ticket - field. Descriptions of the fields are identical to the - descriptions in the KDC-REP message. - -5.9. Error message specification - - This section specifies the format for the KRB_ERROR message. The - fields included in the message are intended to return as much - information as possible about an error. It is not expected that all - the information required by the fields will be available for all - types of errors. If the appropriate information is not available - when the message is composed, the corresponding field will be left - out of the message. - - Note that since the KRB_ERROR message is not protected by any - encryption, it is quite possible for an intruder to synthesize or - - - -Kohl & Neuman [Page 65] - -RFC 1510 Kerberos September 1993 - - - modify such a message. In particular, this means that the client - should not use any fields in this message for security-critical - purposes, such as setting a system clock or generating a fresh - authenticator. The message can be useful, however, for advising a - user on the reason for some failure. - -5.9.1. KRB_ERROR definition - - The KRB_ERROR message consists of the following fields: - - KRB-ERROR ::= [APPLICATION 30] SEQUENCE { - pvno[0] INTEGER, - msg-type[1] INTEGER, - ctime[2] KerberosTime OPTIONAL, - cusec[3] INTEGER OPTIONAL, - stime[4] KerberosTime, - susec[5] INTEGER, - error-code[6] INTEGER, - crealm[7] Realm OPTIONAL, - cname[8] PrincipalName OPTIONAL, - realm[9] Realm, -- Correct realm - sname[10] PrincipalName, -- Correct name - e-text[11] GeneralString OPTIONAL, - e-data[12] OCTET STRING OPTIONAL - } - - pvno and msg-type These fields are described above in section 5.4.1. - msg-type is KRB_ERROR. - - ctime This field is described above in section 5.4.1. - - cusec This field is described above in section 5.5.2. - - stime This field contains the current time on the server. It is - of type KerberosTime. - - susec This field contains the microsecond part of the server's - timestamp. Its value ranges from 0 to 999. It appears - along with stime. The two fields are used in conjunction to - specify a reasonably accurate timestamp. - - error-code This field contains the error code returned by Kerberos or - the server when a request fails. To interpret the value of - this field see the list of error codes in section 8. - Implementations are encouraged to provide for national - language support in the display of error messages. - - crealm, cname, srealm and sname These fields are described above in - - - -Kohl & Neuman [Page 66] - -RFC 1510 Kerberos September 1993 - - - section 5.3.1. - - e-text This field contains additional text to help explain the - error code associated with the failed request (for example, - it might include a principal name which was unknown). - - e-data This field contains additional data about the error for use - by the application to help it recover from or handle the - error. If the errorcode is KDC_ERR_PREAUTH_REQUIRED, then - the e-data field will contain an encoding of a sequence of - padata fields, each corresponding to an acceptable pre- - authentication method and optionally containing data for - the method: - - METHOD-DATA ::= SEQUENCE of PA-DATA - - If the error-code is KRB_AP_ERR_METHOD, then the e-data field will - contain an encoding of the following sequence: - - METHOD-DATA ::= SEQUENCE { - method-type[0] INTEGER, - method-data[1] OCTET STRING OPTIONAL - } - - method-type will indicate the required alternate method; method-data - will contain any required additional information. - -6. Encryption and Checksum Specifications - - The Kerberos protocols described in this document are designed to use - stream encryption ciphers, which can be simulated using commonly - available block encryption ciphers, such as the Data Encryption - Standard [11], in conjunction with block chaining and checksum - methods [12]. Encryption is used to prove the identities of the - network entities participating in message exchanges. The Key - Distribution Center for each realm is trusted by all principals - registered in that realm to store a secret key in confidence. Proof - of knowledge of this secret key is used to verify the authenticity of - a principal. - - The KDC uses the principal's secret key (in the AS exchange) or a - shared session key (in the TGS exchange) to encrypt responses to - ticket requests; the ability to obtain the secret key or session key - implies the knowledge of the appropriate keys and the identity of the - KDC. The ability of a principal to decrypt the KDC response and - present a Ticket and a properly formed Authenticator (generated with - the session key from the KDC response) to a service verifies the - identity of the principal; likewise the ability of the service to - - - -Kohl & Neuman [Page 67] - -RFC 1510 Kerberos September 1993 - - - extract the session key from the Ticket and prove its knowledge - thereof in a response verifies the identity of the service. - - The Kerberos protocols generally assume that the encryption used is - secure from cryptanalysis; however, in some cases, the order of - fields in the encrypted portions of messages are arranged to minimize - the effects of poorly chosen keys. It is still important to choose - good keys. If keys are derived from user-typed passwords, those - passwords need to be well chosen to make brute force attacks more - difficult. Poorly chosen keys still make easy targets for intruders. - - The following sections specify the encryption and checksum mechanisms - currently defined for Kerberos. The encodings, chaining, and padding - requirements for each are described. For encryption methods, it is - often desirable to place random information (often referred to as a - confounder) at the start of the message. The requirements for a - confounder are specified with each encryption mechanism. - - Some encryption systems use a block-chaining method to improve the - the security characteristics of the ciphertext. However, these - chaining methods often don't provide an integrity check upon - decryption. Such systems (such as DES in CBC mode) must be augmented - with a checksum of the plaintext which can be verified at decryption - and used to detect any tampering or damage. Such checksums should be - good at detecting burst errors in the input. If any damage is - detected, the decryption routine is expected to return an error - indicating the failure of an integrity check. Each encryption type is - expected to provide and verify an appropriate checksum. The - specification of each encryption method sets out its checksum - requirements. - - Finally, where a key is to be derived from a user's password, an - algorithm for converting the password to a key of the appropriate - type is included. It is desirable for the string to key function to - be one-way, and for the mapping to be different in different realms. - This is important because users who are registered in more than one - realm will often use the same password in each, and it is desirable - that an attacker compromising the Kerberos server in one realm not - obtain or derive the user's key in another. - - For a discussion of the integrity characteristics of the candidate - encryption and checksum methods considered for Kerberos, the the - reader is referred to [13]. - -6.1. Encryption Specifications - - The following ASN.1 definition describes all encrypted messages. The - enc-part field which appears in the unencrypted part of messages in - - - -Kohl & Neuman [Page 68] - -RFC 1510 Kerberos September 1993 - - - section 5 is a sequence consisting of an encryption type, an optional - key version number, and the ciphertext. - - EncryptedData ::= SEQUENCE { - etype[0] INTEGER, -- EncryptionType - kvno[1] INTEGER OPTIONAL, - cipher[2] OCTET STRING -- ciphertext - } - - etype This field identifies which encryption algorithm was used - to encipher the cipher. Detailed specifications for - selected encryption types appear later in this section. - - kvno This field contains the version number of the key under - which data is encrypted. It is only present in messages - encrypted under long lasting keys, such as principals' - secret keys. - - cipher This field contains the enciphered text, encoded as an - OCTET STRING. - - The cipher field is generated by applying the specified encryption - algorithm to data composed of the message and algorithm-specific - inputs. Encryption mechanisms defined for use with Kerberos must - take sufficient measures to guarantee the integrity of the plaintext, - and we recommend they also take measures to protect against - precomputed dictionary attacks. If the encryption algorithm is not - itself capable of doing so, the protections can often be enhanced by - adding a checksum and a confounder. - - The suggested format for the data to be encrypted includes a - confounder, a checksum, the encoded plaintext, and any necessary - padding. The msg-seq field contains the part of the protocol message - described in section 5 which is to be encrypted. The confounder, - checksum, and padding are all untagged and untyped, and their length - is exactly sufficient to hold the appropriate item. The type and - length is implicit and specified by the particular encryption type - being used (etype). The format for the data to be encrypted is - described in the following diagram: - - +-----------+----------+-------------+-----+ - |confounder | check | msg-seq | pad | - +-----------+----------+-------------+-----+ - - The format cannot be described in ASN.1, but for those who prefer an - ASN.1-like notation: - - - - - -Kohl & Neuman [Page 69] - -RFC 1510 Kerberos September 1993 - - -CipherText ::= ENCRYPTED SEQUENCE { - confounder[0] UNTAGGED OCTET STRING(conf_length) OPTIONAL, - check[1] UNTAGGED OCTET STRING(checksum_length) OPTIONAL, - msg-seq[2] MsgSequence, - pad UNTAGGED OCTET STRING(pad_length) OPTIONAL -} - - In the above specification, UNTAGGED OCTET STRING(length) is the - notation for an octet string with its tag and length removed. It is - not a valid ASN.1 type. The tag bits and length must be removed from - the confounder since the purpose of the confounder is so that the - message starts with random data, but the tag and its length are - fixed. For other fields, the length and tag would be redundant if - they were included because they are specified by the encryption type. - - One generates a random confounder of the appropriate length, placing - it in confounder; zeroes out check; calculates the appropriate - checksum over confounder, check, and msg-seq, placing the result in - check; adds the necessary padding; then encrypts using the specified - encryption type and the appropriate key. - - Unless otherwise specified, a definition of an encryption algorithm - that specifies a checksum, a length for the confounder field, or an - octet boundary for padding uses this ciphertext format (The ordering - of the fields in the CipherText is important. Additionally, messages - encoded in this format must include a length as part of the msg-seq - field. This allows the recipient to verify that the message has not - been truncated. Without a length, an attacker could use a chosen - plaintext attack to generate a message which could be truncated, - while leaving the checksum intact. Note that if the msg-seq is an - encoding of an ASN.1 SEQUENCE or OCTET STRING, then the length is - part of that encoding.). Those fields which are not specified will be - omitted. - - In the interest of allowing all implementations using a particular - encryption type to communicate with all others using that type, the - specification of an encryption type defines any checksum that is - needed as part of the encryption process. If an alternative checksum - is to be used, a new encryption type must be defined. - - Some cryptosystems require additional information beyond the key and - the data to be encrypted. For example, DES, when used in cipher- - block-chaining mode, requires an initialization vector. If required, - the description for each encryption type must specify the source of - such additional information. - - - - - - -Kohl & Neuman [Page 70] - -RFC 1510 Kerberos September 1993 - - -6.2. Encryption Keys - - The sequence below shows the encoding of an encryption key: - - EncryptionKey ::= SEQUENCE { - keytype[0] INTEGER, - keyvalue[1] OCTET STRING - } - - keytype This field specifies the type of encryption key that - follows in the keyvalue field. It will almost always - correspond to the encryption algorithm used to generate the - EncryptedData, though more than one algorithm may use the - same type of key (the mapping is many to one). This might - happen, for example, if the encryption algorithm uses an - alternate checksum algorithm for an integrity check, or a - different chaining mechanism. - - keyvalue This field contains the key itself, encoded as an octet - string. - - All negative values for the encryption key type are reserved for - local use. All non-negative values are reserved for officially - assigned type fields and interpretations. - -6.3. Encryption Systems - -6.3.1. The NULL Encryption System (null) - - If no encryption is in use, the encryption system is said to be the - NULL encryption system. In the NULL encryption system there is no - checksum, confounder or padding. The ciphertext is simply the - plaintext. The NULL Key is used by the null encryption system and is - zero octets in length, with keytype zero (0). - -6.3.2. DES in CBC mode with a CRC-32 checksum (des-cbc-crc) - - The des-cbc-crc encryption mode encrypts information under the Data - Encryption Standard [11] using the cipher block chaining mode [12]. - A CRC-32 checksum (described in ISO 3309 [14]) is applied to the - confounder and message sequence (msg-seq) and placed in the cksum - field. DES blocks are 8 bytes. As a result, the data to be - encrypted (the concatenation of confounder, checksum, and message) - must be padded to an 8 byte boundary before encryption. The details - of the encryption of this data are identical to those for the des- - cbc-md5 encryption mode. - - Note that, since the CRC-32 checksum is not collisionproof, an - - - -Kohl & Neuman [Page 71] - -RFC 1510 Kerberos September 1993 - - - attacker could use a probabilistic chosenplaintext attack to generate - a valid message even if a confounder is used [13]. The use of - collision-proof checksums is recommended for environments where such - attacks represent a significant threat. The use of the CRC-32 as the - checksum for ticket or authenticator is no longer mandated as an - interoperability requirement for Kerberos Version 5 Specification 1 - (See section 9.1 for specific details). - -6.3.3. DES in CBC mode with an MD4 checksum (des-cbc-md4) - - The des-cbc-md4 encryption mode encrypts information under the Data - Encryption Standard [11] using the cipher block chaining mode [12]. - An MD4 checksum (described in [15]) is applied to the confounder and - message sequence (msg-seq) and placed in the cksum field. DES blocks - are 8 bytes. As a result, the data to be encrypted (the - concatenation of confounder, checksum, and message) must be padded to - an 8 byte boundary before encryption. The details of the encryption - of this data are identical to those for the descbc-md5 encryption - mode. - -6.3.4. DES in CBC mode with an MD5 checksum (des-cbc-md5) - - The des-cbc-md5 encryption mode encrypts information under the Data - Encryption Standard [11] using the cipher block chaining mode [12]. - An MD5 checksum (described in [16]) is applied to the confounder and - message sequence (msg-seq) and placed in the cksum field. DES blocks - are 8 bytes. As a result, the data to be encrypted (the - concatenation of confounder, checksum, and message) must be padded to - an 8 byte boundary before encryption. - - Plaintext and DES ciphtertext are encoded as 8-octet blocks which are - concatenated to make the 64-bit inputs for the DES algorithms. The - first octet supplies the 8 most significant bits (with the octet's - MSbit used as the DES input block's MSbit, etc.), the second octet - the next 8 bits, ..., and the eighth octet supplies the 8 least - significant bits. - - Encryption under DES using cipher block chaining requires an - additional input in the form of an initialization vector. Unless - otherwise specified, zero should be used as the initialization - vector. Kerberos' use of DES requires an 8-octet confounder. - - The DES specifications identify some "weak" and "semiweak" keys; - those keys shall not be used for encrypting messages for use in - Kerberos. Additionally, because of the way that keys are derived for - the encryption of checksums, keys shall not be used that yield "weak" - or "semi-weak" keys when eXclusive-ORed with the constant - F0F0F0F0F0F0F0F0. - - - -Kohl & Neuman [Page 72] - -RFC 1510 Kerberos September 1993 - - - A DES key is 8 octets of data, with keytype one (1). This consists - of 56 bits of key, and 8 parity bits (one per octet). The key is - encoded as a series of 8 octets written in MSB-first order. The bits - within the key are also encoded in MSB order. For example, if the - encryption key is: - (B1,B2,...,B7,P1,B8,...,B14,P2,B15,...,B49,P7,B50,...,B56,P8) where - B1,B2,...,B56 are the key bits in MSB order, and P1,P2,...,P8 are the - parity bits, the first octet of the key would be B1,B2,...,B7,P1 - (with B1 as the MSbit). [See the FIPS 81 introduction for - reference.] - - To generate a DES key from a text string (password), the text string - normally must have the realm and each component of the principal's - name appended(In some cases, it may be necessary to use a different - "mix-in" string for compatibility reasons; see the discussion of - padata in section 5.4.2.), then padded with ASCII nulls to an 8 byte - boundary. This string is then fan-folded and eXclusive-ORed with - itself to form an 8 byte DES key. The parity is corrected on the - key, and it is used to generate a DES CBC checksum on the initial - string (with the realm and name appended). Next, parity is corrected - on the CBC checksum. If the result matches a "weak" or "semiweak" - key as described in the DES specification, it is eXclusive-ORed with - the constant 00000000000000F0. Finally, the result is returned as - the key. Pseudocode follows: - - string_to_key(string,realm,name) { - odd = 1; - s = string + realm; - for(each component in name) { - s = s + component; - } - tempkey = NULL; - pad(s); /* with nulls to 8 byte boundary */ - for(8byteblock in s) { - if(odd == 0) { - odd = 1; - reverse(8byteblock) - } - else odd = 0; - tempkey = tempkey XOR 8byteblock; - } - fixparity(tempkey); - key = DES-CBC-check(s,tempkey); - fixparity(key); - if(is_weak_key_key(key)) - key = key XOR 0xF0; - return(key); - } - - - -Kohl & Neuman [Page 73] - -RFC 1510 Kerberos September 1993 - - -6.4. Checksums - - The following is the ASN.1 definition used for a checksum: - - Checksum ::= SEQUENCE { - cksumtype[0] INTEGER, - checksum[1] OCTET STRING - } - - cksumtype This field indicates the algorithm used to generate the - accompanying checksum. - - checksum This field contains the checksum itself, encoded - as an octet string. - - Detailed specification of selected checksum types appear later in - this section. Negative values for the checksum type are reserved for - local use. All non-negative values are reserved for officially - assigned type fields and interpretations. - - Checksums used by Kerberos can be classified by two properties: - whether they are collision-proof, and whether they are keyed. It is - infeasible to find two plaintexts which generate the same checksum - value for a collision-proof checksum. A key is required to perturb - or initialize the algorithm in a keyed checksum. To prevent - message-stream modification by an active attacker, unkeyed checksums - should only be used when the checksum and message will be - subsequently encrypted (e.g., the checksums defined as part of the - encryption algorithms covered earlier in this section). Collision- - proof checksums can be made tamper-proof as well if the checksum - value is encrypted before inclusion in a message. In such cases, the - composition of the checksum and the encryption algorithm must be - considered a separate checksum algorithm (e.g., RSA-MD5 encrypted - using DES is a new checksum algorithm of type RSA-MD5-DES). For most - keyed checksums, as well as for the encrypted forms of collisionproof - checksums, Kerberos prepends a confounder before the checksum is - calculated. - -6.4.1. The CRC-32 Checksum (crc32) - - The CRC-32 checksum calculates a checksum based on a cyclic - redundancy check as described in ISO 3309 [14]. The resulting - checksum is four (4) octets in length. The CRC-32 is neither keyed - nor collision-proof. The use of this checksum is not recommended. - An attacker using a probabilistic chosen-plaintext attack as - described in [13] might be able to generate an alternative message - that satisfies the checksum. The use of collision-proof checksums is - recommended for environments where such attacks represent a - - - -Kohl & Neuman [Page 74] - -RFC 1510 Kerberos September 1993 - - - significant threat. - -6.4.2. The RSA MD4 Checksum (rsa-md4) - - The RSA-MD4 checksum calculates a checksum using the RSA MD4 - algorithm [15]. The algorithm takes as input an input message of - arbitrary length and produces as output a 128-bit (16 octet) - checksum. RSA-MD4 is believed to be collision-proof. - -6.4.3. RSA MD4 Cryptographic Checksum Using DES (rsa-md4des) - - The RSA-MD4-DES checksum calculates a keyed collisionproof checksum - by prepending an 8 octet confounder before the text, applying the RSA - MD4 checksum algorithm, and encrypting the confounder and the - checksum using DES in cipher-block-chaining (CBC) mode using a - variant of the key, where the variant is computed by eXclusive-ORing - the key with the constant F0F0F0F0F0F0F0F0 (A variant of the key is - used to limit the use of a key to a particular function, separating - the functions of generating a checksum from other encryption - performed using the session key. The constant F0F0F0F0F0F0F0F0 was - chosen because it maintains key parity. The properties of DES - precluded the use of the complement. The same constant is used for - similar purpose in the Message Integrity Check in the Privacy - Enhanced Mail standard.). The initialization vector should be zero. - The resulting checksum is 24 octets long (8 octets of which are - redundant). This checksum is tamper-proof and believed to be - collision-proof. - - The DES specifications identify some "weak keys"; those keys shall - not be used for generating RSA-MD4 checksums for use in Kerberos. - - The format for the checksum is described in the following diagram: - - +--+--+--+--+--+--+--+-- - | des-cbc(confounder - +--+--+--+--+--+--+--+-- - - +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ - rsa-md4(confounder+msg),key=var(key),iv=0) | - +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ - - The format cannot be described in ASN.1, but for those who prefer an - ASN.1-like notation: - - rsa-md4-des-checksum ::= ENCRYPTED UNTAGGED SEQUENCE { - confounder[0] UNTAGGED OCTET STRING(8), - check[1] UNTAGGED OCTET STRING(16) - } - - - -Kohl & Neuman [Page 75] - -RFC 1510 Kerberos September 1993 - - -6.4.4. The RSA MD5 Checksum (rsa-md5) - - The RSA-MD5 checksum calculates a checksum using the RSA MD5 - algorithm [16]. The algorithm takes as input an input message of - arbitrary length and produces as output a 128-bit (16 octet) - checksum. RSA-MD5 is believed to be collision-proof. - -6.4.5. RSA MD5 Cryptographic Checksum Using DES (rsa-md5des) - - The RSA-MD5-DES checksum calculates a keyed collisionproof checksum - by prepending an 8 octet confounder before the text, applying the RSA - MD5 checksum algorithm, and encrypting the confounder and the - checksum using DES in cipher-block-chaining (CBC) mode using a - variant of the key, where the variant is computed by eXclusive-ORing - the key with the constant F0F0F0F0F0F0F0F0. The initialization - vector should be zero. The resulting checksum is 24 octets long (8 - octets of which are redundant). This checksum is tamper-proof and - believed to be collision-proof. - - The DES specifications identify some "weak keys"; those keys shall - not be used for encrypting RSA-MD5 checksums for use in Kerberos. - - The format for the checksum is described in the following diagram: - - +--+--+--+--+--+--+--+-- - | des-cbc(confounder - +--+--+--+--+--+--+--+-- - - +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ - rsa-md5(confounder+msg),key=var(key),iv=0) | - +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ - - The format cannot be described in ASN.1, but for those who prefer an - ASN.1-like notation: - - rsa-md5-des-checksum ::= ENCRYPTED UNTAGGED SEQUENCE { - confounder[0] UNTAGGED OCTET STRING(8), - check[1] UNTAGGED OCTET STRING(16) - } - -6.4.6. DES cipher-block chained checksum (des-mac) - - The DES-MAC checksum is computed by prepending an 8 octet confounder - to the plaintext, performing a DES CBC-mode encryption on the result - using the key and an initialization vector of zero, taking the last - block of the ciphertext, prepending the same confounder and - encrypting the pair using DES in cipher-block-chaining (CBC) mode - using a a variant of the key, where the variant is computed by - - - -Kohl & Neuman [Page 76] - -RFC 1510 Kerberos September 1993 - - - eXclusive-ORing the key with the constant F0F0F0F0F0F0F0F0. The - initialization vector should be zero. The resulting checksum is 128 - bits (16 octets) long, 64 bits of which are redundant. This checksum - is tamper-proof and collision-proof. - - The format for the checksum is described in the following diagram: - - +--+--+--+--+--+--+--+-- - | des-cbc(confounder - +--+--+--+--+--+--+--+-- - - +-----+-----+-----+-----+-----+-----+-----+-----+ - des-mac(conf+msg,iv=0,key),key=var(key),iv=0) | - +-----+-----+-----+-----+-----+-----+-----+-----+ - - The format cannot be described in ASN.1, but for those who prefer an - ASN.1-like notation: - - des-mac-checksum ::= ENCRYPTED UNTAGGED SEQUENCE { - confounder[0] UNTAGGED OCTET STRING(8), - check[1] UNTAGGED OCTET STRING(8) - } - - The DES specifications identify some "weak" and "semiweak" keys; - those keys shall not be used for generating DES-MAC checksums for use - in Kerberos, nor shall a key be used whose veriant is "weak" or - "semi-weak". - -6.4.7. RSA MD4 Cryptographic Checksum Using DES alternative - (rsa-md4-des-k) - - The RSA-MD4-DES-K checksum calculates a keyed collision-proof - checksum by applying the RSA MD4 checksum algorithm and encrypting - the results using DES in cipherblock-chaining (CBC) mode using a DES - key as both key and initialization vector. The resulting checksum is - 16 octets long. This checksum is tamper-proof and believed to be - collision-proof. Note that this checksum type is the old method for - encoding the RSA-MD4-DES checksum and it is no longer recommended. - -6.4.8. DES cipher-block chained checksum alternative (desmac-k) - - The DES-MAC-K checksum is computed by performing a DES CBC-mode - encryption of the plaintext, and using the last block of the - ciphertext as the checksum value. It is keyed with an encryption key - and an initialization vector; any uses which do not specify an - additional initialization vector will use the key as both key and - initialization vector. The resulting checksum is 64 bits (8 octets) - long. This checksum is tamper-proof and collision-proof. Note that - - - -Kohl & Neuman [Page 77] - -RFC 1510 Kerberos September 1993 - - - this checksum type is the old method for encoding the DESMAC checksum - and it is no longer recommended. - - The DES specifications identify some "weak keys"; those keys shall - not be used for generating DES-MAC checksums for use in Kerberos. - -7. Naming Constraints - -7.1. Realm Names - - Although realm names are encoded as GeneralStrings and although a - realm can technically select any name it chooses, interoperability - across realm boundaries requires agreement on how realm names are to - be assigned, and what information they imply. - - To enforce these conventions, each realm must conform to the - conventions itself, and it must require that any realms with which - inter-realm keys are shared also conform to the conventions and - require the same from its neighbors. - - There are presently four styles of realm names: domain, X500, other, - and reserved. Examples of each style follow: - - domain: host.subdomain.domain (example) - X500: C=US/O=OSF (example) - other: NAMETYPE:rest/of.name=without-restrictions (example) - reserved: reserved, but will not conflict with above - - Domain names must look like domain names: they consist of components - separated by periods (.) and they contain neither colons (:) nor - slashes (/). - - X.500 names contain an equal (=) and cannot contain a colon (:) - before the equal. The realm names for X.500 names will be string - representations of the names with components separated by slashes. - Leading and trailing slashes will not be included. - - Names that fall into the other category must begin with a prefix that - contains no equal (=) or period (.) and the prefix must be followed - by a colon (:) and the rest of the name. All prefixes must be - assigned before they may be used. Presently none are assigned. - - The reserved category includes strings which do not fall into the - first three categories. All names in this category are reserved. It - is unlikely that names will be assigned to this category unless there - is a very strong argument for not using the "other" category. - - These rules guarantee that there will be no conflicts between the - - - -Kohl & Neuman [Page 78] - -RFC 1510 Kerberos September 1993 - - - various name styles. The following additional constraints apply to - the assignment of realm names in the domain and X.500 categories: the - name of a realm for the domain or X.500 formats must either be used - by the organization owning (to whom it was assigned) an Internet - domain name or X.500 name, or in the case that no such names are - registered, authority to use a realm name may be derived from the - authority of the parent realm. For example, if there is no domain - name for E40.MIT.EDU, then the administrator of the MIT.EDU realm can - authorize the creation of a realm with that name. - - This is acceptable because the organization to which the parent is - assigned is presumably the organization authorized to assign names to - its children in the X.500 and domain name systems as well. If the - parent assigns a realm name without also registering it in the domain - name or X.500 hierarchy, it is the parent's responsibility to make - sure that there will not in the future exists a name identical to the - realm name of the child unless it is assigned to the same entity as - the realm name. - -7.2. Principal Names - - As was the case for realm names, conventions are needed to ensure - that all agree on what information is implied by a principal name. - The name-type field that is part of the principal name indicates the - kind of information implied by the name. The name-type should be - treated as a hint. Ignoring the name type, no two names can be the - same (i.e., at least one of the components, or the realm, must be - different). This constraint may be eliminated in the future. The - following name types are defined: - - name-type value meaning - NT-UNKNOWN 0 Name type not known - NT-PRINCIPAL 1 Just the name of the principal as in - DCE, or for users - NT-SRV-INST 2 Service and other unique instance (krbtgt) - NT-SRV-HST 3 Service with host name as instance - (telnet, rcommands) - NT-SRV-XHST 4 Service with host as remaining components - NT-UID 5 Unique ID - - When a name implies no information other than its uniqueness at a - particular time the name type PRINCIPAL should be used. The - principal name type should be used for users, and it might also be - used for a unique server. If the name is a unique machine generated - ID that is guaranteed never to be reassigned then the name type of - UID should be used (note that it is generally a bad idea to reassign - names of any type since stale entries might remain in access control - lists). - - - -Kohl & Neuman [Page 79] - -RFC 1510 Kerberos September 1993 - - - If the first component of a name identifies a service and the - remaining components identify an instance of the service in a server - specified manner, then the name type of SRV-INST should be used. An - example of this name type is the Kerberos ticket-granting ticket - which has a first component of krbtgt and a second component - identifying the realm for which the ticket is valid. - - If instance is a single component following the service name and the - instance identifies the host on which the server is running, then the - name type SRV-HST should be used. This type is typically used for - Internet services such as telnet and the Berkeley R commands. If the - separate components of the host name appear as successive components - following the name of the service, then the name type SRVXHST should - be used. This type might be used to identify servers on hosts with - X.500 names where the slash (/) might otherwise be ambiguous. - - A name type of UNKNOWN should be used when the form of the name is - not known. When comparing names, a name of type UNKNOWN will match - principals authenticated with names of any type. A principal - authenticated with a name of type UNKNOWN, however, will only match - other names of type UNKNOWN. - - Names of any type with an initial component of "krbtgt" are reserved - for the Kerberos ticket granting service. See section 8.2.3 for the - form of such names. - -7.2.1. Name of server principals - - The principal identifier for a server on a host will generally be - composed of two parts: (1) the realm of the KDC with which the server - is registered, and (2) a two-component name of type NT-SRV-HST if the - host name is an Internet domain name or a multi-component name of - type NT-SRV-XHST if the name of the host is of a form such as X.500 - that allows slash (/) separators. The first component of the two- or - multi-component name will identify the service and the latter - components will identify the host. Where the name of the host is not - case sensitive (for example, with Internet domain names) the name of - the host must be lower case. For services such as telnet and the - Berkeley R commands which run with system privileges, the first - component will be the string "host" instead of a service specific - identifier. - -8. Constants and other defined values - -8.1. Host address types - - All negative values for the host address type are reserved for local - use. All non-negative values are reserved for officially assigned - - - -Kohl & Neuman [Page 80] - -RFC 1510 Kerberos September 1993 - - - type fields and interpretations. - - The values of the types for the following addresses are chosen to - match the defined address family constants in the Berkeley Standard - Distributions of Unix. They can be found in with - symbolic names AF_xxx (where xxx is an abbreviation of the address - family name). - - - Internet addresses - - Internet addresses are 32-bit (4-octet) quantities, encoded in MSB - order. The type of internet addresses is two (2). - - CHAOSnet addresses - - CHAOSnet addresses are 16-bit (2-octet) quantities, encoded in MSB - order. The type of CHAOSnet addresses is five (5). - - ISO addresses - - ISO addresses are variable-length. The type of ISO addresses is - seven (7). - - Xerox Network Services (XNS) addresses - - XNS addresses are 48-bit (6-octet) quantities, encoded in MSB - order. The type of XNS addresses is six (6). - - AppleTalk Datagram Delivery Protocol (DDP) addresses - - AppleTalk DDP addresses consist of an 8-bit node number and a 16- - bit network number. The first octet of the address is the node - number; the remaining two octets encode the network number in MSB - order. The type of AppleTalk DDP addresses is sixteen (16). - - DECnet Phase IV addresses - - DECnet Phase IV addresses are 16-bit addresses, encoded in LSB - order. The type of DECnet Phase IV addresses is twelve (12). - -8.2. KDC messages - -8.2.1. IP transport - - When contacting a Kerberos server (KDC) for a KRB_KDC_REQ request - using IP transport, the client shall send a UDP datagram containing - only an encoding of the request to port 88 (decimal) at the KDC's IP - - - -Kohl & Neuman [Page 81] - -RFC 1510 Kerberos September 1993 - - - address; the KDC will respond with a reply datagram containing only - an encoding of the reply message (either a KRB_ERROR or a - KRB_KDC_REP) to the sending port at the sender's IP address. - -8.2.2. OSI transport - - During authentication of an OSI client to and OSI server, the mutual - authentication of an OSI server to an OSI client, the transfer of - credentials from an OSI client to an OSI server, or during exchange - of private or integrity checked messages, Kerberos protocol messages - may be treated as opaque objects and the type of the authentication - mechanism will be: - - OBJECT IDENTIFIER ::= {iso (1), org(3), dod(5),internet(1), - security(5), kerberosv5(2)} - - Depending on the situation, the opaque object will be an - authentication header (KRB_AP_REQ), an authentication reply - (KRB_AP_REP), a safe message (KRB_SAFE), a private message - (KRB_PRIV), or a credentials message (KRB_CRED). The opaque data - contains an application code as specified in the ASN.1 description - for each message. The application code may be used by Kerberos to - determine the message type. - -8.2.3. Name of the TGS - - The principal identifier of the ticket-granting service shall be - composed of three parts: (1) the realm of the KDC issuing the TGS - ticket (2) a two-part name of type NT-SRVINST, with the first part - "krbtgt" and the second part the name of the realm which will accept - the ticket-granting ticket. For example, a ticket-granting ticket - issued by the ATHENA.MIT.EDU realm to be used to get tickets from the - ATHENA.MIT.EDU KDC has a principal identifier of "ATHENA.MIT.EDU" - (realm), ("krbtgt", "ATHENA.MIT.EDU") (name). A ticket-granting - ticket issued by the ATHENA.MIT.EDU realm to be used to get tickets - from the MIT.EDU realm has a principal identifier of "ATHENA.MIT.EDU" - (realm), ("krbtgt", "MIT.EDU") (name). - -8.3. Protocol constants and associated values - - The following tables list constants used in the protocol and defines - their meanings. - - - - - - - - - -Kohl & Neuman [Page 82] - -RFC 1510 Kerberos September 1993 - - ----------------+-----------+----------+----------------+--------------- -Encryption type|etype value|block size|minimum pad size|confounder size ----------------+-----------+----------+----------------+--------------- -NULL 0 1 0 0 -des-cbc-crc 1 8 4 8 -des-cbc-md4 2 8 0 8 -des-cbc-md5 3 8 0 8 - --------------------------------+-------------------+------------- -Checksum type |sumtype value |checksum size --------------------------------+-------------------+------------- -CRC32 1 4 -rsa-md4 2 16 -rsa-md4-des 3 24 -des-mac 4 16 -des-mac-k 5 8 -rsa-md4-des-k 6 16 -rsa-md5 7 16 -rsa-md5-des 8 24 - --------------------------------+----------------- -padata type |padata-type value --------------------------------+----------------- -PA-TGS-REQ 1 -PA-ENC-TIMESTAMP 2 -PA-PW-SALT 3 - --------------------------------+------------- -authorization data type |ad-type value --------------------------------+------------- -reserved values 0-63 -OSF-DCE 64 -SESAME 65 - --------------------------------+----------------- -alternate authentication type |method-type value --------------------------------+----------------- -reserved values 0-63 -ATT-CHALLENGE-RESPONSE 64 - --------------------------------+------------- -transited encoding type |tr-type value --------------------------------+------------- -DOMAIN-X500-COMPRESS 1 -reserved values all others - - - - - - -Kohl & Neuman [Page 83] - -RFC 1510 Kerberos September 1993 - - ---------------+-------+----------------------------------------- -Label |Value |Meaning or MIT code ---------------+-------+----------------------------------------- - -pvno 5 current Kerberos protocol version number - -message types - -KRB_AS_REQ 10 Request for initial authentication -KRB_AS_REP 11 Response to KRB_AS_REQ request -KRB_TGS_REQ 12 Request for authentication based on TGT -KRB_TGS_REP 13 Response to KRB_TGS_REQ request -KRB_AP_REQ 14 application request to server -KRB_AP_REP 15 Response to KRB_AP_REQ_MUTUAL -KRB_SAFE 20 Safe (checksummed) application message -KRB_PRIV 21 Private (encrypted) application message -KRB_CRED 22 Private (encrypted) message to forward - credentials -KRB_ERROR 30 Error response - -name types - -KRB_NT_UNKNOWN 0 Name type not known -KRB_NT_PRINCIPAL 1 Just the name of the principal as in DCE, or - for users -KRB_NT_SRV_INST 2 Service and other unique instance (krbtgt) -KRB_NT_SRV_HST 3 Service with host name as instance (telnet, - rcommands) -KRB_NT_SRV_XHST 4 Service with host as remaining components -KRB_NT_UID 5 Unique ID - -error codes - -KDC_ERR_NONE 0 No error -KDC_ERR_NAME_EXP 1 Client's entry in database has - expired -KDC_ERR_SERVICE_EXP 2 Server's entry in database has - expired -KDC_ERR_BAD_PVNO 3 Requested protocol version number - not supported -KDC_ERR_C_OLD_MAST_KVNO 4 Client's key encrypted in old - master key -KDC_ERR_S_OLD_MAST_KVNO 5 Server's key encrypted in old - master key -KDC_ERR_C_PRINCIPAL_UNKNOWN 6 Client not found in Kerberos database -KDC_ERR_S_PRINCIPAL_UNKNOWN 7 Server not found in Kerberos database -KDC_ERR_PRINCIPAL_NOT_UNIQUE 8 Multiple principal entries in - database - - - -Kohl & Neuman [Page 84] - -RFC 1510 Kerberos September 1993 - - -KDC_ERR_NULL_KEY 9 The client or server has a null key -KDC_ERR_CANNOT_POSTDATE 10 Ticket not eligible for postdating -KDC_ERR_NEVER_VALID 11 Requested start time is later than - end time -KDC_ERR_POLICY 12 KDC policy rejects request -KDC_ERR_BADOPTION 13 KDC cannot accommodate requested - option -KDC_ERR_ETYPE_NOSUPP 14 KDC has no support for encryption - type -KDC_ERR_SUMTYPE_NOSUPP 15 KDC has no support for checksum type -KDC_ERR_PADATA_TYPE_NOSUPP 16 KDC has no support for padata type -KDC_ERR_TRTYPE_NOSUPP 17 KDC has no support for transited type -KDC_ERR_CLIENT_REVOKED 18 Clients credentials have been revoked -KDC_ERR_SERVICE_REVOKED 19 Credentials for server have been - revoked -KDC_ERR_TGT_REVOKED 20 TGT has been revoked -KDC_ERR_CLIENT_NOTYET 21 Client not yet valid - try again - later -KDC_ERR_SERVICE_NOTYET 22 Server not yet valid - try again - later -KDC_ERR_KEY_EXPIRED 23 Password has expired - change - password to reset -KDC_ERR_PREAUTH_FAILED 24 Pre-authentication information - was invalid -KDC_ERR_PREAUTH_REQUIRED 25 Additional pre-authentication - required* -KRB_AP_ERR_BAD_INTEGRITY 31 Integrity check on decrypted field - failed -KRB_AP_ERR_TKT_EXPIRED 32 Ticket expired -KRB_AP_ERR_TKT_NYV 33 Ticket not yet valid -KRB_AP_ERR_REPEAT 34 Request is a replay -KRB_AP_ERR_NOT_US 35 The ticket isn't for us -KRB_AP_ERR_BADMATCH 36 Ticket and authenticator don't match -KRB_AP_ERR_SKEW 37 Clock skew too great -KRB_AP_ERR_BADADDR 38 Incorrect net address -KRB_AP_ERR_BADVERSION 39 Protocol version mismatch -KRB_AP_ERR_MSG_TYPE 40 Invalid msg type -KRB_AP_ERR_MODIFIED 41 Message stream modified -KRB_AP_ERR_BADORDER 42 Message out of order -KRB_AP_ERR_BADKEYVER 44 Specified version of key is not - available -KRB_AP_ERR_NOKEY 45 Service key not available -KRB_AP_ERR_MUT_FAIL 46 Mutual authentication failed -KRB_AP_ERR_BADDIRECTION 47 Incorrect message direction -KRB_AP_ERR_METHOD 48 Alternative authentication method - required* -KRB_AP_ERR_BADSEQ 49 Incorrect sequence number in message -KRB_AP_ERR_INAPP_CKSUM 50 Inappropriate type of checksum in - - - -Kohl & Neuman [Page 85] - -RFC 1510 Kerberos September 1993 - - - message -KRB_ERR_GENERIC 60 Generic error (description in e-text) -KRB_ERR_FIELD_TOOLONG 61 Field is too long for this - implementation - - *This error carries additional information in the e-data field. The - contents of the e-data field for this message is described in section - 5.9.1. - -9. Interoperability requirements - - Version 5 of the Kerberos protocol supports a myriad of options. - Among these are multiple encryption and checksum types, alternative - encoding schemes for the transited field, optional mechanisms for - pre-authentication, the handling of tickets with no addresses, - options for mutual authentication, user to user authentication, - support for proxies, forwarding, postdating, and renewing tickets, - the format of realm names, and the handling of authorization data. - - In order to ensure the interoperability of realms, it is necessary to - define a minimal configuration which must be supported by all - implementations. This minimal configuration is subject to change as - technology does. For example, if at some later date it is discovered - that one of the required encryption or checksum algorithms is not - secure, it will be replaced. - -9.1. Specification 1 - - This section defines the first specification of these options. - Implementations which are configured in this way can be said to - support Kerberos Version 5 Specification 1 (5.1). - - Encryption and checksum methods - - The following encryption and checksum mechanisms must be supported. - Implementations may support other mechanisms as well, but the - additional mechanisms may only be used when communicating with - principals known to also support them: Encryption: DES-CBC-MD5 - Checksums: CRC-32, DES-MAC, DES-MAC-K, and DES-MD5 - - Realm Names - - All implementations must understand hierarchical realms in both the - Internet Domain and the X.500 style. When a ticket granting ticket - for an unknown realm is requested, the KDC must be able to determine - the names of the intermediate realms between the KDCs realm and the - requested realm. - - - - -Kohl & Neuman [Page 86] - -RFC 1510 Kerberos September 1993 - - - Transited field encoding - - DOMAIN-X500-COMPRESS (described in section 3.3.3.1) must be - supported. Alternative encodings may be supported, but they may be - used only when that encoding is supported by ALL intermediate realms. - - Pre-authentication methods - - The TGS-REQ method must be supported. The TGS-REQ method is not used - on the initial request. The PA-ENC-TIMESTAMP method must be supported - by clients but whether it is enabled by default may be determined on - a realm by realm basis. If not used in the initial request and the - error KDC_ERR_PREAUTH_REQUIRED is returned specifying PA-ENCTIMESTAMP - as an acceptable method, the client should retry the initial request - using the PA-ENC-TIMESTAMP preauthentication method. Servers need not - support the PAENC-TIMESTAMP method, but if not supported the server - should ignore the presence of PA-ENC-TIMESTAMP pre-authentication in - a request. - - Mutual authentication - - Mutual authentication (via the KRB_AP_REP message) must be supported. - - Ticket addresses and flags - - All KDC's must pass on tickets that carry no addresses (i.e., if a - TGT contains no addresses, the KDC will return derivative tickets), - but each realm may set its own policy for issuing such tickets, and - each application server will set its own policy with respect to - accepting them. By default, servers should not accept them. - - Proxies and forwarded tickets must be supported. Individual realms - and application servers can set their own policy on when such tickets - will be accepted. - - All implementations must recognize renewable and postdated tickets, - but need not actually implement them. If these options are not - supported, the starttime and endtime in the ticket shall specify a - ticket's entire useful life. When a postdated ticket is decoded by a - server, all implementations shall make the presence of the postdated - flag visible to the calling server. - - User-to-user authentication - - Support for user to user authentication (via the ENC-TKTIN-SKEY KDC - option) must be provided by implementations, but individual realms - may decide as a matter of policy to reject such requests on a per- - principal or realm-wide basis. - - - -Kohl & Neuman [Page 87] - -RFC 1510 Kerberos September 1993 - - - Authorization data - - Implementations must pass all authorization data subfields from - ticket-granting tickets to any derivative tickets unless directed to - suppress a subfield as part of the definition of that registered - subfield type (it is never incorrect to pass on a subfield, and no - registered subfield types presently specify suppression at the KDC). - - Implementations must make the contents of any authorization data - subfields available to the server when a ticket is used. - Implementations are not required to allow clients to specify the - contents of the authorization data fields. - -9.2. Recommended KDC values - - Following is a list of recommended values for a KDC implementation, - based on the list of suggested configuration constants (see section - 4.4). - - minimum lifetime 5 minutes - - maximum renewable lifetime 1 week - - maximum ticket lifetime 1 day - - empty addresses only when suitable restrictions appear - in authorization data - - proxiable, etc. Allowed. - -10. Acknowledgments - - Early versions of this document, describing version 4 of the - protocol, were written by Jennifer Steiner (formerly at Project - Athena); these drafts provided an excellent starting point for this - current version 5 specification. Many people in the Internet - community have contributed ideas and suggested protocol changes for - version 5. Notable contributions came from Ted Anderson, Steve - Bellovin and Michael Merritt [17], Daniel Bernstein, Mike Burrows, - Donald Davis, Ravi Ganesan, Morrie Gasser, Virgil Gligor, Bill - Griffeth, Mark Lillibridge, Mark Lomas, Steve Lunt, Piers McMahon, - Joe Pato, William Sommerfeld, Stuart Stubblebine, Ralph Swick, Ted - T'so, and Stanley Zanarotti. Many others commented and helped shape - this specification into its current form. - - - - - - - -Kohl & Neuman [Page 88] - -RFC 1510 Kerberos September 1993 - - -11. References - - [1] Miller, S., Neuman, C., Schiller, J., and J. Saltzer, "Section - E.2.1: Kerberos Authentication and Authorization System", - M.I.T. Project Athena, Cambridge, Massachusetts, December 21, - 1987. - - [2] Steiner, J., Neuman, C., and J. Schiller, "Kerberos: An - Authentication Service for Open Network Systems", pp. 191-202 in - Usenix Conference Proceedings, Dallas, Texas, February, 1988. - - [3] Needham, R., and M. Schroeder, "Using Encryption for - Authentication in Large Networks of Computers", Communications - of the ACM, Vol. 21 (12), pp. 993-999, December 1978. - - [4] Denning, D., and G. Sacco, "Time stamps in Key Distribution - Protocols", Communications of the ACM, Vol. 24 (8), pp. 533-536, - August 1981. - - [5] Kohl, J., Neuman, C., and T. Ts'o, "The Evolution of the - Kerberos Authentication Service", in an IEEE Computer Society - Text soon to be published, June 1992. - - [6] Davis, D., and R. Swick, "Workstation Services and Kerberos - Authentication at Project Athena", Technical Memorandum TM-424, - MIT Laboratory for Computer Science, February 1990. - - [7] Levine, P., Gretzinger, M, Diaz, J., Sommerfeld, W., and K. - Raeburn, "Section E.1: Service Management System, M.I.T. - Project Athena, Cambridge, Mas sachusetts (1987). - - [8] CCITT, Recommendation X.509: The Directory Authentication - Framework, December 1988. - - [9] Neuman, C., "Proxy-Based Authorization and Accounting for - Distributed Systems," in Proceedings of the 13th International - Conference on Distributed Computing Systems", Pittsburgh, PA, - May 1993. - - [10] Pato, J., "Using Pre-Authentication to Avoid Password Guessing - Attacks", Open Software Foundation DCE Request for Comments 26, - December 1992. - - [11] National Bureau of Standards, U.S. Department of Commerce, "Data - Encryption Standard", Federal Information Processing Standards - Publication 46, Washington, DC (1977). - - - - - -Kohl & Neuman [Page 89] - -RFC 1510 Kerberos September 1993 - - - [12] National Bureau of Standards, U.S. Department of Commerce, "DES - Modes of Operation", Federal Information Processing Standards - Publication 81, Springfield, VA, December 1980. - - [13] Stubblebine S., and V. Gligor, "On Message Integrity in - Cryptographic Protocols", in Proceedings of the IEEE Symposium - on Research in Security and Privacy, Oakland, California, May - 1992. - - [14] International Organization for Standardization, "ISO Information - Processing Systems - Data Communication High-Level Data Link - Control Procedure - Frame Structure", IS 3309, October 1984, 3rd - Edition. - - [15] Rivest, R., "The MD4 Message Digest Algorithm", RFC 1320, MIT - Laboratory for Computer Science, April 1992. - - [16] Rivest, R., "The MD5 Message Digest Algorithm", RFC 1321, MIT - Laboratory for Computer Science, April 1992. - - [17] Bellovin S., and M. Merritt, "Limitations of the Kerberos - Authentication System", Computer Communications Review, Vol. - 20(5), pp. 119-132, October 1990. - -12. Security Considerations - - Security issues are discussed throughout this memo. - -13. Authors' Addresses - - John Kohl - Digital Equipment Corporation - 110 Spit Brook Road, M/S ZKO3-3/U14 - Nashua, NH 03062 - - Phone: 603-881-2481 - EMail: jtkohl@zk3.dec.com - - - B. Clifford Neuman - USC/Information Sciences Institute - 4676 Admiralty Way #1001 - Marina del Rey, CA 90292-6695 - - Phone: 310-822-1511 - EMail: bcn@isi.edu - - - - - -Kohl & Neuman [Page 90] - -RFC 1510 Kerberos September 1993 - - -A. Pseudo-code for protocol processing - - This appendix provides pseudo-code describing how the messages are to - be constructed and interpreted by clients and servers. - -A.1. KRB_AS_REQ generation - request.pvno := protocol version; /* pvno = 5 */ - request.msg-type := message type; /* type = KRB_AS_REQ */ - - if(pa_enc_timestamp_required) then - request.padata.padata-type = PA-ENC-TIMESTAMP; - get system_time; - padata-body.patimestamp,pausec = system_time; - encrypt padata-body into request.padata.padata-value - using client.key; /* derived from password */ - endif - - body.kdc-options := users's preferences; - body.cname := user's name; - body.realm := user's realm; - body.sname := service's name; /* usually "krbtgt", - "localrealm" */ - if (body.kdc-options.POSTDATED is set) then - body.from := requested starting time; - else - omit body.from; - endif - body.till := requested end time; - if (body.kdc-options.RENEWABLE is set) then - body.rtime := requested final renewal time; - endif - body.nonce := random_nonce(); - body.etype := requested etypes; - if (user supplied addresses) then - body.addresses := user's addresses; - else - omit body.addresses; - endif - omit body.enc-authorization-data; - request.req-body := body; - - kerberos := lookup(name of local kerberos server (or servers)); - send(packet,kerberos); - - wait(for response); - if (timed_out) then - retry or use alternate server; - endif - - - -Kohl & Neuman [Page 91] - -RFC 1510 Kerberos September 1993 - - -A.2. KRB_AS_REQ verification and KRB_AS_REP generation - decode message into req; - - client := lookup(req.cname,req.realm); - server := lookup(req.sname,req.realm); - get system_time; - kdc_time := system_time.seconds; - - if (!client) then - /* no client in Database */ - error_out(KDC_ERR_C_PRINCIPAL_UNKNOWN); - endif - if (!server) then - /* no server in Database */ - error_out(KDC_ERR_S_PRINCIPAL_UNKNOWN); - endif - - if(client.pa_enc_timestamp_required and - pa_enc_timestamp not present) then - error_out(KDC_ERR_PREAUTH_REQUIRED(PA_ENC_TIMESTAMP)); - endif - - if(pa_enc_timestamp present) then - decrypt req.padata-value into decrypted_enc_timestamp - using client.key; - using auth_hdr.authenticator.subkey; - if (decrypt_error()) then - error_out(KRB_AP_ERR_BAD_INTEGRITY); - if(decrypted_enc_timestamp is not within allowable - skew) then error_out(KDC_ERR_PREAUTH_FAILED); - endif - if(decrypted_enc_timestamp and usec is replay) - error_out(KDC_ERR_PREAUTH_FAILED); - endif - add decrypted_enc_timestamp and usec to replay cache; - endif - - use_etype := first supported etype in req.etypes; - - if (no support for req.etypes) then - error_out(KDC_ERR_ETYPE_NOSUPP); - endif - - new_tkt.vno := ticket version; /* = 5 */ - new_tkt.sname := req.sname; - new_tkt.srealm := req.srealm; - reset all flags in new_tkt.flags; - - - - -Kohl & Neuman [Page 92] - -RFC 1510 Kerberos September 1993 - - - /* It should be noted that local policy may affect the */ - /* processing of any of these flags. For example, some */ - /* realms may refuse to issue renewable tickets */ - - if (req.kdc-options.FORWARDABLE is set) then - set new_tkt.flags.FORWARDABLE; - endif - if (req.kdc-options.PROXIABLE is set) then - set new_tkt.flags.PROXIABLE; - endif - if (req.kdc-options.ALLOW-POSTDATE is set) then - set new_tkt.flags.ALLOW-POSTDATE; - endif - if ((req.kdc-options.RENEW is set) or - (req.kdc-options.VALIDATE is set) or - (req.kdc-options.PROXY is set) or - (req.kdc-options.FORWARDED is set) or - (req.kdc-options.ENC-TKT-IN-SKEY is set)) then - error_out(KDC_ERR_BADOPTION); - endif - - new_tkt.session := random_session_key(); - new_tkt.cname := req.cname; - new_tkt.crealm := req.crealm; - new_tkt.transited := empty_transited_field(); - - new_tkt.authtime := kdc_time; - - if (req.kdc-options.POSTDATED is set) then - if (against_postdate_policy(req.from)) then - error_out(KDC_ERR_POLICY); - endif - set new_tkt.flags.INVALID; - new_tkt.starttime := req.from; - else - omit new_tkt.starttime; /* treated as authtime when - omitted */ - endif - if (req.till = 0) then - till := infinity; - else - till := req.till; - endif - - new_tkt.endtime := min(till, - new_tkt.starttime+client.max_life, - new_tkt.starttime+server.max_life, - new_tkt.starttime+max_life_for_realm); - - - -Kohl & Neuman [Page 93] - -RFC 1510 Kerberos September 1993 - - - if ((req.kdc-options.RENEWABLE-OK is set) and - (new_tkt.endtime < req.till)) then - /* we set the RENEWABLE option for later processing */ - set req.kdc-options.RENEWABLE; - req.rtime := req.till; - endif - - if (req.rtime = 0) then - rtime := infinity; - else - rtime := req.rtime; - endif - - if (req.kdc-options.RENEWABLE is set) then - set new_tkt.flags.RENEWABLE; - new_tkt.renew-till := min(rtime, - new_tkt.starttime+client.max_rlife, - new_tkt.starttime+server.max_rlife, - new_tkt.starttime+max_rlife_for_realm); - else - omit new_tkt.renew-till; /* only present if RENEWABLE */ - endif - - if (req.addresses) then - new_tkt.caddr := req.addresses; - else - omit new_tkt.caddr; - endif - - new_tkt.authorization_data := empty_authorization_data(); - - encode to-be-encrypted part of ticket into OCTET STRING; - new_tkt.enc-part := encrypt OCTET STRING - using etype_for_key(server.key), server.key, server.p_kvno; - - - /* Start processing the response */ - - resp.pvno := 5; - resp.msg-type := KRB_AS_REP; - resp.cname := req.cname; - resp.crealm := req.realm; - resp.ticket := new_tkt; - - resp.key := new_tkt.session; - resp.last-req := fetch_last_request_info(client); - resp.nonce := req.nonce; - resp.key-expiration := client.expiration; - - - -Kohl & Neuman [Page 94] - -RFC 1510 Kerberos September 1993 - - - resp.flags := new_tkt.flags; - - resp.authtime := new_tkt.authtime; - resp.starttime := new_tkt.starttime; - resp.endtime := new_tkt.endtime; - - if (new_tkt.flags.RENEWABLE) then - resp.renew-till := new_tkt.renew-till; - endif - - resp.realm := new_tkt.realm; - resp.sname := new_tkt.sname; - - resp.caddr := new_tkt.caddr; - - encode body of reply into OCTET STRING; - - resp.enc-part := encrypt OCTET STRING - using use_etype, client.key, client.p_kvno; - send(resp); - -A.3. KRB_AS_REP verification - decode response into resp; - - if (resp.msg-type = KRB_ERROR) then - if(error = KDC_ERR_PREAUTH_REQUIRED(PA_ENC_TIMESTAMP)) - then set pa_enc_timestamp_required; - goto KRB_AS_REQ; - endif - process_error(resp); - return; - endif - - /* On error, discard the response, and zero the session key */ - /* from the response immediately */ - - key = get_decryption_key(resp.enc-part.kvno, resp.enc-part.etype, - resp.padata); - unencrypted part of resp := decode of decrypt of resp.enc-part - using resp.enc-part.etype and key; - zero(key); - - if (common_as_rep_tgs_rep_checks fail) then - destroy resp.key; - return error; - endif - - if near(resp.princ_exp) then - - - -Kohl & Neuman [Page 95] - -RFC 1510 Kerberos September 1993 - - - print(warning message); - endif - save_for_later(ticket,session,client,server,times,flags); - -A.4. KRB_AS_REP and KRB_TGS_REP common checks - if (decryption_error() or - (req.cname != resp.cname) or - (req.realm != resp.crealm) or - (req.sname != resp.sname) or - (req.realm != resp.realm) or - (req.nonce != resp.nonce) or - (req.addresses != resp.caddr)) then - destroy resp.key; - return KRB_AP_ERR_MODIFIED; - endif - - /* make sure no flags are set that shouldn't be, and that */ - /* all that should be are set */ - if (!check_flags_for_compatability(req.kdc-options,resp.flags)) - then destroy resp.key; - return KRB_AP_ERR_MODIFIED; - endif - - if ((req.from = 0) and - (resp.starttime is not within allowable skew)) then - destroy resp.key; - return KRB_AP_ERR_SKEW; - endif - if ((req.from != 0) and (req.from != resp.starttime)) then - destroy resp.key; - return KRB_AP_ERR_MODIFIED; - endif - if ((req.till != 0) and (resp.endtime > req.till)) then - destroy resp.key; - return KRB_AP_ERR_MODIFIED; - endif - - if ((req.kdc-options.RENEWABLE is set) and - (req.rtime != 0) and (resp.renew-till > req.rtime)) then - destroy resp.key; - return KRB_AP_ERR_MODIFIED; - endif - if ((req.kdc-options.RENEWABLE-OK is set) and - (resp.flags.RENEWABLE) and - (req.till != 0) and - (resp.renew-till > req.till)) then - destroy resp.key; - return KRB_AP_ERR_MODIFIED; - - - -Kohl & Neuman [Page 96] - -RFC 1510 Kerberos September 1993 - - - endif - -A.5. KRB_TGS_REQ generation - /* Note that make_application_request might have to */ - /* recursivly call this routine to get the appropriate */ - /* ticket-granting ticket */ - - request.pvno := protocol version; /* pvno = 5 */ - request.msg-type := message type; /* type = KRB_TGS_REQ */ - - body.kdc-options := users's preferences; - /* If the TGT is not for the realm of the end-server */ - /* then the sname will be for a TGT for the end-realm */ - /* and the realm of the requested ticket (body.realm) */ - /* will be that of the TGS to which the TGT we are */ - /* sending applies */ - body.sname := service's name; - body.realm := service's realm; - - if (body.kdc-options.POSTDATED is set) then - body.from := requested starting time; - else - omit body.from; - endif - body.till := requested end time; - if (body.kdc-options.RENEWABLE is set) then - body.rtime := requested final renewal time; - endif - body.nonce := random_nonce(); - body.etype := requested etypes; - if (user supplied addresses) then - body.addresses := user's addresses; - else - omit body.addresses; - endif - - body.enc-authorization-data := user-supplied data; - if (body.kdc-options.ENC-TKT-IN-SKEY) then - body.additional-tickets_ticket := second TGT; - endif - - request.req-body := body; - check := generate_checksum (req.body,checksumtype); - - request.padata[0].padata-type := PA-TGS-REQ; - request.padata[0].padata-value := create a KRB_AP_REQ using - the TGT and checksum - - - - -Kohl & Neuman [Page 97] - -RFC 1510 Kerberos September 1993 - - - /* add in any other padata as required/supplied */ - - kerberos := lookup(name of local kerberose server (or servers)); - send(packet,kerberos); - - wait(for response); - if (timed_out) then - retry or use alternate server; - endif - -A.6. KRB_TGS_REQ verification and KRB_TGS_REP generation - /* note that reading the application request requires first - determining the server for which a ticket was issued, and - choosing the correct key for decryption. The name of the - server appears in the plaintext part of the ticket. */ - - if (no KRB_AP_REQ in req.padata) then - error_out(KDC_ERR_PADATA_TYPE_NOSUPP); - endif - verify KRB_AP_REQ in req.padata; - - /* Note that the realm in which the Kerberos server is - operating is determined by the instance from the - ticket-granting ticket. The realm in the ticket-granting - ticket is the realm under which the ticket granting ticket was - issued. It is possible for a single Kerberos server to - support more than one realm. */ - - auth_hdr := KRB_AP_REQ; - tgt := auth_hdr.ticket; - - if (tgt.sname is not a TGT for local realm and is not - req.sname) then error_out(KRB_AP_ERR_NOT_US); - - realm := realm_tgt_is_for(tgt); - - decode remainder of request; - - if (auth_hdr.authenticator.cksum is missing) then - error_out(KRB_AP_ERR_INAPP_CKSUM); - endif - if (auth_hdr.authenticator.cksum type is not supported) then - error_out(KDC_ERR_SUMTYPE_NOSUPP); - endif - if (auth_hdr.authenticator.cksum is not both collision-proof - and keyed) then - error_out(KRB_AP_ERR_INAPP_CKSUM); - endif - - - -Kohl & Neuman [Page 98] - -RFC 1510 Kerberos September 1993 - - - set computed_checksum := checksum(req); - if (computed_checksum != auth_hdr.authenticatory.cksum) then - error_out(KRB_AP_ERR_MODIFIED); - endif - - server := lookup(req.sname,realm); - - if (!server) then - if (is_foreign_tgt_name(server)) then - server := best_intermediate_tgs(server); - else - /* no server in Database */ - error_out(KDC_ERR_S_PRINCIPAL_UNKNOWN); - endif - endif - - session := generate_random_session_key(); - - - use_etype := first supported etype in req.etypes; - - if (no support for req.etypes) then - error_out(KDC_ERR_ETYPE_NOSUPP); - endif - - new_tkt.vno := ticket version; /* = 5 */ - new_tkt.sname := req.sname; - new_tkt.srealm := realm; - reset all flags in new_tkt.flags; - - /* It should be noted that local policy may affect the */ - /* processing of any of these flags. For example, some */ - /* realms may refuse to issue renewable tickets */ - - new_tkt.caddr := tgt.caddr; - resp.caddr := NULL; /* We only include this if they change */ - if (req.kdc-options.FORWARDABLE is set) then - if (tgt.flags.FORWARDABLE is reset) then - error_out(KDC_ERR_BADOPTION); - endif - set new_tkt.flags.FORWARDABLE; - endif - if (req.kdc-options.FORWARDED is set) then - if (tgt.flags.FORWARDABLE is reset) then - error_out(KDC_ERR_BADOPTION); - endif - set new_tkt.flags.FORWARDED; - new_tkt.caddr := req.addresses; - - - -Kohl & Neuman [Page 99] - -RFC 1510 Kerberos September 1993 - - - resp.caddr := req.addresses; - endif - if (tgt.flags.FORWARDED is set) then - set new_tkt.flags.FORWARDED; - endif - - if (req.kdc-options.PROXIABLE is set) then - if (tgt.flags.PROXIABLE is reset) - error_out(KDC_ERR_BADOPTION); - endif - set new_tkt.flags.PROXIABLE; - endif - if (req.kdc-options.PROXY is set) then - if (tgt.flags.PROXIABLE is reset) then - error_out(KDC_ERR_BADOPTION); - endif - set new_tkt.flags.PROXY; - new_tkt.caddr := req.addresses; - resp.caddr := req.addresses; - endif - - if (req.kdc-options.POSTDATE is set) then - if (tgt.flags.POSTDATE is reset) - error_out(KDC_ERR_BADOPTION); - endif - set new_tkt.flags.POSTDATE; - endif - if (req.kdc-options.POSTDATED is set) then - if (tgt.flags.POSTDATE is reset) then - error_out(KDC_ERR_BADOPTION); - endif - set new_tkt.flags.POSTDATED; - set new_tkt.flags.INVALID; - if (against_postdate_policy(req.from)) then - error_out(KDC_ERR_POLICY); - endif - new_tkt.starttime := req.from; - endif - - - if (req.kdc-options.VALIDATE is set) then - if (tgt.flags.INVALID is reset) then - error_out(KDC_ERR_POLICY); - endif - if (tgt.starttime > kdc_time) then - error_out(KRB_AP_ERR_NYV); - endif - if (check_hot_list(tgt)) then - - - -Kohl & Neuman [Page 100] - -RFC 1510 Kerberos September 1993 - - - error_out(KRB_AP_ERR_REPEAT); - endif - tkt := tgt; - reset new_tkt.flags.INVALID; - endif - - if (req.kdc-options.(any flag except ENC-TKT-IN-SKEY, RENEW, - and those already processed) is set) then - error_out(KDC_ERR_BADOPTION); - endif - - new_tkt.authtime := tgt.authtime; - - if (req.kdc-options.RENEW is set) then - /* Note that if the endtime has already passed, the ticket */ - /* would have been rejected in the initial authentication */ - /* stage, so there is no need to check again here */ - if (tgt.flags.RENEWABLE is reset) then - error_out(KDC_ERR_BADOPTION); - endif - if (tgt.renew-till >= kdc_time) then - error_out(KRB_AP_ERR_TKT_EXPIRED); - endif - tkt := tgt; - new_tkt.starttime := kdc_time; - old_life := tgt.endttime - tgt.starttime; - new_tkt.endtime := min(tgt.renew-till, - new_tkt.starttime + old_life); - else - new_tkt.starttime := kdc_time; - if (req.till = 0) then - till := infinity; - else - till := req.till; - endif - new_tkt.endtime := min(till, - new_tkt.starttime+client.max_life, - new_tkt.starttime+server.max_life, - new_tkt.starttime+max_life_for_realm, - tgt.endtime); - - if ((req.kdc-options.RENEWABLE-OK is set) and - (new_tkt.endtime < req.till) and - (tgt.flags.RENEWABLE is set) then - /* we set the RENEWABLE option for later */ - /* processing */ - set req.kdc-options.RENEWABLE; - req.rtime := min(req.till, tgt.renew-till); - - - -Kohl & Neuman [Page 101] - -RFC 1510 Kerberos September 1993 - - - endif - endif - - if (req.rtime = 0) then - rtime := infinity; - else - rtime := req.rtime; - endif - - if ((req.kdc-options.RENEWABLE is set) and - (tgt.flags.RENEWABLE is set)) then - set new_tkt.flags.RENEWABLE; - new_tkt.renew-till := min(rtime, - new_tkt.starttime+client.max_rlife, - new_tkt.starttime+server.max_rlife, - new_tkt.starttime+max_rlife_for_realm, - tgt.renew-till); - else - new_tkt.renew-till := OMIT; - /* leave the renew-till field out */ - endif - if (req.enc-authorization-data is present) then - decrypt req.enc-authorization-data - into decrypted_authorization_data - using auth_hdr.authenticator.subkey; - if (decrypt_error()) then - error_out(KRB_AP_ERR_BAD_INTEGRITY); - endif - endif - new_tkt.authorization_data := - req.auth_hdr.ticket.authorization_data + - decrypted_authorization_data; - - new_tkt.key := session; - new_tkt.crealm := tgt.crealm; - new_tkt.cname := req.auth_hdr.ticket.cname; - - if (realm_tgt_is_for(tgt) := tgt.realm) then - /* tgt issued by local realm */ - new_tkt.transited := tgt.transited; - else - /* was issued for this realm by some other realm */ - if (tgt.transited.tr-type not supported) then - error_out(KDC_ERR_TRTYPE_NOSUPP); - endif - new_tkt.transited - := compress_transited(tgt.transited + tgt.realm) - endif - - - -Kohl & Neuman [Page 102] - -RFC 1510 Kerberos September 1993 - - - encode encrypted part of new_tkt into OCTET STRING; - if (req.kdc-options.ENC-TKT-IN-SKEY is set) then - if (server not specified) then - server = req.second_ticket.client; - endif - if ((req.second_ticket is not a TGT) or - (req.second_ticket.client != server)) then - error_out(KDC_ERR_POLICY); - endif - - new_tkt.enc-part := encrypt OCTET STRING using - using etype_for_key(second-ticket.key), - second-ticket.key; - else - new_tkt.enc-part := encrypt OCTET STRING - using etype_for_key(server.key), server.key, - server.p_kvno; - endif - - resp.pvno := 5; - resp.msg-type := KRB_TGS_REP; - resp.crealm := tgt.crealm; - resp.cname := tgt.cname; - resp.ticket := new_tkt; - - resp.key := session; - resp.nonce := req.nonce; - resp.last-req := fetch_last_request_info(client); - resp.flags := new_tkt.flags; - - resp.authtime := new_tkt.authtime; - resp.starttime := new_tkt.starttime; - resp.endtime := new_tkt.endtime; - - omit resp.key-expiration; - - resp.sname := new_tkt.sname; - resp.realm := new_tkt.realm; - - if (new_tkt.flags.RENEWABLE) then - resp.renew-till := new_tkt.renew-till; - endif - - - encode body of reply into OCTET STRING; - - if (req.padata.authenticator.subkey) - resp.enc-part := encrypt OCTET STRING using use_etype, - - - -Kohl & Neuman [Page 103] - -RFC 1510 Kerberos September 1993 - - - req.padata.authenticator.subkey; - else resp.enc-part := encrypt OCTET STRING - using use_etype, tgt.key; - - send(resp); - -A.7. KRB_TGS_REP verification - decode response into resp; - - if (resp.msg-type = KRB_ERROR) then - process_error(resp); - return; - endif - - /* On error, discard the response, and zero the session key from - the response immediately */ - - if (req.padata.authenticator.subkey) - unencrypted part of resp := - decode of decrypt of resp.enc-part - using resp.enc-part.etype and subkey; - else unencrypted part of resp := - decode of decrypt of resp.enc-part - using resp.enc-part.etype and tgt's session key; - if (common_as_rep_tgs_rep_checks fail) then - destroy resp.key; - return error; - endif - - check authorization_data as necessary; - save_for_later(ticket,session,client,server,times,flags); - -A.8. Authenticator generation - body.authenticator-vno := authenticator vno; /* = 5 */ - body.cname, body.crealm := client name; - if (supplying checksum) then - body.cksum := checksum; - endif - get system_time; - body.ctime, body.cusec := system_time; - if (selecting sub-session key) then - select sub-session key; - body.subkey := sub-session key; - endif - if (using sequence numbers) then - select initial sequence number; - body.seq-number := initial sequence; - endif - - - -Kohl & Neuman [Page 104] - -RFC 1510 Kerberos September 1993 - - -A.9. KRB_AP_REQ generation - obtain ticket and session_key from cache; - - packet.pvno := protocol version; /* 5 */ - packet.msg-type := message type; /* KRB_AP_REQ */ - - if (desired(MUTUAL_AUTHENTICATION)) then - set packet.ap-options.MUTUAL-REQUIRED; - else - reset packet.ap-options.MUTUAL-REQUIRED; - endif - if (using session key for ticket) then - set packet.ap-options.USE-SESSION-KEY; - else - reset packet.ap-options.USE-SESSION-KEY; - endif - packet.ticket := ticket; /* ticket */ - generate authenticator; - encode authenticator into OCTET STRING; - encrypt OCTET STRING into packet.authenticator - using session_key; - -A.10. KRB_AP_REQ verification - receive packet; - if (packet.pvno != 5) then - either process using other protocol spec - or error_out(KRB_AP_ERR_BADVERSION); - endif - if (packet.msg-type != KRB_AP_REQ) then - error_out(KRB_AP_ERR_MSG_TYPE); - endif - if (packet.ticket.tkt_vno != 5) then - either process using other protocol spec - or error_out(KRB_AP_ERR_BADVERSION); - endif - if (packet.ap_options.USE-SESSION-KEY is set) then - retrieve session key from ticket-granting ticket for - packet.ticket.{sname,srealm,enc-part.etype}; - else - retrieve service key for - packet.ticket.{sname,srealm,enc-part.etype,enc-part.skvno}; - endif - if (no_key_available) then - if (cannot_find_specified_skvno) then - error_out(KRB_AP_ERR_BADKEYVER); - else - error_out(KRB_AP_ERR_NOKEY); - endif - - - -Kohl & Neuman [Page 105] - -RFC 1510 Kerberos September 1993 - - - endif - decrypt packet.ticket.enc-part into decr_ticket - using retrieved key; - if (decryption_error()) then - error_out(KRB_AP_ERR_BAD_INTEGRITY); - endif - decrypt packet.authenticator into decr_authenticator - using decr_ticket.key; - if (decryption_error()) then - error_out(KRB_AP_ERR_BAD_INTEGRITY); - endif - if (decr_authenticator.{cname,crealm} != - decr_ticket.{cname,crealm}) then - error_out(KRB_AP_ERR_BADMATCH); - endif - if (decr_ticket.caddr is present) then - if (sender_address(packet) is not in decr_ticket.caddr) - then error_out(KRB_AP_ERR_BADADDR); - endif - elseif (application requires addresses) then - error_out(KRB_AP_ERR_BADADDR); - endif - if (not in_clock_skew(decr_authenticator.ctime, - decr_authenticator.cusec)) then - error_out(KRB_AP_ERR_SKEW); - endif - if (repeated(decr_authenticator.{ctime,cusec,cname,crealm})) - then error_out(KRB_AP_ERR_REPEAT); - endif - save_identifier(decr_authenticator.{ctime,cusec,cname,crealm}); - get system_time; - if ((decr_ticket.starttime-system_time > CLOCK_SKEW) or - (decr_ticket.flags.INVALID is set)) then - /* it hasn't yet become valid */ - error_out(KRB_AP_ERR_TKT_NYV); - endif - if (system_time-decr_ticket.endtime > CLOCK_SKEW) then - error_out(KRB_AP_ERR_TKT_EXPIRED); - endif - /* caller must check decr_ticket.flags for any pertinent */ - /* details */ - return(OK, decr_ticket, packet.ap_options.MUTUAL-REQUIRED); - -A.11. KRB_AP_REP generation - packet.pvno := protocol version; /* 5 */ - packet.msg-type := message type; /* KRB_AP_REP */ - body.ctime := packet.ctime; - body.cusec := packet.cusec; - - - -Kohl & Neuman [Page 106] - -RFC 1510 Kerberos September 1993 - - - if (selecting sub-session key) then - select sub-session key; - body.subkey := sub-session key; - endif - if (using sequence numbers) then - select initial sequence number; - body.seq-number := initial sequence; - endif - - encode body into OCTET STRING; - - select encryption type; - encrypt OCTET STRING into packet.enc-part; - -A.12. KRB_AP_REP verification - receive packet; - if (packet.pvno != 5) then - either process using other protocol spec - or error_out(KRB_AP_ERR_BADVERSION); - endif - if (packet.msg-type != KRB_AP_REP) then - error_out(KRB_AP_ERR_MSG_TYPE); - endif - cleartext := decrypt(packet.enc-part) - using ticket's session key; - if (decryption_error()) then - error_out(KRB_AP_ERR_BAD_INTEGRITY); - endif - if (cleartext.ctime != authenticator.ctime) then - error_out(KRB_AP_ERR_MUT_FAIL); - endif - if (cleartext.cusec != authenticator.cusec) then - error_out(KRB_AP_ERR_MUT_FAIL); - endif - if (cleartext.subkey is present) then - save cleartext.subkey for future use; - endif - if (cleartext.seq-number is present) then - save cleartext.seq-number for future verifications; - endif - return(AUTHENTICATION_SUCCEEDED); - -A.13. KRB_SAFE generation - collect user data in buffer; - - /* assemble packet: */ - packet.pvno := protocol version; /* 5 */ - packet.msg-type := message type; /* KRB_SAFE */ - - - -Kohl & Neuman [Page 107] - -RFC 1510 Kerberos September 1993 - - - body.user-data := buffer; /* DATA */ - if (using timestamp) then - get system_time; - body.timestamp, body.usec := system_time; - endif - if (using sequence numbers) then - body.seq-number := sequence number; - endif - body.s-address := sender host addresses; - if (only one recipient) then - body.r-address := recipient host address; - endif - checksum.cksumtype := checksum type; - compute checksum over body; - checksum.checksum := checksum value; /* checksum.checksum */ - packet.cksum := checksum; - packet.safe-body := body; - -A.14. KRB_SAFE verification - receive packet; - if (packet.pvno != 5) then - either process using other protocol spec - or error_out(KRB_AP_ERR_BADVERSION); - endif - if (packet.msg-type != KRB_SAFE) then - error_out(KRB_AP_ERR_MSG_TYPE); - endif - if (packet.checksum.cksumtype is not both collision-proof - and keyed) then - error_out(KRB_AP_ERR_INAPP_CKSUM); - endif - if (safe_priv_common_checks_ok(packet)) then - set computed_checksum := checksum(packet.body); - if (computed_checksum != packet.checksum) then - error_out(KRB_AP_ERR_MODIFIED); - endif - return (packet, PACKET_IS_GENUINE); - else - return common_checks_error; - endif - -A.15. KRB_SAFE and KRB_PRIV common checks - if (packet.s-address != O/S_sender(packet)) then - /* O/S report of sender not who claims to have sent it */ - error_out(KRB_AP_ERR_BADADDR); - endif - if ((packet.r-address is present) and - (packet.r-address != local_host_address)) then - - - -Kohl & Neuman [Page 108] - -RFC 1510 Kerberos September 1993 - - - /* was not sent to proper place */ - error_out(KRB_AP_ERR_BADADDR); - endif - if (((packet.timestamp is present) and - (not in_clock_skew(packet.timestamp,packet.usec))) or - (packet.timestamp is not present and timestamp expected)) - then error_out(KRB_AP_ERR_SKEW); - endif - if (repeated(packet.timestamp,packet.usec,packet.s-address)) - then error_out(KRB_AP_ERR_REPEAT); - endif - if (((packet.seq-number is present) and - ((not in_sequence(packet.seq-number)))) or - (packet.seq-number is not present and sequence expected)) - then error_out(KRB_AP_ERR_BADORDER); - endif - if (packet.timestamp not present and - packet.seq-number not present) then - error_out(KRB_AP_ERR_MODIFIED); - endif - - save_identifier(packet.{timestamp,usec,s-address}, - sender_principal(packet)); - - return PACKET_IS_OK; - -A.16. KRB_PRIV generation - collect user data in buffer; - - /* assemble packet: */ - packet.pvno := protocol version; /* 5 */ - packet.msg-type := message type; /* KRB_PRIV */ - - packet.enc-part.etype := encryption type; - - body.user-data := buffer; - if (using timestamp) then - get system_time; - body.timestamp, body.usec := system_time; - endif - if (using sequence numbers) then - body.seq-number := sequence number; - endif - body.s-address := sender host addresses; - if (only one recipient) then - body.r-address := recipient host address; - endif - - - - -Kohl & Neuman [Page 109] - -RFC 1510 Kerberos September 1993 - - - encode body into OCTET STRING; - - select encryption type; - encrypt OCTET STRING into packet.enc-part.cipher; - -A.17. KRB_PRIV verification - receive packet; - if (packet.pvno != 5) then - either process using other protocol spec - or error_out(KRB_AP_ERR_BADVERSION); - endif - if (packet.msg-type != KRB_PRIV) then - error_out(KRB_AP_ERR_MSG_TYPE); - endif - - cleartext := decrypt(packet.enc-part) using negotiated key; - if (decryption_error()) then - error_out(KRB_AP_ERR_BAD_INTEGRITY); - endif - - if (safe_priv_common_checks_ok(cleartext)) then - return(cleartext.DATA, PACKET_IS_GENUINE_AND_UNMODIFIED); - else - return common_checks_error; - endif - -A.18. KRB_CRED generation - invoke KRB_TGS; /* obtain tickets to be provided to peer */ - - /* assemble packet: */ - packet.pvno := protocol version; /* 5 */ - packet.msg-type := message type; /* KRB_CRED */ - - for (tickets[n] in tickets to be forwarded) do - packet.tickets[n] = tickets[n].ticket; - done - - packet.enc-part.etype := encryption type; - - for (ticket[n] in tickets to be forwarded) do - body.ticket-info[n].key = tickets[n].session; - body.ticket-info[n].prealm = tickets[n].crealm; - body.ticket-info[n].pname = tickets[n].cname; - body.ticket-info[n].flags = tickets[n].flags; - body.ticket-info[n].authtime = tickets[n].authtime; - body.ticket-info[n].starttime = tickets[n].starttime; - body.ticket-info[n].endtime = tickets[n].endtime; - body.ticket-info[n].renew-till = tickets[n].renew-till; - - - -Kohl & Neuman [Page 110] - -RFC 1510 Kerberos September 1993 - - - body.ticket-info[n].srealm = tickets[n].srealm; - body.ticket-info[n].sname = tickets[n].sname; - body.ticket-info[n].caddr = tickets[n].caddr; - done - - get system_time; - body.timestamp, body.usec := system_time; - - if (using nonce) then - body.nonce := nonce; - endif - - if (using s-address) then - body.s-address := sender host addresses; - endif - if (limited recipients) then - body.r-address := recipient host address; - endif - - encode body into OCTET STRING; - - select encryption type; - encrypt OCTET STRING into packet.enc-part.cipher - using negotiated encryption key; - -A.19. KRB_CRED verification - receive packet; - if (packet.pvno != 5) then - either process using other protocol spec - or error_out(KRB_AP_ERR_BADVERSION); - endif - if (packet.msg-type != KRB_CRED) then - error_out(KRB_AP_ERR_MSG_TYPE); - endif - - cleartext := decrypt(packet.enc-part) using negotiated key; - if (decryption_error()) then - error_out(KRB_AP_ERR_BAD_INTEGRITY); - endif - if ((packet.r-address is present or required) and - (packet.s-address != O/S_sender(packet)) then - /* O/S report of sender not who claims to have sent it */ - error_out(KRB_AP_ERR_BADADDR); - endif - if ((packet.r-address is present) and - (packet.r-address != local_host_address)) then - /* was not sent to proper place */ - error_out(KRB_AP_ERR_BADADDR); - - - -Kohl & Neuman [Page 111] - -RFC 1510 Kerberos September 1993 - - - endif - if (not in_clock_skew(packet.timestamp,packet.usec)) then - error_out(KRB_AP_ERR_SKEW); - endif - if (repeated(packet.timestamp,packet.usec,packet.s-address)) - then error_out(KRB_AP_ERR_REPEAT); - endif - if (packet.nonce is required or present) and - (packet.nonce != expected-nonce) then - error_out(KRB_AP_ERR_MODIFIED); - endif - - for (ticket[n] in tickets that were forwarded) do - save_for_later(ticket[n],key[n],principal[n], - server[n],times[n],flags[n]); - return - -A.20. KRB_ERROR generation - - /* assemble packet: */ - packet.pvno := protocol version; /* 5 */ - packet.msg-type := message type; /* KRB_ERROR */ - - get system_time; - packet.stime, packet.susec := system_time; - packet.realm, packet.sname := server name; - - if (client time available) then - packet.ctime, packet.cusec := client_time; - endif - packet.error-code := error code; - if (client name available) then - packet.cname, packet.crealm := client name; - endif - if (error text available) then - packet.e-text := error text; - endif - if (error data available) then - packet.e-data := error data; - endif - - - - - - - - - - - -Kohl & Neuman [Page 112] - \ No newline at end of file diff --git a/doc/rfc1750.txt b/doc/rfc1750.txt deleted file mode 100644 index 56d478c7e..000000000 --- a/doc/rfc1750.txt +++ /dev/null @@ -1,1683 +0,0 @@ - - - - - - -Network Working Group D. Eastlake, 3rd -Request for Comments: 1750 DEC -Category: Informational S. Crocker - Cybercash - J. Schiller - MIT - December 1994 - - - Randomness Recommendations for Security - -Status of this Memo - - This memo provides information for the Internet community. This memo - does not specify an Internet standard of any kind. Distribution of - this memo is unlimited. - -Abstract - - Security systems today are built on increasingly strong cryptographic - algorithms that foil pattern analysis attempts. However, the security - of these systems is dependent on generating secret quantities for - passwords, cryptographic keys, and similar quantities. The use of - pseudo-random processes to generate secret quantities can result in - pseudo-security. The sophisticated attacker of these security - systems may find it easier to reproduce the environment that produced - the secret quantities, searching the resulting small set of - possibilities, than to locate the quantities in the whole of the - number space. - - Choosing random quantities to foil a resourceful and motivated - adversary is surprisingly difficult. This paper points out many - pitfalls in using traditional pseudo-random number generation - techniques for choosing such quantities. It recommends the use of - truly random hardware techniques and shows that the existing hardware - on many systems can be used for this purpose. It provides - suggestions to ameliorate the problem when a hardware solution is not - available. And it gives examples of how large such quantities need - to be for some particular applications. - - - - - - - - - - - - -Eastlake, Crocker & Schiller [Page 1] - -RFC 1750 Randomness Recommendations for Security December 1994 - - -Acknowledgements - - Comments on this document that have been incorporated were received - from (in alphabetic order) the following: - - David M. Balenson (TIS) - Don Coppersmith (IBM) - Don T. Davis (consultant) - Carl Ellison (Stratus) - Marc Horowitz (MIT) - Christian Huitema (INRIA) - Charlie Kaufman (IRIS) - Steve Kent (BBN) - Hal Murray (DEC) - Neil Haller (Bellcore) - Richard Pitkin (DEC) - Tim Redmond (TIS) - Doug Tygar (CMU) - -Table of Contents - - 1. Introduction........................................... 3 - 2. Requirements........................................... 4 - 3. Traditional Pseudo-Random Sequences.................... 5 - 4. Unpredictability....................................... 7 - 4.1 Problems with Clocks and Serial Numbers............... 7 - 4.2 Timing and Content of External Events................ 8 - 4.3 The Fallacy of Complex Manipulation.................. 8 - 4.4 The Fallacy of Selection from a Large Database....... 9 - 5. Hardware for Randomness............................... 10 - 5.1 Volume Required...................................... 10 - 5.2 Sensitivity to Skew.................................. 10 - 5.2.1 Using Stream Parity to De-Skew..................... 11 - 5.2.2 Using Transition Mappings to De-Skew............... 12 - 5.2.3 Using FFT to De-Skew............................... 13 - 5.2.4 Using Compression to De-Skew....................... 13 - 5.3 Existing Hardware Can Be Used For Randomness......... 14 - 5.3.1 Using Existing Sound/Video Input................... 14 - 5.3.2 Using Existing Disk Drives......................... 14 - 6. Recommended Non-Hardware Strategy..................... 14 - 6.1 Mixing Functions..................................... 15 - 6.1.1 A Trivial Mixing Function.......................... 15 - 6.1.2 Stronger Mixing Functions.......................... 16 - 6.1.3 Diff-Hellman as a Mixing Function.................. 17 - 6.1.4 Using a Mixing Function to Stretch Random Bits..... 17 - 6.1.5 Other Factors in Choosing a Mixing Function........ 18 - 6.2 Non-Hardware Sources of Randomness................... 19 - 6.3 Cryptographically Strong Sequences................... 19 - - - -Eastlake, Crocker & Schiller [Page 2] - -RFC 1750 Randomness Recommendations for Security December 1994 - - - 6.3.1 Traditional Strong Sequences....................... 20 - 6.3.2 The Blum Blum Shub Sequence Generator.............. 21 - 7. Key Generation Standards.............................. 22 - 7.1 US DoD Recommendations for Password Generation....... 23 - 7.2 X9.17 Key Generation................................. 23 - 8. Examples of Randomness Required....................... 24 - 8.1 Password Generation................................. 24 - 8.2 A Very High Security Cryptographic Key............... 25 - 8.2.1 Effort per Key Trial............................... 25 - 8.2.2 Meet in the Middle Attacks......................... 26 - 8.2.3 Other Considerations............................... 26 - 9. Conclusion............................................ 27 - 10. Security Considerations.............................. 27 - References............................................... 28 - Authors' Addresses....................................... 30 - -1. Introduction - - Software cryptography is coming into wider use. Systems like - Kerberos, PEM, PGP, etc. are maturing and becoming a part of the - network landscape [PEM]. These systems provide substantial - protection against snooping and spoofing. However, there is a - potential flaw. At the heart of all cryptographic systems is the - generation of secret, unguessable (i.e., random) numbers. - - For the present, the lack of generally available facilities for - generating such unpredictable numbers is an open wound in the design - of cryptographic software. For the software developer who wants to - build a key or password generation procedure that runs on a wide - range of hardware, the only safe strategy so far has been to force - the local installation to supply a suitable routine to generate - random numbers. To say the least, this is an awkward, error-prone - and unpalatable solution. - - It is important to keep in mind that the requirement is for data that - an adversary has a very low probability of guessing or determining. - This will fail if pseudo-random data is used which only meets - traditional statistical tests for randomness or which is based on - limited range sources, such as clocks. Frequently such random - quantities are determinable by an adversary searching through an - embarrassingly small space of possibilities. - - This informational document suggests techniques for producing random - quantities that will be resistant to such attack. It recommends that - future systems include hardware random number generation or provide - access to existing hardware that can be used for this purpose. It - suggests methods for use if such hardware is not available. And it - gives some estimates of the number of random bits required for sample - - - -Eastlake, Crocker & Schiller [Page 3] - -RFC 1750 Randomness Recommendations for Security December 1994 - - - applications. - -2. Requirements - - Probably the most commonly encountered randomness requirement today - is the user password. This is usually a simple character string. - Obviously, if a password can be guessed, it does not provide - security. (For re-usable passwords, it is desirable that users be - able to remember the password. This may make it advisable to use - pronounceable character strings or phrases composed on ordinary - words. But this only affects the format of the password information, - not the requirement that the password be very hard to guess.) - - Many other requirements come from the cryptographic arena. - Cryptographic techniques can be used to provide a variety of services - including confidentiality and authentication. Such services are - based on quantities, traditionally called "keys", that are unknown to - and unguessable by an adversary. - - In some cases, such as the use of symmetric encryption with the one - time pads [CRYPTO*] or the US Data Encryption Standard [DES], the - parties who wish to communicate confidentially and/or with - authentication must all know the same secret key. In other cases, - using what are called asymmetric or "public key" cryptographic - techniques, keys come in pairs. One key of the pair is private and - must be kept secret by one party, the other is public and can be - published to the world. It is computationally infeasible to - determine the private key from the public key [ASYMMETRIC, CRYPTO*]. - - The frequency and volume of the requirement for random quantities - differs greatly for different cryptographic systems. Using pure RSA - [CRYPTO*], random quantities are required when the key pair is - generated, but thereafter any number of messages can be signed - without any further need for randomness. The public key Digital - Signature Algorithm that has been proposed by the US National - Institute of Standards and Technology (NIST) requires good random - numbers for each signature. And encrypting with a one time pad, in - principle the strongest possible encryption technique, requires a - volume of randomness equal to all the messages to be processed. - - In most of these cases, an adversary can try to determine the - "secret" key by trial and error. (This is possible as long as the - key is enough smaller than the message that the correct key can be - uniquely identified.) The probability of an adversary succeeding at - this must be made acceptably low, depending on the particular - application. The size of the space the adversary must search is - related to the amount of key "information" present in the information - theoretic sense [SHANNON]. This depends on the number of different - - - -Eastlake, Crocker & Schiller [Page 4] - -RFC 1750 Randomness Recommendations for Security December 1994 - - - secret values possible and the probability of each value as follows: - - ----- - \ - Bits-of-info = \ - p * log ( p ) - / i 2 i - / - ----- - - where i varies from 1 to the number of possible secret values and p - sub i is the probability of the value numbered i. (Since p sub i is - less than one, the log will be negative so each term in the sum will - be non-negative.) - - If there are 2^n different values of equal probability, then n bits - of information are present and an adversary would, on the average, - have to try half of the values, or 2^(n-1) , before guessing the - secret quantity. If the probability of different values is unequal, - then there is less information present and fewer guesses will, on - average, be required by an adversary. In particular, any values that - the adversary can know are impossible, or are of low probability, can - be initially ignored by an adversary, who will search through the - more probable values first. - - For example, consider a cryptographic system that uses 56 bit keys. - If these 56 bit keys are derived by using a fixed pseudo-random - number generator that is seeded with an 8 bit seed, then an adversary - needs to search through only 256 keys (by running the pseudo-random - number generator with every possible seed), not the 2^56 keys that - may at first appear to be the case. Only 8 bits of "information" are - in these 56 bit keys. - -3. Traditional Pseudo-Random Sequences - - Most traditional sources of random numbers use deterministic sources - of "pseudo-random" numbers. These typically start with a "seed" - quantity and use numeric or logical operations to produce a sequence - of values. - - [KNUTH] has a classic exposition on pseudo-random numbers. - Applications he mentions are simulation of natural phenomena, - sampling, numerical analysis, testing computer programs, decision - making, and games. None of these have the same characteristics as - the sort of security uses we are talking about. Only in the last two - could there be an adversary trying to find the random quantity. - However, in these cases, the adversary normally has only a single - chance to use a guessed value. In guessing passwords or attempting - to break an encryption scheme, the adversary normally has many, - - - -Eastlake, Crocker & Schiller [Page 5] - -RFC 1750 Randomness Recommendations for Security December 1994 - - - perhaps unlimited, chances at guessing the correct value and should - be assumed to be aided by a computer. - - For testing the "randomness" of numbers, Knuth suggests a variety of - measures including statistical and spectral. These tests check - things like autocorrelation between different parts of a "random" - sequence or distribution of its values. They could be met by a - constant stored random sequence, such as the "random" sequence - printed in the CRC Standard Mathematical Tables [CRC]. - - A typical pseudo-random number generation technique, known as a - linear congruence pseudo-random number generator, is modular - arithmetic where the N+1th value is calculated from the Nth value by - - V = ( V * a + b )(Mod c) - N+1 N - - The above technique has a strong relationship to linear shift - register pseudo-random number generators, which are well understood - cryptographically [SHIFT*]. In such generators bits are introduced - at one end of a shift register as the Exclusive Or (binary sum - without carry) of bits from selected fixed taps into the register. - - For example: - - +----+ +----+ +----+ +----+ - | B | <-- | B | <-- | B | <-- . . . . . . <-- | B | <-+ - | 0 | | 1 | | 2 | | n | | - +----+ +----+ +----+ +----+ | - | | | | - | | V +-----+ - | V +----------------> | | - V +-----------------------------> | XOR | - +---------------------------------------------------> | | - +-----+ - - - V = ( ( V * 2 ) + B .xor. B ... )(Mod 2^n) - N+1 N 0 2 - - The goodness of traditional pseudo-random number generator algorithms - is measured by statistical tests on such sequences. Carefully chosen - values of the initial V and a, b, and c or the placement of shift - register tap in the above simple processes can produce excellent - statistics. - - - - - - -Eastlake, Crocker & Schiller [Page 6] - -RFC 1750 Randomness Recommendations for Security December 1994 - - - These sequences may be adequate in simulations (Monte Carlo - experiments) as long as the sequence is orthogonal to the structure - of the space being explored. Even there, subtle patterns may cause - problems. However, such sequences are clearly bad for use in - security applications. They are fully predictable if the initial - state is known. Depending on the form of the pseudo-random number - generator, the sequence may be determinable from observation of a - short portion of the sequence [CRYPTO*, STERN]. For example, with - the generators above, one can determine V(n+1) given knowledge of - V(n). In fact, it has been shown that with these techniques, even if - only one bit of the pseudo-random values is released, the seed can be - determined from short sequences. - - Not only have linear congruent generators been broken, but techniques - are now known for breaking all polynomial congruent generators - [KRAWCZYK]. - -4. Unpredictability - - Randomness in the traditional sense described in section 3 is NOT the - same as the unpredictability required for security use. - - For example, use of a widely available constant sequence, such as - that from the CRC tables, is very weak against an adversary. Once - they learn of or guess it, they can easily break all security, future - and past, based on the sequence [CRC]. Yet the statistical - properties of these tables are good. - - The following sections describe the limitations of some randomness - generation techniques and sources. - -4.1 Problems with Clocks and Serial Numbers - - Computer clocks, or similar operating system or hardware values, - provide significantly fewer real bits of unpredictability than might - appear from their specifications. - - Tests have been done on clocks on numerous systems and it was found - that their behavior can vary widely and in unexpected ways. One - version of an operating system running on one set of hardware may - actually provide, say, microsecond resolution in a clock while a - different configuration of the "same" system may always provide the - same lower bits and only count in the upper bits at much lower - resolution. This means that successive reads on the clock may - produce identical values even if enough time has passed that the - value "should" change based on the nominal clock resolution. There - are also cases where frequently reading a clock can produce - artificial sequential values because of extra code that checks for - - - -Eastlake, Crocker & Schiller [Page 7] - -RFC 1750 Randomness Recommendations for Security December 1994 - - - the clock being unchanged between two reads and increases it by one! - Designing portable application code to generate unpredictable numbers - based on such system clocks is particularly challenging because the - system designer does not always know the properties of the system - clocks that the code will execute on. - - Use of a hardware serial number such as an Ethernet address may also - provide fewer bits of uniqueness than one would guess. Such - quantities are usually heavily structured and subfields may have only - a limited range of possible values or values easily guessable based - on approximate date of manufacture or other data. For example, it is - likely that most of the Ethernet cards installed on Digital Equipment - Corporation (DEC) hardware within DEC were manufactured by DEC - itself, which significantly limits the range of built in addresses. - - Problems such as those described above related to clocks and serial - numbers make code to produce unpredictable quantities difficult if - the code is to be ported across a variety of computer platforms and - systems. - -4.2 Timing and Content of External Events - - It is possible to measure the timing and content of mouse movement, - key strokes, and similar user events. This is a reasonable source of - unguessable data with some qualifications. On some machines, inputs - such as key strokes are buffered. Even though the user's inter- - keystroke timing may have sufficient variation and unpredictability, - there might not be an easy way to access that variation. Another - problem is that no standard method exists to sample timing details. - This makes it hard to build standard software intended for - distribution to a large range of machines based on this technique. - - The amount of mouse movement or the keys actually hit are usually - easier to access than timings but may yield less unpredictability as - the user may provide highly repetitive input. - - Other external events, such as network packet arrival times, can also - be used with care. In particular, the possibility of manipulation of - such times by an adversary must be considered. - -4.3 The Fallacy of Complex Manipulation - - One strategy which may give a misleading appearance of - unpredictability is to take a very complex algorithm (or an excellent - traditional pseudo-random number generator with good statistical - properties) and calculate a cryptographic key by starting with the - current value of a computer system clock as the seed. An adversary - who knew roughly when the generator was started would have a - - - -Eastlake, Crocker & Schiller [Page 8] - -RFC 1750 Randomness Recommendations for Security December 1994 - - - relatively small number of seed values to test as they would know - likely values of the system clock. Large numbers of pseudo-random - bits could be generated but the search space an adversary would need - to check could be quite small. - - Thus very strong and/or complex manipulation of data will not help if - the adversary can learn what the manipulation is and there is not - enough unpredictability in the starting seed value. Even if they can - not learn what the manipulation is, they may be able to use the - limited number of results stemming from a limited number of seed - values to defeat security. - - Another serious strategy error is to assume that a very complex - pseudo-random number generation algorithm will produce strong random - numbers when there has been no theory behind or analysis of the - algorithm. There is a excellent example of this fallacy right near - the beginning of chapter 3 in [KNUTH] where the author describes a - complex algorithm. It was intended that the machine language program - corresponding to the algorithm would be so complicated that a person - trying to read the code without comments wouldn't know what the - program was doing. Unfortunately, actual use of this algorithm - showed that it almost immediately converged to a single repeated - value in one case and a small cycle of values in another case. - - Not only does complex manipulation not help you if you have a limited - range of seeds but blindly chosen complex manipulation can destroy - the randomness in a good seed! - -4.4 The Fallacy of Selection from a Large Database - - Another strategy that can give a misleading appearance of - unpredictability is selection of a quantity randomly from a database - and assume that its strength is related to the total number of bits - in the database. For example, typical USENET servers as of this date - process over 35 megabytes of information per day. Assume a random - quantity was selected by fetching 32 bytes of data from a random - starting point in this data. This does not yield 32*8 = 256 bits - worth of unguessability. Even after allowing that much of the data - is human language and probably has more like 2 or 3 bits of - information per byte, it doesn't yield 32*2.5 = 80 bits of - unguessability. For an adversary with access to the same 35 - megabytes the unguessability rests only on the starting point of the - selection. That is, at best, about 25 bits of unguessability in this - case. - - The same argument applies to selecting sequences from the data on a - CD ROM or Audio CD recording or any other large public database. If - the adversary has access to the same database, this "selection from a - - - -Eastlake, Crocker & Schiller [Page 9] - -RFC 1750 Randomness Recommendations for Security December 1994 - - - large volume of data" step buys very little. However, if a selection - can be made from data to which the adversary has no access, such as - system buffers on an active multi-user system, it may be of some - help. - -5. Hardware for Randomness - - Is there any hope for strong portable randomness in the future? - There might be. All that's needed is a physical source of - unpredictable numbers. - - A thermal noise or radioactive decay source and a fast, free-running - oscillator would do the trick directly [GIFFORD]. This is a trivial - amount of hardware, and could easily be included as a standard part - of a computer system's architecture. Furthermore, any system with a - spinning disk or the like has an adequate source of randomness - [DAVIS]. All that's needed is the common perception among computer - vendors that this small additional hardware and the software to - access it is necessary and useful. - -5.1 Volume Required - - How much unpredictability is needed? Is it possible to quantify the - requirement in, say, number of random bits per second? - - The answer is not very much is needed. For DES, the key is 56 bits - and, as we show in an example in Section 8, even the highest security - system is unlikely to require a keying material of over 200 bits. If - a series of keys are needed, it can be generated from a strong random - seed using a cryptographically strong sequence as explained in - Section 6.3. A few hundred random bits generated once a day would be - enough using such techniques. Even if the random bits are generated - as slowly as one per second and it is not possible to overlap the - generation process, it should be tolerable in high security - applications to wait 200 seconds occasionally. - - These numbers are trivial to achieve. It could be done by a person - repeatedly tossing a coin. Almost any hardware process is likely to - be much faster. - -5.2 Sensitivity to Skew - - Is there any specific requirement on the shape of the distribution of - the random numbers? The good news is the distribution need not be - uniform. All that is needed is a conservative estimate of how non- - uniform it is to bound performance. Two simple techniques to de-skew - the bit stream are given below and stronger techniques are mentioned - in Section 6.1.2 below. - - - -Eastlake, Crocker & Schiller [Page 10] - -RFC 1750 Randomness Recommendations for Security December 1994 - - -5.2.1 Using Stream Parity to De-Skew - - Consider taking a sufficiently long string of bits and map the string - to "zero" or "one". The mapping will not yield a perfectly uniform - distribution, but it can be as close as desired. One mapping that - serves the purpose is to take the parity of the string. This has the - advantages that it is robust across all degrees of skew up to the - estimated maximum skew and is absolutely trivial to implement in - hardware. - - The following analysis gives the number of bits that must be sampled: - - Suppose the ratio of ones to zeros is 0.5 + e : 0.5 - e, where e is - between 0 and 0.5 and is a measure of the "eccentricity" of the - distribution. Consider the distribution of the parity function of N - bit samples. The probabilities that the parity will be one or zero - will be the sum of the odd or even terms in the binomial expansion of - (p + q)^N, where p = 0.5 + e, the probability of a one, and q = 0.5 - - e, the probability of a zero. - - These sums can be computed easily as - - N N - 1/2 * ( ( p + q ) + ( p - q ) ) - and - N N - 1/2 * ( ( p + q ) - ( p - q ) ). - - (Which one corresponds to the probability the parity will be 1 - depends on whether N is odd or even.) - - Since p + q = 1 and p - q = 2e, these expressions reduce to - - N - 1/2 * [1 + (2e) ] - and - N - 1/2 * [1 - (2e) ]. - - Neither of these will ever be exactly 0.5 unless e is zero, but we - can bring them arbitrarily close to 0.5. If we want the - probabilities to be within some delta d of 0.5, i.e. then - - N - ( 0.5 + ( 0.5 * (2e) ) ) < 0.5 + d. - - - - - - -Eastlake, Crocker & Schiller [Page 11] - -RFC 1750 Randomness Recommendations for Security December 1994 - - - Solving for N yields N > log(2d)/log(2e). (Note that 2e is less than - 1, so its log is negative. Division by a negative number reverses - the sense of an inequality.) - - The following table gives the length of the string which must be - sampled for various degrees of skew in order to come within 0.001 of - a 50/50 distribution. - - +---------+--------+-------+ - | Prob(1) | e | N | - +---------+--------+-------+ - | 0.5 | 0.00 | 1 | - | 0.6 | 0.10 | 4 | - | 0.7 | 0.20 | 7 | - | 0.8 | 0.30 | 13 | - | 0.9 | 0.40 | 28 | - | 0.95 | 0.45 | 59 | - | 0.99 | 0.49 | 308 | - +---------+--------+-------+ - - The last entry shows that even if the distribution is skewed 99% in - favor of ones, the parity of a string of 308 samples will be within - 0.001 of a 50/50 distribution. - -5.2.2 Using Transition Mappings to De-Skew - - Another technique, originally due to von Neumann [VON NEUMANN], is to - examine a bit stream as a sequence of non-overlapping pairs. You - could then discard any 00 or 11 pairs found, interpret 01 as a 0 and - 10 as a 1. Assume the probability of a 1 is 0.5+e and the - probability of a 0 is 0.5-e where e is the eccentricity of the source - and described in the previous section. Then the probability of each - pair is as follows: - - +------+-----------------------------------------+ - | pair | probability | - +------+-----------------------------------------+ - | 00 | (0.5 - e)^2 = 0.25 - e + e^2 | - | 01 | (0.5 - e)*(0.5 + e) = 0.25 - e^2 | - | 10 | (0.5 + e)*(0.5 - e) = 0.25 - e^2 | - | 11 | (0.5 + e)^2 = 0.25 + e + e^2 | - +------+-----------------------------------------+ - - This technique will completely eliminate any bias but at the expense - of taking an indeterminate number of input bits for any particular - desired number of output bits. The probability of any particular - pair being discarded is 0.5 + 2e^2 so the expected number of input - bits to produce X output bits is X/(0.25 - e^2). - - - -Eastlake, Crocker & Schiller [Page 12] - -RFC 1750 Randomness Recommendations for Security December 1994 - - - This technique assumes that the bits are from a stream where each bit - has the same probability of being a 0 or 1 as any other bit in the - stream and that bits are not correlated, i.e., that the bits are - identical independent distributions. If alternate bits were from two - correlated sources, for example, the above analysis breaks down. - - The above technique also provides another illustration of how a - simple statistical analysis can mislead if one is not always on the - lookout for patterns that could be exploited by an adversary. If the - algorithm were mis-read slightly so that overlapping successive bits - pairs were used instead of non-overlapping pairs, the statistical - analysis given is the same; however, instead of provided an unbiased - uncorrelated series of random 1's and 0's, it instead produces a - totally predictable sequence of exactly alternating 1's and 0's. - -5.2.3 Using FFT to De-Skew - - When real world data consists of strongly biased or correlated bits, - it may still contain useful amounts of randomness. This randomness - can be extracted through use of the discrete Fourier transform or its - optimized variant, the FFT. - - Using the Fourier transform of the data, strong correlations can be - discarded. If adequate data is processed and remaining correlations - decay, spectral lines approaching statistical independence and - normally distributed randomness can be produced [BRILLINGER]. - -5.2.4 Using Compression to De-Skew - - Reversible compression techniques also provide a crude method of de- - skewing a skewed bit stream. This follows directly from the - definition of reversible compression and the formula in Section 2 - above for the amount of information in a sequence. Since the - compression is reversible, the same amount of information must be - present in the shorter output than was present in the longer input. - By the Shannon information equation, this is only possible if, on - average, the probabilities of the different shorter sequences are - more uniformly distributed than were the probabilities of the longer - sequences. Thus the shorter sequences are de-skewed relative to the - input. - - However, many compression techniques add a somewhat predicatable - preface to their output stream and may insert such a sequence again - periodically in their output or otherwise introduce subtle patterns - of their own. They should be considered only a rough technique - compared with those described above or in Section 6.1.2. At a - minimum, the beginning of the compressed sequence should be skipped - and only later bits used for applications requiring random bits. - - - -Eastlake, Crocker & Schiller [Page 13] - -RFC 1750 Randomness Recommendations for Security December 1994 - - -5.3 Existing Hardware Can Be Used For Randomness - - As described below, many computers come with hardware that can, with - care, be used to generate truly random quantities. - -5.3.1 Using Existing Sound/Video Input - - Increasingly computers are being built with inputs that digitize some - real world analog source, such as sound from a microphone or video - input from a camera. Under appropriate circumstances, such input can - provide reasonably high quality random bits. The "input" from a - sound digitizer with no source plugged in or a camera with the lens - cap on, if the system has enough gain to detect anything, is - essentially thermal noise. - - For example, on a SPARCstation, one can read from the /dev/audio - device with nothing plugged into the microphone jack. Such data is - essentially random noise although it should not be trusted without - some checking in case of hardware failure. It will, in any case, - need to be de-skewed as described elsewhere. - - Combining this with compression to de-skew one can, in UNIXese, - generate a huge amount of medium quality random data by doing - - cat /dev/audio | compress - >random-bits-file - -5.3.2 Using Existing Disk Drives - - Disk drives have small random fluctuations in their rotational speed - due to chaotic air turbulence [DAVIS]. By adding low level disk seek - time instrumentation to a system, a series of measurements can be - obtained that include this randomness. Such data is usually highly - correlated so that significant processing is needed, including FFT - (see section 5.2.3). Nevertheless experimentation has shown that, - with such processing, disk drives easily produce 100 bits a minute or - more of excellent random data. - - Partly offsetting this need for processing is the fact that disk - drive failure will normally be rapidly noticed. Thus, problems with - this method of random number generation due to hardware failure are - very unlikely. - -6. Recommended Non-Hardware Strategy - - What is the best overall strategy for meeting the requirement for - unguessable random numbers in the absence of a reliable hardware - source? It is to obtain random input from a large number of - uncorrelated sources and to mix them with a strong mixing function. - - - -Eastlake, Crocker & Schiller [Page 14] - -RFC 1750 Randomness Recommendations for Security December 1994 - - - Such a function will preserve the randomness present in any of the - sources even if other quantities being combined are fixed or easily - guessable. This may be advisable even with a good hardware source as - hardware can also fail, though this should be weighed against any - increase in the chance of overall failure due to added software - complexity. - -6.1 Mixing Functions - - A strong mixing function is one which combines two or more inputs and - produces an output where each output bit is a different complex non- - linear function of all the input bits. On average, changing any - input bit will change about half the output bits. But because the - relationship is complex and non-linear, no particular output bit is - guaranteed to change when any particular input bit is changed. - - Consider the problem of converting a stream of bits that is skewed - towards 0 or 1 to a shorter stream which is more random, as discussed - in Section 5.2 above. This is simply another case where a strong - mixing function is desired, mixing the input bits to produce a - smaller number of output bits. The technique given in Section 5.2.1 - of using the parity of a number of bits is simply the result of - successively Exclusive Or'ing them which is examined as a trivial - mixing function immediately below. Use of stronger mixing functions - to extract more of the randomness in a stream of skewed bits is - examined in Section 6.1.2. - -6.1.1 A Trivial Mixing Function - - A trivial example for single bit inputs is the Exclusive Or function, - which is equivalent to addition without carry, as show in the table - below. This is a degenerate case in which the one output bit always - changes for a change in either input bit. But, despite its - simplicity, it will still provide a useful illustration. - - +-----------+-----------+----------+ - | input 1 | input 2 | output | - +-----------+-----------+----------+ - | 0 | 0 | 0 | - | 0 | 1 | 1 | - | 1 | 0 | 1 | - | 1 | 1 | 0 | - +-----------+-----------+----------+ - - If inputs 1 and 2 are uncorrelated and combined in this fashion then - the output will be an even better (less skewed) random bit than the - inputs. If we assume an "eccentricity" e as defined in Section 5.2 - above, then the output eccentricity relates to the input eccentricity - - - -Eastlake, Crocker & Schiller [Page 15] - -RFC 1750 Randomness Recommendations for Security December 1994 - - - as follows: - - e = 2 * e * e - output input 1 input 2 - - Since e is never greater than 1/2, the eccentricity is always - improved except in the case where at least one input is a totally - skewed constant. This is illustrated in the following table where - the top and left side values are the two input eccentricities and the - entries are the output eccentricity: - - +--------+--------+--------+--------+--------+--------+--------+ - | e | 0.00 | 0.10 | 0.20 | 0.30 | 0.40 | 0.50 | - +--------+--------+--------+--------+--------+--------+--------+ - | 0.00 | 0.00 | 0.00 | 0.00 | 0.00 | 0.00 | 0.00 | - | 0.10 | 0.00 | 0.02 | 0.04 | 0.06 | 0.08 | 0.10 | - | 0.20 | 0.00 | 0.04 | 0.08 | 0.12 | 0.16 | 0.20 | - | 0.30 | 0.00 | 0.06 | 0.12 | 0.18 | 0.24 | 0.30 | - | 0.40 | 0.00 | 0.08 | 0.16 | 0.24 | 0.32 | 0.40 | - | 0.50 | 0.00 | 0.10 | 0.20 | 0.30 | 0.40 | 0.50 | - +--------+--------+--------+--------+--------+--------+--------+ - - However, keep in mind that the above calculations assume that the - inputs are not correlated. If the inputs were, say, the parity of - the number of minutes from midnight on two clocks accurate to a few - seconds, then each might appear random if sampled at random intervals - much longer than a minute. Yet if they were both sampled and - combined with xor, the result would be zero most of the time. - -6.1.2 Stronger Mixing Functions - - The US Government Data Encryption Standard [DES] is an example of a - strong mixing function for multiple bit quantities. It takes up to - 120 bits of input (64 bits of "data" and 56 bits of "key") and - produces 64 bits of output each of which is dependent on a complex - non-linear function of all input bits. Other strong encryption - functions with this characteristic can also be used by considering - them to mix all of their key and data input bits. - - Another good family of mixing functions are the "message digest" or - hashing functions such as The US Government Secure Hash Standard - [SHS] and the MD2, MD4, MD5 [MD2, MD4, MD5] series. These functions - all take an arbitrary amount of input and produce an output mixing - all the input bits. The MD* series produce 128 bits of output and SHS - produces 160 bits. - - - - - - -Eastlake, Crocker & Schiller [Page 16] - -RFC 1750 Randomness Recommendations for Security December 1994 - - - Although the message digest functions are designed for variable - amounts of input, DES and other encryption functions can also be used - to combine any number of inputs. If 64 bits of output is adequate, - the inputs can be packed into a 64 bit data quantity and successive - 56 bit keys, padding with zeros if needed, which are then used to - successively encrypt using DES in Electronic Codebook Mode [DES - MODES]. If more than 64 bits of output are needed, use more complex - mixing. For example, if inputs are packed into three quantities, A, - B, and C, use DES to encrypt A with B as a key and then with C as a - key to produce the 1st part of the output, then encrypt B with C and - then A for more output and, if necessary, encrypt C with A and then B - for yet more output. Still more output can be produced by reversing - the order of the keys given above to stretch things. The same can be - done with the hash functions by hashing various subsets of the input - data to produce multiple outputs. But keep in mind that it is - impossible to get more bits of "randomness" out than are put in. - - An example of using a strong mixing function would be to reconsider - the case of a string of 308 bits each of which is biased 99% towards - zero. The parity technique given in Section 5.2.1 above reduced this - to one bit with only a 1/1000 deviance from being equally likely a - zero or one. But, applying the equation for information given in - Section 2, this 308 bit sequence has 5 bits of information in it. - Thus hashing it with SHS or MD5 and taking the bottom 5 bits of the - result would yield 5 unbiased random bits as opposed to the single - bit given by calculating the parity of the string. - -6.1.3 Diffie-Hellman as a Mixing Function - - Diffie-Hellman exponential key exchange is a technique that yields a - shared secret between two parties that can be made computationally - infeasible for a third party to determine even if they can observe - all the messages between the two communicating parties. This shared - secret is a mixture of initial quantities generated by each of them - [D-H]. If these initial quantities are random, then the shared - secret contains the combined randomness of them both, assuming they - are uncorrelated. - -6.1.4 Using a Mixing Function to Stretch Random Bits - - While it is not necessary for a mixing function to produce the same - or fewer bits than its inputs, mixing bits cannot "stretch" the - amount of random unpredictability present in the inputs. Thus four - inputs of 32 bits each where there is 12 bits worth of - unpredicatability (such as 4,096 equally probable values) in each - input cannot produce more than 48 bits worth of unpredictable output. - The output can be expanded to hundreds or thousands of bits by, for - example, mixing with successive integers, but the clever adversary's - - - -Eastlake, Crocker & Schiller [Page 17] - -RFC 1750 Randomness Recommendations for Security December 1994 - - - search space is still 2^48 possibilities. Furthermore, mixing to - fewer bits than are input will tend to strengthen the randomness of - the output the way using Exclusive Or to produce one bit from two did - above. - - The last table in Section 6.1.1 shows that mixing a random bit with a - constant bit with Exclusive Or will produce a random bit. While this - is true, it does not provide a way to "stretch" one random bit into - more than one. If, for example, a random bit is mixed with a 0 and - then with a 1, this produces a two bit sequence but it will always be - either 01 or 10. Since there are only two possible values, there is - still only the one bit of original randomness. - -6.1.5 Other Factors in Choosing a Mixing Function - - For local use, DES has the advantages that it has been widely tested - for flaws, is widely documented, and is widely implemented with - hardware and software implementations available all over the world - including source code available by anonymous FTP. The SHS and MD* - family are younger algorithms which have been less tested but there - is no particular reason to believe they are flawed. Both MD5 and SHS - were derived from the earlier MD4 algorithm. They all have source - code available by anonymous FTP [SHS, MD2, MD4, MD5]. - - DES and SHS have been vouched for the the US National Security Agency - (NSA) on the basis of criteria that primarily remain secret. While - this is the cause of much speculation and doubt, investigation of DES - over the years has indicated that NSA involvement in modifications to - its design, which originated with IBM, was primarily to strengthen - it. No concealed or special weakness has been found in DES. It is - almost certain that the NSA modification to MD4 to produce the SHS - similarly strengthened the algorithm, possibly against threats not - yet known in the public cryptographic community. - - DES, SHS, MD4, and MD5 are royalty free for all purposes. MD2 has - been freely licensed only for non-profit use in connection with - Privacy Enhanced Mail [PEM]. Between the MD* algorithms, some people - believe that, as with "Goldilocks and the Three Bears", MD2 is strong - but too slow, MD4 is fast but too weak, and MD5 is just right. - - Another advantage of the MD* or similar hashing algorithms over - encryption algorithms is that they are not subject to the same - regulations imposed by the US Government prohibiting the unlicensed - export or import of encryption/decryption software and hardware. The - same should be true of DES rigged to produce an irreversible hash - code but most DES packages are oriented to reversible encryption. - - - - - -Eastlake, Crocker & Schiller [Page 18] - -RFC 1750 Randomness Recommendations for Security December 1994 - - -6.2 Non-Hardware Sources of Randomness - - The best source of input for mixing would be a hardware randomness - such as disk drive timing affected by air turbulence, audio input - with thermal noise, or radioactive decay. However, if that is not - available there are other possibilities. These include system - clocks, system or input/output buffers, user/system/hardware/network - serial numbers and/or addresses and timing, and user input. - Unfortunately, any of these sources can produce limited or - predicatable values under some circumstances. - - Some of the sources listed above would be quite strong on multi-user - systems where, in essence, each user of the system is a source of - randomness. However, on a small single user system, such as a - typical IBM PC or Apple Macintosh, it might be possible for an - adversary to assemble a similar configuration. This could give the - adversary inputs to the mixing process that were sufficiently - correlated to those used originally as to make exhaustive search - practical. - - The use of multiple random inputs with a strong mixing function is - recommended and can overcome weakness in any particular input. For - example, the timing and content of requested "random" user keystrokes - can yield hundreds of random bits but conservative assumptions need - to be made. For example, assuming a few bits of randomness if the - inter-keystroke interval is unique in the sequence up to that point - and a similar assumption if the key hit is unique but assuming that - no bits of randomness are present in the initial key value or if the - timing or key value duplicate previous values. The results of mixing - these timings and characters typed could be further combined with - clock values and other inputs. - - This strategy may make practical portable code to produce good random - numbers for security even if some of the inputs are very weak on some - of the target systems. However, it may still fail against a high - grade attack on small single user systems, especially if the - adversary has ever been able to observe the generation process in the - past. A hardware based random source is still preferable. - -6.3 Cryptographically Strong Sequences - - In cases where a series of random quantities must be generated, an - adversary may learn some values in the sequence. In general, they - should not be able to predict other values from the ones that they - know. - - - - - - -Eastlake, Crocker & Schiller [Page 19] - -RFC 1750 Randomness Recommendations for Security December 1994 - - - The correct technique is to start with a strong random seed, take - cryptographically strong steps from that seed [CRYPTO2, CRYPTO3], and - do not reveal the complete state of the generator in the sequence - elements. If each value in the sequence can be calculated in a fixed - way from the previous value, then when any value is compromised, all - future values can be determined. This would be the case, for - example, if each value were a constant function of the previously - used values, even if the function were a very strong, non-invertible - message digest function. - - It should be noted that if your technique for generating a sequence - of key values is fast enough, it can trivially be used as the basis - for a confidentiality system. If two parties use the same sequence - generating technique and start with the same seed material, they will - generate identical sequences. These could, for example, be xor'ed at - one end with data being send, encrypting it, and xor'ed with this - data as received, decrypting it due to the reversible properties of - the xor operation. - -6.3.1 Traditional Strong Sequences - - A traditional way to achieve a strong sequence has been to have the - values be produced by hashing the quantities produced by - concatenating the seed with successive integers or the like and then - mask the values obtained so as to limit the amount of generator state - available to the adversary. - - It may also be possible to use an "encryption" algorithm with a - random key and seed value to encrypt and feedback some or all of the - output encrypted value into the value to be encrypted for the next - iteration. Appropriate feedback techniques will usually be - recommended with the encryption algorithm. An example is shown below - where shifting and masking are used to combine the cypher output - feedback. This type of feedback is recommended by the US Government - in connection with DES [DES MODES]. - - - - - - - - - - - - - - - - -Eastlake, Crocker & Schiller [Page 20] - -RFC 1750 Randomness Recommendations for Security December 1994 - - - +---------------+ - | V | - | | n | - +--+------------+ - | | +---------+ - | +---------> | | +-----+ - +--+ | Encrypt | <--- | Key | - | +-------- | | +-----+ - | | +---------+ - V V - +------------+--+ - | V | | - | n+1 | - +---------------+ - - Note that if a shift of one is used, this is the same as the shift - register technique described in Section 3 above but with the all - important difference that the feedback is determined by a complex - non-linear function of all bits rather than a simple linear or - polynomial combination of output from a few bit position taps. - - It has been shown by Donald W. Davies that this sort of shifted - partial output feedback significantly weakens an algorithm compared - will feeding all of the output bits back as input. In particular, - for DES, repeated encrypting a full 64 bit quantity will give an - expected repeat in about 2^63 iterations. Feeding back anything less - than 64 (and more than 0) bits will give an expected repeat in - between 2**31 and 2**32 iterations! - - To predict values of a sequence from others when the sequence was - generated by these techniques is equivalent to breaking the - cryptosystem or inverting the "non-invertible" hashing involved with - only partial information available. The less information revealed - each iteration, the harder it will be for an adversary to predict the - sequence. Thus it is best to use only one bit from each value. It - has been shown that in some cases this makes it impossible to break a - system even when the cryptographic system is invertible and can be - broken if all of each generated value was revealed. - -6.3.2 The Blum Blum Shub Sequence Generator - - Currently the generator which has the strongest public proof of - strength is called the Blum Blum Shub generator after its inventors - [BBS]. It is also very simple and is based on quadratic residues. - It's only disadvantage is that is is computationally intensive - compared with the traditional techniques give in 6.3.1 above. This - is not a serious draw back if it is used for moderately infrequent - purposes, such as generating session keys. - - - -Eastlake, Crocker & Schiller [Page 21] - -RFC 1750 Randomness Recommendations for Security December 1994 - - - Simply choose two large prime numbers, say p and q, which both have - the property that you get a remainder of 3 if you divide them by 4. - Let n = p * q. Then you choose a random number x relatively prime to - n. The initial seed for the generator and the method for calculating - subsequent values are then - - 2 - s = ( x )(Mod n) - 0 - - 2 - s = ( s )(Mod n) - i+1 i - - You must be careful to use only a few bits from the bottom of each s. - It is always safe to use only the lowest order bit. If you use no - more than the - - log ( log ( s ) ) - 2 2 i - - low order bits, then predicting any additional bits from a sequence - generated in this manner is provable as hard as factoring n. As long - as the initial x is secret, you can even make n public if you want. - - An intersting characteristic of this generator is that you can - directly calculate any of the s values. In particular - - i - ( ( 2 )(Mod (( p - 1 ) * ( q - 1 )) ) ) - s = ( s )(Mod n) - i 0 - - This means that in applications where many keys are generated in this - fashion, it is not necessary to save them all. Each key can be - effectively indexed and recovered from that small index and the - initial s and n. - -7. Key Generation Standards - - Several public standards are now in place for the generation of keys. - Two of these are described below. Both use DES but any equally - strong or stronger mixing function could be substituted. - - - - - - - - -Eastlake, Crocker & Schiller [Page 22] - -RFC 1750 Randomness Recommendations for Security December 1994 - - -7.1 US DoD Recommendations for Password Generation - - The United States Department of Defense has specific recommendations - for password generation [DoD]. They suggest using the US Data - Encryption Standard [DES] in Output Feedback Mode [DES MODES] as - follows: - - use an initialization vector determined from - the system clock, - system ID, - user ID, and - date and time; - use a key determined from - system interrupt registers, - system status registers, and - system counters; and, - as plain text, use an external randomly generated 64 bit - quantity such as 8 characters typed in by a system - administrator. - - The password can then be calculated from the 64 bit "cipher text" - generated in 64-bit Output Feedback Mode. As many bits as are needed - can be taken from these 64 bits and expanded into a pronounceable - word, phrase, or other format if a human being needs to remember the - password. - -7.2 X9.17 Key Generation - - The American National Standards Institute has specified a method for - generating a sequence of keys as follows: - - s is the initial 64 bit seed - 0 - - g is the sequence of generated 64 bit key quantities - n - - k is a random key reserved for generating this key sequence - - t is the time at which a key is generated to as fine a resolution - as is available (up to 64 bits). - - DES ( K, Q ) is the DES encryption of quantity Q with key K - - - - - - - - -Eastlake, Crocker & Schiller [Page 23] - -RFC 1750 Randomness Recommendations for Security December 1994 - - - g = DES ( k, DES ( k, t ) .xor. s ) - n n - - s = DES ( k, DES ( k, t ) .xor. g ) - n+1 n - - If g sub n is to be used as a DES key, then every eighth bit should - be adjusted for parity for that use but the entire 64 bit unmodified - g should be used in calculating the next s. - -8. Examples of Randomness Required - - Below are two examples showing rough calculations of needed - randomness for security. The first is for moderate security - passwords while the second assumes a need for a very high security - cryptographic key. - -8.1 Password Generation - - Assume that user passwords change once a year and it is desired that - the probability that an adversary could guess the password for a - particular account be less than one in a thousand. Further assume - that sending a password to the system is the only way to try a - password. Then the crucial question is how often an adversary can - try possibilities. Assume that delays have been introduced into a - system so that, at most, an adversary can make one password try every - six seconds. That's 600 per hour or about 15,000 per day or about - 5,000,000 tries in a year. Assuming any sort of monitoring, it is - unlikely someone could actually try continuously for a year. In - fact, even if log files are only checked monthly, 500,000 tries is - more plausible before the attack is noticed and steps taken to change - passwords and make it harder to try more passwords. - - To have a one in a thousand chance of guessing the password in - 500,000 tries implies a universe of at least 500,000,000 passwords or - about 2^29. Thus 29 bits of randomness are needed. This can probably - be achieved using the US DoD recommended inputs for password - generation as it has 8 inputs which probably average over 5 bits of - randomness each (see section 7.1). Using a list of 1000 words, the - password could be expressed as a three word phrase (1,000,000,000 - possibilities) or, using case insensitive letters and digits, six - would suffice ((26+10)^6 = 2,176,782,336 possibilities). - - For a higher security password, the number of bits required goes up. - To decrease the probability by 1,000 requires increasing the universe - of passwords by the same factor which adds about 10 bits. Thus to - have only a one in a million chance of a password being guessed under - the above scenario would require 39 bits of randomness and a password - - - -Eastlake, Crocker & Schiller [Page 24] - -RFC 1750 Randomness Recommendations for Security December 1994 - - - that was a four word phrase from a 1000 word list or eight - letters/digits. To go to a one in 10^9 chance, 49 bits of randomness - are needed implying a five word phrase or ten letter/digit password. - - In a real system, of course, there are also other factors. For - example, the larger and harder to remember passwords are, the more - likely users are to write them down resulting in an additional risk - of compromise. - -8.2 A Very High Security Cryptographic Key - - Assume that a very high security key is needed for symmetric - encryption / decryption between two parties. Assume an adversary can - observe communications and knows the algorithm being used. Within - the field of random possibilities, the adversary can try key values - in hopes of finding the one in use. Assume further that brute force - trial of keys is the best the adversary can do. - -8.2.1 Effort per Key Trial - - How much effort will it take to try each key? For very high security - applications it is best to assume a low value of effort. Even if it - would clearly take tens of thousands of computer cycles or more to - try a single key, there may be some pattern that enables huge blocks - of key values to be tested with much less effort per key. Thus it is - probably best to assume no more than a couple hundred cycles per key. - (There is no clear lower bound on this as computers operate in - parallel on a number of bits and a poor encryption algorithm could - allow many keys or even groups of keys to be tested in parallel. - However, we need to assume some value and can hope that a reasonably - strong algorithm has been chosen for our hypothetical high security - task.) - - If the adversary can command a highly parallel processor or a large - network of work stations, 2*10^10 cycles per second is probably a - minimum assumption for availability today. Looking forward just a - couple years, there should be at least an order of magnitude - improvement. Thus assuming 10^9 keys could be checked per second or - 3.6*10^11 per hour or 6*10^13 per week or 2.4*10^14 per month is - reasonable. This implies a need for a minimum of 51 bits of - randomness in keys to be sure they cannot be found in a month. Even - then it is possible that, a few years from now, a highly determined - and resourceful adversary could break the key in 2 weeks (on average - they need try only half the keys). - - - - - - - -Eastlake, Crocker & Schiller [Page 25] - -RFC 1750 Randomness Recommendations for Security December 1994 - - -8.2.2 Meet in the Middle Attacks - - If chosen or known plain text and the resulting encrypted text are - available, a "meet in the middle" attack is possible if the structure - of the encryption algorithm allows it. (In a known plain text - attack, the adversary knows all or part of the messages being - encrypted, possibly some standard header or trailer fields. In a - chosen plain text attack, the adversary can force some chosen plain - text to be encrypted, possibly by "leaking" an exciting text that - would then be sent by the adversary over an encrypted channel.) - - An oversimplified explanation of the meet in the middle attack is as - follows: the adversary can half-encrypt the known or chosen plain - text with all possible first half-keys, sort the output, then half- - decrypt the encoded text with all the second half-keys. If a match - is found, the full key can be assembled from the halves and used to - decrypt other parts of the message or other messages. At its best, - this type of attack can halve the exponent of the work required by - the adversary while adding a large but roughly constant factor of - effort. To be assured of safety against this, a doubling of the - amount of randomness in the key to a minimum of 102 bits is required. - - The meet in the middle attack assumes that the cryptographic - algorithm can be decomposed in this way but we can not rule that out - without a deep knowledge of the algorithm. Even if a basic algorithm - is not subject to a meet in the middle attack, an attempt to produce - a stronger algorithm by applying the basic algorithm twice (or two - different algorithms sequentially) with different keys may gain less - added security than would be expected. Such a composite algorithm - would be subject to a meet in the middle attack. - - Enormous resources may be required to mount a meet in the middle - attack but they are probably within the range of the national - security services of a major nation. Essentially all nations spy on - other nations government traffic and several nations are believed to - spy on commercial traffic for economic advantage. - -8.2.3 Other Considerations - - Since we have not even considered the possibilities of special - purpose code breaking hardware or just how much of a safety margin we - want beyond our assumptions above, probably a good minimum for a very - high security cryptographic key is 128 bits of randomness which - implies a minimum key length of 128 bits. If the two parties agree - on a key by Diffie-Hellman exchange [D-H], then in principle only - half of this randomness would have to be supplied by each party. - However, there is probably some correlation between their random - inputs so it is probably best to assume that each party needs to - - - -Eastlake, Crocker & Schiller [Page 26] - -RFC 1750 Randomness Recommendations for Security December 1994 - - - provide at least 96 bits worth of randomness for very high security - if Diffie-Hellman is used. - - This amount of randomness is beyond the limit of that in the inputs - recommended by the US DoD for password generation and could require - user typing timing, hardware random number generation, or other - sources. - - It should be noted that key length calculations such at those above - are controversial and depend on various assumptions about the - cryptographic algorithms in use. In some cases, a professional with - a deep knowledge of code breaking techniques and of the strength of - the algorithm in use could be satisfied with less than half of the - key size derived above. - -9. Conclusion - - Generation of unguessable "random" secret quantities for security use - is an essential but difficult task. - - We have shown that hardware techniques to produce such randomness - would be relatively simple. In particular, the volume and quality - would not need to be high and existing computer hardware, such as - disk drives, can be used. Computational techniques are available to - process low quality random quantities from multiple sources or a - larger quantity of such low quality input from one source and produce - a smaller quantity of higher quality, less predictable key material. - In the absence of hardware sources of randomness, a variety of user - and software sources can frequently be used instead with care; - however, most modern systems already have hardware, such as disk - drives or audio input, that could be used to produce high quality - randomness. - - Once a sufficient quantity of high quality seed key material (a few - hundred bits) is available, strong computational techniques are - available to produce cryptographically strong sequences of - unpredicatable quantities from this seed material. - -10. Security Considerations - - The entirety of this document concerns techniques and recommendations - for generating unguessable "random" quantities for use as passwords, - cryptographic keys, and similar security uses. - - - - - - - - -Eastlake, Crocker & Schiller [Page 27] - -RFC 1750 Randomness Recommendations for Security December 1994 - - -References - - [ASYMMETRIC] - Secure Communications and Asymmetric Cryptosystems, - edited by Gustavus J. Simmons, AAAS Selected Symposium 69, Westview - Press, Inc. - - [BBS] - A Simple Unpredictable Pseudo-Random Number Generator, SIAM - Journal on Computing, v. 15, n. 2, 1986, L. Blum, M. Blum, & M. Shub. - - [BRILLINGER] - Time Series: Data Analysis and Theory, Holden-Day, - 1981, David Brillinger. - - [CRC] - C.R.C. Standard Mathematical Tables, Chemical Rubber - Publishing Company. - - [CRYPTO1] - Cryptography: A Primer, A Wiley-Interscience Publication, - John Wiley & Sons, 1981, Alan G. Konheim. - - [CRYPTO2] - Cryptography: A New Dimension in Computer Data Security, - A Wiley-Interscience Publication, John Wiley & Sons, 1982, Carl H. - Meyer & Stephen M. Matyas. - - [CRYPTO3] - Applied Cryptography: Protocols, Algorithms, and Source - Code in C, John Wiley & Sons, 1994, Bruce Schneier. - - [DAVIS] - Cryptographic Randomness from Air Turbulence in Disk - Drives, Advances in Cryptology - Crypto '94, Springer-Verlag Lecture - Notes in Computer Science #839, 1984, Don Davis, Ross Ihaka, and - Philip Fenstermacher. - - [DES] - Data Encryption Standard, United States of America, - Department of Commerce, National Institute of Standards and - Technology, Federal Information Processing Standard (FIPS) 46-1. - - Data Encryption Algorithm, American National Standards Institute, - ANSI X3.92-1981. - (See also FIPS 112, Password Usage, which includes FORTRAN code for - performing DES.) - - [DES MODES] - DES Modes of Operation, United States of America, - Department of Commerce, National Institute of Standards and - Technology, Federal Information Processing Standard (FIPS) 81. - - Data Encryption Algorithm - Modes of Operation, American National - Standards Institute, ANSI X3.106-1983. - - [D-H] - New Directions in Cryptography, IEEE Transactions on - Information Technology, November, 1976, Whitfield Diffie and Martin - E. Hellman. - - - - -Eastlake, Crocker & Schiller [Page 28] - -RFC 1750 Randomness Recommendations for Security December 1994 - - - [DoD] - Password Management Guideline, United States of America, - Department of Defense, Computer Security Center, CSC-STD-002-85. - (See also FIPS 112, Password Usage, which incorporates CSC-STD-002-85 - as one of its appendices.) - - [GIFFORD] - Natural Random Number, MIT/LCS/TM-371, September 1988, - David K. Gifford - - [KNUTH] - The Art of Computer Programming, Volume 2: Seminumerical - Algorithms, Chapter 3: Random Numbers. Addison Wesley Publishing - Company, Second Edition 1982, Donald E. Knuth. - - [KRAWCZYK] - How to Predict Congruential Generators, Journal of - Algorithms, V. 13, N. 4, December 1992, H. Krawczyk - - [MD2] - The MD2 Message-Digest Algorithm, RFC1319, April 1992, B. - Kaliski - [MD4] - The MD4 Message-Digest Algorithm, RFC1320, April 1992, R. - Rivest - [MD5] - The MD5 Message-Digest Algorithm, RFC1321, April 1992, R. - Rivest - - [PEM] - RFCs 1421 through 1424: - - RFC 1424, Privacy Enhancement for Internet Electronic Mail: Part - IV: Key Certification and Related Services, 02/10/1993, B. Kaliski - - RFC 1423, Privacy Enhancement for Internet Electronic Mail: Part - III: Algorithms, Modes, and Identifiers, 02/10/1993, D. Balenson - - RFC 1422, Privacy Enhancement for Internet Electronic Mail: Part - II: Certificate-Based Key Management, 02/10/1993, S. Kent - - RFC 1421, Privacy Enhancement for Internet Electronic Mail: Part I: - Message Encryption and Authentication Procedures, 02/10/1993, J. Linn - - [SHANNON] - The Mathematical Theory of Communication, University of - Illinois Press, 1963, Claude E. Shannon. (originally from: Bell - System Technical Journal, July and October 1948) - - [SHIFT1] - Shift Register Sequences, Aegean Park Press, Revised - Edition 1982, Solomon W. Golomb. - - [SHIFT2] - Cryptanalysis of Shift-Register Generated Stream Cypher - Systems, Aegean Park Press, 1984, Wayne G. Barker. - - [SHS] - Secure Hash Standard, United States of American, National - Institute of Science and Technology, Federal Information Processing - Standard (FIPS) 180, April 1993. - - [STERN] - Secret Linear Congruential Generators are not - Cryptograhically Secure, Proceedings of IEEE STOC, 1987, J. Stern. - - - -Eastlake, Crocker & Schiller [Page 29] - -RFC 1750 Randomness Recommendations for Security December 1994 - - - [VON NEUMANN] - Various techniques used in connection with random - digits, von Neumann's Collected Works, Vol. 5, Pergamon Press, 1963, - J. von Neumann. - -Authors' Addresses - - Donald E. Eastlake 3rd - Digital Equipment Corporation - 550 King Street, LKG2-1/BB3 - Littleton, MA 01460 - - Phone: +1 508 486 6577(w) +1 508 287 4877(h) - EMail: dee@lkg.dec.com - - - Stephen D. Crocker - CyberCash Inc. - 2086 Hunters Crest Way - Vienna, VA 22181 - - Phone: +1 703-620-1222(w) +1 703-391-2651 (fax) - EMail: crocker@cybercash.com - - - Jeffrey I. Schiller - Massachusetts Institute of Technology - 77 Massachusetts Avenue - Cambridge, MA 02139 - - Phone: +1 617 253 0161(w) - EMail: jis@mit.edu - - - - - - - - - - - - - - - - - - - - -Eastlake, Crocker & Schiller [Page 30] - diff --git a/doc/rfc1831.txt b/doc/rfc1831.txt deleted file mode 100644 index 0556c9e83..000000000 --- a/doc/rfc1831.txt +++ /dev/null @@ -1,1011 +0,0 @@ - - - - - - -Network Working Group R. Srinivasan -Request for Comments: 1831 Sun Microsystems -Category: Standards Track August 1995 - - - RPC: Remote Procedure Call Protocol Specification Version 2 - -Status of this Memo - - This document specifies an Internet standards track protocol for the - Internet community, and requests discussion and suggestions for - improvements. Please refer to the current edition of the "Internet - Official Protocol Standards" (STD 1) for the standardization state - and status of this protocol. Distribution of this memo is unlimited. - -ABSTRACT - - This document describes the ONC Remote Procedure Call (ONC RPC - Version 2) protocol as it is currently deployed and accepted. "ONC" - stands for "Open Network Computing". - -TABLE OF CONTENTS - - 1. INTRODUCTION 2 - 2. TERMINOLOGY 2 - 3. THE RPC MODEL 2 - 4. TRANSPORTS AND SEMANTICS 4 - 5. BINDING AND RENDEZVOUS INDEPENDENCE 5 - 6. AUTHENTICATION 5 - 7. RPC PROTOCOL REQUIREMENTS 5 - 7.1 RPC Programs and Procedures 6 - 7.2 Authentication 7 - 7.3 Program Number Assignment 8 - 7.4 Other Uses of the RPC Protocol 8 - 7.4.1 Batching 8 - 7.4.2 Broadcast Remote Procedure Calls 8 - 8. THE RPC MESSAGE PROTOCOL 9 - 9. AUTHENTICATION PROTOCOLS 12 - 9.1 Null Authentication 13 - 10. RECORD MARKING STANDARD 13 - 11. THE RPC LANGUAGE 13 - 11.1 An Example Service Described in the RPC Language 13 - 11.2 The RPC Language Specification 14 - 11.3 Syntax Notes 15 - APPENDIX A: SYSTEM AUTHENTICATION 16 - REFERENCES 17 - Security Considerations 18 - Author's Address 18 - - - -Srinivasan Standards Track [Page 1] - -RFC 1831 Remote Procedure Call Protocol Version 2 August 1995 - - -1. INTRODUCTION - - This document specifies version two of the message protocol used in - ONC Remote Procedure Call (RPC). The message protocol is specified - with the eXternal Data Representation (XDR) language [9]. This - document assumes that the reader is familiar with XDR. It does not - attempt to justify remote procedure calls systems or describe their - use. The paper by Birrell and Nelson [1] is recommended as an - excellent background for the remote procedure call concept. - -2. TERMINOLOGY - - This document discusses clients, calls, servers, replies, services, - programs, procedures, and versions. Each remote procedure call has - two sides: an active client side that makes the call to a server, - which sends back a reply. A network service is a collection of one - or more remote programs. A remote program implements one or more - remote procedures; the procedures, their parameters, and results are - documented in the specific program's protocol specification. A - server may support more than one version of a remote program in order - to be compatible with changing protocols. - - For example, a network file service may be composed of two programs. - One program may deal with high-level applications such as file system - access control and locking. The other may deal with low-level file - input and output and have procedures like "read" and "write". A - client of the network file service would call the procedures - associated with the two programs of the service on behalf of the - client. - - The terms client and server only apply to a particular transaction; a - particular hardware entity (host) or software entity (process or - program) could operate in both roles at different times. For - example, a program that supplies remote execution service could also - be a client of a network file service. - -3. THE RPC MODEL - - The ONC RPC protocol is based on the remote procedure call model, - which is similar to the local procedure call model. In the local - case, the caller places arguments to a procedure in some well- - specified location (such as a register window). It then transfers - control to the procedure, and eventually regains control. At that - point, the results of the procedure are extracted from the well- - specified location, and the caller continues execution. - - - - - - -Srinivasan Standards Track [Page 2] - -RFC 1831 Remote Procedure Call Protocol Version 2 August 1995 - - - The remote procedure call model is similar. One thread of control - logically winds through two processes: the caller's process, and a - server's process. The caller process first sends a call message to - the server process and waits (blocks) for a reply message. The call - message includes the procedure's parameters, and the reply message - includes the procedure's results. Once the reply message is - received, the results of the procedure are extracted, and caller's - execution is resumed. - - On the server side, a process is dormant awaiting the arrival of a - call message. When one arrives, the server process extracts the - procedure's parameters, computes the results, sends a reply message, - and then awaits the next call message. - - In this model, only one of the two processes is active at any given - time. However, this model is only given as an example. The ONC RPC - protocol makes no restrictions on the concurrency model implemented, - and others are possible. For example, an implementation may choose - to have RPC calls be asynchronous, so that the client may do useful - work while waiting for the reply from the server. Another - possibility is to have the server create a separate task to process - an incoming call, so that the original server can be free to receive - other requests. - - There are a few important ways in which remote procedure calls differ - from local procedure calls: - - 1. Error handling: failures of the remote server or network must - be handled when using remote procedure calls. - - 2. Global variables and side-effects: since the server does not - have access to the client's address space, hidden arguments cannot - be passed as global variables or returned as side effects. - - 3. Performance: remote procedures usually operate one or more - orders of magnitude slower than local procedure calls. - - 4. Authentication: since remote procedure calls can be transported - over unsecured networks, authentication may be necessary. - Authentication prevents one entity from masquerading as some other - entity. - - The conclusion is that even though there are tools to automatically - generate client and server libraries for a given service, protocols - must still be designed carefully. - - - - - - -Srinivasan Standards Track [Page 3] - -RFC 1831 Remote Procedure Call Protocol Version 2 August 1995 - - -4. TRANSPORTS AND SEMANTICS - - The RPC protocol can be implemented on several different transport - protocols. The RPC protocol does not care how a message is passed - from one process to another, but only with specification and - interpretation of messages. However, the application may wish to - obtain information about (and perhaps control over) the transport - layer through an interface not specified in this document. For - example, the transport protocol may impose a restriction on the - maximum size of RPC messages, or it may be stream-oriented like TCP - with no size limit. The client and server must agree on their - transport protocol choices. - - It is important to point out that RPC does not try to implement any - kind of reliability and that the application may need to be aware of - the type of transport protocol underneath RPC. If it knows it is - running on top of a reliable transport such as TCP [6], then most of - the work is already done for it. On the other hand, if it is running - on top of an unreliable transport such as UDP [7], it must implement - its own time-out, retransmission, and duplicate detection policies as - the RPC protocol does not provide these services. - - Because of transport independence, the RPC protocol does not attach - specific semantics to the remote procedures or their execution - requirements. Semantics can be inferred from (but should be - explicitly specified by) the underlying transport protocol. For - example, consider RPC running on top of an unreliable transport such - as UDP. If an application retransmits RPC call messages after time- - outs, and does not receive a reply, it cannot infer anything about - the number of times the procedure was executed. If it does receive a - reply, then it can infer that the procedure was executed at least - once. - - A server may wish to remember previously granted requests from a - client and not regrant them in order to insure some degree of - execute-at-most-once semantics. A server can do this by taking - advantage of the transaction ID that is packaged with every RPC - message. The main use of this transaction ID is by the client RPC - entity in matching replies to calls. However, a client application - may choose to reuse its previous transaction ID when retransmitting a - call. The server may choose to remember this ID after executing a - call and not execute calls with the same ID in order to achieve some - degree of execute-at-most-once semantics. The server is not allowed - to examine this ID in any other way except as a test for equality. - - On the other hand, if using a "reliable" transport such as TCP, the - application can infer from a reply message that the procedure was - executed exactly once, but if it receives no reply message, it cannot - - - -Srinivasan Standards Track [Page 4] - -RFC 1831 Remote Procedure Call Protocol Version 2 August 1995 - - - assume that the remote procedure was not executed. Note that even if - a connection-oriented protocol like TCP is used, an application still - needs time-outs and reconnection to handle server crashes. - - There are other possibilities for transports besides datagram- or - connection-oriented protocols. For example, a request-reply protocol - such as VMTP [2] is perhaps a natural transport for RPC. ONC RPC - uses both TCP and UDP transport protocols. Section 10 (RECORD - MARKING STANDARD) describes the mechanism employed by ONC RPC to - utilize a connection-oriented, stream-oriented transport such as TCP. - -5. BINDING AND RENDEZVOUS INDEPENDENCE - - The act of binding a particular client to a particular service and - transport parameters is NOT part of this RPC protocol specification. - This important and necessary function is left up to some higher-level - software. - - Implementors could think of the RPC protocol as the jump-subroutine - instruction ("JSR") of a network; the loader (binder) makes JSR - useful, and the loader itself uses JSR to accomplish its task. - Likewise, the binding software makes RPC useful, possibly using RPC - to accomplish this task. - -6. AUTHENTICATION - - The RPC protocol provides the fields necessary for a client to - identify itself to a service, and vice-versa, in each call and reply - message. Security and access control mechanisms can be built on top - of this message authentication. Several different authentication - protocols can be supported. A field in the RPC header indicates - which protocol is being used. More information on specific - authentication protocols is in section 9: "Authentication Protocols". - -7. RPC PROTOCOL REQUIREMENTS - - The RPC protocol must provide for the following: - - (1) Unique specification of a procedure to be called. - (2) Provisions for matching response messages to request messages. - (3) Provisions for authenticating the caller to service and - vice-versa. - - - - - - - - - -Srinivasan Standards Track [Page 5] - -RFC 1831 Remote Procedure Call Protocol Version 2 August 1995 - - - Besides these requirements, features that detect the following are - worth supporting because of protocol roll-over errors, implementation - bugs, user error, and network administration: - - (1) RPC protocol mismatches. - (2) Remote program protocol version mismatches. - (3) Protocol errors (such as misspecification of a procedure's - parameters). - (4) Reasons why remote authentication failed. - (5) Any other reasons why the desired procedure was not called. - -7.1 RPC Programs and Procedures - - The RPC call message has three unsigned integer fields -- remote - program number, remote program version number, and remote procedure - number -- which uniquely identify the procedure to be called. - Program numbers are administered by a central authority - (rpc@sun.com). Once implementors have a program number, they can - implement their remote program; the first implementation would most - likely have the version number 1. Because most new protocols evolve, - a version field of the call message identifies which version of the - protocol the caller is using. Version numbers enable support of both - old and new protocols through the same server process. - - The procedure number identifies the procedure to be called. These - numbers are documented in the specific program's protocol - specification. For example, a file service's protocol specification - may state that its procedure number 5 is "read" and procedure number - 12 is "write". - - Just as remote program protocols may change over several versions, - the actual RPC message protocol could also change. Therefore, the - call message also has in it the RPC version number, which is always - equal to two for the version of RPC described here. - - The reply message to a request message has enough information to - distinguish the following error conditions: - - (1) The remote implementation of RPC does not support protocol - version 2. The lowest and highest supported RPC version numbers - are returned. - - (2) The remote program is not available on the remote system. - - (3) The remote program does not support the requested version - number. The lowest and highest supported remote program version - numbers are returned. - - - - -Srinivasan Standards Track [Page 6] - -RFC 1831 Remote Procedure Call Protocol Version 2 August 1995 - - - (4) The requested procedure number does not exist. (This is - usually a client side protocol or programming error.) - - (5) The parameters to the remote procedure appear to be garbage - from the server's point of view. (Again, this is usually caused - by a disagreement about the protocol between client and service.) - -7.2 Authentication - - Provisions for authentication of caller to service and vice-versa are - provided as a part of the RPC protocol. The call message has two - authentication fields, the credential and verifier. The reply - message has one authentication field, the response verifier. The RPC - protocol specification defines all three fields to be the following - opaque type (in the eXternal Data Representation (XDR) language [9]): - - enum auth_flavor { - AUTH_NONE = 0, - AUTH_SYS = 1, - AUTH_SHORT = 2 - /* and more to be defined */ - }; - - struct opaque_auth { - auth_flavor flavor; - opaque body<400>; - }; - - In other words, any "opaque_auth" structure is an "auth_flavor" - enumeration followed by up to 400 bytes which are opaque to - (uninterpreted by) the RPC protocol implementation. - - The interpretation and semantics of the data contained within the - authentication fields is specified by individual, independent - authentication protocol specifications. (Section 9 defines the - various authentication protocols.) - - If authentication parameters were rejected, the reply message - contains information stating why they were rejected. - - - - - - - - - - - - -Srinivasan Standards Track [Page 7] - -RFC 1831 Remote Procedure Call Protocol Version 2 August 1995 - - -7.3 Program Number Assignment - - Program numbers are given out in groups of hexadecimal 20000000 - (decimal 536870912) according to the following chart: - - 0 - 1fffffff defined by rpc@sun.com - 20000000 - 3fffffff defined by user - 40000000 - 5fffffff transient - 60000000 - 7fffffff reserved - 80000000 - 9fffffff reserved - a0000000 - bfffffff reserved - c0000000 - dfffffff reserved - e0000000 - ffffffff reserved - - The first group is a range of numbers administered by rpc@sun.com and - should be identical for all sites. The second range is for - applications peculiar to a particular site. This range is intended - primarily for debugging new programs. When a site develops an - application that might be of general interest, that application - should be given an assigned number in the first range. Application - developers may apply for blocks of RPC program numbers in the first - range by sending electronic mail to "rpc@sun.com". The third group - is for applications that generate program numbers dynamically. The - final groups are reserved for future use, and should not be used. - -7.4 Other Uses of the RPC Protocol - - The intended use of this protocol is for calling remote procedures. - Normally, each call message is matched with a reply message. - However, the protocol itself is a message-passing protocol with which - other (non-procedure call) protocols can be implemented. - -7.4.1 Batching - - Batching is useful when a client wishes to send an arbitrarily large - sequence of call messages to a server. Batching typically uses - reliable byte stream protocols (like TCP) for its transport. In the - case of batching, the client never waits for a reply from the server, - and the server does not send replies to batch calls. A sequence of - batch calls is usually terminated by a legitimate remote procedure - call operation in order to flush the pipeline and get positive - acknowledgement. - -7.4.2 Broadcast Remote Procedure Calls - - In broadcast protocols, the client sends a broadcast call to the - network and waits for numerous replies. This requires the use of - packet-based protocols (like UDP) as its transport protocol. Servers - - - -Srinivasan Standards Track [Page 8] - -RFC 1831 Remote Procedure Call Protocol Version 2 August 1995 - - - that support broadcast protocols usually respond only when the call - is successfully processed and are silent in the face of errors, but - this varies with the application. - - The principles of broadcast RPC also apply to multicasting - an RPC - request can be sent to a multicast address. - -8. THE RPC MESSAGE PROTOCOL - - This section defines the RPC message protocol in the XDR data - description language [9]. - - enum msg_type { - CALL = 0, - REPLY = 1 - }; - - A reply to a call message can take on two forms: The message was - either accepted or rejected. - - enum reply_stat { - MSG_ACCEPTED = 0, - MSG_DENIED = 1 - }; - - Given that a call message was accepted, the following is the status - of an attempt to call a remote procedure. - - enum accept_stat { - SUCCESS = 0, /* RPC executed successfully */ - PROG_UNAVAIL = 1, /* remote hasn't exported program */ - PROG_MISMATCH = 2, /* remote can't support version # */ - PROC_UNAVAIL = 3, /* program can't support procedure */ - GARBAGE_ARGS = 4, /* procedure can't decode params */ - SYSTEM_ERR = 5 /* errors like memory allocation failure */ - }; - - Reasons why a call message was rejected: - - enum reject_stat { - RPC_MISMATCH = 0, /* RPC version number != 2 */ - AUTH_ERROR = 1 /* remote can't authenticate caller */ - }; - - Why authentication failed: - - enum auth_stat { - AUTH_OK = 0, /* success */ - - - -Srinivasan Standards Track [Page 9] - -RFC 1831 Remote Procedure Call Protocol Version 2 August 1995 - - - /* - * failed at remote end - */ - AUTH_BADCRED = 1, /* bad credential (seal broken) */ - AUTH_REJECTEDCRED = 2, /* client must begin new session */ - AUTH_BADVERF = 3, /* bad verifier (seal broken) */ - AUTH_REJECTEDVERF = 4, /* verifier expired or replayed */ - AUTH_TOOWEAK = 5, /* rejected for security reasons */ - /* - * failed locally - */ - AUTH_INVALIDRESP = 6, /* bogus response verifier */ - AUTH_FAILED = 7 /* reason unknown */ - }; - - The RPC message: - - All messages start with a transaction identifier, xid, followed by a - two-armed discriminated union. The union's discriminant is a - msg_type which switches to one of the two types of the message. The - xid of a REPLY message always matches that of the initiating CALL - message. NB: The xid field is only used for clients matching reply - messages with call messages or for servers detecting retransmissions; - the service side cannot treat this id as any type of sequence number. - - struct rpc_msg { - unsigned int xid; - union switch (msg_type mtype) { - case CALL: - call_body cbody; - case REPLY: - reply_body rbody; - } body; - }; - - Body of an RPC call: - - In version 2 of the RPC protocol specification, rpcvers must be equal - to 2. The fields prog, vers, and proc specify the remote program, - its version number, and the procedure within the remote program to be - called. After these fields are two authentication parameters: cred - (authentication credential) and verf (authentication verifier). The - two authentication parameters are followed by the parameters to the - remote procedure, which are specified by the specific program - protocol. - - The purpose of the authentication verifier is to validate the - authentication credential. Note that these two items are - - - -Srinivasan Standards Track [Page 10] - -RFC 1831 Remote Procedure Call Protocol Version 2 August 1995 - - - historically separate, but are always used together as one logical - entity. - - struct call_body { - unsigned int rpcvers; /* must be equal to two (2) */ - unsigned int prog; - unsigned int vers; - unsigned int proc; - opaque_auth cred; - opaque_auth verf; - /* procedure specific parameters start here */ - }; - - Body of a reply to an RPC call: - - union reply_body switch (reply_stat stat) { - case MSG_ACCEPTED: - accepted_reply areply; - case MSG_DENIED: - rejected_reply rreply; - } reply; - - Reply to an RPC call that was accepted by the server: - - There could be an error even though the call was accepted. The first - field is an authentication verifier that the server generates in - order to validate itself to the client. It is followed by a union - whose discriminant is an enum accept_stat. The SUCCESS arm of the - union is protocol specific. The PROG_UNAVAIL, PROC_UNAVAIL, - GARBAGE_ARGS, and SYSTEM_ERR arms of the union are void. The - PROG_MISMATCH arm specifies the lowest and highest version numbers of - the remote program supported by the server. - - struct accepted_reply { - opaque_auth verf; - union switch (accept_stat stat) { - case SUCCESS: - opaque results[0]; - /* - * procedure-specific results start here - */ - case PROG_MISMATCH: - struct { - unsigned int low; - unsigned int high; - } mismatch_info; - default: - /* - - - -Srinivasan Standards Track [Page 11] - -RFC 1831 Remote Procedure Call Protocol Version 2 August 1995 - - - * Void. Cases include PROG_UNAVAIL, PROC_UNAVAIL, - * GARBAGE_ARGS, and SYSTEM_ERR. - */ - void; - } reply_data; - }; - - Reply to an RPC call that was rejected by the server: - - The call can be rejected for two reasons: either the server is not - running a compatible version of the RPC protocol (RPC_MISMATCH), or - the server rejects the identity of the caller (AUTH_ERROR). In case - of an RPC version mismatch, the server returns the lowest and highest - supported RPC version numbers. In case of invalid authentication, - failure status is returned. - - union rejected_reply switch (reject_stat stat) { - case RPC_MISMATCH: - struct { - unsigned int low; - unsigned int high; - } mismatch_info; - case AUTH_ERROR: - auth_stat stat; - }; - -9. AUTHENTICATION PROTOCOLS - - As previously stated, authentication parameters are opaque, but - open-ended to the rest of the RPC protocol. This section defines two - standard "flavors" of authentication. Implementors are free to - invent new authentication types, with the same rules of flavor number - assignment as there is for program number assignment. The "flavor" - of a credential or verifier refers to the value of the "flavor" field - in the opaque_auth structure. Flavor numbers, like RPC program - numbers, are also administered centrally, and developers may assign - new flavor numbers by applying through electronic mail to - "rpc@sun.com". Credentials and verifiers are represented as variable - length opaque data (the "body" field in the opaque_auth structure). - - In this document, two flavors of authentication are described. Of - these, Null authentication (described in the next subsection) is - mandatory - it must be available in all implementations. System - authentication is described in Appendix A. It is strongly - recommended that implementors include System authentication in their - implementations. Many applications use this style of authentication, - and availability of this flavor in an implementation will enhance - interoperability. - - - -Srinivasan Standards Track [Page 12] - -RFC 1831 Remote Procedure Call Protocol Version 2 August 1995 - - -9.1 Null Authentication - - Often calls must be made where the client does not care about its - identity or the server does not care who the client is. In this - case, the flavor of the RPC message's credential, verifier, and reply - verifier is "AUTH_NONE". Opaque data associated with "AUTH_NONE" is - undefined. It is recommended that the length of the opaque data be - zero. - -10. RECORD MARKING STANDARD - - When RPC messages are passed on top of a byte stream transport - protocol (like TCP), it is necessary to delimit one message from - another in order to detect and possibly recover from protocol errors. - This is called record marking (RM). One RPC message fits into one RM - record. - - A record is composed of one or more record fragments. A record - fragment is a four-byte header followed by 0 to (2**31) - 1 bytes of - fragment data. The bytes encode an unsigned binary number; as with - XDR integers, the byte order is from highest to lowest. The number - encodes two values -- a boolean which indicates whether the fragment - is the last fragment of the record (bit value 1 implies the fragment - is the last fragment) and a 31-bit unsigned binary value which is the - length in bytes of the fragment's data. The boolean value is the - highest-order bit of the header; the length is the 31 low-order bits. - (Note that this record specification is NOT in XDR standard form!) - -11. THE RPC LANGUAGE - - Just as there was a need to describe the XDR data-types in a formal - language, there is also need to describe the procedures that operate - on these XDR data-types in a formal language as well. The RPC - Language is an extension to the XDR language, with the addition of - "program", "procedure", and "version" declarations. The following - example is used to describe the essence of the language. - -11.1 An Example Service Described in the RPC Language - - Here is an example of the specification of a simple ping program. - - program PING_PROG { - /* - * Latest and greatest version - */ - version PING_VERS_PINGBACK { - void - PINGPROC_NULL(void) = 0; - - - -Srinivasan Standards Track [Page 13] - -RFC 1831 Remote Procedure Call Protocol Version 2 August 1995 - - - /* - * Ping the client, return the round-trip time - * (in microseconds). Returns -1 if the operation - * timed out. - */ - int - PINGPROC_PINGBACK(void) = 1; - } = 2; - - /* - * Original version - */ - version PING_VERS_ORIG { - void - PINGPROC_NULL(void) = 0; - } = 1; - } = 1; - - const PING_VERS = 2; /* latest version */ - - The first version described is PING_VERS_PINGBACK with two - procedures, PINGPROC_NULL and PINGPROC_PINGBACK. PINGPROC_NULL takes - no arguments and returns no results, but it is useful for computing - round-trip times from the client to the server and back again. By - convention, procedure 0 of any RPC protocol should have the same - semantics, and never require any kind of authentication. The second - procedure is used for the client to have the server do a reverse ping - operation back to the client, and it returns the amount of time (in - microseconds) that the operation used. The next version, - PING_VERS_ORIG, is the original version of the protocol and it does - not contain PINGPROC_PINGBACK procedure. It is useful for - compatibility with old client programs, and as this program matures - it may be dropped from the protocol entirely. - -11.2 The RPC Language Specification - - The RPC language is identical to the XDR language defined in RFC - 1014, except for the added definition of a "program-def" described - below. - - program-def: - "program" identifier "{" - version-def - version-def * - "}" "=" constant ";" - - version-def: - "version" identifier "{" - - - -Srinivasan Standards Track [Page 14] - -RFC 1831 Remote Procedure Call Protocol Version 2 August 1995 - - - procedure-def - procedure-def * - "}" "=" constant ";" - - procedure-def: - type-specifier identifier "(" type-specifier - ("," type-specifier )* ")" "=" constant ";" - -11.3 Syntax Notes - - (1) The following keywords are added and cannot be used as - identifiers: "program" and "version"; - - (2) A version name cannot occur more than once within the scope of a - program definition. Nor can a version number occur more than once - within the scope of a program definition. - - (3) A procedure name cannot occur more than once within the scope of - a version definition. Nor can a procedure number occur more than once - within the scope of version definition. - - (4) Program identifiers are in the same name space as constant and - type identifiers. - - (5) Only unsigned constants can be assigned to programs, versions and - procedures. - - - - - - - - - - - - - - - - - - - - - - - - - -Srinivasan Standards Track [Page 15] - -RFC 1831 Remote Procedure Call Protocol Version 2 August 1995 - - -APPENDIX A: SYSTEM AUTHENTICATION - - The client may wish to identify itself, for example, as it is - identified on a UNIX(tm) system. The flavor of the client credential - is "AUTH_SYS". The opaque data constituting the credential encodes - the following structure: - - struct authsys_parms { - unsigned int stamp; - string machinename<255>; - unsigned int uid; - unsigned int gid; - unsigned int gids<16>; - }; - - The "stamp" is an arbitrary ID which the caller machine may generate. - The "machinename" is the name of the caller's machine (like - "krypton"). The "uid" is the caller's effective user ID. The "gid" - is the caller's effective group ID. The "gids" is a counted array of - groups which contain the caller as a member. The verifier - accompanying the credential should have "AUTH_NONE" flavor value - (defined above). Note this credential is only unique within a - particular domain of machine names, uids, and gids. - - The flavor value of the verifier received in the reply message from - the server may be "AUTH_NONE" or "AUTH_SHORT". In the case of - "AUTH_SHORT", the bytes of the reply verifier's string encode an - opaque structure. This new opaque structure may now be passed to the - server instead of the original "AUTH_SYS" flavor credential. The - server may keep a cache which maps shorthand opaque structures - (passed back by way of an "AUTH_SHORT" style reply verifier) to the - original credentials of the caller. The caller can save network - bandwidth and server cpu cycles by using the shorthand credential. - - The server may flush the shorthand opaque structure at any time. If - this happens, the remote procedure call message will be rejected due - to an authentication error. The reason for the failure will be - "AUTH_REJECTEDCRED". At this point, the client may wish to try the - original "AUTH_SYS" style of credential. - - It should be noted that use of this flavor of authentication does not - guarantee any security for the users or providers of a service, in - itself. The authentication provided by this scheme can be considered - legitimate only when applications using this scheme and the network - can be secured externally, and privileged transport addresses are - used for the communicating end-points (an example of this is the use - of privileged TCP/UDP ports in Unix systems - note that not all - systems enforce privileged transport address mechanisms). - - - -Srinivasan Standards Track [Page 16] - -RFC 1831 Remote Procedure Call Protocol Version 2 August 1995 - - -REFERENCES - - [1] Birrell, A. D. & Nelson, B. J., "Implementing Remote Procedure - Calls", XEROX CSL-83-7, October 1983. - - [2] Cheriton, D., "VMTP: Versatile Message Transaction Protocol", - Preliminary Version 0.3, Stanford University, January 1987. - - [3] Diffie & Hellman, "New Directions in Cryptography", IEEE - Transactions on Information Theory IT-22, November 1976. - - [4] Mills, D., "Network Time Protocol", RFC 1305, UDEL, - March 1992. - - [5] National Bureau of Standards, "Data Encryption Standard", - Federal Information Processing Standards Publication 46, January - 1977. - - [6] Postel, J., "Transmission Control Protocol - DARPA Internet - Program Protocol Specification", STD 7, RFC 793, USC/Information - Sciences Institute, September 1981. - - [7] Postel, J., "User Datagram Protocol", STD 6, RFC 768, - USC/Information Sciences Institute, August 1980. - - [8] Reynolds, J., and Postel, J., "Assigned Numbers", STD 2, - RFC 1700, USC/Information Sciences Institute, October 1994. - - [9] Srinivasan, R., "XDR: External Data Representation Standard", - RFC 1832, Sun Microsystems, Inc., August 1995. - - [10] Miller, S., Neuman, C., Schiller, J., and J. Saltzer, "Section - E.2.1: Kerberos Authentication and Authorization System", - M.I.T. Project Athena, Cambridge, Massachusetts, December 21, - 1987. - - [11] Steiner, J., Neuman, C., and J. Schiller, "Kerberos: An - Authentication Service for Open Network Systems", pp. 191-202 in - Usenix Conference Proceedings, Dallas, Texas, February 1988. - - [12] Kohl, J. and C. Neuman, "The Kerberos Network Authentication - Service (V5)", RFC 1510, Digital Equipment Corporation, - USC/Information Sciences Institute, September 1993. - - - - - - - - -Srinivasan Standards Track [Page 17] - -RFC 1831 Remote Procedure Call Protocol Version 2 August 1995 - - -Security Considerations - - Security issues are not discussed in this memo. - -Author's Address - - Raj Srinivasan - Sun Microsystems, Inc. - ONC Technologies - 2550 Garcia Avenue - M/S MTV-5-40 - Mountain View, CA 94043 - USA - - Phone: 415-336-2478 - Fax: 415-336-6015 - EMail: raj@eng.sun.com - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Srinivasan Standards Track [Page 18] - diff --git a/doc/rfc1964.txt b/doc/rfc1964.txt deleted file mode 100644 index f2960b961..000000000 --- a/doc/rfc1964.txt +++ /dev/null @@ -1,1123 +0,0 @@ - - - - - - -Network Working Group J. Linn -Request for Comments: 1964 OpenVision Technologies -Category: Standards Track June 1996 - - - The Kerberos Version 5 GSS-API Mechanism - -Status of this Memo - - This document specifies an Internet standards track protocol for the - Internet community, and requests discussion and suggestions for - improvements. Please refer to the current edition of the "Internet - Official Protocol Standards" (STD 1) for the standardization state - and status of this protocol. Distribution of this memo is unlimited. - -ABSTRACT - - This specification defines protocols, procedures, and conventions to - be employed by peers implementing the Generic Security Service - Application Program Interface (as specified in RFCs 1508 and 1509) - when using Kerberos Version 5 technology (as specified in RFC 1510). - -ACKNOWLEDGMENTS - - Much of the material in this memo is based on working documents - drafted by John Wray of Digital Equipment Corporation and on - discussions, implementation activities, and interoperability testing - involving Marc Horowitz, Ted Ts'o, and John Wray. Particular thanks - are due to each of these individuals for their contributions towards - development and availability of GSS-API support within the Kerberos - Version 5 code base. - -1. Token Formats - - This section discusses protocol-visible characteristics of the GSS- - API mechanism to be implemented atop Kerberos V5 security technology - per RFC-1508 and RFC-1510; it defines elements of protocol for - interoperability and is independent of language bindings per RFC- - 1509. - - Tokens transferred between GSS-API peers (for security context - management and per-message protection purposes) are defined. The - data elements exchanged between a GSS-API endpoint implementation and - the Kerberos KDC are not specific to GSS-API usage and are therefore - defined within RFC-1510 rather than within this specification. - - - - - - -Linn Standards Track [Page 1] - -RFC 1964 Kerberos Version 5 GSS-API June 1996 - - - To support ongoing experimentation, testing, and evolution of the - specification, the Kerberos V5 GSS-API mechanism as defined in this - and any successor memos will be identified with the following Object - Identifier, as defined in RFC-1510, until the specification is - advanced to the level of Proposed Standard RFC: - - {iso(1), org(3), dod(5), internet(1), security(5), kerberosv5(2)} - - Upon advancement to the level of Proposed Standard RFC, the Kerberos - V5 GSS-API mechanism will be identified by an Object Identifier - having the value: - - {iso(1) member-body(2) United States(840) mit(113554) infosys(1) - gssapi(2) krb5(2)} - -1.1. Context Establishment Tokens - - Per RFC-1508, Appendix B, the initial context establishment token - will be enclosed within framing as follows: - - InitialContextToken ::= - [APPLICATION 0] IMPLICIT SEQUENCE { - thisMech MechType - -- MechType is OBJECT IDENTIFIER - -- representing "Kerberos V5" - innerContextToken ANY DEFINED BY thisMech - -- contents mechanism-specific; - -- ASN.1 usage within innerContextToken - -- is not required - } - - The innerContextToken of the initial context token will consist of a - Kerberos V5 KRB_AP_REQ message, preceded by a two-byte token-id - (TOK_ID) field, which shall contain the value 01 00. - - The above GSS-API framing shall be applied to all tokens emitted by - the Kerberos V5 GSS-API mechanism, including KRB_AP_REP, KRB_ERROR, - context-deletion, and per-message tokens, not just to the initial - token in a context establishment sequence. While not required by - RFC-1508, this enables implementations to perform enhanced error- - checking. The innerContextToken field of context establishment tokens - for the Kerberos V5 GSS-API mechanism will contain a Kerberos message - (KRB_AP_REQ, KRB_AP_REP or KRB_ERROR), preceded by a 2-byte TOK_ID - field containing 01 00 for KRB_AP_REQ messages, 02 00 for KRB_AP_REP - messages and 03 00 for KRB_ERROR messages. - - - - - - -Linn Standards Track [Page 2] - -RFC 1964 Kerberos Version 5 GSS-API June 1996 - - -1.1.1. Initial Token - - Relevant KRB_AP_REQ syntax (from RFC-1510) is as follows: - - AP-REQ ::= [APPLICATION 14] SEQUENCE { - pvno [0] INTEGER, -- indicates Version 5 - msg-type [1] INTEGER, -- indicates KRB_AP_REQ - ap-options[2] APOptions, - ticket[3] Ticket, - authenticator[4] EncryptedData - } - - APOptions ::= BIT STRING { - reserved (0), - use-session-key (1), - mutual-required (2) - } - - Ticket ::= [APPLICATION 1] SEQUENCE { - tkt-vno [0] INTEGER, -- indicates Version 5 - realm [1] Realm, - sname [2] PrincipalName, - enc-part [3] EncryptedData - } - - -- Encrypted part of ticket - EncTicketPart ::= [APPLICATION 3] SEQUENCE { - flags[0] TicketFlags, - key[1] EncryptionKey, - crealm[2] Realm, - cname[3] PrincipalName, - transited[4] TransitedEncoding, - authtime[5] KerberosTime, - starttime[6] KerberosTime OPTIONAL, - endtime[7] KerberosTime, - renew-till[8] KerberosTime OPTIONAL, - caddr[9] HostAddresses OPTIONAL, - authorization-data[10] AuthorizationData OPTIONAL - } - - -- Unencrypted authenticator - Authenticator ::= [APPLICATION 2] SEQUENCE { - authenticator-vno[0] INTEGER, - crealm[1] Realm, - cname[2] PrincipalName, - cksum[3] Checksum OPTIONAL, - cusec[4] INTEGER, - ctime[5] KerberosTime, - - - -Linn Standards Track [Page 3] - -RFC 1964 Kerberos Version 5 GSS-API June 1996 - - - subkey[6] EncryptionKey OPTIONAL, - seq-number[7] INTEGER OPTIONAL, - authorization-data[8] AuthorizationData OPTIONAL - } - - For purposes of this specification, the authenticator shall include - the optional sequence number, and the checksum field shall be used to - convey channel binding, service flags, and optional delegation - information. The checksum will have a type of 0x8003 (a value being - registered within the Kerberos protocol specification), and a value - field of at least 24 bytes in length. The length of the value field - is extended beyond 24 bytes if and only if an optional facility to - carry a Kerberos-defined KRB_CRED message for delegation purposes is - supported by an implementation and active on a context. When - delegation is active, a TGT with its FORWARDABLE flag set will be - transferred within the KRB_CRED message. - - The checksum value field's format is as follows: - - Byte Name Description - 0..3 Lgth Number of bytes in Bnd field; - Currently contains hex 10 00 00 00 - (16, represented in little-endian form) - 4..19 Bnd MD5 hash of channel bindings, taken over all non-null - components of bindings, in order of declaration. - Integer fields within channel bindings are represented - in little-endian order for the purposes of the MD5 - calculation. - 20..23 Flags Bit vector of context-establishment flags, - with values consistent with RFC-1509, p. 41: - GSS_C_DELEG_FLAG: 1 - GSS_C_MUTUAL_FLAG: 2 - GSS_C_REPLAY_FLAG: 4 - GSS_C_SEQUENCE_FLAG: 8 - GSS_C_CONF_FLAG: 16 - GSS_C_INTEG_FLAG: 32 - The resulting bit vector is encoded into bytes 20..23 - in little-endian form. - 24..25 DlgOpt The Delegation Option identifier (=1) [optional] - 26..27 Dlgth The length of the Deleg field. [optional] - 28..n Deleg A KRB_CRED message (n = Dlgth + 29) [optional] - - In computing the contents of the "Bnd" field, the following detailed - points apply: - - (1) Each integer field shall be formatted into four bytes, using - little-endian byte ordering, for purposes of MD5 hash - computation. - - - -Linn Standards Track [Page 4] - -RFC 1964 Kerberos Version 5 GSS-API June 1996 - - - (2) All input length fields within gss_buffer_desc elements of a - gss_channel_bindings_struct, even those which are zero-valued, - shall be included in the hash calculation; the value elements of - gss_buffer_desc elements shall be dereferenced, and the - resulting data shall be included within the hash computation, - only for the case of gss_buffer_desc elements having non-zero - length specifiers. - - (3) If the caller passes the value GSS_C_NO_BINDINGS instead of - a valid channel bindings structure, the Bnd field shall be set - to 16 zero-valued bytes. - - In the initial Kerberos V5 GSS-API mechanism token (KRB_AP_REQ token) - from initiator to target, the GSS_C_DELEG_FLAG, GSS_C_MUTUAL_FLAG, - GSS_C_REPLAY_FLAG, and GSS_C_SEQUENCE_FLAG values shall each be set - as the logical AND of the initiator's corresponding request flag to - GSS_Init_sec_context() and a Boolean indicator of whether that - optional service is available to GSS_Init_sec_context()'s caller. - GSS_C_CONF_FLAG and GSS_C_INTEG_FLAG, for which no corresponding - context-level input indicator flags to GSS_Init_sec_context() exist, - shall each be set to indicate whether their respective per-message - protection services are available for use on the context being - established. - - When input source address channel binding values are provided by a - caller (i.e., unless the input argument is GSS_C_NO_BINDINGS or the - source address specifier value within the input structure is - GSS_C_NULL_ADDRTYPE), and the corresponding token received from the - context's peer bears address restrictions, it is recommended that an - implementation of the Kerberos V5 GSS-API mechanism should check that - the source address as provided by the caller matches that in the - received token, and should return the GSS_S_BAD_BINDINGS major_status - value if a mismatch is detected. Note: discussion is ongoing about - the strength of recommendation to be made in this area, and on the - circumstances under which such a recommendation should be applicable; - implementors are therefore advised that changes on this matter may be - included in subsequent versions of this specification. - -1.1.2. Response Tokens - - A context establishment sequence based on the Kerberos V5 mechanism - will perform one-way authentication (without confirmation or any - return token from target to initiator in response to the initiator's - KRB_AP_REQ) if the mutual_req bit is not set in the application's - call to GSS_Init_sec_context(). Applications requiring confirmation - that their authentication was successful should request mutual - authentication, resulting in a "mutual-required" indication within - KRB_AP_REQ APoptions and the setting of the mutual_req bit in the - - - -Linn Standards Track [Page 5] - -RFC 1964 Kerberos Version 5 GSS-API June 1996 - - - flags field of the authenticator checksum. In response to such a - request, the context target will reply to the initiator with a token - containing either a KRB_AP_REP or KRB_ERROR, completing the mutual - context establishment exchange. - - Relevant KRB_AP_REP syntax is as follows: - - AP-REP ::= [APPLICATION 15] SEQUENCE { - pvno [0] INTEGER, -- represents Kerberos V5 - msg-type [1] INTEGER, -- represents KRB_AP_REP - enc-part [2] EncryptedData - } - - EncAPRepPart ::= [APPLICATION 27] SEQUENCE { - ctime [0] KerberosTime, - cusec [1] INTEGER, - subkey [2] EncryptionKey OPTIONAL, - seq-number [3] INTEGER OPTIONAL - } - - The optional seq-number element within the AP-REP's EncAPRepPart - shall be included. - - The syntax of KRB_ERROR is as follows: - - KRB-ERROR ::= [APPLICATION 30] SEQUENCE { - pvno[0] INTEGER, - msg-type[1] INTEGER, - ctime[2] KerberosTime OPTIONAL, - cusec[3] INTEGER OPTIONAL, - stime[4] KerberosTime, - susec[5] INTEGER, - error-code[6] INTEGER, - crealm[7] Realm OPTIONAL, - cname[8] PrincipalName OPTIONAL, - realm[9] Realm, -- Correct realm - sname[10] PrincipalName, -- Correct name - e-text[11] GeneralString OPTIONAL, - e-data[12] OCTET STRING OPTIONAL - } - - Values to be transferred in the error-code field of a KRB-ERROR - message are defined in [RFC-1510], not in this specification. - - - - - - - - -Linn Standards Track [Page 6] - -RFC 1964 Kerberos Version 5 GSS-API June 1996 - - -1.2. Per-Message and Context Deletion Tokens - - Three classes of tokens are defined in this section: "MIC" tokens, - emitted by calls to GSS_GetMIC() (formerly GSS_Sign()) and consumed - by calls to GSS_VerifyMIC() (formerly GSS_Verify()), "Wrap" tokens, - emitted by calls to GSS_Wrap() (formerly GSS_Seal()) and consumed by - calls to GSS_Unwrap() (formerly GSS_Unseal()), and context deletion - tokens, emitted by calls to GSS_Delete_sec_context() and consumed by - calls to GSS_Process_context_token(). Note: References to GSS-API - per-message routines in the remainder of this specification will be - based on those routines' newer recommended names rather than those - names' predecessors. - - Several variants of cryptographic keys are used in generation and - processing of per-message tokens: - - (1) context key: uses Kerberos session key (or subkey, if - present in authenticator emitted by context initiator) directly - - (2) confidentiality key: forms variant of context key by - exclusive-OR with the hexadecimal constant f0f0f0f0f0f0f0f0. - - (3) MD2.5 seed key: forms variant of context key by reversing - the bytes of the context key (i.e. if the original key is the - 8-byte sequence {aa, bb, cc, dd, ee, ff, gg, hh}, the seed key - will be {hh, gg, ff, ee, dd, cc, bb, aa}). - -1.2.1. Per-message Tokens - MIC - -Use of the GSS_GetMIC() call yields a token, separate from the user -data being protected, which can be used to verify the integrity of -that data as received. The token has the following format: - - Byte no Name Description - 0..1 TOK_ID Identification field. - Tokens emitted by GSS_GetMIC() contain - the hex value 01 01 in this field. - 2..3 SGN_ALG Integrity algorithm indicator. - 00 00 - DES MAC MD5 - 01 00 - MD2.5 - 02 00 - DES MAC - 4..7 Filler Contains ff ff ff ff - 8..15 SND_SEQ Sequence number field. - 16..23 SGN_CKSUM Checksum of "to-be-signed data", - calculated according to algorithm - specified in SGN_ALG field. - - - - - -Linn Standards Track [Page 7] - -RFC 1964 Kerberos Version 5 GSS-API June 1996 - - - GSS-API tokens must be encapsulated within the higher-level protocol - by the application; no embedded length field is necessary. - -1.2.1.1. Checksum - - Checksum calculation procedure (common to all algorithms): Checksums - are calculated over the data field, logically prepended by the first - 8 bytes of the plaintext packet header. The resulting value binds - the data to the packet type and signature algorithm identifier - fields. - - DES MAC MD5 algorithm: The checksum is formed by computing an MD5 - [RFC-1321] hash over the plaintext data, and then computing a DES-CBC - MAC on the 16-byte MD5 result. A standard 64-bit DES-CBC MAC is - computed per [FIPS-PUB-113], employing the context key and a zero IV. - The 8-byte result is stored in the SGN_CKSUM field. - - MD2.5 algorithm: The checksum is formed by first DES-CBC encrypting a - 16-byte zero-block, using a zero IV and a key formed by reversing the - bytes of the context key (i.e. if the original key is the 8-byte - sequence {aa, bb, cc, dd, ee, ff, gg, hh}, the checksum key will be - {hh, gg, ff, ee, dd, cc, bb, aa}). The resulting 16-byte value is - logically prepended to the to-be-signed data. A standard MD5 - checksum is calculated over the combined data, and the first 8 bytes - of the result are stored in the SGN_CKSUM field. Note 1: we refer to - this algorithm informally as "MD2.5" to connote the fact that it uses - half of the 128 bits generated by MD5; use of only a subset of the - MD5 bits is intended to protect against the prospect that data could - be postfixed to an existing message with corresponding modifications - being made to the checksum. Note 2: This algorithm is fairly novel - and has received more limited evaluation than that to which other - integrity algorithms have been subjected. An initial, limited - evaluation indicates that it may be significantly weaker than DES MAC - MD5. - - DES-MAC algorithm: A standard 64-bit DES-CBC MAC is computed on the - plaintext data per [FIPS-PUB-113], employing the context key and a - zero IV. Padding procedures to accomodate plaintext data lengths - which may not be integral multiples of 8 bytes are defined in [FIPS- - PUB-113]. The result is an 8-byte value, which is stored in the - SGN_CKSUM field. Support for this algorithm may not be present in - all implementations. - -1.2.1.2. Sequence Number - - Sequence number field: The 8 byte plaintext sequence number field is - formed from the sender's four-byte sequence number as follows. If - the four bytes of the sender's sequence number are named s0, s1, s2 - - - -Linn Standards Track [Page 8] - -RFC 1964 Kerberos Version 5 GSS-API June 1996 - - - and s3 (from least to most significant), the plaintext sequence - number field is the 8 byte sequence: (s0, s1, s2, s3, di, di, di, - di), where 'di' is the direction-indicator (Hex 0 - sender is the - context initiator, Hex FF - sender is the context acceptor). The - field is then DES-CBC encrypted using the context key and an IV - formed from the first 8 bytes of the previously calculated SGN_CKSUM - field. After sending a GSS_GetMIC() or GSS_Wrap() token, the sender's - sequence number is incremented by one. - - The receiver of the token will first verify the SGN_CKSUM field. If - valid, the sequence number field may be decrypted and compared to the - expected sequence number. The repetition of the (effectively 1-bit) - direction indicator within the sequence number field provides - redundancy so that the receiver may verify that the decryption - succeeded. - - Since the checksum computation is used as an IV to the sequence - number decryption, attempts to splice a checksum and sequence number - from different messages will be detected. The direction indicator - will detect packets that have been maliciously reflected. - - The sequence number provides a basis for detection of replayed - tokens. Replay detection can be performed using state information - retained on received sequence numbers, interpreted in conjunction - with the security context on which they arrive. - - Provision of per-message replay and out-of-sequence detection - services is optional for implementations of the Kerberos V5 GSS-API - mechanism. Further, it is recommended that implementations of the - Kerberos V5 GSS-API mechanism which offer these services should honor - a caller's request that the services be disabled on a context. - Specifically, if replay_det_req_flag is input FALSE, replay_det_state - should be returned FALSE and the GSS_DUPLICATE_TOKEN and - GSS_OLD_TOKEN stati should not be indicated as a result of duplicate - detection when tokens are processed; if sequence_req_flag is input - FALSE, sequence_state should be returned FALSE and - GSS_DUPLICATE_TOKEN, GSS_OLD_TOKEN, and GSS_UNSEQ_TOKEN stati should - not be indicated as a result of out-of-sequence detection when tokens - are processed. - -1.2.2. Per-message Tokens - Wrap - - Use of the GSS_Wrap() call yields a token which encapsulates the - input user data (optionally encrypted) along with associated - integrity check quantities. The token emitted by GSS_Wrap() consists - of an integrity header whose format is identical to that emitted by - GSS_GetMIC() (except that the TOK_ID field contains the value 02 01), - followed by a body portion that contains either the plaintext data - - - -Linn Standards Track [Page 9] - -RFC 1964 Kerberos Version 5 GSS-API June 1996 - - - (if SEAL_ALG = ff ff) or encrypted data for any other supported value - of SEAL_ALG. Currently, only SEAL_ALG = 00 00 is supported, and - means that DES-CBC encryption is being used to protect the data. - - The GSS_Wrap() token has the following format: - - Byte no Name Description - 0..1 TOK_ID Identification field. - Tokens emitted by GSS_Wrap() contain - the hex value 02 01 in this field. - 2..3 SGN_ALG Checksum algorithm indicator. - 00 00 - DES MAC MD5 - 01 00 - MD2.5 - 02 00 - DES MAC - 4..5 SEAL_ALG ff ff - none - 00 00 - DES - 6..7 Filler Contains ff ff - 8..15 SND_SEQ Encrypted sequence number field. - 16..23 SGN_CKSUM Checksum of plaintext padded data, - calculated according to algorithm - specified in SGN_ALG field. - 24..last Data encrypted or plaintext padded data - - GSS-API tokens must be encapsulated within the higher-level protocol - by the application; no embedded length field is necessary. - -1.2.2.1. Checksum - - Checksum calculation procedure (common to all algorithms): Checksums - are calculated over the plaintext padded data field, logically - prepended by the first 8 bytes of the plaintext packet header. The - resulting signature binds the data to the packet type, protocol - version, and signature algorithm identifier fields. - - DES MAC MD5 algorithm: The checksum is formed by computing an MD5 - hash over the plaintext padded data, and then computing a DES-CBC MAC - on the 16-byte MD5 result. A standard 64-bit DES-CBC MAC is computed - per [FIPS-PUB-113], employing the context key and a zero IV. The 8- - byte result is stored in the SGN_CKSUM field. - - MD2.5 algorithm: The checksum is formed by first DES-CBC encrypting a - 16-byte zero-block, using a zero IV and a key formed by reversing the - bytes of the context key (i.e., if the original key is the 8-byte - sequence {aa, bb, cc, dd, ee, ff, gg, hh}, the checksum key will be - {hh, gg, ff, ee, dd, cc, bb, aa}). The resulting 16-byte value is - logically pre-pended to the "to-be-signed data". A standard MD5 - checksum is calculated over the combined data, and the first 8 bytes - of the result are stored in the SGN_CKSUM field. - - - -Linn Standards Track [Page 10] - -RFC 1964 Kerberos Version 5 GSS-API June 1996 - - - DES-MAC algorithm: A standard 64-bit DES-CBC MAC is computed on the - plaintext padded data per [FIPS-PUB-113], employing the context key - and a zero IV. The plaintext padded data is already assured to be an - integral multiple of 8 bytes; no additional padding is required or - applied in order to accomplish MAC calculation. The result is an 8- - byte value, which is stored in the SGN_CKSUM field. Support for this - lgorithm may not be present in all implementations. - -1.2.2.2. Sequence Number - - Sequence number field: The 8 byte plaintext sequence number field is - formed from the sender's four-byte sequence number as follows. If - the four bytes of the sender's sequence number are named s0, s1, s2 - and s3 (from least to most significant), the plaintext sequence - number field is the 8 byte sequence: (s0, s1, s2, s3, di, di, di, - di), where 'di' is the direction-indicator (Hex 0 - sender is the - context initiator, Hex FF - sender is the context acceptor). - - The field is then DES-CBC encrypted using the context key and an IV - formed from the first 8 bytes of the SEAL_CKSUM field. - - After sending a GSS_GetMIC() or GSS_Wrap() token, the sender's - sequence numbers are incremented by one. - -1.2.2.3. Padding - - Data padding: Before encryption and/or signature calculation, - plaintext data is padded to the next highest multiple of 8 bytes, by - appending between 1 and 8 bytes, the value of each such byte being - the total number of pad bytes. For example, given data of length 20 - bytes, four pad bytes will be appended, and each byte will contain - the hex value 04. An 8-byte random confounder is prepended to the - data, and signatures are calculated over the resulting padded - plaintext. - - After padding, the data is encrypted according to the algorithm - specified in the SEAL_ALG field. For SEAL_ALG=DES (the only non-null - algorithm currently supported), the data is encrypted using DES-CBC, - with an IV of zero. The key used is derived from the established - context key by XOR-ing the context key with the hexadecimal constant - f0f0f0f0f0f0f0f0. - -1.2.3. Context deletion token - - The token emitted by GSS_Delete_sec_context() is based on the packet - format for tokens emitted by GSS_GetMIC(). The context-deletion - token has the following format: - - - - -Linn Standards Track [Page 11] - -RFC 1964 Kerberos Version 5 GSS-API June 1996 - - - Byte no Name Description - 0..1 TOK_ID Identification field. - Tokens emitted by - GSS_Delete_sec_context() contain - the hex value 01 02 in this field. - 2..3 SGN_ALG Integrity algorithm indicator. - 00 00 - DES MAC MD5 - 01 00 - MD2.5 - 02 00 - DES MAC - 4..7 Filler Contains ff ff ff ff - 8..15 SND_SEQ Sequence number field. - 16..23 SGN_CKSUM Checksum of "to-be-signed data", - calculated according to algorithm - specified in SGN_ALG field. - - SGN_ALG and SND_SEQ will be calculated as for tokens emitted by - GSS_GetMIC(). The SGN_CKSUM will be calculated as for tokens emitted - by GSS_GetMIC(), except that the user-data component of the "to-be- - signed" data will be a zero-length string. - -2. Name Types and Object Identifiers - - This section discusses the name types which may be passed as input to - the Kerberos V5 GSS-API mechanism's GSS_Import_name() call, and their - associated identifier values. It defines interface elements in - support of portability, and assumes use of C language bindings per - RFC-1509. In addition to specifying OID values for name type - identifiers, symbolic names are included and recommended to GSS-API - implementors in the interests of convenience to callers. It is - understood that not all implementations of the Kerberos V5 GSS-API - mechanism need support all name types in this list, and that - additional name forms will likely be added to this list over time. - Further, the definitions of some or all name types may later migrate - to other, mechanism-independent, specifications. The occurrence of a - name type in this specification is specifically not intended to - suggest that the type may be supported only by an implementation of - the Kerberos V5 mechanism. In particular, the occurrence of the - string "_KRB5_" in the symbolic name strings constitutes a means to - unambiguously register the name strings, avoiding collision with - other documents; it is not meant to limit the name types' usage or - applicability. - - For purposes of clarification to GSS-API implementors, this section's - discussion of some name forms describes means through which those - forms can be supported with existing Kerberos technology. These - discussions are not intended to preclude alternative implementation - strategies for support of the name forms within Kerberos mechanisms - or mechanisms based on other technologies. To enhance application - - - -Linn Standards Track [Page 12] - -RFC 1964 Kerberos Version 5 GSS-API June 1996 - - - portability, implementors of mechanisms are encouraged to support - name forms as defined in this section, even if their mechanisms are - independent of Kerberos V5. - -2.1. Mandatory Name Forms - - This section discusses name forms which are to be supported by all - conformant implementations of the Kerberos V5 GSS-API mechanism. - -2.1.1. Kerberos Principal Name Form - - This name form shall be represented by the Object Identifier {iso(1) - member-body(2) United States(840) mit(113554) infosys(1) gssapi(2) - krb5(2) krb5_name(1)}. The recommended symbolic name for this type - is "GSS_KRB5_NT_PRINCIPAL_NAME". - - This name type corresponds to the single-string representation of a - Kerberos name. (Within the MIT Kerberos V5 implementation, such - names are parseable with the krb5_parse_name() function.) The - elements included within this name representation are as follows, - proceeding from the beginning of the string: - - (1) One or more principal name components; if more than one - principal name component is included, the components are - separated by `/`. Arbitrary octets may be included within - principal name components, with the following constraints and - special considerations: - - (1a) Any occurrence of the characters `@` or `/` within a - name component must be immediately preceded by the `\` - quoting character, to prevent interpretation as a component - or realm separator. - - (1b) The ASCII newline, tab, backspace, and null characters - may occur directly within the component or may be - represented, respectively, by `\n`, `\t`, `\b`, or `\0`. - - (1c) If the `\` quoting character occurs outside the contexts - described in (1a) and (1b) above, the following character is - interpreted literally. As a special case, this allows the - doubled representation `\\` to represent a single occurrence - of the quoting character. - - (1d) An occurrence of the `\` quoting character as the last - character of a component is illegal. - - - - - - -Linn Standards Track [Page 13] - -RFC 1964 Kerberos Version 5 GSS-API June 1996 - - - (2) Optionally, a `@` character, signifying that a realm name - immediately follows. If no realm name element is included, the - local realm name is assumed. The `/` , `:`, and null characters - may not occur within a realm name; the `@`, newline, tab, and - backspace characters may be included using the quoting - conventions described in (1a), (1b), and (1c) above. - -2.1.2. Host-Based Service Name Form - - This name form has been incorporated at the mechanism-independent - GSS-API level as of GSS-API, Version 2. This subsection retains the - Object Identifier and symbolic name assignments previously made at - the Kerberos V5 GSS-API mechanism level, and adopts the definition as - promoted to the mechanism-independent level. - - This name form shall be represented by the Object Identifier {iso(1) - member-body(2) United States(840) mit(113554) infosys(1) gssapi(2) - generic(1) service_name(4)}. The previously recommended symbolic - name for this type is "GSS_KRB5_NT_HOSTBASED_SERVICE_NAME". The - currently preferred symbolic name for this type is - "GSS_C_NT_HOSTBASED_SERVICE". - - This name type is used to represent services associated with host - computers. This name form is constructed using two elements, - "service" and "hostname", as follows: - - service@hostname - - When a reference to a name of this type is resolved, the "hostname" - is canonicalized by attempting a DNS lookup and using the fully- - qualified domain name which is returned, or by using the "hostname" - as provided if the DNS lookup fails. The canonicalization operation - also maps the host's name into lower-case characters. - - The "hostname" element may be omitted. If no "@" separator is - included, the entire name is interpreted as the service specifier, - with the "hostname" defaulted to the canonicalized name of the local - host. - - Values for the "service" element will be registered with the IANA. - -2.1.3. Exported Name Object Form for Kerberos V5 Mechanism - - Support for this name form is not required for GSS-V1 - implementations, but will be required for use in conjunction with the - GSS_Export_name() call planned for GSS-API Version 2. Use of this - name form will be signified by a "GSS-API Exported Name Object" OID - value which will be defined at the mechanism-independent level for - - - -Linn Standards Track [Page 14] - -RFC 1964 Kerberos Version 5 GSS-API June 1996 - - - GSS-API Version 2. - - This name type represents a self-describing object, whose framing - structure will be defined at the mechanism-independent level for - GSS-API Version 2. When generated by the Kerberos V5 mechanism, the - Mechanism OID within the exportable name shall be that of the - Kerberos V5 mechanism. The name component within the exportable name - shall be a contiguous string with structure as defined for the - Kerberos Principal Name Form. - - In order to achieve a distinguished encoding for comparison purposes, - the following additional constraints are imposed on the export - operation: - - (1) all occurrences of the characters `@`, `/`, and `\` within - principal components or realm names shall be quoted with an - immediately-preceding `\`. - - (2) all occurrences of the null, backspace, tab, or newline - characters within principal components or realm names will be - represented, respectively, with `\0`, `\b`, `\t`, or `\n`. - - (3) the `\` quoting character shall not be emitted within an - exported name except to accomodate cases (1) and (2). - -2.2. Optional Name Forms - - This section discusses additional name forms which may optionally be - supported by implementations of the Kerberos V5 GSS-API mechanism. - It is recognized that some of the name forms cited here are derived - from UNIX(tm) operating system platforms; some listed forms may be - irrelevant to non-UNIX platforms, and definition of additional forms - corresponding to such platforms may also be appropriate. It is also - recognized that OS-specific functions outside GSS-API are likely to - exist in order to perform translations among these forms, and that - GSS-API implementations supporting these forms may themselves be - layered atop such OS-specific functions. Inclusion of this support - within GSS-API implementations is intended as a convenience to - applications. - -2.2.1. User Name Form - - This name form shall be represented by the Object Identifier {iso(1) - member-body(2) United States(840) mit(113554) infosys(1) gssapi(2) - generic(1) user_name(1)}. The recommended symbolic name for this - type is "GSS_KRB5_NT_USER_NAME". - - This name type is used to indicate a named user on a local system. - - - -Linn Standards Track [Page 15] - -RFC 1964 Kerberos Version 5 GSS-API June 1996 - - - Its interpretation is OS-specific. This name form is constructed as: - - username - - Assuming that users' principal names are the same as their local - operating system names, an implementation of GSS_Import_name() based - on Kerberos V5 technology can process names of this form by - postfixing an "@" sign and the name of the local realm. - -2.2.2. Machine UID Form - - This name form shall be represented by the Object Identifier {iso(1) - member-body(2) United States(840) mit(113554) infosys(1) gssapi(2) - generic(1) machine_uid_name(2)}. The recommended symbolic name for - this type is "GSS_KRB5_NT_MACHINE_UID_NAME". - - This name type is used to indicate a numeric user identifier - corresponding to a user on a local system. Its interpretation is - OS-specific. The gss_buffer_desc representing a name of this type - should contain a locally-significant uid_t, represented in host byte - order. The GSS_Import_name() operation resolves this uid into a - username, which is then treated as the User Name Form. - -2.2.3. String UID Form - - This name form shall be represented by the Object Identifier {iso(1) - member-body(2) United States(840) mit(113554) infosys(1) gssapi(2) - generic(1) string_uid_name(3)}. The recommended symbolic name for - this type is "GSS_KRB5_NT_STRING_UID_NAME". - - This name type is used to indicate a string of digits representing - the numeric user identifier of a user on a local system. Its - interpretation is OS-specific. This name type is similar to the - Machine UID Form, except that the buffer contains a string - representing the uid_t. - -3. Credentials Management - - The Kerberos V5 protocol uses different credentials (in the GSSAPI - sense) for initiating and accepting security contexts. Normal - clients receive a ticket-granting ticket (TGT) and an associated - session key at "login" time; the pair of a TGT and its corresponding - session key forms a credential which is suitable for initiating - security contexts. A ticket-granting ticket, its session key, and - any other (ticket, key) pairs obtained through use of the ticket- - granting-ticket, are typically stored in a Kerberos V5 credentials - cache, sometimes known as a ticket file. - - - - -Linn Standards Track [Page 16] - -RFC 1964 Kerberos Version 5 GSS-API June 1996 - - - The encryption key used by the Kerberos server to seal tickets for a - particular application service forms the credentials suitable for - accepting security contexts. These service keys are typically stored - in a Kerberos V5 key table, or srvtab file. In addition to their use - as accepting credentials, these service keys may also be used to - obtain initiating credentials for their service principal. - - The Kerberos V5 mechanism's credential handle may contain references - to either or both types of credentials. It is a local matter how the - Kerberos V5 mechanism implementation finds the appropriate Kerberos - V5 credentials cache or key table. - - However, when the Kerberos V5 mechanism attempts to obtain initiating - credentials for a service principal which are not available in a - credentials cache, and the key for that service principal is - available in a Kerberos V5 key table, the mechanism should use the - service key to obtain initiating credentials for that service. This - should be accomplished by requesting a ticket-granting-ticket from - the Kerberos Key Distribution Center (KDC), and decrypting the KDC's - reply using the service key. - -4. Parameter Definitions - - This section defines parameter values used by the Kerberos V5 GSS-API - mechanism. It defines interface elements in support of portability, - and assumes use of C language bindings per RFC-1509. - -4.1. Minor Status Codes - - This section recommends common symbolic names for minor_status values - to be returned by the Kerberos V5 GSS-API mechanism. Use of these - definitions will enable independent implementors to enhance - application portability across different implementations of the - mechanism defined in this specification. (In all cases, - implementations of GSS_Display_status() will enable callers to - convert minor_status indicators to text representations.) Each - implementation should make available, through include files or other - means, a facility to translate these symbolic names into the concrete - values which a particular GSS-API implementation uses to represent - the minor_status values specified in this section. - - It is recognized that this list may grow over time, and that the need - for additional minor_status codes specific to particular - implementations may arise. It is recommended, however, that - implementations should return a minor_status value as defined on a - mechanism-wide basis within this section when that code is accurately - representative of reportable status rather than using a separate, - implementation-defined code. - - - -Linn Standards Track [Page 17] - -RFC 1964 Kerberos Version 5 GSS-API June 1996 - - -4.1.1. Non-Kerberos-specific codes - - GSS_KRB5_S_G_BAD_SERVICE_NAME - /* "No @ in SERVICE-NAME name string" */ - GSS_KRB5_S_G_BAD_STRING_UID - /* "STRING-UID-NAME contains nondigits" */ - GSS_KRB5_S_G_NOUSER - /* "UID does not resolve to username" */ - GSS_KRB5_S_G_VALIDATE_FAILED - /* "Validation error" */ - GSS_KRB5_S_G_BUFFER_ALLOC - /* "Couldn't allocate gss_buffer_t data" */ - GSS_KRB5_S_G_BAD_MSG_CTX - /* "Message context invalid" */ - GSS_KRB5_S_G_WRONG_SIZE - /* "Buffer is the wrong size" */ - GSS_KRB5_S_G_BAD_USAGE - /* "Credential usage type is unknown" */ - GSS_KRB5_S_G_UNKNOWN_QOP - /* "Unknown quality of protection specified" */ - -4.1.2. Kerberos-specific-codes - - GSS_KRB5_S_KG_CCACHE_NOMATCH - /* "Principal in credential cache does not match desired name" */ - GSS_KRB5_S_KG_KEYTAB_NOMATCH - /* "No principal in keytab matches desired name" */ - GSS_KRB5_S_KG_TGT_MISSING - /* "Credential cache has no TGT" */ - GSS_KRB5_S_KG_NO_SUBKEY - /* "Authenticator has no subkey" */ - GSS_KRB5_S_KG_CONTEXT_ESTABLISHED - /* "Context is already fully established" */ - GSS_KRB5_S_KG_BAD_SIGN_TYPE - /* "Unknown signature type in token" */ - GSS_KRB5_S_KG_BAD_LENGTH - /* "Invalid field length in token" */ - GSS_KRB5_S_KG_CTX_INCOMPLETE - /* "Attempt to use incomplete security context" */ - -4.2. Quality of Protection Values - - This section defines Quality of Protection (QOP) values to be used - with the Kerberos V5 GSS-API mechanism as input to GSS_Wrap() and - GSS_GetMIC() routines in order to select among alternate integrity - and confidentiality algorithms. Additional QOP values may be added in - future versions of this specification. Non-overlapping bit positions - are and will be employed in order that both integrity and - - - -Linn Standards Track [Page 18] - -RFC 1964 Kerberos Version 5 GSS-API June 1996 - - - confidentiality QOP may be selected within a single parameter, via - inclusive-OR of the specified integrity and confidentiality values. - -4.2.1. Integrity Algorithms - - The following Quality of Protection (QOP) values are currently - defined for the Kerberos V5 GSS-API mechanism, and are used to select - among alternate integrity checking algorithms. - - GSS_KRB5_INTEG_C_QOP_MD5 (numeric value: 1) - /* Integrity using partial MD5 ("MD2.5") of plaintext */ - - GSS_KRB5_INTEG_C_QOP_DES_MD5 (numeric value: 2) - /* Integrity using DES MAC of MD5 of plaintext */ - - GSS_KRB5_INTEG_C_QOP_DES_MAC (numeric value: 3) - /* Integrity using DES MAC of plaintext */ - -4.2.2. Confidentiality Algorithms - - Only one confidentiality QOP value is currently defined for the - Kerberos V5 GSS-API mechanism: - - GSS_KRB5_CONF_C_QOP_DES (numeric value: 0) - /* Confidentiality with DES */ - - Note: confidentiality QOP should be indicated only by GSS-API calls - capable of providing confidentiality services. If non-zero - confidentiality QOP values are defined in future to represent - different algorithms, therefore, the bit positions containing those - values should be cleared before being returned by implementations of - GSS_GetMIC() and GSS_VerifyMIC(). - -4.3. Buffer Sizes - - All implementations of this specification shall be capable of - accepting buffers of at least 16 Kbytes as input to GSS_GetMIC(), - GSS_VerifyMIC(), and GSS_Wrap(), and shall be capable of accepting - the output_token generated by GSS_Wrap() for a 16 Kbyte input buffer - as input to GSS_Unwrap(). Support for larger buffer sizes is optional - but recommended. - - - - - - - - - - -Linn Standards Track [Page 19] - -RFC 1964 Kerberos Version 5 GSS-API June 1996 - - -5. Security Considerations - - Security issues are discussed throughout this memo. - -6. References - - - [RFC-1321]: Rivest, R., "The MD5 Message-Digest Algorithm", RFC - 1321, April 1992. - - [RFC-1508]: Linn, J., "Generic Security Service Application Program - Interface", RFC 1508, September 1993. - - [RFC-1509]: Wray, J., "Generic Security Service Application Program - Interface: C-bindings", RFC 1509, September 1993. - - [RFC-1510]: Kohl, J., and C. Neuman, "The Kerberos Network - Authentication Service (V5)", RFC 1510, September 1993. - - [FIPS-PUB-113]: National Bureau of Standards, Federal Information - Processing Standard 113, "Computer Data Authentication", May 1985. - -AUTHOR'S ADDRESS - - John Linn - OpenVision Technologies - One Main St. - Cambridge, MA 02142 USA - - Phone: +1 617.374.2245 - EMail: John.Linn@ov.com - - - - - - - - - - - - - - - - - - - - -Linn Standards Track [Page 20] - diff --git a/doc/rfc2078.txt b/doc/rfc2078.txt deleted file mode 100644 index 1dd1e4aeb..000000000 --- a/doc/rfc2078.txt +++ /dev/null @@ -1,4763 +0,0 @@ - - - - - - -Network Working Group J. Linn -Request for Comments: 2078 OpenVision Technologies -Category: Standards Track January 1997 -Obsoletes: 1508 - - - Generic Security Service Application Program Interface, Version 2 - -Status of this Memo - - This document specifies an Internet standards track protocol for the - Internet community, and requests discussion and suggestions for - improvements. Please refer to the current edition of the "Internet - Official Protocol Standards" (STD 1) for the standardization state - and status of this protocol. Distribution of this memo is unlimited. - -Abstract - - The Generic Security Service Application Program Interface (GSS-API), - as defined in RFC-1508, provides security services to callers in a - generic fashion, supportable with a range of underlying mechanisms - and technologies and hence allowing source-level portability of - applications to different environments. This specification defines - GSS-API services and primitives at a level independent of underlying - mechanism and programming language environment, and is to be - complemented by other, related specifications: - - documents defining specific parameter bindings for particular - language environments - - documents defining token formats, protocols, and procedures to be - implemented in order to realize GSS-API services atop particular - security mechanisms - - This memo revises RFC-1508, making specific, incremental changes in - response to implementation experience and liaison requests. It is - intended, therefore, that this memo or a successor version thereto - will become the basis for subsequent progression of the GSS-API - specification on the standards track. - -Table of Contents - - 1: GSS-API Characteristics and Concepts.......................... 3 - 1.1: GSS-API Constructs.......................................... 6 - 1.1.1: Credentials.............................................. 6 - 1.1.1.1: Credential Constructs and Concepts...................... 6 - 1.1.1.2: Credential Management................................... 7 - 1.1.1.3: Default Credential Resolution........................... 8 - - - -Linn Standards Track [Page 1] - -RFC 2078 GSS-API January 1997 - - - 1.1.2: Tokens.................................................... 9 - 1.1.3: Security Contexts........................................ 10 - 1.1.4: Mechanism Types.......................................... 11 - 1.1.5: Naming................................................... 12 - 1.1.6: Channel Bindings......................................... 14 - 1.2: GSS-API Features and Issues................................ 15 - 1.2.1: Status Reporting......................................... 15 - 1.2.2: Per-Message Security Service Availability................. 17 - 1.2.3: Per-Message Replay Detection and Sequencing............... 18 - 1.2.4: Quality of Protection.................................... 20 - 1.2.5: Anonymity Support......................................... 21 - 1.2.6: Initialization............................................ 22 - 1.2.7: Per-Message Protection During Context Establishment....... 22 - 1.2.8: Implementation Robustness................................. 23 - 2: Interface Descriptions....................................... 23 - 2.1: Credential management calls................................ 25 - 2.1.1: GSS_Acquire_cred call.................................... 26 - 2.1.2: GSS_Release_cred call.................................... 28 - 2.1.3: GSS_Inquire_cred call.................................... 29 - 2.1.4: GSS_Add_cred call........................................ 31 - 2.1.5: GSS_Inquire_cred_by_mech call............................ 33 - 2.2: Context-level calls........................................ 34 - 2.2.1: GSS_Init_sec_context call................................ 34 - 2.2.2: GSS_Accept_sec_context call.............................. 40 - 2.2.3: GSS_Delete_sec_context call.............................. 44 - 2.2.4: GSS_Process_context_token call........................... 46 - 2.2.5: GSS_Context_time call.................................... 47 - 2.2.6: GSS_Inquire_context call................................. 47 - 2.2.7: GSS_Wrap_size_limit call................................. 49 - 2.2.8: GSS_Export_sec_context call.............................. 50 - 2.2.9: GSS_Import_sec_context call.............................. 52 - 2.3: Per-message calls.......................................... 53 - 2.3.1: GSS_GetMIC call.......................................... 54 - 2.3.2: GSS_VerifyMIC call....................................... 55 - 2.3.3: GSS_Wrap call............................................ 56 - 2.3.4: GSS_Unwrap call.......................................... 58 - 2.4: Support calls.............................................. 59 - 2.4.1: GSS_Display_status call.................................. 60 - 2.4.2: GSS_Indicate_mechs call.................................. 60 - 2.4.3: GSS_Compare_name call.................................... 61 - 2.4.4: GSS_Display_name call.................................... 62 - 2.4.5: GSS_Import_name call..................................... 63 - 2.4.6: GSS_Release_name call.................................... 64 - 2.4.7: GSS_Release_buffer call.................................. 65 - 2.4.8: GSS_Release_OID_set call................................. 65 - 2.4.9: GSS_Create_empty_OID_set call............................ 66 - 2.4.10: GSS_Add_OID_set_member call.............................. 67 - 2.4.11: GSS_Test_OID_set_member call............................. 67 - - - -Linn Standards Track [Page 2] - -RFC 2078 GSS-API January 1997 - - - 2.4.12: GSS_Release_OID call..................................... 68 - 2.4.13: GSS_OID_to_str call...................................... 68 - 2.4.14: GSS_Str_to_OID call...................................... 69 - 2.4.15: GSS_Inquire_names_for_mech call.......................... 69 - 2.4.16: GSS_Inquire_mechs_for_name call.......................... 70 - 2.4.17: GSS_Canonicalize_name call............................... 71 - 2.4.18: GSS_Export_name call..................................... 72 - 2.4.19: GSS_Duplicate_name call.................................. 73 - 3: Data Structure Definitions for GSS-V2 Usage................... 73 - 3.1: Mechanism-Independent Token Format.......................... 74 - 3.2: Mechanism-Independent Exported Name Object Format........... 77 - 4: Name Type Definitions......................................... 77 - 4.1: Host-Based Service Name Form................................ 77 - 4.2: User Name Form.............................................. 78 - 4.3: Machine UID Form............................................ 78 - 4.4: String UID Form............................................. 79 - 5: Mechanism-Specific Example Scenarios......................... 79 - 5.1: Kerberos V5, single-TGT..................................... 79 - 5.2: Kerberos V5, double-TGT..................................... 80 - 5.3: X.509 Authentication Framework............................. 81 - 6: Security Considerations...................................... 82 - 7: Related Activities........................................... 82 - Appendix A: Mechanism Design Constraints......................... 83 - Appendix B: Compatibility with GSS-V1............................ 83 - -1: GSS-API Characteristics and Concepts - - GSS-API operates in the following paradigm. A typical GSS-API caller - is itself a communications protocol, calling on GSS-API in order to - protect its communications with authentication, integrity, and/or - confidentiality security services. A GSS-API caller accepts tokens - provided to it by its local GSS-API implementation and transfers the - tokens to a peer on a remote system; that peer passes the received - tokens to its local GSS-API implementation for processing. The - security services available through GSS-API in this fashion are - implementable (and have been implemented) over a range of underlying - mechanisms based on secret-key and public-key cryptographic - technologies. - - The GSS-API separates the operations of initializing a security - context between peers, achieving peer entity authentication (This - security service definition, and other definitions used in this - document, corresponds to that provided in International Standard ISO - 7498-2-1988(E), Security Architecture.) (GSS_Init_sec_context() and - GSS_Accept_sec_context() calls), from the operations of providing - per-message data origin authentication and data integrity protection - (GSS_GetMIC() and GSS_VerifyMIC() calls) for messages subsequently - transferred in conjunction with that context. When establishing a - - - -Linn Standards Track [Page 3] - -RFC 2078 GSS-API January 1997 - - - security context, the GSS-API enables a context initiator to - optionally permit its credentials to be delegated, meaning that the - context acceptor may initiate further security contexts on behalf of - the initiating caller. Per-message GSS_Wrap() and GSS_Unwrap() calls - provide the data origin authentication and data integrity services - which GSS_GetMIC() and GSS_VerifyMIC() offer, and also support - selection of confidentiality services as a caller option. Additional - calls provide supportive functions to the GSS-API's users. - - The following paragraphs provide an example illustrating the - dataflows involved in use of the GSS-API by a client and server in a - mechanism-independent fashion, establishing a security context and - transferring a protected message. The example assumes that credential - acquisition has already been completed. The example assumes that the - underlying authentication technology is capable of authenticating a - client to a server using elements carried within a single token, and - of authenticating the server to the client (mutual authentication) - with a single returned token; this assumption holds for presently- - documented CAT mechanisms but is not necessarily true for other - cryptographic technologies and associated protocols. - - The client calls GSS_Init_sec_context() to establish a security - context to the server identified by targ_name, and elects to set the - mutual_req_flag so that mutual authentication is performed in the - course of context establishment. GSS_Init_sec_context() returns an - output_token to be passed to the server, and indicates - GSS_S_CONTINUE_NEEDED status pending completion of the mutual - authentication sequence. Had mutual_req_flag not been set, the - initial call to GSS_Init_sec_context() would have returned - GSS_S_COMPLETE status. The client sends the output_token to the - server. - - The server passes the received token as the input_token parameter to - GSS_Accept_sec_context(). GSS_Accept_sec_context indicates - GSS_S_COMPLETE status, provides the client's authenticated identity - in the src_name result, and provides an output_token to be passed to - the client. The server sends the output_token to the client. - - The client passes the received token as the input_token parameter to - a successor call to GSS_Init_sec_context(), which processes data - included in the token in order to achieve mutual authentication from - the client's viewpoint. This call to GSS_Init_sec_context() returns - GSS_S_COMPLETE status, indicating successful mutual authentication - and the completion of context establishment for this example. - - The client generates a data message and passes it to GSS_Wrap(). - GSS_Wrap() performs data origin authentication, data integrity, and - (optionally) confidentiality processing on the message and - - - -Linn Standards Track [Page 4] - -RFC 2078 GSS-API January 1997 - - - encapsulates the result into output_message, indicating - GSS_S_COMPLETE status. The client sends the output_message to the - server. - - The server passes the received message to GSS_Unwrap(). GSS_Unwrap() - inverts the encapsulation performed by GSS_Wrap(), deciphers the - message if the optional confidentiality feature was applied, and - validates the data origin authentication and data integrity checking - quantities. GSS_Unwrap() indicates successful validation by - returning GSS_S_COMPLETE status along with the resultant - output_message. - - For purposes of this example, we assume that the server knows by - out-of-band means that this context will have no further use after - one protected message is transferred from client to server. Given - this premise, the server now calls GSS_Delete_sec_context() to flush - context-level information. Optionally, the server-side application - may provide a token buffer to GSS_Delete_sec_context(), to receive a - context_token to be transferred to the client in order to request - that client-side context-level information be deleted. - - If a context_token is transferred, the client passes the - context_token to GSS_Process_context_token(), which returns - GSS_S_COMPLETE status after deleting context-level information at the - client system. - - The GSS-API design assumes and addresses several basic goals, - including: - - Mechanism independence: The GSS-API defines an interface to - cryptographically implemented strong authentication and other - security services at a generic level which is independent of - particular underlying mechanisms. For example, GSS-API-provided - services can be implemented by secret-key technologies (e.g., - Kerberos) or public-key approaches (e.g., X.509). - - Protocol environment independence: The GSS-API is independent of - the communications protocol suites with which it is employed, - permitting use in a broad range of protocol environments. In - appropriate environments, an intermediate implementation "veneer" - which is oriented to a particular communication protocol (e.g., - Remote Procedure Call (RPC)) may be interposed between - applications which call that protocol and the GSS-API, thereby - invoking GSS-API facilities in conjunction with that protocol's - communications invocations. - - Protocol association independence: The GSS-API's security context - construct is independent of communications protocol association - - - -Linn Standards Track [Page 5] - -RFC 2078 GSS-API January 1997 - - - constructs. This characteristic allows a single GSS-API - implementation to be utilized by a variety of invoking protocol - modules on behalf of those modules' calling applications. GSS-API - services can also be invoked directly by applications, wholly - independent of protocol associations. - - Suitability to a range of implementation placements: GSS-API - clients are not constrained to reside within any Trusted Computing - Base (TCB) perimeter defined on a system where the GSS-API is - implemented; security services are specified in a manner suitable - to both intra-TCB and extra-TCB callers. - -1.1: GSS-API Constructs - - This section describes the basic elements comprising the GSS-API. - -1.1.1: Credentials - -1.1.1.1: Credential Constructs and Concepts - - Credentials provide the prerequisites which permit GSS-API peers to - establish security contexts with each other. A caller may designate - that the credential elements which are to be applied for context - initiation or acceptance be selected by default. Alternately, those - GSS-API callers which need to make explicit selection of particular - credentials structures may make references to those credentials - through GSS-API-provided credential handles ("cred_handles"). In all - cases, callers' credential references are indirect, mediated by GSS- - API implementations and not requiring callers to access the selected - credential elements. - - A single credential structure may be used to initiate outbound - contexts and to accept inbound contexts. Callers needing to operate - in only one of these modes may designate this fact when credentials - are acquired for use, allowing underlying mechanisms to optimize - their processing and storage requirements. The credential elements - defined by a particular mechanism may contain multiple cryptographic - keys, e.g., to enable authentication and message encryption to be - performed with different algorithms. - - A GSS-API credential structure may contain multiple credential - elements, each containing mechanism-specific information for a - particular underlying mechanism (mech_type), but the set of elements - within a given credential structure represent a common entity. A - credential structure's contents will vary depending on the set of - mech_types supported by a particular GSS-API implementation. Each - credential element identifies the data needed by its mechanism in - order to establish contexts on behalf of a particular principal, and - - - -Linn Standards Track [Page 6] - -RFC 2078 GSS-API January 1997 - - - may contain separate credential references for use in context - initiation and context acceptance. Multiple credential elements - within a given credential having overlapping combinations of - mechanism, usage mode, and validity period are not permitted. - - Commonly, a single mech_type will be used for all security contexts - established by a particular initiator to a particular target. A major - motivation for supporting credential sets representing multiple - mech_types is to allow initiators on systems which are equipped to - handle multiple types to initiate contexts to targets on other - systems which can accommodate only a subset of the set supported at - the initiator's system. - -1.1.1.2: Credential Management - - It is the responsibility of underlying system-specific mechanisms and - OS functions below the GSS-API to ensure that the ability to acquire - and use credentials associated with a given identity is constrained - to appropriate processes within a system. This responsibility should - be taken seriously by implementors, as the ability for an entity to - utilize a principal's credentials is equivalent to the entity's - ability to successfully assert that principal's identity. - - Once a set of GSS-API credentials is established, the transferability - of that credentials set to other processes or analogous constructs - within a system is a local matter, not defined by the GSS-API. An - example local policy would be one in which any credentials received - as a result of login to a given user account, or of delegation of - rights to that account, are accessible by, or transferable to, - processes running under that account. - - The credential establishment process (particularly when performed on - behalf of users rather than server processes) is likely to require - access to passwords or other quantities which should be protected - locally and exposed for the shortest time possible. As a result, it - will often be appropriate for preliminary credential establishment to - be performed through local means at user login time, with the - result(s) cached for subsequent reference. These preliminary - credentials would be set aside (in a system-specific fashion) for - subsequent use, either: - - to be accessed by an invocation of the GSS-API GSS_Acquire_cred() - call, returning an explicit handle to reference that credential - - to comprise default credential elements to be installed, and to be - used when default credential behavior is requested on behalf of a - process - - - - -Linn Standards Track [Page 7] - -RFC 2078 GSS-API January 1997 - - -1.1.1.3: Default Credential Resolution - - The gss_init_sec_context and gss_accept_sec_context routines allow - the value GSS_C_NO_CREDENTIAL to be specified as their credential - handle parameter. This special credential-handle indicates a desire - by the application to act as a default principal. While individual - GSS-API implementations are free to determine such default behavior - as appropriate to the mechanism, the following default behavior by - these routines is recommended for portability: - - GSS_Init_sec_context: - - (i) If there is only a single principal capable of initiating - security contexts that the application is authorized to act on - behalf of, then that principal shall be used, otherwise - - (ii) If the platform maintains a concept of a default network- - identity, and if the application is authorized to act on behalf of - that identity for the purpose of initiating security contexts, - then the principal corresponding to that identity shall be used, - otherwise - - (iii) If the platform maintains a concept of a default local - identity, and provides a means to map local identities into - network-identities, and if the application is authorized to act on - behalf of the network-identity image of the default local identity - for the purpose of initiating security contexts, then the - principal corresponding to that identity shall be used, otherwise - - (iv) A user-configurable default identity should be used. - - GSS_Accept_sec_context: - - (i) If there is only a single authorized principal identity - capable of accepting security contexts, then that principal shall - be used, otherwise - - (ii) If the mechanism can determine the identity of the target - principal by examining the context-establishment token, and if the - accepting application is authorized to act as that principal for - the purpose of accepting security contexts, then that principal - identity shall be used, otherwise - - (iii) If the mechanism supports context acceptance by any - principal, and mutual authentication was not requested, any - principal that the application is authorized to accept security - contexts under may be used, otherwise - - - - -Linn Standards Track [Page 8] - -RFC 2078 GSS-API January 1997 - - - (iv) A user-configurable default identity shall be used. - - The purpose of the above rules is to allow security contexts to be - established by both initiator and acceptor using the default behavior - wherever possible. Applications requesting default behavior are - likely to be more portable across mechanisms and platforms than ones - that use GSS_Acquire_cred to request a specific identity. - -1.1.2: Tokens - - Tokens are data elements transferred between GSS-API callers, and are - divided into two classes. Context-level tokens are exchanged in order - to establish and manage a security context between peers. Per-message - tokens relate to an established context and are exchanged to provide - protective security services (i.e., data origin authentication, - integrity, and optional confidentiality) for corresponding data - messages. - - The first context-level token obtained from GSS_Init_sec_context() is - required to indicate at its very beginning a globally-interpretable - mechanism identifier, i.e., an Object Identifier (OID) of the - security mechanism. The remaining part of this token as well as the - whole content of all other tokens are specific to the particular - underlying mechanism used to support the GSS-API. Section 3 of this - document provides, for designers of GSS-API support mechanisms, the - description of the header of the first context-level token which is - then followed by mechanism-specific information. - - Tokens' contents are opaque from the viewpoint of GSS-API callers. - They are generated within the GSS-API implementation at an end - system, provided to a GSS-API caller to be transferred to the peer - GSS-API caller at a remote end system, and processed by the GSS-API - implementation at that remote end system. Tokens may be output by - GSS-API calls (and should be transferred to GSS-API peers) whether or - not the calls' status indicators indicate successful completion. - Token transfer may take place in an in-band manner, integrated into - the same protocol stream used by the GSS-API callers for other data - transfers, or in an out-of-band manner across a logically separate - channel. - - Different GSS-API tokens are used for different purposes (e.g., - context initiation, context acceptance, protected message data on an - established context), and it is the responsibility of a GSS-API - caller receiving tokens to distinguish their types, associate them - with corresponding security contexts, and pass them to appropriate - GSS-API processing routines. Depending on the caller protocol - environment, this distinction may be accomplished in several ways. - - - - -Linn Standards Track [Page 9] - -RFC 2078 GSS-API January 1997 - - - The following examples illustrate means through which tokens' types - may be distinguished: - - - implicit tagging based on state information (e.g., all tokens on - a new association are considered to be context establishment - tokens until context establishment is completed, at which point - all tokens are considered to be wrapped data objects for that - context), - - - explicit tagging at the caller protocol level, - - - a hybrid of these approaches. - - Commonly, the encapsulated data within a token includes internal - mechanism-specific tagging information, enabling mechanism-level - processing modules to distinguish tokens used within the mechanism - for different purposes. Such internal mechanism-level tagging is - recommended to mechanism designers, and enables mechanisms to - determine whether a caller has passed a particular token for - processing by an inappropriate GSS-API routine. - - Development of GSS-API support primitives based on a particular - underlying cryptographic technique and protocol (i.e., conformant to - a specific GSS-API mechanism definition) does not necessarily imply - that GSS-API callers using that GSS-API mechanism will be able to - interoperate with peers invoking the same technique and protocol - outside the GSS-API paradigm, or with peers implementing a different - GSS-API mechanism based on the same underlying technology. The - format of GSS-API tokens defined in conjunction with a particular - mechanism, and the techniques used to integrate those tokens into - callers' protocols, may not be interoperable with the tokens used by - non-GSS-API callers of the same underlying technique. - -1.1.3: Security Contexts - - Security contexts are established between peers, using credentials - established locally in conjunction with each peer or received by - peers via delegation. Multiple contexts may exist simultaneously - between a pair of peers, using the same or different sets of - credentials. Coexistence of multiple contexts using different - credentials allows graceful rollover when credentials expire. - Distinction among multiple contexts based on the same credentials - serves applications by distinguishing different message streams in a - security sense. - - The GSS-API is independent of underlying protocols and addressing - structure, and depends on its callers to transport GSS-API-provided - data elements. As a result of these factors, it is a caller - - - -Linn Standards Track [Page 10] - -RFC 2078 GSS-API January 1997 - - - responsibility to parse communicated messages, separating GSS-API- - related data elements from caller-provided data. The GSS-API is - independent of connection vs. connectionless orientation of the - underlying communications service. - - No correlation between security context and communications protocol - association is dictated. (The optional channel binding facility, - discussed in Section 1.1.6 of this document, represents an - intentional exception to this rule, supporting additional protection - features within GSS-API supporting mechanisms.) This separation - allows the GSS-API to be used in a wide range of communications - environments, and also simplifies the calling sequences of the - individual calls. In many cases (depending on underlying security - protocol, associated mechanism, and availability of cached - information), the state information required for context setup can be - sent concurrently with initial signed user data, without interposing - additional message exchanges. - -1.1.4: Mechanism Types - - In order to successfully establish a security context with a target - peer, it is necessary to identify an appropriate underlying mechanism - type (mech_type) which both initiator and target peers support. The - definition of a mechanism embodies not only the use of a particular - cryptographic technology (or a hybrid or choice among alternative - cryptographic technologies), but also definition of the syntax and - semantics of data element exchanges which that mechanism will employ - in order to support security services. - - It is recommended that callers initiating contexts specify the - "default" mech_type value, allowing system-specific functions within - or invoked by the GSS-API implementation to select the appropriate - mech_type, but callers may direct that a particular mech_type be - employed when necessary. - - The means for identifying a shared mech_type to establish a security - context with a peer will vary in different environments and - circumstances; examples include (but are not limited to): - - use of a fixed mech_type, defined by configuration, within an - environment - - syntactic convention on a target-specific basis, through - examination of a target's name - - lookup of a target's name in a naming service or other database in - order to identify mech_types supported by that target - - - - -Linn Standards Track [Page 11] - -RFC 2078 GSS-API January 1997 - - - explicit negotiation between GSS-API callers in advance of - security context setup - - When transferred between GSS-API peers, mech_type specifiers (per - Section 3, represented as Object Identifiers (OIDs)) serve to qualify - the interpretation of associated tokens. (The structure and encoding - of Object Identifiers is defined in ISO/IEC 8824, "Specification of - Abstract Syntax Notation One (ASN.1)" and in ISO/IEC 8825, - "Specification of Basic Encoding Rules for Abstract Syntax Notation - One (ASN.1)".) Use of hierarchically structured OIDs serves to - preclude ambiguous interpretation of mech_type specifiers. The OID - representing the DASS MechType, for example, is 1.3.12.2.1011.7.5, - and that of the Kerberos V5 mechanism, once advanced to the level of - Proposed Standard, will be 1.2.840.113554.1.2.2. - -1.1.5: Naming - - The GSS-API avoids prescribing naming structures, treating the names - which are transferred across the interface in order to initiate and - accept security contexts as opaque objects. This approach supports - the GSS-API's goal of implementability atop a range of underlying - security mechanisms, recognizing the fact that different mechanisms - process and authenticate names which are presented in different - forms. Generalized services offering translation functions among - arbitrary sets of naming environments are outside the scope of the - GSS-API; availability and use of local conversion functions to - translate among the naming formats supported within a given end - system is anticipated. - - Different classes of name representations are used in conjunction - with different GSS-API parameters: - - - Internal form (denoted in this document by INTERNAL NAME), - opaque to callers and defined by individual GSS-API - implementations. GSS-API implementations supporting multiple - namespace types must maintain internal tags to disambiguate the - interpretation of particular names. A Mechanism Name (MN) is a - special case of INTERNAL NAME, guaranteed to contain elements - corresponding to one and only one mechanism; calls which are - guaranteed to emit MNs or which require MNs as input are so - identified within this specification. - - - Contiguous string ("flat") form (denoted in this document by - OCTET STRING); accompanied by OID tags identifying the namespace - to which they correspond. Depending on tag value, flat names may - or may not be printable strings for direct acceptance from and - presentation to users. Tagging of flat names allows GSS-API - callers and underlying GSS-API mechanisms to disambiguate name - - - -Linn Standards Track [Page 12] - -RFC 2078 GSS-API January 1997 - - - types and to determine whether an associated name's type is one - which they are capable of processing, avoiding aliasing problems - which could result from misinterpreting a name of one type as a - name of another type. - - - The GSS-API Exported Name Object, a special case of flat name - designated by a reserved OID value, carries a canonicalized form - of a name suitable for binary comparisons. - - In addition to providing means for names to be tagged with types, - this specification defines primitives to support a level of naming - environment independence for certain calling applications. To provide - basic services oriented towards the requirements of callers which - need not themselves interpret the internal syntax and semantics of - names, GSS-API calls for name comparison (GSS_Compare_name()), - human-readable display (GSS_Display_name()), input conversion - (GSS_Import_name()), internal name deallocation (GSS_Release_name()), - and internal name duplication (GSS_Duplicate_name()) functions are - defined. (It is anticipated that these proposed GSS-API calls will be - implemented in many end systems based on system-specific name - manipulation primitives already extant within those end systems; - inclusion within the GSS-API is intended to offer GSS-API callers a - portable means to perform specific operations, supportive of - authorization and audit requirements, on authenticated names.) - - GSS_Import_name() implementations can, where appropriate, support - more than one printable syntax corresponding to a given namespace - (e.g., alternative printable representations for X.500 Distinguished - Names), allowing flexibility for their callers to select among - alternative representations. GSS_Display_name() implementations - output a printable syntax selected as appropriate to their - operational environments; this selection is a local matter. Callers - desiring portability across alternative printable syntaxes should - refrain from implementing comparisons based on printable name forms - and should instead use the GSS_Compare_name() call to determine - whether or not one internal-format name matches another. - - The GSS_Canonicalize_name() and GSS_Export_name() calls enable - callers to acquire and process Exported Name Objects, canonicalized - and translated in accordance with the procedures of a particular - GSS-API mechanism. Exported Name Objects can, in turn, be input to - GSS_Import_name(), yielding equivalent MNs. These facilities are - designed specifically to enable efficient storage and comparison of - names (e.g., for use in access control lists). - - - - - - - -Linn Standards Track [Page 13] - -RFC 2078 GSS-API January 1997 - - - The following diagram illustrates the intended dataflow among name- - related GSS-API processing routines. - - GSS-API library defaults - | - | - V text, for - text --------------> internal_name (IN) -----------> display only - import_name() / display_name() - / - / - / - accept_sec_context() / - | / - | / - | / canonicalize_name() - | / - | / - | / - | / - | / - | | - V V <--------------------- - single mechanism import_name() exported name: flat - internal_name (MN) binary "blob" usable - ----------------------> for access control - export_name() - -1.1.6: Channel Bindings - - The GSS-API accommodates the concept of caller-provided channel - binding ("chan_binding") information. Channel bindings are used to - strengthen the quality with which peer entity authentication is - provided during context establishment, by limiting the scope within - which an intercepted context establishment token can be reused by an - attacker. Specifically, they enable GSS-API callers to bind the - establishment of a security context to relevant characteristics - (e.g., addresses, transformed representations of encryption keys) of - the underlying communications channel, of protection mechanisms - applied to that communications channel, and to application-specific - data. - - The caller initiating a security context must determine the - appropriate channel binding values to provide as input to the - GSS_Init_sec_context() call, and consistent values must be provided - to GSS_Accept_sec_context() by the context's target, in order for - both peers' GSS-API mechanisms to validate that received tokens - possess correct channel-related characteristics. Use or non-use of - - - -Linn Standards Track [Page 14] - -RFC 2078 GSS-API January 1997 - - - the GSS-API channel binding facility is a caller option. GSS-API - mechanisms can operate in an environment where NULL channel bindings - are presented; mechanism implementors are encouraged, but not - required, to make use of caller-provided channel binding data within - their mechanisms. Callers should not assume that underlying - mechanisms provide confidentiality protection for channel binding - information. - - When non-NULL channel bindings are provided by callers, certain - mechanisms can offer enhanced security value by interpreting the - bindings' content (rather than simply representing those bindings, or - integrity check values computed on them, within tokens) and will - therefore depend on presentation of specific data in a defined - format. To this end, agreements among mechanism implementors are - defining conventional interpretations for the contents of channel - binding arguments, including address specifiers (with content - dependent on communications protocol environment) for context - initiators and acceptors. (These conventions are being incorporated - in GSS-API mechanism specifications and into the GSS-API C language - bindings specification.) In order for GSS-API callers to be portable - across multiple mechanisms and achieve the full security - functionality which each mechanism can provide, it is strongly - recommended that GSS-API callers provide channel bindings consistent - with these conventions and those of the networking environment in - which they operate. - -1.2: GSS-API Features and Issues - - This section describes aspects of GSS-API operations, of the security - services which the GSS-API provides, and provides commentary on - design issues. - -1.2.1: Status Reporting - - Each GSS-API call provides two status return values. Major_status - values provide a mechanism-independent indication of call status - (e.g., GSS_S_COMPLETE, GSS_S_FAILURE, GSS_S_CONTINUE_NEEDED), - sufficient to drive normal control flow within the caller in a - generic fashion. Table 1 summarizes the defined major_status return - codes in tabular fashion. - - - - - - - - - - - -Linn Standards Track [Page 15] - -RFC 2078 GSS-API January 1997 - - -Table 1: GSS-API Major Status Codes - - FATAL ERROR CODES - - GSS_S_BAD_BINDINGS channel binding mismatch - GSS_S_BAD_MECH unsupported mechanism requested - GSS_S_BAD_NAME invalid name provided - GSS_S_BAD_NAMETYPE name of unsupported type provided - GSS_S_BAD_STATUS invalid input status selector - GSS_S_BAD_SIG token had invalid integrity check - GSS_S_CONTEXT_EXPIRED specified security context expired - GSS_S_CREDENTIALS_EXPIRED expired credentials detected - GSS_S_DEFECTIVE_CREDENTIAL defective credential detected - GSS_S_DEFECTIVE_TOKEN defective token detected - GSS_S_FAILURE failure, unspecified at GSS-API - level - GSS_S_NO_CONTEXT no valid security context specified - GSS_S_NO_CRED no valid credentials provided - GSS_S_BAD_QOP unsupported QOP value - GSS_S_UNAUTHORIZED operation unauthorized - GSS_S_UNAVAILABLE operation unavailable - GSS_S_DUPLICATE_ELEMENT duplicate credential element requested - GSS_S_NAME_NOT_MN name contains multi-mechanism elements - - INFORMATORY STATUS CODES - - GSS_S_COMPLETE normal completion - GSS_S_CONTINUE_NEEDED continuation call to routine - required - GSS_S_DUPLICATE_TOKEN duplicate per-message token - detected - GSS_S_OLD_TOKEN timed-out per-message token - detected - GSS_S_UNSEQ_TOKEN reordered (early) per-message token - detected - GSS_S_GAP_TOKEN skipped predecessor token(s) - detected - - Minor_status provides more detailed status information which may - include status codes specific to the underlying security mechanism. - Minor_status values are not specified in this document. - - GSS_S_CONTINUE_NEEDED major_status returns, and optional message - outputs, are provided in GSS_Init_sec_context() and - GSS_Accept_sec_context() calls so that different mechanisms' - employment of different numbers of messages within their - authentication sequences need not be reflected in separate code paths - within calling applications. Instead, such cases are accommodated - - - -Linn Standards Track [Page 16] - -RFC 2078 GSS-API January 1997 - - - with sequences of continuation calls to GSS_Init_sec_context() and - GSS_Accept_sec_context(). The same mechanism is used to encapsulate - mutual authentication within the GSS-API's context initiation calls. - - For mech_types which require interactions with third-party servers in - order to establish a security context, GSS-API context establishment - calls may block pending completion of such third-party interactions. - - On the other hand, no GSS-API calls pend on serialized interactions - with GSS-API peer entities. As a result, local GSS-API status - returns cannot reflect unpredictable or asynchronous exceptions - occurring at remote peers, and reflection of such status information - is a caller responsibility outside the GSS-API. - -1.2.2: Per-Message Security Service Availability - - When a context is established, two flags are returned to indicate the - set of per-message protection security services which will be - available on the context: - - the integ_avail flag indicates whether per-message integrity and - data origin authentication services are available - - the conf_avail flag indicates whether per-message confidentiality - services are available, and will never be returned TRUE unless the - integ_avail flag is also returned TRUE - - GSS-API callers desiring per-message security services should - check the values of these flags at context establishment time, and - must be aware that a returned FALSE value for integ_avail means - that invocation of GSS_GetMIC() or GSS_Wrap() primitives on the - associated context will apply no cryptographic protection to user - data messages. - - The GSS-API per-message integrity and data origin authentication - services provide assurance to a receiving caller that protection was - applied to a message by the caller's peer on the security context, - corresponding to the entity named at context initiation. The GSS-API - per-message confidentiality service provides assurance to a sending - caller that the message's content is protected from access by - entities other than the context's named peer. - - - - - - - - - - -Linn Standards Track [Page 17] - -RFC 2078 GSS-API January 1997 - - - The GSS-API per-message protection service primitives, as the - category name implies, are oriented to operation at the granularity - of protocol data units. They perform cryptographic operations on the - data units, transfer cryptographic control information in tokens, - and, in the case of GSS_Wrap(), encapsulate the protected data unit. - As such, these primitives are not oriented to efficient data - protection for stream-paradigm protocols (e.g., Telnet) if - cryptography must be applied on an octet-by-octet basis. - -1.2.3: Per-Message Replay Detection and Sequencing - - Certain underlying mech_types offer support for replay detection - and/or sequencing of messages transferred on the contexts they - support. These optionally-selectable protection features are distinct - from replay detection and sequencing features applied to the context - establishment operation itself; the presence or absence of context- - level replay or sequencing features is wholly a function of the - underlying mech_type's capabilities, and is not selected or omitted - as a caller option. - - The caller initiating a context provides flags (replay_det_req_flag - and sequence_req_flag) to specify whether the use of per-message - replay detection and sequencing features is desired on the context - being established. The GSS-API implementation at the initiator system - can determine whether these features are supported (and whether they - are optionally selectable) as a function of mech_type, without need - for bilateral negotiation with the target. When enabled, these - features provide recipients with indicators as a result of GSS-API - processing of incoming messages, identifying whether those messages - were detected as duplicates or out-of-sequence. Detection of such - events does not prevent a suspect message from being provided to a - recipient; the appropriate course of action on a suspect message is a - matter of caller policy. - - The semantics of the replay detection and sequencing services applied - to received messages, as visible across the interface which the GSS- - API provides to its clients, are as follows: - - When replay_det_state is TRUE, the possible major_status returns for - well-formed and correctly signed messages are as follows: - - 1. GSS_S_COMPLETE indicates that the message was within the window - (of time or sequence space) allowing replay events to be detected, - and that the message was not a replay of a previously-processed - message within that window. - - - - - - -Linn Standards Track [Page 18] - -RFC 2078 GSS-API January 1997 - - - 2. GSS_S_DUPLICATE_TOKEN indicates that the cryptographic - checkvalue on the received message was correct, but that the - message was recognized as a duplicate of a previously-processed - message. - - 3. GSS_S_OLD_TOKEN indicates that the cryptographic checkvalue on - the received message was correct, but that the message is too old - to be checked for duplication. - - When sequence_state is TRUE, the possible major_status returns for - well-formed and correctly signed messages are as follows: - - 1. GSS_S_COMPLETE indicates that the message was within the window - (of time or sequence space) allowing replay events to be detected, - that the message was not a replay of a previously-processed - message within that window, and that no predecessor sequenced - messages are missing relative to the last received message (if - any) processed on the context with a correct cryptographic - checkvalue. - - 2. GSS_S_DUPLICATE_TOKEN indicates that the integrity check value - on the received message was correct, but that the message was - recognized as a duplicate of a previously-processed message. - - 3. GSS_S_OLD_TOKEN indicates that the integrity check value on the - received message was correct, but that the token is too old to be - checked for duplication. - - 4. GSS_S_UNSEQ_TOKEN indicates that the cryptographic checkvalue - on the received message was correct, but that it is earlier in a - sequenced stream than a message already processed on the context. - [Note: Mechanisms can be architected to provide a stricter form of - sequencing service, delivering particular messages to recipients - only after all predecessor messages in an ordered stream have been - delivered. This type of support is incompatible with the GSS-API - paradigm in which recipients receive all messages, whether in - order or not, and provide them (one at a time, without intra-GSS- - API message buffering) to GSS-API routines for validation. GSS- - API facilities provide supportive functions, aiding clients to - achieve strict message stream integrity in an efficient manner in - conjunction with sequencing provisions in communications - protocols, but the GSS-API does not offer this level of message - stream integrity service by itself.] - - - - - - - - -Linn Standards Track [Page 19] - -RFC 2078 GSS-API January 1997 - - - 5. GSS_S_GAP_TOKEN indicates that the cryptographic checkvalue on - the received message was correct, but that one or more predecessor - sequenced messages have not been successfully processed relative - to the last received message (if any) processed on the context - with a correct cryptographic checkvalue. - - As the message stream integrity features (especially sequencing) may - interfere with certain applications' intended communications - paradigms, and since support for such features is likely to be - resource intensive, it is highly recommended that mech_types - supporting these features allow them to be activated selectively on - initiator request when a context is established. A context initiator - and target are provided with corresponding indicators - (replay_det_state and sequence_state), signifying whether these - features are active on a given context. - - An example mech_type supporting per-message replay detection could - (when replay_det_state is TRUE) implement the feature as follows: The - underlying mechanism would insert timestamps in data elements output - by GSS_GetMIC() and GSS_Wrap(), and would maintain (within a time- - limited window) a cache (qualified by originator-recipient pair) - identifying received data elements processed by GSS_VerifyMIC() and - GSS_Unwrap(). When this feature is active, exception status returns - (GSS_S_DUPLICATE_TOKEN, GSS_S_OLD_TOKEN) will be provided when - GSS_VerifyMIC() or GSS_Unwrap() is presented with a message which is - either a detected duplicate of a prior message or which is too old to - validate against a cache of recently received messages. - -1.2.4: Quality of Protection - - Some mech_types provide their users with fine granularity control - over the means used to provide per-message protection, allowing - callers to trade off security processing overhead dynamically against - the protection requirements of particular messages. A per-message - quality-of-protection parameter (analogous to quality-of-service, or - QOS) selects among different QOP options supported by that mechanism. - On context establishment for a multi-QOP mech_type, context-level - data provides the prerequisite data for a range of protection - qualities. - - It is expected that the majority of callers will not wish to exert - explicit mechanism-specific QOP control and will therefore request - selection of a default QOP. Definitions of, and choices among, non- - default QOP values are mechanism-specific, and no ordered sequences - of QOP values can be assumed equivalent across different mechanisms. - Meaningful use of non-default QOP values demands that callers be - familiar with the QOP definitions of an underlying mechanism or - mechanisms, and is therefore a non-portable construct. The - - - -Linn Standards Track [Page 20] - -RFC 2078 GSS-API January 1997 - - - GSS_S_BAD_QOP major_status value is defined in order to indicate that - a provided QOP value is unsupported for a security context, most - likely because that value is unrecognized by the underlying - mechanism. - -1.2.5: Anonymity Support - - In certain situations or environments, an application may wish to - authenticate a peer and/or protect communications using GSS-API per- - message services without revealing its own identity. For example, - consider an application which provides read access to a research - database, and which permits queries by arbitrary requestors. A - client of such a service might wish to authenticate the service, to - establish trust in the information received from it, but might not - wish to disclose its identity to the service for privacy reasons. - - In ordinary GSS-API usage, a context initiator's identity is made - available to the context acceptor as part of the context - establishment process. To provide for anonymity support, a facility - (input anon_req_flag to GSS_Init_sec_context()) is provided through - which context initiators may request that their identity not be - provided to the context acceptor. Mechanisms are not required to - honor this request, but a caller will be informed (via returned - anon_state indicator from GSS_Init_sec_context()) whether or not the - request is honored. Note that authentication as the anonymous - principal does not necessarily imply that credentials are not - required in order to establish a context. - - The following Object Identifier value is provided as a means to - identify anonymous names, and can be compared against in order to - determine, in a mechanism-independent fashion, whether a name refers - to an anonymous principal: - - {1(iso), 3(org), 6(dod), 1(internet), 5(security), 6(nametypes), - 3(gss-anonymous-name)} - - The recommended symbolic name corresponding to this definition is - GSS_C_NT_ANONYMOUS. - - Four possible combinations of anon_state and mutual_state are - possible, with the following results: - - anon_state == FALSE, mutual_state == FALSE: initiator - authenticated to target. - - anon_state == FALSE, mutual_state == TRUE: initiator authenticated - to target, target authenticated to initiator. - - - - -Linn Standards Track [Page 21] - -RFC 2078 GSS-API January 1997 - - - anon_state == TRUE, mutual_state == FALSE: initiator authenticated - as anonymous principal to target. - - anon_state == TRUE, mutual_state == TRUE: initiator authenticated - as anonymous principal to target, target authenticated to - initiator. - -1.2.6: Initialization - - No initialization calls (i.e., calls which must be invoked prior to - invocation of other facilities in the interface) are defined in GSS- - API. As an implication of this fact, GSS-API implementations must - themselves be self-initializing. - -1.2.7: Per-Message Protection During Context Establishment - - A facility is defined in GSS-V2 to enable protection and buffering of - data messages for later transfer while a security context's - establishment is in GSS_S_CONTINUE_NEEDED status, to be used in cases - where the caller side already possesses the necessary session key to - enable this processing. Specifically, a new state Boolean, called - prot_ready_state, is added to the set of information returned by - GSS_Init_sec_context(), GSS_Accept_sec_context(), and - GSS_Inquire_context(). - - For context establishment calls, this state Boolean is valid and - interpretable when the associated major_status is either - GSS_S_CONTINUE_NEEDED, or GSS_S_COMPLETE. Callers of GSS-API (both - initiators and acceptors) can assume that per-message protection (via - GSS_Wrap(), GSS_Unwrap(), GSS_GetMIC() and GSS_VerifyMIC()) is - available and ready for use if either: prot_ready_state == TRUE, or - major_status == GSS_S_COMPLETE, though mutual authentication (if - requested) cannot be guaranteed until GSS_S_COMPLETE is returned. - - This achieves full, transparent backward compatibility for GSS-API V1 - callers, who need not even know of the existence of prot_ready_state, - and who will get the expected behavior from GSS_S_COMPLETE, but who - will not be able to use per-message protection before GSS_S_COMPLETE - is returned. - - It is not a requirement that GSS-V2 mechanisms ever return TRUE - prot_ready_state before completion of context establishment (indeed, - some mechanisms will not evolve usable message protection keys, - especially at the context acceptor, before context establishment is - complete). It is expected but not required that GSS-V2 mechanisms - will return TRUE prot_ready_state upon completion of context - establishment if they support per-message protection at all (however - GSS-V2 applications should not assume that TRUE prot_ready_state will - - - -Linn Standards Track [Page 22] - -RFC 2078 GSS-API January 1997 - - - always be returned together with the GSS_S_COMPLETE major_status, - since GSS-V2 implementations may continue to support GSS-V1 mechanism - code, which will never return TRUE prot_ready_state). - - When prot_ready_state is returned TRUE, mechanisms shall also set - those context service indicator flags (deleg_state, mutual_state, - replay_det_state, sequence_state, anon_state, trans_state, - conf_avail, integ_avail) which represent facilities confirmed, at - that time, to be available on the context being established. In - situations where prot_ready_state is returned before GSS_S_COMPLETE, - it is possible that additional facilities may be confirmed and - subsequently indicated when GSS_S_COMPLETE is returned. - -1.2.8: Implementation Robustness - - This section recommends aspects of GSS-API implementation behavior in - the interests of overall robustness. - - If a token is presented for processing on a GSS-API security context - and that token is determined to be invalid for that context, the - context's state should not be disrupted for purposes of processing - subsequent valid tokens. - - Certain local conditions at a GSS-API implementation (e.g., - unavailability of memory) may preclude, temporarily or permanently, - the successful processing of tokens on a GSS-API security context, - typically generating GSS_S_FAILURE major_status returns along with - locally-significant minor_status. For robust operation under such - conditions, the following recommendations are made: - - Failing calls should free any memory they allocate, so that - callers may retry without causing further loss of resources. - - Failure of an individual call on an established context should not - preclude subsequent calls from succeeding on the same context. - - Whenever possible, it should be possible for - GSS_Delete_sec_context() calls to be successfully processed even - if other calls cannot succeed, thereby enabling context-related - resources to be released. - -2: Interface Descriptions - - This section describes the GSS-API's service interface, dividing the - set of calls offered into four groups. Credential management calls - are related to the acquisition and release of credentials by - principals. Context-level calls are related to the management of - security contexts between principals. Per-message calls are related - - - -Linn Standards Track [Page 23] - -RFC 2078 GSS-API January 1997 - - - to the protection of individual messages on established security - contexts. Support calls provide ancillary functions useful to GSS-API - callers. Table 2 groups and summarizes the calls in tabular fashion. - -Table 2: GSS-API Calls - - CREDENTIAL MANAGEMENT - - GSS_Acquire_cred acquire credentials for use - GSS_Release_cred release credentials after use - GSS_Inquire_cred display information about - credentials - GSS_Add_cred construct credentials incrementally - GSS_Inquire_cred_by_mech display per-mechanism credential - information - - CONTEXT-LEVEL CALLS - - GSS_Init_sec_context initiate outbound security context - GSS_Accept_sec_context accept inbound security context - GSS_Delete_sec_context flush context when no longer needed - GSS_Process_context_token process received control token on - context - GSS_Context_time indicate validity time remaining on - context - GSS_Inquire_context display information about context - GSS_Wrap_size_limit determine GSS_Wrap token size limit - GSS_Export_sec_context transfer context to other process - GSS_Import_sec_context import transferred context - - PER-MESSAGE CALLS - - GSS_GetMIC apply integrity check, receive as - token separate from message - GSS_VerifyMIC validate integrity check token - along with message - GSS_Wrap sign, optionally encrypt, - encapsulate - GSS_Unwrap decapsulate, decrypt if needed, - validate integrity check - - - - - - - - - - - -Linn Standards Track [Page 24] - -RFC 2078 GSS-API January 1997 - - - SUPPORT CALLS - - GSS_Display_status translate status codes to printable - form - GSS_Indicate_mechs indicate mech_types supported on - local system - GSS_Compare_name compare two names for equality - GSS_Display_name translate name to printable form - GSS_Import_name convert printable name to - normalized form - GSS_Release_name free storage of normalized-form - name - GSS_Release_buffer free storage of printable name - GSS_Release_OID free storage of OID object - GSS_Release_OID_set free storage of OID set object - GSS_Create_empty_OID_set create empty OID set - GSS_Add_OID_set_member add member to OID set - GSS_Test_OID_set_member test if OID is member of OID set - GSS_OID_to_str display OID as string - GSS_Str_to_OID construct OID from string - GSS_Inquire_names_for_mech indicate name types supported by - mechanism - GSS_Inquire_mechs_for_name indicates mechanisms supporting name - type - GSS_Canonicalize_name translate name to per-mechanism form - GSS_Export_name externalize per-mechanism name - GSS_Duplicate_name duplicate name object - -2.1: Credential management calls - - These GSS-API calls provide functions related to the management of - credentials. Their characterization with regard to whether or not - they may block pending exchanges with other network entities (e.g., - directories or authentication servers) depends in part on OS-specific - (extra-GSS-API) issues, so is not specified in this document. - - The GSS_Acquire_cred() call is defined within the GSS-API in support - of application portability, with a particular orientation towards - support of portable server applications. It is recognized that (for - certain systems and mechanisms) credentials for interactive users may - be managed differently from credentials for server processes; in such - environments, it is the GSS-API implementation's responsibility to - distinguish these cases and the procedures for making this - distinction are a local matter. The GSS_Release_cred() call provides - a means for callers to indicate to the GSS-API that use of a - credentials structure is no longer required. The GSS_Inquire_cred() - call allows callers to determine information about a credentials - structure. The GSS_Add_cred() call enables callers to append - - - -Linn Standards Track [Page 25] - -RFC 2078 GSS-API January 1997 - - - elements to an existing credential structure, allowing iterative - construction of a multi-mechanism credential. The - GSS_Inquire_cred_by_mech() call enables callers to extract per- - mechanism information describing a credentials structure. - -2.1.1: GSS_Acquire_cred call - - Inputs: - - o desired_name INTERNAL NAME, -NULL requests locally-determined - default - - o lifetime_req INTEGER,-in seconds; 0 requests default - - o desired_mechs SET OF OBJECT IDENTIFIER,-empty set requests - system-selected default - - o cred_usage INTEGER -0=INITIATE-AND-ACCEPT, 1=INITIATE-ONLY, - 2=ACCEPT-ONLY - - Outputs: - - o major_status INTEGER, - - o minor_status INTEGER, - - o output_cred_handle CREDENTIAL HANDLE, - - o actual_mechs SET OF OBJECT IDENTIFIER, - - o lifetime_rec INTEGER -in seconds, or reserved value for - INDEFINITE - - Return major_status codes: - - o GSS_S_COMPLETE indicates that requested credentials were - successfully established, for the duration indicated in - lifetime_rec, suitable for the usage requested in cred_usage, - for the set of mech_types indicated in actual_mechs, and that - those credentials can be referenced for subsequent use with - the handle returned in output_cred_handle. - - o GSS_S_BAD_MECH indicates that a mech_type unsupported by the - GSS-API implementation type was requested, causing the - credential establishment operation to fail. - - - - - - -Linn Standards Track [Page 26] - -RFC 2078 GSS-API January 1997 - - - o GSS_S_BAD_NAMETYPE indicates that the provided desired_name is - uninterpretable or of a type unsupported by the applicable - underlying GSS-API mechanism(s), so no credentials could be - established for the accompanying desired_name. - - o GSS_S_BAD_NAME indicates that the provided desired_name is - inconsistent in terms of internally-incorporated type specifier - information, so no credentials could be established for the - accompanying desired_name. - - o GSS_S_FAILURE indicates that credential establishment failed - for reasons unspecified at the GSS-API level, including lack - of authorization to establish and use credentials associated - with the identity named in the input desired_name argument. - - GSS_Acquire_cred() is used to acquire credentials so that a - principal can (as a function of the input cred_usage parameter) - initiate and/or accept security contexts under the identity - represented by the desired_name input argument. On successful - completion, the returned output_cred_handle result provides a handle - for subsequent references to the acquired credentials. Typically, - single-user client processes requesting that default credential - behavior be applied for context establishment purposes will have no - need to invoke this call. - - A caller may provide the value NULL for desired_name, signifying a - request for credentials corresponding to a principal identity - selected by default for the caller. The procedures used by GSS-API - implementations to select the appropriate principal identity in - response to such a request are local matters. It is possible that - multiple pre-established credentials may exist for the same principal - identity (for example, as a result of multiple user login sessions) - when GSS_Acquire_cred() is called; the means used in such cases to - select a specific credential are local matters. The input - lifetime_req argument to GSS_Acquire_cred() may provide useful - information for local GSS-API implementations to employ in making - this disambiguation in a manner which will best satisfy a caller's - intent. - - The lifetime_rec result indicates the length of time for which the - acquired credentials will be valid, as an offset from the present. A - mechanism may return a reserved value indicating INDEFINITE if no - constraints on credential lifetime are imposed. A caller of - GSS_Acquire_cred() can request a length of time for which acquired - credentials are to be valid (lifetime_req argument), beginning at the - present, or can request credentials with a default validity interval. - (Requests for postdated credentials are not supported within the - GSS-API.) Certain mechanisms and implementations may bind in - - - -Linn Standards Track [Page 27] - -RFC 2078 GSS-API January 1997 - - - credential validity period specifiers at a point preliminary to - invocation of the GSS_Acquire_cred() call (e.g., in conjunction with - user login procedures). As a result, callers requesting non-default - values for lifetime_req must recognize that such requests cannot - always be honored and must be prepared to accommodate the use of - returned credentials with different lifetimes as indicated in - lifetime_rec. - - The caller of GSS_Acquire_cred() can explicitly specify a set of - mech_types which are to be accommodated in the returned credentials - (desired_mechs argument), or can request credentials for a system- - defined default set of mech_types. Selection of the system-specified - default set is recommended in the interests of application - portability. The actual_mechs return value may be interrogated by the - caller to determine the set of mechanisms with which the returned - credentials may be used. - -2.1.2: GSS_Release_cred call - - Input: - - o cred_handle CREDENTIAL HANDLE - NULL specifies that - the credential elements used when default credential behavior - is requested be released. - - Outputs: - - o major_status INTEGER, - - o minor_status INTEGER - - Return major_status codes: - - o GSS_S_COMPLETE indicates that the credentials referenced by the - input cred_handle were released for purposes of subsequent - access by the caller. The effect on other processes which may - be authorized shared access to such credentials is a local - matter. - - o GSS_S_NO_CRED indicates that no release operation was - performed, either because the input cred_handle was invalid or - because the caller lacks authorization to access the - referenced credentials. - - o GSS_S_FAILURE indicates that the release operation failed for - reasons unspecified at the GSS-API level. - - - - - -Linn Standards Track [Page 28] - -RFC 2078 GSS-API January 1997 - - - Provides a means for a caller to explicitly request that credentials - be released when their use is no longer required. Note that system- - specific credential management functions are also likely to exist, - for example to assure that credentials shared among processes are - properly deleted when all affected processes terminate, even if no - explicit release requests are issued by those processes. Given the - fact that multiple callers are not precluded from gaining authorized - access to the same credentials, invocation of GSS_Release_cred() - cannot be assumed to delete a particular set of credentials on a - system-wide basis. - -2.1.3: GSS_Inquire_cred call - - Input: - - o cred_handle CREDENTIAL HANDLE -NULL specifies that the - credential elements used when default credential behavior is - requested are to be queried - - Outputs: - - o major_status INTEGER, - - o minor_status INTEGER, - - o cred_name INTERNAL NAME, - - o lifetime_rec INTEGER -in seconds, or reserved value for - INDEFINITE - - o cred_usage INTEGER, -0=INITIATE-AND-ACCEPT, 1=INITIATE-ONLY, - 2=ACCEPT-ONLY - - o mech_set SET OF OBJECT IDENTIFIER - - Return major_status codes: - - o GSS_S_COMPLETE indicates that the credentials referenced by the - input cred_handle argument were valid, and that the output - cred_name, lifetime_rec, and cred_usage values represent, - respectively, the credentials' associated principal name, - remaining lifetime, suitable usage modes, and supported - mechanism types. - - o GSS_S_NO_CRED indicates that no information could be returned - about the referenced credentials, either because the input - cred_handle was invalid or because the caller lacks - authorization to access the referenced credentials. - - - -Linn Standards Track [Page 29] - -RFC 2078 GSS-API January 1997 - - - o GSS_S_DEFECTIVE_CREDENTIAL indicates that the referenced - credentials are invalid. - - o GSS_S_CREDENTIALS_EXPIRED indicates that the referenced - credentials have expired. - - o GSS_S_FAILURE indicates that the operation failed for - reasons unspecified at the GSS-API level. - - The GSS_Inquire_cred() call is defined primarily for the use of those - callers which request use of default credential behavior rather than - acquiring credentials explicitly with GSS_Acquire_cred(). It enables - callers to determine a credential structure's associated principal - name, remaining validity period, usability for security context - initiation and/or acceptance, and supported mechanisms. - - For a multi-mechanism credential, the returned "lifetime" specifier - indicates the shortest lifetime of any of the mechanisms' elements in - the credential (for either context initiation or acceptance - purposes). - - GSS_Inquire_cred() should indicate INITIATE-AND-ACCEPT for - "cred_usage" if both of the following conditions hold: - - (1) there exists in the credential an element which allows context - initiation using some mechanism - - (2) there exists in the credential an element which allows context - acceptance using some mechanism (allowably, but not necessarily, - one of the same mechanism(s) qualifying for (1)). - - If condition (1) holds but not condition (2), GSS_Inquire_cred() - should indicate INITIATE-ONLY for "cred_usage". If condition (2) - holds but not condition (1), GSS_Inquire_cred() should indicate - ACCEPT-ONLY for "cred_usage". - - Callers requiring finer disambiguation among available combinations - of lifetimes, usage modes, and mechanisms should call the - GSS_Inquire_cred_by_mech() routine, passing that routine one of the - mech OIDs returned by GSS_Inquire_cred(). - - - - - - - - - - - -Linn Standards Track [Page 30] - -RFC 2078 GSS-API January 1997 - - -2.1.4: GSS_Add_cred call - - Inputs: - - o input_cred_handle CREDENTIAL HANDLE - handle to credential - structure created with prior GSS_Acquire_cred() or - GSS_Add_cred() call, or NULL to append elements to the set - which are applied for the caller when default credential - behavior is specified. - - o desired_name INTERNAL NAME - NULL requests locally-determined - default - - o initiator_time_req INTEGER - in seconds; 0 requests default - - o acceptor_time_req INTEGER - in seconds; 0 requests default - - o desired_mech OBJECT IDENTIFIER - - o cred_usage INTEGER - 0=INITIATE-AND-ACCEPT, 1=INITIATE-ONLY, - 2=ACCEPT-ONLY - - Outputs: - - o major_status INTEGER, - - o minor_status INTEGER, - - o output_cred_handle CREDENTIAL HANDLE, - NULL to request that - credential elements be added "in place" to the credential - structure identified by input_cred_handle, non-NULL pointer - to request that a new credential structure and handle be created. - - o actual_mechs SET OF OBJECT IDENTIFIER, - - o initiator_time_rec INTEGER - in seconds, or reserved value for - INDEFINITE - - o acceptor_time_rec INTEGER - in seconds, or reserved value for - INDEFINITE - - o cred_usage INTEGER, -0=INITIATE-AND-ACCEPT, 1=INITIATE-ONLY, - 2=ACCEPT-ONLY - - o mech_set SET OF OBJECT IDENTIFIER -- full set of mechanisms - supported by resulting credential. - - - - - -Linn Standards Track [Page 31] - -RFC 2078 GSS-API January 1997 - - - Return major_status codes: - - o GSS_S_COMPLETE indicates that the credentials referenced by - the input_cred_handle argument were valid, and that the - resulting credential from GSS_Add_cred() is valid for the - durations indicated in initiator_time_rec and acceptor_time_rec, - suitable for the usage requested in cred_usage, and for the - mechanisms indicated in actual_mechs. - - o GSS_S_DUPLICATE_ELEMENT indicates that the input desired_mech - specified a mechanism for which the referenced credential - already contained a credential element with overlapping - cred_usage and validity time specifiers. - - o GSS_S_BAD_MECH indicates that the input desired_mech specified - a mechanism unsupported by the GSS-API implementation, causing - the GSS_Add_cred() operation to fail. - - o GSS_S_BAD_NAMETYPE indicates that the provided desired_name - is uninterpretable or of a type unsupported by the applicable - underlying GSS-API mechanism(s), so the GSS_Add_cred() operation - could not be performed for that name. - - o GSS_S_BAD_NAME indicates that the provided desired_name is - inconsistent in terms of internally-incorporated type specifier - information, so the GSS_Add_cred() operation could not be - performed for that name. - - o GSS_S_NO_CRED indicates that the input_cred_handle referenced - invalid or inaccessible credentials. - - o GSS_S_FAILURE indicates that the operation failed for - reasons unspecified at the GSS-API level, including lack of - authorization to establish or use credentials representing - the requested identity. - - GSS_Add_cred() enables callers to construct credentials iteratively - by adding credential elements in successive operations, corresponding - to different mechanisms. This offers particular value in multi- - mechanism environments, as the major_status and minor_status values - returned on each iteration are individually visible and can therefore - be interpreted unambiguously on a per-mechanism basis. - - The same input desired_name, or default reference, should be used on - all GSS_Acquire_cred() and GSS_Add_cred() calls corresponding to a - particular credential. - - - - - -Linn Standards Track [Page 32] - -RFC 2078 GSS-API January 1997 - - -2.1.5: GSS_Inquire_cred_by_mech call - - Inputs: - - o cred_handle CREDENTIAL HANDLE -- NULL specifies that the - credential elements used when default credential behavior is - requested are to be queried - - o mech_type OBJECT IDENTIFIER -- specific mechanism for - which credentials are being queried - - Outputs: - - o major_status INTEGER, - - o minor_status INTEGER, - - o cred_name INTERNAL NAME, -- guaranteed to be MN - - o lifetime_rec_initiate INTEGER -- in seconds, or reserved value for - INDEFINITE - - o lifetime_rec_accept INTEGER -- in seconds, or reserved value for - INDEFINITE - - o cred_usage INTEGER, -0=INITIATE-AND-ACCEPT, 1=INITIATE-ONLY, - 2=ACCEPT-ONLY - - Return major_status codes: - - o GSS_S_COMPLETE indicates that the credentials referenced by the - input cred_handle argument were valid, that the mechanism - indicated by the input mech_type was represented with elements - within those credentials, and that the output cred_name, - lifetime_rec_initiate, lifetime_rec_accept, and cred_usage values - represent, respectively, the credentials' associated principal - name, remaining lifetimes, and suitable usage modes. - - o GSS_S_NO_CRED indicates that no information could be returned - about the referenced credentials, either because the input - cred_handle was invalid or because the caller lacks - authorization to access the referenced credentials. - - o GSS_S_DEFECTIVE_CREDENTIAL indicates that the referenced - credentials are invalid. - - o GSS_S_CREDENTIALS_EXPIRED indicates that the referenced - credentials have expired. - - - -Linn Standards Track [Page 33] - -RFC 2078 GSS-API January 1997 - - - o GSS_S_BAD_MECH indicates that the referenced credentials do not - contain elements for the requested mechanism. - - o GSS_S_FAILURE indicates that the operation failed for reasons - unspecified at the GSS-API level. - - The GSS_Inquire_cred_by_mech() call enables callers in multi- - mechanism environments to acquire specific data about available - combinations of lifetimes, usage modes, and mechanisms within a - credential structure. The lifetime_rec_initiate result indicates the - available lifetime for context initiation purposes; the - lifetime_rec_accept result indicates the available lifetime for - context acceptance purposes. - -2.2: Context-level calls - - This group of calls is devoted to the establishment and management of - security contexts between peers. A context's initiator calls - GSS_Init_sec_context(), resulting in generation of a token which the - caller passes to the target. At the target, that token is passed to - GSS_Accept_sec_context(). Depending on the underlying mech_type and - specified options, additional token exchanges may be performed in the - course of context establishment; such exchanges are accommodated by - GSS_S_CONTINUE_NEEDED status returns from GSS_Init_sec_context() and - GSS_Accept_sec_context(). - - Either party to an established context may invoke - GSS_Delete_sec_context() to flush context information when a context - is no longer required. GSS_Process_context_token() is used to - process received tokens carrying context-level control information. - GSS_Context_time() allows a caller to determine the length of time - for which an established context will remain valid. - GSS_Inquire_context() returns status information describing context - characteristics. GSS_Wrap_size_limit() allows a caller to determine - the size of a token which will be generated by a GSS_Wrap() - operation. GSS_Export_sec_context() and GSS_Import_sec_context() - enable transfer of active contexts between processes on an end - system. - -2.2.1: GSS_Init_sec_context call - - Inputs: - - o claimant_cred_handle CREDENTIAL HANDLE, -NULL specifies "use - default" - - o input_context_handle CONTEXT HANDLE, -0 specifies "none assigned - yet" - - - -Linn Standards Track [Page 34] - -RFC 2078 GSS-API January 1997 - - - o targ_name INTERNAL NAME, - - o mech_type OBJECT IDENTIFIER, -NULL parameter specifies "use - default" - - o deleg_req_flag BOOLEAN, - - o mutual_req_flag BOOLEAN, - - o replay_det_req_flag BOOLEAN, - - o sequence_req_flag BOOLEAN, - - o anon_req_flag BOOLEAN, - - o lifetime_req INTEGER,-0 specifies default lifetime - - o chan_bindings OCTET STRING, - - o input_token OCTET STRING-NULL or token received from target - - Outputs: - - o major_status INTEGER, - - o minor_status INTEGER, - - o output_context_handle CONTEXT HANDLE, - - o mech_type OBJECT IDENTIFIER, -actual mechanism always - indicated, never NULL - - o output_token OCTET STRING, -NULL or token to pass to context - target - - o deleg_state BOOLEAN, - - o mutual_state BOOLEAN, - - o replay_det_state BOOLEAN, - - o sequence_state BOOLEAN, - - o anon_state BOOLEAN, - - o trans_state BOOLEAN, - - o prot_ready_state BOOLEAN, -- see Section 1.2.7 - - - -Linn Standards Track [Page 35] - -RFC 2078 GSS-API January 1997 - - - o conf_avail BOOLEAN, - - o integ_avail BOOLEAN, - - o lifetime_rec INTEGER - in seconds, or reserved value for - INDEFINITE - - This call may block pending network interactions for those mech_types - in which an authentication server or other network entity must be - consulted on behalf of a context initiator in order to generate an - output_token suitable for presentation to a specified target. - - Return major_status codes: - - o GSS_S_COMPLETE indicates that context-level information was - successfully initialized, and that the returned output_token - will provide sufficient information for the target to perform - per-message processing on the newly-established context. - - o GSS_S_CONTINUE_NEEDED indicates that control information in the - returned output_token must be sent to the target, and that a - reply must be received and passed as the input_token argument - to a continuation call to GSS_Init_sec_context(), before - per-message processing can be performed in conjunction with - this context. - - o GSS_S_DEFECTIVE_TOKEN indicates that consistency checks - performed on the input_token failed, preventing further - processing from being performed based on that token. - - o GSS_S_DEFECTIVE_CREDENTIAL indicates that consistency checks - performed on the credential structure referenced by - claimant_cred_handle failed, preventing further processing from - being performed using that credential structure. - - o GSS_S_BAD_SIG indicates that the received input_token - contains an incorrect integrity check, so context setup cannot - be accomplished. - - o GSS_S_NO_CRED indicates that no context was established, - either because the input cred_handle was invalid, because the - referenced credentials are valid for context acceptor use - only, or because the caller lacks authorization to access the - referenced credentials. - - o GSS_S_CREDENTIALS_EXPIRED indicates that the credentials - provided through the input claimant_cred_handle argument are no - longer valid, so context establishment cannot be completed. - - - -Linn Standards Track [Page 36] - -RFC 2078 GSS-API January 1997 - - - o GSS_S_BAD_BINDINGS indicates that a mismatch between the - caller-provided chan_bindings and those extracted from the - input_token was detected, signifying a security-relevant - event and preventing context establishment. (This result will - be returned by GSS_Init_sec_context only for contexts where - mutual_state is TRUE.) - - o GSS_S_OLD_TOKEN indicates that the input_token is too old to - be checked for integrity. This is a fatal error during context - establishment. - - o GSS_S_DUPLICATE_TOKEN indicates that the input token has a - correct integrity check, but is a duplicate of a token already - processed. This is a fatal error during context establishment. - - o GSS_S_NO_CONTEXT indicates that no valid context was recognized - for the input context_handle provided; this major status will - be returned only for successor calls following GSS_S_CONTINUE_ - NEEDED status returns. - - o GSS_S_BAD_NAMETYPE indicates that the provided targ_name is - of a type uninterpretable or unsupported by the applicable - underlying GSS-API mechanism(s), so context establishment - cannot be completed. - - o GSS_S_BAD_NAME indicates that the provided targ_name is - inconsistent in terms of internally-incorporated type specifier - information, so context establishment cannot be accomplished. - - o GSS_S_BAD_MECH indicates receipt of a context establishment token - or of a caller request specifying a mechanism unsupported by - the local system or with the caller's active credentials - - o GSS_S_FAILURE indicates that context setup could not be - accomplished for reasons unspecified at the GSS-API level, and - that no interface-defined recovery action is available. - - This routine is used by a context initiator, and ordinarily emits one - (or, for the case of a multi-step exchange, more than one) - output_token suitable for use by the target within the selected - mech_type's protocol. Using information in the credentials structure - referenced by claimant_cred_handle, GSS_Init_sec_context() - initializes the data structures required to establish a security - context with target targ_name. The targ_name may be any valid - INTERNAL NAME; it need not be an MN. The claimant_cred_handle must - correspond to the same valid credentials structure on the initial - call to GSS_Init_sec_context() and on any successor calls resulting - from GSS_S_CONTINUE_NEEDED status returns; different protocol - - - -Linn Standards Track [Page 37] - -RFC 2078 GSS-API January 1997 - - - sequences modeled by the GSS_S_CONTINUE_NEEDED facility will require - access to credentials at different points in the context - establishment sequence. - - The input_context_handle argument is 0, specifying "not yet - assigned", on the first GSS_Init_sec_context() call relating to a - given context. If successful (i.e., if accompanied by major_status - GSS_S_COMPLETE or GSS_S_CONTINUE_NEEDED), and only if successful, the - initial GSS_Init_sec_context() call returns a non-zero - output_context_handle for use in future references to this context. - Once a non-zero output_context_handle has been returned, GSS-API - callers should call GSS_Delete_sec_context() to release context- - related resources if errors occur in later phases of context - establishment, or when an established context is no longer required. - - When continuation attempts to GSS_Init_sec_context() are needed to - perform context establishment, the previously-returned non-zero - handle value is entered into the input_context_handle argument and - will be echoed in the returned output_context_handle argument. On - such continuation attempts (and only on continuation attempts) the - input_token value is used, to provide the token returned from the - context's target. - - The chan_bindings argument is used by the caller to provide - information binding the security context to security-related - characteristics (e.g., addresses, cryptographic keys) of the - underlying communications channel. See Section 1.1.6 of this document - for more discussion of this argument's usage. - - The input_token argument contains a message received from the target, - and is significant only on a call to GSS_Init_sec_context() which - follows a previous return indicating GSS_S_CONTINUE_NEEDED - major_status. - - It is the caller's responsibility to establish a communications path - to the target, and to transmit any returned output_token (independent - of the accompanying returned major_status value) to the target over - that path. The output_token can, however, be transmitted along with - the first application-provided input message to be processed by - GSS_GetMIC() or GSS_Wrap() in conjunction with a successfully- - established context. - - The initiator may request various context-level functions through - input flags: the deleg_req_flag requests delegation of access rights, - the mutual_req_flag requests mutual authentication, the - replay_det_req_flag requests that replay detection features be - applied to messages transferred on the established context, and the - sequence_req_flag requests that sequencing be enforced. (See Section - - - -Linn Standards Track [Page 38] - -RFC 2078 GSS-API January 1997 - - - 1.2.3 for more information on replay detection and sequencing - features.) The anon_req_flag requests that the initiator's identity - not be transferred within tokens to be sent to the acceptor. - - Not all of the optionally-requestable features will be available in - all underlying mech_types. The corresponding return state values - deleg_state, mutual_state, replay_det_state, and sequence_state - indicate, as a function of mech_type processing capabilities and - initiator-provided input flags, the set of features which will be - active on the context. The returned trans_state value indicates - whether the context is transferable to other processes through use of - GSS_Export_sec_context(). These state indicators' values are - undefined unless either the routine's major_status indicates - GSS_S_COMPLETE, or TRUE prot_ready_state is returned along with - GSS_S_CONTINUE_NEEDED major_status; for the latter case, it is - possible that additional features, not confirmed or indicated along - with TRUE prot_ready_state, will be confirmed and indicated when - GSS_S_COMPLETE is subsequently returned. - - The returned anon_state and prot_ready_state values are significant - for both GSS_S_COMPLETE and GSS_S_CONTINUE_NEEDED major_status - returns from GSS_Init_sec_context(). When anon_state is returned - TRUE, this indicates that neither the current token nor its - predecessors delivers or has delivered the initiator's identity. - Callers wishing to perform context establishment only if anonymity - support is provided should transfer a returned token from - GSS_Init_sec_context() to the peer only if it is accompanied by a - TRUE anon_state indicator. When prot_ready_state is returned TRUE in - conjunction with GSS_S_CONTINUE_NEEDED major_status, this indicates - that per-message protection operations may be applied on the context: - see Section 1.2.7 for further discussion of this facility. - - Failure to provide the precise set of features requested by the - caller does not cause context establishment to fail; it is the - caller's prerogative to delete the context if the feature set - provided is unsuitable for the caller's use. - - The returned mech_type value indicates the specific mechanism - employed on the context, is valid only along with major_status - GSS_S_COMPLETE, and will never indicate the value for "default". - Note that, for the case of certain mechanisms which themselves - perform negotiation, the returned mech_type result may indicate - selection of a mechanism identified by an OID different than that - passed in the input mech_type argument. - - The conf_avail return value indicates whether the context supports - per-message confidentiality services, and so informs the caller - whether or not a request for encryption through the conf_req_flag - - - -Linn Standards Track [Page 39] - -RFC 2078 GSS-API January 1997 - - - input to GSS_Wrap() can be honored. In similar fashion, the - integ_avail return value indicates whether per-message integrity - services are available (through either GSS_GetMIC() or GSS_Wrap()) on - the established context. These state indicators' values are undefined - unless either the routine's major_status indicates GSS_S_COMPLETE, or - TRUE prot_ready_state is returned along with GSS_S_CONTINUE_NEEDED - major_status. - - The lifetime_req input specifies a desired upper bound for the - lifetime of the context to be established, with a value of 0 used to - request a default lifetime. The lifetime_rec return value indicates - the length of time for which the context will be valid, expressed as - an offset from the present; depending on mechanism capabilities, - credential lifetimes, and local policy, it may not correspond to the - value requested in lifetime_req. If no constraints on context - lifetime are imposed, this may be indicated by returning a reserved - value representing INDEFINITE lifetime_req. The value of lifetime_rec - is undefined unless the routine's major_status indicates - GSS_S_COMPLETE. - - If the mutual_state is TRUE, this fact will be reflected within the - output_token. A call to GSS_Accept_sec_context() at the target in - conjunction with such a context will return a token, to be processed - by a continuation call to GSS_Init_sec_context(), in order to - achieve mutual authentication. - -2.2.2: GSS_Accept_sec_context call - - Inputs: - - o acceptor_cred_handle CREDENTIAL HANDLE, -- NULL specifies - "use default" - - o input_context_handle CONTEXT HANDLE, -- 0 specifies - "not yet assigned" - - o chan_bindings OCTET STRING, - - o input_token OCTET STRING - - Outputs: - - o major_status INTEGER, - - o minor_status INTEGER, - - o src_name INTERNAL NAME, -- guaranteed to be MN - - - - -Linn Standards Track [Page 40] - -RFC 2078 GSS-API January 1997 - - - o mech_type OBJECT IDENTIFIER, - - o output_context_handle CONTEXT HANDLE, - - o deleg_state BOOLEAN, - - o mutual_state BOOLEAN, - - o replay_det_state BOOLEAN, - - o sequence_state BOOLEAN, - - o anon_state BOOLEAN, - - o trans_state BOOLEAN, - - o prot_ready_state BOOLEAN, -- see Section 1.2.7 for discussion - - o conf_avail BOOLEAN, - - o integ_avail BOOLEAN, - - o lifetime_rec INTEGER, - in seconds, or reserved value for - INDEFINITE - - o delegated_cred_handle CREDENTIAL HANDLE, - - o output_token OCTET STRING -NULL or token to pass to context - initiator - - This call may block pending network interactions for those mech_types - in which a directory service or other network entity must be - consulted on behalf of a context acceptor in order to validate a - received input_token. - - Return major_status codes: - - o GSS_S_COMPLETE indicates that context-level data structures - were successfully initialized, and that per-message processing - can now be performed in conjunction with this context. - - o GSS_S_CONTINUE_NEEDED indicates that control information in the - returned output_token must be sent to the initiator, and that - a response must be received and passed as the input_token - argument to a continuation call to GSS_Accept_sec_context(), - before per-message processing can be performed in conjunction - with this context. - - - - -Linn Standards Track [Page 41] - -RFC 2078 GSS-API January 1997 - - - o GSS_S_DEFECTIVE_TOKEN indicates that consistency checks performed - on the input_token failed, preventing further processing from - being performed based on that token. - - o GSS_S_DEFECTIVE_CREDENTIAL indicates that consistency checks - performed on the credential structure referenced by - acceptor_cred_handle failed, preventing further processing from - being performed using that credential structure. - - o GSS_S_BAD_SIG indicates that the received input_token contains - an incorrect integrity check, so context setup cannot be - accomplished. - - o GSS_S_DUPLICATE_TOKEN indicates that the integrity check on the - received input_token was correct, but that the input_token - was recognized as a duplicate of an input_token already - processed. No new context is established. - - o GSS_S_OLD_TOKEN indicates that the integrity check on the received - input_token was correct, but that the input_token is too old - to be checked for duplication against previously-processed - input_tokens. No new context is established. - - o GSS_S_NO_CRED indicates that no context was established, either - because the input cred_handle was invalid, because the - referenced credentials are valid for context initiator use - only, or because the caller lacks authorization to access the - referenced credentials. - - o GSS_S_CREDENTIALS_EXPIRED indicates that the credentials provided - through the input acceptor_cred_handle argument are no - longer valid, so context establishment cannot be completed. - - o GSS_S_BAD_BINDINGS indicates that a mismatch between the - caller-provided chan_bindings and those extracted from the - input_token was detected, signifying a security-relevant - event and preventing context establishment. - - o GSS_S_NO_CONTEXT indicates that no valid context was recognized - for the input context_handle provided; this major status will - be returned only for successor calls following GSS_S_CONTINUE_ - NEEDED status returns. - - o GSS_S_BAD_MECH indicates receipt of a context establishment token - specifying a mechanism unsupported by the local system or with - the caller's active credentials. - - - - - -Linn Standards Track [Page 42] - -RFC 2078 GSS-API January 1997 - - - o GSS_S_FAILURE indicates that context setup could not be - accomplished for reasons unspecified at the GSS-API level, and - that no interface-defined recovery action is available. - - The GSS_Accept_sec_context() routine is used by a context target. - Using information in the credentials structure referenced by the - input acceptor_cred_handle, it verifies the incoming input_token and - (following the successful completion of a context establishment - sequence) returns the authenticated src_name and the mech_type used. - The returned src_name is guaranteed to be an MN, processed by the - mechanism under which the context was established. The - acceptor_cred_handle must correspond to the same valid credentials - structure on the initial call to GSS_Accept_sec_context() and on any - successor calls resulting from GSS_S_CONTINUE_NEEDED status returns; - different protocol sequences modeled by the GSS_S_CONTINUE_NEEDED - mechanism will require access to credentials at different points in - the context establishment sequence. - - The input_context_handle argument is 0, specifying "not yet - assigned", on the first GSS_Accept_sec_context() call relating to a - given context. If successful (i.e., if accompanied by major_status - GSS_S_COMPLETE or GSS_S_CONTINUE_NEEDED), and only if successful, the - initial GSS_Accept_sec_context() call returns a non-zero - output_context_handle for use in future references to this context. - Once a non-zero output_context_handle has been returned, GSS-API - callers should call GSS_Delete_sec_context() to release context- - related resources if errors occur in later phases of context - establishment, or when an established context is no longer required. - - The chan_bindings argument is used by the caller to provide - information binding the security context to security-related - characteristics (e.g., addresses, cryptographic keys) of the - underlying communications channel. See Section 1.1.6 of this document - for more discussion of this argument's usage. - - The returned state results (deleg_state, mutual_state, - replay_det_state, sequence_state, anon_state, trans_state, and - prot_ready_state) reflect the same information as described for - GSS_Init_sec_context(), and their values are significant under the - same return state conditions. - - - - - - - - - - - -Linn Standards Track [Page 43] - -RFC 2078 GSS-API January 1997 - - - The conf_avail return value indicates whether the context supports - per-message confidentiality services, and so informs the caller - whether or not a request for encryption through the conf_req_flag - input to GSS_Wrap() can be honored. In similar fashion, the - integ_avail return value indicates whether per-message integrity - services are available (through either GSS_GetMIC() or GSS_Wrap()) - on the established context. These values are significant under the - same return state conditions as described under - GSS_Init_sec_context(). - - The lifetime_rec return value is significant only in conjunction with - GSS_S_COMPLETE major_status, and indicates the length of time for - which the context will be valid, expressed as an offset from the - present. - - The mech_type return value indicates the specific mechanism employed - on the context, is valid only along with major_status GSS_S_COMPLETE, - and will never indicate the value for "default". - - The delegated_cred_handle result is significant only when deleg_state - is TRUE, and provides a means for the target to reference the - delegated credentials. The output_token result, when non-NULL, - provides a context-level token to be returned to the context - initiator to continue a multi-step context establishment sequence. As - noted with GSS_Init_sec_context(), any returned token should be - transferred to the context's peer (in this case, the context - initiator), independent of the value of the accompanying returned - major_status. - - Note: A target must be able to distinguish a context-level - input_token, which is passed to GSS_Accept_sec_context(), from the - per-message data elements passed to GSS_VerifyMIC() or GSS_Unwrap(). - These data elements may arrive in a single application message, and - GSS_Accept_sec_context() must be performed before per-message - processing can be performed successfully. - -2.2.3: GSS_Delete_sec_context call - - Input: - - o context_handle CONTEXT HANDLE - - Outputs: - - o major_status INTEGER, - - o minor_status INTEGER, - - - - -Linn Standards Track [Page 44] - -RFC 2078 GSS-API January 1997 - - - o output_context_token OCTET STRING - - Return major_status codes: - - o GSS_S_COMPLETE indicates that the context was recognized, and that - relevant context-specific information was flushed. If the caller - provides a non-null buffer to receive an output_context_token, and - the mechanism returns a non-NULL token into that buffer, the - returned output_context_token is ready for transfer to the - context's peer. - - o GSS_S_NO_CONTEXT indicates that no valid context was recognized - for the input context_handle provided, so no deletion was - performed. - - o GSS_S_FAILURE indicates that the context is recognized, but - that the GSS_Delete_sec_context() operation could not be - performed for reasons unspecified at the GSS-API level. - - This call may block pending network interactions for mech_types in - which active notification must be made to a central server when a - security context is to be deleted. - - This call can be made by either peer in a security context, to flush - context-specific information. If a non-null output_context_token - parameter is provided by the caller, an output_context_token may be - returned to the caller. If an output_context_token is provided to - the caller, it can be passed to the context's peer to inform the - peer's GSS-API implementation that the peer's corresponding context - information can also be flushed. (Once a context is established, the - peers involved are expected to retain cached credential and context- - related information until the information's expiration time is - reached or until a GSS_Delete_sec_context() call is made.) - - The facility for context_token usage to signal context deletion is - retained for compatibility with GSS-API Version 1. For current - usage, it is recommended that both peers to a context invoke - GSS_Delete_sec_context() independently, passing a null - output_context_token buffer to indicate that no context_token is - required. Implementations of GSS_Delete_sec_context() should delete - relevant locally-stored context information. - - Attempts to perform per-message processing on a deleted context will - result in error returns. - - - - - - - -Linn Standards Track [Page 45] - -RFC 2078 GSS-API January 1997 - - -2.2.4: GSS_Process_context_token call - - Inputs: - - o context_handle CONTEXT HANDLE, - - o input_context_token OCTET STRING - - Outputs: - - o major_status INTEGER, - - o minor_status INTEGER, - - Return major_status codes: - - o GSS_S_COMPLETE indicates that the input_context_token was - successfully processed in conjunction with the context - referenced by context_handle. - - o GSS_S_DEFECTIVE_TOKEN indicates that consistency checks - performed on the received context_token failed, preventing - further processing from being performed with that token. - - o GSS_S_NO_CONTEXT indicates that no valid context was recognized - for the input context_handle provided. - - o GSS_S_FAILURE indicates that the context is recognized, but - that the GSS_Process_context_token() operation could not be - performed for reasons unspecified at the GSS-API level. - - This call is used to process context_tokens received from a peer once - a context has been established, with corresponding impact on - context-level state information. One use for this facility is - processing of the context_tokens generated by - GSS_Delete_sec_context(); GSS_Process_context_token() will not block - pending network interactions for that purpose. Another use is to - process tokens indicating remote-peer context establishment failures - after the point where the local GSS-API implementation has already - indicated GSS_S_COMPLETE status. - - - - - - - - - - - -Linn Standards Track [Page 46] - -RFC 2078 GSS-API January 1997 - - -2.2.5: GSS_Context_time call - - Input: - - o context_handle CONTEXT HANDLE, - - Outputs: - - o major_status INTEGER, - - o minor_status INTEGER, - - o lifetime_rec INTEGER - in seconds, or reserved value for - INDEFINITE - - Return major_status codes: - - o GSS_S_COMPLETE indicates that the referenced context is valid, - and will remain valid for the amount of time indicated in - lifetime_rec. - - o GSS_S_CONTEXT_EXPIRED indicates that data items related to the - referenced context have expired. - - o GSS_S_CREDENTIALS_EXPIRED indicates that the context is - recognized, but that its associated credentials have expired. - - o GSS_S_NO_CONTEXT indicates that no valid context was recognized - for the input context_handle provided. - - o GSS_S_FAILURE indicates that the requested operation failed for - reasons unspecified at the GSS-API level. - - This call is used to determine the amount of time for which a - currently established context will remain valid. - -2.2.6: GSS_Inquire_context call - - Input: - - o context_handle CONTEXT HANDLE, - - Outputs: - - o major_status INTEGER, - - o minor_status INTEGER, - - - - -Linn Standards Track [Page 47] - -RFC 2078 GSS-API January 1997 - - - o src_name INTERNAL NAME, -- name of context initiator, - -- guaranteed to be MN - - o targ_name INTERNAL NAME, -- name of context target, - -- guaranteed to be MN - - - o lifetime_rec INTEGER -- in seconds, or reserved value for - INDEFINITE, - - o mech_type OBJECT IDENTIFIER, -- the mechanism supporting this - security context - - o deleg_state BOOLEAN, - - o mutual_state BOOLEAN, - - o replay_det_state BOOLEAN, - - o sequence_state BOOLEAN, - - o anon_state BOOLEAN, - - o trans_state BOOLEAN, - - o prot_ready_state BOOLEAN, - - o conf_avail BOOLEAN, - - o integ_avail BOOLEAN, - - o locally_initiated BOOLEAN, -- TRUE if initiator, FALSE if acceptor - - Return major_status codes: - - o GSS_S_COMPLETE indicates that the referenced context is valid - and that src_name, targ_name, lifetime_rec, mech_type, deleg_state, - mutual_state, replay_det_state, sequence_state, anon_state, - trans_state, prot_ready_state, conf_avail, integ_avail, and - locally_initiated return values describe the corresponding - characteristics of the context. - - o GSS_S_CONTEXT_EXPIRED indicates that the provided input - context_handle is recognized, but that the referenced context - has expired. Return values other than major_status and - minor_status are undefined. - - - - - -Linn Standards Track [Page 48] - -RFC 2078 GSS-API January 1997 - - - o GSS_S_NO_CONTEXT indicates that no valid context was recognized - for the input context_handle provided. Return values other than - major_status and minor_status are undefined. - - o GSS_S_FAILURE indicates that the requested operation failed for - reasons unspecified at the GSS-API level. Return values other than - major_status and minor_status are undefined. - - This call is used to extract information describing characteristics - of a security context. - -2.2.7: GSS_Wrap_size_limit call - - Inputs: - - o context_handle CONTEXT HANDLE, - - o qop INTEGER, - - o output_size INTEGER - - Outputs: - - o major_status INTEGER, - - o minor_status INTEGER, - - o max_input_size INTEGER - - Return major_status codes: - - o GSS_S_COMPLETE indicates a successful token size determination: - an input message with a length in octets equal to the - returned max_input_size value will, when passed to GSS_Wrap() - for processing on the context identified by the context_handle - parameter and with the quality of protection specifier provided - in the qop parameter, yield an output token no larger than the - value of the provided output_size parameter. - - o GSS_S_CONTEXT_EXPIRED indicates that the provided input - context_handle is recognized, but that the referenced context - has expired. Return values other than major_status and - minor_status are undefined. - - o GSS_S_NO_CONTEXT indicates that no valid context was recognized - for the input context_handle provided. Return values other than - major_status and minor_status are undefined. - - - - -Linn Standards Track [Page 49] - -RFC 2078 GSS-API January 1997 - - - o GSS_S_BAD_QOP indicates that the provided QOP value is not - recognized or supported for the context. - - o GSS_S_FAILURE indicates that the requested operation failed for - reasons unspecified at the GSS-API level. Return values other than - major_status and minor_status are undefined. - - This call is used to determine the largest input datum which may be - passed to GSS_Wrap() without yielding an output token larger than a - caller-specified value. - -2.2.8: GSS_Export_sec_context call - - Inputs: - - o context_handle CONTEXT HANDLE - - Outputs: - - o major_status INTEGER, - - o minor_status INTEGER, - - o interprocess_token OCTET STRING - - Return major_status codes: - - o GSS_S_COMPLETE indicates that the referenced context has been - successfully exported to a representation in the interprocess_token, - and is no longer available for use by the caller. - - o GSS_S_UNAVAILABLE indicates that the context export facility - is not available for use on the referenced context. (This status - should occur only for contexts for which the trans_state value is - FALSE.) Return values other than major_status and minor_status are - undefined. - - o GSS_S_CONTEXT_EXPIRED indicates that the provided input - context_handle is recognized, but that the referenced context has - expired. Return values other than major_status and minor_status are - undefined. - - o GSS_S_NO_CONTEXT indicates that no valid context was recognized - for the input context_handle provided. Return values other than - major_status and minor_status are undefined. - - - - - - -Linn Standards Track [Page 50] - -RFC 2078 GSS-API January 1997 - - - o GSS_S_FAILURE indicates that the requested operation failed for - reasons unspecified at the GSS-API level. Return values other than - major_status and minor_status are undefined. - - This call generates an interprocess token for transfer to another - process within an end system, in order to transfer control of a - security context to that process. The recipient of the interprocess - token will call GSS_Import_sec_context() to accept the transfer. The - GSS_Export_sec_context() operation is defined for use only with - security contexts which are fully and successfully established (i.e., - those for which GSS_Init_sec_context() and GSS_Accept_sec_context() - have returned GSS_S_COMPLETE major_status). - - To ensure portability, a caller of GSS_Export_sec_context() must not - assume that a context may continue to be used once it has been - exported; following export, the context referenced by the - context_handle cannot be assumed to remain valid. Further, portable - callers must not assume that a given interprocess token can be - imported by GSS_Import_sec_context() more than once, thereby creating - multiple instantiations of a single context. GSS-API implementations - may detect and reject attempted multiple imports, but are not - required to do so. - - The internal representation contained within the interprocess token - is an implementation-defined local matter. Interprocess tokens - cannot be assumed to be transferable across different GSS-API - implementations. - - It is recommended that GSS-API implementations adopt policies suited - to their operational environments in order to define the set of - processes eligible to import a context, but specific constraints in - this area are local matters. Candidate examples include transfers - between processes operating on behalf of the same user identity, or - processes comprising a common job. However, it may be impossible to - enforce such policies in some implementations. - - In support of the above goals, implementations may protect the - transferred context data by using cryptography to protect data within - the interprocess token, or by using interprocess tokens as a means to - reference local interprocess communication facilities (protected by - other means) rather than storing the context data directly within the - tokens. - - Transfer of an open context may, for certain mechanisms and - implementations, reveal data about the credential which was used to - establish the context. Callers should, therefore, be cautious about - the trustworthiness of processes to which they transfer contexts. - Although the GSS-API implementation may provide its own set of - - - -Linn Standards Track [Page 51] - -RFC 2078 GSS-API January 1997 - - - protections over the exported context, the caller is responsible for - protecting the interprocess token from disclosure, and for taking - care that the context is transferred to an appropriate destination - process. - -2.2.9: GSS_Import_sec_context call - - Inputs: - - o interprocess_token OCTET STRING - - Outputs: - - o major_status INTEGER, - - o minor_status INTEGER, - - o context_handle CONTEXT HANDLE - - Return major_status codes: - - o GSS_S_COMPLETE indicates that the context represented by the - input interprocess_token has been successfully transferred to - the caller, and is available for future use via the output - context_handle. - - o GSS_S_CONTEXT_EXPIRED indicates that the context represented by - the input interprocess_token has expired. Return values other - than major_status and minor_status are undefined. - - o GSS_S_NO_CONTEXT indicates that the context represented by the - input interprocess_token was invalid. Return values other than - major_status and minor_status are undefined. - - o GSS_S_DEFECTIVE_TOKEN indicates that the input interprocess_token - was defective. Return values other than major_status and - minor_status are undefined. - - o GSS_S_UNAVAILABLE indicates that the context import facility - is not available for use on the referenced context. Return values - other than major_status and minor_status are undefined. - - o GSS_S_UNAUTHORIZED indicates that the context represented by - the input interprocess_token is unauthorized for transfer to the - caller. Return values other than major_status and minor_status - are undefined. - - - - - -Linn Standards Track [Page 52] - -RFC 2078 GSS-API January 1997 - - - o GSS_S_FAILURE indicates that the requested operation failed for - reasons unspecified at the GSS-API level. Return values other than - major_status and minor_status are undefined. - - This call processes an interprocess token generated by - GSS_Export_sec_context(), making the transferred context available - for use by the caller. After a successful GSS_Import_sec_context() - operation, the imported context is available for use by the importing - process. - - For further discussion of the security and authorization issues - regarding this call, please see the discussion in Section 2.2.8. - -2.3: Per-message calls - - This group of calls is used to perform per-message protection - processing on an established security context. None of these calls - block pending network interactions. These calls may be invoked by a - context's initiator or by the context's target. The four members of - this group should be considered as two pairs; the output from - GSS_GetMIC() is properly input to GSS_VerifyMIC(), and the output - from GSS_Wrap() is properly input to GSS_Unwrap(). - - GSS_GetMIC() and GSS_VerifyMIC() support data origin authentication - and data integrity services. When GSS_GetMIC() is invoked on an - input message, it yields a per-message token containing data items - which allow underlying mechanisms to provide the specified security - services. The original message, along with the generated per-message - token, is passed to the remote peer; these two data elements are - processed by GSS_VerifyMIC(), which validates the message in - conjunction with the separate token. - - GSS_Wrap() and GSS_Unwrap() support caller-requested confidentiality - in addition to the data origin authentication and data integrity - services offered by GSS_GetMIC() and GSS_VerifyMIC(). GSS_Wrap() - outputs a single data element, encapsulating optionally enciphered - user data as well as associated token data items. The data element - output from GSS_Wrap() is passed to the remote peer and processed by - GSS_Unwrap() at that system. GSS_Unwrap() combines decipherment (as - required) with validation of data items related to authentication and - integrity. - - - - - - - - - - -Linn Standards Track [Page 53] - -RFC 2078 GSS-API January 1997 - - -2.3.1: GSS_GetMIC call - - Note: This call is functionally equivalent to the GSS_Sign call as - defined in previous versions of this specification. In the interests - of backward compatibility, it is recommended that implementations - support this function under both names for the present; future - references to this function as GSS_Sign are deprecated. - - Inputs: - - o context_handle CONTEXT HANDLE, - - o qop_req INTEGER,-0 specifies default QOP - - o message OCTET STRING - - Outputs: - - o major_status INTEGER, - - o minor_status INTEGER, - - o per_msg_token OCTET STRING - - Return major_status codes: - - o GSS_S_COMPLETE indicates that an integrity check, suitable for an - established security context, was successfully applied and - that the message and corresponding per_msg_token are ready - for transmission. - - o GSS_S_CONTEXT_EXPIRED indicates that context-related data - items have expired, so that the requested operation cannot be - performed. - - o GSS_S_CREDENTIALS_EXPIRED indicates that the context is recognized, - but that its associated credentials have expired, so - that the requested operation cannot be performed. - - o GSS_S_NO_CONTEXT indicates that no valid context was recognized - for the input context_handle provided. - - o GSS_S_BAD_QOP indicates that the provided QOP value is not - recognized or supported for the context. - - o GSS_S_FAILURE indicates that the context is recognized, but - that the requested operation could not be performed for - reasons unspecified at the GSS-API level. - - - -Linn Standards Track [Page 54] - -RFC 2078 GSS-API January 1997 - - - Using the security context referenced by context_handle, apply an - integrity check to the input message (along with timestamps and/or - other data included in support of mech_type-specific mechanisms) and - return the result in per_msg_token. The qop_req parameter, - interpretation of which is discussed in Section 1.2.4, allows - quality-of-protection control. The caller passes the message and the - per_msg_token to the target. - - The GSS_GetMIC() function completes before the message and - per_msg_token is sent to the peer; successful application of - GSS_GetMIC() does not guarantee that a corresponding GSS_VerifyMIC() - has been (or can necessarily be) performed successfully when the - message arrives at the destination. - - Mechanisms which do not support per-message protection services - should return GSS_S_FAILURE if this routine is called. - -2.3.2: GSS_VerifyMIC call - - Note: This call is functionally equivalent to the GSS_Verify call as - defined in previous versions of this specification. In the interests - of backward compatibility, it is recommended that implementations - support this function under both names for the present; future - references to this function as GSS_Verify are deprecated. - - Inputs: - - o context_handle CONTEXT HANDLE, - - o message OCTET STRING, - - o per_msg_token OCTET STRING - - Outputs: - - o qop_state INTEGER, - - o major_status INTEGER, - - o minor_status INTEGER, - - Return major_status codes: - - o GSS_S_COMPLETE indicates that the message was successfully - verified. - - - - - - -Linn Standards Track [Page 55] - -RFC 2078 GSS-API January 1997 - - - o GSS_S_DEFECTIVE_TOKEN indicates that consistency checks performed - on the received per_msg_token failed, preventing - further processing from being performed with that token. - - o GSS_S_BAD_SIG indicates that the received per_msg_token contains - an incorrect integrity check for the message. - - o GSS_S_DUPLICATE_TOKEN, GSS_S_OLD_TOKEN, GSS_S_UNSEQ_TOKEN, - and GSS_S_GAP_TOKEN values appear in conjunction with the - optional per-message replay detection features described - in Section 1.2.3; their semantics are described in that section. - - o GSS_S_CONTEXT_EXPIRED indicates that context-related data - items have expired, so that the requested operation cannot be - performed. - - o GSS_S_CREDENTIALS_EXPIRED indicates that the context is - recognized, - but that its associated credentials have expired, so - that the requested operation cannot be performed. - - o GSS_S_NO_CONTEXT indicates that no valid context was recognized - for the input context_handle provided. - - o GSS_S_FAILURE indicates that the context is recognized, but - that the GSS_VerifyMIC() operation could not be performed for - reasons unspecified at the GSS-API level. - - Using the security context referenced by context_handle, verify that - the input per_msg_token contains an appropriate integrity check for - the input message, and apply any active replay detection or - sequencing features. Return an indication of the quality-of- - protection applied to the processed message in the qop_state result. - Since the GSS_VerifyMIC() routine never provides a confidentiality - service, its implementations should not return non-zero values in the - confidentiality fields of the output qop_state. - - Mechanisms which do not support per-message protection services - should return GSS_S_FAILURE if this routine is called. - -2.3.3: GSS_Wrap call - - Note: This call is functionally equivalent to the GSS_Seal call as - defined in previous versions of this specification. In the interests - of backward compatibility, it is recommended that implementations - support this function under both names for the present; future - references to this function as GSS_Seal are deprecated. - - - - -Linn Standards Track [Page 56] - -RFC 2078 GSS-API January 1997 - - - Inputs: - - o context_handle CONTEXT HANDLE, - - o conf_req_flag BOOLEAN, - - o qop_req INTEGER,-0 specifies default QOP - - o input_message OCTET STRING - - Outputs: - - o major_status INTEGER, - - o minor_status INTEGER, - - o conf_state BOOLEAN, - - o output_message OCTET STRING - - Return major_status codes: - - o GSS_S_COMPLETE indicates that the input_message was successfully - processed and that the output_message is ready for - transmission. - - o GSS_S_CONTEXT_EXPIRED indicates that context-related data - items have expired, so that the requested operation cannot be - performed. - - o GSS_S_CREDENTIALS_EXPIRED indicates that the context is - recognized, - but that its associated credentials have expired, so - that the requested operation cannot be performed. - - o GSS_S_NO_CONTEXT indicates that no valid context was recognized - for the input context_handle provided. - - o GSS_S_BAD_QOP indicates that the provided QOP value is not - recognized or supported for the context. - - o GSS_S_FAILURE indicates that the context is recognized, but - that the GSS_Wrap() operation could not be performed for - reasons unspecified at the GSS-API level. - - Performs the data origin authentication and data integrity functions - of GSS_GetMIC(). If the input conf_req_flag is TRUE, requests that - confidentiality be applied to the input_message. Confidentiality may - - - -Linn Standards Track [Page 57] - -RFC 2078 GSS-API January 1997 - - - not be supported in all mech_types or by all implementations; the - returned conf_state flag indicates whether confidentiality was - provided for the input_message. The qop_req parameter, interpretation - of which is discussed in Section 1.2.4, allows quality-of-protection - control. - - In all cases, the GSS_Wrap() call yields a single output_message - data element containing (optionally enciphered) user data as well as - control information. - - Mechanisms which do not support per-message protection services - should return GSS_S_FAILURE if this routine is called. - -2.3.4: GSS_Unwrap call - - Note: This call is functionally equivalent to the GSS_Unseal call as - defined in previous versions of this specification. In the interests - of backward compatibility, it is recommended that implementations - support this function under both names for the present; future - references to this function as GSS_Unseal are deprecated. - - Inputs: - - o context_handle CONTEXT HANDLE, - - o input_message OCTET STRING - - Outputs: - - o conf_state BOOLEAN, - - o qop_state INTEGER, - - o major_status INTEGER, - - o minor_status INTEGER, - - o output_message OCTET STRING - - Return major_status codes: - - o GSS_S_COMPLETE indicates that the input_message was - successfully processed and that the resulting output_message is - available. - - o GSS_S_DEFECTIVE_TOKEN indicates that consistency checks performed - on the per_msg_token extracted from the input_message - failed, preventing further processing from being performed. - - - -Linn Standards Track [Page 58] - -RFC 2078 GSS-API January 1997 - - - o GSS_S_BAD_SIG indicates that an incorrect integrity check was - detected - for the message. - - o GSS_S_DUPLICATE_TOKEN, GSS_S_OLD_TOKEN, GSS_S_UNSEQ_TOKEN, - and GSS_S_GAP_TOKEN values appear in conjunction with the - optional per-message replay detection features described - in Section 1.2.3; their semantics are described in that section. - - o GSS_S_CONTEXT_EXPIRED indicates that context-related data - items have expired, so that the requested operation cannot be - performed. - - o GSS_S_CREDENTIALS_EXPIRED indicates that the context is - recognized, - but that its associated credentials have expired, so - that the requested operation cannot be performed. - - o GSS_S_NO_CONTEXT indicates that no valid context was recognized - for the input context_handle provided. - - o GSS_S_FAILURE indicates that the context is recognized, but - that the GSS_Unwrap() operation could not be performed for - reasons unspecified at the GSS-API level. - - Processes a data element generated (and optionally enciphered) by - GSS_Wrap(), provided as input_message. The returned conf_state value - indicates whether confidentiality was applied to the input_message. - If conf_state is TRUE, GSS_Unwrap() deciphers the input_message. - Returns an indication of the quality-of-protection applied to the - processed message in the qop_state result. GSS_Wrap() performs the - data integrity and data origin authentication checking functions of - GSS_VerifyMIC() on the plaintext data. Plaintext data is returned in - output_message. - - Mechanisms which do not support per-message protection services - should return GSS_S_FAILURE if this routine is called. - -2.4: Support calls - - This group of calls provides support functions useful to GSS-API - callers, independent of the state of established contexts. Their - characterization with regard to blocking or non-blocking status in - terms of network interactions is unspecified. - - - - - - - -Linn Standards Track [Page 59] - -RFC 2078 GSS-API January 1997 - - -2.4.1: GSS_Display_status call - - Inputs: - - o status_value INTEGER,-GSS-API major_status or minor_status - return value - - o status_type INTEGER,-1 if major_status, 2 if minor_status - - o mech_type OBJECT IDENTIFIER-mech_type to be used for minor_ - status translation - - Outputs: - - o major_status INTEGER, - - o minor_status INTEGER, - - o status_string_set SET OF OCTET STRING - - Return major_status codes: - - o GSS_S_COMPLETE indicates that a valid printable status - representation (possibly representing more than one status event - encoded within the status_value) is available in the returned - status_string_set. - - o GSS_S_BAD_MECH indicates that translation in accordance with an - unsupported mech_type was requested, so translation could not - be performed. - - o GSS_S_BAD_STATUS indicates that the input status_value was - invalid, or that the input status_type carried a value other - than 1 or 2, so translation could not be performed. - - o GSS_S_FAILURE indicates that the requested operation could not - be performed for reasons unspecified at the GSS-API level. - - Provides a means for callers to translate GSS-API-returned major and - minor status codes into printable string representations. - -2.4.2: GSS_Indicate_mechs call - - Input: - - o (none) - - - - - -Linn Standards Track [Page 60] - -RFC 2078 GSS-API January 1997 - - - Outputs: - - o major_status INTEGER, - - o minor_status INTEGER, - - o mech_set SET OF OBJECT IDENTIFIER - - Return major_status codes: - - o GSS_S_COMPLETE indicates that a set of available mechanisms has - been returned in mech_set. - - o GSS_S_FAILURE indicates that the requested operation could not - be performed for reasons unspecified at the GSS-API level. - - Allows callers to determine the set of mechanism types available on - the local system. This call is intended for support of specialized - callers who need to request non-default mech_type sets from - GSS_Acquire_cred(), and should not be needed by other callers. - -2.4.3: GSS_Compare_name call - - Inputs: - - o name1 INTERNAL NAME, - - o name2 INTERNAL NAME - - Outputs: - - o major_status INTEGER, - - o minor_status INTEGER, - - o name_equal BOOLEAN - - Return major_status codes: - - o GSS_S_COMPLETE indicates that name1 and name2 were comparable, - and that the name_equal result indicates whether name1 and - name2 represent the same entity. - - o GSS_S_BAD_NAMETYPE indicates that one or both of name1 and - name2 contained internal type specifiers uninterpretable - by the applicable underlying GSS-API mechanism(s), or that - the two names' types are different and incomparable, so that - the comparison operation could not be completed. - - - -Linn Standards Track [Page 61] - -RFC 2078 GSS-API January 1997 - - - o GSS_S_BAD_NAME indicates that one or both of the input names - was ill-formed in terms of its internal type specifier, so - the comparison operation could not be completed. - - o GSS_S_FAILURE indicates that the call's operation could not - be performed for reasons unspecified at the GSS-API level. - - Allows callers to compare two internal name representations to - determine whether they refer to the same entity. If either name - presented to GSS_Compare_name() denotes an anonymous principal, - GSS_Compare_name() shall indicate FALSE. It is not required that - either or both inputs name1 and name2 be MNs; for some - implementations and cases, GSS_S_BAD_NAMETYPE may be returned, - indicating name incomparability, for the case where neither input - name is an MN. - -2.4.4: GSS_Display_name call - - Inputs: - - o name INTERNAL NAME - - Outputs: - - o major_status INTEGER, - - o minor_status INTEGER, - - o name_string OCTET STRING, - - o name_type OBJECT IDENTIFIER - - Return major_status codes: - - o GSS_S_COMPLETE indicates that a valid printable name - representation is available in the returned name_string. - - o GSS_S_BAD_NAMETYPE indicates that the provided name was of a - type uninterpretable by the applicable underlying GSS-API - mechanism(s), so no printable representation could be generated. - - o GSS_S_BAD_NAME indicates that the contents of the provided name - were inconsistent with the internally-indicated name type, so - no printable representation could be generated. - - o GSS_S_FAILURE indicates that the requested operation could not - be performed for reasons unspecified at the GSS-API level. - - - - -Linn Standards Track [Page 62] - -RFC 2078 GSS-API January 1997 - - - Allows callers to translate an internal name representation into a - printable form with associated namespace type descriptor. The syntax - of the printable form is a local matter. - - If the input name represents an anonymous identity, a reserved value - (GSS_C_NT_ANONYMOUS) shall be returned for name_type. - -2.4.5: GSS_Import_name call - - Inputs: - - o input_name_string OCTET STRING, - - o input_name_type OBJECT IDENTIFIER - - Outputs: - - o major_status INTEGER, - - o minor_status INTEGER, - - o output_name INTERNAL NAME - - Return major_status codes: - - o GSS_S_COMPLETE indicates that a valid name representation is - output in output_name and described by the type value in - output_name_type. - - o GSS_S_BAD_NAMETYPE indicates that the input_name_type is unsupported - by the applicable underlying GSS-API mechanism(s), so the import - operation could not be completed. - - o GSS_S_BAD_NAME indicates that the provided input_name_string - is ill-formed in terms of the input_name_type, so the import - operation could not be completed. - - o GSS_S_FAILURE indicates that the requested operation could not - be performed for reasons unspecified at the GSS-API level. - - Allows callers to provide a name representation as a contiguous octet - string, designate the type of namespace in conjunction with which it - should be parsed, and convert that representation to an internal form - suitable for input to other GSS-API routines. The syntax of the - input_name_string is defined in conjunction with its associated name - type; depending on the input_name_type, the associated - input_name_string may or may not be a printable string. Note: The - input_name_type argument serves to describe and qualify the - - - -Linn Standards Track [Page 63] - -RFC 2078 GSS-API January 1997 - - - interpretation of the associated input_name_string; it does not - specify the data type of the returned output_name. - - If a mechanism claims support for a particular name type, its - GSS_Import_name() operation shall be able to accept all possible - values conformant to the external name syntax as defined for that - name type. These imported values may correspond to: - - (1) locally registered entities (for which credentials may be - acquired), - - (2) non-local entities (for which local credentials cannot be - acquired, but which may be referenced as targets of initiated - security contexts or initiators of accepted security contexts), or - to - - (3) neither of the above. - - Determination of whether a particular name belongs to class (1), (2), - or (3) as described above is not guaranteed to be performed by the - GSS_Import_name() function. - - The internal name generated by a GSS_Import_name() operation may be a - single-mechanism MN, and is likely to be an MN within a single- - mechanism implementation, but portable callers must not depend on - this property (and must not, therefore, assume that the output from - GSS_Import_name() can be passed directly to GSS_Export_name() without - first being processed through GSS_Canonicalize_name()). - -2.4.6: GSS_Release_name call - - Inputs: - - o name INTERNAL NAME - - Outputs: - - o major_status INTEGER, - - o minor_status INTEGER - - Return major_status codes: - - o GSS_S_COMPLETE indicates that the storage associated with the - input name was successfully released. - - o GSS_S_BAD_NAME indicates that the input name argument did not - contain a valid name. - - - -Linn Standards Track [Page 64] - -RFC 2078 GSS-API January 1997 - - - o GSS_S_FAILURE indicates that the requested operation could not - be performed for reasons unspecified at the GSS-API level. - - Allows callers to release the storage associated with an internal - name representation. This call's specific behavior depends on the - language and programming environment within which a GSS-API - implementation operates, and is therefore detailed within applicable - bindings specifications; in particular, this call may be superfluous - within bindings where memory management is automatic. - -2.4.7: GSS_Release_buffer call - - Inputs: - - o buffer OCTET STRING - - Outputs: - - o major_status INTEGER, - - o minor_status INTEGER - - Return major_status codes: - - o GSS_S_COMPLETE indicates that the storage associated with the - input buffer was successfully released. - - o GSS_S_FAILURE indicates that the requested operation could not - be performed for reasons unspecified at the GSS-API level. - - Allows callers to release the storage associated with an OCTET STRING - buffer allocated by another GSS-API call. This call's specific - behavior depends on the language and programming environment within - which a GSS-API implementation operates, and is therefore detailed - within applicable bindings specifications; in particular, this call - may be superfluous within bindings where memory management is - automatic. - -2.4.8: GSS_Release_OID_set call - - Inputs: - - o buffer SET OF OBJECT IDENTIFIER - - Outputs: - - o major_status INTEGER, - - - - -Linn Standards Track [Page 65] - -RFC 2078 GSS-API January 1997 - - - o minor_status INTEGER - - Return major_status codes: - - o GSS_S_COMPLETE indicates that the storage associated with the - input object identifier set was successfully released. - - o GSS_S_FAILURE indicates that the requested operation could not - be performed for reasons unspecified at the GSS-API level. - - Allows callers to release the storage associated with an object - identifier set object allocated by another GSS-API call. This call's - specific behavior depends on the language and programming environment - within which a GSS-API implementation operates, and is therefore - detailed within applicable bindings specifications; in particular, - this call may be superfluous within bindings where memory management - is automatic. - -2.4.9: GSS_Create_empty_OID_set call - - Inputs: - - o (none) - - Outputs: - - o major_status INTEGER, - - o minor_status INTEGER, - - o oid_set SET OF OBJECT IDENTIFIER - - Return major_status codes: - - o GSS_S_COMPLETE indicates successful completion - - o GSS_S_FAILURE indicates that the operation failed - - Creates an object identifier set containing no object identifiers, to - which members may be subsequently added using the - GSS_Add_OID_set_member() routine. These routines are intended to be - used to construct sets of mechanism object identifiers, for input to - GSS_Acquire_cred(). - - - - - - - - -Linn Standards Track [Page 66] - -RFC 2078 GSS-API January 1997 - - -2.4.10: GSS_Add_OID_set_member call - - Inputs: - - o member_oid OBJECT IDENTIFIER, - - o oid_set SET OF OBJECT IDENTIFIER - - Outputs: - - o major_status INTEGER, - - o minor_status INTEGER, - - Return major_status codes: - - o GSS_S_COMPLETE indicates successful completion - - o GSS_S_FAILURE indicates that the operation failed - - Adds an Object Identifier to an Object Identifier set. This routine - is intended for use in conjunction with GSS_Create_empty_OID_set() - when constructing a set of mechanism OIDs for input to - GSS_Acquire_cred(). - -2.4.11: GSS_Test_OID_set_member call - - Inputs: - - o member OBJECT IDENTIFIER, - - o set SET OF OBJECT IDENTIFIER - - Outputs: - - o major_status INTEGER, - - o minor_status INTEGER, - - o present BOOLEAN - - Return major_status codes: - - o GSS_S_COMPLETE indicates successful completion - - o GSS_S_FAILURE indicates that the operation failed - - - - - -Linn Standards Track [Page 67] - -RFC 2078 GSS-API January 1997 - - - Interrogates an Object Identifier set to determine whether a - specified Object Identifier is a member. This routine is intended to - be used with OID sets returned by GSS_Indicate_mechs(), - GSS_Acquire_cred(), and GSS_Inquire_cred(). - -2.4.12: GSS_Release_OID call - - Inputs: - - o oid OBJECT IDENTIFIER - - Outputs: - - o major_status INTEGER, - - o minor_status INTEGER - - Return major_status codes: - - o GSS_S_COMPLETE indicates successful completion - - o GSS_S_FAILURE indicates that the operation failed - - Allows the caller to release the storage associated with an OBJECT - IDENTIFIER buffer allocated by another GSS-API call. This call's - specific behavior depends on the language and programming environment - within which a GSS-API implementation operates, and is therefore - detailed within applicable bindings specifications; in particular, - this call may be superfluous within bindings where memory management - is automatic. - -2.4.13: GSS_OID_to_str call - - Inputs: - - o oid OBJECT IDENTIFIER - - Outputs: - - o major_status INTEGER, - - o minor_status INTEGER, - - o oid_str OCTET STRING - - Return major_status codes: - - o GSS_S_COMPLETE indicates successful completion - - - -Linn Standards Track [Page 68] - -RFC 2078 GSS-API January 1997 - - - o GSS_S_FAILURE indicates that the operation failed - - The function GSS_OID_to_str() returns a string representing the input - OID in numeric ASN.1 syntax format (curly-brace enclosed, space- - delimited, e.g., "{2 16 840 1 113687 1 2 1}"). The string is - releasable using GSS_Release_buffer(). If the input "oid" does not - represent a syntactically valid object identifier, GSS_S_FAILURE - status is returned and the returned oid_str result is NULL. - -2.4.14: GSS_Str_to_OID call - - Inputs: - - o oid_str OCTET STRING - - Outputs: - - o major_status INTEGER, - - o minor_status INTEGER, - - o oid OBJECT IDENTIFIER - - Return major_status codes: - - o GSS_S_COMPLETE indicates successful completion - - o GSS_S_FAILURE indicates that the operation failed - - The function GSS_Str_to_OID() constructs and returns an OID from its - printable form; implementations should be able to accept the numeric - ASN.1 syntax form as described for GSS_OID_to_str(), and this form - should be used for portability, but implementations of this routine - may also accept other formats (e.g., "1.2.3.3"). The OID is suitable - for release using the function GSS_Release_OID(). If the input - oid_str cannot be translated into an OID, GSS_S_FAILURE status is - returned and the "oid" result is NULL. - -2.4.15: GSS_Inquire_names_for_mech call - - Input: - - o input_mech_type OBJECT IDENTIFIER, -- mechanism type - - Outputs: - - o major_status INTEGER, - - - - -Linn Standards Track [Page 69] - -RFC 2078 GSS-API January 1997 - - - o minor_status INTEGER, - - o name_type_set SET OF OBJECT IDENTIFIER - - Return major_status codes: - - o GSS_S_COMPLETE indicates that the output name_type_set contains - a list of name types which are supported by the locally available - mechanism identified by input_mech_type. - - o GSS_S_BAD_MECH indicates that the mechanism identified by - input_mech_type was unsupported within the local implementation, - causing the query to fail. - - o GSS_S_FAILURE indicates that the requested operation could not - be performed for reasons unspecified at the GSS-API level. - - Allows callers to determine the set of name types which are - supportable by a specific locally-available mechanism. - -2.4.16: GSS_Inquire_mechs_for_name call - - Inputs: - - o input_name INTERNAL NAME, - - Outputs: - - o major_status INTEGER, - - o minor_status INTEGER, - - o mech_types SET OF OBJECT IDENTIFIER - - Return major_status codes: - - o GSS_S_COMPLETE indicates that a set of object identifiers, - corresponding to the set of mechanisms suitable for processing - the input_name, is available in mech_types. - - o GSS_S_BAD_NAME indicates that the input_name could not be - processed. - - o GSS_S_BAD_NAMETYPE indicates that the type of the input_name - is unsupported by the GSS-API implementation. - - o GSS_S_FAILURE indicates that the requested operation could not - be performed for reasons unspecified at the GSS-API level. - - - -Linn Standards Track [Page 70] - -RFC 2078 GSS-API January 1997 - - - This routine returns the mechanism set with which the input_name may - be processed. After use, the mech_types object should be freed by - the caller via the GSS_Release_OID_set() call. Note: it is - anticipated that implementations of GSS_Inquire_mechs_for_name() will - commonly operate based on type information describing the - capabilities of available mechanisms; it is not guaranteed that all - identified mechanisms will necessarily be able to canonicalize (via - GSS_Canonicalize_name()) a particular name. - -2.4.17: GSS_Canonicalize_name call - - Inputs: - - o input_name INTERNAL NAME, - - o mech_type OBJECT IDENTIFIER -- must be explicit mechanism, - not "default" specifier - - Outputs: - - o major_status INTEGER, - - o minor_status INTEGER, - - o output_name INTERNAL NAME - - Return major_status codes: - - o GSS_S_COMPLETE indicates that a mechanism-specific reduction of - the input_name, as processed by the mechanism identified by - mech_type, is available in output_name. - - o GSS_S_BAD_MECH indicates that the identified mechanism is - unsupported. - - o GSS_S_BAD_NAMETYPE indicates that the input name does not - contain an element with suitable type for processing by the - identified mechanism. - - o GSS_S_BAD_NAME indicates that the input name contains an - element with suitable type for processing by the identified - mechanism, but that this element could not be processed - successfully. - - o GSS_S_FAILURE indicates that the requested operation could not - be performed for reasons unspecified at the GSS-API level. - - - - - -Linn Standards Track [Page 71] - -RFC 2078 GSS-API January 1997 - - - This routine reduces a GSS-API internal name, which may in general - contain elements corresponding to multiple mechanisms, to a - mechanism-specific Mechanism Name (MN) by applying the translations - corresponding to the mechanism identified by mech_type. - -2.4.18: GSS_Export_name call - - Inputs: - - o input_name INTERNAL NAME, -- required to be MN - - Outputs: - - o major_status INTEGER, - - o minor_status INTEGER, - - o output_name OCTET STRING - - Return major_status codes: - - o GSS_S_COMPLETE indicates that a flat representation of the - input name is available in output_name. - - o GSS_S_NAME_NOT_MN indicates that the input name contained - elements corresponding to multiple mechanisms, so cannot - be exported into a single-mechanism flat form. - - o GSS_S_BAD_NAME indicates that the input name was an MN, - but could not be processed. - - o GSS_S_BAD_NAMETYPE indicates that the input name was an MN, - but that its type is unsupported by the GSS-API implementation. - - o GSS_S_FAILURE indicates that the requested operation could not - be performed for reasons unspecified at the GSS-API level. - - This routine creates a flat name representation, suitable for - bytewise comparison or for input to GSS_Import_name() in conjunction - with the reserved GSS-API Exported Name Object OID, from a internal- - form Mechanism Name (MN) as emitted, e.g., by GSS_Canonicalize_name() - or GSS_Accept_sec_context(). - - The emitted GSS-API Exported Name Object is self-describing; no - associated parameter-level OID need be emitted by this call. This - flat representation consists of a mechanism-independent wrapper - layer, defined in Section 3.2 of this document, enclosing a - mechanism-defined name representation. - - - -Linn Standards Track [Page 72] - -RFC 2078 GSS-API January 1997 - - - In all cases, the flat name output by GSS_Export_name() to correspond - to a particular input MN must be invariant over time within a - particular installation. - - The GSS_S_NAME_NOT_MN status code is provided to enable - implementations to reject input names which are not MNs. It is not, - however, required for purposes of conformance to this specification - that all non-MN input names must necessarily be rejected. - -2.4.19: GSS_Duplicate_name call - - Inputs: - - o src_name INTERNAL NAME - - Outputs: - - o major_status INTEGER, - - o minor_status INTEGER, - - o dest_name INTERNAL NAME - - Return major_status codes: - - o GSS_S_COMPLETE indicates that dest_name references an internal - name object containing the same name as passed to src_name. - - o GSS_S_BAD_NAME indicates that the input name was invalid. - - o GSS_S_BAD_NAMETYPE indicates that the input name's type - is unsupported by the GSS-API implementation. - - o GSS_S_FAILURE indicates that the requested operation could not - be performed for reasons unspecified at the GSS-API level. - - This routine takes input internal name src_name, and returns another - reference (dest_name) to that name which can be used even if src_name - is later freed. (Note: This may be implemented by copying or through - use of reference counts.) - -3: Data Structure Definitions for GSS-V2 Usage - - Subsections of this section define, for interoperability and - portability purposes, certain data structures for use with GSS-V2. - - - - - - -Linn Standards Track [Page 73] - -RFC 2078 GSS-API January 1997 - - -3.1: Mechanism-Independent Token Format - - This section specifies a mechanism-independent level of encapsulating - representation for the initial token of a GSS-API context - establishment sequence, incorporating an identifier of the mechanism - type to be used on that context and enabling tokens to be interpreted - unambiguously at GSS-API peers. Use of this format is required for - initial context establishment tokens of Internet standards-track - GSS-API mechanisms; use in non-initial tokens is optional. - - The encoding format for the token tag is derived from ASN.1 and DER - (per illustrative ASN.1 syntax included later within this - subsection), but its concrete representation is defined directly in - terms of octets rather than at the ASN.1 level in order to facilitate - interoperable implementation without use of general ASN.1 processing - code. The token tag consists of the following elements, in order: - - 1. 0x60 -- Tag for [APPLICATION 0] SEQUENCE; indicates that - constructed form, definite length encoding follows. - - 2. Token length octets, specifying length of subsequent data - (i.e., the summed lengths of elements 3-5 in this list, and of the - mechanism-defined token object following the tag). This element - comprises a variable number of octets: - - 2a. If the indicated value is less than 128, it shall be - represented in a single octet with bit 8 (high order) set to "0" - and the remaining bits representing the value. - - 2b. If the indicated value is 128 or more, it shall be represented - in two or more octets, with bit 8 of the first octet set to "1" - and the remaining bits of the first octet specifying the number of - additional octets. The subsequent octets carry the value, 8 bits - per octet, most significant digit first. The minimum number of - octets shall be used to encode the length (i.e., no octets - representing leading zeros shall be included within the length - encoding). - - 3. 0x06 -- Tag for OBJECT IDENTIFIER - - 4. Object identifier length -- length (number of octets) of the - encoded object identifier contained in element 5, encoded per - rules as described in 2a. and 2b. above. - - 5. Object identifier octets -- variable number of octets, encoded - per ASN.1 BER rules: - - - - - -Linn Standards Track [Page 74] - -RFC 2078 GSS-API January 1997 - - - 5a. The first octet contains the sum of two values: (1) the top- - level object identifier component, multiplied by 40 (decimal), and - (2) the second-level object identifier component. This special - case is the only point within an object identifier encoding where - a single octet represents contents of more than one component. - - 5b. Subsequent octets, if required, encode successively-lower - components in the represented object identifier. A component's - encoding may span multiple octets, encoding 7 bits per octet (most - significant bits first) and with bit 8 set to "1" on all but the - final octet in the component's encoding. The minimum number of - octets shall be used to encode each component (i.e., no octets - representing leading zeros shall be included within a component's - encoding). - - (Note: In many implementations, elements 3-5 may be stored and - referenced as a contiguous string constant.) - - The token tag is immediately followed by a mechanism-defined token - object. Note that no independent size specifier intervenes following - the object identifier value to indicate the size of the mechanism- - defined token object. While ASN.1 usage within mechanism-defined - tokens is permitted, there is no requirement that the mechanism- - specific innerContextToken, innerMsgToken, and sealedUserData data - elements must employ ASN.1 BER/DER encoding conventions. - - - - - - - - - - - - - - - - - - - - - - - - - - -Linn Standards Track [Page 75] - -RFC 2078 GSS-API January 1997 - - - The following ASN.1 syntax is included for descriptive purposes only, - to illustrate structural relationships among token and tag objects. - For interoperability purposes, token and tag encoding shall be - performed using the concrete encoding procedures described earlier in - this subsection. - - GSS-API DEFINITIONS ::= - - BEGIN - - MechType ::= OBJECT IDENTIFIER - -- data structure definitions - - -- callers must be able to distinguish among - -- InitialContextToken, SubsequentContextToken, - -- PerMsgToken, and SealedMessage data elements - -- based on the usage in which they occur - - InitialContextToken ::= - -- option indication (delegation, etc.) indicated within - -- mechanism-specific token - [APPLICATION 0] IMPLICIT SEQUENCE { - thisMech MechType, - innerContextToken ANY DEFINED BY thisMech - -- contents mechanism-specific - -- ASN.1 structure not required - } - - SubsequentContextToken ::= innerContextToken ANY - -- interpretation based on predecessor InitialContextToken - -- ASN.1 structure not required - - PerMsgToken ::= - -- as emitted by GSS_GetMIC and processed by GSS_VerifyMIC - -- ASN.1 structure not required - innerMsgToken ANY - - SealedMessage ::= - -- as emitted by GSS_Wrap and processed by GSS_Unwrap - -- includes internal, mechanism-defined indicator - -- of whether or not encrypted - -- ASN.1 structure not required - sealedUserData ANY - - END - - - - - - -Linn Standards Track [Page 76] - -RFC 2078 GSS-API January 1997 - - -3.2: Mechanism-Independent Exported Name Object Format - - This section specifies a mechanism-independent level of encapsulating - representation for names exported via the GSS_Export_name() call, - including an object identifier representing the exporting mechanism. - The format of names encapsulated via this representation shall be - defined within individual mechanism drafts. Name objects of this - type will be identified with the following Object Identifier: - - {1(iso), 3(org), 6(dod), 1(internet), 5(security), 6(nametypes), - 4(gss-api-exported-name)} - - No name type OID is included in this mechanism-independent level of - format definition, since (depending on individual mechanism - specifications) the enclosed name may be implicitly typed or may be - explicitly typed using a means other than OID encoding. - - Length Name Description - - 2 TOK_ID Token Identifier - For exported name objects, this - must be hex 04 01. - 2 MECH_OID_LEN Length of the Mechanism OID - MECH_OID_LEN MECH_OID Mechanism OID, in DER - 4 NAME_LEN Length of name - NAME_LEN NAME Exported name; format defined in - applicable mechanism draft. - -4: Name Type Definitions - - This section includes definitions for name types and associated - syntaxes which are defined in a mechanism-independent fashion at the - GSS-API level rather than being defined in individual mechanism - specifications. - -4.1: Host-Based Service Name Form - - The following Object Identifier value is provided as a means to - identify this name form: - - {1(iso), 3(org), 6(dod), 1(internet), 5(security), 6(nametypes), - 2(gss-host-based-services)} - - The recommended symbolic name for this type is - "GSS_C_NT_HOSTBASED_SERVICE". - - - - - - -Linn Standards Track [Page 77] - -RFC 2078 GSS-API January 1997 - - - This name type is used to represent services associated with host - computers. This name form is constructed using two elements, - "service" and "hostname", as follows: - - service@hostname - - When a reference to a name of this type is resolved, the "hostname" - is canonicalized by attempting a DNS lookup and using the fully- - qualified domain name which is returned, or by using the "hostname" - as provided if the DNS lookup fails. The canonicalization operation - also maps the host's name into lower-case characters. - - The "hostname" element may be omitted. If no "@" separator is - included, the entire name is interpreted as the service specifier, - with the "hostname" defaulted to the canonicalized name of the local - host. - - Values for the "service" element are registered with the IANA. - -4.2: User Name Form - - This name form shall be represented by the Object Identifier {iso(1) - member-body(2) United States(840) mit(113554) infosys(1) gssapi(2) - generic(1) user_name(1)}. The recommended mechanism-independent - symbolic name for this type is "GSS_C_NT_USER_NAME". (Note: the same - name form and OID is defined within the Kerberos V5 GSS-API - mechanism, but the symbolic name recommended there begins with a - "GSS_KRB5_NT_" prefix.) - - This name type is used to indicate a named user on a local system. - Its interpretation is OS-specific. This name form is constructed as: - - username - -4.3: Machine UID Form - - This name form shall be represented by the Object Identifier {iso(1) - member-body(2) United States(840) mit(113554) infosys(1) gssapi(2) - generic(1) machine_uid_name(2)}. The recommended mechanism- - independent symbolic name for this type is - "GSS_C_NT_MACHINE_UID_NAME". (Note: the same name form and OID is - defined within the Kerberos V5 GSS-API mechanism, but the symbolic - name recommended there begins with a "GSS_KRB5_NT_" prefix.) - - This name type is used to indicate a numeric user identifier - corresponding to a user on a local system. Its interpretation is - OS-specific. The gss_buffer_desc representing a name of this type - should contain a locally-significant uid_t, represented in host byte - - - -Linn Standards Track [Page 78] - -RFC 2078 GSS-API January 1997 - - - order. The GSS_Import_name() operation resolves this uid into a - username, which is then treated as the User Name Form. - -4.4: String UID Form - - This name form shall be represented by the Object Identifier {iso(1) - member-body(2) United States(840) mit(113554) infosys(1) gssapi(2) - generic(1) string_uid_name(3)}. The recommended symbolic name for - this type is "GSS_C_NT_STRING_UID_NAME". (Note: the same name form - and OID is defined within the Kerberos V5 GSS-API mechanism, but the - symbolic name recommended there begins with a "GSS_KRB5_NT_" prefix.) - - This name type is used to indicate a string of digits representing - the numeric user identifier of a user on a local system. Its - interpretation is OS-specific. This name type is similar to the - Machine UID Form, except that the buffer contains a string - representing the uid_t. - -5: Mechanism-Specific Example Scenarios - - This section provides illustrative overviews of the use of various - candidate mechanism types to support the GSS-API. These discussions - are intended primarily for readers familiar with specific security - technologies, demonstrating how GSS-API functions can be used and - implemented by candidate underlying mechanisms. They should not be - regarded as constrictive to implementations or as defining the only - means through which GSS-API functions can be realized with a - particular underlying technology, and do not demonstrate all GSS-API - features with each technology. - -5.1: Kerberos V5, single-TGT - - OS-specific login functions yield a TGT to the local realm Kerberos - server; TGT is placed in a credentials structure for the client. - Client calls GSS_Acquire_cred() to acquire a cred_handle in order to - reference the credentials for use in establishing security contexts. - - Client calls GSS_Init_sec_context(). If the requested service is - located in a different realm, GSS_Init_sec_context() gets the - necessary TGT/key pairs needed to traverse the path from local to - target realm; these data are placed in the owner's TGT cache. After - any needed remote realm resolution, GSS_Init_sec_context() yields a - service ticket to the requested service with a corresponding session - key; these data are stored in conjunction with the context. GSS-API - code sends KRB_TGS_REQ request(s) and receives KRB_TGS_REP - response(s) (in the successful case) or KRB_ERROR. - - - - - -Linn Standards Track [Page 79] - -RFC 2078 GSS-API January 1997 - - - Assuming success, GSS_Init_sec_context() builds a Kerberos-formatted - KRB_AP_REQ message, and returns it in output_token. The client sends - the output_token to the service. - - The service passes the received token as the input_token argument to - GSS_Accept_sec_context(), which verifies the authenticator, provides - the service with the client's authenticated name, and returns an - output_context_handle. - - Both parties now hold the session key associated with the service - ticket, and can use this key in subsequent GSS_GetMIC(), - GSS_VerifyMIC(), GSS_Wrap(), and GSS_Unwrap() operations. - -5.2: Kerberos V5, double-TGT - - TGT acquisition as above. - - Note: To avoid unnecessary frequent invocations of error paths when - implementing the GSS-API atop Kerberos V5, it seems appropriate to - represent "single-TGT K-V5" and "double-TGT K-V5" with separate - mech_types, and this discussion makes that assumption. - - Based on the (specified or defaulted) mech_type, - GSS_Init_sec_context() determines that the double-TGT protocol - should be employed for the specified target. GSS_Init_sec_context() - returns GSS_S_CONTINUE_NEEDED major_status, and its returned - output_token contains a request to the service for the service's TGT. - (If a service TGT with suitably long remaining lifetime already - exists in a cache, it may be usable, obviating the need for this - step.) The client passes the output_token to the service. Note: this - scenario illustrates a different use for the GSS_S_CONTINUE_NEEDED - status return facility than for support of mutual authentication; - note that both uses can coexist as successive operations within a - single context establishment operation. - - The service passes the received token as the input_token argument to - GSS_Accept_sec_context(), which recognizes it as a request for TGT. - (Note that current Kerberos V5 defines no intra-protocol mechanism to - represent such a request.) GSS_Accept_sec_context() returns - GSS_S_CONTINUE_NEEDED major_status and provides the service's TGT in - its output_token. The service sends the output_token to the client. - - The client passes the received token as the input_token argument to a - continuation of GSS_Init_sec_context(). GSS_Init_sec_context() caches - the received service TGT and uses it as part of a service ticket - request to the Kerberos authentication server, storing the returned - service ticket and session key in conjunction with the context. - GSS_Init_sec_context() builds a Kerberos-formatted authenticator, - - - -Linn Standards Track [Page 80] - -RFC 2078 GSS-API January 1997 - - - and returns it in output_token along with GSS_S_COMPLETE return - major_status. The client sends the output_token to the service. - - Service passes the received token as the input_token argument to a - continuation call to GSS_Accept_sec_context(). - GSS_Accept_sec_context() verifies the authenticator, provides the - service with the client's authenticated name, and returns - major_status GSS_S_COMPLETE. - - GSS_GetMIC(), GSS_VerifyMIC(), GSS_Wrap(), and GSS_Unwrap() as - above. - -5.3: X.509 Authentication Framework - - This example illustrates use of the GSS-API in conjunction with - public-key mechanisms, consistent with the X.509 Directory - Authentication Framework. - - The GSS_Acquire_cred() call establishes a credentials structure, - making the client's private key accessible for use on behalf of the - client. - - The client calls GSS_Init_sec_context(), which interrogates the - Directory to acquire (and validate) a chain of public-key - certificates, thereby collecting the public key of the service. The - certificate validation operation determines that suitable integrity - checks were applied by trusted authorities and that those - certificates have not expired. GSS_Init_sec_context() generates a - secret key for use in per-message protection operations on the - context, and enciphers that secret key under the service's public - key. - - The enciphered secret key, along with an authenticator quantity - signed with the client's private key, is included in the output_token - from GSS_Init_sec_context(). The output_token also carries a - certification path, consisting of a certificate chain leading from - the service to the client; a variant approach would defer this path - resolution to be performed by the service instead of being asserted - by the client. The client application sends the output_token to the - service. - - The service passes the received token as the input_token argument to - GSS_Accept_sec_context(). GSS_Accept_sec_context() validates the - certification path, and as a result determines a certified binding - between the client's distinguished name and the client's public key. - Given that public key, GSS_Accept_sec_context() can process the - input_token's authenticator quantity and verify that the client's - private key was used to sign the input_token. At this point, the - - - -Linn Standards Track [Page 81] - -RFC 2078 GSS-API January 1997 - - - client is authenticated to the service. The service uses its private - key to decipher the enciphered secret key provided to it for per- - message protection operations on the context. - - The client calls GSS_GetMIC() or GSS_Wrap() on a data message, which - causes per-message authentication, integrity, and (optional) - confidentiality facilities to be applied to that message. The service - uses the context's shared secret key to perform corresponding - GSS_VerifyMIC() and GSS_Unwrap() calls. - -6: Security Considerations - - Security issues are discussed throughout this memo. - -7: Related Activities - - In order to implement the GSS-API atop existing, emerging, and future - security mechanisms: - - object identifiers must be assigned to candidate GSS-API - mechanisms and the name types which they support - - concrete data element formats and processing procedures must be - defined for candidate mechanisms - - Calling applications must implement formatting conventions which will - enable them to distinguish GSS-API tokens from other data carried in - their application protocols. - - Concrete language bindings are required for the programming - environments in which the GSS-API is to be employed, as RFC-1509 - defines for the C programming language and GSS-V1. - - - - - - - - - - - - - - - - - - - -Linn Standards Track [Page 82] - -RFC 2078 GSS-API January 1997 - - -APPENDIX A - -MECHANISM DESIGN CONSTRAINTS - - The following constraints on GSS-API mechanism designs are adopted in - response to observed caller protocol requirements, and adherence - thereto is anticipated in subsequent descriptions of GSS-API - mechanisms to be documented in standards-track Internet - specifications. - - It is strongly recommended that mechanisms offering per-message - protection services also offer at least one of the replay detection - and sequencing services, as mechanisms offering neither of the latter - will fail to satisfy recognized requirements of certain candidate - caller protocols. - -APPENDIX B - - COMPATIBILITY WITH GSS-V1 - - It is the intent of this document to define an interface and - procedures which preserve compatibility between GSS-V1 (RFC-1508) - callers and GSS- V2 providers. All calls defined in GSS-V1 are - preserved, and it has been a goal that GSS-V1 callers should be able - to operate atop GSS-V2 provider implementations. Certain detailed - changes, summarized in this section, have been made in order to - resolve omissions identified in GSS-V1. - - The following GSS-V1 constructs, while supported within GSS-V2, are - deprecated: - - Names for per-message processing routines: GSS_Seal() deprecated - in favor of GSS_Wrap(); GSS_Sign() deprecated in favor of - GSS_GetMIC(); GSS_Unseal() deprecated in favor of GSS_Unwrap(); - GSS_Verify() deprecated in favor of GSS_VerifyMIC(). - - GSS_Delete_sec_context() facility for context_token usage, - allowing mechanisms to signal context deletion, is retained for - compatibility with GSS-V1. For current usage, it is recommended - that both peers to a context invoke GSS_Delete_sec_context() - independently, passing a null output_context_token buffer to - indicate that no context_token is required. Implementations of - GSS_Delete_sec_context() should delete relevant locally-stored - context information. - - - - - - - -Linn Standards Track [Page 83] - -RFC 2078 GSS-API January 1997 - - - This GSS-V2 specification adds the following calls which are not - present in GSS-V1: - - Credential management calls: GSS_Add_cred(), - GSS_Inquire_cred_by_mech(). - - Context-level calls: GSS_Inquire_context(), GSS_Wrap_size_limit(), - GSS_Export_sec_context(), GSS_Import_sec_context(). - - Per-message calls: No new calls. Existing calls have been renamed. - - Support calls: GSS_Create_empty_OID_set(), - GSS_Add_OID_set_member(), GSS_Test_OID_set_member(), - GSS_Release_OID(), GSS_OID_to_str(), GSS_Str_to_OID(), - GSS_Inquire_names_for_mech(), GSS_Inquire_mechs_for_name(), - GSS_Canonicalize_name(), GSS_Export_name(), GSS_Duplicate_name(). - - This GSS-V2 specification introduces three new facilities applicable - to security contexts, indicated using the following context state - values which are not present in GSS-V1: - - anon_state, set TRUE to indicate that a context's initiator is - anonymous from the viewpoint of the target; Section 1.2.5 of this - specification provides a summary description of the GSS-V2 - anonymity support facility, support and use of which is optional. - - prot_ready_state, set TRUE to indicate that a context may be used - for per-message protection before final completion of context - establishment; Section 1.2.7 of this specification provides a - summary description of the GSS-V2 facility enabling mechanisms to - selectively permit per-message protection during context - establishment, support and use of which is optional. - - trans_state, set TRUE to indicate that a context is transferable to - another process using the GSS-V2 GSS_Export_sec_context() facility. - - These state values are represented (at the C bindings level) in - positions within a bit vector which are unused in GSS-V1, and may be - safely ignored by GSS-V1 callers. - - Relative to GSS-V1, GSS-V2 provides additional guidance to GSS-API - implementors in the following areas: implementation robustness, - credential management, behavior in multi-mechanism configurations, - naming support, and inclusion of optional sequencing services. The - token tagging facility as defined in GSS-V2, Section 3.1, is now - described directly in terms of octets to facilitate interoperable - implementation without general ASN.1 processing code; the - corresponding ASN.1 syntax, included for descriptive purposes, is - - - -Linn Standards Track [Page 84] - -RFC 2078 GSS-API January 1997 - - - unchanged from that in GSS-V1. For use in conjunction with added - naming support facilities, a new Exported Name Object construct is - added. Additional name types are introduced in Section 4. - - This GSS-V2 specification adds the following major_status values - which are not defined in GSS-V1: - - GSS_S_BAD_QOP unsupported QOP value - GSS_S_UNAUTHORIZED operation unauthorized - GSS_S_UNAVAILABLE operation unavailable - GSS_S_DUPLICATE_ELEMENT duplicate credential element requested - GSS_S_NAME_NOT_MN name contains multi-mechanism elements - GSS_S_GAP_TOKEN skipped predecessor token(s) - detected - - Of these added status codes, only two values are defined to be - returnable by calls existing in GSS-V1: GSS_S_BAD_QOP (returnable by - GSS_GetMIC() and GSS_Wrap()), and GSS_S_GAP_TOKEN (returnable by - GSS_VerifyMIC() and GSS_Unwrap()). - - Additionally, GSS-V2 descriptions of certain calls present in GSS-V1 - have been updated to allow return of additional major_status values - from the set as defined in GSS-V1: GSS_Inquire_cred() has - GSS_S_DEFECTIVE_CREDENTIAL and GSS_S_CREDENTIALS_EXPIRED defined as - returnable, GSS_Init_sec_context() has GSS_S_OLD_TOKEN, - GSS_S_DUPLICATE_TOKEN, and GSS_S_BAD_MECH defined as returnable, and - GSS_Accept_sec_context() has GSS_S_BAD_MECH defined as returnable. - -Author's Address - - John Linn - OpenVision Technologies - One Main St. - Cambridge, MA 02142 USA - - Phone: +1 617.374.2245 - EMail: John.Linn@ov.com - - - - - - - - - - - - - - -Linn Standards Track [Page 85] - diff --git a/doc/rfc2203.txt b/doc/rfc2203.txt deleted file mode 100644 index 2f6a8a0d0..000000000 --- a/doc/rfc2203.txt +++ /dev/null @@ -1,1291 +0,0 @@ - - - - - - -Network Working Group M. Eisler -Request for Comments: 2203 A. Chiu -Category: Standards Track L. Ling - September 1997 - - - RPCSEC_GSS Protocol Specification - -Status of this Memo - - This document specifies an Internet standards track protocol for the - Internet community, and requests discussion and suggestions for - improvements. Please refer to the current edition of the "Internet - Official Protocol Standards" (STD 1) for the standardization state - and status of this protocol. Distribution of this memo is unlimited. - -Abstract - - This memo describes an ONC/RPC security flavor that allows RPC - protocols to access the Generic Security Services Application - Programming Interface (referred to henceforth as GSS-API). - -Table of Contents - - 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 2 - 2. The ONC RPC Message Protocol . . . . . . . . . . . . . . . . . 2 - 3. Flavor Number Assignment . . . . . . . . . . . . . . . . . . . 3 - 4. New auth_stat Values . . . . . . . . . . . . . . . . . . . . . 3 - 5. Elements of the RPCSEC_GSS Security Protocol . . . . . . . . . 3 - 5.1. Version Selection . . . . . . . . . . . . . . . . . . . . . 5 - 5.2. Context Creation . . . . . . . . . . . . . . . . . . . . . . 5 - 5.2.1. Mechanism and QOP Selection . . . . . . . . . . . . . . . 5 - 5.2.2. Context Creation Requests . . . . . . . . . . . . . . . . 6 - 5.2.3. Context Creation Responses . . . . . . . . . . . . . . . . 8 - 5.2.3.1. Context Creation Response - Successful Acceptance . . . 8 - 5.2.3.1.1. Client Processing of Successful Context Creation - Responses . . . . . . . . . . . . . . . . . . . . . . 9 - 5.2.3.2. Context Creation Response - Unsuccessful Cases . . . . . 9 - 5.3. RPC Data Exchange . . . . . . . . . . . . . . . . . . . . 10 - 5.3.1. RPC Request Header . . . . . . . . . . . . . . . . . . . 10 - 5.3.2. RPC Request Data . . . . . . . . . . . . . . . . . . . . 11 - 5.3.2.1. RPC Request Data - No Data Integrity . . . . . . . . . 11 - 5.3.2.2. RPC Request Data - With Data Integrity . . . . . . . . 11 - 5.3.2.3. RPC Request Data - With Data Privacy . . . . . . . . . 12 - 5.3.3. Server Processing of RPC Data Requests . . . . . . . . . 12 - 5.3.3.1. Context Management . . . . . . . . . . . . . . . . . . 12 - 5.3.3.2. Server Reply - Request Accepted . . . . . . . . . . . 14 - 5.3.3.3. Server Reply - Request Denied . . . . . . . . . . . . 15 - - - -Eisler, et. al. Standards Track [Page 1] - -RFC 2203 RPCSEC_GSS Protocol Specification September 1997 - - - 5.3.3.4. Mapping of GSS-API Errors to Server Responses . . . . 16 - 5.3.3.4.1. GSS_GetMIC() Failure . . . . . . . . . . . . . . . . 16 - 5.3.3.4.2. GSS_VerifyMIC() Failure . . . . . . . . . . . . . . 16 - 5.3.3.4.3. GSS_Unwrap() Failure . . . . . . . . . . . . . . . . 16 - 5.3.3.4.4. GSS_Wrap() Failure . . . . . . . . . . . . . . . . . 16 - 5.4. Context Destruction . . . . . . . . . . . . . . . . . . . 17 - 6. Set of GSS-API Mechanisms . . . . . . . . . . . . . . . . . 17 - 7. Security Considerations . . . . . . . . . . . . . . . . . . 18 - 7.1. Privacy of Call Header . . . . . . . . . . . . . . . . . . 18 - 7.2. Sequence Number Attacks . . . . . . . . . . . . . . . . . 18 - 7.2.1. Sequence Numbers Above the Window . . . . . . . . . . . 18 - 7.2.2. Sequence Numbers Within or Below the Window . . . . . . 18 - 7.3. Message Stealing Attacks . . . . . . . . . . . . . . . . . 19 - Appendix A. GSS-API Major Status Codes . . . . . . . . . . . . . 20 - Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 22 - Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 23 - -1. Introduction - - This document describes the protocol used by the RPCSEC_GSS security - flavor. Security flavors have been called authentication flavors for - historical reasons. This memo recognizes that there are two other - security services besides authentication, integrity, and privacy, and - so defines a new RPCSEC_GSS security flavor. - - The protocol is described using the XDR language [Srinivasan-xdr]. - The reader is assumed to be familiar with ONC RPC and the security - flavor mechanism [Srinivasan-rpc]. The reader is also assumed to be - familiar with the GSS-API framework [Linn]. The RPCSEC_GSS security - flavor uses GSS-API interfaces to provide security services that are - independent of the underlying security mechanism. - -2. The ONC RPC Message Protocol - - This memo refers to the following XDR types of the ONC RPC protocol, - which are described in the document entitled Remote Procedure Call - Protocol Specification Version 2 [Srinivasan-rpc]: - - msg_type - reply_stat - auth_flavor - accept_stat - reject_stat - auth_stat - opaque_auth - rpc_msg - call_body - reply_body - - - -Eisler, et. al. Standards Track [Page 2] - -RFC 2203 RPCSEC_GSS Protocol Specification September 1997 - - - accepted_reply - rejected_reply - -3. Flavor Number Assignment - - The RPCSEC_GSS security flavor has been assigned the value of 6: - - enum auth_flavor { - ... - RPCSEC_GSS = 6 /* RPCSEC_GSS security flavor */ - }; - -4. New auth_stat Values - - RPCSEC_GSS requires the addition of two new values to the auth_stat - enumerated type definition: - - enum auth_stat { - ... - /* - * RPCSEC_GSS errors - */ - RPCSEC_GSS_CREDPROBLEM = 13, - RPCSEC_GSS_CTXPROBLEM = 14 - }; - - The descriptions of these two new values are defined later in this - memo. - -5. Elements of the RPCSEC_GSS Security Protocol - - An RPC session based on the RPCSEC_GSS security flavor consists of - three phases: context creation, RPC data exchange, and context - destruction. In the following discussion, protocol elements for - these three phases are described. - - The following description of the RPCSEC_GSS protocol uses some of the - definitions within XDR language description of the RPC protocol. - - Context creation and destruction use control messages that are not - dispatched to service procedures registered by an RPC server. The - program and version numbers used in these control messages are the - same as the RPC service's program and version numbers. The procedure - number used is NULLPROC (zero). A field in the credential - information (the gss_proc field which is defined in the - rpc_gss_cred_t structure below) specifies whether a message is to be - interpreted as a control message or a regular RPC message. If this - field is set to RPCSEC_GSS_DATA, no control action is implied; in - - - -Eisler, et. al. Standards Track [Page 3] - -RFC 2203 RPCSEC_GSS Protocol Specification September 1997 - - - this case, it is a regular data message. If this field is set to any - other value, a control action is implied. This is described in the - following sections. - - Just as with normal RPC data exchange messages, the transaction - identifier (the xid field in struct rpc_msg), should be set to unique - values on each call for context creation and context destruction. - - The following definitions are used for describing the protocol. - - /* RPCSEC_GSS control procedures */ - - - enum rpc_gss_proc_t { - RPCSEC_GSS_DATA = 0, - RPCSEC_GSS_INIT = 1, - RPCSEC_GSS_CONTINUE_INIT = 2, - RPCSEC_GSS_DESTROY = 3 - }; - - /* RPCSEC_GSS services */ - - enum rpc_gss_service_t { - /* Note: the enumerated value for 0 is reserved. */ - rpc_gss_svc_none = 1, - rpc_gss_svc_integrity = 2, - rpc_gss_svc_privacy = 3 - }; - - /* Credential */ - - /* - * Note: version 0 is reserved for possible future - * definition of a version negotiation protocol - * - */ - #define RPCSEC_GSS_VERS_1 1 - - struct rpc_gss_cred_t { - union switch (unsigned int version) { /* version of - RPCSEC_GSS */ - case RPCSEC_GSS_VERS_1: - struct { - rpc_gss_proc_t gss_proc; /* control procedure */ - unsigned int seq_num; /* sequence number */ - rpc_gss_service_t service; /* service used */ - opaque handle<>; /* context handle */ - } rpc_gss_cred_vers_1_t; - - - -Eisler, et. al. Standards Track [Page 4] - -RFC 2203 RPCSEC_GSS Protocol Specification September 1997 - - - } - }; - - /* Maximum sequence number value */ - - #define MAXSEQ 0x80000000 - -5.1. Version Selection - - This document defines just one protocol version (RPCSEC_GSS_VERS_1). - The client should assume that the server supports RPCSEC_GSS_VERS_1 - and issue a Context Creation message (as described in the section - RPCSEC_GSS_VERS_1, the RPC response will have a reply_stat of - MSG_DENIED, a rejection status of AUTH_ERROR, and an auth_stat of - AUTH_REJECTED_CRED. - -5.2. Context Creation - - Before RPC data is exchanged on a session using the RPCSEC_GSS - flavor, a context must be set up between the client and the server. - Context creation may involve zero or more RPC exchanges. The number - of exchanges depends on the security mechanism. - -5.2.1. Mechanism and QOP Selection - - There is no facility in the RPCSEC_GSS protocol to negotiate GSS-API - mechanism identifiers or QOP values. At minimum, it is expected that - implementations of the RPCSEC_GSS protocol provide a means to: - - * specify mechanism identifiers, QOP values, and RPCSEC_GSS - service values on the client side, and to - - * enforce mechanism identifiers, QOP values, and RPCSEC_GSS - service values on a per-request basis on the server side. - - It is necessary that above capabilities exist so that applications - have the means to conform the required set of required set of - tuples (See the section entitled Set of - GSS-API Mechanisms). An application may negotiate selection within its protocol or via an out of band - protocol. Hence it may be necessary for RPCSEC_GSS implementations to - provide programming interfaces for the specification and enforcement - of . - - Additionally, implementations may depend on negotiation schemes - constructed as pseudo-mechanisms under the GSS-API. Because such - schemes are below the GSS-API layer, the RPCSEC_GSS protocol, as - specified in this document, can make use of them. - - - -Eisler, et. al. Standards Track [Page 5] - -RFC 2203 RPCSEC_GSS Protocol Specification September 1997 - - -5.2.2. Context Creation Requests - - The first RPC request from the client to the server initiates context - creation. Within the RPC message protocol's call_body structure, - rpcvers is set to 2. prog and vers are always those for the service - being accessed. The proc is always set to NULLPROC (zero). - - Within the RPC message protocol's cred structure, flavor is set to - RPCSEC_GSS (6). The opaque data of the cred structure (the body - field) constituting the credential encodes the rpc_gss_cred_t - structure defined previously. - - The values of the fields contained in the rpc_gss_cred_t structure - are set as follows. The version field is set to the version of the - RPCSEC_GSS protocol the client wants to use. The remainder of this - memo documents version RPCSEC_GSS_VERS_1 of RPCSEC_GSS, and so the - version field would be set to RPCSEC_GSS_VERS_1. The gss_proc field - must be set to RPCSEC_GSS_INIT for the first creation request. In - subsequent creation requests, the gss_proc field must be set to - RPCSEC_GSS_CONTINUE_INIT. In a creation request, the seq_num and - service fields are undefined and both must be ignored by the server. - In the first creation request, the handle field is NULL (opaque data - of zero length). In subsequent creation requests, handle must be - equal to the value returned by the server. The handle field serves - as the identifier for the context, and will not change for the - duration of the context, including responses to - RPCSEC_GSS_CONTINUE_INIT. - - The verifier field in the RPC message header is also described by the - opaque_auth structure. All creation requests have the NULL verifier - (AUTH_NONE flavor with zero length opaque data). - - Following the verifier are the call data (procedure specific - parameters). Note that the proc field of the call_body structure is - set to NULLPROC, and thus normally there would be zero octets - following the verifier. However, since there is no RPC data exchange - during a context creation, it is safe to transfer information - following the verifier. It is necessary to "overload" the call data - in this way, rather than pack the GSS-API token into the RPC header, - because RPC Version 2 restricts the amount of data that can be sent - in the header. The opaque body of the credential and verifier fields - can be each at most 400 octets long, and GSS tokens can be longer - than 800 octets. - - - - - - - - -Eisler, et. al. Standards Track [Page 6] - -RFC 2203 RPCSEC_GSS Protocol Specification September 1997 - - - The call data for a context creation request is described by the - following structure for all creation requests: - - struct rpc_gss_init_arg { - opaque gss_token<>; - }; - - Here, gss_token is the token returned by the call to GSS-API's - GSS_Init_sec_context() routine, opaquely encoded. The value of this - field will likely be different in each creation request, if there is - more than one creation request. If no token is returned by the call - to GSS_Init_sec_context(), the context must have been created - (assuming no errors), and there will not be any more creation - requests. - - When GSS_Init_sec_context() is called, the parameters - replay_det_req_flag and sequence_req_flag must be turned off. The - reasons for this are: - - * ONC RPC can be used over unreliable transports and provides no - layer to reliably re-assemble messages. Thus it is possible for - gaps in message sequencing to occur, as well as out of order - messages. - - * RPC servers can be multi-threaded, and thus the order in which - GSS-API messages are signed or wrapped can be different from the - order in which the messages are verified or unwrapped, even if - the requests are sent on reliable transports. - - * To maximize convenience of implementation, the order in which an - ONC RPC entity will verify the header and verify/unwrap the body - of an RPC call or reply is left unspecified. - - The RPCSEC_GSS protocol provides for protection from replay attack, - yet tolerates out-of-order delivery or processing of messages and - tolerates dropped requests. - - - - - - - - - - - - - - - -Eisler, et. al. Standards Track [Page 7] - -RFC 2203 RPCSEC_GSS Protocol Specification September 1997 - - -5.2.3. Context Creation Responses - -5.2.3.1. Context Creation Response - Successful Acceptance - - The response to a successful creation request has an MSG_ACCEPTED - response with a status of SUCCESS. The results field encodes a - response with the following structure: - - struct rpc_gss_init_res { - opaque handle<>; - unsigned int gss_major; - unsigned int gss_minor; - unsigned int seq_window; - opaque gss_token<>; - }; - - Here, handle is non-NULL opaque data that serves as the context - identifier. The client must use this value in all subsequent requests - whether control messages or otherwise). The gss_major and gss_minor - fields contain the results of the call to GSS_Accept_sec_context() - executed by the server. The values for the gss_major field are - defined in Appendix A of this document. The values for the gss_minor - field are GSS-API mechanism specific and are defined in the - mechanism's specification. If gss_major is not one of GSS_S_COMPLETE - or GSS_S_CONTINUE_NEEDED, the context setup has failed; in this case - handle and gss_token must be set to NULL by the server. The value of - gss_minor is dependent on the value of gss_major and the security - mechanism used. The gss_token field contains any token returned by - the GSS_Accept_sec_context() call executed by the server. A token - may be returned for both successful values of gss_major. If the - value is GSS_S_COMPLETE, it indicates that the server is not - expecting any more tokens, and the RPC Data Exchange phase must begin - on the subsequent request from the client. If the value is - GSS_S_CONTINUE_NEEDED, the server is expecting another token. Hence - the client must send at least one more creation request (with - gss_proc set to RPCSEC_GSS_CONTINUE_INIT in the request's credential) - carrying the required token. - - In a successful response, the seq_window field is set to the sequence - window length supported by the server for this context. This window - specifies the maximum number of client requests that may be - outstanding for this context. The server will accept "seq_window" - requests at a time, and these may be out of order. The client may - use this number to determine the number of threads that can - simultaneously send requests on this context. - - - - - - -Eisler, et. al. Standards Track [Page 8] - -RFC 2203 RPCSEC_GSS Protocol Specification September 1997 - - - If gss_major is GSS_S_COMPLETE, the verifier's (the verf element in - the response) flavor field is set to RPCSEC_GSS, and the body field - set to the checksum of the seq_window (in network order). The QOP - used for this checksum is 0 (zero), which is the default QOP. For - all other values of gss_major, a NULL verifier (AUTH_NONE flavor with - zero-length opaque data) is used. - -5.2.3.1.1. Client Processing of Successful Context Creation Responses - - If the value of gss_major in the response is GSS_S_CONTINUE_NEEDED, - then the client, per the GSS-API specification, must invoke - GSS_Init_sec_context() using the token returned in gss_token in the - context creation response. The client must then generate a context - creation request, with gss_proc set to RPCSEC_GSS_CONTINUE_INIT. - - If the value of gss_major in the response is GSS_S_COMPLETE, and if - the client's previous invocation of GSS_Init_sec_context() returned a - gss_major value of GSS_S_CONTINUE_NEEDED, then the client, per the - GSS-API specification, must invoke GSS_Init_sec_context() using the - token returned in gss_token in the context creation response. If - GSS_Init_sec_context() returns GSS_S_COMPLETE, the context is - successfully set up, and the RPC data exchange phase must begin on - the subsequent request from the client. - -5.2.3.2. Context Creation Response - Unsuccessful Cases - - An MSG_ACCEPTED reply (to a creation request) with an acceptance - status of other than SUCCESS has a NULL verifier (flavor set to - AUTH_NONE, and zero length opaque data in the body field), and is - formulated as usual for different status values. - - An MSG_DENIED reply (to a creation request) is also formulated as - usual. Note that MSG_DENIED could be returned because the server's - RPC implementation does not recognize the RPCSEC_GSS security flavor. - RFC 1831 does not specify the appropriate reply status in this - instance, but common implementation practice appears to be to return - a rejection status of AUTH_ERROR with an auth_stat of - AUTH_REJECTEDCRED. Even though two new values (RPCSEC_GSS_CREDPROBLEM - and RPCSEC_GSS_CTXPROBLEM) have been defined for the auth_stat type, - neither of these two can be returned in responses to context creation - requests. The auth_stat new values can be used for responses to - normal (data) requests. This is described later. - - MSG_DENIED might also be returned if the RPCSEC_GSS version number in - the credential is not supported on the server. In that case, the - server returns a rejection status of AUTH_ERROR, with an auth_stat of - - AUTH_REJECTED_CRED. - - - -Eisler, et. al. Standards Track [Page 9] - -RFC 2203 RPCSEC_GSS Protocol Specification September 1997 - - -5.3. RPC Data Exchange - - The data exchange phase is entered after a context has been - successfully set up. The format of the data exchanged depends on the - security service used for the request. Although clients can change - the security service and QOP used on a per-request basis, this may - not be acceptable to all RPC services; some RPC services may "lock" - the data exchange phase into using the QOP and service used on the - first data exchange message. For all three modes of service (no data - integrity, data integrity, data privacy), the RPC request header has - the same format. - -5.3.1. RPC Request Header - - The credential has the opaque_auth structure described earlier. The - flavor field is set to RPCSEC_GSS. The credential body is created by - XDR encoding the rpc_gss_cred_t structure listed earlier into an - octet stream, and then opaquely encoding this octet stream as the - body field. - - Values of the fields contained in the rpc_gss_cred_t structure are - set as follows. The version field is set to same version value that - was used to create the context, which within the scope of this memo - will always be RPCSEC_GSS_VERS_1. The gss_proc field is set to - RPCSEC_GSS_DATA. The service field is set to indicate the desired - service (one of rpc_gss_svc_none, rpc_gss_svc_integrity, or - rpc_gss_svc_privacy). The handle field is set to the context handle - value received from the RPC server during context creation. The - seq_num field can start at any value below MAXSEQ, and must be - incremented (by one or more) for successive requests. Use of - sequence numbers is described in detail when server processing of the - request is discussed. - - The verifier has the opaque_auth structure described earlier. The - flavor field is set to RPCSEC_GSS. The body field is set as follows. - The checksum of the RPC header (up to and including the credential) - is computed using the GSS_GetMIC() call with the desired QOP. This - returns the checksum as an opaque octet stream and its length. This - is encoded into the body field. Note that the QOP is not explicitly - specified anywhere in the request. It is implicit in the checksum or - encrypted data. The same QOP value as is used for the header - checksum must also be used for the data (for checksumming or - encrypting), unless the service used for the request is - rpc_gss_svc_none. - - - - - - - -Eisler, et. al. Standards Track [Page 10] - -RFC 2203 RPCSEC_GSS Protocol Specification September 1997 - - -5.3.2. RPC Request Data - -5.3.2.1. RPC Request Data - No Data Integrity - - If the service specified is rpc_gss_svc_none, the data (procedure - arguments) are not integrity or privacy protected. They are sent in - exactly the same way as they would be if the AUTH_NONE flavor were - used (following the verifier). Note, however, that since the RPC - header is integrity protected, the sender will still be authenticated - in this case. - -5.3.2.2. RPC Request Data - With Data Integrity - - When data integrity is used, the request data is represented as - follows: - - struct rpc_gss_integ_data { - opaque databody_integ<>; - opaque checksum<>; - }; - - The databody_integ field is created as follows. A structure - consisting of a sequence number followed by the procedure arguments - is constructed. This is shown below as the type rpc_gss_data_t: - - struct rpc_gss_data_t { - unsigned int seq_num; - proc_req_arg_t arg; - }; - - Here, seq_num must have the same value as in the credential. The - type proc_req_arg_t is the procedure specific XDR type describing the - procedure arguments (and so is not specified here). The octet stream - corresponding to the XDR encoded rpc_gss_data_t structure and its - length are placed in the databody_integ field. Note that because the - XDR type of databody_integ is opaque, the XDR encoding of - databody_integ will include an initial four octet length field, - followed by the XDR encoded octet stream of rpc_gss_data_t. - - The checksum field represents the checksum of the XDR encoded octet - stream corresponding to the XDR encoded rpc_gss_data_t structure - (note, this is not the checksum of the databody_integ field). This - is obtained using the GSS_GetMIC() call, with the same QOP as was - used to compute the header checksum (in the verifier). The - - - - - - - -Eisler, et. al. Standards Track [Page 11] - -RFC 2203 RPCSEC_GSS Protocol Specification September 1997 - - - GSS_GetMIC() call returns the checksum as an opaque octet stream and - its length. The checksum field of struct rpc_gss_integ_data has an - XDR type of opaque. Thus the checksum length from GSS_GetMIC() is - encoded as a four octet length field, followed by the checksum, - padded to a multiple of four octets. - -5.3.2.3. RPC Request Data - With Data Privacy - - When data privacy is used, the request data is represented as - follows: - - struct rpc_gss_priv_data { - opaque databody_priv<> - }; - - The databody_priv field is created as follows. The rpc_gss_data_t - structure described earlier is constructed again in the same way as - for the case of data integrity. Next, the GSS_Wrap() call is invoked - to encrypt the octet stream corresponding to the rpc_gss_data_t - structure, using the same value for QOP (argument qop_req to - GSS_Wrap()) as was used for the header checksum (in the verifier) and - conf_req_flag (an argument to GSS_Wrap()) of TRUE. The GSS_Wrap() - call returns an opaque octet stream (representing the encrypted - rpc_gss_data_t structure) and its length, and this is encoded as the - databody_priv field. Since databody_priv has an XDR type of opaque, - the length returned by GSS_Wrap() is encoded as the four octet - length, followed by the encrypted octet stream (padded to a multiple - of four octets). - -5.3.3. Server Processing of RPC Data Requests - -5.3.3.1. Context Management - - When a request is received by the server, the following are verified - to be acceptable: - - * the version number in the credential - - * the service specified in the credential - - * the context handle specified in the credential - - * the header checksum in the verifier (via GSS_VerifyMIC()) - - * the sequence number (seq_num) specified in the credential (more - on this follows) - - - - - -Eisler, et. al. Standards Track [Page 12] - -RFC 2203 RPCSEC_GSS Protocol Specification September 1997 - - - The gss_proc field in the credential must be set to RPCSEC_GSS_DATA - for data requests (otherwise, the message will be interpreted as a - control message). - - The server maintains a window of "seq_window" sequence numbers, - starting with the last sequence number seen and extending backwards. - If a sequence number higher than the last number seen is received - (AND if GSS_VerifyMIC() on the header checksum from the verifier - returns GSS_S_COMPLETE), the window is moved forward to the new - sequence number. If the last sequence number seen is N, the server - is prepared to receive requests with sequence numbers in the range N - through (N - seq_window + 1), both inclusive. If the sequence number - received falls below this range, it is silently discarded. If the - sequence number is within this range, and the server has not seen it, - the request is accepted, and the server turns on a bit to "remember" - that this sequence number has been seen. If the server determines - that it has already seen a sequence number within the window, the - request is silently discarded. The server should select a seq_window - value based on the number requests it expects to process - simultaneously. For example, in a threaded implementation seq_window - might be equal to the number of server threads. There are no known - security issues with selecting a large window. The primary issue is - how much space the server is willing to allocate to keep track of - requests received within the window. - - The reason for discarding requests silently is that the server is - unable to determine if the duplicate or out of range request was due - to a sequencing problem in the client, network, or the operating - system, or due to some quirk in routing, or a replay attack by an - intruder. Discarding the request allows the client to recover after - timing out, if indeed the duplication was unintentional or well - intended. Note that a consequence of the silent discard is that - clients may increment the seq_num by more than one. The effect of - this is that the window will move forward more quickly. It is not - believed that there is any benefit to doing this. - - Note that the sequence number algorithm requires that the client - increment the sequence number even if it is retrying a request with - the same RPC transaction identifier. It is not infrequent for - clients to get into a situation where they send two or more attempts - and a slow server sends the reply for the first attempt. With - RPCSEC_GSS, each request and reply will have a unique sequence - number. If the client wishes to improve turn around time on the RPC - call, it can cache the RPCSEC_GSS sequence number of each request it - sends. Then when it receives a response with a matching RPC - transaction identifier, it can compute the checksum of each sequence - number in the cache to try to match the checksum in the reply's - verifier. - - - -Eisler, et. al. Standards Track [Page 13] - -RFC 2203 RPCSEC_GSS Protocol Specification September 1997 - - - The data is decoded according to the service specified in the - credential. In the case of integrity or privacy, the server ensures - that the QOP value is acceptable, and that it is the same as that - used for the header checksum in the verifier. Also, in the case of - integrity or privacy, the server will reject the message (with a - reply status of MSG_ACCEPTED, and an acceptance status of - GARBAGE_ARGS) if the sequence number embedded in the request body is - different from the sequence number in the credential. - -5.3.3.2. Server Reply - Request Accepted - - An MSG_ACCEPTED reply to a request in the data exchange phase will - have the verifier's (the verf element in the response) flavor field - set to RPCSEC_GSS, and the body field set to the checksum (the output - of GSS_GetMIC()) of the sequence number (in network order) of the - corresponding request. The QOP used is the same as the QOP used for - the corresponding request. - - If the status of the reply is not SUCCESS, the rest of the message is - formatted as usual. - - If the status of the message is SUCCESS, the format of the rest of - the message depends on the service specified in the corresponding - request message. Basically, what follows the verifier in this case - are the procedure results, formatted in different ways depending on - the requested service. - - If no data integrity was requested, the procedure results are - formatted as for the AUTH_NONE security flavor. - - If data integrity was requested, the results are encoded in exactly - the same way as the procedure arguments were in the corresponding - request. See the section 'RPC Request Data - With Data Integrity.' - The only difference is that the structure representing the - procedure's result - proc_res_arg_t - must be substituted in place of - the request argument structure proc_req_arg_t. The QOP used for the - checksum must be the same as that used for constructing the reply - verifier. - - If data privacy was requested, the results are encoded in exactly the - same way as the procedure arguments were in the corresponding - request. See the section 'RPC Request Data - With Data Privacy.' The - QOP used for encryption must be the same as that used for - constructing the reply verifier. - - - - - - - -Eisler, et. al. Standards Track [Page 14] - -RFC 2203 RPCSEC_GSS Protocol Specification September 1997 - - -5.3.3.3. Server Reply - Request Denied - - An MSG_DENIED reply (to a data request) is formulated as usual. Two - new values (RPCSEC_GSS_CREDPROBLEM and RPCSEC_GSS_CTXPROBLEM) have - been defined for the auth_stat type. When the reason for denial of - the request is a reject_stat of AUTH_ERROR, one of the two new - auth_stat values could be returned in addition to the existing - values. These two new values have special significance from the - existing reasons for denial of a request. - - The server maintains a list of contexts for the clients that are - currently in session with it. Normally, a context is destroyed when - the client ends the session corresponding to it. However, due to - resource constraints, the server may destroy a context prematurely - (on an LRU basis, or if the server machine is rebooted, for example). - In this case, when a client request comes in, there may not be a - context corresponding to its handle. The server rejects the request, - with the reason RPCSEC_GSS_CREDPROBLEM in this case. Upon receiving - this error, the client must refresh the context - that is, - reestablish it after destroying the old one - and try the request - again. This error is also returned if the context handle matches - that of a different context that was allocated after the client's - context was destroyed (this will be detected by a failure in - verifying the header checksum). - - If the GSS_VerifyMIC() call on the header checksum (contained in the - verifier) fails to return GSS_S_COMPLETE, the server rejects the - request and returns an auth_stat of RPCSEC_GSS_CREDPROBLEM. - - When the client's sequence number exceeds the maximum the server will - allow, the server will reject the request with the reason - RPCSEC_GSS_CTXPROBLEM. Also, if security credentials become stale - while in use (due to ticket expiry in the case of the Kerberos V5 - mechanism, for example), the failures which result cause the - RPCSEC_GSS_CTXPROBLEM reason to be returned. In these cases also, - the client must refresh the context, and retry the request. - - For other errors, retrying will not rectify the problem and the - client must not refresh the context until the problem causing the - client request to be denied is rectified. - - If the version field in the credential does not match the version of - RPCSEC_GSS that was used when the context was created, the - AUTH_BADCRED value is returned. - - If there is a problem with the credential, such a bad length, illegal - control procedure, or an illegal service, the appropriate auth_stat - status is AUTH_BADCRED. - - - -Eisler, et. al. Standards Track [Page 15] - -RFC 2203 RPCSEC_GSS Protocol Specification September 1997 - - - Other errors can be returned as appropriate. - -5.3.3.4. Mapping of GSS-API Errors to Server Responses - - During the data exchange phase, the server may invoke GSS_GetMIC(), - GSS_VerifyMIC(), GSS_Unwrap(), and GSS_Wrap(). If any of these - routines fail to return GSS_S_COMPLETE, then various unsuccessful - responses can be returned. The are described as follows for each of - the aforementioned four interfaces. - -5.3.3.4.1. GSS_GetMIC() Failure - - When GSS_GetMIC() is called to generate the verifier in the response, - a failure results in an RPC response with a reply status of - MSG_DENIED, reject status of AUTH_ERROR and an auth status of - RPCSEC_GSS_CTXPROBLEM. - - When GSS_GetMIC() is called to sign the call results (service is - rpc_gss_svc_integrity), a failure results in no RPC response being - sent. Since ONC RPC server applications will typically control when a - response is sent, the failure indication will be returned to the - server application and it can take appropriate action (such as - logging the error). - -5.3.3.4.2. GSS_VerifyMIC() Failure - - When GSS_VerifyMIC() is called to verify the verifier in request, a - failure results in an RPC response with a reply status of MSG_DENIED, - reject status of AUTH_ERROR and an auth status of - RPCSEC_GSS_CREDPROBLEM. - - When GSS_VerifyMIC() is called to verify the call arguments (service - is rpc_gss_svc_integrity), a failure results in an RPC response with - a reply status of MSG_ACCEPTED, and an acceptance status of - GARBAGE_ARGS. - -5.3.3.4.3. GSS_Unwrap() Failure - - When GSS_Unwrap() is called to decrypt the call arguments (service is - rpc_gss_svc_privacy), a failure results in an RPC response with a - reply status of MSG_ACCEPTED, and an acceptance status of - GARBAGE_ARGS. - -5.3.3.4.4. GSS_Wrap() Failure - - When GSS_Wrap() is called to encrypt the call results (service is - rpc_gss_svc_privacy), a failure results in no RPC response being - sent. Since ONC RPC server applications will typically control when a - - - -Eisler, et. al. Standards Track [Page 16] - -RFC 2203 RPCSEC_GSS Protocol Specification September 1997 - - - response is sent, the failure indication will be returned to the - application and it can take appropriate action (such as logging the - error). - -5.4. Context Destruction - - When the client is done using the session, it must send a control - message informing the server that it no longer requires the context. - This message is formulated just like a data request packet, with the - following differences: the credential has gss_proc set to - RPCSEC_GSS_DESTROY, the procedure specified in the header is - NULLPROC, and there are no procedure arguments. The sequence number - in the request must be valid, and the header checksum in the verifier - must be valid, for the server to accept the message. The server - sends a response as it would to a data request. The client and - server must then destroy the context for the session. - - If the request to destroy the context fails for some reason, the - client need not take any special action. The server must be prepared - to deal with situations where clients never inform the server that - they no longer are in session and so don't need the server to - maintain a context. An LRU mechanism or an aging mechanism should be - employed by the server to clean up in such cases. - -6. Set of GSS-API Mechanisms - - RPCSEC_GSS is effectively a "pass-through" to the GSS-API layer, and - as such it is inappropriate for the RPCSEC_GSS specification to - enumerate a minimum set of required security mechanisms and/or - quality of protections. - - If an application protocol specification references RPCSEC_GSS, the - protocol specification must list a mandatory set of { mechanism, QOP, - service } triples, such that an implementation cannot claim - conformance to the protocol specification unless it implements the - set of triples. Within each triple, mechanism is a GSS-API security - mechanism, QOP is a valid quality-of-protection within the mechanism, - and service is either rpc_gss_svc_integrity or rpc_gss_svc_privacy. - - For example, a network filing protocol built on RPC that depends on - RPCSEC_GSS for security, might require that Kerberos V5 with the - default QOP using the rpc_gss_svc_integrity service be supported by - implementations conforming to the network filing protocol - specification. - - - - - - - -Eisler, et. al. Standards Track [Page 17] - -RFC 2203 RPCSEC_GSS Protocol Specification September 1997 - - -7. Security Considerations - -7.1. Privacy of Call Header - - The reader will note that for the privacy option, only the call - arguments and results are encrypted. Information about the - application in the form of RPC program number, program version - number, and program procedure number is transmitted in the clear. - Encrypting these fields in the RPC call header would have changed the - size and format of the call header. This would have required revising - the RPC protocol which was beyond the scope of this proposal. Storing - the encrypted numbers in the credential would have obviated a - protocol change, but would have introduced more overloading of fields - and would have made implementations of RPC more complex. Even if the - fields were encrypted somehow, in most cases an attacker can - determine the program number and version number by examining the - destination address of the request and querying the rpcbind service - on the destination host [Srinivasan-bind]. In any case, even by not - encrypting the three numbers, RPCSEC_GSS still improves the state of - security over what existing RPC services have had available - previously. Implementors of new RPC services that are concerned about - this risk may opt to design in a "sub-procedure" field that is - included in the service specific call arguments. - -7.2. Sequence Number Attacks - -7.2.1. Sequence Numbers Above the Window - - An attacker cannot coax the server into raising the sequence number - beyond the range the legitimate client is aware of (and thus engineer - a denial of server attack) without constructing an RPC request that - will pass the header checksum. If the cost of verifying the header - checksum is sufficiently large (depending on the speed of the - processor doing the checksum and the cost of checksum algorithm), it - is possible to envision a denial of service attack (vandalism, in the - form of wasting processing resources) whereby the attacker sends - requests that are above the window. The simplest method might be for - the attacker to monitor the network traffic and then choose a - sequence number that is far above the current sequence number. Then - the attacker can send bogus requests using the above window sequence - number. - -7.2.2. Sequence Numbers Within or Below the Window - - If the attacker sends requests that are within or below the window, - then even if the header checksum is successfully verified, the server - will silently discard the requests because the server assumes it has - already processed the request. In this case, a server can optimize by - - - -Eisler, et. al. Standards Track [Page 18] - -RFC 2203 RPCSEC_GSS Protocol Specification September 1997 - - - skipping the header checksum verification if the sequence number is - below the window, or if it is within the window, not attempt the - checksum verification if the sequence number has already been seen. - -7.3. Message Stealing Attacks - - This proposal does not address attacks where an attacker can block or - steal messages without being detected by the server. To implement - such protection would be tantamount to assuming a state in the RPC - service. RPCSEC_GSS does not worsen this situation. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Eisler, et. al. Standards Track [Page 19] - -RFC 2203 RPCSEC_GSS Protocol Specification September 1997 - - -Appendix A. GSS-API Major Status Codes - - The GSS-API definition [Linn] does not include numerical values for - the various GSS-API major status codes. It is expected that this will - be addressed in future RFC. Until then, this appendix defines the - values for each GSS-API major status code listed in the GSS-API - definition. If in the future, the GSS-API definition defines values - for the codes that are different than what follows, then implementors - of RPCSEC_GSS will be obliged to map them into the values defined - below. If in the future, the GSS-API definition defines additional - status codes not defined below, then the RPCSEC_GSS definition will - subsume those additional values. - - Here are the definitions of each GSS_S_* major status that the - implementor of RPCSEC_GSS can expect in the gss_major major field of - rpc_gss_init_res. These definitions are not in RPC description - language form. The numbers are in base 16 (hexadecimal): - - GSS_S_COMPLETE 0x00000000 - GSS_S_CONTINUE_NEEDED 0x00000001 - GSS_S_DUPLICATE_TOKEN 0x00000002 - GSS_S_OLD_TOKEN 0x00000004 - GSS_S_UNSEQ_TOKEN 0x00000008 - GSS_S_GAP_TOKEN 0x00000010 - GSS_S_BAD_MECH 0x00010000 - GSS_S_BAD_NAME 0x00020000 - GSS_S_BAD_NAMETYPE 0x00030000 - GSS_S_BAD_BINDINGS 0x00040000 - GSS_S_BAD_STATUS 0x00050000 - GSS_S_BAD_MIC 0x00060000 - GSS_S_BAD_SIG 0x00060000 - GSS_S_NO_CRED 0x00070000 - GSS_S_NO_CONTEXT 0x00080000 - GSS_S_DEFECTIVE_TOKEN 0x00090000 - GSS_S_DEFECTIVE_CREDENTIAL 0x000a0000 - GSS_S_CREDENTIALS_EXPIRED 0x000b0000 - GSS_S_CONTEXT_EXPIRED 0x000c0000 - GSS_S_FAILURE 0x000d0000 - GSS_S_BAD_QOP 0x000e0000 - GSS_S_UNAUTHORIZED 0x000f0000 - GSS_S_UNAVAILABLE 0x00100000 - GSS_S_DUPLICATE_ELEMENT 0x00110000 - GSS_S_NAME_NOT_MN 0x00120000 - GSS_S_CALL_INACCESSIBLE_READ 0x01000000 - GSS_S_CALL_INACCESSIBLE_WRITE 0x02000000 - GSS_S_CALL_BAD_STRUCTURE 0x03000000 - - - - - -Eisler, et. al. Standards Track [Page 20] - -RFC 2203 RPCSEC_GSS Protocol Specification September 1997 - - - Note that the GSS-API major status is split into three fields as - follows: - - Most Significant Bit Least Significant Bit - |------------------------------------------------------------| - | Calling Error | Routine Error | Supplementary Info | - |------------------------------------------------------------| - Bit 31 24 23 16 15 0 - - Up to one status in the Calling Error field can be logically ORed - with up to one status in the Routine Error field which in turn can be - logically ORed with zero or more statuses in the Supplementary Info - field. If the resulting major status has a non-zero Calling Error - and/or a non-zero Routine Error, then the applicable GSS-API - operation has failed. For purposes of RPCSEC_GSS, this means that - the GSS_Accept_sec_context() call executed by the server has failed. - - If the major status is equal GSS_S_COMPLETE, then this indicates the - absence of any Errors or Supplementary Info. - - The meanings of most of the GSS_S_* status are defined in the GSS-API - definition, which the exceptions of: - - GSS_S_BAD_MIC This code has the same meaning as GSS_S_BAD_SIG. - - GSS_S_CALL_INACCESSIBLE_READ - A required input parameter could not be read. - - GSS_S_CALL_INACCESSIBLE_WRITE - A required input parameter could not be written. - - GSS_S_CALL_BAD_STRUCTURE - A parameter was malformed. - - - - - - - - - - - - - - - - - - -Eisler, et. al. Standards Track [Page 21] - -RFC 2203 RPCSEC_GSS Protocol Specification September 1997 - - -Acknowledgements - - Much of the protocol was based on the AUTH_GSSAPI security flavor - developed by Open Vision Technologies [Jaspan]. In particular, we - acknowledge Barry Jaspan, Marc Horowitz, John Linn, and Ellen - McDermott. - - Raj Srinivasan designed RPCSEC_GSS [Eisler] with input from Mike - Eisler. Raj, Roland Schemers, Lin Ling, and Alex Chiu contributed to - Sun Microsystems' implementation of RPCSEC_GSS. - - Brent Callaghan, Marc Horowitz, Barry Jaspan, John Linn, Hilarie - Orman, Martin Rex, Ted Ts'o, and John Wroclawski analyzed the - specification and gave valuable feedback. - - Steve Nahm and Kathy Slattery reviewed various drafts of this - specification. - - Much of content of Appendix A was excerpted from John Wray's Work in - Progress on GSS-API Version 2 C-bindings. - -References - - [Eisler] Eisler, M., Schemers, R., and Srinivasan, R. - (1996). "Security Mechanism Independence in ONC - RPC," Proceedings of the Sixth Annual USENIX - Security Symposium, pp. 51-65. - - [Jaspan] Jaspan, B. (1995). "GSS-API Security for ONC - RPC," `95 Proceedings of The Internet Society - Symposium on Network and Distributed System - Security, pp. 144- 151. - - [Linn] Linn, J., "Generic Security Service Application - Program Interface, Version 2", RFC 2078, January - 1997. - - [Srinivasan-bind] Srinivasan, R., "Binding Protocols for - ONC RPC Version 2", RFC 1833, August 1995. - - [Srinivasan-rpc] Srinivasan, R., "RPC: Remote Procedure Call - Protocol Specification Version 2", RFC 1831, - August 1995. - - [Srinivasan-xdr] Srinivasan, R., "XDR: External Data - Representation Standard", RFC 1832, August 1995. - - - - - -Eisler, et. al. Standards Track [Page 22] - -RFC 2203 RPCSEC_GSS Protocol Specification September 1997 - - -Authors' Addresses - - Michael Eisler - Sun Microsystems, Inc. - M/S UCOS03 - 2550 Garcia Avenue - Mountain View, CA 94043 - - Phone: +1 (719) 599-9026 - EMail: mre@eng.sun.com - - - Alex Chiu - Sun Microsystems, Inc. - M/S UMPK17-203 - 2550 Garcia Avenue - Mountain View, CA 94043 - - Phone: +1 (415) 786-6465 - EMail: hacker@eng.sun.com - - - Lin Ling - Sun Microsystems, Inc. - M/S UMPK17-201 - 2550 Garcia Avenue - Mountain View, CA 94043 - - Phone: +1 (415) 786-5084 - EMail: lling@eng.sun.com - - - - - - - - - - - - - - - - - - - - - -Eisler, et. al. Standards Track [Page 23] - diff --git a/doc/rfc2228.txt b/doc/rfc2228.txt deleted file mode 100644 index 1fbfcbfa0..000000000 --- a/doc/rfc2228.txt +++ /dev/null @@ -1,1515 +0,0 @@ - - - - - - -Network Working Group M. Horowitz -Request for Comments: 2228 Cygnus Solutions -Updates: 959 S. Lunt -Category: Standards Track Bellcore - October 1997 - - FTP Security Extensions - -Status of this Memo - - This document specifies an Internet standards track protocol for the - Internet community, and requests discussion and suggestions for - improvements. Please refer to the current edition of the "Internet - Official Protocol Standards" (STD 1) for the standardization state - and status of this protocol. Distribution of this memo is unlimited. - -Copyright Notice - - Copyright (C) The Internet Society (1997). All Rights Reserved. - -Abstract - - This document defines extensions to the FTP specification STD 9, RFC - 959, "FILE TRANSFER PROTOCOL (FTP)" (October 1985). These extensions - provide strong authentication, integrity, and confidentiality on both - the control and data channels with the introduction of new optional - commands, replies, and file transfer encodings. - - The following new optional commands are introduced in this - specification: - - AUTH (Authentication/Security Mechanism), - ADAT (Authentication/Security Data), - PROT (Data Channel Protection Level), - PBSZ (Protection Buffer Size), - CCC (Clear Command Channel), - MIC (Integrity Protected Command), - CONF (Confidentiality Protected Command), and - ENC (Privacy Protected Command). - - A new class of reply types (6yz) is also introduced for protected - replies. - - None of the above commands are required to be implemented, but - interdependencies exist. These dependencies are documented with the - commands. - - Note that this specification is compatible with STD 9, RFC 959. - - - -Horowitz & Lunt Standards Track [Page 1] - -RFC 2228 FTP Security Extensions October 1997 - - -1. Introduction - - The File Transfer Protocol (FTP) currently defined in STD 9, RFC 959 - and in place on the Internet uses usernames and passwords passed in - cleartext to authenticate clients to servers (via the USER and PASS - commands). Except for services such as "anonymous" FTP archives, - this represents a security risk whereby passwords can be stolen - through monitoring of local and wide-area networks. This either aids - potential attackers through password exposure and/or limits - accessibility of files by FTP servers who cannot or will not accept - the inherent security risks. - - Aside from the problem of authenticating users in a secure manner, - there is also the problem of authenticating servers, protecting - sensitive data and/or verifying its integrity. An attacker may be - able to access valuable or sensitive data merely by monitoring a - network, or through active means may be able to delete or modify the - data being transferred so as to corrupt its integrity. An active - attacker may also initiate spurious file transfers to and from a site - of the attacker's choice, and may invoke other commands on the - server. FTP does not currently have any provision for the encryption - or verification of the authenticity of commands, replies, or - transferred data. Note that these security services have value even - to anonymous file access. - - Current practice for sending files securely is generally either: - - 1. via FTP of files pre-encrypted under keys which are manually - distributed, - - 2. via electronic mail containing an encoding of a file encrypted - under keys which are manually distributed, - - 3. via a PEM message, or - - 4. via the rcp command enhanced to use Kerberos. - - None of these means could be considered even a de facto standard, and - none are truly interactive. A need exists to securely transfer files - using FTP in a secure manner which is supported within the FTP - protocol in a consistent manner and which takes advantage of existing - security infrastructure and technology. Extensions are necessary to - the FTP specification if these security services are to be introduced - into the protocol in an interoperable way. - - - - - - - -Horowitz & Lunt Standards Track [Page 2] - -RFC 2228 FTP Security Extensions October 1997 - - - Although the FTP control connection follows the Telnet protocol, and - Telnet has defined an authentication and encryption option [TELNET- - SEC], [RFC-1123] explicitly forbids the use of Telnet option - negotiation over the control connection (other than Synch and IP). - - Also, the Telnet authentication and encryption option does not - provide for integrity protection only (without confidentiality), and - does not address the protection of the data channel. - -2. FTP Security Overview - - At the highest level, the FTP security extensions seek to provide an - abstract mechanism for authenticating and/or authorizing connections, - and integrity and/or confidentiality protecting commands, replies, - and data transfers. - - In the context of FTP security, authentication is the establishment - of a client's identity and/or a server's identity in a secure way, - usually using cryptographic techniques. The basic FTP protocol does - not have a concept of authentication. - - Authorization is the process of validating a user for login. The - basic authorization process involves the USER, PASS, and ACCT - commands. With the FTP security extensions, authentication - established using a security mechanism may also be used to make the - authorization decision. - - Without the security extensions, authentication of the client, as - this term is usually understood, never happens. FTP authorization is - accomplished with a password, passed on the network in the clear as - the argument to the PASS command. The possessor of this password is - assumed to be authorized to transfer files as the user named in the - USER command, but the identity of the client is never securely - established. - - An FTP security interaction begins with a client telling the server - what security mechanism it wants to use with the AUTH command. The - server will either accept this mechanism, reject this mechanism, or, - in the case of a server which does not implement the security - extensions, reject the command completely. The client may try - multiple security mechanisms until it requests one which the server - accepts. This allows a rudimentary form of negotiation to take - place. (If more complex negotiation is desired, this may be - implemented as a security mechanism.) The server's reply will - indicate if the client must respond with additional data for the - - - - - - -Horowitz & Lunt Standards Track [Page 3] - -RFC 2228 FTP Security Extensions October 1997 - - - security mechanism to interpret. If none is needed, this will - usually mean that the mechanism is one where the password (specified - by the PASS command) is to be interpreted differently, such as with a - token or one-time password system. - - If the server requires additional security information, then the - client and server will enter into a security data exchange. The - client will send an ADAT command containing the first block of - security data. The server's reply will indicate if the data exchange - is complete, if there was an error, or if more data is needed. The - server's reply can optionally contain security data for the client to - interpret. If more data is needed, the client will send another ADAT - command containing the next block of data, and await the server's - reply. This exchange can continue as many times as necessary. Once - this exchange completes, the client and server have established a - security association. This security association may include - authentication (client, server, or mutual) and keying information for - integrity and/or confidentiality, depending on the mechanism in use. - - The term "security data" here is carefully chosen. The purpose of - the security data exchange is to establish a security association, - which might not actually include any authentication at all, between - the client and the server as described above. For instance, a - Diffie-Hellman exchange establishes a secret key, but no - authentication takes place. If an FTP server has an RSA key pair but - the client does not, then the client can authenticate the server, but - the server cannot authenticate the client. - - Once a security association is established, authentication which is a - part of this association may be used instead of or in addition to the - standard username/password exchange for authorizing a user to connect - to the server. A username specified by the USER command is always - required to specify the identity to be used on the server. - - In order to prevent an attacker from inserting or deleting commands - on the control stream, if the security association supports - integrity, then the server and client must use integrity protection - on the control stream, unless it first transmits a CCC command to - turn off this requirement. Integrity protection is performed with - the MIC and ENC commands, and the 63z reply codes. The CCC command - and its reply must be transmitted with integrity protection. - Commands and replies may be transmitted without integrity (that is, - in the clear or with confidentiality only) only if no security - association is established, the negotiated security association does - not support integrity, or the CCC command has succeeded. - - - - - - -Horowitz & Lunt Standards Track [Page 4] - -RFC 2228 FTP Security Extensions October 1997 - - - Once the client and server have negotiated with the PBSZ command an - acceptable buffer size for encapsulating protected data over the data - channel, the security mechanism may also be used to protect data - channel transfers. - - Policy is not specified by this document. In particular, client and - server implementations may choose to implement restrictions on what - operations can be performed depending on the security association - which exists. For example, a server may require that a client - authorize via a security mechanism rather than using a password, - require that the client provide a one-time password from a token, - require at least integrity protection on the command channel, or - require that certain files only be transmitted encrypted. An - anonymous ftp client might refuse to do file transfers without - integrity protection in order to insure the validity of files - downloaded. - - No particular set of functionality is required, except as - dependencies described in the next section. This means that none of - authentication, integrity, or confidentiality are required of an - implementation, although a mechanism which does none of these is not - of much use. For example, it is acceptable for a mechanism to - implement only integrity protection, one-way authentication and/or - encryption, encryption without any authentication or integrity - protection, or any other subset of functionality if policy or - technical considerations make this desirable. Of course, one peer - might require as a matter of policy stronger protection than the - other is able to provide, preventing perfect interoperability. - -3. New FTP Commands - - The following commands are optional, but dependent on each other. - They are extensions to the FTP Access Control Commands. - - The reply codes documented here are generally described as - recommended, rather than required. The intent is that reply codes - describing the full range of success and failure modes exist, but - that servers be allowed to limit information presented to the client. - For example, a server might implement a particular security - mechanism, but have a policy restriction against using it. The - server should respond with a 534 reply code in this case, but may - respond with a 504 reply code if it does not wish to divulge that the - disallowed mechanism is supported. If the server does choose to use - a different reply code than the recommended one, it should try to use - a reply code which only differs in the last digit. In all cases, the - server must use a reply code which is documented as returnable from - the command received, and this reply code must begin with the same - digit as the recommended reply code for the situation. - - - -Horowitz & Lunt Standards Track [Page 5] - -RFC 2228 FTP Security Extensions October 1997 - - - AUTHENTICATION/SECURITY MECHANISM (AUTH) - - The argument field is a Telnet string identifying a supported - mechanism. This string is case-insensitive. Values must be - registered with the IANA, except that values beginning with "X-" - are reserved for local use. - - If the server does not recognize the AUTH command, it must respond - with reply code 500. This is intended to encompass the large - deployed base of non-security-aware ftp servers, which will - respond with reply code 500 to any unrecognized command. If the - server does recognize the AUTH command but does not implement the - security extensions, it should respond with reply code 502. - - If the server does not understand the named security mechanism, it - should respond with reply code 504. - - If the server is not willing to accept the named security - mechanism, it should respond with reply code 534. - - If the server is not able to accept the named security mechanism, - such as if a required resource is unavailable, it should respond - with reply code 431. - - If the server is willing to accept the named security mechanism, - but requires security data, it must respond with reply code 334. - - If the server is willing to accept the named security mechanism, - and does not require any security data, it must respond with reply - code 234. - - If the server is responding with a 334 reply code, it may include - security data as described in the next section. - - Some servers will allow the AUTH command to be reissued in order - to establish new authentication. The AUTH command, if accepted, - removes any state associated with prior FTP Security commands. - The server must also require that the user reauthorize (that is, - reissue some or all of the USER, PASS, and ACCT commands) in this - case (see section 4 for an explanation of "authorize" in this - context). - - - - - - - - - - -Horowitz & Lunt Standards Track [Page 6] - -RFC 2228 FTP Security Extensions October 1997 - - - AUTHENTICATION/SECURITY DATA (ADAT) - - The argument field is a Telnet string representing base 64 encoded - security data (see Section 9, "Base 64 Encoding"). If a reply - code indicating success is returned, the server may also use a - string of the form "ADAT=base64data" as the text part of the reply - if it wishes to convey security data back to the client. - - The data in both cases is specific to the security mechanism - specified by the previous AUTH command. The ADAT command, and the - associated replies, allow the client and server to conduct an - arbitrary security protocol. The security data exchange must - include enough information for both peers to be aware of which - optional features are available. For example, if the client does - not support data encryption, the server must be made aware of - this, so it will know not to send encrypted command channel - replies. It is strongly recommended that the security mechanism - provide sequencing on the command channel, to insure that commands - are not deleted, reordered, or replayed. - - The ADAT command must be preceded by a successful AUTH command, - and cannot be issued once a security data exchange completes - (successfully or unsuccessfully), unless it is preceded by an AUTH - command to reset the security state. - - If the server has not yet received an AUTH command, or if a prior - security data exchange completed, but the security state has not - been reset with an AUTH command, it should respond with reply code - 503. - - If the server cannot base 64 decode the argument, it should - respond with reply code 501. - - If the server rejects the security data (if a checksum fails, for - instance), it should respond with reply code 535. - - If the server accepts the security data, and requires additional - data, it should respond with reply code 335. - - If the server accepts the security data, but does not require any - additional data (i.e., the security data exchange has completed - successfully), it must respond with reply code 235. - - If the server is responding with a 235 or 335 reply code, then it - may include security data in the text part of the reply as - specified above. - - - - - -Horowitz & Lunt Standards Track [Page 7] - -RFC 2228 FTP Security Extensions October 1997 - - - If the ADAT command returns an error, the security data exchange - will fail, and the client must reset its internal security state. - If the client becomes unsynchronized with the server (for example, - the server sends a 234 reply code to an AUTH command, but the - client has more data to transmit), then the client must reset the - server's security state. - - PROTECTION BUFFER SIZE (PBSZ) - - The argument is a decimal integer representing the maximum size, - in bytes, of the encoded data blocks to be sent or received during - file transfer. This number shall be no greater than can be - represented in a 32-bit unsigned integer. - - This command allows the FTP client and server to negotiate a - maximum protected buffer size for the connection. There is no - default size; the client must issue a PBSZ command before it can - issue the first PROT command. - - The PBSZ command must be preceded by a successful security data - exchange. - - If the server cannot parse the argument, or if it will not fit in - 32 bits, it should respond with a 501 reply code. - - If the server has not completed a security data exchange with the - client, it should respond with a 503 reply code. - - Otherwise, the server must reply with a 200 reply code. If the - size provided by the client is too large for the server, it must - use a string of the form "PBSZ=number" in the text part of the - reply to indicate a smaller buffer size. The client and the - server must use the smaller of the two buffer sizes if both buffer - sizes are specified. - - DATA CHANNEL PROTECTION LEVEL (PROT) - - The argument is a single Telnet character code specifying the data - channel protection level. - - This command indicates to the server what type of data channel - protection the client and server will be using. The following - codes are assigned: - - C - Clear - S - Safe - E - Confidential - P - Private - - - -Horowitz & Lunt Standards Track [Page 8] - -RFC 2228 FTP Security Extensions October 1997 - - - The default protection level if no other level is specified is - Clear. The Clear protection level indicates that the data channel - will carry the raw data of the file transfer, with no security - applied. The Safe protection level indicates that the data will - be integrity protected. The Confidential protection level - indicates that the data will be confidentiality protected. The - Private protection level indicates that the data will be integrity - and confidentiality protected. - - It is reasonable for a security mechanism not to provide all data - channel protection levels. It is also reasonable for a mechanism - to provide more protection at a level than is required (for - instance, a mechanism might provide Confidential protection, but - include integrity-protection in that encoding, due to API or other - considerations). - - The PROT command must be preceded by a successful protection - buffer size negotiation. - - If the server does not understand the specified protection level, - it should respond with reply code 504. - - If the current security mechanism does not support the specified - protection level, the server should respond with reply code 536. - - If the server has not completed a protection buffer size - negotiation with the client, it should respond with a 503 reply - code. - - The PROT command will be rejected and the server should reply 503 - if no previous PBSZ command was issued. - - If the server is not willing to accept the specified protection - level, it should respond with reply code 534. - - If the server is not able to accept the specified protection - level, such as if a required resource is unavailable, it should - respond with reply code 431. - - Otherwise, the server must reply with a 200 reply code to indicate - that the specified protection level is accepted. - - CLEAR COMMAND CHANNEL (CCC) - - This command does not take an argument. - - - - - - -Horowitz & Lunt Standards Track [Page 9] - -RFC 2228 FTP Security Extensions October 1997 - - - It is desirable in some environments to use a security mechanism - to authenticate and/or authorize the client and server, but not to - perform any integrity checking on the subsequent commands. This - might be used in an environment where IP security is in place, - insuring that the hosts are authenticated and that TCP streams - cannot be tampered, but where user authentication is desired. - - If unprotected commands are allowed on any connection, then an - attacker could insert a command on the control stream, and the - server would have no way to know that it was invalid. In order to - prevent such attacks, once a security data exchange completes - successfully, if the security mechanism supports integrity, then - integrity (via the MIC or ENC command, and 631 or 632 reply) must - be used, until the CCC command is issued to enable non-integrity - protected control channel messages. The CCC command itself must - be integrity protected. - - Once the CCC command completes successfully, if a command is not - protected, then the reply to that command must also not be - protected. This is to support interoperability with clients which - do not support protection once the CCC command has been issued. - - This command must be preceded by a successful security data - exchange. - - If the command is not integrity-protected, the server must respond - with a 533 reply code. - - If the server is not willing to turn off the integrity - requirement, it should respond with a 534 reply code. - - Otherwise, the server must reply with a 200 reply code to indicate - that unprotected commands and replies may now be used on the - command channel. - - INTEGRITY PROTECTED COMMAND (MIC) and - CONFIDENTIALITY PROTECTED COMMAND (CONF) and - PRIVACY PROTECTED COMMAND (ENC) - - The argument field of MIC is a Telnet string consisting of a base - 64 encoded "safe" message produced by a security mechanism - specific message integrity procedure. The argument field of CONF - is a Telnet string consisting of a base 64 encoded "confidential" - message produced by a security mechanism specific confidentiality - procedure. The argument field of ENC is a Telnet string - consisting of a base 64 encoded "private" message produced by a - security mechanism specific message integrity and confidentiality - procedure. - - - -Horowitz & Lunt Standards Track [Page 10] - -RFC 2228 FTP Security Extensions October 1997 - - - The server will decode and/or verify the encoded message. - - This command must be preceded by a successful security data - exchange. - - A server may require that the first command after a successful - security data exchange be CCC, and not implement the protection - commands at all. In this case, the server should respond with a - 502 reply code. - - If the server cannot base 64 decode the argument, it should - respond with a 501 reply code. - - If the server has not completed a security data exchange with the - client, it should respond with a 503 reply code. - - If the server has completed a security data exchange with the - client using a mechanism which supports integrity, and requires a - CCC command due to policy or implementation limitations, it should - respond with a 503 reply code. - - If the server rejects the command because it is not supported by - the current security mechanism, the server should respond with - reply code 537. - - If the server rejects the command (if a checksum fails, for - instance), it should respond with reply code 535. - - If the server is not willing to accept the command (if privacy is - required by policy, for instance, or if a CONF command is received - before a CCC command), it should respond with reply code 533. - - Otherwise, the command will be interpreted as an FTP command. An - end-of-line code need not be included, but if one is included, it - must be a Telnet end-of-line code, not a local end-of-line code. - - The server may require that, under some or all circumstances, all - commands be protected. In this case, it should make a 533 reply - to commands other than MIC, CONF, and ENC. - -4. Login Authorization - - The security data exchange may, among other things, establish the - identity of the client in a secure way to the server. This identity - may be used as one input to the login authorization process. - - - - - - -Horowitz & Lunt Standards Track [Page 11] - -RFC 2228 FTP Security Extensions October 1997 - - - In response to the FTP login commands (AUTH, PASS, ACCT), the server - may choose to change the sequence of commands and replies specified - by RFC 959 as follows. There are also some new replies available. - - If the server is willing to allow the user named by the USER command - to log in based on the identity established by the security data - exchange, it should respond with reply code 232. - - If the security mechanism requires a challenge/response password, it - should respond to the USER command with reply code 336. The text - part of the reply should contain the challenge. The client must - display the challenge to the user before prompting for the password - in this case. This is particularly relevant to more sophisticated - clients or graphical user interfaces which provide dialog boxes or - other modal input. These clients should be careful not to prompt for - the password before the username has been sent to the server, in case - the user needs the challenge in the 336 reply to construct a valid - password. - -5. New FTP Replies - - The new reply codes are divided into two classes. The first class is - new replies made necessary by the new FTP Security commands. The - second class is a new reply type to indicate protected replies. - - 5.1. New individual reply codes - - 232 User logged in, authorized by security data exchange. - 234 Security data exchange complete. - 235 [ADAT=base64data] - ; This reply indicates that the security data exchange - ; completed successfully. The square brackets are not - ; to be included in the reply, but indicate that - ; security data in the reply is optional. - - 334 [ADAT=base64data] - ; This reply indicates that the requested security mechanism - ; is ok, and includes security data to be used by the client - ; to construct the next command. The square brackets are not - ; to be included in the reply, but indicate that - ; security data in the reply is optional. - 335 [ADAT=base64data] - ; This reply indicates that the security data is - ; acceptable, and more is required to complete the - ; security data exchange. The square brackets - ; are not to be included in the reply, but indicate - ; that security data in the reply is optional. - - - - -Horowitz & Lunt Standards Track [Page 12] - -RFC 2228 FTP Security Extensions October 1997 - - - 336 Username okay, need password. Challenge is "...." - ; The exact representation of the challenge should be chosen - ; by the mechanism to be sensible to the human user of the - ; system. - - 431 Need some unavailable resource to process security. - - 533 Command protection level denied for policy reasons. - 534 Request denied for policy reasons. - 535 Failed security check (hash, sequence, etc). - 536 Requested PROT level not supported by mechanism. - 537 Command protection level not supported by security mechanism. - - 5.2. Protected replies. - - One new reply type is introduced: - - 6yz Protected reply - - There are three reply codes of this type. The first, reply - code 631 indicates an integrity protected reply. The - second, reply code 632, indicates a confidentiality and - integrity protected reply. the third, reply code 633, - indicates a confidentiality protected reply. - - The text part of a 631 reply is a Telnet string consisting - of a base 64 encoded "safe" message produced by a security - mechanism specific message integrity procedure. The text - part of a 632 reply is a Telnet string consisting of a base - 64 encoded "private" message produced by a security - mechanism specific message confidentiality and integrity - procedure. The text part of a 633 reply is a Telnet string - consisting of a base 64 encoded "confidential" message - produced by a security mechanism specific message - confidentiality procedure. - - The client will decode and verify the encoded reply. How - failures decoding or verifying replies are handled is - implementation-specific. An end-of-line code need not be - included, but if one is included, it must be a Telnet end- - of-line code, not a local end-of-line code. - - A protected reply may only be sent if a security data - exchange has succeeded. - - The 63z reply may be a multiline reply. In this case, the - plaintext reply must be broken up into a number of - fragments. Each fragment must be protected, then base 64 - - - -Horowitz & Lunt Standards Track [Page 13] - -RFC 2228 FTP Security Extensions October 1997 - - - encoded in order into a separate line of the multiline - reply. There need not be any correspondence between the - line breaks in the plaintext reply and the encoded reply. - Telnet end-of-line codes must appear in the plaintext of the - encoded reply, except for the final end-of-line code, which - is optional. - - The multiline reply must be formatted more strictly than the - continuation specification in RFC 959. In particular, each - line before the last must be formed by the reply code, - followed immediately by a hyphen, followed by a base 64 - encoded fragment of the reply. - - For example, if the plaintext reply is - - 123-First line - Second line - 234 A line beginning with numbers - 123 The last line - - then the resulting protected reply could be any of the - following (the first example has a line break only to fit - within the margins): - - 631 base64(protect("123-First line\r\nSecond line\r\n 234 A line - 631-base64(protect("123-First line\r\n")) - 631-base64(protect("Second line\r\n")) - 631-base64(protect(" 234 A line beginning with numbers\r\n")) - 631 base64(protect("123 The last line")) - - 631-base64(protect("123-First line\r\nSecond line\r\n 234 A line b")) - 631 base64(protect("eginning with numbers\r\n123 The last line\r\n")) - -6. Data Channel Encapsulation - - When data transfers are protected between the client and server (in - either direction), certain transformations and encapsulations must be - performed so that the recipient can properly decode the transmitted - file. - - The sender must apply all protection services after transformations - associated with the representation type, file structure, and transfer - mode have been performed. The data sent over the data channel is, - for the purposes of protection, to be treated as a byte stream. - - When performing a data transfer in an authenticated manner, the - authentication checks are performed on individual blocks of the file, - rather than on the file as a whole. Consequently, it is possible for - - - -Horowitz & Lunt Standards Track [Page 14] - -RFC 2228 FTP Security Extensions October 1997 - - - insertion attacks to insert blocks into the data stream (i.e., - replays) that authenticate correctly, but result in a corrupted file - being undetected by the receiver. To guard against such attacks, the - specific security mechanism employed should include mechanisms to - protect against such attacks. Many GSS-API mechanisms usable with - the specification in Appendix I, and the Kerberos mechanism in - Appendix II do so. - - The sender must take the input byte stream, and break it up into - blocks such that each block, when encoded using a security mechanism - specific procedure, will be no larger than the buffer size negotiated - by the client with the PBSZ command. Each block must be encoded, - then transmitted with the length of the encoded block prepended as a - four byte unsigned integer, most significant byte first. - - When the end of the file is reached, the sender must encode a block - of zero bytes, and send this final block to the recipient before - closing the data connection. - - The recipient will read the four byte length, read a block of data - that many bytes long, then decode and verify this block with a - security mechanism specific procedure. This must be repeated until a - block encoding a buffer of zero bytes is received. This indicates - the end of the encoded byte stream. - - Any transformations associated with the representation type, file - structure, and transfer mode are to be performed by the recipient on - the byte stream resulting from the above process. - - When using block transfer mode, the sender's (cleartext) buffer size - is independent of the block size. - - The server will reply 534 to a STOR, STOU, RETR, LIST, NLST, or APPE - command if the current protection level is not at the level dictated - by the server's security requirements for the particular file - transfer. - - If any data protection services fail at any time during data transfer - at the server end (including an attempt to send a buffer size greater - than the negotiated maximum), the server will send a 535 reply to the - data transfer command (either STOR, STOU, RETR, LIST, NLST, or APPE). - - - - - - - - - - -Horowitz & Lunt Standards Track [Page 15] - -RFC 2228 FTP Security Extensions October 1997 - - -7. Potential policy considerations - - While there are no restrictions on client and server policy, there - are a few recommendations which an implementation should implement. - - - Once a security data exchange takes place, a server should require - all commands be protected (with integrity and/or confidentiality), - and it should protect all replies. Replies should use the same - level of protection as the command which produced them. This - includes replies which indicate failure of the MIC, CONF, and ENC - commands. In particular, it is not meaningful to require that - AUTH and ADAT be protected; it is meaningful and useful to require - that PROT and PBSZ be protected. In particular, the use of CCC is - not recommended, but is defined in the interest of - interoperability between implementations which might desire such - functionality. - - - A client should encrypt the PASS command whenever possible. It is - reasonable for the server to refuse to accept a non-encrypted PASS - command if the server knows encryption is available. - - - Although no security commands are required to be implemented, it - is recommended that an implementation provide all commands which - can be implemented, given the mechanisms supported and the policy - considerations of the site (export controls, for instance). - -8. Declarative specifications - - These sections are modelled after sections 5.3 and 5.4 of RFC 959, - which describe the same information, except for the standard FTP - commands and replies. - - 8.1. FTP Security commands and arguments - - AUTH - ADAT - PROT - PBSZ - MIC - CONF - ENC - - ::= - ::= - ; must be formatted as described in section 9 - ::= C | S | E | P - ::= any decimal integer from 1 to (2^32)-1 - - - - -Horowitz & Lunt Standards Track [Page 16] - -RFC 2228 FTP Security Extensions October 1997 - - - 8.2. Command-Reply sequences - - Security Association Setup - AUTH - 234 - 334 - 502, 504, 534, 431 - 500, 501, 421 - ADAT - 235 - 335 - 503, 501, 535 - 500, 501, 421 - Data protection negotiation commands - PBSZ - 200 - 503 - 500, 501, 421, 530 - PROT - 200 - 504, 536, 503, 534, 431 - 500, 501, 421, 530 - Command channel protection commands - MIC - 535, 533 - 500, 501, 421 - CONF - 535, 533 - 500, 501, 421 - ENC - 535, 533 - 500, 501, 421 - Security-Enhanced login commands (only new replies listed) - USER - 232 - 336 - Data channel commands (only new replies listed) - STOR - 534, 535 - STOU - 534, 535 - RETR - 534, 535 - - - - - - - - -Horowitz & Lunt Standards Track [Page 17] - -RFC 2228 FTP Security Extensions October 1997 - - - LIST - 534, 535 - NLST - 534, 535 - APPE - 534, 535 - - In addition to these reply codes, any security command can return - 500, 501, 502, 533, or 421. Any ftp command can return a reply - code encapsulated in a 631, 632, or 633 reply once a security data - exchange has completed successfully. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Horowitz & Lunt Standards Track [Page 18] - -RFC 2228 FTP Security Extensions October 1997 - - -9. State Diagrams - - This section includes a state diagram which demonstrates the flow of - authentication and authorization in a security enhanced FTP - implementation. The rectangular blocks show states where the client - must issue a command, and the diamond blocks show states where the - server must issue a response. - - - ,------------------, USER - __\| Unauthenticated |_________\ - | /| (new connection) | /| - | `------------------' | - | | | - | | AUTH | - | V | - | / \ | - | 4yz,5yz / \ 234 | - |<--------< >------------->. | - | \ / | | - | \_/ | | - | | | | - | | 334 | | - | V | | - | ,--------------------, | | - | | Need Security Data |<--. | | - | `--------------------' | | | - | | | | | - | | ADAT | | | - | V | | | - | / \ | | | - | 4yz,5yz / \ 335 | | | - `<--------< >-----------' | | - \ / | | - \_/ | | - | | | - | 235 | | - V | | - ,---------------. | | - ,--->| Authenticated |<--------' | After the client and server - | `---------------' | have completed authenti- - | | | cation, command must be - | | USER | integrity-protected if - | | | integrity is available. The - | |<-------------------' CCC command may be issued to - | V relax this restriction. - - - - - -Horowitz & Lunt Standards Track [Page 19] - -RFC 2228 FTP Security Extensions October 1997 - - - | / \ - | 4yz,5yz / \ 2yz - |<--------< >------------->. - | \ / | - | \_/ | - | | | - | | 3yz | - | V | - | ,---------------. | - | | Need Password | | - | `---------------' | - | | | - | | PASS | - | V | - | / \ | - | 4yz,5yz / \ 2yz | - |<--------< >------------->| - | \ / | - | \_/ | - | | | - | | 3yz | - | V | - | ,--------------. | - | | Need Account | | - | `--------------' | - | | | - | | ACCT | - | V | - | / \ | - | 4yz,5yz / \ 2yz | - `<--------< >------------->| - \ / | - \_/ | - | | - | 3yz | - V | - ,-------------. | - | Authorized |/________| - | (Logged in) |\ - `-------------' - - - - - - - - - - - -Horowitz & Lunt Standards Track [Page 20] - -RFC 2228 FTP Security Extensions October 1997 - - -10. Base 64 Encoding - - Base 64 encoding is the same as the Printable Encoding described in - Section 4.3.2.4 of [RFC-1421], except that line breaks must not be - included. This encoding is defined as follows. - - Proceeding from left to right, the bit string resulting from the - mechanism specific protection routine is encoded into characters - which are universally representable at all sites, though not - necessarily with the same bit patterns (e.g., although the character - "E" is represented in an ASCII-based system as hexadecimal 45 and as - hexadecimal C5 in an EBCDIC-based system, the local significance of - the two representations is equivalent). - - A 64-character subset of International Alphabet IA5 is used, enabling - 6 bits to be represented per printable character. (The proposed - subset of characters is represented identically in IA5 and ASCII.) - The character "=" signifies a special processing function used for - padding within the printable encoding procedure. - - The encoding process represents 24-bit groups of input bits as output - strings of 4 encoded characters. Proceeding from left to right - across a 24-bit input group output from the security mechanism - specific message protection procedure, each 6-bit group is used as an - index into an array of 64 printable characters, namely "[A-Z][a- - z][0-9]+/". The character referenced by the index is placed in the - output string. These characters are selected so as to be universally - representable, and the set excludes characters with particular - significance to Telnet (e.g., "", "", IAC). - - Special processing is performed if fewer than 24 bits are available - in an input group at the end of a message. A full encoding quantum - is always completed at the end of a message. When fewer than 24 - input bits are available in an input group, zero bits are added (on - the right) to form an integral number of 6-bit groups. Output - character positions which are not required to represent actual input - data are set to the character "=". Since all canonically encoded - output is an integral number of octets, only the following cases can - arise: (1) the final quantum of encoding input is an integral - multiple of 24 bits; here, the final unit of encoded output will be - an integral multiple of 4 characters with no "=" padding, (2) the - final quantum of encoding input is exactly 8 bits; here, the final - unit of encoded output will be two characters followed by two "=" - padding characters, or (3) the final quantum of encoding input is - exactly 16 bits; here, the final unit of encoded output will be three - characters followed by one "=" padding character. - - - - - -Horowitz & Lunt Standards Track [Page 21] - -RFC 2228 FTP Security Extensions October 1997 - - - Implementors must keep in mind that the base 64 encodings in ADAT, - MIC, CONF, and ENC commands, and in 63z replies may be arbitrarily - long. Thus, the entire line must be read before it can be processed. - Several successive reads on the control channel may be necessary. It - is not appropriate to for a server to reject a command containing a - base 64 encoding simply because it is too long (assuming that the - decoding is otherwise well formed in the context in which it was - sent). - - Case must not be ignored when reading commands and replies containing - base 64 encodings. - -11. Security Considerations - - This entire document deals with security considerations related to - the File Transfer Protocol. - - Third party file transfers cannot be secured using these extensions, - since a security context cannot be established between two servers - using these facilities (no control connection exists between servers - over which to pass ADAT tokens). Further work in this area is - deferred. - -12. Acknowledgements - - I would like to thank the members of the CAT WG, as well as all - participants in discussions on the "cat-ietf@mit.edu" mailing list, - for their contributions to this document. I would especially like to - thank Sam Sjogren, John Linn, Ted Ts'o, Jordan Brown, Michael Kogut, - Derrick Brashear, John Gardiner Myers, Denis Pinkas, and Karri Balk - for their contributions to this work. Of course, without Steve Lunt, - the author of the first six revisions of this document, it would not - exist at all. - -13. References - - [TELNET-SEC] Borman, D., "Telnet Authentication and Encryption - Option", Work in Progress. - - [RFC-1123] Braden, R., "Requirements for Internet Hosts -- - Application and Support", STD 3, RFC 1123, October 1989. - - [RFC-1421] Linn, J., "Privacy Enhancement for Internet Electronic - Mail: Part I: Message Encryption and Authentication Procedures", - RFC 1421, February 1993. - - - - - - -Horowitz & Lunt Standards Track [Page 22] - -RFC 2228 FTP Security Extensions October 1997 - - -14. Author's Address - - Marc Horowitz - Cygnus Solutions - 955 Massachusetts Avenue - Cambridge, MA 02139 - - Phone: +1 617 354 7688 - EMail: marc@cygnus.com - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Horowitz & Lunt Standards Track [Page 23] - -RFC 2228 FTP Security Extensions October 1997 - - -Appendix I: Specification under the GSSAPI - - In order to maximise the utility of new security mechanisms, it is - desirable that new mechanisms be implemented as GSSAPI mechanisms - rather than as FTP security mechanisms. This will enable existing - ftp implementations to support the new mechanisms more easily, since - little or no code will need to be changed. In addition, the - mechanism will be usable by other protocols, such as IMAP, which are - built on top of the GSSAPI, with no additional specification or - implementation work needed by the mechanism designers. - - The security mechanism name (for the AUTH command) associated with - all mechanisms employing the GSSAPI is GSSAPI. If the server - supports a security mechanism employing the GSSAPI, it must respond - with a 334 reply code indicating that an ADAT command is expected - next. - - The client must begin the authentication exchange by calling - GSS_Init_Sec_Context, passing in 0 for input_context_handle - (initially), and a targ_name equal to output_name from - GSS_Import_Name called with input_name_type of Host-Based Service and - input_name_string of "ftp@hostname" where "hostname" is the fully - qualified host name of the server with all letters in lower case. - (Failing this, the client may try again using input_name_string of - "host@hostname".) The output_token must then be base 64 encoded and - sent to the server as the argument to an ADAT command. If - GSS_Init_Sec_Context returns GSS_S_CONTINUE_NEEDED, then the client - must expect a token to be returned in the reply to the ADAT command. - This token must subsequently be passed to another call to - GSS_Init_Sec_Context. In this case, if GSS_Init_Sec_Context returns - no output_token, then the reply code from the server for the previous - ADAT command must have been 235. If GSS_Init_Sec_Context returns - GSS_S_COMPLETE, then no further tokens are expected from the server, - and the client must consider the server authenticated. - - The server must base 64 decode the argument to the ADAT command and - pass the resultant token to GSS_Accept_Sec_Context as input_token, - setting acceptor_cred_handle to NULL (for "use default credentials"), - and 0 for input_context_handle (initially). If an output_token is - returned, it must be base 64 encoded and returned to the client by - including "ADAT=base64string" in the text of the reply. If - GSS_Accept_Sec_Context returns GSS_S_COMPLETE, the reply code must be - 235, and the server must consider the client authenticated. If - GSS_Accept_Sec_Context returns GSS_S_CONTINUE_NEEDED, the reply code - must be 335. Otherwise, the reply code should be 535, and the text - of the reply should contain a descriptive error message. - - - - - -Horowitz & Lunt Standards Track [Page 24] - -RFC 2228 FTP Security Extensions October 1997 - - - The chan_bindings input to GSS_Init_Sec_Context and - GSS_Accept_Sec_Context should use the client internet address and - server internet address as the initiator and acceptor addresses, - respectively. The address type for both should be GSS_C_AF_INET. No - application data should be specified. - - Since GSSAPI supports anonymous peers to security contexts, it is - possible that the client's authentication of the server does not - actually establish an identity. - - The procedure associated with MIC commands, 631 replies, and Safe - file transfers is: - - GSS_Wrap for the sender, with conf_flag == FALSE - - GSS_Unwrap for the receiver - - The procedure associated with ENC commands, 632 replies, and Private - file transfers is: - - GSS_Wrap for the sender, with conf_flag == TRUE - GSS_Unwrap for the receiver - - CONF commands and 633 replies are not supported. - - Both the client and server should inspect the value of conf_avail to - determine whether the peer supports confidentiality services. - - When the security state is reset (when AUTH is received a second - time, or when REIN is received), this should be done by calling the - GSS_Delete_sec_context function. - -Appendix II: Specification under Kerberos version 4 - - The security mechanism name (for the AUTH command) associated with - Kerberos Version 4 is KERBEROS_V4. If the server supports - KERBEROS_V4, it must respond with a 334 reply code indicating that an - ADAT command is expected next. - - The client must retrieve a ticket for the Kerberos principal - "ftp.hostname@realm" by calling krb_mk_req(3) with a principal name - of "ftp", an instance equal to the first part of the canonical host - name of the server with all letters in lower case (as returned by - krb_get_phost(3)), the server's realm name (as returned by - krb_realmofhost(3)), and an arbitrary checksum. The ticket must then - be base 64 encoded and sent as the argument to an ADAT command. - - - - - -Horowitz & Lunt Standards Track [Page 25] - -RFC 2228 FTP Security Extensions October 1997 - - - If the "ftp" principal name is not a registered principal in the - Kerberos database, then the client may fall back on the "rcmd" - principal name (same instance and realm). However, servers must - accept only one or the other of these principal names, and must not - be willing to accept either. Generally, if the server has a key for - the "ftp" principal in its srvtab, then that principal only must be - used, otherwise the "rcmd" principal only must be used. - - The server must base 64 decode the argument to the ADAT command and - pass the result to krb_rd_req(3). The server must add one to the - checksum from the authenticator, convert the result to network byte - order (most significant byte first), and sign it using - krb_mk_safe(3), and base 64 encode the result. Upon success, the - server must reply to the client with a 235 code and include - "ADAT=base64string" in the text of the reply. Upon failure, the - server should reply 535. - - Upon receipt of the 235 reply from the server, the client must parse - the text of the reply for the base 64 encoded data, decode it, - convert it from network byte order, and pass the result to - krb_rd_safe(3). The client must consider the server authenticated if - the resultant checksum is equal to one plus the value previously - sent. - - The procedure associated with MIC commands, 631 replies, and Safe - file transfers is: - - krb_mk_safe(3) for the sender - krb_rd_safe(3) for the receiver - - The procedure associated with ENC commands, 632 replies, and Private - file transfers is: - - krb_mk_priv(3) for the sender - krb_rd_priv(3) for the receiver - - CONF commands and 633 replies are not supported. - - Note that this specification for KERBEROS_V4 contains no provision - for negotiating alternate means for integrity and confidentiality - routines. Note also that the ADAT exchange does not convey whether - the peer supports confidentiality services. - - In order to stay within the allowed PBSZ, implementors must take note - that a cleartext buffer will grow by 31 bytes when processed by - krb_mk_safe(3) and will grow by 26 bytes when processed by - krb_mk_priv(3). - - - - -Horowitz & Lunt Standards Track [Page 26] - -RFC 2228 FTP Security Extensions October 1997 - - -Full Copyright Statement - - Copyright (C) The Internet Society (1997). All Rights Reserved. - - This document and translations of it may be copied and furnished to - others, and derivative works that comment on or otherwise explain it - or assist in its implmentation may be prepared, copied, published - andand distributed, in whole or in part, without restriction of any - kind, provided that the above copyright notice and this paragraph are - included on all such copies and derivative works. However, this - document itself may not be modified in any way, such as by removing - the copyright notice or references to the Internet Society or other - Internet organizations, except as needed for the purpose of - developing Internet standards in which case the procedures for - copyrights defined in the Internet Standards process must be - followed, or as required to translate it into languages other than - English. - - The limited permissions granted above are perpetual and will not be - revoked by the Internet Society or its successors or assigns. - - This document and the information contained herein is provided on an - "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING - TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING - BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION - HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF - MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. - - - - - - - - - - - - - - - - - - - - - - - - -Horowitz & Lunt Standards Track [Page 27] -