From 0bd4a81b2ecb7ddc44136998d6266e627028fa7a Mon Sep 17 00:00:00 2001 From: Jacques Vidrine Date: Wed, 18 Sep 2002 14:17:14 +0000 Subject: [PATCH] These RFCs and internet-drafts are not really needed in the base system, and I've not been importing them lately. cvs rm them now so they can be cleaned out of the attic later. Requested by: obrien --- .../draft-brezak-win2k-krb-rc4-hmac-01.txt | 412 - .../draft-brezak-win2k-krb-rc4-hmac-02.txt | 589 -- .../draft-brezak-win2k-krb-rc4-hmac-03.txt | 587 -- crypto/heimdal/doc/standardisation/draft-foo | 171 - .../heimdal/doc/standardisation/draft-foo.ms | 136 - crypto/heimdal/doc/standardisation/draft-foo2 | 171 - .../heimdal/doc/standardisation/draft-foo2.ms | 145 - crypto/heimdal/doc/standardisation/draft-foo3 | 227 - .../heimdal/doc/standardisation/draft-foo3.ms | 260 - .../draft-hornstein-dhc-kerbauth-02.txt | 1594 ---- .../draft-horowitz-key-derivation-01.txt | 244 - .../draft-ietf-cat-gssv2-08.txt | 62 - .../draft-ietf-cat-gssv2-cbind-04.txt | 6188 ------------ .../draft-ietf-cat-iakerb-04.txt | 301 - .../draft-ietf-cat-kerb-chg-password-02.txt | 311 - .../draft-ietf-cat-kerb-des3-hmac-sha1-00.txt | 127 - .../draft-ietf-cat-kerb-key-derivation-00.txt | 250 - .../draft-ietf-cat-kerberos-err-msg-00.txt | 252 - .../draft-ietf-cat-kerberos-extra-tgt-02.txt | 174 - .../draft-ietf-cat-kerberos-extra-tgt-03.txt | 5 - .../draft-ietf-cat-kerberos-pk-cross-01.txt | 282 - .../draft-ietf-cat-kerberos-pk-cross-06.txt | 523 -- .../draft-ietf-cat-kerberos-pk-init-03.txt | 589 -- .../draft-ietf-cat-kerberos-pk-init-11.txt | 1059 --- .../draft-ietf-cat-kerberos-pk-init-12.txt | 1080 --- .../draft-ietf-cat-kerberos-pk-tapp-03.txt | 378 - .../draft-ietf-cat-kerberos-revisions-00.txt | 8277 ----------------- .../draft-ietf-cat-kerberos-revisions-01.txt | 6214 ------------- .../draft-ietf-cat-kerberos-revisions-03.txt | 6766 -------------- .../draft-ietf-cat-kerberos-revisions-04.txt | 6780 -------------- .../draft-ietf-cat-kerberos-revisions-05.txt | 6866 -------------- .../draft-ietf-cat-kerberos-revisions-06.txt | 7301 --------------- .../draft-ietf-cat-kerberos-set-passwd-02.txt | 325 - .../draft-ietf-cat-kerberos-set-passwd-03.txt | 345 - .../draft-ietf-cat-krb-dns-locate-00.txt | 250 - .../draft-ietf-cat-krb-dns-locate-02.txt | 339 - .../draft-ietf-cat-krb5gss-mech2-03.txt | 1333 --- .../draft-ietf-ftpext-mlst-08.txt | 3415 ------- ...raft-ietf-krb-wg-kerberos-referrals-00.txt | 725 -- .../draft-ietf-krb-wg-krb-dns-locate-02.txt | 339 - .../draft-raeburn-cat-gssapi-krb5-3des-00.txt | 281 - .../draft-raeburn-krb-gssapi-krb5-3des-01.txt | 395 - .../draft-smedvinsky-dhc-kerbauth-01.txt | 929 -- .../draft-swift-win2k-krb-referrals-01.txt | 5 - .../draft-swift-win2k-krb-user2user-01.txt | 5 - .../draft-thomas-snmpv3-kerbusm-00.txt | 1140 --- ...ostle-win2k-cat-kerberos-set-passwd-00.txt | 227 - .../draft-tso-telnet-krb5-04.txt | 327 - .../heimdal/doc/standardisation/rc4-hmac.txt | 587 -- .../heimdal/doc/standardisation/rfc1508.txt | 2747 ------ .../heimdal/doc/standardisation/rfc1509.txt | 2691 ------ .../heimdal/doc/standardisation/rfc1510.txt | 6275 ------------- .../heimdal/doc/standardisation/rfc1750.txt | 1683 ---- .../heimdal/doc/standardisation/rfc1831.txt | 1011 -- .../heimdal/doc/standardisation/rfc1964.txt | 1123 --- .../heimdal/doc/standardisation/rfc2078.txt | 4763 ---------- .../heimdal/doc/standardisation/rfc2203.txt | 1291 --- .../heimdal/doc/standardisation/rfc2228.txt | 1515 --- .../heimdal/doc/standardisation/rfc2743.txt | 5659 ----------- .../heimdal/doc/standardisation/rfc2744.txt | 5659 ----------- 60 files changed, 103705 deletions(-) delete mode 100644 crypto/heimdal/doc/standardisation/draft-brezak-win2k-krb-rc4-hmac-01.txt delete mode 100644 crypto/heimdal/doc/standardisation/draft-brezak-win2k-krb-rc4-hmac-02.txt delete mode 100644 crypto/heimdal/doc/standardisation/draft-brezak-win2k-krb-rc4-hmac-03.txt delete mode 100644 crypto/heimdal/doc/standardisation/draft-foo delete mode 100644 crypto/heimdal/doc/standardisation/draft-foo.ms delete mode 100644 crypto/heimdal/doc/standardisation/draft-foo2 delete mode 100644 crypto/heimdal/doc/standardisation/draft-foo2.ms delete mode 100644 crypto/heimdal/doc/standardisation/draft-foo3 delete mode 100644 crypto/heimdal/doc/standardisation/draft-foo3.ms delete mode 100644 crypto/heimdal/doc/standardisation/draft-hornstein-dhc-kerbauth-02.txt delete mode 100644 crypto/heimdal/doc/standardisation/draft-horowitz-key-derivation-01.txt delete mode 100644 crypto/heimdal/doc/standardisation/draft-ietf-cat-gssv2-08.txt delete mode 100644 crypto/heimdal/doc/standardisation/draft-ietf-cat-gssv2-cbind-04.txt delete mode 100644 crypto/heimdal/doc/standardisation/draft-ietf-cat-iakerb-04.txt delete mode 100644 crypto/heimdal/doc/standardisation/draft-ietf-cat-kerb-chg-password-02.txt delete mode 100644 crypto/heimdal/doc/standardisation/draft-ietf-cat-kerb-des3-hmac-sha1-00.txt delete mode 100644 crypto/heimdal/doc/standardisation/draft-ietf-cat-kerb-key-derivation-00.txt delete mode 100644 crypto/heimdal/doc/standardisation/draft-ietf-cat-kerberos-err-msg-00.txt delete mode 100644 crypto/heimdal/doc/standardisation/draft-ietf-cat-kerberos-extra-tgt-02.txt delete mode 100644 crypto/heimdal/doc/standardisation/draft-ietf-cat-kerberos-extra-tgt-03.txt delete mode 100644 crypto/heimdal/doc/standardisation/draft-ietf-cat-kerberos-pk-cross-01.txt delete mode 100644 crypto/heimdal/doc/standardisation/draft-ietf-cat-kerberos-pk-cross-06.txt delete mode 100644 crypto/heimdal/doc/standardisation/draft-ietf-cat-kerberos-pk-init-03.txt delete mode 100644 crypto/heimdal/doc/standardisation/draft-ietf-cat-kerberos-pk-init-11.txt delete mode 100644 crypto/heimdal/doc/standardisation/draft-ietf-cat-kerberos-pk-init-12.txt delete mode 100644 crypto/heimdal/doc/standardisation/draft-ietf-cat-kerberos-pk-tapp-03.txt delete mode 100644 crypto/heimdal/doc/standardisation/draft-ietf-cat-kerberos-revisions-00.txt delete mode 100644 crypto/heimdal/doc/standardisation/draft-ietf-cat-kerberos-revisions-01.txt delete mode 100644 crypto/heimdal/doc/standardisation/draft-ietf-cat-kerberos-revisions-03.txt delete mode 100644 crypto/heimdal/doc/standardisation/draft-ietf-cat-kerberos-revisions-04.txt delete mode 100644 crypto/heimdal/doc/standardisation/draft-ietf-cat-kerberos-revisions-05.txt delete mode 100644 crypto/heimdal/doc/standardisation/draft-ietf-cat-kerberos-revisions-06.txt delete mode 100644 crypto/heimdal/doc/standardisation/draft-ietf-cat-kerberos-set-passwd-02.txt delete mode 100644 crypto/heimdal/doc/standardisation/draft-ietf-cat-kerberos-set-passwd-03.txt delete mode 100644 crypto/heimdal/doc/standardisation/draft-ietf-cat-krb-dns-locate-00.txt delete mode 100644 crypto/heimdal/doc/standardisation/draft-ietf-cat-krb-dns-locate-02.txt delete mode 100644 crypto/heimdal/doc/standardisation/draft-ietf-cat-krb5gss-mech2-03.txt delete mode 100644 crypto/heimdal/doc/standardisation/draft-ietf-ftpext-mlst-08.txt delete mode 100644 crypto/heimdal/doc/standardisation/draft-ietf-krb-wg-kerberos-referrals-00.txt delete mode 100644 crypto/heimdal/doc/standardisation/draft-ietf-krb-wg-krb-dns-locate-02.txt delete mode 100644 crypto/heimdal/doc/standardisation/draft-raeburn-cat-gssapi-krb5-3des-00.txt delete mode 100644 crypto/heimdal/doc/standardisation/draft-raeburn-krb-gssapi-krb5-3des-01.txt delete mode 100644 crypto/heimdal/doc/standardisation/draft-smedvinsky-dhc-kerbauth-01.txt delete mode 100644 crypto/heimdal/doc/standardisation/draft-swift-win2k-krb-referrals-01.txt delete mode 100644 crypto/heimdal/doc/standardisation/draft-swift-win2k-krb-user2user-01.txt delete mode 100644 crypto/heimdal/doc/standardisation/draft-thomas-snmpv3-kerbusm-00.txt delete mode 100644 crypto/heimdal/doc/standardisation/draft-trostle-win2k-cat-kerberos-set-passwd-00.txt delete mode 100644 crypto/heimdal/doc/standardisation/draft-tso-telnet-krb5-04.txt delete mode 100644 crypto/heimdal/doc/standardisation/rc4-hmac.txt delete mode 100644 crypto/heimdal/doc/standardisation/rfc1508.txt delete mode 100644 crypto/heimdal/doc/standardisation/rfc1509.txt delete mode 100644 crypto/heimdal/doc/standardisation/rfc1510.txt delete mode 100644 crypto/heimdal/doc/standardisation/rfc1750.txt delete mode 100644 crypto/heimdal/doc/standardisation/rfc1831.txt delete mode 100644 crypto/heimdal/doc/standardisation/rfc1964.txt delete mode 100644 crypto/heimdal/doc/standardisation/rfc2078.txt delete mode 100644 crypto/heimdal/doc/standardisation/rfc2203.txt delete mode 100644 crypto/heimdal/doc/standardisation/rfc2228.txt delete mode 100644 crypto/heimdal/doc/standardisation/rfc2743.txt delete mode 100644 crypto/heimdal/doc/standardisation/rfc2744.txt diff --git a/crypto/heimdal/doc/standardisation/draft-brezak-win2k-krb-rc4-hmac-01.txt b/crypto/heimdal/doc/standardisation/draft-brezak-win2k-krb-rc4-hmac-01.txt deleted file mode 100644 index a97ef9d191e0..000000000000 --- a/crypto/heimdal/doc/standardisation/draft-brezak-win2k-krb-rc4-hmac-01.txt +++ /dev/null @@ -1,412 +0,0 @@ -CAT working group M. Swift -Internet Draft J. Brezak -Document: draft-brezak-win2k-krb-rc4-hmac-01.txt Microsoft -Category: Informational October 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 desire 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 October 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 (NT Password Hash) 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(Data) returning the checksum of 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. - - All strings in this document are ASCII unless otherwise specified. - 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 October 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(concat(T, data)) - CHKSUM = HMAC(Ksign, 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 = concat("fortybits", T) //includes zero octet at - //end of string constant - Else - L = T - Ksign = HMAC(K,L) - Confounder = nonce(8) // get an 8 octet nonce for a confounder - Checksum = HMAC(Ksign, concat(Confounder, data)) - Ke = Ksign - if (K.enctype == KERB_ETYPE_RC4_HMAC_EXP) - 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 October 1999 - - - - 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. In this description, the key size is actually 56-bits. - -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 October 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: - - T = the message type, encoded as a little-endian four byte integer. - - GSS-ENCRYPT(K, T, data) - IV = SND_SEQ - K = XOR(K, 0xf0f0f0f0f0f0f0f0f0f0f0f0f0f0f0) - if (K.enctype == KERB_ETYPE_RC4_HMAC_EXP) - L = concat("fortybits", T) //includes zero octet at end - else - L = T - Ksign = HMAC(K, L) - Ke = Ksign - if (K.enctype == KERB_ETYPE_RC4_HMAC_EXP) - 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. In this description, the key size is actually 56-bits. - -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 - - - -Swift Category - Informational 5 - - Windows 2000 RC4-HMAC Kerberos E-Type October 1999 - - - - 5 Linn, J., "The Kerberos Version 5 GSS-API Mechanism", RFC-1964, - June 1996 - - 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 October 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/crypto/heimdal/doc/standardisation/draft-brezak-win2k-krb-rc4-hmac-02.txt b/crypto/heimdal/doc/standardisation/draft-brezak-win2k-krb-rc4-hmac-02.txt deleted file mode 100644 index 1fc9927dea4c..000000000000 --- a/crypto/heimdal/doc/standardisation/draft-brezak-win2k-krb-rc4-hmac-02.txt +++ /dev/null @@ -1,589 +0,0 @@ - - -CAT working group M. Swift -Internet Draft J. Brezak -Document: draft-brezak-win2k-krb-rc4-hmac-02.txt Microsoft -Category: Informational November 2000 - - - The Windows 2000 RC4-HMAC Kerberos encryption type - - -tatus 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. - -. 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 desire 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. - - -. Conventions used in this document - - - -wift Category - Informational 1 - - Windows 2000 RC4-HMAC Kerberos E-Type June 2000 - - - 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]. - -. 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 (NT Password Hash) 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). - - For an account with a password of "foo", this String2Key("foo") will - return: - - 0xac, 0x8e, 0x65, 0x7f, 0x83, 0xdf, 0x82, 0xbe, - 0xea, 0x5d, 0x43, 0xbd, 0xaf, 0x78, 0x00, 0xcc - -. 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(Data) returning the checksum of the data. - - RC4 is a stream cipher licensed by RSA Data Security [RSADSI]. A - compatible cipher is described 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. This - summarizes the different key derivation values used in the various - -wift Category - Informational 2 - - Windows 2000 RC4-HMAC Kerberos E-Type June 2000 - - - operations. Note that these differ from the key derivations used in - other Kerberos encryption types. - - T = 1 for TS-ENC-TS in the AS-Request - T = 8 for the AS-Reply - T = 7 for the Authenticator in the TGS-Request - T = 8 for the TGS-Reply - T = 2 for the Server Ticket in the AP-Request - T = 11 for the Authenticator in the AP-Request - T = 12 for the Server returned AP-Reply - T = 15 in the generation of checksum for the MIC token - T = 0 in the generation of sequence number for the MIC token - T = 13 in the generation of checksum for the WRAP token - T = 0 in the generation of sequence number for the WRAP token - T = 0 in the generation of encrypted data for the WRAPPED token - - All strings in this document are ASCII unless otherwise specified. - 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. - - The nonce(n) function returns a pseudo-random number of "n" octets. - -. 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, "signaturekey") //includes zero octet at end - tmp = MD5(concat(T, data)) - CHKSUM = HMAC(Ksign, tmp) - - -. 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. - -wift Category - Informational 3 - - Windows 2000 RC4-HMAC Kerberos E-Type June 2000 - - - - BYTE L40[14] = "fortybits"; - BYTE SK = "signaturekey"; - - ENCRYPT (K, fRC4_EXP, T, data, data_len, edata, edata_len) - { - if (fRC4_EXP){ - *((DWORD *)(L40+10)) = T; - HMAC (K, L40, 10 + 4, K1); - }else{ - HMAC (K, &T, 4, K1); - } - memcpy (K2, K1, 16); - if (fRC4_EXP) memset (K1+7, 0xAB, 9); - add_8_random_bytes(data, data_len, conf_plus_data); - HMAC (K2, conf_plus_data, 8 + data_len, checksum); - HMAC (K1, checksum, 16, K3); - RC4(K3, conf_plus_data, 8 + data_len, edata + 16); - memcpy (edata, checksum, 16); - edata_len = 16 + 8 + data_len; - } - - DECRYPT (K, fRC4_EXP, T, edata, edata_len, data, data_len) - { - if (fRC4_EXP){ - *((DWORD *)(L40+10)) = T; - HMAC (K, L40, 14, K1); - }else{ - HMAC (K, &T, 4, K1); - } - memcpy (K2, K1, 16); - if (fRC4_EXP) memset (K1+7, 0xAB, 9); - HMAC (K1, edata, 16, K3); // checksum is at edata - RC4(K3, edata + 16, edata_len - 16, edata + 16); - data_len = edata_len - 16 - 8; - memcpy (data, edata + 16 + 8, data_len); - - // verify generated and received checksums - HMAC (K2, edata + 16, edata_len - 16, checksum); - if (memcmp(edata, checksum, 16) != 0) - printf("CHECKSUM ERROR !!!!!!\n"); - } - - 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; - - The KDC message is encrypted using the ENCRYPT function not - including the Checksum in the RC4_MDx_HEADER. - - -wift Category - Informational 4 - - Windows 2000 RC4-HMAC Kerberos E-Type June 2000 - - - 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. In this description, the key size is actually 56-bits. - -. 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. - -. GSSAPI Kerberos V5 Mechanism Type - -.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. - - The Windows 2000 implementation also defines new GSSAPI flags in the - initial token passed when initializing a security context. These - flags are passed in the checksum field of the authenticator (See [5] - Section 1.1.1). - - GSS_C_DCE_STYLE - This flag was added for use with MicrosoftÆs - implementation of DCE RPC, which initially expected three legs of - authentication. Setting this flag causes an extra AP reply to be - sent from the client back to the server after receiving the serverÆs - AP reply. In addition, the context negotiation tokens do not have - GSSAPI framing - they are raw AP message and do not include object - identifiers. - #define GSS_C_DCE_STYLE 0x1000 - - - -wift Category - Informational 5 - - Windows 2000 RC4-HMAC Kerberos E-Type June 2000 - - - GSS_C_IDENTIFY_FLAG - This flag allows the client to indicate to the - server that it should only allow the server application to identify - the client by name and ID, but not to impersonate the client. - #define GSS_C_IDENTIFY_FLAG 0x2000 - - GSS_C_EXTENDED_ERROR_FLAG - Setting this flag indicates that the - client wants to be informed of extended error information. In - particular, Windows 2000 status codes may be returned in the data - field of a Kerberos error message. This allows the client to - understand a server failure more precisely. In addition, the server - may return errors to the client that are normally handled at the - application layer in the server, in order to let the client try to - recover. After receiving an error message, the client may attempt to - resubmit an AP request. - #define GSS_C_EXTENDED_ERROR_FLAG 0x4000 - - These flags are only used if a client is aware of these conventions - when using the SSPI on the Windows platform, they are not generally - used by default. - - When NetBIOS addresses are used in the GSSAPI, they are identified - by the GSS_C_AF_NETBIOS value. This value is defined as: - #define GSS_C_AF_NETBIOS 0x14 - NetBios addresses are 16-octet addresses typically composed of 1 to th 15 characters, trailing blank (ascii char 20) filled, with a 16 - octet of 0x0. - -.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). - - MIC (K, fRC4_EXP, seq_num, MIC_hdr, msg, msg_len, - MIC_seq, MIC_checksum) - { - HMAC (K, SK, 13, K4); - T = 15; - memcpy (T_plus_hdr_plus_msg + 00, &T, 4); - memcpy (T_plus_hdr_plus_msg + 04, MIC_hdr, 8); - // 0101 1100 FFFFFFFF - memcpy (T_plus_hdr_plus_msg + 12, msg, msg_len); - MD5 (T_hdr_msg, 4 + 8 + msg_len, MD5_of_T_hdr_msg); - HMAC (K4, MD5_of_T_hdr_msg, CHKSUM); - memcpy (MIC_checksum, CHKSUM, 8); // use only first 8 bytes - - T = 0; - if (fRC4_EXP){ - *((DWORD *)(L40+10)) = T; - HMAC (K, L40, 14, K5); - }else{ - HMAC (K, &T, 4, K5); - -wift Category - Informational 6 - - Windows 2000 RC4-HMAC Kerberos E-Type June 2000 - - - } - if (fRC4_EXP) memset(K5+7, 0xAB, 9); - HMAC(K5, MIT_checksum, 8, K6); - copy_seq_num_in_big_endian(seq_num, seq_plus_direction); - //0x12345678 - copy_direction_flag (direction_flag, seq_plus_direction + - 4); //0x12345678FFFFFFFF - RC4(K6, seq_plus_direction, 8, MIC_seq); - } - -.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. - - 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 wrap based messages is as - follow: - - - WRAP (K, fRC4_EXP, seq_num, WRAP_hdr, msg, msg_len, - WRAP_seq, WRAP_checksum, edata, edata_len) - { - HMAC (K, SK, 13, K7); - T = 13; - PAD = 1; - memcpy (T_hdr_conf_msg_pad + 00, &T, 4); - memcpy (T_hdr_conf_msg_pad + 04, WRAP_hdr, 8); // 0101 1100 - FFFFFFFF - memcpy (T_hdr_conf_msg_pad + 12, msg, msg_len); - memcpy (T_hdr_conf_msg_pad + 12 + msg_len, &PAD, 1); - MD5 (T_hdr_conf_msg_pad, - 4 + 8 + 8 + msg_len + 1, - MD5_of_T_hdr_conf_msg_pad); - HMAC (K7, MD5_of_T_hdr_conf_msg_pad, CHKSUM); - memcpy (WRAP_checksum, CHKSUM, 8); // use only first 8 - bytes - - T = 0; - if (fRC4_EXP){ - *((DWORD *)(L40+10)) = T; - HMAC (K, L40, 14, K8); - }else{ - HMAC (K, &T, 4, K8); - } - if (fRC4_EXP) memset(K8+7, 0xAB, 9); - HMAC(K8, WRAP_checksum, 8, K9); - copy_seq_num_in_big_endian(seq_num, seq_plus_direction); - //0x12345678 - -wift Category - Informational 7 - - Windows 2000 RC4-HMAC Kerberos E-Type June 2000 - - - copy_direction_flag (direction_flag, seq_plus_direction + - 4); //0x12345678FFFFFFFF - RC4(K9, seq_plus_direction, 8, WRAP_seq); - - for (i = 0; i < 16; i++) K10 [i] ^= 0xF0; // XOR each byte - of key with 0xF0 - T = 0; - if (fRC4_EXP){ - *(DWORD *)(L40+10) = T; - HMAC(K10, L40, 14, K11); - memset(K11+7, 0xAB, 9); - }else{ - HMAC(K10, &T, 4, K11); - } - HMAC(K11, seq_num, 4, K12); - RC4(K12, T_hdr_conf_msg_pad + 4 + 8, 8 + msg_len + 1, - edata); /* skip T & hdr */ - edata_len = 8 + msg_len + 1; // conf + msg_len + pad - } - - - 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. In this description, the key size is actually 56-bits. - -. 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. - -0. Acknowledgements - - We would like to thank Salil Dangi for the valuable input in - refining the descriptions of the functions and review input. - -1. 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 - - - -wift Category - Informational 8 - - Windows 2000 RC4-HMAC Kerberos E-Type June 2000 - - - - 5 Linn, J., "The Kerberos Version 5 GSS-API Mechanism", RFC-1964, - June 1996 - - 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 Thayer, R. and K. Kaukonen, "A Stream Cipher Encryption - Algorithm", Work in Progress. - - 9 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 - - 10 Neuman, C., Kohl, J., Ts'o, T., "The Kerberos Network - Authentication Service (V5)", draft-ietf-cat-kerberos-revisions- - 04.txt, June 25, 1999 - - -2. Author's Addresses - - Mike Swift - Dept. of Computer Science - Sieg Hall - University of Washington - Seattle, WA 98105 - Email: mikesw@cs.washington.edu - - John Brezak - Microsoft - One Microsoft Way - Redmond, Washington - Email: jbrezak@microsoft.com - - - - - - - - - - - - - - - -wift Category - Informational 9 - - Windows 2000 RC4-HMAC Kerberos E-Type October 1999 - - - -3. Full Copyright Statement - - "Copyright (C) The Internet Society (2000). 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. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -wift Category - Informational 10 - diff --git a/crypto/heimdal/doc/standardisation/draft-brezak-win2k-krb-rc4-hmac-03.txt b/crypto/heimdal/doc/standardisation/draft-brezak-win2k-krb-rc4-hmac-03.txt deleted file mode 100644 index 202d44e8639c..000000000000 --- a/crypto/heimdal/doc/standardisation/draft-brezak-win2k-krb-rc4-hmac-03.txt +++ /dev/null @@ -1,587 +0,0 @@ -CAT working group M. Swift -Internet Draft J. Brezak -Document: draft-brezak-win2k-krb-rc4-hmac-03.txt Microsoft -Category: Informational June 2000 - - - 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 desire 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 June 2000 - - - 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 (NT Password Hash) 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). - - For an account with a password of "foo", this String2Key("foo") will - return: - - 0xac, 0x8e, 0x65, 0x7f, 0x83, 0xdf, 0x82, 0xbe, - 0xea, 0x5d, 0x43, 0xbd, 0xaf, 0x78, 0x00, 0xcc - -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(Data) returning the checksum of the data. - - RC4 is a stream cipher licensed by RSA Data Security [RSADSI]. A - compatible cipher is described 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. This - summarizes the different key derivation values used in the various - -Swift Category - Informational 2 - - Windows 2000 RC4-HMAC Kerberos E-Type June 2000 - - - operations. Note that these differ from the key derivations used in - other Kerberos encryption types. - - T = 1 for TS-ENC-TS in the AS-Request - T = 8 for the AS-Reply - T = 7 for the Authenticator in the TGS-Request - T = 8 for the TGS-Reply - T = 2 for the Server Ticket in the AP-Request - T = 11 for the Authenticator in the AP-Request - T = 12 for the Server returned AP-Reply - T = 15 in the generation of checksum for the MIC token - T = 0 in the generation of sequence number for the MIC token - T = 13 in the generation of checksum for the WRAP token - T = 0 in the generation of sequence number for the WRAP token - T = 0 in the generation of encrypted data for the WRAPPED token - - All strings in this document are ASCII unless otherwise specified. - 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. - - 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, "signaturekey") //includes zero octet at end - tmp = MD5(concat(T, data)) - CHKSUM = HMAC(Ksign, 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. - -Swift Category - Informational 3 - - Windows 2000 RC4-HMAC Kerberos E-Type June 2000 - - - - BYTE L40[14] = "fortybits"; - BYTE SK = "signaturekey"; - - ENCRYPT (K, fRC4_EXP, T, data, data_len, edata, edata_len) - { - if (fRC4_EXP){ - *((DWORD *)(L40+10)) = T; - HMAC (K, L40, 10 + 4, K1); - }else{ - HMAC (K, &T, 4, K1); - } - memcpy (K2, K1, 16); - if (fRC4_EXP) memset (K1+7, 0xAB, 9); - add_8_random_bytes(data, data_len, conf_plus_data); - HMAC (K2, conf_plus_data, 8 + data_len, checksum); - HMAC (K1, checksum, 16, K3); - RC4(K3, conf_plus_data, 8 + data_len, edata + 16); - memcpy (edata, checksum, 16); - edata_len = 16 + 8 + data_len; - } - - DECRYPT (K, fRC4_EXP, T, edata, edata_len, data, data_len) - { - if (fRC4_EXP){ - *((DWORD *)(L40+10)) = T; - HMAC (K, L40, 14, K1); - }else{ - HMAC (K, &T, 4, K1); - } - memcpy (K2, K1, 16); - if (fRC4_EXP) memset (K1+7, 0xAB, 9); - HMAC (K1, edata, 16, K3); // checksum is at edata - RC4(K3, edata + 16, edata_len - 16, edata + 16); - data_len = edata_len - 16 - 8; - memcpy (data, edata + 16 + 8, data_len); - - // verify generated and received checksums - HMAC (K2, edata + 16, edata_len - 16, checksum); - if (memcmp(edata, checksum, 16) != 0) - printf("CHECKSUM ERROR !!!!!!\n"); - } - - 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; - - The KDC message is encrypted using the ENCRYPT function not - including the Checksum in the RC4_MDx_HEADER. - - -Swift Category - Informational 4 - - Windows 2000 RC4-HMAC Kerberos E-Type June 2000 - - - 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. In this description, the key size is actually 56-bits. - -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. - - The Windows 2000 implementation also defines new GSSAPI flags in the - initial token passed when initializing a security context. These - flags are passed in the checksum field of the authenticator (See [5] - Section 1.1.1). - - GSS_C_DCE_STYLE - This flag was added for use with Microsoft’s - implementation of DCE RPC, which initially expected three legs of - authentication. Setting this flag causes an extra AP reply to be - sent from the client back to the server after receiving the server’s - AP reply. In addition, the context negotiation tokens do not have - GSSAPI framing - they are raw AP message and do not include object - identifiers. - #define GSS_C_DCE_STYLE 0x1000 - - - -Swift Category - Informational 5 - - Windows 2000 RC4-HMAC Kerberos E-Type June 2000 - - - GSS_C_IDENTIFY_FLAG - This flag allows the client to indicate to the - server that it should only allow the server application to identify - the client by name and ID, but not to impersonate the client. - #define GSS_C_IDENTIFY_FLAG 0x2000 - - GSS_C_EXTENDED_ERROR_FLAG - Setting this flag indicates that the - client wants to be informed of extended error information. In - particular, Windows 2000 status codes may be returned in the data - field of a Kerberos error message. This allows the client to - understand a server failure more precisely. In addition, the server - may return errors to the client that are normally handled at the - application layer in the server, in order to let the client try to - recover. After receiving an error message, the client may attempt to - resubmit an AP request. - #define GSS_C_EXTENDED_ERROR_FLAG 0x4000 - - These flags are only used if a client is aware of these conventions - when using the SSPI on the Windows platform, they are not generally - used by default. - - When NetBIOS addresses are used in the GSSAPI, they are identified - by the GSS_C_AF_NETBIOS value. This value is defined as: - #define GSS_C_AF_NETBIOS 0x14 - NetBios addresses are 16-octet addresses typically composed of 1 to th 15 characters, trailing blank (ascii char 20) filled, with a 16 - octet of 0x0. - -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). - - MIC (K, fRC4_EXP, seq_num, MIC_hdr, msg, msg_len, - MIC_seq, MIC_checksum) - { - HMAC (K, SK, 13, K4); - T = 15; - memcpy (T_plus_hdr_plus_msg + 00, &T, 4); - memcpy (T_plus_hdr_plus_msg + 04, MIC_hdr, 8); - // 0101 1100 FFFFFFFF - memcpy (T_plus_hdr_plus_msg + 12, msg, msg_len); - MD5 (T_hdr_msg, 4 + 8 + msg_len, MD5_of_T_hdr_msg); - HMAC (K4, MD5_of_T_hdr_msg, CHKSUM); - memcpy (MIC_checksum, CHKSUM, 8); // use only first 8 bytes - - T = 0; - if (fRC4_EXP){ - *((DWORD *)(L40+10)) = T; - HMAC (K, L40, 14, K5); - }else{ - HMAC (K, &T, 4, K5); - -Swift Category - Informational 6 - - Windows 2000 RC4-HMAC Kerberos E-Type June 2000 - - - } - if (fRC4_EXP) memset(K5+7, 0xAB, 9); - HMAC(K5, MIT_checksum, 8, K6); - copy_seq_num_in_big_endian(seq_num, seq_plus_direction); - //0x12345678 - copy_direction_flag (direction_flag, seq_plus_direction + - 4); //0x12345678FFFFFFFF - RC4(K6, seq_plus_direction, 8, MIC_seq); - } - -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. - - 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 wrap based messages is as - follow: - - - WRAP (K, fRC4_EXP, seq_num, WRAP_hdr, msg, msg_len, - WRAP_seq, WRAP_checksum, edata, edata_len) - { - HMAC (K, SK, 13, K7); - T = 13; - PAD = 1; - memcpy (T_hdr_conf_msg_pad + 00, &T, 4); - memcpy (T_hdr_conf_msg_pad + 04, WRAP_hdr, 8); // 0101 1100 - FFFFFFFF - memcpy (T_hdr_conf_msg_pad + 12, msg, msg_len); - memcpy (T_hdr_conf_msg_pad + 12 + msg_len, &PAD, 1); - MD5 (T_hdr_conf_msg_pad, - 4 + 8 + 8 + msg_len + 1, - MD5_of_T_hdr_conf_msg_pad); - HMAC (K7, MD5_of_T_hdr_conf_msg_pad, CHKSUM); - memcpy (WRAP_checksum, CHKSUM, 8); // use only first 8 - bytes - - T = 0; - if (fRC4_EXP){ - *((DWORD *)(L40+10)) = T; - HMAC (K, L40, 14, K8); - }else{ - HMAC (K, &T, 4, K8); - } - if (fRC4_EXP) memset(K8+7, 0xAB, 9); - HMAC(K8, WRAP_checksum, 8, K9); - copy_seq_num_in_big_endian(seq_num, seq_plus_direction); - //0x12345678 - -Swift Category - Informational 7 - - Windows 2000 RC4-HMAC Kerberos E-Type June 2000 - - - copy_direction_flag (direction_flag, seq_plus_direction + - 4); //0x12345678FFFFFFFF - RC4(K9, seq_plus_direction, 8, WRAP_seq); - - for (i = 0; i < 16; i++) K10 [i] ^= 0xF0; // XOR each byte - of key with 0xF0 - T = 0; - if (fRC4_EXP){ - *(DWORD *)(L40+10) = T; - HMAC(K10, L40, 14, K11); - memset(K11+7, 0xAB, 9); - }else{ - HMAC(K10, &T, 4, K11); - } - HMAC(K11, seq_num, 4, K12); - RC4(K12, T_hdr_conf_msg_pad + 4 + 8, 8 + msg_len + 1, - edata); /* skip T & hdr */ - edata_len = 8 + msg_len + 1; // conf + msg_len + pad - } - - - 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. In this description, the key size is actually 56-bits. - -9. 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. - -10. Acknowledgements - - We would like to thank Salil Dangi for the valuable input in - refining the descriptions of the functions and review input. - -11. 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 - - - -Swift Category - Informational 8 - - Windows 2000 RC4-HMAC Kerberos E-Type June 2000 - - - - 5 Linn, J., "The Kerberos Version 5 GSS-API Mechanism", RFC-1964, - June 1996 - - 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 Thayer, R. and K. Kaukonen, "A Stream Cipher Encryption - Algorithm", Work in Progress. - - 9 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 - - 10 Neuman, C., Kohl, J., Ts'o, T., "The Kerberos Network - Authentication Service (V5)", draft-ietf-cat-kerberos-revisions- - 04.txt, June 25, 1999 - - -12. Author's Addresses - - Mike Swift - Dept. of Computer Science - Sieg Hall - University of Washington - Seattle, WA 98105 - Email: mikesw@cs.washington.edu - - John Brezak - Microsoft - One Microsoft Way - Redmond, Washington - Email: jbrezak@microsoft.com - - - - - - - - - - - - - - - -Swift Category - Informational 9 - - Windows 2000 RC4-HMAC Kerberos E-Type October 1999 - - - -13. Full Copyright Statement - - "Copyright (C) The Internet Society (2000). 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. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Swift Category - Informational 10 - diff --git a/crypto/heimdal/doc/standardisation/draft-foo b/crypto/heimdal/doc/standardisation/draft-foo deleted file mode 100644 index 8174d4678f8d..000000000000 --- a/crypto/heimdal/doc/standardisation/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/crypto/heimdal/doc/standardisation/draft-foo.ms b/crypto/heimdal/doc/standardisation/draft-foo.ms deleted file mode 100644 index 62b109afa52c..000000000000 --- a/crypto/heimdal/doc/standardisation/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/crypto/heimdal/doc/standardisation/draft-foo2 b/crypto/heimdal/doc/standardisation/draft-foo2 deleted file mode 100644 index 0fa695f640f8..000000000000 --- a/crypto/heimdal/doc/standardisation/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/crypto/heimdal/doc/standardisation/draft-foo2.ms b/crypto/heimdal/doc/standardisation/draft-foo2.ms deleted file mode 100644 index 7e0fa0a6281b..000000000000 --- a/crypto/heimdal/doc/standardisation/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/crypto/heimdal/doc/standardisation/draft-foo3 b/crypto/heimdal/doc/standardisation/draft-foo3 deleted file mode 100644 index 2b8b7bb5775c..000000000000 --- a/crypto/heimdal/doc/standardisation/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/crypto/heimdal/doc/standardisation/draft-foo3.ms b/crypto/heimdal/doc/standardisation/draft-foo3.ms deleted file mode 100644 index c024ca355cd4..000000000000 --- a/crypto/heimdal/doc/standardisation/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/crypto/heimdal/doc/standardisation/draft-hornstein-dhc-kerbauth-02.txt b/crypto/heimdal/doc/standardisation/draft-hornstein-dhc-kerbauth-02.txt deleted file mode 100644 index 89e64524c475..000000000000 --- a/crypto/heimdal/doc/standardisation/draft-hornstein-dhc-kerbauth-02.txt +++ /dev/null @@ -1,1594 +0,0 @@ - -DHC Working Group Ken Hornstein -INTERNET-DRAFT NRL -Category: Standards Track Ted Lemon - Internet Engines, Inc. -20 February 2000 Bernard Aboba -Expires: September 1, 2000 Microsoft - Jonathan Trostle - Cisco Systems - - DHCP Authentication Via Kerberos V - -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. - -The distribution of this memo is unlimited. - -1. Copyright Notice - -Copyright (C) The Internet Society (2000). All Rights Reserved. - -2. Abstract - -The Dynamic Host Configuration Protocol (DHCP) provides a mechanism for -host configuration. In some circumstances, it is useful for the DHCP -client and server to be able to mutually authenticate as well as to -guarantee the integrity of DHCP packets in transit. This document -describes how Kerberos V may be used in order to allow a DHCP client and -server to mutually authenticate as well as to protect the integrity of -the DHCP exchange. The protocol described in this document is capable of -handling both intra-realm and inter-realm authentication. - - - - - - -Hornstein, et al. Standards Track [Page 1] - - -INTERNET-DRAFT DHCP Authentication Via Kerberos V 20 February 2000 - - -3. Introduction - -The Dynamic Host Configuration Protocol (DHCP) provides a mechanism for -host configuration. In some circumstances, it is useful for the DHCP -client and server to be able to mutually authenticate as well as to -guarantee the integrity of DHCP packets in transit. This document -describes how Kerberos V may be used in order to allow a DHCP client and -server to mutually authenticate as well as to protect the integrity of -the DHCP exchange. The protocol described in this document is capable -of handling both intra-realm and inter-realm authentication. - -3.1. Terminology - -This document uses the following terms: - -DHCP client - A DHCP client or "client" is an Internet host using DHCP to - obtain configuration parameters such as a network address. - -DHCP server - A DHCP server or "server" is an Internet host that returns - configuration parameters to DHCP clients. - -Home KDC The KDC corresponding to the DHCP client's realm. - -Local KDC The KDC corresponding to the DHCP server's realm. - -3.2. Requirements language - -In this document, the key words "MAY", "MUST, "MUST NOT", "optional", -"recommended", "SHOULD", and "SHOULD NOT", are to be interpreted as -described in [1]. - -4. Protocol overview - -In DHCP authentication via Kerberos V, DHCP clients and servers utilize -a Kerberos session key in order to compute a message integrity check -value included within the DHCP authentication option. The message -integrity check serves to authenticate as well as integrity protect the -messages, while remaining compatible with the operation of a DHCP relay. -Replay protection is also provided by a replay counter within the -authentication option, as described in [3]. - -Each server maintains a list of session keys and identifiers for -clients, so that the server can retrieve the session key and identifier -used by a client to which the server has provided previous configuration -information. Each server MUST save the replay counter from the previous -authenticated message. To avoid replay attacks, the server MUST discard - - - -Hornstein, et al. Standards Track [Page 2] - - -INTERNET-DRAFT DHCP Authentication Via Kerberos V 20 February 2000 - - -any incoming message whose replay counter is not strictly greater than -the replay counter from the previous message. - -DHCP authentication, described in [3], must work within the existing -DHCP state machine described in [4]. For a client in INIT state, this -means that the client must obtain a valid TGT, as well as a session key, -within the two round-trips provided by the -DHCPDISCOVER/OFFER/REQUEST/ACK sequence. - -In INIT state, the DHCP client submits an incomplete AS_REQ to the DHCP -server within the DHCPDISCOVER message. The DHCP server then completes -the AS_REQ using the IP address to be assigned to the client, and -submits this to the client's home KDC in order to obtain a TGT on the -client's behalf. Once the home KDC responds with an AS_REP, the DHCP -server extracts the client TGT and submits this along with its own TGT -to the home KDC, in order to obtain a user-to-user ticket to the DHCP -client. The AS_REP as well as the AP_REQ are included by the DHCP server -in the DHCPOFFER. The DHCP client can then decrypt the AS_REP to obtain -a home realm TGT and TGT session key, using the latter to decrypt the -user-to-user ticket to obtain the user-to-user session key. It is the -user-to-user session key that is used to authenticate and integrity -protect the client's DHCPREQUEST, and DHCPDECLINE messages. Similarly, -this same session key is used to compute the integrity attribute in the -server's DHCPOFFER, DHCPACK and DHCPNAK messages, as described in [3]. - -In the INIT-REBOOT, REBINDING, or RENEWING states, the server can submit -the home realm TGT in the DHCPREQUEST, along with authenticating and -integrity protecting the message using an integrity attribute within the -authentication option. The integrity attribute is computed using the -existing session key. The DHCP server can then return a renewed user- -to-user ticket within the DHCPACK message. The authenticated DHCPREQUEST -message from a client in INIT-REBOOT state can only be validated by -servers that used the same session key to compute the integrity -attribute in their DHCPOFFER messages. - -Other servers will discard the DHCPREQUEST messages. Thus, only servers -that used the user-to-user session key selected by the client will be -able to determine that their offered configuration information was not -selected, returning the offered network address to the server's pool of -available addresses. The servers that cannot validate the DHCPREQUEST -message will eventually return their offered network addresses to their -pool of available addresses as described in section 3.1 of the DHCP -specification [4]. - -When sending a DHCPINFORM, there are two possible procedures. If the -client knows the DHCP server it will be interacting with, then it can -obtain a ticket to the DHCP server from the local realm KDC. This will -require obtaining a TGT to its home realm, as well as possibly a cross- - - - -Hornstein, et al. Standards Track [Page 3] - - -INTERNET-DRAFT DHCP Authentication Via Kerberos V 20 February 2000 - - -realm TGT to the local realm if the local and home realms differ. Once -the DHCP client has a local realm TGT, it can then request a DHCP server -ticket in a TGS_REQ. The DHCP client can then include AP_REQ and -integrity attributes within the DHCPINFORM. The integrity attribute is -computed as described in [3], using the session key obtained from the -TGS_REP. The DHCP server replies with a DHCPACK/DHCPNAK, authenticated -using the same session key. - -If the DHCP client does not know the DHCP server it is interacting with -then it will not be able to obtain a ticket to it and a different -procedure is needed. In this case, the client will include in the -DHCPINFORM an authentication option with a ticket attribute containing -its home realm TGT. The DHCP server will then use this TGT in order to -request a user-to-user ticket from the home KDC in a TGS_REQ. The DHCP -server will return the user-to-user ticket and will authenticate and -integrity protect the DHCPACK/DHCPNAK message. This is accomplished by -including AP_REQ and integrity attributes within the authentication -option included with the DHCPACK/DHCPNAK messages. - -In order to support the DHCP client's ability to authenticate the DHCP -server in the case where the server name is unknown, the Kerberos -principal name for the DHCP server must be of type KRB_NT_SRV_HST with -the service name component equal to 'dhcp'. For example, the DHCP server -principal name for the host srv.foo.org would be of the form -dhcp/srv.foo.org. The client MUST validate that the DHCP server -principal name has the above format. This convention requires that the -administrator ensure that non-DHCP server principals do not have names -that match the above format. - -4.1. Authentication Option Format - -A summary of the authentication option format for DHCP authentication -via Kerberos V is shown below. The fields are transmitted from left to -right. - -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 -+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ -| Code | Length | Protocol | Algorithm | -+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ -| Global Replay Counter | -+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ -| Global Replay Counter | -+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ -| Attributes... -+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - -Code - - - -Hornstein, et al. Standards Track [Page 4] - - -INTERNET-DRAFT DHCP Authentication Via Kerberos V 20 February 2000 - - - TBD - DHCP Authentication - -Length - - The length field is a single octet and indicates the length of the - Protocol, Algorith, and Authentication Information fields. Octets - outside the range of the length field should be ignored on reception. - -Protocol - - TBD - DHCP Kerberos V authentication - -Algorithm - - The algorithm field is a single octet and defines the specific - algorithm to be used for computation of the authentication option. - Values for the field are as follows: - - 0 - reserved - 1 - HMAC-MD5 - 2 - HMAC-SHA - 3 - 255 reserved - -Global Replay Counter - - As described in [3], the global replay counter field is 8 octets in - length. It MUST be set to the value of a monotonically increasing - counter. Using a counter value such as the current time of day (e.g., - an NTP-format timestamp [10]) can reduce the danger of replay - attacks. - -Attributes - - The attributes field consists of type-length-value attributes of the - following format: - - 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 - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | Type | Reserved | Payload Length | - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | Attribute value... - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - -Type - The type field is a single octet and is defined as follows: - - 0 - Integrity check - - - -Hornstein, et al. Standards Track [Page 5] - - -INTERNET-DRAFT DHCP Authentication Via Kerberos V 20 February 2000 - - - 1 - TICKET - 2 - Authenticator - 3 - EncTicketPart - 10 - AS_REQ - 11 - AS_REP - 12 - TGS_REQ - 13 - TGS_REP - 14 - AP_REQ - 15 - AP_REP - 20 - KRB_SAFE - 21 - KRB_PRIV - 22 - KRB_CRED - 25 - EncASRepPart - 26 - EncTGSRepPart - 27 - EncAPRepPart - 28 - EncKrbPrvPart - 29 - EncKrbCredPart - 30 - KRB_ERROR - - Note that the values of the Type field are the same as in the - Kerberos MSG-TYPE field. As a result, no new number spaces are - created for IANA administration. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Hornstein, et al. Standards Track [Page 6] - - -INTERNET-DRAFT DHCP Authentication Via Kerberos V 20 February 2000 - - - The following attribute types are allowed within the following - messages: - - DISCOVER OFFER REQUEST DECLINE # Attribute - -------------------------------------------------------- - 0 1 1 1 0 Integrity check - 0 0 0-1 0 1 Ticket - 1 0 0 0 10 AS_REQ - 0 1 0 0 11 AS_REP - 0 1 0 0 14 AP_REQ - 0 0-1 0 0 30 KRB_ERROR - - RELEASE ACK NAK INFORM INFORM # Attribute - w/known w/unknown - server server - --------------------------------------------------------------- - 1 1 1 1 0 0 Integrity check - 0 0 0 0 1 1 Ticket - 0 0 0 0 0 10 AS_REQ - 0 0 0 0 0 11 AS_REP - 0 0-1 0 1 0 14 AP_REQ - 0 0 0-1 0 0 30 KRB_ERROR - -4.2. Client behavior - -The following section, which incorporates material from [3], describes -client behavior in detail. - -4.2.1. INIT state - -When in INIT state, the client behaves as follows: - - -[1] As described in [3], the client MUST include the authentication - request option in its DHCPDISCOVER message along with option 61 - [11] to identify itself uniquely to the server. An AS_REQ attribute - MUST be included within the authentication request option. This - (incomplete) AS_REQ will set the FORWARDABLE and RENEWABLE flags - and MAY include pre-authentication data (PADATA) if the client - knows what PADATA its home KDC will require. The ADDRESSES field in - the AS_REQ will be ommitted since the client does not yet know its - IP address. The ETYPE field will be set to an encryption type that - the client can accept. - -[2] The client MUST validate DHCPOFFER messages that include an - authentication option. Messages including an authentication option - with a KRB_ERROR attribute and no integrity attribute are treated - as though they are unauthenticated. More typically, authentication - - - -Hornstein, et al. Standards Track [Page 7] - - -INTERNET-DRAFT DHCP Authentication Via Kerberos V 20 February 2000 - - - options within the DHCPOFFER message will include AS_REP, AP_REQ, - and integrity attributes. To validate the authentication option, - the client decrypts the enc-part of the AS_REP in order to obtain - the TGT session key. This is used to decrypt the enc-part of the - AP_REQ in order to obtain the user-to-user session key. The user- - to-user session key is then used to compute the message integrity - check as described in [3], and the computed value is compared to - the value within the integrity attribute. The client MUST discard - any messages which fail to pass validation and MAY log the - validation failure. - - As described in [3], the client selects one DHCPOFFER message as - its selected configuration. If none of the DHCPOFFER messages - received by the client include an authentication option, the client - MAY choose an unauthenticated message as its selected - configuration. DHCPOFFER messages including an authentication - option with a KRB_ERROR attribute and no integrity attribute are - treated as though they are unauthenticated. The client SHOULD be - configurable to accept or reject unauthenticated DHCPOFFER - messages. - -[3] The client replies with a DHCPREQUEST message that MUST include an - authentication option. The authentication option MUST include an - integrity attribute, computed as described in [3], using the user - to user session key recovered in step 2. - -[4] As noted in [3], the client MUST validate a DHCPACK message from - the server that includes an authentication option. DHCPACK or - DHCPNAK messages including an authentication option with a - KRB_ERROR attribute and no integrity attribute are treated as - though they are unauthenticated. The client MUST silently discard - the DHCPACK if the message fails to pass validation and MAY log the - validation failure. If the DHCPACK fails to pass validation, the - client MUST revert to the INIT state and return to step 1. The - client MAY choose to remember which server replied with an invalid - DHCPACK message and discard subsequent messages from that server. - -4.2.2. INIT-REBOOT state - -When in INIT-REBOOT state, if the user-to-user ticket is still valid, -the client MUST re-use the session key from the DHCP server user-to-user -ticket in its DHCPREQUEST message. This is used to generate the -integrity attribute contained within the authentication option, as -described in [3]. In the DHCPREQUEST, the DHCP client also includes its -home realm TGT in a ticket attribute in the authentication option in -order to assist the DHCP server in renewing the user-to-user ticket. To -ensure that the user-to-user ticket remains valid throughout the DHCP -lease period so that the renewal process can proceed, the Kerberos - - - -Hornstein, et al. Standards Track [Page 8] - - -INTERNET-DRAFT DHCP Authentication Via Kerberos V 20 February 2000 - - -ticket lifetime SHOULD be set to exceed the DHCP lease time. If the -user-to-user ticket is expired, then the client MUST return to the INIT -state. - -The client MAY choose to accept unauthenticated DHCPACK/DHCPNAK messages -if no authenticated messages were received. DHCPACK/DHCPNAK messages -with an authentication option containing a KRB_ERROR attribute and no -integrity attribute are treated as though they are unauthenticated. The -client MUST treat the receipt (or lack thereof) of any DHCPACK/DHCPNAK -messages as specified in section 3.2 of the DHCP specification [4]. - -4.2.3. RENEWING state - -When in RENEWING state, the DHCP client can be assumed to have a valid -IP address, as well as a TGT to the home realm, a user-to-user ticket -provided by the DHCP server, and a session key with the DHCP server, all -obtained during the original DHCP conversation. If the user-to-user -ticket is still valid, the client MUST re-use the session key from the -user-to-user ticket in its DHCPREQUEST message to generate the integrity -attribute contained within the authentication option. - -Since the DHCP client can renew the TGT to the home realm, it is -possible for it to continue to hold a valid home realm TGT. However, -since the DHCP client did not obtain the user-to-user ticket on its own, -it will need to rely on the DHCP server to renew this ticket. In the -DHCPREQUEST, the DHCP client includes its home realm TGT in a ticket -attribute in the authentication option in order to assist the DHCP -server in renewing the user-to-user ticket. - -If the DHCP server user-to-user ticket is expired, then the client MUST -return to INIT state. To ensure that the user-to-user ticket remains -valid throughout the DHCP lease period so that the renewal process can -proceed, the Kerberos ticket lifetime SHOULD be set to exceed the DHCP -lease time. If client receives no DHCPACK messages or none of the -DHCPACK messages pass validation, the client behaves as if it had not -received a DHCPACK message in section 4.4.5 of the DHCP specification -[4]. - -4.2.4. REBINDING state - -When in REBINDING state, the DHCP client can be assumed to have a valid -IP address, as well as a TGT to the home realm, a user-to-user ticket -and a session key with the DHCP server, all obtained during the original -DHCP conversation. If the user-to-user ticket is still valid, the -client MUST re-use the session key from the user-to-user ticket in its -DHCPREQUEST message to generate the integrity attribute contained within -the authentication option, as described in [3]. - - - - -Hornstein, et al. Standards Track [Page 9] - - -INTERNET-DRAFT DHCP Authentication Via Kerberos V 20 February 2000 - - -Since the DHCP client can renew the TGT to the home realm, it is -possible for it to continue to hold a valid home realm TGT. However, -since the DHCP client did not obtain the user-to-user ticket on its own, -it will need to rely on the DHCP server to renew this ticket. In the -DHCPREQUEST, the DHCP client includes its home realm TGT in a ticket -attribute in the authentication option in order to assist the DHCP -server in renewing the user-to-user ticket. - -If the user-to-user ticket is expired, then the client MUST return to -INIT state. To ensure that the user-to-user ticket remains valid -throughout the DHCP lease period so that the renewal process can -proceed, the Kerberos ticket lifetime SHOULD be set to exceed the DHCP -lease time. If client receives no DHCPACK messages or none of the -DHCPACK messages pass validation, the client behaves as if it had not -received a DHCPACK message in section 4.4.5 of the DHCP specification -[4]. - -4.2.5. DHCPRELEASE message - -Clients sending a DHCPRELEASE MUST include an authentication option. The -authentication option MUST include an integrity attribute, computed as -described in [3], using the user to user session key. - -4.2.6. DHCPDECLINE message - -Clients sending a DHCPDECLINE MUST include an authentication option. The -authentication option MUST include an integrity attribute, computed as -described in [3], using the user to user session key. - -4.2.7. DHCPINFORM message - -Since the client already has some configuration information, it can be -assumed that it has the ability to obtain a home or local realm TGT -prior to sending the DHCPINFORM. - -If the DHCP client knows which DHCP server it will be interacting with, -then it SHOULD include an authentication option containing AP_REQ and -integrity attributes within the DHCPINFORM. The DHCP client first -requests a TGT to the local realm via an AS_REQ and then using the TGT -returned in the AS_REP to request a ticket to the DHCP server from the -local KDC in a TGS_REQ. The session key obtained from the TGS_REP will -be used to generate the integrity attribute as described in [3]. - -If the DHCP client does not know what DHCP server it will be talking to, -then it cannot obtain a ticket to the DHCP server. In this case, the -DHCP client MAY send an unauthenticated DHCPINFORM or it MAY include an -authentication option including a ticket attribute only. The ticket -attribute includes a TGT for the home realm. The client MUST validate - - - -Hornstein, et al. Standards Track [Page 10] - - -INTERNET-DRAFT DHCP Authentication Via Kerberos V 20 February 2000 - - -that the DHCP server name in the received Kerberos AP_REQ message is of -the form dhcp/.... as described in section 4. - -The client MAY choose to accept unauthenticated DHCPACK/DHCPNAK messages -if no authenticated messages were received. DHCPACK/DHCPNAK messages -with an authentication option containing a KRB_ERROR attribute and no -integrity attribute are treated as though they are unauthenticated. The -client MUST treat the receipt (or lack thereof) of any DHCPACK/DHCPNAK -messages as specified in section 3.2 of the DHCP specification [4]. - -4.3. Server behavior - -This section, which relies on material from [3], describes the behavior -of a server in response to client messages. - -4.3.1. After receiving a DHCPDISCOVER message - -For installations where IP addresses are required within tickets, the -DHCP server MAY complete the AS_REQ by filling in the ADDRESSES field -based on the IP address that it will include in the DHCPOFFER. The DHCP -server sends the AS_REQ to the home KDC with the FORWARDABLE flag set. -The home KDC then replies to the DHCP server with an AS_REP. The DHCP -server extracts the client TGT from the AS_REP and forms a TGS_REQ, -which it sends to the home KDC. - -If the DHCP server and client are in different realms, then the DHCP -server will need to obtain a TGT to the home realm from the KDC of its -own (local) realm prior to sending the TGS_REQ. The TGS_REQ includes the -DHCP server's TGT within the home realm, has the ENC-TKT-IN-SKEY flag -set and includes the client home realm TGT in the ADDITIONAL-TICKETS -field, thus requesting a user-to ticket to the DHCP client. The home -KDC then returns a user-to-user ticket in a TGS_REP. The user-to-user -ticket is encrypted in the client's home realm TGT session key. - -In order to recover the user-to-user session key, the DHCP server -decrypts the enc-part of the TGS_REP. To accomplish this, the DHCP -server uses the session key that it shares with the home realm, obtained -in the AS_REQ/AS_REP conversation that it used to obtain its own TGT to -the home realm. - -The DHCP server then sends a DHCPOFFER to the client, including AS_REP, -AP_REQ and integrity attributes within the authentication option. The -AS_REP attribute encapsulates the AS_REP sent to the DHCP server by the -home KDC. The AP_REQ attribute includes an AP_REQ constructed by the -DHCP server based on the TGS_REP sent to it by the home KDC. The server -also includes an integrity attribute generated as specified in [3] from -the user-to-user session key. The server MUST record the user-to-user -session key selected for the client and use that session key for - - - -Hornstein, et al. Standards Track [Page 11] - - -INTERNET-DRAFT DHCP Authentication Via Kerberos V 20 February 2000 - - -validating subsequent messages with the client. - -4.3.2. After receiving a DHCPREQUEST message - -The DHCP server uses the user-to-user session key in order to validate -the integrity attribute contained within the authentication option, -using the method specified in [3]. If the message fails to pass -validation, it MUST discard the message and MAY choose to log the -validation failure. - -If the message passes the validation procedure, the server responds as -described in [4], including an integrity attribute computed as specified -in [3] within the DHCPACK or DHCPNAK message. - -If the authentication option included within the DHCPREQUEST message -contains a ticket attribute then the DHCP server will use the home realm -TGT included in the ticket attribute in order to renew the user-to-user -ticket, which it returns in an AP_REQ attribute within the DHCPACK. -DHCPACK or DHCPNAK messages then include an integrity attribute -generated as specified in [3], using the new user-to-user session key -included within the AP_REQ. - -4.3.3. After receiving a DHCPINFORM message - -The server MAY choose to accept unauthenticated DHCPINFORM messages, or -only accept authenticated DHCPINFORM messages based on a site policy. - -When a client includes an authentication option in a DHCPINFORM message, -the server MUST respond with an authenticated DHCPACK or DHCPNAK -message. If the DHCPINFORM message includes an authentication option -including AP_REQ and integrity attributes, the DHCP server decrypts the -AP_REQ attribute and then recovers the session key. The DHCP server than -validates the integrity attribute included in the authentication option -using the session key. If the integrity attribute is invalid then the -DHCP server MUST silently discard the DHCPINFORM message. - -If the authentication option only includes a ticket attribute and no -integrity or AP_REQ attributes, then the DHCP server should assume that -the client needs the server to obtain a user-to-user ticket from the -home realm KDC. In this case, the DHCP server includes the client home -realm TGT and its own home realm TGT in a TGS_REQ to the home realm KDC. -It then receives a user-to-user ticket from the home realm KDC in a -TGS_REP. The DHCP server will then include AP_REQ and integrity -attributes within the DHCPACK/DHCPNAK. - -If the client does not include an authentication option in the -DHCPINFORM, the server can either respond with an unauthenticated -DHCPACK message, or a DHCPNAK if the server does not accept - - - -Hornstein, et al. Standards Track [Page 12] - - -INTERNET-DRAFT DHCP Authentication Via Kerberos V 20 February 2000 - - -unauthenticated clients. - -4.3.4. After receiving a DHCPRELEASE message - -The DHCP server uses the session key in order to validate the integrity -attribute contained within the authentication option, using the method -specified in [3]. If the message fails to pass validation, it MUST -discard the message and MAY choose to log the validation failure. - -If the message passes the validation procedure, the server responds as -described in [4], marking the client's network address as not allocated. - -4.3.5. After receiving a DHCPDECLINE message - -The DHCP server uses the session key in order to validate the integrity -attribute contained within the authentication option, using the method -specified in [3]. If the message fails to pass validation, it MUST -discard the message and MAY choose to log the validation failure. - -If the message passes the validation procedure, the server proceeds as -described in [4]. - -4.4. Error handling - -When an error condition occurs during a Kerberos exchange, Kerberos -error messages can be returned by either side. These Kerberos error -messages MAY be logged by the receiving and sending parties. - -In some cases, it may be possible for these error messages to be -included within the authentication option via the KRB_ERROR attribute. -However, in most cases, errors will result in messages being silently -discarded and so no response will be returned. - -For example, if the home KDC returns a KRB_ERROR in response to the -AS_REQ submitted by the DHCP server on the client's behalf, then the -DHCP server will conclude that the DHCPDISCOVER was not authentic, and -will silently discard it. - -However, if the AS_REQ included PADATA and the home KDC responds with an -AS_REP, then the DHCP server can conclude that the client is authentic. -If the subsequent TGS_REQ is unsuccessful, with a KRB_ERROR returned by -the home KDC in the TGS_REP, then the fault may lie with the DHCP server -rather than with the client. In this case, the DHCP server MAY choose to -return a KRB_ERROR within the authentication option included in the -DHCPOFFER. The client will then treat this as an unauthenticated -DHCPOFFER. - - - - - -Hornstein, et al. Standards Track [Page 13] - - -INTERNET-DRAFT DHCP Authentication Via Kerberos V 20 February 2000 - - -Similarly, if the integrity attribute contained in the DHCPOFFER proves -invalid, the client will silently discard the DHCPOFFER and instead -accept an offer from another server if one is available. If the -integrity attribute included in the DHCPACK/DHCPNAK proves invalid, then -the client behaves as if it did not receive a DHCPACK/DHCPNAK. - -When in INIT-REBOOT, REBINDING or RENEWING state, the client will -include a ticket attribute and integrity attribute within the -authentication option of the DHCPREQUEST, in order to assist the DHCP -server in renewing the user-to-user ticket. If the integrity attribute -is invalid, then the DHCP server MUST silently discard the DHCPREQUEST. - -However, if the integrity attribute is successfully validated by the -DHCP server, but the home realm TGT included in the ticket attribute is -invalid (e.g. expired), then the DHCP server will receive a KRB_ERROR in -response to its TGS_REQ to the home KDC. In this case, the DHCP server -MAY respond with a DHCPNAK including a KRB_ERROR attribute and no -integrity attribute within the authentication option. This will force -the client back to the INIT state, where it can receive a valid home -realm TGT. - -Where the client included PADATA in the AS_REQ attribute of the -authentication option within the DHCPDISCOVER and the AS_REQ was -successfully validated by the KDC, the DHCP server will conclude that -the DHCP client is authentic. In this case if the client successfully -validates the integrity attribute in the DHCPOFFER, but the server does -not validate the integrity attribute in the client's DHCPREQUEST, the -server MAY choose to respond with an authenticated DHCPNAK containing a -KRB_ERROR attribute. - -4.5. PKINIT issues - -When public key authentication is supported with Kerberos as described -in [8], the client certificate and a signature accompany the initial -request in the preauthentication fields. As a result, it is conceivable -that the incomplete AS_REQ included in the DHCPDISCOVER packet may -exceed the size of a single DHCP option, or even the MTU size. As noted -in [4], a single option may be as large as 255 octets. If the value to -be passed is larger than this the client concatenates together the -values of multiple instances of the same option. - -4.6. Examples - -4.6.1. INIT state - -In the intra-realm case where the DHCP Kerberos mutual authentication is -successful, the conversation will appear as follows: - - - - -Hornstein, et al. Standards Track [Page 14] - - -INTERNET-DRAFT DHCP Authentication Via Kerberos V 20 February 2000 - - - DHCP DHCP - Client Server KDC --------------- ------------- --------- -DHCPDISCOVER - (Incomplete - AS_REQ) -> - AS_REQ -> - <- AS_REP - TGS_REQ - U-2-U -> - <- TGS_REP - <- DHCPOFFER, - (AS_REP, - AP_REQ, - Integrity) -DHCPREQUEST - (Integrity) -> - <- DHCPACK - (Integrity) - -In the case where the KDC returns a KRB_ERROR in response to the AS_REQ, -the server will silently discard the DHCPDISCOVER and the conversation -will appear as follows: - - DHCP DHCP - Client Server KDC --------------- ------------- --------- -DHCPDISCOVER - (Incomplete - AS_REQ) -> - AS_REQ -> - <- KRB_ERROR - -In the inter-realm case where the DHCP Kerberos mutual authentication is -successful, the conversation will appear as follows: - - DHCP DHCP Home Local - Client Server KDC KDC --------------- ------------- --------- --------- -DHCPDISCOVER -(Incomplete - AS_REQ) -> - AS_REQ -> - <- AS_REP - TGS_REQ -> - (cross realm, - for home - KDC) - - - -Hornstein, et al. Standards Track [Page 15] - - -INTERNET-DRAFT DHCP Authentication Via Kerberos V 20 February 2000 - - - <- TGS_REP - - TGS_REQ - U-2-U -> - <- TGS_REP - <- DHCPOFFER, - (AS_REP, - AP_REQ, - Integrity) -DHCPREQUEST - (Integrity) -> - <- DHCPACK - (Integrity) - -In the case where the client includes PADATA in the AS_REQ attribute -within the authentication option of the DHCPDISCOVER and the KDC returns -an error-free AS_REP indicating successful validation of the PADATA, the -DHCP server will conclude that the DHCP client is authentic. If the KDC -then returns a KRB_ERROR in response to the TGS_REQ, indicating a fault -that lies with the DHCP server, the server MAY choose not to silently -discard the DHCPDISCOVER. Instead it MAY respond with a DHCPOFFER -including a KRB_ERROR attribute within the authentication option. The -client will then treat this as an unauthenticated DHCPOFFER. The -conversation will appear as follows: - - DHCP DHCP - Client Server KDC --------------- ------------- --------- -DHCPDISCOVER - (Incomplete - AS_REQ - w/PADATA) -> - AS_REQ -> - <- AS_REP - TGS_REQ - U-2-U -> - <- KRB_ERROR - <- DHCPOFFER, - (KRB_ERROR) -DHCPREQUEST -> - <- DHCPACK - -In the intra-realm case where the client included PADATA in the AS_REQ -attribute of the authentication option and the AS_REQ was successfully -validated by the KDC, the DHCP server will conclude that the DHCP client -is authentic. In this case if the client successfully validates the -integrity attribute in the DHCPOFFER, but the server does not validate -the integrity attribute in the client's DHCPREQUEST, the server MAY - - - -Hornstein, et al. Standards Track [Page 16] - - -INTERNET-DRAFT DHCP Authentication Via Kerberos V 20 February 2000 - - -choose to respond with an authenticated DHCPNAK containing a KRB_ERROR -attribute. The conversation will appear as follows: - - DHCP DHCP - Client Server KDC --------------- ------------- --------- -DHCPDISCOVER - (Incomplete - AS_REQ - w/PADATA) -> - AS_REQ -> - <- AS_REP - TGS_REQ - U-2-U -> - <- TGS_REP - <- DHCPOFFER, - (AS_REP, - AP_REQ, - Integrity) -DHCPREQUEST - (Integrity) -> - <- DHCNAK - (KRB_ERROR, - Integrity) -DHCPDISCOVER - (Incomplete - AS_REQ) -> - -In the intra-realm case where the DHCP client cannot validate the -integrity attribute in the DHCPOFFER, the client silently discards the -DHCPOFFER. The conversation will appear as follows: - - DHCP DHCP - Client Server KDC --------------- ------------- --------- -DHCPDISCOVER - (Incomplete - AS_REQ) -> - AS_REQ -> - <- AS_REP - TGS_REQ - U-2-U -> - <- TGS_REP - <- DHCPOFFER, - (AS_REP, - AP_REQ, - Integrity) -DHCPREQUEST - - - -Hornstein, et al. Standards Track [Page 17] - - -INTERNET-DRAFT DHCP Authentication Via Kerberos V 20 February 2000 - - - [To another server] - (Integrity) -> - -In the intra-realm case where the DHCP client cannot validate the -integrity attribute in the DHCPACK, the client reverts to INIT state. -The conversation will appear as follows: - - DHCP DHCP - Client Server KDC --------------- ------------- --------- -DHCPDISCOVER -(Incomplete - AS_REQ) -> - AS_REQ -> - <- AS_REP - TGS_REQ - U-2-U -> - <- TGS_REP - <- DHCPOFFER, - (AS_REP, - AP_REQ, - Integrity) -DHCPREQUEST - (Integrity) -> - <- DHCPACK - (Integrity) -DHCPDISCOVER - (Incomplete - AS_REQ) -> - -4.6.2. INIT-REBOOT, RENEWING or REBINDING - -In the intra-realm or inter-realm case where the original user-to-user -ticket is still valid, and the DHCP server still has a valid TGT to the -home realm, the conversation will appear as follows: - - DHCP DHCP Home - Client Server KDC --------------- ------------- --------- - -DHCPREQUEST - (TGT, - Integrity) -> - TGS_REQ - U-2-U -> - <- TGS_REP - <- DHCPACK - (AP_REQ, - - - -Hornstein, et al. Standards Track [Page 18] - - -INTERNET-DRAFT DHCP Authentication Via Kerberos V 20 February 2000 - - - Integrity) - -In the intra-realm or inter-realm case where the DHCP server validates -the integrity attribute in the DHCPREQUEST, but receives a KRB_ERROR in -response to the TGS_REQ to the KDC, the DHCP sever MAY choose not to -silently discard the DHCPREQUEST and MAY return an authenticated DHCPNAK -to the client instead, using the user-to-user session key previously -established with the client. The conversation appears as follows: - - DHCP DHCP Home - Client Server KDC --------------- ------------- --------- - -DHCPREQUEST - (TGT, - Integrity) -> - TGS_REQ - U-2-U -> - <- KRB_ERROR - <- DHCPNAK - (KRB_ERROR, - Integrity) -DHCPDISCOVER - (Incomplete - AS_REQ) -> - -In the intra-realm or inter-realm case where the DHCP server cannot -validate the integrity attribute in the DHCPREQUEST, the DHCP server -MUST silently discard the DHCPREQUEST and the conversation will appear -as follows: - - DHCP DHCP - Client Server KDC --------------- ------------- --------- - -DHCPREQUEST - (TGT, - Integrity) -> - Silent discard -[Sequence repeats - until timeout] - -DHCPDISCOVER - (Incomplete - AS_REQ) -> - -In the intra-realm or inter-realm case where the original user-to-user -ticket is still valid, the server validates the integrity attribute in - - - -Hornstein, et al. Standards Track [Page 19] - - -INTERNET-DRAFT DHCP Authentication Via Kerberos V 20 February 2000 - - -the DHCPREQUEST, but the client fails to validate the integrity -attribute in the DHCPACK, the client will silently discard the DHCPACK. -The conversation will appear as follows: - - DHCP DHCP - Client Server KDC --------------- ------------- --------- - -DHCPREQUEST - (TGT, - Integrity) -> - - <- DHCPACK - (AP_REQ, - Integrity) -DHCPDISCOVER - (Incomplete - AS_REQ) -> - -4.6.3. DHCPINFORM (with known DHCP server) - -In the case where the DHCP client knows the DHCP server it will be -interacting with, the DHCP client will obtain a ticket to the DHCP -server and will include AP_REQ and integrity attributes within the -DHCPINFORM. - -Where the DHCP Kerberos mutual authentication is successful, the -conversation will appear as follows: - - DHCP DHCP - Client Server KDC --------------- ------------- --------- -AS_REQ -> - <- AS_REP -TGS_REQ -> - <- TGS_REP -DHCPINFORM - (AP_REQ, - Integrity) -> - <- DHCPACK - (Integrity) - -In the inter-realm case where the DHCP Kerberos mutual authentication is -successful, the conversation will appear as follows: - - DHCP DHCP Home Local - Client Server KDC KDC --------------- ------------- --------- --------- - - - -Hornstein, et al. Standards Track [Page 20] - - -INTERNET-DRAFT DHCP Authentication Via Kerberos V 20 February 2000 - - -AS_REQ -> - <- AS_REP -TGS_REQ -> - <- TGS_REP -TGS_REQ -> - <- TGS_REP -DHCPINFORM - (AP_REQ, - Integrity) -> - <- DHCPACK - (Integrity) - -In the inter-realm case where the DHCP server fails to validate the -integrity attribute in the DHCPINFORM, the server MUST silently discard -the DHCPINFORM. The conversation will appear as follows: - - DHCP DHCP Home Local - Client Server KDC KDC --------------- ------------- --------- --------- -AS_REQ -> - <- AS_REP -TGS_REQ -> - <- TGS_REP -TGS_REQ -> - <- TGS_REP -DHCPINFORM - (AP_REQ, - Integrity) -> - <- DHCPACK - (Integrity) -DHCPINFORM - (AP_REQ, - Integrity) -> - -In the inter-realm case where the DHCP client fails to validate the -integrity attribute in the DHCPACK, the client MUST silently discard the -DHCPACK. The conversation will appear as follows: - - DHCP DHCP Home Local - Client Server KDC KDC --------------- ------------- --------- --------- -AS_REQ -> - <- AS_REP -TGS_REQ -> - <- TGS_REP -TGS_REQ -> - <- TGS_REP -DHCPINFORM - - - -Hornstein, et al. Standards Track [Page 21] - - -INTERNET-DRAFT DHCP Authentication Via Kerberos V 20 February 2000 - - - (AP_REQ, - Integrity) -> - -4.6.4. DHCPINFORM (with unknown DHCP server) - -In the case where the DHCP client does not know the DHCP server it will -be interacting with, the DHCP client will only include a ticket -attribute within the DHCPINFORM. Thus the DHCP server will not be able -to validate the authentication option. - -Where the DHCP client is able to validate the DHCPACK and no error -occur, the onversation will appear as follows: - - DHCP DHCP - Client Server KDC --------------- ------------- --------- -AS_REQ -> - <- AS_REP -DHCPINFORM - (Ticket) -> - TGS_REQ - U-2-U -> - <- TGS_REP - <- DHCPACK - (AP_REQ, - Integrity) - -In the inter-realm case where the DHCP server needs to obtain a TGT to -the home realm, and where the client successfully validates the DHCPACK, -the conversation will appear as follows: - - DHCP DHCP Home Local - Client Server KDC KDC --------------- ------------- --------- --------- -AS_REQ -> - <- AS_REP -DHCPINFORM - (Ticket) -> - AS_REQ -> - <- AS_REP - TGS_REQ -> - (cross realm, - for home - KDC) - <- TGS_REP - - TGS_REQ - U-2-U -> - - - -Hornstein, et al. Standards Track [Page 22] - - -INTERNET-DRAFT DHCP Authentication Via Kerberos V 20 February 2000 - - - <- TGS_REP - <- DHCPACK - (AP_REQ, - Integrity) - -In the inter-realm case where the local KDC returns a KRB_ERROR in -response to the TGS_REQ from the DHCP server, the DHCP server MAY return -a KRB_ERROR within the DHCP authentication option included in a DHCPNAK. -The conversation will appear as follows: - - DHCP DHCP Home Local - Client Server KDC KDC --------------- ------------- --------- --------- -AS_REQ -> - <- AS_REP -DHCPINFORM - (Ticket) -> - AS_REQ -> - <- AS_REP - TGS_REQ -> - (cross realm, - for home - KDC) - <- KRB_ERROR - <- DHCPNAK - (KRB_ERROR) - - -In the inter-realm case where the DHCP client fails to validate the -integrity attribute in the DHCPACK, the client MUST silently discard the -DHCPACK. The conversation will appear as follows: - - DHCP DHCP Home Local - Client Server KDC KDC --------------- ------------- --------- --------- -AS_REQ -> - <- AS_REP -DHCPINFORM - (Ticket) -> - AS_REQ -> - <- AS_REP - TGS_REQ -> - (cross realm, - for home - KDC) - <- TGS_REP - - TGS_REQ - - - -Hornstein, et al. Standards Track [Page 23] - - -INTERNET-DRAFT DHCP Authentication Via Kerberos V 20 February 2000 - - - U-2-U -> - <- TGS_REP - <- DHCPACK - (AP_REQ, - Integrity) -DHCPINFORM - (Ticket) -> - -5. References - - -[1] Bradner, S., "Key words for use in RFCs to Indicate Requirement - Levels", BCP 14, RFC 2119, March 1997. - -[2] Kohl, J., Neuman, C., "The Kerberos Network Authentication Service - (V5)", RFC 1510, September 1993. - -[3] Droms, R., Arbaugh, W., "Authentication for DHCP Messages", - Internet draft (work in progress), draft-ietf-dhc- - authentication-11.txt, June 1999. - -[4] Droms, R., "Dynamic Host Configuration Protocol", RFC 2131, March - 1997. - -[5] Alexander, S., Droms, R., "DHCP Options and BOOTP Vendor - Extensions", RFC 2132, March 1997. - -[6] Perkins, C., "IP Mobility Support", RFC 2002, October 1996. - -[7] Jain, V., Congdon, P., Roese, J., "Network Port Authentication", - IEEE 802.1 PAR submission, June 1999. - -[8] Tung, B., Neuman, C., Hur, M., Medvinsky, A., Medvinsky, S., Wray, - J., Trostle, J., "Public Key Cryptography for Initial - Authentication in Kerberos", Internet draft (work in progress), - draft-ietf-cat-kerberos-pk-init-09.txt, June 1999. - -[9] Tung, B., Ryutov, T., Neuman, C., Tsudik, G., Sommerfeld, B., - Medvinsky, A., Hur, M., "Public Key Cryptography for Cross-Realm - Authentication in Kerberos", Internet draft (work in progress), - draft-ietf-cat-kerberos-pk-cross-04.txt, June 1999. - -[10] Mills, D., "Network Time Protocol (Version 3)", RFC-1305, March - 1992. - -[11] Henry, M., "DHCP Option 61 UUID Type Definition", Internet draft - (work in progress), draft-henry-DHCP-opt61-UUID-type-00.txt, - November 1998. - - - -Hornstein, et al. Standards Track [Page 24] - - -INTERNET-DRAFT DHCP Authentication Via Kerberos V 20 February 2000 - - -6. Security Considerations - -DHCP authentication, described in [3], addresses the following threats: - - Modification of messages - Rogue servers - Unauthorized clients - -This section describes how DHCP authentication via Kerberos V addresses -each of these threats. - -6.1. Client security - -As noted in [3], it may be desirable to ensure that IP addresses are -only allocated to authorized clients. This can serve to protect against -denial of service attacks. To address this issue it is necessary for -DHCP client messages to be authenticated. In order to guard against -message modification, it is also necessary for DHCP client messages to -be integrity protected. - -Note that this protocol does not make use of KRB_SAFE, so as to allow -modification of mutable fields by the DHCP relay. Replay protection is -therefore provided within the DHCP authentication option itself. - -In DHCP authentication via Kerberos V the DHCP client will authenticate, -integrity and replay-protect the DHCPREQUEST, DHCPDECLINE and -DHCPRELEASE messages using a user-to-user session key obtained by the -DHCP server from the home KDC. If the DHCP client knows the DHCP server -it will be interacting with, then the DHCP client MAY also authenticate, -integrity and replay-protect the DHCPINFORM message using a session key -obtained from the local realm KDC for the DHCP server it expects to -converse with. - -Since the client has not yet obtained a session key, DHCPDISCOVER -packets cannot be authenticated using the session key. However, the -client MAY include pre-authentication data in the PADATA field included -in the DHCPDISCOVER packet. Since the PADATA will then be used by the -DHCP server to request a ticket on the client's behalf, the DHCP server -will learn from the AS_REP whether the PADATA was acceptable or not. -Therefore in this case, the DHCPDISCOVER will be authenticated but not -integrity protected. - -Where the DHCP client does not know the DHCP server it will be -interacting with ahead of time, the DHCPINFORM message will not be -authenticated, integrity or replay protected. - -Note that snooping of PADATA and TGTs on the wire may provide an -attacker with a means of mounting a dictionary attack, since these items - - - -Hornstein, et al. Standards Track [Page 25] - - -INTERNET-DRAFT DHCP Authentication Via Kerberos V 20 February 2000 - - -are typically encrypted with a key derived from the user's password. -Thus use of strong passwords and/or pre-authentication methods utilizing -strong cryptography (see [8]) are recommended. - -6.2. Network access control - -DHCP authentication has been proposed as a method of limiting access to -network media that are not physically secured such as wireless LANs and -ports in college residence halls. However, it is not particularly well -suited to this purpose since even if address allocation is denied an -inauthentic client may use a statically assigned IP address instead, or -may attempt to access the network using non-IP protocols. As a result, -other methods, described in [6]-[7], have been proposed for controlling -access to wireless media and switched LANs. - -6.3. Server security - -As noted in [3], it may be desirable to protect against rogue DHCP -servers put on the network either intentionally or by accident. To -address this issue it is necessary for DHCP server messages to be -authenticated. In order to guard against message modification, it is -also necessary for DHCP server messages to be integrity protected. -Replay protection is also provided within the DHCP authentication -option. - -All messages sent by the DHCP server are authenticated and integrity and -replaly protected using a session key. This includes the DHCPOFFER, -DHCPACK, and DHCPNAK messages. The session key is used to compute the -DHCP authentication option, which is verified by the client. - -In order to provide protection against rogue servers it is necessary to -prevent rogue servers from obtaining the credentials necessary to act as -a DHCP server. As noted in Section 4, the Kerberos principal name for -the DHCP server must be of type KRB_NT_SRV_HST with the service name -component equal to 'dhcp'. The client MUST validate that the DHCP server -principal name has the above format. This convention requires that the -administrator ensure that non-DHCP server principals do not have names -that match the above format. - -7. IANA Considerations - -This draft does not create any new number spaces for IANA -administration. - -8. Acknowledgements - -The authors would like to acknowledge Ralph Droms and William Arbaugh, -authors of the DHCP authentication draft [3]. This draft incorporates - - - -Hornstein, et al. Standards Track [Page 26] - - -INTERNET-DRAFT DHCP Authentication Via Kerberos V 20 February 2000 - - -material from their work; however, any mistakes in this document are -solely the responsibility of the authors. - -9. 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 - -Ted Lemon -Internet Engines, Inc. -950 Charter Street -Redwood City, CA 94063 - -Phone: +1 (650) 779 6031 -Email: mellon@iengines.net - -Bernard Aboba -Microsoft Corporation -One Microsoft Way -Redmond, WA 98052 - -Phone: +1 (425) 936-6605 -EMail: bernarda@microsoft.com - -Jonathan Trostle -170 W. Tasman Dr. -San Jose, CA 95134, U.S.A. - -Email: jtrostle@cisco.com -Phone: +1 (408) 527-6201 - - -10. Intellectual Property Statement - -The IETF takes no position regarding the validity or scope of any -intellectual property or other rights that might be claimed to pertain -to the implementation or use of the technology described in this -document or the extent to which any license under such rights might or -might not be available; neither does it represent that it has made any -effort to identify any such rights. Information on the IETF's -procedures with respect to rights in standards-track and standards- -related documentation can be found in BCP-11. Copies of claims of - - - -Hornstein, et al. Standards Track [Page 27] - - -INTERNET-DRAFT DHCP Authentication Via Kerberos V 20 February 2000 - - -rights made available for publication and any assurances of licenses to -be made available, or the result of an attempt made to obtain a general -license or permission for the use of such proprietary rights by -implementors or users of this specification can be obtained from the -IETF Secretariat. - -The IETF invites any interested party to bring to its attention any -copyrights, patents or patent applications, or other proprietary rights -which may cover technology that may be required to practice this -standard. Please address the information to the IETF Executive -Director. - -11. Full Copyright Statement - -Copyright (C) The Internet Society (2000). 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 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." - -12. Expiration Date - -This memo is filed as , and -expires October 1, 2000. - - - - - - - - - - - - -Hornstein, et al. Standards Track [Page 28] - - diff --git a/crypto/heimdal/doc/standardisation/draft-horowitz-key-derivation-01.txt b/crypto/heimdal/doc/standardisation/draft-horowitz-key-derivation-01.txt deleted file mode 100644 index 4dcff486b936..000000000000 --- a/crypto/heimdal/doc/standardisation/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/crypto/heimdal/doc/standardisation/draft-ietf-cat-gssv2-08.txt b/crypto/heimdal/doc/standardisation/draft-ietf-cat-gssv2-08.txt deleted file mode 100644 index ccba35eeb4ab..000000000000 --- a/crypto/heimdal/doc/standardisation/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/crypto/heimdal/doc/standardisation/draft-ietf-cat-gssv2-cbind-04.txt b/crypto/heimdal/doc/standardisation/draft-ietf-cat-gssv2-cbind-04.txt deleted file mode 100644 index 518f4c63d171..000000000000 --- a/crypto/heimdal/doc/standardisation/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/crypto/heimdal/doc/standardisation/draft-ietf-cat-iakerb-04.txt b/crypto/heimdal/doc/standardisation/draft-ietf-cat-iakerb-04.txt deleted file mode 100644 index 208d057f24c8..000000000000 --- a/crypto/heimdal/doc/standardisation/draft-ietf-cat-iakerb-04.txt +++ /dev/null @@ -1,301 +0,0 @@ -INTERNET-DRAFT Mike Swift -draft-ietf-cat-iakerb-04.txt Microsoft -Updates: RFC 1510 Jonathan Trostle -July 2000 Cisco Systems - - - Initial Authentication and Pass Through Authentication - Using Kerberos V5 and the GSS-API (IAKERB) - - -0. 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. - - This draft expires on January 31st, 2001. - - -1. Abstract - - This document defines an extension to the Kerberos protocol - specification (RFC 1510 [1]) and GSSAPI Kerberos mechanism (RFC - 1964 [2]) that enables a client to obtain Kerberos tickets for - services where: - - (1) The client knows its principal name and password, but not - its realm name (applicable in the situation where a user is already - on the network but needs to authenticate to an ISP, and the user - does not know his ISP realm name). - (2) The client is able to obtain the IP address of the service in - a realm which it wants to send a request to, but is otherwise unable - to locate or communicate with a KDC in the service realm or one of - the intermediate realms. (One example would be a dial up user who - does not have direct IP connectivity). - (3) The client does not know the realm name of the service. - - -2. Motivation - - When authenticating using Kerberos V5, clients obtain tickets from - a KDC and present them to services. This method of operation works - - well in many situations, but is not always applicable since it - requires the client to know its own realm, the realm of the target - service, the names of the KDC's, and to be able to connect to the - KDC's. - - This document defines an extension to the Kerberos protocol - specification (RFC 1510) [1] that enables a client to obtain - Kerberos tickets for services where: - - (1) The client knows its principal name and password, but not - its realm name (applicable in the situation where a user is already - on the network but needs to authenticate to an ISP, and the user - does not know his ISP realm name). - (2) The client is able to obtain the IP address of the service in - a realm which it wants to send a request to, but is otherwise unable - to locate or communicate with a KDC in the service realm or one of - the intermediate realms. (One example would be a dial up user who - does not have direct IP connectivity). - (3) The client does not know the realm name of the service. - - In this proposal, the client sends KDC request messages directly - to application servers if one of the above failure cases develops. - The application server acts as a proxy, forwarding messages back - and forth between the client and various KDC's (see Figure 1). - - - Client <---------> App Server <----------> KDC - proxies - - - Figure 1: IAKERB proxying - - - In the case where the client has sent a TGS_REQ message to the - application server without a realm name in the request, the - application server will forward an error message to the client - with its realm name in the e-data field of the error message. - The client will attempt to proceed using conventional Kerberos. - -3. When Clients Should Use IAKERB - - We list several, but possibly not all, cases where the client - should use IAKERB. In general, the existing Kerberos paradigm - where clients contact the KDC to obtain service tickets should - be preserved where possible. - - (a) AS_REQ cases: - - (i) The client is unable to locate the user's KDC or the KDC's - in the user's realm are not responding, or - (ii) The user has not entered a name which can be converted - into a realm name (and the realm name cannot be derived from - a certificate). - - (b) TGS_REQ cases: - - (i) the client determines that the KDC(s) in either an - intermediate realm or the service realm are not responding or - - the client is unable to locate a KDC, - - (ii) the client is not able to generate the application server - realm name. - - -4. GSSAPI Encapsulation - - The mechanism ID for IAKERB GSS-API Kerberos, in accordance with the - mechanism proposed by SPNEGO for negotiating protocol variations, is: - {iso(1) member-body(2) United States(840) mit(113554) infosys(1) - gssapi(2) krb5(2) initialauth(4)} - - The AS request, AS reply, TGS request, and TGS reply messages are all - encapsulated using the format defined by RFC1964 [2]. This consists - of the GSS-API token framing defined in appendix B of RFC1508 [3]: - - 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 consists of a 2-byte TOK_ID field (defined - below), followed by the Kerberos V5 KRB-AS-REQ, KRB-AS-REP, - KRB-TGS-REQ, or KRB-TGS-REP messages, as appropriate. The TOK_ID field - shall be one of the following values, to denote that the message is - either a request to the KDC or a response from the KDC. - - Message TOK_ID - KRB-KDC-REQ 00 03 - KRB-KDC-REP 01 03 - - -5. The Protocol - - a. The user supplies a password (AS_REQ): Here the Kerberos client - will send an AS_REQ message to the application server if it cannot - locate a KDC for the user's realm, or such KDC's do not respond, - or the user does not enter a name from which the client can derive - the user's realm name. The client sets the realm field of the - request equal to its own realm if the realm name is known, - otherwise the realm length is set to 0. Upon receipt of the AS_REQ - message, the application server checks if the client has included - a realm. - - If the realm was not included in the original request, the - application server must determine the realm and add it to the - AS_REQ message before forwarding it. If the application server - cannot determine the client realm, it returns the - KRB_AP_ERR_REALM_REQUIRED error-code in an error message to - the client: - - KRB_AP_ERR_REALM_REQUIRED 77 - - The error message can be sent in response to either an AS_REQ - message, or in response to a TGS_REQ message, in which case the - realm and principal name of the application server are placed - into the realm and sname fields respectively, of the KRB-ERROR - message. In the AS_REQ case, once the realm is filled in, the - application server forwards the request to a KDC in the user's - realm. It will retry the request if necessary, and forward the - KDC response back to the client. - - At the time the user enters a username and password, the client - should create a new credential with an INTERNAL NAME [3] that can - be used as an input into the GSS_Acquire_cred function call. - - This functionality is useful when there is no trust relationship - between the user's logon realm and the target realm (Figure 2). - - - User Realm KDC - / - / - / - / 2,3 - 1,4 / - Client<-------------->App Server - - - 1 Client sends AS_REQ to App Server - 2 App server forwards AS_REQ to User Realm KDC - 3 App server receives AS_REP from User Realm KDC - 4 App server sends AS_REP back to Client - - - Figure 2: IAKERB AS_REQ - - - - b. The user does not supply a password (TGS_REQ): The user includes a - TGT targetted at the user's realm, or an intermediate realm, in a - TGS_REQ message. The TGS_REQ message is sent to the application - server. - - If the client has included the realm name in the TGS request, then - the application server will forward the request to a KDC in the - request TGT srealm. It will forward the response back to the client. - - If the client has not included the realm name in the TGS request, - then the application server will return its realm name and principal - name to the client using the KRB_AP_ERR_REALM_REQUIRED error - described above. Sending a TGS_REQ message to the application server - without a realm name in the request, followed by a TGS request using - the returned realm name and then sending an AP request with a mutual - authentication flag should be subject to a local policy decision - (see security considerations below). Using the returned server - principal name in a TGS request followed by sending an AP request - message using the received ticket MUST NOT set any mutual - authentication flags. - - -6. Addresses in Tickets - - In IAKERB, the machine sending requests to the KDC is the server and - not the client. As a result, the client should not include its - addresses in any KDC requests for two reasons. First, the KDC may - reject the forwarded request as being from the wrong client. Second, - in the case of initial authentication for a dial-up client, the client - machine may not yet possess a network address. Hence, as allowed by - RFC1510 [1], the addresses field of the AS and TGS requests should be - blank and the caddr field of the ticket should similarly be left blank. - - -7. Combining IAKERB with Other Kerberos Extensions - - This protocol is usable with other proposed Kerberos extensions such as - PKINIT (Public Key Cryptography for Initial Authentication in Kerberos - [4]). In such cases, the messages which would normally be sent to the - KDC by the GSS runtime are instead sent by the client application to the - server, which then forwards them to a KDC. - - -8. Security Considerations - - A principal is identified by its principal name and realm. A client - that sends a TGS request to an application server without the request - realm name will only be able to mutually authenticate the server - up to its principal name. Thus when requesting mutual authentication, - it is preferable if clients can either determine the server realm name - beforehand, or apply some policy checks to the realm name obtained from - the returned error message. - - -9. Bibliography - - [1] J. Kohl, C. Neuman. The Kerberos Network Authentication - Service (V5). Request for Comments 1510. - - [2] J. Linn. The Kerberos Version 5 GSS-API Mechanism. Request - for Comments 1964 - - [3] J. Linn. Generic Security Service Application Program Interface. - Request for Comments 1508 - - [4] B. Tung, C. Neuman, M. Hur, A. Medvinsky, S. Medvinsky, J. Wray, - J. Trostle, Public Key Cryptography for Initial Authentication in - Kerberos, http://www.ietf.org/internet-drafts/draft-ietf-cat-kerberos- - pkinit-10.txt. - - -10. This draft expires on January 31st, 2001. - - -11. Authors' Addresses - - Michael Swift - Microsoft - One Microsoft Way - Redmond, Washington, 98052, U.S.A. - Email: mikesw@microsoft.com - - Jonathan Trostle - 170 W. Tasman Dr. - San Jose, CA 95134, U.S.A. - Email: jtrostle@cisco.com - Phone: (408) 527-6201 diff --git a/crypto/heimdal/doc/standardisation/draft-ietf-cat-kerb-chg-password-02.txt b/crypto/heimdal/doc/standardisation/draft-ietf-cat-kerb-chg-password-02.txt deleted file mode 100644 index e235bec58c02..000000000000 --- a/crypto/heimdal/doc/standardisation/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/crypto/heimdal/doc/standardisation/draft-ietf-cat-kerb-des3-hmac-sha1-00.txt b/crypto/heimdal/doc/standardisation/draft-ietf-cat-kerb-des3-hmac-sha1-00.txt deleted file mode 100644 index 2583a84da0a4..000000000000 --- a/crypto/heimdal/doc/standardisation/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/crypto/heimdal/doc/standardisation/draft-ietf-cat-kerb-key-derivation-00.txt b/crypto/heimdal/doc/standardisation/draft-ietf-cat-kerb-key-derivation-00.txt deleted file mode 100644 index 46a415852706..000000000000 --- a/crypto/heimdal/doc/standardisation/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/crypto/heimdal/doc/standardisation/draft-ietf-cat-kerberos-err-msg-00.txt b/crypto/heimdal/doc/standardisation/draft-ietf-cat-kerberos-err-msg-00.txt deleted file mode 100644 index c5e4d05e7e3e..000000000000 --- a/crypto/heimdal/doc/standardisation/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/crypto/heimdal/doc/standardisation/draft-ietf-cat-kerberos-extra-tgt-02.txt b/crypto/heimdal/doc/standardisation/draft-ietf-cat-kerberos-extra-tgt-02.txt deleted file mode 100644 index b3ec336b6513..000000000000 --- a/crypto/heimdal/doc/standardisation/draft-ietf-cat-kerberos-extra-tgt-02.txt +++ /dev/null @@ -1,174 +0,0 @@ -INTERNET-DRAFT Jonathan Trostle -draft-ietf-cat-kerberos-extra-tgt-02.txt Cisco Systems -Updates: RFC 1510 Michael M. Swift -expires January 30, 2000 University of WA - - - Extension to Kerberos V5 For Additional Initial Encryption - -0. 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. - -1. Abstract - - This document defines an extension to the Kerberos protocol - specification (RFC 1510) [1] to enable a preauthentication field in - the AS_REQ message to carry a ticket granting ticket. The session - key from this ticket granting ticket will be used to - cryptographically strengthen the initial exchange in either the - conventional Kerberos V5 case or in the case the user stores their - encrypted private key on the KDC [2]. - - -2. Motivation - - In Kerberos V5, the initial exchange with the KDC consists of the - AS_REQ and AS_REP messages. For users, the encrypted part of the - AS_REP message is encrypted in a key derived from a password. - Although a password policy may be in place to prevent dictionary - attacks, brute force attacks may still be a concern due to - insufficient key length. - - This draft specifies an extension to the Kerberos V5 protocol to - allow a ticket granting ticket to be included in an AS_REQ message - preauthentication field. The session key from this ticket granting - ticket will be used to cryptographically strengthen the initial - - exchange in either the conventional Kerberos V5 case or in the case - the user stores their encrypted private key on the KDC [2]. The - session key from the ticket granting ticket is combined with the - user password key (key K2 in the encrypted private key on KDC - option) using HMAC to obtain a new triple des key that is used in - place of the user key in the initial exchange. The ticket granting - ticket could be obtained by the workstation using its host key. - -3. The Extension - - The following new preauthentication type is proposed: - - PA-EXTRA-TGT 22 - - The preauthentication-data field contains a ticket granting ticket - encoded as an ASN.1 octet string. The server realm of the ticket - granting ticket must be equal to the realm in the KDC-REQ-BODY of - the AS_REQ message. In the absence of a trust relationship, the - local Kerberos client should send the AS_REQ message without this - extension. - - In the conventional (non-pkinit) case, we require the RFC 1510 - PA-ENC-TIMESTAMP preauthentication field in the AS_REQ message. - If neither it or the PA-PK-KEY-REQ preauthentication field is - included in the AS_REQ message, the KDC will reply with a - KDC_ERR_PREAUTH_FAILED error message. - - We propose the following new etypes: - - des3-cbc-md5-xor 16 - des3-cbc-sha1-xor 17 - - The encryption key is obtained by: - - (1) Obtaining an output M from the HMAC-SHA1 function [3] using - the user password key (the key K2 in the encrypted private - key on KDC option of pkinit) as the text and the triple des - session key as the K input in HMAC: - - M = H(K XOR opad, H(K XOR ipad, text)) where H = SHA1. - - The session key from the accompanying ticket granting ticket - must be a triple des key when one of the triple des xor - encryption types is used. - (2) Concatenate the output M (20 bytes) with the first 8 non-parity - bits of the triple-des ticket granting ticket session key to - get 168 bits that will be used for the new triple-des encryption - key. - (3) Set the parity bits of the resulting key. - - The resulting triple des key is used to encrypt the timestamp - for the PA-ENC-TIMESTAMP preauthentication value (or in the - encrypted private key on KDC option of pkinit, it is used in - place of the key K2 to both sign in the PA-PK-KEY-REQ and for - encryption in the PA-PK-KEY-REP preauthentication types). - - If the KDC decrypts the encrypted timestamp and it is not within - the appropriate clock skew period, the KDC will reply with the - KDC_ERR_PREAUTH_FAILED error. The same error will also be sent if - the above ticket granting ticket fails to decrypt properly, or if - it is not a valid ticket. - - The KDC will create the shared triple des key from the ticket - granting ticket session key and the user password key (the key K2 - in the encrypted private key on KDC case) using HMAC as specified - above and use it to validate the AS_REQ message and then to - encrypt the encrypted part of the AS_REP message (use it in place - of the key K2 for encryption in the PA-PK-KEY-REP preauthentication - field). - - Local workstation policy will determine the exact behaviour of - the Kerberos client with respect to the extension protocol. For - example, the client should consult policy to decide when to use - use the extension. This policy could be dependent on the user - identity, or whether the workstation is in the same realm as the - user. One possibility is for the workstation logon to fail if - the extension is not used. Another possibility is for the KDC - to set a flag in tickets issued when this extension is used. - - A similar idea was proposed in OSF DCE RFC 26.0 [4]; there a - preauthentication field containing a ticket granting ticket, - a randomly generated subkey encrypted in the session key from - the ticket, and a timestamp structure encrypted in the user - password and then the randomly generated subkey was proposed. - Some advantages of the current proposal are that the KDC has two - fewer decryptions to perform per request and the client does not - have to generate a random key. - -4. Bibliography - - [1] J. Kohl, C. Neuman. The Kerberos Network Authentication - Service (V5). Request for Comments 1510. - - [2] B. Tung, C. Neuman, J. Wray, A. Medvinsky, M. Hur, J. Trostle. - Public Key Cryptography for Initial Authentication in Kerberos. - ftp://ds.internic.net/internet-drafts/ - draft-ietf-cat-kerberos-pkinit-08.txt - - [3] H. Krawczyk, M. Bellare, R. Canetti. HMAC: Keyed-Hashing for - Message Authentication. Request for Comments 2104. - - [4] J. Pato. Using Pre-authentication to Avoid Password Guessing - Attacks. OSF DCE SIG Request for Comments 26.0. - -5. Acknowledgement: We thank Ken Hornstein for some helpful comments. - -6. Expires January 30, 2000. - -7. Authors' Addresses - - Jonathan Trostle - 170 W. Tasman Dr. - San Jose, CA 95134, U.S.A. - - Email: jtrostle@cisco.com - Phone: (408) 527-6201 - - Michael Swift - Email: mikesw@cs.washington.edu diff --git a/crypto/heimdal/doc/standardisation/draft-ietf-cat-kerberos-extra-tgt-03.txt b/crypto/heimdal/doc/standardisation/draft-ietf-cat-kerberos-extra-tgt-03.txt deleted file mode 100644 index d09a2ded5bc5..000000000000 --- a/crypto/heimdal/doc/standardisation/draft-ietf-cat-kerberos-extra-tgt-03.txt +++ /dev/null @@ -1,5 +0,0 @@ -This Internet-Draft has expired and is no longer available. - -Unrevised documents placed in the Internet-Drafts directories have a -maximum life of six months. After that time, they must be updated, or -they will be deleted. This document was deleted on March 20, 2000. diff --git a/crypto/heimdal/doc/standardisation/draft-ietf-cat-kerberos-pk-cross-01.txt b/crypto/heimdal/doc/standardisation/draft-ietf-cat-kerberos-pk-cross-01.txt deleted file mode 100644 index 4b193c57390c..000000000000 --- a/crypto/heimdal/doc/standardisation/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/crypto/heimdal/doc/standardisation/draft-ietf-cat-kerberos-pk-cross-06.txt b/crypto/heimdal/doc/standardisation/draft-ietf-cat-kerberos-pk-cross-06.txt deleted file mode 100644 index 1ab2b03e079d..000000000000 --- a/crypto/heimdal/doc/standardisation/draft-ietf-cat-kerberos-pk-cross-06.txt +++ /dev/null @@ -1,523 +0,0 @@ - -INTERNET-DRAFT Matthew Hur -draft-ietf-cat-kerberos-pk-cross-06.txt CyberSafe Corporation -Updates: RFC 1510 Brian Tung -expires October 10, 2000 Tatyana Ryutov - Clifford Neuman - Gene Tsudik - ISI - Ari Medvinsky - Keen.com - Bill Sommerfeld - Hewlett-Packard - - - Public Key Cryptography for Cross-Realm Authentication in Kerberos - - -0. Status Of this Memo - - This document is an Internet-Draft and is in full conformance with - all provisions of Section 10 of RFC 2026. 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 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-pk-cross-06.txt, and expires May 15, 1999. - Please send comments to the authors. - - -1. Abstract - - This document defines extensions to the Kerberos protocol - specification [1] to provide a method for using public key - cryptography to enable 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. Introduction - - The Kerberos authentication protocol [2] can leverage the - advantages provided by public key cryptography. PKINIT [3] - describes the use of public key cryptography in the initial - authentication exchange in Kerberos. PKTAPP [4] describes how an - application service can essentially issue a kerberos ticket to - itself after utilizing public key cryptography for authentication. - Another informational document species the use of public key - crypography for anonymous authentication in Kerberos [5]. This - specification describes the use of public key crpytography in cross- - realm authentication. - - Without the use of public key cryptography, administrators must - maintain separate keys for every realm which wishes to exchange - authentication information with another realm (which implies n(n-1) - keys), or they must utilize a hierachichal arrangement of realms, - which may complicate the trust model by requiring evaluation of - transited realms. - - 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. - - PKCROSS utilizes a public key infrastructure (PKI) [6] to simplify - the administrative burden of maintaining cross-realm keys. Such - usage leverages a PKI for a non-centrally-administratable environment - (namely, inter-realm). Thus, a shared key for cross-realm - authentication can be established for a set period of time, and a - remote realm is able to issue policy information that is returned to - itself when a client requests cross-realm authentication. Such policy - information may be in the form of restrictions [7]. Furthermore, - these methods are transparent to the client; therefore, only the KDCs - need to be modified to use them. In this way, we take advantage of - the the distributed trust management capabilities of public key - crypography while maintaining the advantages of localized trust - management provided by Kerberos. - - - Although this specification utilizes the protocol specfied in the - PKINIT specification, it is not necessary to implement client - changes in order to make use of the changes in this document. - - -3. Objectives - - The objectives of this specification are as follows: - - 1. Simplify the administration required to establish Kerberos - cross-realm keys. - - 2. Avoid modification of clients and application servers. - - 3. Allow remote KDC to control its policy on cross-realm - keys shared between KDCs, and on cross-realm tickets - presented by clients. - - 4. Remove any need for KDCs to maintain state about keys - shared with other KDCs. - - 5. Leverage the work done for PKINIT to provide the public key - protocol for establishing symmetric cross realm keys. - - -4. Definitions - - The following notation is used throughout this specification: - KDC_l ........... local KDC - KDC_r ........... remote KDC - XTKT_(l,r) ...... PKCROSS ticket that the remote KDC issues to the - local KDC - TGT_(c,r) ....... cross-realm TGT that the local KDC issues to the - client for presentation to the remote KDC - - This specification defines the following new types to be added to the - Kerberos specification: - PKCROSS kdc-options field in the AS_REQ is bit 9 - TE-TYPE-PKCROSS-KDC 2 - TE-TYPE-PKCROSS-CLIENT 3 - - This specification defines the following ASN.1 type for conveying - policy information: - CrossRealmTktData ::= SEQUENCE OF TypedData - - This specification defines the following types for policy information - conveyed in CrossRealmTktData: - PLC_LIFETIME 1 - PLC_SET_TKT_FLAGS 2 - PLC_NOSET_TKT_FLAGS 3 - - TicketExtensions are defined per the Kerberos specification [8]: - TicketExtensions ::= SEQUENCE OF TypedData - Where - TypedData ::= SEQUENCE { - data-type[0] INTEGER, - data-value[1] OCTET STRING OPTIONAL - } - - -5. Protocol Specification - - We assume that the client has already obtained a TGT. To perform - cross-realm authentication, the client does exactly what it does - with ordinary (i.e. non-public-key-enabled) Kerberos; the only - changes are in the KDC; although the ticket which the client - forwards to the remote realm may be changed. This is acceptable - since the client treats the ticket as opaque. - - -5.1. Overview of Protocol - - The basic operation of the PKCROSS protocol is as follows: - - 1. The client submits a request to the local KDC for - credentials for the remote realm. This is just a typical - cross realm request that may occur with or without PKCROSS. - - 2. The local KDC submits a PKINIT request to the remote KDC to - obtain a "special" PKCROSS ticket. This is a standard - PKINIT request, except that PKCROSS flag (bit 9) is set in - the kdc-options field in the AS_REQ. - - 3. The remote KDC responds as per PKINIT, except that - the ticket contains a TicketExtension, which contains - policy information such as lifetime of cross realm tickets - issued by KDC_l to a client. The local KDC must reflect - this policy information in the credentials it forwards to - the client. Call this ticket XTKT_(l,r) to indicate that - this ticket is used to authenticate the local KDC to the - remote KDC. - - 4. The local KDC passes a ticket, TGT_(c,r) (the cross realm - TGT between the client and remote KDC), to the client. - This ticket contains in its TicketExtension field the - ticket, XTKT_(l,r), which contains the cross-realm key. - The TGT_(c,r) ticket is encrypted using the key sealed in - XTKT_(l,r). (The TicketExtension field is not encrypted.) - The local KDC may optionally include another TicketExtension - type that indicates the hostname and/or IP address for the - remote KDC. - - 5. The client submits the request directly to the remote - KDC, as before. - - 6. The remote KDC extracts XTKT_(l,r) from the TicketExtension - in order to decrypt the encrypted part of TGT_(c,r). - - -------------------------------------------------------------------- - - Client Local KDC (KDC_l) Remote KDC (KDC_r) - ------ ----------------- ------------------ - Normal Kerberos - request for - cross-realm - ticket for KDC_r - ----------------------> - - PKINIT request for - XTKT(l,r) - PKCROSS flag - set in the AS-REQ - * -------------------------> - - PKINIT reply with - XTKT_(l,r) and - policy info in - ticket extension - <-------------------------- * - - Normal Kerberos reply - with TGT_(c,r) and - XTKT(l,r) in ticket - extension - <--------------------------------- - - Normal Kerberos - cross-realm TGS-REQ - for remote - application - service with - TGT_(c,r) and - XTKT(l,r) in ticket - extension - -------------------------------------------------> - - Normal Kerberos - cross-realm - TGS-REP - <--------------------------------------------------------------- - - * Note that the KDC to KDC messages occur only periodically, since - the local KDC caches the XTKT_(l,r). - -------------------------------------------------------------------- - - - Sections 5.2 through 5.4 describe in detail steps 2 through 4 - above. Section 5.6 describes the conditions under which steps - 2 and 3 may be skipped. - - Note that the mechanism presented above requires infrequent KDC to - KDC communication (as dictated by policy - this is discussed - later). Without such an exchange, there are the following issues: - 1) KDC_l would have to issue a ticket with the expectation that - KDC_r will accept it. - 2) In the message that the client sends to KDC_r, KDC_l would have - to authenticate KDC_r with credentials that KDC_r trusts. - 3) There is no way for KDC_r to convey policy information to KDC_l. - 4) If, based on local policy, KDC_r does not accept a ticket from - KDC_l, then the client gets stuck in the middle. To address such - an issue would require modifications to standard client - processing behavior. - Therefore, the infreqeunt use of KDC to KDC communication assures - that inter-realm KDC keys may be established in accordance with local - policies and that clients may continue to operate without - modification. - - -5.2. Local KDC's Request to Remote KDC - - When the local KDC receives a request for cross-realm authentication, - it first checks its ticket cache to see if it has a valid PKCROSS - ticket, XTKT_(l,r). If it has a valid XTKT_(l,r), then it does not - need to send a request to the remote KDC (see section 5.5). - - If the local KDC does not have a valid XTKT_(l,r), it sends a - request to the remote KDC in order to establish a cross realm key and - obtain the XTKT_(l,r). This request is in fact a PKINIT request as - described in the PKINIT specification; i.e., it consists of an AS-REQ - with a PA-PK-AS-REQ included as a preauthentication field. Note, - that the AS-REQ MUST have the PKCROSS flag (bit 9) set in the - kdc_options field of the AS-REQ. Otherwise, this exchange exactly - follows the description given in the PKINIT specification. In - addition, the naming - - -5.3. Remote KDC's Response to Local KDC - - When the remote KDC receives the PKINIT/PKCROSS request from the - local KDC, it sends back a PKINIT response as described in - the PKINIT specification with the following exception: the encrypted - part of the Kerberos ticket is not encrypted with the krbtgt key; - instead, it is encrypted with the ticket granting server's PKCROSS - key. This key, rather than the krbtgt key, is used because it - encrypts a ticket used for verifying a cross realm request rather - than for issuing an application service ticket. Note that, as a - matter of policy, the session key for the XTKT_(l,r) MAY be of - greater strength than that of a session key for a normal PKINIT - reply, since the XTKT_(l,r) SHOULD be much longer lived than a - normal application service ticket. - - In addition, the remote KDC SHOULD include policy information in the - XTKT_(l,r). This policy information would then be reflected in the - cross-realm TGT, TGT_(c,r). Otherwise, the policy for TGT_(c,r) - would be dictated by KDC_l rather than by KDC_r. The local KDC MAY - enforce a more restrictive local policy when creating a cross-realm - ticket, TGT_(c,r). For example, KDC_r may dictate a lifetime - policy of eight hours, but KDC_l may create TKT_(c,r) with a - lifetime of four hours, as dictated by local policy. Also, the - remote KDC MAY include other information about itself along with the - PKCROSS ticket. These items are further discussed in section 6 - below. - - -5.4. Local KDC's Response to Client - - Upon receipt of the PKINIT/CROSS response from the remote KDC, - the local KDC formulates a response to the client. This reply - is constructed exactly as in the Kerberos specification, except - for the following: - - A) The local KDC places XTKT_(l,r) in the TicketExtension field of - the client's cross-realm, ticket, TGT_(c,r), for the remote realm. - Where - data-type equals 3 for TE-TYPE-PKCROSS-CLIENT - data-value is ASN.1 encoding of XTKT_(l,r) - - B) The local KDC adds the name of its CA to the transited field of - TGT_(c,r). - - -5.5 Remote KDC's Processing of Client Request - - When the remote KDC, KDC_r, receives a cross-realm ticket, - TGT_(c,r), and it detects that the ticket contains a ticket - extension of type TE-TYPE-PKCROSS-CLIENT, KDC_r must first decrypt - the ticket, XTKT_(l,r), that is encoded in the ticket extension. - KDC_r uses its PKCROSS key in order to decrypt XTKT_(l,r). KDC_r - then uses the key obtained from XTKT_(l,r) in order to decrypt the - cross-realm ticket, TGT_(c,r). - - KDC_r MUST verify that the cross-realm ticket, TGT_(c,r) is in - compliance with any policy information contained in XTKT_(l,r) (see - section 6). If the TGT_(c,r) is not in compliance with policy, then - the KDC_r responds to the client with a KRB-ERROR message of type - KDC_ERR_POLICY. - - -5.6. Short-Circuiting the KDC-to-KDC Exchange - - As we described earlier, the KDC to KDC exchange is required only - for establishing a symmetric, inter-realm key. Once this key is - established (via the PKINIT exchange), no KDC to KDC communication - is required until that key needs to be renewed. This section - describes the circumstances under which the KDC to KDC exchange - described in Sections 5.2 and 5.3 may be skipped. - - The local KDC has a known lifetime for TGT_(c,r). This lifetime may - be determined by policy information included in XTKT_(l,r), and/or - it may be determined by local KDC policy. If the local KDC already - has a ticket XTKT(l,r), and the start time plus the lifetime for - TGT_(c,r) does not exceed the expiration time for XTGT_(l,r), then - the local KDC may skip the exchange with the remote KDC, and issue a - cross-realm ticket to the client as described in Section 5.4. - - Since the remote KDC may change its PKCROSS key (referred to in - Section 5.2) while there are PKCROSS tickets still active, it SHOULD - cache the old PKCROSS keys until the last issued PKCROSS ticket - expires. Otherwise, the remote KDC will respond to a client with a - KRB-ERROR message of type KDC_ERR_TGT_REVOKED. - - -6. Extensions for the PKCROSS Ticket - - As stated in section 5.3, the remote KDC SHOULD include policy - information in XTKT_(l,r). This policy information is contained in - a TicketExtension, as defined by the Kerberos specification, and the - authorization data of the ticket will contain an authorization - record of type AD-IN-Ticket-Extensions. The TicketExtension defined - for use by PKCROSS is TE-TYPE-PKCROSS-KDC. - Where - data-type equals 2 for TE-TYPE-PKCROSS-KDC - data-value is ASN.1 encoding of CrossRealmTktData - - CrossRealmTktData ::= SEQUENCE OF TypedData - - - ------------------------------------------------------------------ - CrossRealmTktData types and the corresponding data are interpreted - as follows: - - ASN.1 data - type value interpretation encoding - ---------------- ----- -------------- ---------- - PLC_LIFETIME 1 lifetime (in seconds) INTEGER - for TGT_(c,r) - - cross-realm tickets - issued for clients by - TGT_l - - PLC_SET_TKT_FLAGS 2 TicketFlags that must BITSTRING - be set - - format defined by - Kerberos specification - - PLC_NOSET_TKT_FLAGS 3 TicketFlags that must BITSTRING - not be set - - format defined by - Kerberos specification - - Further types may be added to this table. - ------------------------------------------------------------------ - - -7. Usage of Certificates - - In the cases of PKINIT and PKCROSS, the trust in a certification - authority is equivalent to Kerberos cross realm trust. For this - reason, an implementation MAY choose to use the same KDC certificate - when the KDC is acting in any of the following three roles: - 1) KDC is authenticating clients via PKINIT - 2) KDC is authenticating another KDC for PKCROSS - 3) KDC is the client in a PKCROSS exchange with another KDC - - Note that per PKINIT, the KDC X.509 certificate (the server in a - PKINIT exchange) MUST contain the principal name of the KDC in the - subjectAltName field. - - -8. Transport Issues - - Because the messages between the KDCs involve PKINIT exchanges, and - PKINIT recommends TCP as a transport mechanism (due to the length of - the messages and the likelihood that they will fragment), the same - recommendation for TCP applies to PKCROSS as well. - - -9. Security Considerations - - Since PKCROSS utilizes PKINIT, it is subject to the same security - considerations as PKINIT. Administrators should assure adherence - to security policy - for example, this affects the PKCROSS policies - for cross realm key lifetime and for policy propogation from the - PKCROSS ticket, issued from a remote KDC to a local KDC, to - cross realm tickets that are issued by a local KDC to a client. - - -10. 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] B. Tung, C. Neuman, M. Hur, A. Medvinsky, S.Medvinsky, J. Wray - J. Trostle. Public Key Cryptography for Initial Authentication - in Kerberos. - draft-ietf-cat-kerberos-pk-init-11.txt - - [4] A. Medvinsky, M. Hur, S. Medvinsky, B. Clifford Neuman. Public - Key Utilizing Tickets for Application Servers (PKTAPP). draft-ietf- - cat-pktapp-02.txt - - [5] A. Medvinsky, J. Cargille, M. Hur. Anonymous Credentials in - Kerberos. draft-ietf-cat-kerberos-anoncred-01.txt - - [6] ITU-T (formerly CCITT) Information technology - Open Systems - Interconnection - The Directory: Authentication Framework - Recommendation X.509 ISO/IEC 9594-8 - - [7] B.C. Neuman, Proxy-Based Authorization and Accounting for - Distributed Systems. In Proceedings of the 13th International - Conference on Distributed Computing Systems, May 1993. - - [8] C.Neuman, J. Kohl, T. Ts'o. The Kerberos Network Authentication - Service (V5). draft-ietf-cat-kerberos-revisions-05.txt - - -11. Authors' Addresses - - Matthew Hur - CyberSafe Corporation - 1605 NW Sammamish Road - Issaquah WA 98027-5378 - Phone: +1 425 391 6000 - E-mail: matt.hur@cybersafe.com - - 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 - - Ari Medvinsky - Keen.com - 2480 Sand Hill Road, Suite 200 - Menlo Park, CA 94025 - Phone +1 650 289 3134 - E-mail: ari@keen.com - - Bill Sommerfeld - Hewlett Packard - 300 Apollo Drive - Chelmsford MA 01824 - Phone: +1 508 436 4352 - E-Mail: sommerfeld@apollo.hp.com - diff --git a/crypto/heimdal/doc/standardisation/draft-ietf-cat-kerberos-pk-init-03.txt b/crypto/heimdal/doc/standardisation/draft-ietf-cat-kerberos-pk-init-03.txt deleted file mode 100644 index d91c087dddf9..000000000000 --- a/crypto/heimdal/doc/standardisation/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/crypto/heimdal/doc/standardisation/draft-ietf-cat-kerberos-pk-init-11.txt b/crypto/heimdal/doc/standardisation/draft-ietf-cat-kerberos-pk-init-11.txt deleted file mode 100644 index 9b0e76adad98..000000000000 --- a/crypto/heimdal/doc/standardisation/draft-ietf-cat-kerberos-pk-init-11.txt +++ /dev/null @@ -1,1059 +0,0 @@ -INTERNET-DRAFT Brian Tung -draft-ietf-cat-kerberos-pk-init-11.txt Clifford Neuman -Updates: RFC 1510 USC/ISI -expires September 15, 2000 Matthew Hur - CyberSafe Corporation - Ari Medvinsky - Keen.com, Inc. - Sasha Medvinsky - Motorola - John Wray - Iris Associates, Inc. - Jonathan Trostle - Cisco - - Public Key Cryptography for Initial Authentication in Kerberos - -0. Status Of This Memo - - This document is an Internet-Draft and is in full conformance with - all provisions of Section 10 of RFC 2026. 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 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-pk-init-11.txt, and expires September 15, - 2000. 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 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. - - PKINIT utilizes ephemeral-ephemeral Diffie-Hellman keys in - combination with digital signature keys as the primary, required - mechanism. It also allows for the use of RSA keys and/or (static) - Diffie-Hellman certificates. Note in particular that PKINIT supports - the use of separate signature and encryption keys. - - PKINIT enables access to Kerberos-secured services based on initial - authentication utilizing public key cryptography. PKINIT utilizes - standard public key signature and encryption data formats within the - standard Kerberos messages. The basic mechanism is as follows: The - user sends an AS-REQ message to the KDC as before, except that if that - user is to use public key cryptography in the initial authentication - step, his certificate and a signature accompany 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 the encPart from the AS-REP message - carrying the TGT is now encrypted utilizing either a Diffie-Hellman - derived key or the user's public key. This message is authenticated - utilizing the public key signature of the KDC. - - Note that PKINIT does not require the use of certificates. A KDC - may store the public key of a principal as part of that principal's - record. In this scenario, the KDC is the trusted party that vouches - for the principal (as in a standard, non-cross realm, Kerberos - environment). Thus, for any principal, the KDC may maintain a - secret key, a public key, or both. - - The PKINIT specification may also be used as a building block for - other specifications. PKCROSS [3] utilizes PKINIT for establishing - the inter-realm key and associated inter-realm policy to be applied - in issuing cross realm service tickets. As specified in [4], - anonymous Kerberos tickets can be issued by applying a NULL - signature in combination with Diffie-Hellman in the PKINIT exchange. - Additionally, the PKINIT specification may be used for direct peer - to peer authentication without contacting a central KDC. This - application of PKINIT is described in PKTAPP [5] and is based on - concepts introduced in [6, 7]. 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 TLS [8] 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 [9]). - -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 change to RFC 1510 is 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. The user presents - a public key certificate and 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 describes the extensions for the initial authentication - method. - -3.1. Definitions - - The extensions involve new preauthentication fields; we introduce - the following preauthentication types: - - PA-PK-AS-REQ 14 - PA-PK-AS-REP 15 - - The extensions also involve new error types; we introduce the - following types: - - KDC_ERR_CLIENT_NOT_TRUSTED 62 - KDC_ERR_KDC_NOT_TRUSTED 63 - KDC_ERR_INVALID_SIG 64 - KDC_ERR_KEY_TOO_WEAK 65 - KDC_ERR_CERTIFICATE_MISMATCH 66 - KDC_ERR_CANT_VERIFY_CERTIFICATE 70 - KDC_ERR_INVALID_CERTIFICATE 71 - KDC_ERR_REVOKED_CERTIFICATE 72 - KDC_ERR_REVOCATION_STATUS_UNKNOWN 73 - KDC_ERR_REVOCATION_STATUS_UNAVAILABLE 74 - KDC_ERR_CLIENT_NAME_MISMATCH 75 - KDC_ERR_KDC_NAME_MISMATCH 76 - - We utilize the following typed data for errors: - - TD-PKINIT-CMS-CERTIFICATES 101 - TD-KRB-PRINCIPAL 102 - TD-KRB-REALM 103 - TD-TRUSTED-CERTIFIERS 104 - TD-CERTIFICATE-INDEX 105 - - We utilize the following encryption types (which map directly to - OIDs): - - dsaWithSHA1-CmsOID 9 - md5WithRSAEncryption-CmsOID 10 - sha1WithRSAEncryption-CmsOID 11 - rc2CBC-EnvOID 12 - rsaEncryption-EnvOID (PKCS#1 v1.5) 13 - rsaES-OAEP-ENV-OID (PKCS#1 v2.0) 14 - des-ede3-cbc-Env-OID 15 - - These mappings are provided so that a client may send the - appropriate enctypes in the AS-REQ message in order to indicate - support for the corresponding OIDs (for performing PKINIT). - - In many cases, PKINIT requires the encoding of the X.500 name of a - certificate authority as a Realm. When such a name appears as - a realm it will be represented using the "other" form of the realm - name as specified in the naming constraints section of RFC1510. - For a realm derived from an X.500 name, NAMETYPE will have the value - X500-RFC2253. The full realm name will appear as follows: - - + ":" + - - where nametype is "X500-RFC2253" and string is the result of doing - an RFC2253 encoding of the distinguished name, i.e. - - "X500-RFC2253:" + RFC2253Encode(DistinguishedName) - - where DistinguishedName is an X.500 name, and RFC2253Encode is a - function returing a readable UTF encoding of an X.500 name, as - defined by RFC 2253 [14] (part of LDAPv3 [18]). - - To ensure that this encoding is unique, we add the following rule - to those specified by RFC 2253: - - The order in which the attributes appear in the RFC 2253 - encoding must be the reverse of the order in the ASN.1 - encoding of the X.500 name that appears in the public key - certificate. The order of the relative distinguished names - (RDNs), as well as the order of the AttributeTypeAndValues - within each RDN, will be reversed. (This is despite the fact - that an RDN is defined as a SET of AttributeTypeAndValues, where - an order is normally not important.) - - Similarly, in cases where the KDC does not provide a specific - policy based mapping from the X.500 name or X.509 Version 3 - SubjectAltName extension in the user's certificate to a Kerberos - principal name, PKINIT requires the direct encoding of the X.500 - name as a PrincipalName. In this case, the name-type of the - principal name shall be set to KRB_NT-X500-PRINCIPAL. This new - name type is defined in RFC 1510 as: - - KRB_NT_X500_PRINCIPAL 6 - - The name-string shall be set as follows: - - RFC2253Encode(DistinguishedName) - - as described above. When this name type is used, the principal's - realm shall be set to the certificate authority's distinguished - name using the X500-RFC2253 realm name format described earlier in - this section - - RFC 1510 specifies the ASN.1 structure for PrincipalName as follows: - - PrincipalName ::= SEQUENCE { - name-type[0] INTEGER, - name-string[1] SEQUENCE OF GeneralString - } - - For the purposes of encoding an X.500 name as a Kerberos name for - use in Kerberos structures, the name-string shall be encoded as a - single GeneralString. The name-type should be KRB_NT_X500_PRINCIPAL, - as noted above. All Kerberos names must conform to validity - requirements as given in RFC 1510. Note that name mapping may be - required or optional, based on policy. - - We also define the following similar ASN.1 structure: - - CertPrincipalName ::= SEQUENCE { - name-type[0] INTEGER, - name-string[1] SEQUENCE OF UTF8String - } - - When a Kerberos PrincipalName is to be placed within an X.509 data - structure, the CertPrincipalName structure is to be used, with the - name-string encoded as a single UTF8String. The name-type should be - as identified in the original PrincipalName structure. The mapping - between the GeneralString and UTF8String formats can be found in - [19]. - - The following rules relate to the the matching of PrincipalNames (or - corresponding CertPrincipalNames) with regard to the PKI name - constraints for CAs as laid out in RFC 2459 [15]. In order to be - regarded as a match (for permitted and excluded name trees), the - following must be satisfied. - - 1. If the constraint is given as a user plus realm name, or - as a user plus instance plus realm name (as specified in - RFC 1510), the realm name must be valid (see 2.a-d below) - and the match must be exact, byte for byte. - - 2. If the constraint is given only as a realm name, matching - depends on the type of the realm: - - a. If the realm contains a colon (':') before any equal - sign ('='), it is treated as a realm of type Other, - and must match exactly, byte for byte. - - b. Otherwise, if the realm contains an equal sign, it - is treated as an X.500 name. In order to match, every - component in the constraint MUST be in the principal - name, and have the same value. For example, 'C=US' - matches 'C=US/O=ISI' but not 'C=UK'. - - c. Otherwise, if the realm name conforms to rules regarding - the format of DNS names, it is considered a realm name of - type Domain. The constraint may be given as a realm - name 'FOO.BAR', which matches any PrincipalName within - the realm 'FOO.BAR' but not those in subrealms such as - 'CAR.FOO.BAR'. A constraint of the form '.FOO.BAR' - matches PrincipalNames in subrealms of the form - 'CAR.FOO.BAR' but not the realm 'FOO.BAR' itself. - - d. Otherwise, the realm name is invalid and does not match - under any conditions. - -3.1.1. Encryption and Key Formats - - In the exposition below, we use the terms public key and private - key generically. It should be understood that the term "public - key" may be used to refer to either a public encryption key or a - signature verification key, and that the term "private key" may be - used to refer to either a private decryption key or a signature - generation key. The fact that these are logically distinct does - not preclude the assignment of bitwise identical keys for RSA - keys. - - In the case of Diffie-Hellman, the key shall be produced from the - agreed bit string as follows: - - * Truncate the bit string to the appropriate length. - * Rectify parity in each byte (if necessary) to obtain the key. - - For instance, in the case of a DES key, we take the first eight - bytes of the bit stream, and then adjust the least significant bit - of each byte to ensure that each byte has odd parity. - -3.1.2. Algorithm Identifiers - - PKINIT does not define, but does permit, the algorithm identifiers - listed below. - -3.1.2.1. Signature Algorithm Identifiers - - The following signature algorithm identifiers specified in [11] and - in [15] shall be used with PKINIT: - - id-dsa-with-sha1 (DSA with SHA1) - md5WithRSAEncryption (RSA with MD5) - sha-1WithRSAEncryption (RSA with SHA1) - -3.1.2.2 Diffie-Hellman Key Agreement Algorithm Identifier - - The following algorithm identifier shall be used within the - SubjectPublicKeyInfo data structure: dhpublicnumber - - This identifier and the associated algorithm parameters are - specified in RFC 2459 [15]. - -3.1.2.3. Algorithm Identifiers for RSA Encryption - - These algorithm identifiers are used inside the EnvelopedData data - structure, for encrypting the temporary key with a public key: - - rsaEncryption (RSA encryption, PKCS#1 v1.5) - id-RSAES-OAEP (RSA encryption, PKCS#1 v2.0) - - Both of the above RSA encryption schemes are specified in [16]. - Currently, only PKCS#1 v1.5 is specified by CMS [11], although the - CMS specification says that it will likely include PKCS#1 v2.0 in - the future. (PKCS#1 v2.0 addresses adaptive chosen ciphertext - vulnerability discovered in PKCS#1 v1.5.) - -3.1.2.4. Algorithm Identifiers for Encryption with Secret Keys - - These algorithm identifiers are used inside the EnvelopedData data - structure in the PKINIT Reply, for encrypting the reply key with the - temporary key: - des-ede3-cbc (3-key 3-DES, CBC mode) - rc2-cbc (RC2, CBC mode) - - The full definition of the above algorithm identifiers and their - corresponding parameters (an IV for block chaining) is provided in - the CMS specification [11]. - -3.2. Public Key Authentication - - Implementation of the changes in this section is REQUIRED for - compliance with PKINIT. - -3.2.1. Client Request - - Public keys may be signed by some certification authority (CA), or - they may be maintained by the KDC in which case the KDC is the - trusted authority. Note that the latter mode does not require the - use of certificates. - - The initial authentication request is sent as per RFC 1510, except - that a preauthentication field containing data signed by the user's - private key accompanies the request: - - PA-PK-AS-REQ ::= SEQUENCE { - -- PA TYPE 14 - signedAuthPack [0] SignedData - -- Defined in CMS [11]; - -- AuthPack (below) defines the - -- data that is signed. - trustedCertifiers [1] SEQUENCE OF TrustedCas OPTIONAL, - -- This is a list of CAs that the - -- client trusts and that certify - -- KDCs. - kdcCert [2] IssuerAndSerialNumber OPTIONAL - -- As defined in CMS [11]; - -- specifies a particular KDC - -- certificate if the client - -- already has it. - encryptionCert [3] IssuerAndSerialNumber OPTIONAL - -- For example, this may be the - -- client's Diffie-Hellman - -- certificate, or it may be the - -- client's RSA encryption - -- certificate. - } - - TrustedCas ::= CHOICE { - principalName [0] KerberosName, - -- as defined below - caName [1] Name - -- fully qualified X.500 name - -- as defined by X.509 - issuerAndSerial [2] IssuerAndSerialNumber - -- Since a CA may have a number of - -- certificates, only one of which - -- a client trusts - } - - Usage of SignedData: - - The SignedData data type is specified in the Cryptographic - Message Syntax, a product of the S/MIME working group of the - IETF. The following describes how to fill in the fields of - this data: - - 1. The encapContentInfo field must contain the PKAuthenticator - and, optionally, the client's Diffie Hellman public value. - - a. The eContentType field shall contain the OID value for - pkdata: iso (1) org (3) dod (6) internet (1) security (5) - kerberosv5 (2) pkinit (3) pkdata (1) - - b. The eContent field is data of the type AuthPack (below). - - 2. The signerInfos field contains the signature of AuthPack. - - 3. The Certificates field, when non-empty, contains the client's - certificate chain. If present, the KDC uses the public key - from the client's certificate to verify the signature in the - request. Note that the client may pass different certificate - chains that are used for signing or for encrypting. Thus, - the KDC may utilize a different client certificate for - signature verification than the one it uses to encrypt the - reply to the client. For example, the client may place a - Diffie-Hellman certificate in this field in order to convey - its static Diffie Hellman certificate to the KDC to enable - static-ephemeral Diffie-Hellman mode for the reply; in this - case, the client does NOT place its public value in the - AuthPack (defined below). As another example, the client may - place an RSA encryption certificate in this field. However, - there must always be (at least) a signature certificate. - - AuthPack ::= SEQUENCE { - pkAuthenticator [0] PKAuthenticator, - clientPublicValue [1] SubjectPublicKeyInfo OPTIONAL - -- if client is using Diffie-Hellman - -- (ephemeral-ephemeral only) - } - - PKAuthenticator ::= SEQUENCE { - kdcName [0] PrincipalName, - kdcRealm [1] Realm, - cusec [2] INTEGER, - -- for replay prevention as in RFC1510 - ctime [3] KerberosTime, - -- for replay prevention as in RFC1510 - nonce [4] INTEGER - } - - SubjectPublicKeyInfo ::= SEQUENCE { - algorithm AlgorithmIdentifier, - -- dhKeyAgreement - subjectPublicKey BIT STRING - -- for DH, equals - -- public exponent (INTEGER encoded - -- as payload of BIT STRING) - } -- as specified by the X.509 recommendation [10] - - AlgorithmIdentifier ::= SEQUENCE { - algorithm ALGORITHM.&id, - parameters ALGORITHM.&type - } -- as specified by the X.509 recommendation [10] - - If the client passes an issuer and serial number in the request, - the KDC is requested to use the referred-to certificate. If none - exists, then the KDC returns an error of type - KDC_ERR_CERTIFICATE_MISMATCH. It also returns this error if, on the - other hand, the client does not pass any trustedCertifiers, - believing that it has the KDC's certificate, but the KDC has more - than one certificate. The KDC should include information in the - KRB-ERROR message that indicates the KDC certificate(s) that a - client may utilize. This data is specified in the e-data, which - is defined in RFC 1510 revisions as a SEQUENCE of TypedData: - - TypedData ::= SEQUENCE { - data-type [0] INTEGER, - data-value [1] OCTET STRING, - } -- per Kerberos RFC 1510 revisions - - where: - data-type = TD-PKINIT-CMS-CERTIFICATES = 101 - data-value = CertificateSet // as specified by CMS [11] - - The PKAuthenticator carries information to foil replay attacks, and - to bind the request and response. The PKAuthenticator is signed - with the client's signature key. - -3.2.2. KDC Response - - 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 client's certificate chain contains no certificate signed by - a CA trusted by the KDC, then the KDC sends back an error message - of type KDC_ERR_CANT_VERIFY_CERTIFICATE. The accompanying e-data - is a SEQUENCE of one TypedData (with type TD-TRUSTED-CERTIFIERS=104) - whose data-value is an OCTET STRING which is the DER encoding of - - TrustedCertifiers ::= SEQUENCE OF PrincipalName - -- X.500 name encoded as a principal name - -- see Section 3.1 - - If while verifying a certificate chain the KDC determines that the - signature on one of the certificates in the CertificateSet from - the signedAuthPack fails verification, then the KDC returns an - error of type KDC_ERR_INVALID_CERTIFICATE. The accompanying - e-data is a SEQUENCE of one TypedData (with type - TD-CERTIFICATE-INDEX=105) whose data-value is an OCTET STRING - which is the DER encoding of the index into the CertificateSet - ordered as sent by the client. - - CertificateIndex ::= INTEGER - -- 0 = 1st certificate, - -- (in order of encoding) - -- 1 = 2nd certificate, etc - - The KDC may also check whether any of the certificates in the - client's chain has been revoked. If one of the certificates has - been revoked, then the KDC returns an error of type - KDC_ERR_REVOKED_CERTIFICATE; if such a query reveals that - the certificate's revocation status is unknown or not - available, then if required by policy, the KDC returns the - appropriate error of type KDC_ERR_REVOCATION_STATUS_UNKNOWN or - KDC_ERR_REVOCATION_STATUS_UNAVAILABLE. In any of these three - cases, the affected certificate is identified by the accompanying - e-data, which contains a CertificateIndex as described for - KDC_ERR_INVALID_CERTIFICATE. - - If the certificate chain can be verified, but the name of the - client in the certificate does not match the client's name in the - request, then the KDC returns an error of type - KDC_ERR_CLIENT_NAME_MISMATCH. There is no accompanying e-data - field in this case. - - Finally, if the certificate chain is verified, but the KDC's name - or realm as given in the PKAuthenticator does not match the KDC's - actual principal name, then the KDC returns an error of type - KDC_ERR_KDC_NAME_MISMATCH. The accompanying e-data field is again - a SEQUENCE of one TypedData (with type TD-KRB-PRINCIPAL=102 or - TD-KRB-REALM=103 as appropriate) whose data-value is an OCTET - STRING whose data-value is the DER encoding of a PrincipalName or - Realm as defined in RFC 1510 revisions. - - Even if all succeeds, the KDC may--for policy reasons--decide not - to trust the client. In this case, the KDC returns an error message - of type KDC_ERR_CLIENT_NOT_TRUSTED. One specific case of this is - the presence or absence of an Enhanced Key Usage (EKU) OID within - the certificate extensions. The rules regarding acceptability of - an EKU sequence (or the absence of any sequence) are a matter of - local policy. For the benefit of implementers, we define a PKINIT - EKU OID as the following: iso (1) org (3) dod (6) internet (1) - security (5) kerberosv5 (2) pkinit (3) pkekuoid (2). - - If a trust relationship exists, the KDC then verifies the client's - signature on AuthPack. If that fails, the KDC returns an error - message of type KDC_ERR_INVALID_SIG. Otherwise, the KDC uses the - timestamp (ctime and cusec) in the PKAuthenticator to assure that - the request is not a replay. The KDC also verifies that its name - is specified in the PKAuthenticator. - - If the clientPublicValue field is filled in, indicating that the - client wishes to use Diffie-Hellman key agreement, then the KDC - checks to see that the parameters satisfy its policy. If they do - not (e.g., the prime size is insufficient for the expected - encryption type), then the KDC sends back an error message of type - KDC_ERR_KEY_TOO_WEAK. Otherwise, it generates its own public and - private values for the response. - - The KDC also checks that the timestamp in the PKAuthenticator is - within the allowable window and that the principal name and realm - are correct. If the local (server) time and the client time in the - authenticator differ by more than the allowable clock skew, then the - KDC returns an error message of type KRB_AP_ERR_SKEW as defined in 1510. - - Assuming no errors, the KDC replies as per RFC 1510, except as - follows. The user's name in the ticket is determined by the - following decision algorithm: - - 1. If the KDC has a mapping from the name in the certificate - to a Kerberos name, then use that name. - Else - 2. If the certificate contains the SubjectAltName extention - and the local KDC policy defines a mapping from the - SubjectAltName to a Kerberos name, then use that name. - Else - 3. Use the name as represented in the certificate, mapping - mapping as necessary (e.g., as per RFC 2253 for X.500 - names). In this case the realm in the ticket shall be the - name of the certifier that issued the user's certificate. - - Note that a principal name may be carried in the subject alt name - field of a certificate. This name may be mapped to a principal - record in a security database based on local policy, for example - the subject alt name may be kerberos/principal@realm format. In - this case the realm name is not that of the CA but that of the - local realm doing the mapping (or some realm name chosen by that - realm). - - If a non-KDC X.509 certificate contains the principal name within - the subjectAltName version 3 extension , that name may utilize - KerberosName as defined below, or, in the case of an S/MIME - certificate [17], may utilize the email address. If the KDC - is presented with an S/MIME certificate, then the email address - within subjectAltName will be interpreted as a principal and realm - separated by the "@" sign, or as a name that needs to be - canonicalized. If the resulting name does not correspond to a - registered principal name, then the principal name is formed as - defined in section 3.1. - - 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. If the KDC has no - certificate signed by any of the trustedCertifiers, then it returns - an error of type KDC_ERR_KDC_NOT_TRUSTED. - - KDCs should try to (in order of preference): - 1. Use the KDC certificate identified by the serialNumber included - in the client's request. - 2. Use a certificate issued to the KDC by the client's CA (if in the - middle of a CA key roll-over, use the KDC cert issued under same - CA key as user cert used to verify request). - 3. Use a certificate issued to the KDC by one of the client's - trustedCertifier(s); - If the KDC is unable to comply with any of these options, then the - KDC returns an error message of type KDC_ERR_KDC_NOT_TRUSTED to the - client. - - The KDC encrypts the reply not with the user's long-term key, but - with the Diffie Hellman derived key or a random key generated - for this particular response which is carried in the padata field of - the TGS-REP message. - - PA-PK-AS-REP ::= CHOICE { - -- PA TYPE 15 - dhSignedData [0] SignedData, - -- Defined in CMS and used only with - -- Diffie-Hellman key exchange (if the - -- client public value was present in the - -- request). - -- This choice MUST be supported - -- by compliant implementations. - encKeyPack [1] EnvelopedData, - -- Defined in CMS - -- The temporary key is encrypted - -- using the client public key - -- key - -- SignedReplyKeyPack, encrypted - -- with the temporary key, is also - -- included. - } - - Usage of SignedData: - - When the Diffie-Hellman option is used, dhSignedData in - PA-PK-AS-REP provides authenticated Diffie-Hellman parameters - of the KDC. The reply key used to encrypt part of the KDC reply - message is derived from the Diffie-Hellman exchange: - - 1. Both the KDC and the client calculate a secret value - (g^ab mod p), where a is the client's private exponent and - b is the KDC's private exponent. - - 2. Both the KDC and the client take the first N bits of this - secret value and convert it into a reply key. N depends on - the reply key type. - - 3. If the reply key is DES, N=64 bits, where some of the bits - are replaced with parity bits, according to FIPS PUB 74. - - 4. If the reply key is (3-key) 3-DES, N=192 bits, where some - of the bits are replaced with parity bits, according to - FIPS PUB 74. - - 5. The encapContentInfo field must contain the KdcDHKeyInfo as - defined below. - - a. The eContentType field shall contain the OID value for - pkdata: iso (1) org (3) dod (6) internet (1) security (5) - kerberosv5 (2) pkinit (3) pkdata (1) - - b. The eContent field is data of the type KdcDHKeyInfo - (below). - - 6. The certificates field must contain the certificates - necessary for the client to establish trust in the KDC's - certificate based on the list of trusted certifiers sent by - the client in the PA-PK-AS-REQ. This field may be empty if - the client did not send to the KDC a list of trusted - certifiers (the trustedCertifiers field was empty, meaning - that the client already possesses the KDC's certificate). - - 7. The signerInfos field is a SET that must contain at least - one member, since it contains the actual signature. - - KdcDHKeyInfo ::= SEQUENCE { - -- used only when utilizing Diffie-Hellman - nonce [0] INTEGER, - -- binds responce to the request - subjectPublicKey [2] BIT STRING - -- Equals public exponent (g^a mod p) - -- INTEGER encoded as payload of - -- BIT STRING - } - - Usage of EnvelopedData: - - The EnvelopedData data type is specified in the Cryptographic - Message Syntax, a product of the S/MIME working group of the - IETF. It contains a temporary key encrypted with the PKINIT - client's public key. It also contains a signed and encrypted - reply key. - - 1. The originatorInfo field is not required, since that - information may be presented in the signedData structure - that is encrypted within the encryptedContentInfo field. - - 2. The optional unprotectedAttrs field is not required for - PKINIT. - - 3. The recipientInfos field is a SET which must contain exactly - one member of the KeyTransRecipientInfo type for encryption - with an RSA public key. - - a. The encryptedKey field (in KeyTransRecipientInfo) - contains the temporary key which is encrypted with the - PKINIT client's public key. - - 4. The encryptedContentInfo field contains the signed and - encrypted reply key. - - a. The contentType field shall contain the OID value for - id-signedData: iso (1) member-body (2) us (840) - rsadsi (113549) pkcs (1) pkcs7 (7) signedData (2) - - b. The encryptedContent field is encrypted data of the CMS - type signedData as specified below. - - i. The encapContentInfo field must contains the - ReplyKeyPack. - - * The eContentType field shall contain the OID value - for pkdata: iso (1) org (3) dod (6) internet (1) - security (5) kerberosv5 (2) pkinit (3) pkdata (1) - - * The eContent field is data of the type ReplyKeyPack - (below). - - ii. The certificates field must contain the certificates - necessary for the client to establish trust in the - KDC's certificate based on the list of trusted - certifiers sent by the client in the PA-PK-AS-REQ. - This field may be empty if the client did not send - to the KDC a list of trusted certifiers (the - trustedCertifiers field was empty, meaning that the - client already possesses the KDC's certificate). - - iii. The signerInfos field is a SET that must contain at - least one member, since it contains the actual - signature. - - ReplyKeyPack ::= SEQUENCE { - -- not used for Diffie-Hellman - replyKey [0] EncryptionKey, - -- used to encrypt main reply - -- ENCTYPE is at least as strong as - -- ENCTYPE of session key - nonce [1] INTEGER, - -- binds response to the request - -- must be same as the nonce - -- passed in the PKAuthenticator - } - - Since each certifier in the certification path of a user's - certificate is equivalent to a separate Kerberos realm, the name - of each certifier in the certificate chain must be added to the - transited field of the ticket. The format of these realm names is - defined in Section 3.1 of this document. If applicable, the - transit-policy-checked flag should be set in the issued ticket. - - The KDC's certificate(s) must bind the public key(s) of the KDC to - a name derivable from the name of the realm for that KDC. X.509 - certificates shall contain the principal name of the KDC - (defined in section 8.2 of RFC 1510) as the SubjectAltName version - 3 extension. Below is the definition of this version 3 extension, - as specified by the X.509 standard: - - subjectAltName EXTENSION ::= { - SYNTAX GeneralNames - IDENTIFIED BY id-ce-subjectAltName - } - - GeneralNames ::= SEQUENCE SIZE(1..MAX) OF GeneralName - - GeneralName ::= CHOICE { - otherName [0] OtherName, - ... - } - - OtherName ::= SEQUENCE { - type-id OBJECT IDENTIFIER, - value [0] EXPLICIT ANY DEFINED BY type-id - } - - For the purpose of specifying a Kerberos principal name, the value - in OtherName shall be a KerberosName as defined in RFC 1510, but with - the PrincipalName replaced by CertPrincipalName as mentioned in - Section 3.1: - - KerberosName ::= SEQUENCE { - realm [0] Realm, - principalName [1] CertPrincipalName -- defined above - } - - This specific syntax is identified within subjectAltName by setting - the type-id in OtherName to krb5PrincipalName, where (from the - Kerberos specification) we have - - krb5 OBJECT IDENTIFIER ::= { iso (1) - org (3) - dod (6) - internet (1) - security (5) - kerberosv5 (2) } - - krb5PrincipalName OBJECT IDENTIFIER ::= { krb5 2 } - - (This specification may also be used to specify a Kerberos name - within the user's certificate.) The KDC's certificate may be signed - directly by a CA, or there may be intermediaries if the server resides - within a large organization, or it may be unsigned if the client - indicates possession (and trust) of the KDC's certificate. - - 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. The client uses this - random key to decrypt the main reply, and subsequently proceeds as - described in RFC 1510. - -3.2.3. Required Algorithms - - Not all of the algorithms in the PKINIT protocol specification have - to be implemented in order to comply with the proposed standard. - Below is a list of the required algorithms: - - * Diffie-Hellman public/private key pairs - * utilizing Diffie-Hellman ephemeral-ephemeral mode - * SHA1 digest and DSA for signatures - * 3-key triple DES keys derived from the Diffie-Hellman Exchange - * 3-key triple DES Temporary and Reply keys - -4. Logistics and Policy - - This section describes a way to define the policy on the use of - PKINIT for each principal and request. - - The KDC is not required to contain a database record for users - who use public key authentication. However, if these users are - registered with the KDC, it is recommended that the database record - for these users be modified to an additional flag in the attributes - field to indicate that the user should authenticate using PKINIT. - If this flag is set and a request message does not contain the - PKINIT preauthentication field, then the KDC sends back as error of - type KDC_ERR_PREAUTH_REQUIRED indicating that a preauthentication - field of type PA-PK-AS-REQ must be included in the request. - -5. Security Considerations - - PKINIT raises a few security considerations, which we will address - in this section. - - First of all, PKINIT introduces a new trust model, where KDCs do not - (necessarily) certify the identity of those for whom they issue - tickets. PKINIT does allow KDCs to act as their own CAs, in the - limited capacity of self-signing their certificates, but one of the - additional benefits is to align Kerberos authentication with a global - public key infrastructure. Anyone using PKINIT in this way must be - aware of how the certification infrastructure they are linking to - works. - - Secondly, PKINIT also introduces the possibility of interactions - between different cryptosystems, which may be of widely varying - strengths. Many systems, for instance, allow the use of 512-bit - public keys. Using such keys to wrap data encrypted under strong - conventional cryptosystems, such as triple-DES, is inappropriate; - it adds a weak link to a strong one at extra cost. Implementors - and administrators should take care to avoid such wasteful and - deceptive interactions. - - Lastly, PKINIT calls for randomly generated keys for conventional - cryptosystems. Many such systems contain systematically "weak" - keys. PKINIT implementations MUST avoid use of these keys, either - by discarding those keys when they are generated, or by fixing them - in some way (e.g., by XORing them with a given mask). These - precautions vary from system to system; it is not our intention to - give an explicit recipe for them here. - -6. Transport Issues - - Certificate chains can potentially grow quite large and span several - UDP packets; this in turn increases the probability that a Kerberos - message involving PKINIT extensions will be broken in transit. In - light of the possibility that the Kerberos specification will - require KDCs to accept requests using TCP as a transport mechanism, - we make the same recommendation with respect to the PKINIT - extensions as well. - -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] B. Tung, T. Ryutov, C. Neuman, G. Tsudik, B. Sommerfeld, - A. Medvinsky, M. Hur. Public Key Cryptography for Cross-Realm - Authentication in Kerberos. draft-ietf-cat-kerberos-pk-cross-04.txt - - [4] A. Medvinsky, J. Cargille, M. Hur. Anonymous Credentials in - Kerberos. draft-ietf-cat-kerberos-anoncred-00.txt - - [5] Ari Medvinsky, M. Hur, Alexander Medvinsky, B. Clifford Neuman. - Public Key Utilizing Tickets for Application Servers (PKTAPP). - draft-ietf-cat-pktapp-02.txt - - [6] M. Sirbu, J. Chuang. Distributed Authentication in Kerberos - Using Public Key Cryptography. Symposium On Network and Distributed - System Security, 1997. - - [7] B. Cox, J.D. Tygar, M. Sirbu. NetBill Security and Transaction - Protocol. In Proceedings of the USENIX Workshop on Electronic - Commerce, July 1995. - - [8] T. Dierks, C. Allen. The TLS Protocol, Version 1.0 - Request for Comments 2246, January 1999. - - [9] B.C. Neuman, Proxy-Based Authorization and Accounting for - Distributed Systems. In Proceedings of the 13th International - Conference on Distributed Computing Systems, May 1993. - - [10] ITU-T (formerly CCITT) Information technology - Open Systems - Interconnection - The Directory: Authentication Framework - Recommendation X.509 ISO/IEC 9594-8 - - [11] R. Housley. Cryptographic Message Syntax. - draft-ietf-smime-cms-13.txt, April 1999, approved for publication - as RFC. - - [12] PKCS #7: Cryptographic Message Syntax Standard, - An RSA Laboratories Technical Note Version 1.5 - Revised November 1, 1993 - - [13] R. Rivest, MIT Laboratory for Computer Science and RSA Data - Security, Inc. A Description of the RC2(r) Encryption Algorithm - March 1998. - Request for Comments 2268. - - [14] M. Wahl, S. Kille, T. Howes. Lightweight Directory Access - Protocol (v3): UTF-8 String Representation of Distinguished Names. - Request for Comments 2253. - - [15] R. Housley, W. Ford, W. Polk, D. Solo. Internet X.509 Public - Key Infrastructure, Certificate and CRL Profile, January 1999. - Request for Comments 2459. - - [16] B. Kaliski, J. Staddon. PKCS #1: RSA Cryptography - Specifications, October 1998. Request for Comments 2437. - - [17] S. Dusse, P. Hoffman, B. Ramsdell, J. Weinstein. S/MIME - Version 2 Certificate Handling, March 1998. Request for - Comments 2312. - - [18] M. Wahl, T. Howes, S. Kille. Lightweight Directory Access - Protocol (v3), December 1997. Request for Comments 2251. - - [19] ITU-T (formerly CCITT) Information Processing Systems - Open - Systems Interconnection - Specification of Abstract Syntax Notation - One (ASN.1) Rec. X.680 ISO/IEC 8824-1 - -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 15, 2000. - -10. Authors - - Brian Tung - Clifford Neuman - USC Information Sciences Institute - 4676 Admiralty Way Suite 1001 - Marina del Rey CA 90292-6695 - Phone: +1 310 822 1511 - E-mail: {brian, bcn}@isi.edu - - Matthew Hur - CyberSafe Corporation - 1605 NW Sammamish Road - Issaquah WA 98027-5378 - Phone: +1 425 391 6000 - E-mail: matt.hur@cybersafe.com - - Ari Medvinsky - Keen.com, Inc. - 150 Independence Drive - Menlo Park CA 94025 - Phone: +1 650 289 3134 - E-mail: ari@keen.com - - Sasha Medvinsky - Motorola - 6450 Sequence Drive - San Diego, CA 92121 - Phone +1 619 404 2825 - E-mail: smedvinsky@gi.com - - John Wray - Iris Associates, Inc. - 5 Technology Park Dr. - Westford, MA 01886 - E-mail: John_Wray@iris.com - - Jonathan Trostle - 170 W. Tasman Dr. - San Jose, CA 95134 - E-mail: jtrostle@cisco.com diff --git a/crypto/heimdal/doc/standardisation/draft-ietf-cat-kerberos-pk-init-12.txt b/crypto/heimdal/doc/standardisation/draft-ietf-cat-kerberos-pk-init-12.txt deleted file mode 100644 index b1e596836eb8..000000000000 --- a/crypto/heimdal/doc/standardisation/draft-ietf-cat-kerberos-pk-init-12.txt +++ /dev/null @@ -1,1080 +0,0 @@ -INTERNET-DRAFT Brian Tung -draft-ietf-cat-kerberos-pk-init-12.txt Clifford Neuman -Updates: RFC 1510 USC/ISI -expires January 15, 2001 Matthew Hur - CyberSafe Corporation - Ari Medvinsky - Keen.com, Inc. - Sasha Medvinsky - Motorola - John Wray - Iris Associates, Inc. - Jonathan Trostle - Cisco - - Public Key Cryptography for Initial Authentication in Kerberos - -0. Status Of This Memo - - This document is an Internet-Draft and is in full conformance with - all provisions of Section 10 of RFC 2026. 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 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-pk-init-11.txt, and expires January 15, - 2001. 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 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. - - PKINIT utilizes ephemeral-ephemeral Diffie-Hellman keys in - combination with digital signature keys as the primary, required - mechanism. It also allows for the use of RSA keys and/or (static) - Diffie-Hellman certificates. Note in particular that PKINIT supports - the use of separate signature and encryption keys. - - PKINIT enables access to Kerberos-secured services based on initial - authentication utilizing public key cryptography. PKINIT utilizes - standard public key signature and encryption data formats within the - standard Kerberos messages. The basic mechanism is as follows: The - user sends an AS-REQ message to the KDC as before, except that if that - user is to use public key cryptography in the initial authentication - step, his certificate and a signature accompany 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 the encPart from the AS-REP message - carrying the TGT is now encrypted utilizing either a Diffie-Hellman - derived key or the user's public key. This message is authenticated - utilizing the public key signature of the KDC. - - Note that PKINIT does not require the use of certificates. A KDC - may store the public key of a principal as part of that principal's - record. In this scenario, the KDC is the trusted party that vouches - for the principal (as in a standard, non-cross realm, Kerberos - environment). Thus, for any principal, the KDC may maintain a - secret key, a public key, or both. - - The PKINIT specification may also be used as a building block for - other specifications. PKCROSS [3] utilizes PKINIT for establishing - the inter-realm key and associated inter-realm policy to be applied - in issuing cross realm service tickets. As specified in [4], - anonymous Kerberos tickets can be issued by applying a NULL - signature in combination with Diffie-Hellman in the PKINIT exchange. - Additionally, the PKINIT specification may be used for direct peer - to peer authentication without contacting a central KDC. This - application of PKINIT is described in PKTAPP [5] and is based on - concepts introduced in [6, 7]. 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 TLS [8] 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 [9]). - -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 change to RFC 1510 is 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. The user presents - a public key certificate and 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 describes the extensions for the initial authentication - method. - -3.1. Definitions - - The extensions involve new preauthentication fields; we introduce - the following preauthentication types: - - PA-PK-AS-REQ 14 - PA-PK-AS-REP 15 - - The extensions also involve new error types; we introduce the - following types: - - KDC_ERR_CLIENT_NOT_TRUSTED 62 - KDC_ERR_KDC_NOT_TRUSTED 63 - KDC_ERR_INVALID_SIG 64 - KDC_ERR_KEY_TOO_WEAK 65 - KDC_ERR_CERTIFICATE_MISMATCH 66 - KDC_ERR_CANT_VERIFY_CERTIFICATE 70 - KDC_ERR_INVALID_CERTIFICATE 71 - KDC_ERR_REVOKED_CERTIFICATE 72 - KDC_ERR_REVOCATION_STATUS_UNKNOWN 73 - KDC_ERR_REVOCATION_STATUS_UNAVAILABLE 74 - KDC_ERR_CLIENT_NAME_MISMATCH 75 - KDC_ERR_KDC_NAME_MISMATCH 76 - - We utilize the following typed data for errors: - - TD-PKINIT-CMS-CERTIFICATES 101 - TD-KRB-PRINCIPAL 102 - TD-KRB-REALM 103 - TD-TRUSTED-CERTIFIERS 104 - TD-CERTIFICATE-INDEX 105 - - We utilize the following encryption types (which map directly to - OIDs): - - dsaWithSHA1-CmsOID 9 - md5WithRSAEncryption-CmsOID 10 - sha1WithRSAEncryption-CmsOID 11 - rc2CBC-EnvOID 12 - rsaEncryption-EnvOID (PKCS#1 v1.5) 13 - rsaES-OAEP-ENV-OID (PKCS#1 v2.0) 14 - des-ede3-cbc-Env-OID 15 - - These mappings are provided so that a client may send the - appropriate enctypes in the AS-REQ message in order to indicate - support for the corresponding OIDs (for performing PKINIT). - - In many cases, PKINIT requires the encoding of the X.500 name of a - certificate authority as a Realm. When such a name appears as - a realm it will be represented using the "other" form of the realm - name as specified in the naming constraints section of RFC1510. - For a realm derived from an X.500 name, NAMETYPE will have the value - X500-RFC2253. The full realm name will appear as follows: - - + ":" + - - where nametype is "X500-RFC2253" and string is the result of doing - an RFC2253 encoding of the distinguished name, i.e. - - "X500-RFC2253:" + RFC2253Encode(DistinguishedName) - - where DistinguishedName is an X.500 name, and RFC2253Encode is a - function returing a readable UTF encoding of an X.500 name, as - defined by RFC 2253 [14] (part of LDAPv3 [18]). - - To ensure that this encoding is unique, we add the following rule - to those specified by RFC 2253: - - The order in which the attributes appear in the RFC 2253 - encoding must be the reverse of the order in the ASN.1 - encoding of the X.500 name that appears in the public key - certificate. The order of the relative distinguished names - (RDNs), as well as the order of the AttributeTypeAndValues - within each RDN, will be reversed. (This is despite the fact - that an RDN is defined as a SET of AttributeTypeAndValues, where - an order is normally not important.) - - Similarly, in cases where the KDC does not provide a specific - policy based mapping from the X.500 name or X.509 Version 3 - SubjectAltName extension in the user's certificate to a Kerberos - principal name, PKINIT requires the direct encoding of the X.500 - name as a PrincipalName. In this case, the name-type of the - principal name shall be set to KRB_NT-X500-PRINCIPAL. This new - name type is defined in RFC 1510 as: - - KRB_NT_X500_PRINCIPAL 6 - - The name-string shall be set as follows: - - RFC2253Encode(DistinguishedName) - - as described above. When this name type is used, the principal's - realm shall be set to the certificate authority's distinguished - name using the X500-RFC2253 realm name format described earlier in - this section - - RFC 1510 specifies the ASN.1 structure for PrincipalName as follows: - - PrincipalName ::= SEQUENCE { - name-type[0] INTEGER, - name-string[1] SEQUENCE OF GeneralString - } - - For the purposes of encoding an X.500 name as a Kerberos name for - use in Kerberos structures, the name-string shall be encoded as a - single GeneralString. The name-type should be KRB_NT_X500_PRINCIPAL, - as noted above. All Kerberos names must conform to validity - requirements as given in RFC 1510. Note that name mapping may be - required or optional, based on policy. - - We also define the following similar ASN.1 structure: - - CertPrincipalName ::= SEQUENCE { - name-type[0] INTEGER, - name-string[1] SEQUENCE OF UTF8String - } - - When a Kerberos PrincipalName is to be placed within an X.509 data - structure, the CertPrincipalName structure is to be used, with the - name-string encoded as a single UTF8String. The name-type should be - as identified in the original PrincipalName structure. The mapping - between the GeneralString and UTF8String formats can be found in - [19]. - - The following rules relate to the the matching of PrincipalNames (or - corresponding CertPrincipalNames) with regard to the PKI name - constraints for CAs as laid out in RFC 2459 [15]. In order to be - regarded as a match (for permitted and excluded name trees), the - following must be satisfied. - - 1. If the constraint is given as a user plus realm name, or - as a user plus instance plus realm name (as specified in - RFC 1510), the realm name must be valid (see 2.a-d below) - and the match must be exact, byte for byte. - - 2. If the constraint is given only as a realm name, matching - depends on the type of the realm: - - a. If the realm contains a colon (':') before any equal - sign ('='), it is treated as a realm of type Other, - and must match exactly, byte for byte. - - b. Otherwise, if the realm contains an equal sign, it - is treated as an X.500 name. In order to match, every - component in the constraint MUST be in the principal - name, and have the same value. For example, 'C=US' - matches 'C=US/O=ISI' but not 'C=UK'. - - c. Otherwise, if the realm name conforms to rules regarding - the format of DNS names, it is considered a realm name of - type Domain. The constraint may be given as a realm - name 'FOO.BAR', which matches any PrincipalName within - the realm 'FOO.BAR' but not those in subrealms such as - 'CAR.FOO.BAR'. A constraint of the form '.FOO.BAR' - matches PrincipalNames in subrealms of the form - 'CAR.FOO.BAR' but not the realm 'FOO.BAR' itself. - - d. Otherwise, the realm name is invalid and does not match - under any conditions. - -3.1.1. Encryption and Key Formats - - In the exposition below, we use the terms public key and private - key generically. It should be understood that the term "public - key" may be used to refer to either a public encryption key or a - signature verification key, and that the term "private key" may be - used to refer to either a private decryption key or a signature - generation key. The fact that these are logically distinct does - not preclude the assignment of bitwise identical keys for RSA - keys. - - In the case of Diffie-Hellman, the key shall be produced from the - agreed bit string as follows: - - * Truncate the bit string to the appropriate length. - * Rectify parity in each byte (if necessary) to obtain the key. - - For instance, in the case of a DES key, we take the first eight - bytes of the bit stream, and then adjust the least significant bit - of each byte to ensure that each byte has odd parity. - -3.1.2. Algorithm Identifiers - - PKINIT does not define, but does permit, the algorithm identifiers - listed below. - -3.1.2.1. Signature Algorithm Identifiers - - The following signature algorithm identifiers specified in [11] and - in [15] shall be used with PKINIT: - - id-dsa-with-sha1 (DSA with SHA1) - md5WithRSAEncryption (RSA with MD5) - sha-1WithRSAEncryption (RSA with SHA1) - -3.1.2.2 Diffie-Hellman Key Agreement Algorithm Identifier - - The following algorithm identifier shall be used within the - SubjectPublicKeyInfo data structure: dhpublicnumber - - This identifier and the associated algorithm parameters are - specified in RFC 2459 [15]. - -3.1.2.3. Algorithm Identifiers for RSA Encryption - - These algorithm identifiers are used inside the EnvelopedData data - structure, for encrypting the temporary key with a public key: - - rsaEncryption (RSA encryption, PKCS#1 v1.5) - id-RSAES-OAEP (RSA encryption, PKCS#1 v2.0) - - Both of the above RSA encryption schemes are specified in [16]. - Currently, only PKCS#1 v1.5 is specified by CMS [11], although the - CMS specification says that it will likely include PKCS#1 v2.0 in - the future. (PKCS#1 v2.0 addresses adaptive chosen ciphertext - vulnerability discovered in PKCS#1 v1.5.) - -3.1.2.4. Algorithm Identifiers for Encryption with Secret Keys - - These algorithm identifiers are used inside the EnvelopedData data - structure in the PKINIT Reply, for encrypting the reply key with the - temporary key: - des-ede3-cbc (3-key 3-DES, CBC mode) - rc2-cbc (RC2, CBC mode) - - The full definition of the above algorithm identifiers and their - corresponding parameters (an IV for block chaining) is provided in - the CMS specification [11]. - -3.2. Public Key Authentication - - Implementation of the changes in this section is REQUIRED for - compliance with PKINIT. - -3.2.1. Client Request - - Public keys may be signed by some certification authority (CA), or - they may be maintained by the KDC in which case the KDC is the - trusted authority. Note that the latter mode does not require the - use of certificates. - - The initial authentication request is sent as per RFC 1510, except - that a preauthentication field containing data signed by the user's - private key accompanies the request: - - PA-PK-AS-REQ ::= SEQUENCE { - -- PA TYPE 14 - signedAuthPack [0] SignedData - -- Defined in CMS [11]; - -- AuthPack (below) defines the - -- data that is signed. - trustedCertifiers [1] SEQUENCE OF TrustedCas OPTIONAL, - -- This is a list of CAs that the - -- client trusts and that certify - -- KDCs. - kdcCert [2] IssuerAndSerialNumber OPTIONAL - -- As defined in CMS [11]; - -- specifies a particular KDC - -- certificate if the client - -- already has it. - encryptionCert [3] IssuerAndSerialNumber OPTIONAL - -- For example, this may be the - -- client's Diffie-Hellman - -- certificate, or it may be the - -- client's RSA encryption - -- certificate. - } - - TrustedCas ::= CHOICE { - principalName [0] KerberosName, - -- as defined below - caName [1] Name - -- fully qualified X.500 name - -- as defined by X.509 - issuerAndSerial [2] IssuerAndSerialNumber - -- Since a CA may have a number of - -- certificates, only one of which - -- a client trusts - } - - Usage of SignedData: - - The SignedData data type is specified in the Cryptographic - Message Syntax, a product of the S/MIME working group of the - IETF. The following describes how to fill in the fields of - this data: - - 1. The encapContentInfo field must contain the PKAuthenticator - and, optionally, the client's Diffie Hellman public value. - - a. The eContentType field shall contain the OID value for - pkauthdata: iso (1) org (3) dod (6) internet (1) - security (5) kerberosv5 (2) pkinit (3) pkauthdata (1) - - b. The eContent field is data of the type AuthPack (below). - - 2. The signerInfos field contains the signature of AuthPack. - - 3. The Certificates field, when non-empty, contains the client's - certificate chain. If present, the KDC uses the public key - from the client's certificate to verify the signature in the - request. Note that the client may pass different certificate - chains that are used for signing or for encrypting. Thus, - the KDC may utilize a different client certificate for - signature verification than the one it uses to encrypt the - reply to the client. For example, the client may place a - Diffie-Hellman certificate in this field in order to convey - its static Diffie Hellman certificate to the KDC to enable - static-ephemeral Diffie-Hellman mode for the reply; in this - case, the client does NOT place its public value in the - AuthPack (defined below). As another example, the client may - place an RSA encryption certificate in this field. However, - there must always be (at least) a signature certificate. - - AuthPack ::= SEQUENCE { - pkAuthenticator [0] PKAuthenticator, - clientPublicValue [1] SubjectPublicKeyInfo OPTIONAL - -- if client is using Diffie-Hellman - -- (ephemeral-ephemeral only) - } - - PKAuthenticator ::= SEQUENCE { - cusec [0] INTEGER, - -- for replay prevention as in RFC1510 - ctime [1] KerberosTime, - -- for replay prevention as in RFC1510 - nonce [2] INTEGER, - pachecksum [3] Checksum - -- Checksum over KDC-REQ-BODY - -- Defined by Kerberos spec - } - - SubjectPublicKeyInfo ::= SEQUENCE { - algorithm AlgorithmIdentifier, - -- dhKeyAgreement - subjectPublicKey BIT STRING - -- for DH, equals - -- public exponent (INTEGER encoded - -- as payload of BIT STRING) - } -- as specified by the X.509 recommendation [10] - - AlgorithmIdentifier ::= SEQUENCE { - algorithm OBJECT IDENTIFIER, - -- for dhKeyAgreement, this is - -- { iso (1) member-body (2) US (840) - -- rsadsi (113459) pkcs (1) 3 1 } - -- from PKCS #3 [20] - parameters ANY DEFINED by algorithm OPTIONAL - -- for dhKeyAgreement, this is - -- DHParameter - } -- as specified by the X.509 recommendation [10] - - DHParameter ::= SEQUENCE { - prime INTEGER, - -- p - base INTEGER, - -- g - privateValueLength INTEGER OPTIONAL - -- l - } -- as defined in PKCS #3 [20] - - If the client passes an issuer and serial number in the request, - the KDC is requested to use the referred-to certificate. If none - exists, then the KDC returns an error of type - KDC_ERR_CERTIFICATE_MISMATCH. It also returns this error if, on the - other hand, the client does not pass any trustedCertifiers, - believing that it has the KDC's certificate, but the KDC has more - than one certificate. The KDC should include information in the - KRB-ERROR message that indicates the KDC certificate(s) that a - client may utilize. This data is specified in the e-data, which - is defined in RFC 1510 revisions as a SEQUENCE of TypedData: - - TypedData ::= SEQUENCE { - data-type [0] INTEGER, - data-value [1] OCTET STRING, - } -- per Kerberos RFC 1510 revisions - - where: - data-type = TD-PKINIT-CMS-CERTIFICATES = 101 - data-value = CertificateSet // as specified by CMS [11] - - The PKAuthenticator carries information to foil replay attacks, to - bind the pre-authentication data to the KDC-REQ-BODY, and to bind the - request and response. The PKAuthenticator is signed with the client's - signature key. - -3.2.2. KDC Response - - 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 client's certificate chain contains no certificate signed by - a CA trusted by the KDC, then the KDC sends back an error message - of type KDC_ERR_CANT_VERIFY_CERTIFICATE. The accompanying e-data - is a SEQUENCE of one TypedData (with type TD-TRUSTED-CERTIFIERS=104) - whose data-value is an OCTET STRING which is the DER encoding of - - TrustedCertifiers ::= SEQUENCE OF PrincipalName - -- X.500 name encoded as a principal name - -- see Section 3.1 - - If while verifying a certificate chain the KDC determines that the - signature on one of the certificates in the CertificateSet from - the signedAuthPack fails verification, then the KDC returns an - error of type KDC_ERR_INVALID_CERTIFICATE. The accompanying - e-data is a SEQUENCE of one TypedData (with type - TD-CERTIFICATE-INDEX=105) whose data-value is an OCTET STRING - which is the DER encoding of the index into the CertificateSet - ordered as sent by the client. - - CertificateIndex ::= INTEGER - -- 0 = 1st certificate, - -- (in order of encoding) - -- 1 = 2nd certificate, etc - - The KDC may also check whether any of the certificates in the - client's chain has been revoked. If one of the certificates has - been revoked, then the KDC returns an error of type - KDC_ERR_REVOKED_CERTIFICATE; if such a query reveals that - the certificate's revocation status is unknown or not - available, then if required by policy, the KDC returns the - appropriate error of type KDC_ERR_REVOCATION_STATUS_UNKNOWN or - KDC_ERR_REVOCATION_STATUS_UNAVAILABLE. In any of these three - cases, the affected certificate is identified by the accompanying - e-data, which contains a CertificateIndex as described for - KDC_ERR_INVALID_CERTIFICATE. - - If the certificate chain can be verified, but the name of the - client in the certificate does not match the client's name in the - request, then the KDC returns an error of type - KDC_ERR_CLIENT_NAME_MISMATCH. There is no accompanying e-data - field in this case. - - Finally, if the certificate chain is verified, but the KDC's name - or realm as given in the PKAuthenticator does not match the KDC's - actual principal name, then the KDC returns an error of type - KDC_ERR_KDC_NAME_MISMATCH. The accompanying e-data field is again - a SEQUENCE of one TypedData (with type TD-KRB-PRINCIPAL=102 or - TD-KRB-REALM=103 as appropriate) whose data-value is an OCTET - STRING whose data-value is the DER encoding of a PrincipalName or - Realm as defined in RFC 1510 revisions. - - Even if all succeeds, the KDC may--for policy reasons--decide not - to trust the client. In this case, the KDC returns an error message - of type KDC_ERR_CLIENT_NOT_TRUSTED. One specific case of this is - the presence or absence of an Enhanced Key Usage (EKU) OID within - the certificate extensions. The rules regarding acceptability of - an EKU sequence (or the absence of any sequence) are a matter of - local policy. For the benefit of implementers, we define a PKINIT - EKU OID as the following: iso (1) org (3) dod (6) internet (1) - security (5) kerberosv5 (2) pkinit (3) pkekuoid (2). - - If a trust relationship exists, the KDC then verifies the client's - signature on AuthPack. If that fails, the KDC returns an error - message of type KDC_ERR_INVALID_SIG. Otherwise, the KDC uses the - timestamp (ctime and cusec) in the PKAuthenticator to assure that - the request is not a replay. The KDC also verifies that its name - is specified in the PKAuthenticator. - - If the clientPublicValue field is filled in, indicating that the - client wishes to use Diffie-Hellman key agreement, then the KDC - checks to see that the parameters satisfy its policy. If they do - not (e.g., the prime size is insufficient for the expected - encryption type), then the KDC sends back an error message of type - KDC_ERR_KEY_TOO_WEAK. Otherwise, it generates its own public and - private values for the response. - - The KDC also checks that the timestamp in the PKAuthenticator is - within the allowable window and that the principal name and realm - are correct. If the local (server) time and the client time in the - authenticator differ by more than the allowable clock skew, then the - KDC returns an error message of type KRB_AP_ERR_SKEW as defined in 1510. - - Assuming no errors, the KDC replies as per RFC 1510, except as - follows. The user's name in the ticket is determined by the - following decision algorithm: - - 1. If the KDC has a mapping from the name in the certificate - to a Kerberos name, then use that name. - Else - 2. If the certificate contains the SubjectAltName extention - and the local KDC policy defines a mapping from the - SubjectAltName to a Kerberos name, then use that name. - Else - 3. Use the name as represented in the certificate, mapping - mapping as necessary (e.g., as per RFC 2253 for X.500 - names). In this case the realm in the ticket shall be the - name of the certifier that issued the user's certificate. - - Note that a principal name may be carried in the subject alt name - field of a certificate. This name may be mapped to a principal - record in a security database based on local policy, for example - the subject alt name may be kerberos/principal@realm format. In - this case the realm name is not that of the CA but that of the - local realm doing the mapping (or some realm name chosen by that - realm). - - If a non-KDC X.509 certificate contains the principal name within - the subjectAltName version 3 extension , that name may utilize - KerberosName as defined below, or, in the case of an S/MIME - certificate [17], may utilize the email address. If the KDC - is presented with an S/MIME certificate, then the email address - within subjectAltName will be interpreted as a principal and realm - separated by the "@" sign, or as a name that needs to be - canonicalized. If the resulting name does not correspond to a - registered principal name, then the principal name is formed as - defined in section 3.1. - - 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. If the KDC has no - certificate signed by any of the trustedCertifiers, then it returns - an error of type KDC_ERR_KDC_NOT_TRUSTED. - - KDCs should try to (in order of preference): - 1. Use the KDC certificate identified by the serialNumber included - in the client's request. - 2. Use a certificate issued to the KDC by the client's CA (if in the - middle of a CA key roll-over, use the KDC cert issued under same - CA key as user cert used to verify request). - 3. Use a certificate issued to the KDC by one of the client's - trustedCertifier(s); - If the KDC is unable to comply with any of these options, then the - KDC returns an error message of type KDC_ERR_KDC_NOT_TRUSTED to the - client. - - The KDC encrypts the reply not with the user's long-term key, but - with the Diffie Hellman derived key or a random key generated - for this particular response which is carried in the padata field of - the TGS-REP message. - - PA-PK-AS-REP ::= CHOICE { - -- PA TYPE 15 - dhSignedData [0] SignedData, - -- Defined in CMS and used only with - -- Diffie-Hellman key exchange (if the - -- client public value was present in the - -- request). - -- This choice MUST be supported - -- by compliant implementations. - encKeyPack [1] EnvelopedData, - -- Defined in CMS - -- The temporary key is encrypted - -- using the client public key - -- key - -- SignedReplyKeyPack, encrypted - -- with the temporary key, is also - -- included. - } - - Usage of SignedData: - - When the Diffie-Hellman option is used, dhSignedData in - PA-PK-AS-REP provides authenticated Diffie-Hellman parameters - of the KDC. The reply key used to encrypt part of the KDC reply - message is derived from the Diffie-Hellman exchange: - - 1. Both the KDC and the client calculate a secret value - (g^ab mod p), where a is the client's private exponent and - b is the KDC's private exponent. - - 2. Both the KDC and the client take the first N bits of this - secret value and convert it into a reply key. N depends on - the reply key type. - - 3. If the reply key is DES, N=64 bits, where some of the bits - are replaced with parity bits, according to FIPS PUB 74. - - 4. If the reply key is (3-key) 3-DES, N=192 bits, where some - of the bits are replaced with parity bits, according to - FIPS PUB 74. - - 5. The encapContentInfo field must contain the KdcDHKeyInfo as - defined below. - - a. The eContentType field shall contain the OID value for - pkdhkeydata: iso (1) org (3) dod (6) internet (1) - security (5) kerberosv5 (2) pkinit (3) pkdhkeydata (2) - - b. The eContent field is data of the type KdcDHKeyInfo - (below). - - 6. The certificates field must contain the certificates - necessary for the client to establish trust in the KDC's - certificate based on the list of trusted certifiers sent by - the client in the PA-PK-AS-REQ. This field may be empty if - the client did not send to the KDC a list of trusted - certifiers (the trustedCertifiers field was empty, meaning - that the client already possesses the KDC's certificate). - - 7. The signerInfos field is a SET that must contain at least - one member, since it contains the actual signature. - - KdcDHKeyInfo ::= SEQUENCE { - -- used only when utilizing Diffie-Hellman - nonce [0] INTEGER, - -- binds responce to the request - subjectPublicKey [2] BIT STRING - -- Equals public exponent (g^a mod p) - -- INTEGER encoded as payload of - -- BIT STRING - } - - Usage of EnvelopedData: - - The EnvelopedData data type is specified in the Cryptographic - Message Syntax, a product of the S/MIME working group of the - IETF. It contains a temporary key encrypted with the PKINIT - client's public key. It also contains a signed and encrypted - reply key. - - 1. The originatorInfo field is not required, since that - information may be presented in the signedData structure - that is encrypted within the encryptedContentInfo field. - - 2. The optional unprotectedAttrs field is not required for - PKINIT. - - 3. The recipientInfos field is a SET which must contain exactly - one member of the KeyTransRecipientInfo type for encryption - with an RSA public key. - - a. The encryptedKey field (in KeyTransRecipientInfo) - contains the temporary key which is encrypted with the - PKINIT client's public key. - - 4. The encryptedContentInfo field contains the signed and - encrypted reply key. - - a. The contentType field shall contain the OID value for - id-signedData: iso (1) member-body (2) us (840) - rsadsi (113549) pkcs (1) pkcs7 (7) signedData (2) - - b. The encryptedContent field is encrypted data of the CMS - type signedData as specified below. - - i. The encapContentInfo field must contains the - ReplyKeyPack. - - * The eContentType field shall contain the OID value - for pkrkeydata: iso (1) org (3) dod (6) internet (1) - security (5) kerberosv5 (2) pkinit (3) pkrkeydata (3) - - * The eContent field is data of the type ReplyKeyPack - (below). - - ii. The certificates field must contain the certificates - necessary for the client to establish trust in the - KDC's certificate based on the list of trusted - certifiers sent by the client in the PA-PK-AS-REQ. - This field may be empty if the client did not send - to the KDC a list of trusted certifiers (the - trustedCertifiers field was empty, meaning that the - client already possesses the KDC's certificate). - - iii. The signerInfos field is a SET that must contain at - least one member, since it contains the actual - signature. - - ReplyKeyPack ::= SEQUENCE { - -- not used for Diffie-Hellman - replyKey [0] EncryptionKey, - -- used to encrypt main reply - -- ENCTYPE is at least as strong as - -- ENCTYPE of session key - nonce [1] INTEGER, - -- binds response to the request - -- must be same as the nonce - -- passed in the PKAuthenticator - } - - Since each certifier in the certification path of a user's - certificate is equivalent to a separate Kerberos realm, the name - of each certifier in the certificate chain must be added to the - transited field of the ticket. The format of these realm names is - defined in Section 3.1 of this document. If applicable, the - transit-policy-checked flag should be set in the issued ticket. - - The KDC's certificate(s) must bind the public key(s) of the KDC to - a name derivable from the name of the realm for that KDC. X.509 - certificates shall contain the principal name of the KDC - (defined in section 8.2 of RFC 1510) as the SubjectAltName version - 3 extension. Below is the definition of this version 3 extension, - as specified by the X.509 standard: - - subjectAltName EXTENSION ::= { - SYNTAX GeneralNames - IDENTIFIED BY id-ce-subjectAltName - } - - GeneralNames ::= SEQUENCE SIZE(1..MAX) OF GeneralName - - GeneralName ::= CHOICE { - otherName [0] OtherName, - ... - } - - OtherName ::= SEQUENCE { - type-id OBJECT IDENTIFIER, - value [0] EXPLICIT ANY DEFINED BY type-id - } - - For the purpose of specifying a Kerberos principal name, the value - in OtherName shall be a KerberosName as defined in RFC 1510, but with - the PrincipalName replaced by CertPrincipalName as mentioned in - Section 3.1: - - KerberosName ::= SEQUENCE { - realm [0] Realm, - principalName [1] CertPrincipalName -- defined above - } - - This specific syntax is identified within subjectAltName by setting - the type-id in OtherName to krb5PrincipalName, where (from the - Kerberos specification) we have - - krb5 OBJECT IDENTIFIER ::= { iso (1) - org (3) - dod (6) - internet (1) - security (5) - kerberosv5 (2) } - - krb5PrincipalName OBJECT IDENTIFIER ::= { krb5 2 } - - (This specification may also be used to specify a Kerberos name - within the user's certificate.) The KDC's certificate may be signed - directly by a CA, or there may be intermediaries if the server resides - within a large organization, or it may be unsigned if the client - indicates possession (and trust) of the KDC's certificate. - - 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. The client uses this - random key to decrypt the main reply, and subsequently proceeds as - described in RFC 1510. - -3.2.3. Required Algorithms - - Not all of the algorithms in the PKINIT protocol specification have - to be implemented in order to comply with the proposed standard. - Below is a list of the required algorithms: - - * Diffie-Hellman public/private key pairs - * utilizing Diffie-Hellman ephemeral-ephemeral mode - * SHA1 digest and DSA for signatures - * SHA1 digest also for the Checksum in the PKAuthenticator - * 3-key triple DES keys derived from the Diffie-Hellman Exchange - * 3-key triple DES Temporary and Reply keys - -4. Logistics and Policy - - This section describes a way to define the policy on the use of - PKINIT for each principal and request. - - The KDC is not required to contain a database record for users - who use public key authentication. However, if these users are - registered with the KDC, it is recommended that the database record - for these users be modified to an additional flag in the attributes - field to indicate that the user should authenticate using PKINIT. - If this flag is set and a request message does not contain the - PKINIT preauthentication field, then the KDC sends back as error of - type KDC_ERR_PREAUTH_REQUIRED indicating that a preauthentication - field of type PA-PK-AS-REQ must be included in the request. - -5. Security Considerations - - PKINIT raises a few security considerations, which we will address - in this section. - - First of all, PKINIT introduces a new trust model, where KDCs do not - (necessarily) certify the identity of those for whom they issue - tickets. PKINIT does allow KDCs to act as their own CAs, in the - limited capacity of self-signing their certificates, but one of the - additional benefits is to align Kerberos authentication with a global - public key infrastructure. Anyone using PKINIT in this way must be - aware of how the certification infrastructure they are linking to - works. - - Secondly, PKINIT also introduces the possibility of interactions - between different cryptosystems, which may be of widely varying - strengths. Many systems, for instance, allow the use of 512-bit - public keys. Using such keys to wrap data encrypted under strong - conventional cryptosystems, such as triple-DES, is inappropriate; - it adds a weak link to a strong one at extra cost. Implementors - and administrators should take care to avoid such wasteful and - deceptive interactions. - - Lastly, PKINIT calls for randomly generated keys for conventional - cryptosystems. Many such systems contain systematically "weak" - keys. PKINIT implementations MUST avoid use of these keys, either - by discarding those keys when they are generated, or by fixing them - in some way (e.g., by XORing them with a given mask). These - precautions vary from system to system; it is not our intention to - give an explicit recipe for them here. - -6. Transport Issues - - Certificate chains can potentially grow quite large and span several - UDP packets; this in turn increases the probability that a Kerberos - message involving PKINIT extensions will be broken in transit. In - light of the possibility that the Kerberos specification will - require KDCs to accept requests using TCP as a transport mechanism, - we make the same recommendation with respect to the PKINIT - extensions as well. - -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] B. Tung, T. Ryutov, C. Neuman, G. Tsudik, B. Sommerfeld, - A. Medvinsky, M. Hur. Public Key Cryptography for Cross-Realm - Authentication in Kerberos. draft-ietf-cat-kerberos-pk-cross-04.txt - - [4] A. Medvinsky, J. Cargille, M. Hur. Anonymous Credentials in - Kerberos. draft-ietf-cat-kerberos-anoncred-00.txt - - [5] Ari Medvinsky, M. Hur, Alexander Medvinsky, B. Clifford Neuman. - Public Key Utilizing Tickets for Application Servers (PKTAPP). - draft-ietf-cat-pktapp-02.txt - - [6] M. Sirbu, J. Chuang. Distributed Authentication in Kerberos - Using Public Key Cryptography. Symposium On Network and Distributed - System Security, 1997. - - [7] B. Cox, J.D. Tygar, M. Sirbu. NetBill Security and Transaction - Protocol. In Proceedings of the USENIX Workshop on Electronic - Commerce, July 1995. - - [8] T. Dierks, C. Allen. The TLS Protocol, Version 1.0 - Request for Comments 2246, January 1999. - - [9] B.C. Neuman, Proxy-Based Authorization and Accounting for - Distributed Systems. In Proceedings of the 13th International - Conference on Distributed Computing Systems, May 1993. - - [10] ITU-T (formerly CCITT) Information technology - Open Systems - Interconnection - The Directory: Authentication Framework - Recommendation X.509 ISO/IEC 9594-8 - - [11] R. Housley. Cryptographic Message Syntax. - draft-ietf-smime-cms-13.txt, April 1999, approved for publication - as RFC. - - [12] PKCS #7: Cryptographic Message Syntax Standard, - An RSA Laboratories Technical Note Version 1.5 - Revised November 1, 1993 - - [13] R. Rivest, MIT Laboratory for Computer Science and RSA Data - Security, Inc. A Description of the RC2(r) Encryption Algorithm - March 1998. - Request for Comments 2268. - - [14] M. Wahl, S. Kille, T. Howes. Lightweight Directory Access - Protocol (v3): UTF-8 String Representation of Distinguished Names. - Request for Comments 2253. - - [15] R. Housley, W. Ford, W. Polk, D. Solo. Internet X.509 Public - Key Infrastructure, Certificate and CRL Profile, January 1999. - Request for Comments 2459. - - [16] B. Kaliski, J. Staddon. PKCS #1: RSA Cryptography - Specifications, October 1998. Request for Comments 2437. - - [17] S. Dusse, P. Hoffman, B. Ramsdell, J. Weinstein. S/MIME - Version 2 Certificate Handling, March 1998. Request for - Comments 2312. - - [18] M. Wahl, T. Howes, S. Kille. Lightweight Directory Access - Protocol (v3), December 1997. Request for Comments 2251. - - [19] ITU-T (formerly CCITT) Information Processing Systems - Open - Systems Interconnection - Specification of Abstract Syntax Notation - One (ASN.1) Rec. X.680 ISO/IEC 8824-1 - - [20] PKCS #3: Diffie-Hellman Key-Agreement Standard, An RSA - Laboratories Technical Note, Version 1.4, Revised November 1, 1993. - -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 January 15, 2001. - -10. Authors - - Brian Tung - Clifford Neuman - USC Information Sciences Institute - 4676 Admiralty Way Suite 1001 - Marina del Rey CA 90292-6695 - Phone: +1 310 822 1511 - E-mail: {brian, bcn}@isi.edu - - Matthew Hur - CyberSafe Corporation - 1605 NW Sammamish Road - Issaquah WA 98027-5378 - Phone: +1 425 391 6000 - E-mail: matt.hur@cybersafe.com - - Ari Medvinsky - Keen.com, Inc. - 150 Independence Drive - Menlo Park CA 94025 - Phone: +1 650 289 3134 - E-mail: ari@keen.com - - Sasha Medvinsky - Motorola - 6450 Sequence Drive - San Diego, CA 92121 - +1 858 404 2367 - E-mail: smedvinsky@gi.com - - John Wray - Iris Associates, Inc. - 5 Technology Park Dr. - Westford, MA 01886 - E-mail: John_Wray@iris.com - - Jonathan Trostle - 170 W. Tasman Dr. - San Jose, CA 95134 - E-mail: jtrostle@cisco.com diff --git a/crypto/heimdal/doc/standardisation/draft-ietf-cat-kerberos-pk-tapp-03.txt b/crypto/heimdal/doc/standardisation/draft-ietf-cat-kerberos-pk-tapp-03.txt deleted file mode 100644 index 6581dd5810a5..000000000000 --- a/crypto/heimdal/doc/standardisation/draft-ietf-cat-kerberos-pk-tapp-03.txt +++ /dev/null @@ -1,378 +0,0 @@ -INTERNET-DRAFT Ari Medvinsky -draft-ietf-cat-kerberos-pk-tapp-03.txt Keen.com, Inc. -Expires January 14, 2001 Matthew Hur -Informational CyberSafe Corporation - Sasha Medvinsky - Motorola - Clifford Neuman - USC/ISI - -Public Key Utilizing Tickets for Application Servers (PKTAPP) - - -0. Status Of this Memo - -This document is an Internet-Draft and is in full conformance with -all provisions of Section 10 of RFC 2026. 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 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-pk-init-10.txt, and expires April 30, -2000. Please send comments to the authors. - -1. Abstract - -Public key based Kerberos for Distributed Authentication[1], (PKDA) -proposed by Sirbu & Chuang, describes PK based authentication that -eliminates the use of a centralized key distribution center while -retaining the advantages of Kerberos tickets. This draft describes how, -without any modification, the PKINIT specification[2] may be used to -implement the ideas introduced in PKDA. The benefit is that only a -single PK Kerberos extension is needed to address the goals of PKINIT & -PKDA. - - - -2. Introduction - -With the proliferation of public key cryptography, a number of public -key extensions to Kerberos have been proposed to provide -interoperability with the PK infrastructure and to improve the Kerberos -authentication system [4]. Among these are PKINIT[2] (under development -in the CAT working group) and more recently PKDA [1] proposed by Sirbu & -Chuang of CMU. One of the principal goals of PKINIT is to provide for -interoperability between a PK infrastructure and Kerberos. Using -PKINIT, a user can authenticate to the KDC via a public key certificate. -A ticket granting ticket (TGT), returned by the KDC, enables a PK user -to obtain tickets and authenticate to kerberized services. The PKDA -proposal goes a step further. It supports direct client to server -authentication, eliminating the need for an online key distribution -center. In this draft, we describe how, without any modification, the -PKINIT protocol may be applied to achieve the goals of PKDA. For direct -client to server authentication, the client will use PKINIT to -authenticate to the end server (instead of a central KDC), which then, -will issue a ticket for itself. The benefit of this proposal, is that a -single PK extension to Kerberos can addresses the goals of PKINIT and -PKDA. - - -3. PKDA background - -The PKDA proposal provides direct client to server authentication, thus -eliminating the need for an online key distribution center. A client -and server take part in an initial PK based authentication exchange, -with an added caveat that the server acts as a Kerberos ticket granting -service and issues a traditional Kerberos ticket for itself. In -subsequent communication, the client makes use of the Kerberos ticket, -thus eliminating the need for public key operations on the server. This -approach has an advantage over SSL 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 Neuman[3]). - -Below is a brief overview of the PKDA protocol. For a more detailed -description see [1]. - -SCERT_REQ: Client to Server -The client requests a certificate from the server. If the serverÆs -certificate is cached locally, SCERT_REQ and SCERT_REP are omitted. - -SCERT_REP: Server to Client -The server returns its certificate to the client. - -PKTGS_REQ: Client to Server -The client sends a request for a service ticket to the server. To -authenticate the request, the client signs, among other fields, a time -stamp and a newly generated symmetric key . The time stamp is used to -foil replay attacks; the symmetric key is used by the server to secure -the PKTGS_REP message. -The client provides a certificate in the request (the certificate -enables the server to verify the validity of the clientÆs signature) and -seals it along with the signed information using the serverÆs public -key. - - -PKTGS_REP: Server to Client -The server returns a service ticket (which it issued for itself) along -with the session key for the ticket. The session key is protected by -the client-generated key from the PKTGS_REQ message. - -AP_REQ: Client to Server -After the above exchange, the client can proceed in a normal fashion, -using the conventional Kerberos ticket in an AP_REQ message. - - -4. PKINIT background - -One of the principal goals of PKINIT is to provide for interoperability -between a public key infrastructure and Kerberos. Using a public key -certificate, a client can authenticate to the KDC and receive a TGT -which enables the client to obtain service tickets to kerberized -services.. In PKINIT, the AS-REQ and AS-REP messages remain the same; -new preauthentication data types are used to conduct the PK exchange. -Client and server certificates are exchanged via the preauthentication -data. Thus, the exchange of certificates , PK authentication, and -delivery of a TGT can occur in two messages. - -Below is a brief overview of the PKINIT protocol. For a more detailed -description see [2]. - -PreAuthentication data of AS-REQ: Client to Server -The client sends a list of trusted certifiers, a signed PK -authenticator, and its certificate. The PK authenticator, based on the -Kerberos authenticator, contains the name of the KDC, a timestamp, and a -nonce. - -PreAuthentication data of AS-REP: Server to Client -The server responds with its certificate and the key used for decrypting -the encrypted part of the AS-REQ. This key is encrypted with the -clientÆs public key. - -AP_REQ: Client to Server -After the above exchange, the client can proceed in a normal fashion, -using the conventional Kerberos ticket in an AP_REQ message. - - -5. Application of PKINIT to achieve equivalence to PKDA - -While PKINIT is normally used to retrieve a ticket granting ticket -(TGT), it may also be used to request an end service ticket. When used -in this fashion, PKINIT is functionally equivalent to PKDA. We -introduce the concept of a local ticket granting server (LTGS) to -illustrate how PKINIT may be used for issuing end service tickets based -on public key authentication. It is important to note that the LTGS may -be built into an application server, or it may be a stand-alone server -used for issuing tickets within a well-defined realm, such as a single -machine. We will discuss both of these options. - - -5.1. The LTGS - -The LTGS processes the Kerberos AS-REQ and AS-REP messages with PKINIT -preauthentication data. When a client submits an AS-REQ to the LTGS, it -specifies an application server, in order to receive an end service -ticket instead of a TGT. - - -5.1.1. The LTGS as a standalone server - -The LTGS may run as a separate process that serves applications which -reside on the same machine. This serves to consolidate administrative -functions and provide an easier migration path for a heterogeneous -environment consisting of both public key and Kerberos. The LTGS would -use one well-known port (port #88 - same as the KDC) for all message -traffic and would share a symmetric with each service. After the client -receives a service ticket, it then contacts the application server -directly. This approach is similar to the one suggested by Sirbu , et -al [1]. - -5.1.1.1. Ticket Policy for PKTAPP Clients - -It is desirable for the LTGS to have access to a PKTAPP client ticket -policy. This policy will contain information for each client, such as -the maximum lifetime of a ticket, whether or not a ticket can be -forwardable, etc. PKTAPP clients, however, use the PKINIT protocol for -authentication and are not required to be registered as Kerberos -principals. - -As one possible solution, each public key Certification Authority could -be registered in a secure database, along with the ticket policy -information for all PKTAPP clients that are certified by this -Certification Authority. - -5.1.1.2. LTGS as a Kerberos Principal - -Since the LTGS serves only PKTAPP clients and returns only end service -tickets for other services, it does not require a Kerberos service key -or a Kerberos principal identity. It is therefore not necessary for the -LTGS to even be registered as a Kerberos principal. - -The LTGS still requires public key credentials for the PKINIT exchange, -and it may be desired to have some global restrictions on the Kerberos -tickets that it can issue. It is recommended (but not required) that -this information be associated with a Kerberos principal entry for the -LTGS. - - -5.1.1.3. Kerberos Principal Database - -Since the LTGS issues tickets for Kerberos services, it will require -access to a Kerberos principal database containing entries for at least -the end services. Each entry must contain a service key and may also -contain restrictions on the service tickets that are issued to clients. -It is recommended that (for ease of administration) this principal -database be centrally administered and distributed (replicated) to all -hosts where an LTGS may be running. - -In the case that there are other clients that do not support PKINIT -protocol, but still need access to the same Kerberos services, this -principal database will also require entries for Kerberos clients and -for the TGS entries. - -5.1.2. The LTGS as part of an application server - -The LTGS may be combined with an application server. This accomplishes -direct client to application server authentication; however, it requires -that applications be modified to process AS-REQ and AS-REP messages. -The LTGS would communicate over the port assigned to the application -server or over the well known Kerberos port for that particular -application. - -5.1.2.2. Ticket Policy for PKTAPP Clients - -Application servers normally do not have access to a distributed -principal database. Therefore, they will have to find another means of -keeping track of the ticket policy information for PKTAPP clients. It is -recommended that this ticket policy be kept in a directory service (such -as LDAP). - -It is critical, however, that both read and write access to this ticket -policy is restricted with strong authentication and encryption to only -the correct application server. An unauthorized party should not have -the authority to modify the ticket policy. Disclosing the ticket policy -to a 3rd party may aid an adversary in determining the best way to -compromise the network. - -It is just as critical for the application server to authenticate the -directory service. Otherwise an adversary could use a man-in-the-middle -attack to substitute a false ticket policy with a false directory -service. - -5.1.2.3. LTGS Credentials - -Each LTGS (combined with an application service) will require public key -credentials in order to use the PKINIT protocol. These credentials can -be stored in a single file that is both encrypted with a password- -derived symmetric key and also secured by an operating system. This -symmetric key may be stashed somewhere on the machine for convenience, -although such practice potentially weakens the overall system security -and is strongly discouraged. - -For added security, it is recommended that the LTGS private keys are -stored inside a temper-resistant hardware module that requires a pin -code for access. - - -5.1.2.4. Compatibility With Standard Kerberos - -Even though an application server is combined with the LTGS, for -backward compatibility it should still accept service tickets that have -been issued by the KDC. This will allow Kerberos clients that do not -support PKTAPP to authenticate to the same application server (with the -help of a KDC). - -5.1.3. Cross-Realm Authentication - -According to the PKINIT draft, the client's realm is the X.500 name of -the Certification Authority that issued the client certificate. A -Kerberos application service will be in a standard Kerberos realm, which -implies that the LTGS will need to issue cross-realm end service -tickets. This is the only case, where cross-realm end service tickets -are issued. In a standard Kerberos model, a client first acquires a -cross-realm TGT, and then gets an end service ticket from the KDC that -is in the same realm as the application service. - -6. Protocol differences between PKINIT and PKDA - -Both PKINIT and PKDA will accomplish the same goal of issuing end -service tickets, based on initial public key authentication. A PKINIT- -based implementation and a PKDA implementation would be functionally -equivalent. The primary differences are that 1)PKDA requires the client -to create the symmetric key while PKINIT requires the server to create -the key and 2)PKINIT accomplishes in two messages what PKDA accomplishes -in four messages. - -7. Summary - -The PKINIT protocol can be used, without modification to facilitate -client to server authentication without the use of a central KDC. The -approach described in this draft (and originally proposed in PKDA[1]) -is essentially a public key authentication protocol that retains the -advantages of Kerberos tickets. - -Given that PKINIT has progressed through the CAT working group of the -IETF, with plans for non-commercial distribution (via MITÆs v5 Kerberos) -as well as commercial support, it is worthwhile to provide PKDA -functionality, under the PKINIT umbrella. - -8. Security Considerations - -PKTAPP is based on the PKINIT protocol and all security considerations -already listed in [2] apply here. - -When the LTGS is implemented as part of each application server, the -secure storage of its public key credentials and of its ticket policy -are both a concern. The respective security considerations are already -covered in sections 5.1.2.3 and 5.1.2.2 of this document. - - -9. Bibliography - -[1] M. Sirbu, J. Chuang. Distributed Authentication in Kerberos Using -Public Key Cryptography. Symposium On Network and Distributed System -Security, 1997. - -[2] B. Tung, C. Neuman, M. Hur, A. Medvinsky, S. Medvinsky, J. Wray, -J. Trostle. Public Key Cryptography for Initial Authentication in -Kerberos. Internet Draft, October 1999. -(ftp://ietf.org/internet-drafts/draft-ietf-cat-kerberos-pk-init-10.txt) - -[3] C. Neuman, Proxy-Based Authorization and Accounting for -Distributed Systems. In Proceedings of the 13th International -Conference on Distributed Computing Systems, May 1993. - -[4] J. Kohl, C. Neuman. The Kerberos Network Authentication Service -(V5). Request for Comments 1510. - -10. Expiration Date - -This draft expires April 24, 2000. - -11. Authors - -Ari Medvinsky -Keen.com, Inc. -150 Independence Dr. -Menlo Park, CA 94025 -Phone +1 650 289 3134 -E-mail: ari@keen.com - -Matthew Hur -CyberSafe Corporation -1605 NW Sammamish Road -Issaquah, WA 98027-5378 -Phone: +1 425 391 6000 -E-mail: matt.hur@cybersafe.com - -Alexander Medvinsky -Motorola -6450 Sequence Dr. -San Diego, CA 92121 -Phone: +1 858 404 2367 -E-mail: smedvinsky@gi.com - -Clifford Neuman -USC Information Sciences Institute -4676 Admiralty Way Suite 1001 -Marina del Rey CA 90292-6695 -Phone: +1 310 822 1511 -E-mail: bcn@isi.edu diff --git a/crypto/heimdal/doc/standardisation/draft-ietf-cat-kerberos-revisions-00.txt b/crypto/heimdal/doc/standardisation/draft-ietf-cat-kerberos-revisions-00.txt deleted file mode 100644 index 2284c3c6b57b..000000000000 --- a/crypto/heimdal/doc/standardisation/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/crypto/heimdal/doc/standardisation/draft-ietf-cat-kerberos-revisions-01.txt b/crypto/heimdal/doc/standardisation/draft-ietf-cat-kerberos-revisions-01.txt deleted file mode 100644 index 78db9d78f3cb..000000000000 --- a/crypto/heimdal/doc/standardisation/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/crypto/heimdal/doc/standardisation/draft-ietf-cat-kerberos-revisions-03.txt b/crypto/heimdal/doc/standardisation/draft-ietf-cat-kerberos-revisions-03.txt deleted file mode 100644 index 06d997d48cca..000000000000 --- a/crypto/heimdal/doc/standardisation/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/crypto/heimdal/doc/standardisation/draft-ietf-cat-kerberos-revisions-04.txt b/crypto/heimdal/doc/standardisation/draft-ietf-cat-kerberos-revisions-04.txt deleted file mode 100644 index 16af15dbce9f..000000000000 --- a/crypto/heimdal/doc/standardisation/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/crypto/heimdal/doc/standardisation/draft-ietf-cat-kerberos-revisions-05.txt b/crypto/heimdal/doc/standardisation/draft-ietf-cat-kerberos-revisions-05.txt deleted file mode 100644 index 15921248c117..000000000000 --- a/crypto/heimdal/doc/standardisation/draft-ietf-cat-kerberos-revisions-05.txt +++ /dev/null @@ -1,6866 +0,0 @@ -INTERNET-DRAFT Clifford Neuman - John Kohl - Theodore Ts'o - March 10, 2000 - Expires September 10, 2000 - -The Kerberos Network Authentication Service (V5) -draft-ietf-cat-kerberos-revisions-05.txt - -STATUS OF THIS MEMO - -This document is an Internet-Draft and is in full conformance with all -provisions of Section 10 of RFC 2026. 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 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-05.txt, and expires September 10, 2000. -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 - -Neuman, Ts'o, Kohl Expires: 10 September, 2000 - - - - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-05 June 25, 1999 - -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 -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 - -Neuman, Ts'o, Kohl Expires: 10 September, 2000 - - - - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-05 June 25, 1999 - -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. - -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 - -Neuman, Ts'o, Kohl Expires: 10 September, 2000 - - - - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-05 June 25, 1999 - -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 -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 - -Neuman, Ts'o, Kohl Expires: 10 September, 2000 - - - - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-05 June 25, 1999 - -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. -Separately authenticated authorization credentials may be embedded in a -tickets authorization data when encapsulated by the kdc-issued authorization -data element. - -Applications should not be modified to accept the mere issuance of a service -ticket by the Kerberos server (even by a 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 - -Neuman, Ts'o, Kohl Expires: 10 September, 2000 - - - - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-05 June 25, 1999 - - 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). -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 - -Neuman, Ts'o, Kohl Expires: 10 September, 2000 - - - - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-05 June 25, 1999 - - 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. - -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). - - -Neuman, Ts'o, Kohl Expires: 10 September, 2000 - - - - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-05 June 25, 1999 - -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. - -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 - -Neuman, Ts'o, Kohl Expires: 10 September, 2000 - - - - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-05 June 25, 1999 - -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. - -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 - -Neuman, Ts'o, Kohl Expires: 10 September, 2000 - - - - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-05 June 25, 1999 - -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. - -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 - -Neuman, Ts'o, Kohl Expires: 10 September, 2000 - - - - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-05 June 25, 1999 - -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<>]. - -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 - - -Neuman, Ts'o, Kohl Expires: 10 September, 2000 - - - - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-05 June 25, 1999 - -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 -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 - -Neuman, Ts'o, Kohl Expires: 10 September, 2000 - - - - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-05 June 25, 1999 - -(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. - -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 - - -Neuman, Ts'o, Kohl Expires: 10 September, 2000 - - - - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-05 June 25, 1999 - -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.' - -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 - -Neuman, Ts'o, Kohl Expires: 10 September, 2000 - - - - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-05 June 25, 1999 - -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. - -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. - -Neuman, Ts'o, Kohl Expires: 10 September, 2000 - - - - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-05 June 25, 1999 - - -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, -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 - -Neuman, Ts'o, Kohl Expires: 10 September, 2000 - - - - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-05 June 25, 1999 - -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 -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 - -Neuman, Ts'o, Kohl Expires: 10 September, 2000 - - - - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-05 June 25, 1999 - -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 -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 - -Neuman, Ts'o, Kohl Expires: 10 September, 2000 - - - - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-05 June 25, 1999 - -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. - -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 - -Neuman, Ts'o, Kohl Expires: 10 September, 2000 - - - - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-05 June 25, 1999 - -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 -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 - -Neuman, Ts'o, Kohl Expires: 10 September, 2000 - - - - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-05 June 25, 1999 - -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 -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: 10 September, 2000 - - - - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-05 June 25, 1999 - - - "/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: 10 September, 2000 - - - - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-05 June 25, 1999 - -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 -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: 10 September, 2000 - - - - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-05 June 25, 1999 - -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 -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 - -Neuman, Ts'o, Kohl Expires: 10 September, 2000 - - - - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-05 June 25, 1999 - -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 containing 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 - -Neuman, Ts'o, Kohl Expires: 10 September, 2000 - - - - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-05 June 25, 1999 - -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). - -Other frequently changing information that can be maintained is the latest -expiration time for any tickets that have been issued using each key. This - -Neuman, Ts'o, Kohl Expires: 10 September, 2000 - - - - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-05 June 25, 1999 - -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. 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 - -Neuman, Ts'o, Kohl Expires: 10 September, 2000 - - - - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-05 June 25, 1999 - -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 -} - -ad-data - This field contains authorization data to be interpreted according to - the value of the corresponding ad-type field. - -Neuman, Ts'o, Kohl Expires: 10 September, 2000 - - - - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-05 June 25, 1999 - -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), - -- proxiable(3), - -- proxy(4), - -- allow-postdate(5), - -- postdated(6), - -Neuman, Ts'o, Kohl Expires: 10 September, 2000 - - - - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-05 June 25, 1999 - - -- 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 - -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: 10 September, 2000 - - - - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-05 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 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. - -Neuman, Ts'o, Kohl Expires: 10 September, 2000 - - - - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-05 June 25, 1999 - - - 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. - - 5 MAY-POSTDATE - -Neuman, Ts'o, Kohl Expires: 10 September, 2000 - - - - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-05 June 25, 1999 - - 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 - reset (0), then the application server - must check the transited field itself, - -Neuman, Ts'o, Kohl Expires: 10 September, 2000 - - - - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-05 June 25, 1999 - - 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 - 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. - -Neuman, Ts'o, Kohl Expires: 10 September, 2000 - - - - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-05 June 25, 1999 - - 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 Kerberos 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 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 - -Neuman, Ts'o, Kohl Expires: 10 September, 2000 - - - - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-05 June 25, 1999 - - 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, except when an entry is separately authenticated by - encapulation in the kdc-issued element, 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), - may obtain 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. - Alternatively, such authorization credentials may be embedded in the - ticket authenticating the authorized entity, when the authorization is - separately authenticated using the kdc-issued authorization data - element (see B.4). - - 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 - -Neuman, Ts'o, Kohl Expires: 10 September, 2000 - - - - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-05 June 25, 1999 - -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. -authorization-data - -Neuman, Ts'o, Kohl Expires: 10 September, 2000 - - - - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-05 June 25, 1999 - - 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 -} - -The fields in this message are: - - -Neuman, Ts'o, Kohl Expires: 10 September, 2000 - - - - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-05 June 25, 1999 - -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. -padata-type - -Neuman, Ts'o, Kohl Expires: 10 September, 2000 - - - - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-05 June 25, 1999 - - 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 - the initial request, or in a subsequent - request if the ticket-granting ticket on - which it is based is also proxiable. - -Neuman, Ts'o, Kohl Expires: 10 September, 2000 - - - - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-05 June 25, 1999 - - - 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- - 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 - -Neuman, Ts'o, Kohl Expires: 10 September, 2000 - - - - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-05 June 25, 1999 - - 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 - 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 - -Neuman, Ts'o, Kohl Expires: 10 September, 2000 - - - - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-05 June 25, 1999 - - 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 - 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]. - -Neuman, Ts'o, Kohl Expires: 10 September, 2000 - - - - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-05 June 25, 1999 - -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, - padata[2] SEQUENCE OF PA-DATA OPTIONAL, - crealm[3] Realm, - cname[4] PrincipalName, - ticket[5] Ticket, - -Neuman, Ts'o, Kohl Expires: 10 September, 2000 - - - - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-05 June 25, 1999 - - 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 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 - -Neuman, Ts'o, Kohl Expires: 10 September, 2000 - - - - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-05 June 25, 1999 - - 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 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 - -Neuman, Ts'o, Kohl Expires: 10 September, 2000 - - - - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-05 June 25, 1999 - - 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 - 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. - -Neuman, Ts'o, Kohl Expires: 10 September, 2000 - - - - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-05 June 25, 1999 - -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. -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 - -Neuman, Ts'o, Kohl Expires: 10 September, 2000 - - - - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-05 June 25, 1999 - - 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 -} - -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. - -Neuman, Ts'o, Kohl Expires: 10 September, 2000 - - - - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-05 June 25, 1999 - -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 -} - -pvno and msg-type - These fields are described above in section 5.4.1. msg-type is - -Neuman, Ts'o, Kohl Expires: 10 September, 2000 - - - - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-05 June 25, 1999 - - 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 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. - -Neuman, Ts'o, Kohl Expires: 10 September, 2000 - - - - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-05 June 25, 1999 - - -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, -} - - - -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 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: - -Neuman, Ts'o, Kohl Expires: 10 September, 2000 - - - - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-05 June 25, 1999 - - - 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. - - 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], and triple DES variants, 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. - - The Kerberos protocols generally assume that the encryption used is - secure from cryptanalysis; however, in some cases, the order of fields - -Neuman, Ts'o, Kohl Expires: 10 September, 2000 - - - - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-05 June 25, 1999 - - 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 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 - -Neuman, Ts'o, Kohl Expires: 10 September, 2000 - - - - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-05 June 25, 1999 - - 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 for some methods is - described in the following diagram, but other methods may deviate from - this layour - so long as the definition of the method defines the - layout actually in use. - - +-----------+----------+-------------+-----+ - |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 - -Neuman, Ts'o, Kohl Expires: 10 September, 2000 - - - - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-05 June 25, 1999 - - 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. - - 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) - - -Neuman, Ts'o, Kohl Expires: 10 September, 2000 - - - - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-05 June 25, 1999 - - 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 eXclusive-ORing a block, every byte is shifted one bit to - -Neuman, Ts'o, Kohl Expires: 10 September, 2000 - - - - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-05 June 25, 1999 - - 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 and - without Key Derivation [Original draft by Marc Horowitz, revisions by - David Miller] - - This encryption type is based on the Triple DES cryptosystem, the - HMAC-SHA1 [Krawczyk96] message authentication algorithm, and key - derivation for Kerberos V5 [HorowitzB96]. Key derivation may or may not - be used in conjunction with the use of Triple DES keys. - - Algorithm Identifiers - - The des3-cbc-hmac-sha1 encryption type has been assigned the value 7. - The des3-cbc-hmac-sha1-kd encryption type, specifying the key - derivation variant of the encryption type, has been assigned the value - 16. The hmac-sha1-des3 checksum type has been assigned the value 13. - -Neuman, Ts'o, Kohl Expires: 10 September, 2000 - - - - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-05 June 25, 1999 - - The hmac-sha1-des3-kd checksum type, specifying the key derivation - variant of the checksum, has been assigned the value 12. - - Triple DES Key Production - - 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. - - The string-to-key function is used to tranform UNICODE passwords into - DES3 keys. The DES3 string-to-key function relies on the "N-fold" - algorithm, which is detailed in [9]. The description of the N-fold - algorithm in that document is as follows: - o 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 is rotated to the right by 13 bit positions. - The successive n-bit chunks are added together using - 1's-complement addition (that is, addition with end-around carry) - to yield an n-bit result" - o The n-fold algorithm, as with DES string-to-key, is applied to the - password string concatenated with a salt value. The salt value is - derived in the same was as for the DES string-to-key algorithm. - For 3-key triple DES then, the operation will involve a 168-fold - of the input password string. The remainder of the string-to-key - function for DES3 is shown here in pseudocode: - - DES3string-to-key(passwordString, key) - - salt = name_to_default_salt(realm, name) - s = passwordString + salt - tmpKey1 = 168-fold(s) - parityFix(tmpKey1); - if not weakKey(tmpKey1) - /* - * Encrypt temp key in itself with a - * zero initialization vector - * - * Function signature is DES3encrypt(plain, key, iv) - -Neuman, Ts'o, Kohl Expires: 10 September, 2000 - - - - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-05 June 25, 1999 - - * with cipher as the return value - */ - tmpKey2 = DES3encrypt(tmpKey1, tmpKey1, zeroIvec) - /* - * Encrypt resultant temp key in itself with third component - * of first temp key as initialization vector - */ - key = DES3encrypt(tmpKey2, tmpKey1, tmpKey1[2]) - parityFix(key) - if not weakKey(key) - return SUCCESS - else - return FAILURE - else - return FAILURE - - The weakKey function above is the same weakKey function used with DES - keys, but applied to each of the three single DES keys that comprise - the triple DES key. - - The lengths of UNICODE encoded character strings include the trailing - terminator character (0). - - Encryption Types des3-cbc-hmac-sha1 and des3-cbc-hmac-sha1-kd - - EncryptedData using this type must be generated as described in - [Horowitz96]. The encryption algorithm is Triple DES in Outer-CBC mode. - The checksum algorithm is HMAC-SHA1. If the key derivation variant of - the encryption type is used, encryption key values are modified - according to the method under the Key Derivation section below. - - 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 Types hmac-sha1-des3 and hmac-sha1-des3-kd - - Checksums using this type must be generated as described in - [Horowitz96]. The keyed hash algorithm is HMAC-SHA1. If the key - derivation variant of the checksum type is used, checksum key values - are modified according to the method under the Key Derivation section - below. - - 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. - -Neuman, Ts'o, Kohl Expires: 10 September, 2000 - - - - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-05 June 25, 1999 - - - 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 - -Neuman, Ts'o, Kohl Expires: 10 September, 2000 - - - - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-05 June 25, 1999 - - 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. - - 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 required 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. - -Neuman, Ts'o, Kohl Expires: 10 September, 2000 - - - - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-05 June 25, 1999 - - 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) - - 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: - -Neuman, Ts'o, Kohl Expires: 10 September, 2000 - - - - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-05 June 25, 1999 - - - +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ - | 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 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 - -Neuman, Ts'o, Kohl Expires: 10 September, 2000 - - - - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-05 June 25, 1999 - - 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 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 - -Neuman, Ts'o, Kohl Expires: 10 September, 2000 - - - - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-05 June 25, 1999 - - 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. - - 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 - -Neuman, Ts'o, Kohl Expires: 10 September, 2000 - - - - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-05 June 25, 1999 - - 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. - - 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 - -Neuman, Ts'o, Kohl Expires: 10 September, 2000 - - - - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-05 June 25, 1999 - - 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). - - 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: - o the Unspecified Address - o the Loopback Address - o 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 - -Neuman, Ts'o, Kohl Expires: 10 September, 2000 - - - - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-05 June 25, 1999 - - 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. - - 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 - -Neuman, Ts'o, Kohl Expires: 10 September, 2000 - - - - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-05 June 25, 1999 - - 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. - - 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 - -Neuman, Ts'o, Kohl Expires: 10 September, 2000 - - - - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-05 June 25, 1999 - - 6 - des3-cbc-sha1 7 8 0 8 - 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) - des3-cbc-sha1-kd 16 (Tom Yu) - rc4-hmac 23 (swift) - rc4-hmac-exp 24 (swift) - - 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 (drop rsa ?) - rsa-md5 7 16 (drop rsa ?) - rsa-md5-des 8 24 (drop rsa ?) - rsa-md5-des3 9 24 (drop rsa ?) - hmac-sha1-des3-kd 12 20 - hmac-sha1-des3 13 20 - - padata type padata-type value - - PA-TGS-REQ 1 - PA-ENC-TIMESTAMP 2 - PA-PW-SALT 3 - 4 - PA-ENC-UNIX-TIME 5 (depricated) - PA-SANDIA-SECUREID 6 - PA-SESAME 7 - PA-OSF-DCE 8 - PA-CYBERSAFE-SECUREID 9 - PA-AFS3-SALT 10 - PA-ETYPE-INFO 11 - PA-SAM-CHALLENGE 12 (sam/otp) - PA-SAM-RESPONSE 13 (sam/otp) - PA-PK-AS-REQ 14 (pkinit) - PA-PK-AS-REP 15 (pkinit) - PA-USE-SPECIFIED-KVNO 20 - PA-SAM-REDIRECT 21 (sam/otp) - PA-GET-FROM-TYPED-DATA 22 - PA-SAM-ETYPE-INFO 23 (sam/otp) - -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 - -Neuman, Ts'o, Kohl Expires: 10 September, 2000 - - - - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-05 June 25, 1999 - -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 -AD-OSF-DCE-PKI-CERTID 66 (hemsath@us.ibm.com) - -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 -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] - - -Neuman, Ts'o, Kohl Expires: 10 September, 2000 - - - - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-05 June 25, 1999 - -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 prot vers 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 -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) - -Neuman, Ts'o, Kohl Expires: 10 September, 2000 - - - - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-05 June 25, 1999 - -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. - - 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. - - Encryption: DES-CBC-MD5, one triple des variant (tbd) - Checksums: CRC-32, DES-MAC, DES-MAC-K, and DES-MD5 (tbd) - - 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 - -Neuman, Ts'o, Kohl Expires: 10 September, 2000 - - - - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-05 June 25, 1999 - - 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. - - 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). - - -Neuman, Ts'o, Kohl Expires: 10 September, 2000 - - - - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-05 June 25, 1999 - - 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, - "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 - -Neuman, Ts'o, Kohl Expires: 10 September, 2000 - - - - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-05 June 25, 1999 - - 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, - 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. - - -Neuman, Ts'o, Kohl Expires: 10 September, 2000 - - - - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-05 June 25, 1999 - - [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 - - A.2. KRB_AS_REQ verification and KRB_AS_REP generation - - decode message into req; - - -Neuman, Ts'o, Kohl Expires: 10 September, 2000 - - - - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-05 June 25, 1999 - - 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; - endif - - if (req.kdc-options.ALLOW-POSTDATE is set) then - -Neuman, Ts'o, Kohl Expires: 10 September, 2000 - - - - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-05 June 25, 1999 - - 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, - new_tkt.starttime+max_rlife_for_realm); - else - omit new_tkt.renew-till; /* only present if RENEWABLE */ - -Neuman, Ts'o, Kohl Expires: 10 September, 2000 - - - - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-05 June 25, 1999 - - 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 - process_error(resp); - return; - endif - -Neuman, Ts'o, Kohl Expires: 10 September, 2000 - - - - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-05 June 25, 1999 - - - /* 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 - destroy resp.key; - return KRB_AP_ERR_MODIFIED; - endif - -Neuman, Ts'o, Kohl Expires: 10 September, 2000 - - - - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-05 June 25, 1999 - - 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)); - send(packet,kerberos); - - -Neuman, Ts'o, Kohl Expires: 10 September, 2000 - - - - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-05 June 25, 1999 - - 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 */ - -Neuman, Ts'o, Kohl Expires: 10 September, 2000 - - - - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-05 June 25, 1999 - - 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 - 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); - -Neuman, Ts'o, Kohl Expires: 10 September, 2000 - - - - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-05 June 25, 1999 - - 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 - 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: 10 September, 2000 - - - - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-05 June 25, 1999 - - 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, - -Neuman, Ts'o, Kohl Expires: 10 September, 2000 - - - - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-05 June 25, 1999 - - * 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; - 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, - -Neuman, Ts'o, Kohl Expires: 10 September, 2000 - - - - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-05 June 25, 1999 - - 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 - - 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 */ - - -Neuman, Ts'o, Kohl Expires: 10 September, 2000 - - - - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-05 June 25, 1999 - - 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); - 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 - -Neuman, Ts'o, Kohl Expires: 10 September, 2000 - - - - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-05 June 25, 1999 - - 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); - - 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; - -Neuman, Ts'o, Kohl Expires: 10 September, 2000 - - - - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-05 June 25, 1999 - - 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 - - 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 - -Neuman, Ts'o, Kohl Expires: 10 September, 2000 - - - - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-05 June 25, 1999 - - 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; - - A.16. KRB_PRIV generation - - collect user data in buffer; - - /* assemble packet: */ - packet.pvno := protocol version; /* 5 */ - packet.msg-type := message type; /* KRB_PRIV */ - - -Neuman, Ts'o, Kohl Expires: 10 September, 2000 - - - - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-05 June 25, 1999 - - 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 */ - - /* 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; - -Neuman, Ts'o, Kohl Expires: 10 September, 2000 - - - - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-05 June 25, 1999 - - 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); - 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 - -Neuman, Ts'o, Kohl Expires: 10 September, 2000 - - - - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-05 June 25, 1999 - - 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 - - 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 - - -Neuman, Ts'o, Kohl Expires: 10 September, 2000 - - - - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-05 June 25, 1999 - - 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. - - 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 - -Neuman, Ts'o, Kohl Expires: 10 September, 2000 - - - - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-05 June 25, 1999 - - 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. - - 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 - - -Neuman, Ts'o, Kohl Expires: 10 September, 2000 - - - - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-05 June 25, 1999 - - 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. - - 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 - - -Neuman, Ts'o, Kohl Expires: 10 September, 2000 - - - - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-05 June 25, 1999 - - 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. - - [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 - -Neuman, Ts'o, Kohl Expires: 10 September, 2000 - - - - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-05 June 25, 1999 - - 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. - - [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 - -Neuman, Ts'o, Kohl Expires: 10 September, 2000 - - - - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-05 June 25, 1999 - - 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. - - [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 - -Neuman, Ts'o, Kohl Expires: 10 September, 2000 - - - - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-05 June 25, 1999 - - 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/crypto/heimdal/doc/standardisation/draft-ietf-cat-kerberos-revisions-06.txt b/crypto/heimdal/doc/standardisation/draft-ietf-cat-kerberos-revisions-06.txt deleted file mode 100644 index ae79e8a7c4fb..000000000000 --- a/crypto/heimdal/doc/standardisation/draft-ietf-cat-kerberos-revisions-06.txt +++ /dev/null @@ -1,7301 +0,0 @@ -INTERNET-DRAFT Clifford Neuman - John Kohl - Theodore Ts'o - July 14, 2000 - Expires January 14, 2001 - -The Kerberos Network Authentication Service (V5) - - -draft-ietf-cat-kerberos-revisions-06.txt - -STATUS OF THIS MEMO - -This document is an Internet-Draft and is in full conformance with all -provisions of Section 10 of RFC 2026. 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 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-06.txt, and expires January 14, 2001. -Please send comments to: krb-protocol@MIT.EDU - - This document is getting closer to a last call, but there are several - issues to be discussed. Some, but not all of these issues, are - highlighted in comments in the draft. We hope to resolve these issues - on the mailing list for the Kerberos working group, leading up to and - during the Pittsburgh IETF on a section by section basis, since this - is a long document, and it has been difficult to consider it as a - whole. Once sections are agreed to, it is out intent to issue the more - formal WG and IETF last calls. - -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. - - -Neuman, Ts'o, Kohl Expires: 14 January -2001 - -^L - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-06 July 14, -2000 - -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 -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 - -Neuman, Ts'o, Kohl Expires: 14 January -2001 - -^L - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-06 July 14, -2000 - -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 -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 - -Neuman, Ts'o, Kohl Expires: 14 January -2001 - -^L - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-06 July 14, -2000 - -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 -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. - - -Neuman, Ts'o, Kohl Expires: 14 January -2001 - -^L - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-06 July 14, -2000 - - [JBrezak] Should there be a section here on how clients determine what - realm a service is in? Something like: - - The client may not immediately know what realm a particular service - principal is in. There are 2 basic mechanisms that can be used to - determine the realm of a service. The first requires that the client - fully specify the service principal including the realm in the - Kerberos protocol request. If the Kerberos server for the specified - realm does not have a principal that exactly matches the service in - the request, the Kerberos server will return an error indicating that - the service principal was not found. Alternatively the client can make - a request providing just the service principal name and requesting - name canonicalization from the Kerberos server. The Kerberos server - will attempt to locate a service principal in its database that best - matches the request principal or provide a referral to another - Kerberos realm that may be contain the requested service principal. - -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. -Separately authenticated authorization credentials may be embedded in a -tickets authorization data when encapsulated by the kdc-issued -authorization data element. - -Applications should not be modified to accept the mere issuance of a -service ticket by the Kerberos server (even by a 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: 14 January -2001 - -^L - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-06 July 14, -2000 - - * 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). -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. - -Neuman, Ts'o, Kohl Expires: 14 January -2001 - -^L - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-06 July 14, -2000 - -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. - -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). - - -Neuman, Ts'o, Kohl Expires: 14 January -2001 - -^L - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-06 July 14, -2000 - -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 -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. - - -Neuman, Ts'o, Kohl Expires: 14 January -2001 - -^L - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-06 July 14, -2000 - -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. - -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. - - -Neuman, Ts'o, Kohl Expires: 14 January -2001 - -^L - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-06 July 14, -2000 - -2.7 Name canonicalization [JBrezak] - -If a client does not have the full name information for a principal, it can -request that the Kerberos server attempt to lookup the name in its database -and return a canonical form of the requested principal or a referral to a -realm that has the requested principal in its namespace. Name -canonicalization allows a principal to have alternate names. Name -canonicalization must not be used to locate principal names supplied from -wildcards and is not a mechanism to be used to search a Kerberos database. - -The CANONICALIZE flag in a ticket request is used to indicate to the -Kerberos server that the client will accept an alternative name to the -principal in the request or a referral to another realm. Both the AS and -TGS must be able to interpret requests with this flag. - -By using this flag, the client can avoid extensive configuration needed to -map specific host names to a particular realm. - -2.8. 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. - - -Neuman, Ts'o, Kohl Expires: 14 January -2001 - -^L - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-06 July 14, -2000 - -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; whether -the client requests name-canonicalization; 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 -the requested client principal named in the request is not found in its -database, then an error message with a KDC_ERR_C_PRINCIPAL_UNKNOWN is -returned. If the request had the CANONICALIZE option set, then the AS can -attempt to lookup the client principal name in an alternate database, if it -is found an error message with a KDC_ERR_WRONG_REALM error code and the -cname and crealm in the error message must contain the true client -principal name and realm. - -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]. - - -Neuman, Ts'o, Kohl Expires: 14 January -2001 - -^L - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-06 July 14, -2000 - -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. DES3-CBC-SHA1 and DES3-CBC-SHA1-KD), 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. - - JBrezak - the behavior of PW-SALT, and ETYPE-INFO should be explained - here; also about using keys that have different string-to-key - functions like AFSsalt - -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 - 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. - - -Neuman, Ts'o, Kohl Expires: 14 January -2001 - -^L - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-06 July 14, -2000 - -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. If the client set the CANONICALIZE option and a -KDC_ERR_WRONG_REALM error was returned, the AS request should be retried to -the realm and client principal name specified in the error message crealm -and cname field respectively. - -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. - - -Neuman, Ts'o, Kohl Expires: 14 January -2001 - -^L - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-06 July 14, -2000 - -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 -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). - - -Neuman, Ts'o, Kohl Expires: 14 January -2001 - -^L - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-06 July 14, -2000 - -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 -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 - -Neuman, Ts'o, Kohl Expires: 14 January -2001 - -^L - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-06 July 14, -2000 - -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 -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: 14 January -2001 - -^L - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-06 July 14, -2000 - -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 it is -known. If the client does know the service principal name and realm and it -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. - -If the client does not know the realm of the service or the true service -principal name, then the CANONICALIZE option must be used in the request. -This will cause the TGS to locate the service principal based on the target -service name in the ticket and return the service principal name in the -response. Alternatively, the Kerberos server may return a TGT for a realm -which is 'closer' to the desired realm (further along the standard - -Neuman, Ts'o, Kohl Expires: 14 January -2001 - -^L - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-06 July 14, -2000 - -hierarchical path) or the realm that may contain the requested service -principal name in a request with the CANONCALIZE option set [JBrezak], 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. If the CANONICALIZE option is -set in the KRB_TGS_REQ, then the requested service name may not be the true -principal name or the service may not be in the TGS realm. - - -Neuman, Ts'o, Kohl Expires: 14 January -2001 - -^L - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-06 July 14, -2000 - -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. If the CANONICALIZE option is set, the TGS may return a -ticket containing the server name of the true service principal. If the -requested server cannot be found in the TGS database, then a TGT for -another trusted realm may be returned instead of a ticket for the service. -This TGT is a referral mechanism to cause the client to retry the request -to the realm of the TGT. These are the only cases where the response for -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 - -Neuman, Ts'o, Kohl Expires: 14 January -2001 - -^L - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-06 July 14, -2000 - -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 -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). - - -Neuman, Ts'o, Kohl Expires: 14 January -2001 - -^L - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-06 July 14, -2000 - -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. - -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. The server name returned in the reply is the true principal name of -the service. See section A.7 for pseudocode. - - -Neuman, Ts'o, Kohl Expires: 14 January -2001 - -^L - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-06 July 14, -2000 - -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 -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. - - -Neuman, Ts'o, Kohl Expires: 14 January -2001 - -^L - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-06 July 14, -2000 - -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 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. - - -Neuman, Ts'o, Kohl Expires: 14 January -2001 - -^L - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-06 July 14, -2000 - -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. - -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[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 - -Neuman, Ts'o, Kohl Expires: 14 January -2001 - -^L - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-06 July 14, -2000 - -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. - -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. - - -Neuman, Ts'o, Kohl Expires: 14 January -2001 - -^L - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-06 July 14, -2000 - -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 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]. - - -Neuman, Ts'o, Kohl Expires: 14 January -2001 - -^L - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-06 July 14, -2000 - -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 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: 14 January -2001 - -^L - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-06 July 14, -2000 - -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 io - -- reserved(0), - -- forwardable(1), - -- forwarded(2), - -- proxiable(3), - -- proxy(4), - -- allow-postdate(5), - -- postdated(6), - -- unused7(7), - -- renewable(8), - -- unused9(9), - -Neuman, Ts'o, Kohl Expires: 14 January -2001 - -^L - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-06 July 14, -2000 - - -- unused10(10), - -- unused11(11), - -- unused12(12), - -- unused13(13), - -- requestanonymous(14), - -- canonicalize(15), - -- 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: 14 January -2001 - -^L - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-06 July 14, -2000 - -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 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. - - -Neuman, Ts'o, Kohl Expires: 14 January -2001 - -^L - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-06 July 14, -2000 - - 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. - - 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. - - -Neuman, Ts'o, Kohl Expires: 14 January -2001 - -^L - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-06 July 14, -2000 - - 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 - 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. - -Neuman, Ts'o, Kohl Expires: 14 January -2001 - -^L - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-06 July 14, -2000 - - 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 - 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 Kerberos - 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. - -Neuman, Ts'o, Kohl Expires: 14 January -2001 - -^L - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-06 July 14, -2000 - -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. -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, except when an entry is separately authenticated by - encapulation in the kdc-issued element, 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). - - -Neuman, Ts'o, Kohl Expires: 14 January -2001 - -^L - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-06 July 14, -2000 - - 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), - may obtain 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. Alternatively, such authorization credentials - may be embedded in the ticket authenticating the authorized entity, - when the authorization is separately authenticated using the - kdc-issued authorization data element (see B.4). - - 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. -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. - -Neuman, Ts'o, Kohl Expires: 14 January -2001 - -^L - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-06 July 14, -2000 - -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. -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 -} - - -Neuman, Ts'o, Kohl Expires: 14 January -2001 - -^L - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-06 July 14, -2000 - -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 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. When - this field is used to authenticate or pre-authenticate a request, it - should contain a keyed checksum over the KDC-REQ-BODY to bind the - pre-authentication data to rest of the request. The KDC, as a matter - of policy, may decide whether to honor a KDC-REQ which includes any - pre-authentication data that does not contain the checksum field. - PA-ENC-TIMESTAMP defines a pre-authentication data type that is used - for authenticating a client by way of an encrypted timestamp. This is - accomplished with a padata field with padata-type equal to - PA-ENC-TIMESTAMP and padata-value defined as follows (query: the - checksum is new in this definition. If the optional field will break - things we can keep the old PA-ENC-TS-ENC, and define a new alternate - form that includes the checksum). : - - -Neuman, Ts'o, Kohl Expires: 14 January -2001 - -^L - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-06 July 14, -2000 - - 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, - pachecksum[2] checksum OPTIONAL - -- keyed checksum of -KDC-REQ-BODY - } - - 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 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: - - -Neuman, Ts'o, Kohl Expires: 14 January -2001 - -^L - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-06 July 14, -2000 - - 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. - - 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. - - -Neuman, Ts'o, Kohl Expires: 14 January -2001 - -^L - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-06 July 14, -2000 - - 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 RESERVED - Reserved for PK-Cross - - 10-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 CANONICALIZE - The CANONICALIZE option indicates that - the client will accept the return of a - true server name instead of the name - specified in the request. In addition - the client will be able to process - any TGT referrals that will direct - the client to another realm to locate - the requested server. If a KDC does - not support name- canonicalization, - the option is ignored and the - appropriate - KDC_ERR_C_PRINCIPAL_UNKNOWN or - KDC_ERR_S_PRINCIPAL_UNKNOWN error is - returned. [JBrezak] - - 16-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 - -Neuman, Ts'o, Kohl Expires: 14 January -2001 - -^L - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-06 July 14, -2000 - - 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 - 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. - - -Neuman, Ts'o, Kohl Expires: 14 January -2001 - -^L - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-06 July 14, -2000 - -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. If the CANONICALIZE option is set, the - realm is used as a hint to the KDC for its database lookup. -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 - 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. When he - ENC-TKT-IN-SKEY option is used for user-to-user authentication, this - addional ticket may be a TGT issued by the local realm or an - inter-realm TGT issued for the current KDC's realm by a remote KDC. 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). - - -Neuman, Ts'o, Kohl Expires: 14 January -2001 - -^L - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-06 July 14, -2000 - -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[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. - -Neuman, Ts'o, Kohl Expires: 14 January -2001 - -^L - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-06 July 14, -2000 - -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 - 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. - - -Neuman, Ts'o, Kohl Expires: 14 January -2001 - -^L - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-06 July 14, -2000 - -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 - 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. - - -Neuman, Ts'o, Kohl Expires: 14 January -2001 - -^L - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-06 July 14, -2000 - -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 - 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). - - -Neuman, Ts'o, Kohl Expires: 14 January -2001 - -^L - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-06 July 14, -2000 - -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. -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. - - -Neuman, Ts'o, Kohl Expires: 14 January -2001 - -^L - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-06 July 14, -2000 - -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 - 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 -} - - -Neuman, Ts'o, Kohl Expires: 14 January -2001 - -^L - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-06 July 14, -2000 - -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. - 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: 14 January -2001 - -^L - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-06 July 14, -2000 - -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, -} - - - -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. - -Neuman, Ts'o, Kohl Expires: 14 January -2001 - -^L - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-06 July 14, -2000 - -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. - - 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], and triple DES variants, 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 - -Neuman, Ts'o, Kohl Expires: 14 January -2001 - -^L - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-06 July 14, -2000 - - 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 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. - -Neuman, Ts'o, Kohl Expires: 14 January -2001 - -^L - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-06 July 14, -2000 - - 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 for some - methods is described in the following diagram, but other methods may - deviate from this layour - so long as the definition of the method - defines the layout actually in use. - - +-----------+----------+-------------+-----+ - |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 - - -Neuman, Ts'o, Kohl Expires: 14 January -2001 - -^L - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-06 July 14, -2000 - - 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. - - 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. - - -Neuman, Ts'o, Kohl Expires: 14 January -2001 - -^L - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-06 July 14, -2000 - - 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 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: - - -Neuman, Ts'o, Kohl Expires: 14 January -2001 - -^L - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-06 July 14, -2000 - - 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 and - without Key Derivation [Original draft by Marc Horowitz, revisions by - David Miller] - - There are still a few pieces of this specification to be included - by falue, rather than by reference. This will be done before the - Pittsburgh IETF. - This encryption type is based on the Triple DES cryptosystem, the - HMAC-SHA1 [Krawczyk96] message authentication algorithm, and key - derivation for Kerberos V5 [HorowitzB96]. Key derivation may or may - not be used in conjunction with the use of Triple DES keys. - - Algorithm Identifiers - - The des3-cbc-hmac-sha1 encryption type has been assigned the value 7. - The des3-cbc-hmac-sha1-kd encryption type, specifying the key - derivation variant of the encryption type, has been assigned the value - 16. The hmac-sha1-des3 checksum type has been assigned the value 13. - The hmac-sha1-des3-kd checksum type, specifying the key derivation - variant of the checksum, has been assigned the value 12. - - Triple DES Key Production - - 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: 14 January -2001 - -^L - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-06 July 14, -2000 - - 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. - - The string-to-key function is used to tranform UNICODE passwords into - DES3 keys. The DES3 string-to-key function relies on the "N-fold" - algorithm, which is detailed in [9]. The description of the N-fold - algorithm in that document is as follows: - o 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 is rotated to the right by 13 bit - positions. The successive n-bit chunks are added together using - 1's-complement addition (that is, addition with end-around carry) - to yield an n-bit result" - o The n-fold algorithm, as with DES string-to-key, is applied to - the password string concatenated with a salt value. The salt - value is derived in the same was as for the DES string-to-key - algorithm. For 3-key triple DES then, the operation will involve - a 168-fold of the input password string. The remainder of the - string-to-key function for DES3 is shown here in pseudocode: - - DES3string-to-key(passwordString, key) - - salt = name_to_default_salt(realm, name) - s = passwordString + salt - tmpKey1 = 168-fold(s) - parityFix(tmpKey1); - if not weakKey(tmpKey1) - /* - * Encrypt temp key in itself with a - * zero initialization vector - * - * Function signature is DES3encrypt(plain, key, iv) - * with cipher as the return value - */ - tmpKey2 = DES3encrypt(tmpKey1, tmpKey1, zeroIvec) - /* - * Encrypt resultant temp key in itself with third component - * of first temp key as initialization vector - */ - key = DES3encrypt(tmpKey2, tmpKey1, tmpKey1[2]) - parityFix(key) - if not weakKey(key) - return SUCCESS - else - return FAILURE - else - return FAILURE - - -Neuman, Ts'o, Kohl Expires: 14 January -2001 - -^L - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-06 July 14, -2000 - - The weakKey function above is the same weakKey function used with DES - keys, but applied to each of the three single DES keys that comprise - the triple DES key. - - The lengths of UNICODE encoded character strings include the trailing - terminator character (0). - - Encryption Types des3-cbc-hmac-sha1 and des3-cbc-hmac-sha1-kd - - EncryptedData using this type must be generated as described in - [Horowitz96]. The encryption algorithm is Triple DES in Outer-CBC - mode. The checksum algorithm is HMAC-SHA1. If the key derivation - variant of the encryption type is used, encryption key values are - modified according to the method under the Key Derivation section - below. - - 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 Types hmac-sha1-des3 and hmac-sha1-des3-kd - - Checksums using this type must be generated as described in - [Horowitz96]. The keyed hash algorithm is HMAC-SHA1. If the key - derivation variant of the checksum type is used, checksum key values - are modified according to the method under the Key Derivation section - below. - - 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) - -Neuman, Ts'o, Kohl Expires: 14 January -2001 - -^L - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-06 July 14, -2000 - - 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 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: 14 January -2001 - -^L - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-06 July 14, -2000 - - 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 required 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: 14 January -2001 - -^L - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-06 July 14, -2000 - - 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 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. - - -Neuman, Ts'o, Kohl Expires: 14 January -2001 - -^L - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-06 July 14, -2000 - - 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 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. - - -Neuman, Ts'o, Kohl Expires: 14 January -2001 - -^L - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-06 July 14, -2000 - - 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 (/). Though domain names themselves are case insensitive, in - order for realms to match, the case must match as well. When - establishing a new realm name based on an internet domain name it is - recommended by convention that the characters be converted to upper - case. - - 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. - - -Neuman, Ts'o, Kohl Expires: 14 January -2001 - -^L - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-06 July 14, -2000 - - 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, DCE -principal) - NT-SRV-INST 2 Service and other unique instance (krbtgt) - NT-SRV-HST 3 Service with host name as instance (telnet, rcmds) - 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] - NT-SMTP-NAME 7 Name in form of SMTP email name (e.g. -user@foo.com) - - 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. - - -Neuman, Ts'o, Kohl Expires: 14 January -2001 - -^L - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-06 July 14, -2000 - - 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 SMTP allows a name to be of a form that resembles a - SMTP email name. This name type can be used in conjunction with - name-canonicalization to allow a free-form of username to be specified - as a client name and allow the KDC to determine the Kerberos principal - name for the requested name. [JBrezak] - - 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). - - Internet (IPv6) Addresses [Westerlund] - - -Neuman, Ts'o, Kohl Expires: 14 January -2001 - -^L - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-06 July 14, -2000 - - 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: - o the Unspecified Address - o the Loopback Address - o 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. - - 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 - -Neuman, Ts'o, Kohl Expires: 14 January -2001 - -^L - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-06 July 14, -2000 - - 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. - - 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). - - -Neuman, Ts'o, Kohl Expires: 14 January -2001 - -^L - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-06 July 14, -2000 - - 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 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 - reserved 4 - des3-cbc-md5 5 8 0 8 - reserved 6 - des3-cbc-sha1 7 8 0 8 - 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) - des3-cbc-sha1-kd 16 (Tom -Yu) - rc4-hmac 23 -(swift) - rc4-hmac-exp 24 -(swift) - - reserved 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 (drop rsa ?) - rsa-md5 7 16 (drop rsa ?) - rsa-md5-des 8 24 (drop rsa ?) - rsa-md5-des3 9 24 (drop rsa ?) - hmac-sha1-des3-kd 12 20 - hmac-sha1-des3 13 20 - sha1 (unkeyed) 14 20 - - padata type padata-type value - - PA-TGS-REQ 1 - PA-ENC-TIMESTAMP 2 - PA-PW-SALT 3 - reserved 4 - PA-ENC-UNIX-TIME 5 (depricated) - PA-SANDIA-SECUREID 6 - PA-SESAME 7 - PA-OSF-DCE 8 - PA-CYBERSAFE-SECUREID 9 - PA-AFS3-SALT 10 - PA-ETYPE-INFO 11 - PA-SAM-CHALLENGE 12 (sam/otp) - PA-SAM-RESPONSE 13 (sam/otp) - PA-PK-AS-REQ 14 (pkinit) - PA-PK-AS-REP 15 (pkinit) - PA-USE-SPECIFIED-KVNO 20 - PA-SAM-REDIRECT 21 (sam/otp) - PA-GET-FROM-TYPED-DATA 22 - PA-SAM-ETYPE-INFO 23 (sam/otp) - - -Neuman, Ts'o, Kohl Expires: 14 January -2001 - -^L - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-06 July 14, -2000 - - data-type value form of typed-data - - reserved 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 - TD-APP-DEFINED-ERROR 106 - - 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 - AD-OSF-DCE-PKI-CERTID 66 (hemsath@us.ibm.com) - AD-WIN200-PAC 128 -(jbrezak@exchange.microsoft.com) - - Ticket Extension Types - - TE-TYPE-NULL 0 Null ticket extension - TE-TYPE-EXTERNAL-ADATA 1 Integrity protected authorization -data - reserved 2 TE-TYPE-PKCROSS-KDC - TE-TYPE-PKCROSS-CLIENT 3 PKCROSS cross realm key ticket - TE-TYPE-CYBERSAFE-EXT 4 Assigned to CyberSafe Corp - reserved 5 TE-TYPE-DEST-HOST - - 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 - - -Neuman, Ts'o, Kohl Expires: 14 January -2001 - -^L - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-06 July 14, -2000 - - 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 - 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 - -Neuman, Ts'o, Kohl Expires: 14 January -2001 - -^L - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-06 July 14, -2000 - - 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. - - 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. - - Encryption: DES-CBC-MD5, one triple des variant (tbd) - Checksums: CRC-32, DES-MAC, DES-MAC-K, and DES-MD5 (tbd) - - 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. - - -Neuman, Ts'o, Kohl Expires: 14 January -2001 - -^L - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-06 July 14, -2000 - - 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. - - 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. - - -Neuman, Ts'o, Kohl Expires: 14 January -2001 - -^L - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-06 July 14, -2000 - - 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, - "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). - - -Neuman, Ts'o, Kohl Expires: 14 January -2001 - -^L - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-06 July 14, -2000 - - [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, - 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. - - -Neuman, Ts'o, Kohl Expires: 14 January -2001 - -^L - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-06 July 14, -2000 - - 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); - - 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 - -Neuman, Ts'o, Kohl Expires: 14 January -2001 - -^L - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-06 July 14, -2000 - - 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 - - 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; - -Neuman, Ts'o, Kohl Expires: 14 January -2001 - -^L - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-06 July 14, -2000 - - 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, - -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; - -Neuman, Ts'o, Kohl Expires: 14 January -2001 - -^L - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-06 July 14, -2000 - - 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 - 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 - -Neuman, Ts'o, Kohl Expires: 14 January -2001 - -^L - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-06 July 14, -2000 - - 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 - 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 - - -Neuman, Ts'o, Kohl Expires: 14 January -2001 - -^L - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-06 July 14, -2000 - - 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 - - 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 - -Neuman, Ts'o, Kohl Expires: 14 January -2001 - -^L - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-06 July 14, -2000 - - - 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 - 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 - -Neuman, Ts'o, Kohl Expires: 14 January -2001 - -^L - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-06 July 14, -2000 - - 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 - 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); - -Neuman, Ts'o, Kohl Expires: 14 January -2001 - -^L - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-06 July 14, -2000 - - - 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 - /* 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 - -Neuman, Ts'o, Kohl Expires: 14 January -2001 - -^L - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-06 July 14, -2000 - - 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; - - 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 - -Neuman, Ts'o, Kohl Expires: 14 January -2001 - -^L - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-06 July 14, -2000 - - 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 - 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 - -Neuman, Ts'o, Kohl Expires: 14 January -2001 - -^L - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-06 July 14, -2000 - - 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 - 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; - -Neuman, Ts'o, Kohl Expires: 14 January -2001 - -^L - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-06 July 14, -2000 - - 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; - 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; - -Neuman, Ts'o, Kohl Expires: 14 January -2001 - -^L - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-06 July 14, -2000 - - 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 - - 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; - - -Neuman, Ts'o, Kohl Expires: 14 January -2001 - -^L - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-06 July 14, -2000 - - 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 */ - - /* 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 - -Neuman, Ts'o, Kohl Expires: 14 January -2001 - -^L - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-06 July 14, -2000 - - 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); - 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 - -Neuman, Ts'o, Kohl Expires: 14 January -2001 - -^L - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-06 July 14, -2000 - - (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 - - 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. - - -Neuman, Ts'o, Kohl Expires: 14 January -2001 - -^L - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-06 July 14, -2000 - - 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. 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. - - -Neuman, Ts'o, Kohl Expires: 14 January -2001 - -^L - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-06 July 14, -2000 - - 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.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 SEQUENCE { - te-type[0] INTEGER, - te-checksum[0] Checksum - } - - An authorization data element of type mandatory-ticket-extensions - specifies the type and 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 of the - type indicated. 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 type and - checksum do not match that checksum specified in the authorization - data element. Note that although the type is redundant for the - purposes of the comparison, it makes the comparison easier when - multiple extensions are present. Application servers that do not - implement this element must reject tickets that contain authorization - data elements of this type. - - -Neuman, Ts'o, Kohl Expires: 14 January -2001 - -^L - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-06 July 14, -2000 - - 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. - - 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. - -Neuman, Ts'o, Kohl Expires: 14 January -2001 - -^L - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-06 July 14, -2000 - - ---------------------------------------------------------------------- - [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. - - [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. - - -Neuman, Ts'o, Kohl Expires: 14 January -2001 - -^L - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-06 July 14, -2000 - - [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. - - [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. - - -Neuman, Ts'o, Kohl Expires: 14 January -2001 - -^L - -INTERNET-DRAFT draft-ietf-cat-kerberos-revisions-06 July 14, -2000 - - [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 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/crypto/heimdal/doc/standardisation/draft-ietf-cat-kerberos-set-passwd-02.txt b/crypto/heimdal/doc/standardisation/draft-ietf-cat-kerberos-set-passwd-02.txt deleted file mode 100644 index 6f7dae0dea70..000000000000 --- a/crypto/heimdal/doc/standardisation/draft-ietf-cat-kerberos-set-passwd-02.txt +++ /dev/null @@ -1,325 +0,0 @@ - -INTERNET-DRAFT Mike Swift -draft-ietf-cat-kerberos-set-passwd-02.txt Microsoft -March 2000 Jonathan Trostle - Cisco Systems - John Brezak - Microsoft - Bill Gossman - Cybersafe - - Kerberos Set/Change Password: Version 2 - - -0. 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. - - Comments and suggestions on this document are encouraged. Comments - on this document should be sent to the CAT working group discussion - list: - ietf-cat-wg@stanford.edu - -1. Abstract - - The Kerberos (RFC 1510 [3]) change password protocol (Horowitz [4]), - does not allow for an administrator to set a password for a new user. - This functionality is useful in some environments, and this proposal - extends [4] to allow password setting. The changes are: adding new - fields to the request message to indicate the principal which is - having its password set, not requiring the initial flag in the service - ticket, using a new protocol version number, and adding three new - result codes. We also extend the set/change protocol to allow a - client to send a sequence of keys to the KDC instead of a cleartext - password. If in the cleartext password case, the cleartext password - fails to satisfy password policy, the server should use the result - code KRB5_KPASSWD_POLICY_REJECT. - -2. Conventions used in this document - - 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. The Protocol - - The service must accept requests on UDP port 464 and TCP port 464 as - well. The protocol 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. - - For TCP transport, there is a 4 octet header in network byte order - precedes the message and specifies the length of the message. This - requirement is consistent with the TCP transport header in 1510bis. - -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 / - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - - All 16 bit fields are in network byte order. - - message length field: contains the number of bytes in the message - including this field. - - protocol version number: contains the hex constant 0x0002 (network - byte order). - - AP-REQ length: length of AP-REQ data, in bytes. If the length is zero, - then the last field contains a KRB-ERROR message instead of a KRB-PRIV - message. - - AP-REQ data: (see [3]) The AP-REQ message must be for the service - principal kadmin/changepw@REALM, where REALM is the REALM of the user - who wishes to change/set his password. The ticket in the AP-REQ must - must include a subkey in the Authenticator. To enable setting of - passwords/keys, it is not required that the initial flag be set in the - Kerberos service ticket. The initial flag is required for change requests, - but not for set password requests. We have the following definitions: - - old passwd initial flag target principal can be - in request? required? distinct from - authenticating principal? - - change password: yes yes no - - set password: no no yes - - set key: no policy yes - determined - - KRB-PRIV message (see [3]) This KRB-PRIV message must be generated - using the subkey from the authenticator in the AP-REQ data. - - The user-data component of the message consists of the following ASN.1 - structure encoded as an OCTET STRING: - - ChangePasswdData :: = SEQUENCE { - newpasswdorkeys[0] NewPasswdOrKeys, - targname[1] PrincipalName OPTIONAL, - -- only present in set password: the principal - -- which will have its password set - targrealm[2] Realm OPTIONAL, - -- only present in set password: the realm for - -- the principal which will have its password set - - } - - NewPasswdOrKeys :: = CHOICE { - passwords[0] PasswordSequence, - keyseq[1] KeySequences - } - - KeySequences :: = SEQUENCE OF KeySequence - - KeySequence :: = SEQUENCE { - key[0] EncryptionKey, - salt[1] OCTET STRING OPTIONAL, - salt-type[2] INTEGER OPTIONAL - } - - PasswordSequence :: = SEQUENCE { - newpasswd[0] OCTET STRING, - oldpasswd[1] OCTET STRING OPTIONAL - -- oldpasswd always present for change password - -- but not present for set password - } - - The server must verify the AP-REQ message, check whether the client - principal in the ticket is authorized to set or change the password - (either for that principal, or for the principal in the targname - field if present), and decrypt the new password/keys. The server - also checks whether the initial flag is required for this request, - replying with status 0x0007 if it is not set and should be. An - authorization failure is cause to respond with status 0x0005. For - forward compatibility, the server should be prepared to ignore fields - after targrealm in the structure that it does not understand. - - The newpasswdorkeys field contains either the new cleartext password - (with the old cleartext password for a change password operation), - or a sequence of encryption keys with their respective salts. - - In the cleartext password case, if the old password is sent in the - request, the request is defined to be a change password request. If - the old password is not present in the request, the request is a set - password request. The server should apply policy checks to the old - and new password after verifying that the old password is valid. - The server can check validity by obtaining a key from the old - password with a keytype that is present in the KDC database for the - user and comparing the keys for equality. The server then generates - the appropriate keytypes from the password and stores them in the KDC - - database. If all goes well, status 0x0000 is returned to the client - in the reply message (see below). For a change password operation, - the initial flag in the service ticket MUST be set. - - In the key sequence case, the sequence of keys is sent to the set - password service. For a principal that can act as a server, its - preferred keytype should be sent as the first key in the sequence, - but the KDC is not required to honor this preference. Application - servers should use the key sequence option for changing/setting their - keys. The set password service should check that all keys are in the - proper format, returning the KRB5_KPASSWD_MALFORMED error otherwise. - -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 message / - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - - - All 16 bit fields are in network byte order. - - message length field: contains the number of bytes in the message - including this field. - - protocol version number: contains the hex constant 0x0002 (network - byte order). (The reply message has the same format as in [4]). - - AP-REP length: length of AP-REP data, in bytes. If the length is zero, - then the last field contains a KRB-ERROR message instead of a KRB-PRIV - message. - - AP-REP data: the AP-REP is the response to the AP-REQ in the request - packet. - - KRB-PRIV from [4]: This KRB-PRIV message must be generated using the - subkey in the authenticator in the AP-REQ data. - - The server will respond with a KRB-PRIV message unless it cannot - validate the client AP-REQ or KRB-PRIV message, in which case it will - respond with a KRB-ERROR message. NOTE: Unlike change password version - 1, the KRB-ERROR message will be sent back without any encapsulation. - - 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 / - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | edata / - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - - result code (16 bits) (result codes 0-4 are from [4]): - The result code must have one of the following values (network - byte order): - KRB5_KPASSWD_SUCCESS 0 request succeeds (This value is not - allowed in a KRB-ERROR message) - KRB5_KPASSWD_MALFORMED 1 request fails due to being malformed - KRB5_KPASSWD_HARDERROR 2 request fails due to "hard" error in - processing the request (for example, - there is a resource or other problem - causing the request to fail) - KRB5_KPASSWD_AUTHERROR 3 request fails due to an error in - authentication processing - KRB5_KPASSWD_SOFTERROR 4 request fails due to a soft error - in processing the request - KRB5_KPASSWD_ACCESSDENIED 5 requestor not authorized - KRB5_KPASSWD_BAD_VERSION 6 protocol version unsupported - KRB5_KPASSWD_INITIAL_FLAG_NEEDED 7 initial flag required - KRB5_KPASSWD_POLICY_REJECT 8 new cleartext password fails policy; - the result string should include a text message to be presented - to the user. - KRB5_KPASSWD_BAD_PRINCIPAL 9 target principal does not exist - (only in response to a set password request). - KRB5_KPASSWD_ETYPE_NOSUPP 10 the request contains a key sequence - containing at least one etype that is not supported by the KDC. - The response edata contains an ASN.1 encoded PKERB-ETYPE-INFO - type that specifies the etypes that the KDC supports: - - KERB-ETYPE-INFO-ENTRY :: = SEQUENCE { - encryption-type[0] INTEGER, - salt[1] OCTET STRING OPTIONAL -- not sent - } - - PKERB-ETYPE-INFO ::= SEQUENCE OF KERB-ETYPE-INFO-ENTRY - - The client should retry the request using only etypes (keytypes) - that are contained within the PKERB-ETYPE-INFO structure in the - previous response. - 0xFFFF if the request fails for some other reason. - The client must interpret any non-zero result code as a failure. - result string - from [4]: - This field is a UTF-8 encoded string which should be displayed - to the user by the client. Specific reasons for a password - set/change policy failure is one use for this string. - edata: used to convey additional information as defined by the - result code. - -4. 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] J. Kohl, C. Neuman. The Kerberos Network Authentication - Service (V5), Request for Comments 1510. - - [4] M. Horowitz. Kerberos Change Password Protocol, - ftp://ds.internic.net/internet-drafts/ - draft-ietf-cat-kerb-chg-password-02.txt - -5. Expiration Date - - This draft expires in September 2000. - -6. Authors' Addresses - - Jonathan Trostle - Cisco Systems - 170 W. Tasman Dr. - San Jose, CA 95134 - Email: jtrostle@cisco.com - - Mike Swift - 1 Microsoft Way - Redmond, WA 98052 - Email: mikesw@microsoft.com - - John Brezak - 1 Microsoft Way - Redmond, WA 98052 - Email: jbrezak@microsoft.com - - Bill Gossman - Cybersafe Corporation - 1605 NW Sammamish Rd. - Issaquah, WA 98027-5378 - Email: bill.gossman@cybersafe.com - diff --git a/crypto/heimdal/doc/standardisation/draft-ietf-cat-kerberos-set-passwd-03.txt b/crypto/heimdal/doc/standardisation/draft-ietf-cat-kerberos-set-passwd-03.txt deleted file mode 100644 index 0319f8bf347c..000000000000 --- a/crypto/heimdal/doc/standardisation/draft-ietf-cat-kerberos-set-passwd-03.txt +++ /dev/null @@ -1,345 +0,0 @@ - -INTERNET-DRAFT Mike Swift -draft-ietf-cat-kerberos-set-passwd-03.txt Microsoft -April 2000 Jonathan Trostle - Cisco Systems - John Brezak - Microsoft - Bill Gossman - Cybersafe - - Kerberos Set/Change Password: Version 2 - - -0. 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. - - Comments and suggestions on this document are encouraged. Comments - on this document should be sent to the CAT working group discussion - list: - ietf-cat-wg@stanford.edu - -1. Abstract - - The Kerberos (RFC 1510 [3]) change password protocol (Horowitz [4]), - does not allow for an administrator to set a password for a new user. - This functionality is useful in some environments, and this proposal - extends [4] to allow password setting. The changes are: adding new - fields to the request message to indicate the principal which is - having its password set, not requiring the initial flag in the service - ticket, using a new protocol version number, and adding three new - result codes. We also extend the set/change protocol to allow a - client to send a sequence of keys to the KDC instead of a cleartext - password. If in the cleartext password case, the cleartext password - fails to satisfy password policy, the server should use the result - code KRB5_KPASSWD_POLICY_REJECT. - -2. Conventions used in this document - - 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. The Protocol - - The service must accept requests on UDP port 464 and TCP port 464 as - well. The protocol 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. - - For TCP transport, there is a 4 octet header in network byte order - precedes the message and specifies the length of the message. This - requirement is consistent with the TCP transport header in 1510bis. - -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 / - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - - All 16 bit fields are in network byte order. - - message length field: contains the number of bytes in the message - including this field. - - protocol version number: contains the hex constant 0x0002 (network - byte order). - - AP-REQ length: length of AP-REQ data, in bytes. If the length is zero, - then the last field contains a KRB-ERROR message instead of a KRB-PRIV - message. - - AP-REQ data: (see [3]) For a change password/key request, the AP-REQ - message service ticket sname, srealm principal identifier is - kadmin/changepw@REALM where REALM is the realm of the change password - service. The same applies to a set password/key request except the - principal identifier is kadmin/setpw@REALM. The ticket in the AP-REQ - must include a subkey in the Authenticator. To enable setting of - passwords/keys, it is not required that the initial flag be set in the - Kerberos service ticket. The initial flag is required for change requests, - but not for set requests. We have the following definitions: - - old passwd initial flag target principal can be - in request? required? distinct from - authenticating principal? - - change password: yes yes no - - set password: no policy (*) yes - - set key: no policy (*) yes - - change key: no yes no - - policy (*): implementations SHOULD allow administrators to set the - initial flag required for set requests policy to either yes or no. - Clients MUST be able to retry set requests that fail due to error 7 - (initial flag required) with an initial ticket. Clients SHOULD NOT - cache service tickets targetted at kadmin/changepw. - - KRB-PRIV message (see [3]) This KRB-PRIV message must be generated - using the subkey from the authenticator in the AP-REQ data. - - The user-data component of the message consists of the following ASN.1 - structure encoded as an OCTET STRING: - - ChangePasswdData :: = SEQUENCE { - newpasswdorkeys[0] NewPasswdOrKeys, - targname[1] PrincipalName OPTIONAL, - -- only present in set password/key: the principal - -- which will have its password or keys set. Not - -- present in a set request if the client principal - -- from the ticket is the principal having its - -- passwords or keys set. - targrealm[2] Realm OPTIONAL, - -- only present in set password/key: the realm for - -- the principal which will have its password or - -- keys set. Not present in a set request if the - -- client principal from the ticket is the principal - -- having its passwords or keys set. - } - - NewPasswdOrKeys :: = CHOICE { - passwords[0] PasswordSequence, -- change/set passwd - keyseq[1] KeySequences -- change/set key - } - - KeySequences :: = SEQUENCE OF KeySequence - - KeySequence :: = SEQUENCE { - key[0] EncryptionKey, - salt[1] OCTET STRING OPTIONAL, - salt-type[2] INTEGER OPTIONAL - } - - PasswordSequence :: = SEQUENCE { - newpasswd[0] OCTET STRING, - oldpasswd[1] OCTET STRING OPTIONAL - -- oldpasswd always present for change password - -- but not present for set password, set key, or - -- change key - } - - The server must verify the AP-REQ message, check whether the client - principal in the ticket is authorized to set or change the password - (either for that principal, or for the principal in the targname - field if present), and decrypt the new password/keys. The server - also checks whether the initial flag is required for this request, - replying with status 0x0007 if it is not set and should be. An - authorization failure is cause to respond with status 0x0005. For - forward compatibility, the server should be prepared to ignore fields - after targrealm in the structure that it does not understand. - - The newpasswdorkeys field contains either the new cleartext password - (with the old cleartext password for a change password operation), - or a sequence of encryption keys with their respective salts. - - In the cleartext password case, if the old password is sent in the - request, the request MUST be a change password request. If the old - password is not present in the request, the request MUST be a set - password request. The server should apply policy checks to the old - and new password after verifying that the old password is valid. - The server can check validity by obtaining a key from the old - password with a keytype that is present in the KDC database for the - user and comparing the keys for equality. The server then generates - the appropriate keytypes from the password and stores them in the KDC - database. If all goes well, status 0x0000 is returned to the client - in the reply message (see below). For a change password operation, - the initial flag in the service ticket MUST be set. - - In the key sequence case, the sequence of keys is sent to the change - or set password service (kadmin/changepw or kadmin/setpw respectively). - For a principal that can act as a server, its preferred keytype should - be sent as the first key in the sequence, but the KDC is not required - to honor this preference. Application servers should use the key - sequence option for changing/setting their keys. The change/set password - services should check that all keys are in the proper format, returning - the KRB5_KPASSWD_MALFORMED error otherwise. - -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 message / - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - - - All 16 bit fields are in network byte order. - - message length field: contains the number of bytes in the message - including this field. - - protocol version number: contains the hex constant 0x0002 (network - byte order). (The reply message has the same format as in [4]). - - AP-REP length: length of AP-REP data, in bytes. If the length is zero, - then the last field contains a KRB-ERROR message instead of a KRB-PRIV - message. - - AP-REP data: the AP-REP is the response to the AP-REQ in the request - packet. - - KRB-PRIV from [4]: This KRB-PRIV message must be generated using the - subkey in the authenticator in the AP-REQ data. - - The server will respond with a KRB-PRIV message unless it cannot - validate the client AP-REQ or KRB-PRIV message, in which case it will - respond with a KRB-ERROR message. NOTE: Unlike change password version - 1, the KRB-ERROR message will be sent back without any encapsulation. - - 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 / - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | edata / - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - - result code (16 bits) (result codes 0-4 are from [4]): - The result code must have one of the following values (network - byte order): - KRB5_KPASSWD_SUCCESS 0 request succeeds (This value is not - allowed in a KRB-ERROR message) - KRB5_KPASSWD_MALFORMED 1 request fails due to being malformed - KRB5_KPASSWD_HARDERROR 2 request fails due to "hard" error in - processing the request (for example, - there is a resource or other problem - causing the request to fail) - KRB5_KPASSWD_AUTHERROR 3 request fails due to an error in - authentication processing - KRB5_KPASSWD_SOFTERROR 4 request fails due to a soft error - in processing the request - KRB5_KPASSWD_ACCESSDENIED 5 requestor not authorized - KRB5_KPASSWD_BAD_VERSION 6 protocol version unsupported - KRB5_KPASSWD_INITIAL_FLAG_NEEDED 7 initial flag required - KRB5_KPASSWD_POLICY_REJECT 8 new cleartext password fails policy; - the result string should include a text message to be presented - to the user. - KRB5_KPASSWD_BAD_PRINCIPAL 9 target principal does not exist - (only in response to a set password request). - KRB5_KPASSWD_ETYPE_NOSUPP 10 the request contains a key sequence - containing at least one etype that is not supported by the KDC. - The response edata contains an ASN.1 encoded PKERB-ETYPE-INFO - type that specifies the etypes that the KDC supports: - - KERB-ETYPE-INFO-ENTRY :: = SEQUENCE { - encryption-type[0] INTEGER, - salt[1] OCTET STRING OPTIONAL -- not sent - } - - PKERB-ETYPE-INFO ::= SEQUENCE OF KERB-ETYPE-INFO-ENTRY - - The client should retry the request using only etypes (keytypes) - that are contained within the PKERB-ETYPE-INFO structure in the - previous response. - 0xFFFF if the request fails for some other reason. - The client must interpret any non-zero result code as a failure. - result string - from [4]: - This field is a UTF-8 encoded string which should be displayed - to the user by the client. Specific reasons for a password - - set/change policy failure is one use for this string. - edata: used to convey additional information as defined by the - result code. - -4. Acknowledgements - - The authors thank Tony Andrea for his input to the document. - -5. 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] J. Kohl, C. Neuman. The Kerberos Network Authentication - Service (V5), Request for Comments 1510. - - [4] M. Horowitz. Kerberos Change Password Protocol, - ftp://ds.internic.net/internet-drafts/ - draft-ietf-cat-kerb-chg-password-02.txt - -6. Expiration Date - - This draft expires in October 2000. - -7. Authors' Addresses - - Jonathan Trostle - Cisco Systems - 170 W. Tasman Dr. - San Jose, CA 95134 - Email: jtrostle@cisco.com - - Mike Swift - 1 Microsoft Way - Redmond, WA 98052 - Email: mikesw@microsoft.com - - John Brezak - 1 Microsoft Way - Redmond, WA 98052 - Email: jbrezak@microsoft.com - - Bill Gossman - Cybersafe Corporation - 1605 NW Sammamish Rd. - Issaquah, WA 98027-5378 - Email: bill.gossman@cybersafe.com - diff --git a/crypto/heimdal/doc/standardisation/draft-ietf-cat-krb-dns-locate-00.txt b/crypto/heimdal/doc/standardisation/draft-ietf-cat-krb-dns-locate-00.txt deleted file mode 100644 index e76a0e402ad1..000000000000 --- a/crypto/heimdal/doc/standardisation/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/crypto/heimdal/doc/standardisation/draft-ietf-cat-krb-dns-locate-02.txt b/crypto/heimdal/doc/standardisation/draft-ietf-cat-krb-dns-locate-02.txt deleted file mode 100644 index bd31750a15af..000000000000 --- a/crypto/heimdal/doc/standardisation/draft-ietf-cat-krb-dns-locate-02.txt +++ /dev/null @@ -1,339 +0,0 @@ - - - - - - -INTERNET-DRAFT Ken Hornstein - NRL -March 10, 2000 Jeffrey Altman -Expires: September 10, 2000 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 September 10, 2000. 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 March 10, 2000 - - - 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. - -DNS vs. Kerberos - Case Sensitivity of Realm Names - - In Kerberos, realm names are case sensitive. While it is strongly - encouraged that all realm names be all upper case this recommendation - has not been adopted by all sites. Some sites use all lower case - names and other use mixed case. DNS on the other hand is case insen- - sitive for queries but is case preserving for responses to TXT - queries. Since "MYREALM", "myrealm", and "MyRealm" are all different - it is necessary that the DNS entries be distinguishable. - - Since the recommend realm names are all upper case, we will not - require any quoting to be applied to upper case names. If the realm - name contains lower case characters each character is to be quoted by - a '=' character. So "MyRealm" would be represented as "M=yR=e=a=l=m" - and "myrealm" as "=m=y=r=e=a=l=m". If the realm name contains the - '=' character it will be represented as "==". - - -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. - - - -Hornstein, Altman [Page 2] - -RFC DRAFT March 10, 2000 - - - 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 - Kerberos password changing server location information - - Kerberos password changing server [KERB-CHG] location is to be stored - using the DNS SRV RR [RFC 2052]. The format of this RR is as fol- - lows: - - Service.Proto.Realm TTL Class SRV Priority Weight Port Target - - The Service name for the password server is always "_kpasswd". - - The Proto MUST be "_udp". - - 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. - -Overview - Kerberos admin server location information - - Kerberos admin 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 the admin server is always "_kerberos-adm". - - The Proto can be either "_udp" or "_tcp". If these records are to be - used, a "_tcp" record MUST be included. If the Kerberos admin imple- - mentation supports UDP transport, a "_udp" 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. - - Note that there is no formal definition of a Kerberos admin protocol, - so the use of this record is optional and implementation-dependent. - -Example - Kerberos administrative server location information - - These are DNS records for a Kerberos realm ASDF.COM. It has one - administrative server, kdc1.asdf.com. - - - - -Hornstein, Altman [Page 3] - -RFC DRAFT March 10, 2000 - - - _kerberos-adm._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" - _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: - - - - -Hornstein, Altman [Page 4] - -RFC DRAFT March 10, 2000 - - - _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. - - Current practice for REALM to KDC mapping 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 vulnerabili- - ties that already exist in the common practice of using hostnames for - KDC locations. - - Current practice for HOSTNAME to REALM mapping is to provide a local - configuration of mappings of hostname or domain name to realm which - are then mapped to KDCs. But this again is vulnerable to spoofing - via CNAME records that point to hosts in other domains. This has the - same effect as when a TXT record is spoofed. In a realm with no - cross-realm trusts this is a DoS attack. However, when cross-realm - trusts are used it is possible to redirect a client to use a comprom- - ised realm. - - This is not an exploit of the Kerberos protocol but of the Kerberos - trust model. The same can be done to any application that must - resolve the hostname in order to determine which domain a non-FQDN - belongs to. - - 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 information on a client should - be interpretted as permission to use DNS. - - - - - - -Hornstein, Altman [Page 5] - -RFC DRAFT March 10, 2000 - - -Expiration - - This Internet-Draft expires on September 10, 2000. - -References - - - [RFC1510] - The Kerberos Network Authentication System; Kohl, Newman; Sep- - tember 1993. - - [RFC1035] - Domain Names - Implementation and Specification; Mockapetris; - November 1987 - - [RFC2782] - A DNS RR for specifying the location of services (DNS SRV); Gul- - brandsen, Vixie; Feburary 2000 - - [KERB-CHG] - Kerberos Change Password Protocol; Horowitz; - ftp://ds.internic.net/internet-drafts/draft-ietf-cat-kerb-chg- - password-02.txt - -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 6] - diff --git a/crypto/heimdal/doc/standardisation/draft-ietf-cat-krb5gss-mech2-03.txt b/crypto/heimdal/doc/standardisation/draft-ietf-cat-krb5gss-mech2-03.txt deleted file mode 100644 index 11e5dc9f9548..000000000000 --- a/crypto/heimdal/doc/standardisation/draft-ietf-cat-krb5gss-mech2-03.txt +++ /dev/null @@ -1,1333 +0,0 @@ - -INTERNET-DRAFT Tom Yu -Common Authentication Technology WG MIT -draft-ietf-cat-krb5gss-mech2-03.txt 04 March 2000 - - The Kerberos Version 5 GSSAPI Mechanism, Version 2 - -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. - - Comments on this document should be sent to - "ietf-cat-wg@lists.stanford.edu", the IETF Common Authentication - Technology WG discussion list. - -Abstract - - This document defines protocols, procedures, and conventions to be - employed by peers implementing the Generic Security Service - Application Program Interface (as specified in RFC 2743) when using - Kerberos Version 5 technology (as specified in RFC 1510). This - obsoletes RFC 1964. - -Acknowledgements - - Much of the material in this specification is based on work done for - Cygnus Solutions by Marc Horowitz. - -Table of Contents - - Status of This Memo ............................................ 1 - Abstract ....................................................... 1 - Acknowledgements ............................................... 1 - Table of Contents .............................................. 1 - 1. Introduction ............................................... 3 - 2. Token Formats .............................................. 3 - 2.1. Packet Notation ....................................... 3 - -Yu Document Expiration: 04 Sep 2000 [Page 1] - -Internet-Draft krb5-gss-mech2-03 March 2000 - - 2.2. Mechanism OID ......................................... 4 - 2.3. Context Establishment ................................. 4 - 2.3.1. Option Format .................................... 4 - 2.3.1.1. Delegated Credentials Option ................ 5 - 2.3.1.2. Null Option ................................. 5 - 2.3.2. Initial Token .................................... 6 - 2.3.2.1. Data to be Checksummed in APREQ ............. 8 - 2.3.3. Response Token ................................... 10 - 2.4. Per-message Tokens .................................... 12 - 2.4.1. Sequence Number Usage ............................ 12 - 2.4.2. MIC Token ........................................ 12 - 2.4.2.1. Data to be Checksummed in MIC Token ......... 13 - 2.4.3. Wrap Token ....................................... 14 - 2.4.3.1. Wrap Token With Integrity Only .............. 14 - 2.4.3.2. Wrap Token With Integrity and Encryption - ............................................. 15 - 2.4.3.2.1. Data to be Encrypted in Wrap Token ..... 16 - 3. ASN.1 Encoding of Octet Strings ............................ 17 - 4. Name Types ................................................. 18 - 4.1. Mandatory Name Forms .................................. 18 - 4.1.1. Kerberos Principal Name Form ..................... 18 - 4.1.2. Exported Name Object Form for Kerberos5 - Mechanism ........................................ 19 - 5. Credentials ................................................ 20 - 6. Parameter Definitions ...................................... 20 - 6.1. Minor Status Codes .................................... 20 - 6.1.1. Non-Kerberos-specific codes ...................... 21 - 6.1.2. Kerberos-specific-codes .......................... 21 - 7. Kerberos Protocol Dependencies ............................. 22 - 8. Security Considerations .................................... 22 - 9. References ................................................. 22 - 10. Author's Address .......................................... 23 - - - - - - - - - - - - - - - - - - - - - - -Yu Document Expiration: 04 Sep 2000 [Page 2] - -Internet-Draft krb5-gss-mech2-03 March 2000 - -1. Introduction - - The original Kerberos 5 GSSAPI mechanism[RFC1964] has a number of - shortcomings. This document attempts to remedy them by defining a - completely new Kerberos 5 GSSAPI mechanism. - - The context establishment token format requires that the - authenticator of AP-REQ messages contain a cleartext data structure - in its checksum field, which is a needless and potentially confusing - overloading of that field. This is implemented by a special checksum - algorithm whose purpose is to copy the input data directly into the - checksum field of the authenticator. - - The number assignments for checksum algorithms and for encryption - types are inconsistent between the Kerberos protocol and the original - GSSAPI mechanism. If new encryption or checksum algorithms are added - to the Kerberos protocol at some point, the GSSAPI mechanism will - need to be separately updated to use these new algorithms. - - The original mechanism specifies a crude method of key derivation (by - using the XOR of the context key with a fixed constant), which is - incompatible with newer cryptosystems which specify key derivation - procedures themselves. The original mechanism also assumes that both - checksums and cryptosystem blocksizes are eight bytes. - - Defining all GSSAPI tokens for the new Kerberos 5 mechanism in terms - of the Kerberos protocol specification ensures that new encryption - types and checksum types may be automatically used as they are - defined for the Kerberos protocol. - -2. Token Formats - - All tokens, not just the initial token, are framed as the - InitialContextToken described in RFC 2743 section 3.1. The - innerContextToken element of the token will not itself be encoded in - ASN.1, with the exception of caller-provided application data. - - One rationale for avoiding the use of ASN.1 in the inner token is - that some implementors may wish to implement this mechanism in a - kernel or other similarly constrained application where handling of - full ASN.1 encoding may be cumbersome. Also, due to the poor - availability of the relevant standards documents, ASN.1 encoders and - decoders are difficult to implement completely correctly, so keeping - ASN.1 usage to a minimum decreases the probability of bugs in the - implementation of the mechanism. In particular, bit strings need to - be transferred at certain points in this mechanism. There are many - conflicting common misunderstandings of how to encode and decode - ASN.1 bit strings, which have led difficulties in the implementaion - of the Kerberos protocol. - - - - - -Yu Document Expiration: 04 Sep 2000 [Page 3] - -Internet-Draft krb5-gss-mech2-03 March 2000 - -2.1. Packet Notation - - The order of transmission of this protocol is described at the octet - level. Packet diagrams depict bits in the order of transmission, - assuming that individual octets are transmitted with the most - significant bit (MSB) first. The diagrams read from left to right - and from top to bottom, as in printed English. In each octet, bit - number 7 is the MSB and bit number 0 is the LSB. - - Numbers prefixed by the characters "0x" are in hexadecimal notation, - as in the C programming language. Even though packet diagrams are - drawn 16 bits wide, no padding should be used to align the ends of - variable-length fields to a 32-bit or 16-bit boundary. - - All integer fields are in network byte order. All other fields have - the size shown in the diagrams, with the exception of variable length - fields. - -2.2. Mechanism OID - - The Object Identifier (OID) of the new krb5 v2 mechanism is: - - {iso(1) member-body(2) us(840) mit(113554) infosys(1) gssapi(2) - krb5v2(3)} - - -2.3. Context Establishment - -2.3.1. Option Format - - Context establishment tokens, i.e., the initial ones that the - GSS_Init_sec_context() and the GSS_Accept_sec_context() calls emit - while a security context is being set up, may contain options that - influence the subsequent behavior of the context. This document - describes only a small set of options, but additional types may be - added by documents intended to supplement this one. The generic - format is as follows: - - bit| 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | -byte +-------------------------------+-------------------------------+ - 0 | option type | - +-------------------------------+-------------------------------+ - 2 | | - +-- option length (32 bits) --+ - 4 | | - +-------------------------------+-------------------------------+ - 6 | . | - / option data (variable length) / - | . | - +-------------------------------+-------------------------------+ - - - - -Yu Document Expiration: 04 Sep 2000 [Page 4] - -Internet-Draft krb5-gss-mech2-03 March 2000 - - option type (16 bits) - The type identifier of the following option. - - option length (32 bits) - The length in bytes of the following option. - - option data (variable length) - The actual option data. - - Any number of options may appear in an initator or acceptor token. - The final option in a token must be the null option, in order to mark - the end of the list. Option type 0xffff is reserved. - - The initiator and acceptor shall ignore any options that they do not - understand. - -2.3.1.1. Delegated Credentials Option - - Only the initiator may use this option. The format of the delegated - credentials option is as follows: - - bit| 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | -byte +-------------------------------+-------------------------------+ - 0 | option type = 0x00001 | - +-------------------------------+-------------------------------+ - 2 | | - +-- KRB-CRED length --+ - 4 | | - +-------------------------------+-------------------------------+ - 6 | . | - / KRB-CRED message / - | . | - +-------------------------------+-------------------------------+ - - - option type (16 bits) - The option type for this option shall be 0x0001. - - KRB-CRED length (32 bits) - The length in bytes of the following KRB-CRED message. - - KRB-CRED message (variable length) - The option data for this option shall be the KRB-CRED message - that contains the credentials being delegated (forwarded) to the - context acceptor. Only the initiator may use this option. - -2.3.1.2. Null Option - - The Null option terminates the option list, and must be used by both - the initiator and the acceptor. Its format is as follows: - - - - -Yu Document Expiration: 04 Sep 2000 [Page 5] - -Internet-Draft krb5-gss-mech2-03 March 2000 - - bit| 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | -byte +-------------------------------+-------------------------------+ - 0 | option type = 0 | - +-------------------------------+-------------------------------+ - 2 | | - +-- length = 0 --+ - 4 | | - +-------------------------------+-------------------------------+ - - - option type (16 bits) - The option type of this option must be zero. - - option length (32 bits) - The length of this option must be zero. - -2.3.2. Initial Token - - This is the initial token sent by the context initiator, generated by - GSS_Init_sec_context(). - - bit| 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | -byte +-------------------------------+-------------------------------+ - 0 | initial token id = 0x0101 | - +-------------------------------+-------------------------------+ - 2 | | - +-- reserved flag bits +-----------------------+ - 4 | | I | C | S | R | M | D | - +-------------------------------+-------------------------------+ - 6 | checksum type count | - +-------------------------------+-------------------------------+ - 8 | . | - / checksum type list / - | . | - +-------------------------------+-------------------------------+ - n | . | - / options / - | . | - +-------------------------------+-------------------------------+ - m | | - +-- AP-REQ length --+ - m+2 | | - +-------------------------------+-------------------------------+ - m+4 | . | - / AP-REQ data / - | . | - +-------------------------------+-------------------------------+ - - - initial token ID (16 bits) - Contains the integer 0x0101, which identifies this as the - initial token in the context setup. - - -Yu Document Expiration: 04 Sep 2000 [Page 6] - -Internet-Draft krb5-gss-mech2-03 March 2000 - - reserved flag bits (26 bits) - These bits are reserved for future expansion. They must be set - to zero by the initiator and be ignored by the acceptor. - - I flag (1 bit) - 0x00000020 -- GSS_C_INTEG_FLAG - - C flag (1 bit) - 0x00000010 -- GSS_C_CONF_FLAG - - S flag (1 bit) - 0x00000008 -- GSS_C_SEQUENCE_FLAG - - R flag (1 bit) - 0x00000004 -- GSS_C_REPLAY_FLAG - - M flag (1 bit) - 0x00000002 -- GSS_C_MUTUAL_FLAG - - D flag (1 bit) - 0x00000001 -- GSS_C_DELEG_FLAG; This flag must be set if the - "delegated credentials" option is included. - - checksum type count (16 bits) - The number of checksum types supported by the initiator. - - checksum type list (variable length) - A list of Kerberos checksum types, as defined in RFC 1510 - section 6.4. These checksum types must be collision-proof and - keyed with the context key; no checksum types that are - incompatible with the encryption key shall be used. Each - checksum type number shall be 32 bits wide. This list should - contain all the checksum types supported by the initiator. If - mutual authentication is not used, then this list shall contain - only one checksum type. - - options (variable length) - The context initiation options, described in section 2.3.1. - - AP-REQ length (32 bits) - The length of the following KRB_AP_REQ message. - - AP-REQ data (variable length) - The AP-REQ message as described in RFC 1510. The checksum in - the authenticator will be computed over the items listed in the - next section. - - The optional sequence number field shall be used in the AP-REQ. The - initiator should generate a subkey in the authenticator, and the - acceptor should generate a subkey in the AP-REP. The key used for - the per-message tokens will be the AP-REP subkey, or if that is not - present, the authenticator subkey, or if that is not present, the - session key. When subkeys are generated, it is strongly recommended - -Yu Document Expiration: 04 Sep 2000 [Page 7] - -Internet-Draft krb5-gss-mech2-03 March 2000 - - that they be of the same type as the associated session key. - - XXX The above is not secure. There should be an algorithmic process - to arrive at a subsession key which both sides of the authentication - exchange can perform based on the ticket sessions key and data known - to both parties, and this should probably be part of the revised - Kerberos protocol rather than bound to the GSSAPI mechanism. - -2.3.2.1. Data to be Checksummed in AP-REQ - - The checksum in the AP-REQ message is calculated over the following - items. Like in the actual tokens, no padding should be added to - force integer fields to align on 32 bit boundaries. This particular - set of data should not be sent as a part of any token; it merely - specifies what is to be checksummed in the AP-REQ. The items in this - encoding that precede the initial token ID correspond to the channel - bindings passed to GSS_Init_sec_context(). - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Yu Document Expiration: 04 Sep 2000 [Page 8] - -Internet-Draft krb5-gss-mech2-03 March 2000 - - bit| 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | -byte +-------------------------------+-------------------------------+ - 0 | | - +-- initiator address type --+ - 2 | | - +-------------------------------+-------------------------------+ - 4 | initiator address length | - +-------------------------------+-------------------------------+ - 6 | . | - / initiator address / - | . | - +-------------------------------+-------------------------------+ - n | | - +-- acceptor address type --+ - | | - +-------------------------------+-------------------------------+ - n+4 | acceptor address length | - +-------------------------------+-------------------------------+ - n+6 | . | - / acceptor address / - | . | - +-------------------------------+-------------------------------+ - m | . | - / application data / - | . | - +-------------------------------+-------------------------------+ - k | initial token id = 0x0101 | - +-------------------------------+-------------------------------+ - k+2 | | - +-- flags --+ - k+4 | | - +-------------------------------+-------------------------------+ - k+6 | checksum type count | - +-------------------------------+-------------------------------+ - k+8 | . | - / checksum type list / - | . | - +-------------------------------+-------------------------------+ - j | . | - / options / - | . | - +-------------------------------+-------------------------------+ - - - initiator address type (32 bits) - The initiator address type, as defined in the Kerberos protocol - specification. If no initiator address is provided, this must - be zero. - - initiator address length (16 bits) - The length in bytes of the following initiator address. If - there is no inititator address provided, this must be zero. - - -Yu Document Expiration: 04 Sep 2000 [Page 9] - -Internet-Draft krb5-gss-mech2-03 March 2000 - - initiator address (variable length) - The actual initiator address, in network byte order. - - acceptor address type (32 bits) - The acceptor address type, as defined in the Kerberos protocol - specification. If no acceptor address is provided, this must be - zero. - - acceptor address length (16 bits) - The length in bytes of the following acceptor address. This - must be zero is there is no acceptor address provided. - - initiator address (variable length) - The actual acceptor address, in network byte order. - - applicatation data (variable length) - The application data, if provided, encoded as a ASN.1 octet - string using DER. If no application data are passed as input - channel bindings, this shall be a zero-length ASN.1 octet - string. - - initial token ID (16 bits) - The initial token ID from the initial token. - - flags (32 bits) - The context establishment flags from the initial token. - - checksum type count (16 bits) - The number of checksum types supported by the initiator. - - checksum type list (variable length) - The same list of checksum types contained in the initial token. - - options (variable length) - The options list from the initial token. - -2.3.3. Response Token - - This is the reponse token sent by the context acceptor, if mutual - authentication is enabled. - - - - - - - - - - - - - - -Yu Document Expiration: 04 Sep 2000 [Page 10] - -Internet-Draft krb5-gss-mech2-03 March 2000 - - bit| 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | -byte +-------------------------------+-------------------------------+ - 0 | response token id = 0x0202 | - +-------------------------------+-------------------------------+ - 2 | | - +-- reserved flag bits +-------+ - 4 | | D | E | - +-------------------------------+-------------------------------+ - 6 | | - +-- checksum type --+ - 8 | | - +-------------------------------+-------------------------------+ - 10 | . | - / options / - | . | - +-------------------------------+-------------------------------+ - n | | - +-- AP-REP or KRB-ERROR length --+ - n+2 | | - +-------------------------------+-------------------------------+ - n+4 | . | - / AP-REP or KRB-ERROR data / - | . | - +-------------------------------+-------------------------------+ - m | . | - / MIC data / - | . | - +-------------------------------+-------------------------------+ - - - response token id (16 bits) - Contains the integer 0x0202, which identifies this as the - response token in the context setup. - - reserved flag bits (30 bits) - These bits are reserved for future expansion. They must be set - to zero by the acceptor and be ignored by the initiator. - - D flag -- delegated creds accepted (1 bit) - 0x00000002 -- If this flag is set, the acceptor processed the - delegated credentials, and GSS_C_DELEG_FLAG should be returned - to the caller. - - E flag -- error (1 bit) - 0x00000001 -- If this flag is set, a KRB-ERROR message shall be - present, rather than an AP-REP message. If this flag is not - set, an AP-REP message shall be present. - - checksum type count (16 bits) - The number of checksum types supported by both the initiator and - the acceptor. - - - -Yu Document Expiration: 04 Sep 2000 [Page 11] - -Internet-Draft krb5-gss-mech2-03 March 2000 - - checksum type (32 bits) - A Kerberos checksum type, as defined in RFC 1510 section 6.4. - This checksum type must be among the types listed by the - initiator, and will be used in for subsequent checksums - generated during this security context. - - options (variable length) - The option list, as described earlier. At this time, no options - are defined for the acceptor, but an implementation might make - use of these options to acknowledge an option from the initial - token. After all the options are specified, a null option must - be used to terminate the list. - - AP-REP or KRB-ERROR length (32 bits) - Depending on the value of the error flag, length in bytes of the - AP-REP or KRB-ERROR message. - - AP-REP or KRB-ERROR data (variable length) - Depending on the value of the error flag, the AP-REP or - KRB-ERROR message as described in RFC 1510. If this field - contains an AP-REP message, the sequence number field in the - AP-REP shall be filled. If this is a KRB-ERROR message, no - further fields will be in this message. - - MIC data (variable length) - A MIC token, as described in section 2.4.2, computed over the - concatentation of the response token ID, flags, checksum length - and type fields, and all option fields. This field and the - preceding length field must not be present if the error flag is - set. - -2.4. Per-message Tokens - -2.4.1. Sequence Number Usage - - Sequence numbers for per-message tokens are 31 bit unsigned integers, - which are incremented by 1 after each token. An overflow condition - should result in a wraparound of the sequence number to zero. The - initiator and acceptor each keep their own sequence numbers per - connection. - - The intial sequence number for tokens sent from the initiator to the - acceptor shall be the least significant 31 bits of sequence number in - the AP-REQ message. The initial sequence number for tokens sent from - the acceptor to the initiator shall be the least significant 31 bits - of the sequence number in the AP-REP message if mutual authentication - is used; if mutual authentication is not used, the initial sequence - number from acceptor to initiator shall be the least significant 31 - bits of the sequence number in the AP-REQ message. - - - - - -Yu Document Expiration: 04 Sep 2000 [Page 12] - -Internet-Draft krb5-gss-mech2-03 March 2000 - -2.4.2. MIC Token - - 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 when it is received. The MIC token has the following - format: - - bit| 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | -byte +-------------------------------+-------------------------------+ - 0 | MIC token id = 0x0303 | - +-------------------------------+-------------------------------+ - 2 | D | | - +---+ sequence number --+ - 4 | | - +-------------------------------+-------------------------------+ - 6 | checksum length | - +-------------------------------+-------------------------------+ - 8 | . | - / checksum data / - | . | - +-------------------------------+-------------------------------+ - - - MIC token id (16 bits) - Contains the integer 0x0303, which identifies this as a MIC - token. - - D -- direction bit (1 bit) - This bit shall be zero if the message is sent from the context - initiator. If the message is sent from the context acceptor, - this bit shall be one. - - sequence number (31 bits) - The sequence number. - - checksum length (16 bits) - The number of bytes in the following checksum data field. - - checksum data (variable length) - The checksum itself, as defined in RFC 1510 section 6.4. The - checksum is calculated over the encoding described in the - following section. The key usage GSS_TOK_MIC -- 22 [XXX need to - register this] shall be used in cryptosystems that support key - derivation. - - The mechanism implementation shall only use the checksum type - returned by the acceptor in the case of mutual authentication. If - mutual authentication is not requested, then only the checksum type - in the initiator token shall be used. - - - - - -Yu Document Expiration: 04 Sep 2000 [Page 13] - -Internet-Draft krb5-gss-mech2-03 March 2000 - -2.4.2.1. Data to be Checksummed in MIC Token - - The checksum in the MIC token shall be calculated over the following - elements. This set of data is not actually included in the token as - is; the description only appears for the purpose of specifying the - method of calculating the checksum. - - bit| 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | -byte +-------------------------------+-------------------------------+ - 0 | MIC token id = 0x0303 | - +-------------------------------+-------------------------------+ - 2 | D | | - +---+ sequence number --+ - 4 | | - +-------------------------------+-------------------------------+ - 6 | . | - / application data / - | . | - +-------------------------------+-------------------------------+ - - - MIC token ID (16 bits) - The MIC token ID from the MIC message. - - D -- direction bit (1 bit) - This bit shall be zero if the message is sent from the context - initiator. If the message is sent from the context acceptor, - this bit shall be one. - - sequence number (31 bits) - The sequence number. - - application data (variable length) - The application-supplied data, encoded as an ASN.1 octet string - using DER. - -2.4.3. Wrap Token - - Use of the GSS_Wrap() call yields a token which encapsulates the - input user data (optionally encrypted) along with associated - integrity check quantities. - -2.4.3.1. Wrap Token With Integrity Only - - - - - - - - - - - -Yu Document Expiration: 04 Sep 2000 [Page 14] - -Internet-Draft krb5-gss-mech2-03 March 2000 - - bit| 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | -byte +-------------------------------+-------------------------------+ - 0 | integrity wrap token id = 0x0404 | - +-------------------------------+-------------------------------+ - 2 | D | | - +---+ sequence number --+ - 4 | | - +-------------------------------+-------------------------------+ - 6 | . | - / application data / - | . | - +-------------------------------+-------------------------------+ - n | checksum length | - +-------------------------------+-------------------------------+ - n+2 | . | - / checksum data / - | . | - +-------------------------------+-------------------------------+ - - - integrity wrap token id (16 bits) - Contains the integer 0x0404, which identifies this as a Wrap - token with integrity only. - - D -- direction bit (1 bit) - This bit shall be zero if the message is sent from the context - initiator. If the message is sent from the context acceptor, - this bit shall be one. - - sequence number (31 bits) - The sequence number. - - application data (variable length) - The application-supplied data, encoded as an ASN.1 octet string - using DER. - - checksum length (16 bits) - The number of bytes in the following checksum data field. - - checksum data (variable length) - The checksum itself, as defined in RFC 1510 section 6.4, - computed over the concatenation of the token ID, sequence - number, direction field, application data length, and - application data, as in the MIC token checksum in the previous - section. The key usage GSS_TOK_WRAP_INTEG -- 23 [XXX need to - register this] shall be used in cryptosystems that support key - derivation. - - The mechanism implementation should only use checksum types which it - knows to be valid for both peers, as described for MIC tokens. - - - - -Yu Document Expiration: 04 Sep 2000 [Page 15] - -Internet-Draft krb5-gss-mech2-03 March 2000 - -2.4.3.2. Wrap Token With Integrity and Encryption - - bit| 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | -byte +-------------------------------+-------------------------------+ - | encrypted wrap token id = 0x0505 | - +-------------------------------+-------------------------------+ - 2 | . | - / encrypted data / - | . | - +-------------------------------+-------------------------------+ - - - encrypted wrap token id (16 bits) - Contains the integer 0x0505, which identifies this as a Wrap - token with integrity and encryption. - - encrypted data (variable length) - The encrypted data itself, as defined in RFC 1510 section 6.3, - encoded as an ASN.1 octet string using DER. Note that this is - not the ASN.1 type EncryptedData as defined in RFC 1510 - section 6.1, but rather the ciphertext without encryption type - or kvno information. The encryption is performed using the - key/enctype exchanged during context setup. The confounder and - checksum are as specified in the Kerberos protocol - specification. The key usage GSS_TOK_WRAP_PRIV -- 24 [XXX need - to register this] shall be used in cryptosystems that support - key derivation. The actual data to be encrypted are specified - below. - -2.4.3.2.1. Data to be Encrypted in Wrap Token - - bit| 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | -byte +-------------------------------+-------------------------------+ - 0 | D | | - +---+ sequence number --+ - 2 | | - +-------------------------------+-------------------------------+ - 4 | . | - / application data / - | . | - +-------------------------------+-------------------------------+ - - - D -- direction bit (1 bit) - This bit shall be zero if the message is sent from the context - initiator. If the message is sent from the context acceptor, - this bit shall be one. - - sequence number (31 bits) - The sequence number. - - application data (variable length) - The application-supplied data, encoded as an ASN.1 octet string - -Yu Document Expiration: 04 Sep 2000 [Page 16] - -Internet-Draft krb5-gss-mech2-03 March 2000 - - using DER. - -3. ASN.1 Encoding of Octet Strings - - In order to encode arbitirarly-sized application data, ASN.1 octet - string encoding is in this protocol. The Distinguished Encoding - Rules (DER) shall always be used in such cases. For reference - purposes, the DER encoding of an ASN.1 octet string, adapted from - ITU-T X.690, follows: - - +--------+-------//-------+-------//-------+ - |00000100| length octets |contents octets | - +--------+-------//-------+-------//-------+ - | - +-- identifier octet = 0x04 = [UNIVERSAL 4] - - - In this section only, the bits in each octet shall be numbered as in - the ASN.1 specification, from 8 to 1, with bit 8 being the MSB of the - octet, and with bit 1 being the LSB of the octet. - - identifier octet (8 bits) - Contains the constant 0x04, the tag for primitive encoding of an - octet string with the default (UNIVERSAL 4) tag. - - length octets (variable length) - Contains the length of the contents octets, in definite form - (since this encoding uses DER). - - contents octets (variable length) - The contents of the octet string. - - The length octets shall consist of either a short form (one byte - only), which is to be used only if the number of octets in the - contents octets is less than or equal to 127, or a long form, which - is to be used in all other cases. The short form shall consist of a - single octet with bit 8 (the MSB) equal to zero, and the remaining - bits encoding the number of contents octets (which may be zero) as an - unsigned binary integer. - - The long form shall consist of an initial octet and one or more - subsequent octets. The first octet shall have bit 8 (the MSB) set to - one, and the remaining bits shall encode the number of subsequent - octets in the length encoding as an unsigned binary integer. The - length must be encoded in the minimum number of octets. An initial - octet of 0xFF is reserved by the ASN.1 specification. Bits 8 to 1 of - the first subsequent octet, followed by bits 8 to 1 of each - subsequent octet in order, shall be the encoding of an unsigned - binary integer, with bit 8 of the first octet being the most - significant bit. Thus, the length encoding within is in network byte - order. - - - -Yu Document Expiration: 04 Sep 2000 [Page 17] - -Internet-Draft krb5-gss-mech2-03 March 2000 - - An initial length octet of 0x80 shall not be used, as that is - reserved by the ASN.1 specification for indefinite lengths in - conjunction with constructed contents encodings, which are not to be - used with DER. - -4. Name Types - - This section discusses the name types which may be passed as input to - the Kerberos 5 GSSAPI 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 2744. In addition to specifying OID values for name type - identifiers, symbolic names are included and recommended to GSSAPI - implementors in the interests of convenience to callers. It is - understood that not all implementations of the Kerberos 5 GSSAPI - 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 5 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 GSSAPI 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 - portability, implementors of mechanisms are encouraged to support - name forms as defined in this section, even if their mechanisms are - independent of Kerberos 5. - -4.1. Mandatory Name Forms - - This section discusses name forms which are to be supported by all - conformant implementations of the Kerberos 5 GSSAPI mechanism. - -4.1.1. Kerberos Principal Name Form - - This name form shall be represented by the Object Identifier {iso(1) - member-body(2) us(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 5 implementation, such names - are parseable with the krb5_parse_name() function.) The elements - included within this name representation are as follows, proceeding - -Yu Document Expiration: 04 Sep 2000 [Page 18] - -Internet-Draft krb5-gss-mech2-03 March 2000 - - 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. - - (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. - -4.1.2. Exported Name Object Form for Kerberos 5 Mechanism - - When generated by the Kerberos 5 mechanism, the Mechanism OID within - the exportable name shall be that of the original Kerberos 5 - mechanism[RFC1964]. The Mechanism OID for the original Kerberos 5 - mechanism is: - - {iso(1) member-body(2) us(840) mit(113554) infosys(1) gssapi(2) - krb5(2)} - - 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 - -Yu Document Expiration: 04 Sep 2000 [Page 19] - -Internet-Draft krb5-gss-mech2-03 March 2000 - - 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). - -5. Credentials - - The Kerberos 5 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 5 - credentials cache, sometimes known as a ticket file. - - 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 5 key table (keytab), or srvtab file (the Kerberos 4 - terminology). 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 5 mechanism's credential handle may contain references - to either or both types of credentials. It is a local matter how the - Kerberos 5 mechanism implementation finds the appropriate Kerberos 5 - credentials cache or key table. - - However, when the Kerberos 5 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 5 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. - -6. Parameter Definitions - - This section defines parameter values used by the Kerberos V5 GSSAPI - mechanism. It defines interface elements in support of portability, - and assumes use of C language bindings per RFC 2744. - -6.1. Minor Status Codes - - This section recommends common symbolic names for minor_status values - to be returned by the Kerberos 5 GSSAPI mechanism. Use of these - -Yu Document Expiration: 04 Sep 2000 [Page 20] - -Internet-Draft krb5-gss-mech2-03 March 2000 - - 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 GSSAPI 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. - -6.1.1. Non-Kerberos-specific codes - - These symbols should likely be incorporated into the generic GSSAPI - C-bindings document, since they really are more general. - -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" */ - - -6.1.2. Kerberos-specific-codes - - - - - - - - - - -Yu Document Expiration: 04 Sep 2000 [Page 21] - -Internet-Draft krb5-gss-mech2-03 March 2000 - -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" */ - - -7. Kerberos Protocol Dependencies - - This protocol makes several assumptions about the Kerberos protocol, - which may require changes to the successor of RFC 1510. - - Sequence numbers, checksum types, and address types are assumed to be - no wider than 32 bits. The Kerberos protocol specification might - need to be modified to accomodate this. This obviously requires some - further discussion. - - Key usages need to be registered within the Kerberos protocol for use - with GSSAPI per-message tokens. The current specification of the - Kerberos protocol does not include descriptions of key derivations or - key usages, but planned revisions to the protocol will include them. - - This protocol also makes the assumption that any cryptosystem used - with the session key will include integrity protection, i.e., it - assumes that no "raw" cryptosystems will be used. - -8. Security Considerations - - The GSSAPI is a security protocol; therefore, security considerations - are discussed throughout this document. The original Kerberos 5 - GSSAPI mechanism's constraints on possible cryptosystems and checksum - types do not permit it to be readily extended to accomodate more - secure cryptographic technologies with larger checksums or encryption - block sizes. Sites are strongly encouraged to adopt the mechanism - specified in this document in the light of recent publicity about the - deficiencies of DES. - -9. References - - [X.680] ISO/IEC, "Information technology -- Abstract Syntax Notation - One (ASN.1): Specification of basic notation", ITU-T X.680 (1997) | - ISO/IEC 8824-1:1998 - -Yu Document Expiration: 04 Sep 2000 [Page 22] - -Internet-Draft krb5-gss-mech2-03 March 2000 - - [X.690] ISO/IEC, "Information technology -- ASN.1 encoding rules: - Specification of Basic Encoding Rules (BER), Canonical Encoding Rules - (CER) and Distinguished Encoding Rules (DER)", ITU-T X.690 (1997) | - ISO/IEC 8825-1:1998. - - [RFC1510] Kohl, J., Neumann, C., "The Kerberos Network Authentication - Service (V5)", RFC 1510. - - [RFC1964] Linn, J., "The Kerberos Version 5 GSS-API Mechanism", - RFC 1964. - - [RFC2743] Linn, J., "Generic Security Service Application Program - Interface, Version 2, Update 1", RFC 2743. - - [RFC2744] Wray, J., "Generic Security Service API Version 2: - C-bindings", RFC 2744. - -10. Author's Address - - Tom Yu - Massachusetts Institute of Technology - Room E40-345 - 77 Massachusetts Avenue - Cambridge, MA 02139 - USA - - email: tlyu@mit.edu - phone: +1 617 253 1753 - - - - - - - - - - - - - - - - - - - - - - - - - - -Yu Document Expiration: 04 Sep 2000 [Page 23] - diff --git a/crypto/heimdal/doc/standardisation/draft-ietf-ftpext-mlst-08.txt b/crypto/heimdal/doc/standardisation/draft-ietf-ftpext-mlst-08.txt deleted file mode 100644 index 885cf4967679..000000000000 --- a/crypto/heimdal/doc/standardisation/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/crypto/heimdal/doc/standardisation/draft-ietf-krb-wg-kerberos-referrals-00.txt b/crypto/heimdal/doc/standardisation/draft-ietf-krb-wg-kerberos-referrals-00.txt deleted file mode 100644 index 5845995f2d9c..000000000000 --- a/crypto/heimdal/doc/standardisation/draft-ietf-krb-wg-kerberos-referrals-00.txt +++ /dev/null @@ -1,725 +0,0 @@ - - -Kerberos Working Group M. Swift -Internet Draft University of WA -Document: draft-ietf-krb-wg-kerberos-referrals-00.txt J. Brezak -Category: Standards Track Microsoft - J. Trostle - Cisco Systems - K. Raeburn - MIT - February 2001 - - - Generating KDC Referrals to locate Kerberos realms - - -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 draft documents a new method for a Kerberos Key Distribution - Center (KDC) to respond to client requests for kerberos tickets when - the client does not have detailed configuration information on the - realms of users or services. The KDC will handle requests for - principals in other realms by returning either a referral error or a - cross-realm TGT to another realm on the referral path. The clients - will use this referral information to reach the realm of the target - principal and then receive the ticket. - -2. Conventions used in this document - - 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. Introduction - - - - -Swift Category - Standards Track 1 - - - - - - - - - KDC Referrals February 2001 - - - Current implementations of the Kerberos AS and TGS protocols, as - defined in RFC 1510 [3], use principal names constructed from a - known user or service name and realm. A service name is typically - constructed from a name of the service and the DNS host name of the - computer that is providing the service. Many existing deployments of - Kerberos use a single Kerberos realm where all users and services - would be using the same realm. However in an environment where there - are multiple trusted Kerberos realms, the client needs to be able to - determine what realm a particular user or service is in before - making an AS or TGS request. Traditionally this requires client - configuration to make this possible. - - When having to deal with multiple trusted realms, users are forced - to know what realm they are in before they can obtain a ticket - granting ticket (TGT) with an AS request. However, in many cases the - user would like to use a more familiar name that is not directly - related to the realm of their Kerberos principal name. A good - example of this is an RFC-822 style email name. This document - describes a mechanism that would allow a user to specify a user - principal name that is an alias for the user's Kerberos principal - name. In practice this would be the name that the user specifies to - obtain a TGT from a Kerberos KDC. The user principal name no longer - has a direct relationship with the Kerberos principal or realm. Thus - the administrator is able to move the user's principal to other - realms without the user having to know that it happened. - - Once a user has a TGT, they would like to be able to access services - in any trusted Kerberos realm. To do this requires that the client - be able to determine what realm the target service's host is in - before making the TGS request. Current implementations of Kerberos - typically have a table that maps DNS host names to corresponding - Kerberos realms. In order for this to work on the client, each - application canonicalizes the host name of the service by doing a - DNS lookup followed by a reverse lookup using the returned IP - address. The returned primary host name is then used in the - construction of the principal name for the target service. In order - for the correct realm to be added for the target host, the mapping - table [domain_to_realm] is consulted for the realm corresponding to - the DNS host name. The corresponding realm is then used to complete - the target service principal name. - - This traditional mechanism requires that each client have very - detailed configuration information about the hosts that are - providing services and their corresponding realms. Having client - side configuration information can be very costly from an - administration point of view - especially if there are many realms - and computers in the environment. - - Current implementations of Kerberos also have difficulty with - services on hosts that can have multiple host names (multi-homed - hosts). Traditionally, each host name would need to have a distinct - principal and a corresponding key. An extreme example of this would - be a Web server with multiple host names for each domain that it is - -Swift Category - Standards Track 2 - - - - - - - - - KDC Referrals February 2001 - - - supporting. Principal aliases allow multi-homed hosts to have a - single Kerberos principal (with a single key) that can have - identities for each distinct host name. This mechanism allows the - Kerberos client to request a service ticket for the distinct - hostname and allows the KDC to return a ticket for the single - principal that the host is using. This canonical principal name - allows the host to only have to manage a single key for all of the - identities that it supports. In addition, the client only needs to - know the realm of the canonical service name, not all of the - identities. - - This draft proposes a solution for these problems and simplifies - administration by minimizing the configuration information needed on - each computer using Kerberos. Specifically it describes a mechanism - to allow the KDC to handle Canonicalization of names, provide for - principal aliases for users and services and provide a mechanism for - the KDC to determine the trusted realm authentication path by being - able to generate referrals to other realms in order to locate - principals. - - To rectify these problems, this draft introduces three new kinds of - KDC referrals: - - 1. AS ticket referrals, in which the client doesn't know which realm - contains a user account. - 2. TGS ticket referrals, in which the client doesn't know which - realm contains a server account. - 3. Cross realm shortcut referrals, in which the KDC chooses the next - path on a referral chain - -4. Realm Organization Model - - This draft assumes that the world of principals is arranged on - multiple levels: the realm, the enterprise, and the world. A KDC may - issue tickets for any principal in its realm or cross-realm tickets - for realms with which it has a direct trust relationship. The KDC - also has access to a trusted name service that can resolve any name - from within its enterprise into a realm. This trusted name service - removes the need to use an untrusted DNS lookup for name resolution. - - For example, consider the following configuration, where lines - indicate trust relationships: - - MS.COM - / \ - / \ - OFFICE.MS.COM NT.MS.COM - - In this configuration, all users in the MS.COM enterprise could have - a principal name such as alice@MS.COM, with the same realm portion. - In addition, servers at MS.COM should be able to have DNS host names - from any DNS domain independent of what Kerberos realm their - principal resides in. - -Swift Category - Standards Track 3 - - - - - - - - - KDC Referrals February 2001 - - - -5. Principal Names - -5.1 Service Principal Names - - The standard Kerberos model in RFC 1510 [3] gives each Kerberos - principal a single name. However, if a service is reachable by - several addresses, it is useful for a principal to have multiple - names. Consider a service running on a multi-homed machine. Rather - than requiring a separate principal and password for each name it - exports, a single account with multiple names could be used. - - Multiple names are also useful for services in that clients need not - perform DNS lookups to resolve a host name into a full DNS address. - Instead, the service may have a name for each of its supported host - names, including its IP address. Nonetheless, it is still convenient - for the service to not have to be aware of all these names. Thus a - new name may be added to DNS for a service by updating DNS and the - KDC database without having to notify the service. In addition, it - implies that these aliases are globally unique: they do not include - a specifier dictating what realm contains the principal. Thus, an - alias for a server is of the form "class/instance/name" and may be - transmitted as any name type. - -5.2 Client Principal Names - - Similarly, a client account may also have multiple principal names. - More useful, though, is a globally unique name that allows - unification of email and security principal names. For example, all - users at MS may have a client principal name of the form - "joe@MS.COM" even though the principals are contained in multiple - realms. This global name is again an alias for the true client - principal name, which is indicates what realm contains the - principal. Thus, accounts "alice" in the realm ntdev.MS.COM and - "bob" in office.MS.COM may logon as "alice@MS.COM" and "bob@MS.COM". - This requires a new client principal name type, as the AS-REQ - message only contains a single realm field, and the realm portion of - this name doesn't correspond to any Kerberos realm. Thus, the entire - name "alice@MS.COM" is transmitted in the client name field of the - AS-REQ message, with a name type of KRB-NT-ENTERPRISE-PRINCIPAL. - - KRB-NT-ENTERPRISE-PRINCIPAL 10 - -5.3 Name Canonicalization - - In order to support name aliases, the Kerberos client must - explicitly request the name-canonicalization KDC option (bit 15) in - the ticket flags for the TGS-REQ. This flag indicates to the KDC - that the client is prepared to receive a reply with a different - client or server principal name than the request. Thus, the - KDCOptions types is redefined as: - - KDCOptions ::= BIT STRING { - -Swift Category - Standards Track 4 - - - - - - - - - KDC Referrals February 2001 - - - 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), - name-canonicalize(15), - renewable-ok(27), - enc-tkt-in-skey(28), - renew(30), - validate(31) - } - -6. Client Referrals - - The simplest form of ticket referral is for a user requesting a - ticket using an AS-REQ. In this case, the client machine will send - the AS request to a convenient trusted realm, either the realm of - the client machine or the realm of the client name. In the case of - the name Alice@MS.COM, the client may optimistically choose to send - the request to MS.COM. - - The client will send the string "alice@MS.COM" in the client - principal name field using the KRB-NT-ENTERPRISE-PRINCIPAL name type - with the crealm set to MS.COM. The KDC will try to lookup the name - in its local account database. If the account is present in the - crealm of the request, it MUST return a KDC reply structure with the - appropriate ticket. If the account is not present in the crealm - specified in the request and the name-canonicalize flag in the - KDCoptions is set, the KDC will try to lookup the entire name, - Alice@MS.COM, using a name service. If this lookup is unsuccessful, - it MUST return the error KDC_ERR_C_PRINCIPAL_UNKNOWN. If the lookup - is successful, it MUST return an error KDC_ERR_WRONG_REALM (0x44) - and in the error message the cname and crealm field MUST contain the - client name and the true realm of the client. If the KDC contains - the account locally, it MUST return a normal ticket. The client name - and realm portions of the ticket and KDC reply message MUST be the - client's true name in the realm, not the globally unique name. - - If the client receives a KDC_ERR_WRONG_REALM error, it will issue a - new AS request with the same client principal name used to generate - the first referral to the realm specified by the crealm field of the - kerberos error message from the first request. This request MUST - produce a valid AS response with a ticket for the canonical user - name. The ticket MUST also include the ticket extension containing - the TE-REFERRAL-DATA with the referred-names set to the name from - - -Swift Category - Standards Track 5 - - - - - - - - - KDC Referrals February 2001 - - - the AS request. Any other error or referral will terminate the - request and result in a failed AS request. - -7. Server Referrals - - The server referral mechanism is a bit more complex than the client - referral mechanism. The primary problem is that the KDC must return - a referral ticket rather than an error message, so it will include - in the TGS response information about what realm contains the - service. This is done by returning information about the server name - in the pre-auth data field of the KDC reply. - - If the KDC resolves the server principal name into a principal in - its realm, it may return a normal ticket. If the name-canonicalize - flag in the KDCoptions is not set, then the KDC MUST only look up - the name as a normal principal name. Otherwise, it MUST search all - aliases as well. The server principal name in both the ticket and - the KDC reply MUST be the true server principal name instead of one - of the aliases. This frees the application server from needing to - know about all its aliases. - - If the name-canonicalize flag in the KDCoptions is set and the KDC - doesn't find the principal locally, the KDC can return a cross-realm - ticket granting ticket to the next hop on the trust path towards a - realm that may be able to resolve the principal name. - - If the KDC can determine the service principal's realm, it can - return the server realm as ticket extension data. The ticket - extension MUST be encrypted using the session key from the ticket, - and the same etype as is used to protect the TGS reply body. - - The data itself is an ASN.1 encoded structure containing the - server's realm, and if known, canonical principal name and alias - names. The first name in the sequence is the canonical principal - name. - - TE-REFERRAL-INFO 20 - - TE-REFERRAL-DATA ::= SEQUENCE { - referred-server-realm[0] KERB-REALM - referred-names[1] SEQUENCE OF - PrincipalNames OPTIONAL - } - - - The client can use this information to request a chain of cross- - realm ticket granting tickets until it reaches the realm of the - server, and can then expect to receive a valid service ticket. - - In order to facilitate cross-realm interoperability, a client SHOULD - NOT send short names in TGS requests to the KDC. A short name is - defined as a Kerberos name that includes a DNS name that is not - fully qualified. The client MAY use forward DNS lookups to obtain - -Swift Category - Standards Track 6 - - - - - - - - - KDC Referrals February 2001 - - - the long name that corresponds to the user entered short name (the - short name will be a prefix of the corresponding long name). - - The client may use the referred-names field to tell if it already - has a ticket to the server in its ticket cache. - - The client can use this information to request a chain of cross- - realm ticket granting tickets until it reaches the realm of the - server, and can then expect to receive a valid service ticket. - However an implementation should limit the number of referrals that - it processes to avoid infinite referral loops. A suggested limit is - 5 referrals before giving up. - -8. Cross Realm Routing - - The current Kerberos protocol requires the client to explicitly - request a cross-realm TGT for each pair of realms on a referral - chain. As a result, the client machines need to be aware of the - trust hierarchy and of any short-cut trusts (those that aren't - parent-child trusts). This requires more configurations on the - client. Instead, the client should be able to request a TGT to the - target realm from each realm on the route. The KDC will determine - the best path for the client and return a cross-realm TGT. The - client has to be aware that a request for a cross-realm TGT may - return a TGT for a realm different from the one requested. - -9. Security Considerations - - The original Kerberos specification stated that the server principal - name in the KDC reply was the same as the server name in the - request. These protocol changes break that assumption, so the client - may be vulnerable to a denial of service attack by an attacker that - replays replies from previous requests. It can verify that the - request was one of its own by checking the client-address field or - authtime field, though, so the damage is limited and detectable. - - For the AS exchange case, it is important that the logon mechanism - not trust a name that has not been used to authenticate the user. - For example, the name that the user enters as part of a logon - exchange may not be the name that the user authenticates as, given - that the KDC_ERR_WRONG_REALM error may have been returned. The - relevant Kerberos naming information for logon (if any), is the - client name and client realm in the service ticket targeted at the - workstation that was obtained using the user's initial TGT. - - How the client name and client realm is mapped into a local account - for logon is a local matter, but the client logon mechanism MUST use - additional information such as the client realm and/or authorization - attributes from the service ticket presented to the workstation by - the user, when mapping the logon credentials to a local account on - the workstation. - -10. Discussion - -Swift Category - Standards Track 7 - - - - - - - - - KDC Referrals February 2001 - - - - This section contains issues and suggestions that need to be - incorporated into this draft. From Ken Raeburn [raeburn@mit.edu]: - - 1) No means to do name canonicalization if you're not - authenticating. Is it okay to require credentials in order to do - canonicalization? If so, how about this: Send a TGS_REQ for the - service name you have. If you get back a TGS_REP for a service, - great; pull out the name and throw out the credentials. If you - get back a TGS_REP for a TGT service, ask again in the specified - realm. If you get back a KRB_ERROR because policy prohibits you - from authenticating to that service, we can add to the - specification that the {realm,sname} in the KRB_ERROR must be the - canonical name, and the checksum must be used. As long as the - checksum is present, it's still a secure exchange with the KDC. - - If we have to be able to do name canonicalization without any - sort of credentials, either client-side (tickets) or server-side - (tickets automatically acquired via service key), I think we just - lose. But maybe GSSAPI should be changed if that's the case. - - 2) Can't refer to another realm and specify a different service name - to give to that realm's KDC. The local KDC can tell you a - different service name or a different realm name, but not both. - This comes up in the "gnuftp.raeburn.org CNAME ftp.gnu.org" type - of case I've mentioned. - - Except ... the KDC-REP structure includes padata and ticket - extensions fields that are extensible. We could add a required - value to one of them -- perhaps only in the case where you return - a TGT when not asked -- that contains signed information about - the principal name to ask for in the other realm. (It would have - to be required, otherwise a man-in-the-middle could make it go - away.) Signing would be done using the session key for the TGS. - - 3) Secure canonicalization of service name in AS_REQ. If the - response is an AS_REP, we need a way to tell that the altered - server name wasn't a result of a MITM attack on the AS_REQ - message. Again, the KDC-REP extensible fields could have a new - required value added when name canonicalization happens, - indicating what the original principal name (in the AS_REQ - message) was, and signed using the same key as protects the - AS_REP. If it doesn't match what the client requested, the - messages were altered in transit. - - 4) Client name needs referral to another realm, and server name - needs canonicalization of some sort. The above fixes wouldn't - work for this case, and I'm not even sure which KDC should be - doing the canonicalization anyways. - - - The other-principal-name datum would probably look something like: - - -Swift Category - Standards Track 8 - - - - - - - - - KDC Referrals February 2001 - - - PrincipalAndNonce ::= SEQUENCE { - name[0] PrincipalName, - nonce[1] INTEGER -- copied from KDC_REQ - } - SignedPrincipal ::= SEQUENCE { - name-and-nonce[0] PrincipalAndNonce, - cksum[1] Checksum - } - {PA,TE}-ORIGINAL-SERVER-PRINCIPAL ::= SignedPrincipal - {PA,TE}-REMOTE-SERVER-PRINCIPAL ::= SignedPrincipal - - with the checksum computed over the encoding of the 'name-and-nonce' - field, and appropriate PA- or TE- numbers assigned. I don't have a - strong opinion on whether it'd be a pa-data or ticket extension; - conceptually it seems like an abuse of either, but, well, I think - I'd rather abuse them than leave the facility both in and - inadequate. - - The nonce is needed because multiple exchanges may be made with the - same key, and these extension fields aren't packed in with the other - encrypted data in the same response, so a MITM could pick apart - multiple messages and mix-and-match components. (In a TGS_REQ - exchange, a subsession key would help, but it's not required.) - - The extension field would be required to prevent a MITM from - discarding the field from a response; a flag bit in a protected part - of the message (probably in 'flags' in EncKDCRepPart) could also let - us know of a cases where the information can be omitted, namely, - when no name change is done. Perhaps the bit should be set to - indicate that a name change *was* done, and clear if it wasn't, - making the no-change case more directly compatible with RFC1510. - -11. 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 Kohl, J., Neuman, C., "The Kerberos Network Authentication - Service (V5)", RFC 1510, September 1993 - - -12. Author's Addresses - - Michael Swift - University of Washington - Seattle, Washington - Email: mikesw@cs.washington.edu - - John Brezak - -Swift Category - Standards Track 9 - - - - - - - - - KDC Referrals February 2001 - - - Microsoft - One Microsoft Way - Redmond, Washington - Email: jbrezak@Microsoft.com - - Jonathan Trostle - Cisco Systems - 170 W. Tasman Dr. - San Jose, CA 95134 - Email: jtrostle@cisco.com - - Kenneth Raeburn - Massachusetts Institute of Technology 77 - Massachusetts Avenue - Cambridge, Massachusetts 02139 - Email: raeburn@mit.edu - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Swift Category - Standards Track 10 - - - - - - - - - KDC Referrals February 2001 - - - 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 - Standards Track 11 - - - - - - - diff --git a/crypto/heimdal/doc/standardisation/draft-ietf-krb-wg-krb-dns-locate-02.txt b/crypto/heimdal/doc/standardisation/draft-ietf-krb-wg-krb-dns-locate-02.txt deleted file mode 100644 index a6dec9d1e076..000000000000 --- a/crypto/heimdal/doc/standardisation/draft-ietf-krb-wg-krb-dns-locate-02.txt +++ /dev/null @@ -1,339 +0,0 @@ - - - - - - -INTERNET-DRAFT Ken Hornstein - NRL -February 28, 2001 Jeffrey Altman -Expires: August 28, 2001 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 August 28, 2001. - 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 February 28, 2001 - - - 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. - -DNS vs. Kerberos - Case Sensitivity of Realm Names - - In Kerberos, realm names are case sensitive. While it is strongly - encouraged that all realm names be all upper case this recommendation - has not been adopted by all sites. Some sites use all lower case - names and other use mixed case. DNS on the other hand is case insen- - sitive for queries but is case preserving for responses to TXT - queries. Since "MYREALM", "myrealm", and "MyRealm" are all different - it is necessary that only one of the possible combinations of upper - and lower case characters be used. This restriction may be lifted in - the future as the DNS naming scheme is expanded to support non-ASCII - names. - -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, and Target have the standard mean- - ing as defined in RFC 2052. - - As per RFC 2052 the Port number should be the value assigned to "ker- - beros" by the Internet Assigned Number Authority (88). - -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. - - - - -Hornstein, Altman [Page 2] - -RFC DRAFT February 28, 2001 - - - _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 - Kerberos password changing server location information - - Kerberos password changing server [KERB-CHG] location is to be stored - using the DNS SRV RR [RFC 2052]. The format of this RR is as fol- - lows: - - Service.Proto.Realm TTL Class SRV Priority Weight Port Target - - The Service name for the password server is always "_kpasswd". - - The Proto MUST be "_udp". - - The Realm is the Kerberos realm that this record corresponds to. - - TTL, Class, SRV, Priority, Weight, and Target have the standard mean- - ing as defined in RFC 2052. - - As per RFC 2052 the Port number should be the value assigned to - "kpasswd" by the Internet Assigned Number Authority (464). - -Overview - Kerberos admin server location information - - Kerberos admin 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 the admin server is always "_kerberos-adm". - - The Proto can be either "_udp" or "_tcp". If these records are to be - used, a "_tcp" record MUST be included. If the Kerberos admin imple- - mentation supports UDP transport, a "_udp" record SHOULD be included. - - The Realm is the Kerberos realm that this record corresponds to. - - TTL, Class, SRV, Priority, Weight, and Target have the standard mean- - ing as defined in RFC 2052. - - As per RFC 2052 the Port number should be the value assigned to - "kerberos-adm" by the Internet Assigned Number Authority (749). - - Note that there is no formal definition of a Kerberos admin protocol, - so the use of this record is optional and implementation-dependent. - - - - - -Hornstein, Altman [Page 3] - -RFC DRAFT February 28, 2001 - - -Example - Kerberos administrative server location information - - These are DNS records for a Kerberos realm ASDF.COM. It has one - administrative server, kdc1.asdf.com. - - _kerberos-adm._tcp.ASDF.COM. IN SRV 0 0 749 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" - _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: - - - -Hornstein, Altman [Page 4] - -RFC DRAFT February 28, 2001 - - - _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. - - Current practice for REALM to KDC mapping 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 vulnerabili- - ties that already exist in the common practice of using hostnames for - KDC locations. - - Current practice for HOSTNAME to REALM mapping is to provide a local - configuration of mappings of hostname or domain name to realm which - are then mapped to KDCs. But this again is vulnerable to spoofing - via CNAME records that point to hosts in other domains. This has the - same effect as when a TXT record is spoofed. In a realm with no - cross-realm trusts this is a DoS attack. However, when cross-realm - trusts are used it is possible to redirect a client to use a comprom- - ised realm. - - This is not an exploit of the Kerberos protocol but of the Kerberos - trust model. The same can be done to any application that must - resolve the hostname in order to determine which domain a non-FQDN - belongs to. - - 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 information on a client should - - - -Hornstein, Altman [Page 5] - -RFC DRAFT February 28, 2001 - - - be interpretted as permission to use DNS. - -Expiration - - This Internet-Draft expires on August 28, 2001. - -References - - - [RFC1510] - The Kerberos Network Authentication System; Kohl, Newman; Sep- - tember 1993. - - [RFC1035] - Domain Names - Implementation and Specification; Mockapetris; - November 1987 - - [RFC2782] - A DNS RR for specifying the location of services (DNS SRV); Gul- - brandsen, Vixie; Feburary 2000 - - [KERB-CHG] - Kerberos Change Password Protocol; Horowitz; - ftp://ds.internic.net/internet-drafts/draft-ietf-cat-kerb-chg- - password-02.txt - -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 6] - diff --git a/crypto/heimdal/doc/standardisation/draft-raeburn-cat-gssapi-krb5-3des-00.txt b/crypto/heimdal/doc/standardisation/draft-raeburn-cat-gssapi-krb5-3des-00.txt deleted file mode 100644 index 24325fdbda74..000000000000 --- a/crypto/heimdal/doc/standardisation/draft-raeburn-cat-gssapi-krb5-3des-00.txt +++ /dev/null @@ -1,281 +0,0 @@ -CAT Working Group K. Raeburn -Internet-draft MIT -Category: July 14, 2000 -Updates: RFC 1964 -Document: draft-raeburn-cat-gssapi-krb5-3des-00.txt - - Triple-DES Support for the Kerberos 5 GSSAPI Mechanism - -Status of this Memo - - This document is an Internet-Draft and is in full conformance with - all provisions of Section 10 of RFC2026 [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. - -1. Abstract - - The MIT Kerberos 5 release version 1.2 includes support for - triple-DES with key derivation [KrbRev]. Recent work by the EFF - [EFF] has demonstrated the vulnerability of single-DES mechanisms - to brute-force attacks by sufficiently motivated and well-funded - parties. - - The GSSAPI Kerberos 5 mechanism definition [GSSAPI-KRB5] - specifically enumerates encryption and checksum types, - independently of how such schemes may be used in Kerberos. In the - long run, a new Kerberos-based mechanism, which does not require - separately enumerating for the GSSAPI mechanism each of the - encryption types defined by Kerberos, appears to be a better - approach. Efforts to produce such a specification are under way. - - In the interest of providing increased security in the interim, - however, MIT is proposing adding support for triple-DES to the - existing mechanism, as described here. - -2. Conventions Used in this Document - - 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. - -3. New Algorithm Identifiers - - One new sealing algorithm is defined, for use in WRAP tokens: - - 02 00 - DES3-KD - - This algorithm uses triple-DES with key derivation, with a usage - value KG_USAGE_SEAL. Padding is still to 8-byte multiples, and the - IV for encrypting application data is zero. - - One new signing algorithm is defined, for use in MIC, Wrap, and - Delete tokens: - - 04 00 - HMAC SHA1 DES3-KD - - This algorithm generates an HMAC using SHA-1 and a derived DES3 key - with usage KG_USAGE_SIGN, as (ought to be described) in [KrbRev]. - - [XXX: The current [KrbRev] description refers to expired I-Ds from - Marc Horowitz. The text in [KrbRev] may be inadequate to produce - an interoperable implementation.] - - The checksum size for this algorithm is 20 octets. See section 5.3 - below for the use of checksum lengths of other than eight bytes. - -4. Key Derivation - - For purposes of key derivation, we add three new usage values to the - list defined in [KrbRev]; one for signing messages, one for - sealing messages, and one for encrypting sequence numbers: - - #define KG_USAGE_SEAL 22 - #define KG_USAGE_SIGN 23 - #define KG_USAGE_SEQ 24 - -5. Adjustments to Previous Definitions - -5.1. Quality of Protection - - The GSSAPI specification [GSSAPI] says that a zero QOP value - indicates the "default". The original specification for the - Kerberos 5 mechanism says that a zero QOP value (or a QOP value - with the appropriate bits clear) means DES encryption. - - Rather than continue to force the use of plain DES when the - application doesn't use mechanism-specific QOP values, the better - choice appears to be to redefine the DES QOP value as some non-zero - value, and define a triple-DES value as well. Then a zero value - continues to imply the default, which would be triple-DES - protection when given a triple-DES session key. - - Our values are: - - GSS_KRB5_INTEG_C_QOP_HMAC_SHA1 0x0004 - /* SHA-1 checksum encrypted with key derivation */ - - GSS_KRB5_CONF_C_QOP_DES 0x0100 - /* plain DES encryption */ - GSS_KRB5_CONF_C_QOP_DES3_KD 0x0200 - /* triple-DES with key derivation */ - - Rather than open the question of whether to specify means for - deriving a key of one type given a key of another type, and the - security implications of whether to generate a long key from a - shorter one, our implementation will simply return an error if the - QOP value specified does not correspond to the session key type. - - [Implementation note: MIT's code does not implement QoP, and - returns an error for any non-zero QoP value.] - -5.2. MIC Sequence Number Encryption - - The sequence numbers are encrypted in the context key (as defined - in [GSSAPI-KRB5] -- this will be either the Kerberos session key or - asubkey provided by the context initiator), using whatever - encryption system is designated by the type of that context key. - The IV is formed from the first N bytes of the SGN_CKSUM field, - where N is the number of bytes needed for the IV. (With all - algorithms described here and in [GSSAPI-KRB5], the checksum is at - least as large as the IV.) - -5.3. Message Layout - - Both MIC and Wrap tokens, as defined in [GSSAPI-KRB5], contain an - checksum field SGN_CKSUM. In [GSSAPI-KRB5], this field was - specified as being 8 bytes long. We now change this size to be - "defined by the checksum algorithm", and retroactively amend the - descriptions of all the checksum algorithms described in - [GSSAPI-KRB5] to explicitly specify 8-byte output. Application - data continues to immediately follow the checksum field in the Wrap - token. - - The revised message descriptions are thus: - - MIC: - - Byte no Name Description - 0..1 TOK_ID Identification field. - 2..3 SGN_ALG Integrity algorithm indicator. - 4..7 Filler Contains ff ff ff ff - 8..15 SND_SEQ Sequence number field. - 16..s+15 SGN_CKSUM Checksum of "to-be-signed data", - calculated according to algorithm - specified in SGN_ALG field. - - Wrap: - - 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. - 4..5 SEAL_ALG Sealing algorithm indicator. - 6..7 Filler Contains ff ff - 8..15 SND_SEQ Encrypted sequence number field. - 16..s+15 SGN_CKSUM Checksum of plaintext padded data, - calculated according to algorithm - specified in SGN_ALG field. - s+16..last Data encrypted or plaintext padded data - - Where "s" indicates the size of the checksum. - - As indicated above in section 2, we define the HMAC SHA1 DES3-KD - checksum algorithm to produce a 20-byte output, so encrypted data - begins at byte 36. - -6. Backwards Compatibility Considerations - - The context initiator SHOULD request of the KDC credentials using - session-key cryptosystem types supported by that implementation; if - the only types returned by the KDC are not supported by the - mechanism implementation, it MUST indicate a failure. This may - seem obvious, but early implementations of both Kerberos and the - GSSAPI Kerberos mechanism supported only DES keys, so the - cryptosystem compatibility question was easy to overlook. - - Under the current mechanism, no negotiation of algorithm types - occurs, so server-side (acceptor) implementations cannot request - that clients not use algorithm types not understood by the server. - However, administration of the server's Kerberos data has to be - done in communication with the KDC, and it is from the KDC that the - client will request credentials. The KDC could therefore be tasked - with limiting session keys for a given service to types actually - supported by the Kerberos and GSSAPI software on the server. - - This does have a drawback for cases where a service principal name - is used both for GSSAPI-based and non-GSSAPI-based communication, - if the GSSAPI implementation does not understand triple-DES but the - Kerberos implementation does. It means that triple-DES session - keys cannot be issued for that service principal, which keeps the - protection of non-GSSAPI services weaker than necessary. However, - in the most recent MIT releases thus far, while triple-DES support - has been present, it has required additional work to enable, so it - is not likely to be in use for many services. - - It would also be possible to have clients attempt to get single-DES - session keys before trying to get triple-DES session keys, and have - the KDC refuse to issue the single-DES keys only for the most - critical of services, for which single-DES protection is considered - inadequate. However, that would eliminate the possibility of - connecting with the more secure cryptosystem to any service that - can be accessed with the weaker cryptosystem. - - We have chosen to go with the former approach, putting the burden - on the KDC administration and gaining the best protection possible - for GSSAPI services, possibly at the cost of protection of - non-GSSAPI Kerberos services running earlier versions of the - software. - -6. Security Considerations - - Various tradeoffs arise regarding the mixing of new and old - software, or GSSAPI-based and non-GSSAPI Kerberos authentication. - They are discussed in section 5. - -7. References - - [EFF] Electronic Frontier Foundation, "Cracking DES: Secrets of - Encryption Research, Wiretap Politics, and Chip Design", O'Reilly & - Associates, Inc., May, 1998. - - [GSSAPI] Linn, J., "Generic Security Service Application Program - Interface Version 2, Update 1", RFC 2743, January, 2000. - - [GSSAPI-KRB5] Linn, J., "The Kerberos Version 5 GSS-API Mechanism", - RFC 1964, June, 1996. - - [KrbRev] Neuman, C., Kohl, J., Ts'o, T., "The Kerberos Network - Authentication Service (V5)", - draft-ietf-cat-kerberos-revisions-05.txt, March 10, 2000. - - [RFC2026] Bradner, S., "The Internet Standards Process -- Revision - 3", RFC 2026, October, 1996. - -8. Author's Address - - Kenneth Raeburn - Massachusetts Institute of Technology - 77 Massachusetts Avenue - Cambridge, MA 02139 - -9. Full Copyright Statement - - Copyright (C) The Internet Society (2000). 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." diff --git a/crypto/heimdal/doc/standardisation/draft-raeburn-krb-gssapi-krb5-3des-01.txt b/crypto/heimdal/doc/standardisation/draft-raeburn-krb-gssapi-krb5-3des-01.txt deleted file mode 100644 index 64ca1ac498be..000000000000 --- a/crypto/heimdal/doc/standardisation/draft-raeburn-krb-gssapi-krb5-3des-01.txt +++ /dev/null @@ -1,395 +0,0 @@ - - - - - - -Kerberos Working Group K. Raeburn -Category: Informational MIT -Document: draft-raeburn-krb-gssapi-krb5-3des-01.txt November 24, 2000 - - - Triple-DES Support for the Kerberos 5 GSSAPI Mechanism - -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 GSSAPI Kerberos 5 mechanism definition [GSSAPI-KRB5] specifically - enumerates encryption and checksum types, independently of how such - schemes may be used in Kerberos. In the long run, a new Kerberos- - based mechanism, which does not require separately enumerating for - the GSSAPI mechanism each of the various encryption types defined by - Kerberos, is probably a better approach. Various people have - expressed interest in designing one, but the work has not yet been - completed. - - The MIT Kerberos 5 release version 1.2 includes support for triple- - DES with key derivation [KrbRev]. Recent work by the EFF [EFF] has - demonstrated the vulnerability of single-DES mechanisms to brute- - force attacks by sufficiently motivated and well-funded parties. So, - in the interest of providing increased security in the near term, MIT - is adding support for triple-DES to the existing mechanism - implementation we ship, as an interim measure. - - - - - - - - -Raeburn [Page 1] - -INTERNET DRAFT Triple-DES for GSSAPI Kerberos November 2000 - - -2. New Algorithm Identifiers - - One new sealing algorithm is defined, for use in Wrap tokens. - - - +--------------------------------------------------------------------+ - | name octet values | - +--------------------------------------------------------------------+ - | DES3-KD 02 00 | - +--------------------------------------------------------------------+ - - This algorithm uses triple-DES with key derivation, with a usage - value KG_USAGE_SEAL. (Unlike the EncryptedData definition in - [KrbRev], no integrity protection is needed, so this is "raw" triple- - DES, with no checksum attached to the encrypted data.) Padding is - still to 8-byte multiples, and the IV for encrypting application data - is zero. - - One new signing algorithm is defined, for use in MIC, Wrap, and - Delete tokens. - - - +--------------------------------------------------------------------+ - | name octet values | - +--------------------------------------------------------------------+ - | HMAC SHA1 DES3-KD 04 00 | - +--------------------------------------------------------------------+ - - This algorithm generates an HMAC using SHA-1 and a derived DES3 key - with usage KG_USAGE_SIGN, as described in [KrbRev]. - - [N.B.: The current [KrbRev] description refers to expired I-Ds from - Marc Horowitz. The text in [KrbRev] may be inadequate to produce an - interoperable implementation.] - - The checksum size for this algorithm is 20 octets. See section 4.3 - below for the use of checksum lengths of other than eight bytes. - - - - - - - - - - - - - - -Raeburn [Page 2] - -INTERNET DRAFT Triple-DES for GSSAPI Kerberos November 2000 - - -3. Key Derivation - - For purposes of key derivation, we add three new usage values to the - list defined in [KrbRev]; one for signing messages, one for sealing - messages, and one for encrypting sequence numbers: - - - +--------------------------------------------------------------------+ - | name value | - +--------------------------------------------------------------------+ - | KG_USAGE_SEAL 22 | - | KG_USAGE_SIGN 23 | - | KG_USAGE_SEQ 24 | - +--------------------------------------------------------------------+ - -4. Adjustments to Previous Definitions - -4.1. Quality of Protection - - The GSSAPI specification [GSSAPI] says that a zero QOP value - indicates the "default". The original specification for the Kerberos - 5 mechanism says that a zero QOP value (or a QOP value with the - appropriate bits clear) means DES encryption. - - Rather than forcing the use of plain DES when the application doesn't - use mechanism-specific QOP values, we redefine the explicit DES QOP - value as a non-zero value, and define a triple-DES value as well. - Then a zero value continues to imply the default, which would be - triple-DES protection when given a triple-DES session key. - - Our values are: - - +--------------------------------------------------------------------+ - | name value meaning | - +--------------------------------------------------------------------+ - | GSS_KRB5_INTEG_C_QOP_HMAC_SHA1 0x0004 SHA-1 HMAC, using | - | key derivation | - | | - | GSS_KRB5_CONF_C_QOP_DES 0x0100 plain DES encryption | - | | - | GSS_KRB5_CONF_C_QOP_DES3_KD 0x0200 triple-DES with key | - | derivation | - +--------------------------------------------------------------------+ - - Rather than attempt to specify a generic mechanism for deriving a key - of one type given a key of another type, and evaluate the security - implications of using a short key to generate a longer key to satisfy - the requested quality of protection, our implementation will simply - - - -Raeburn [Page 3] - -INTERNET DRAFT Triple-DES for GSSAPI Kerberos November 2000 - - - return an error if the nonzero QOP value specified does not - correspond to the session key type. - -4.2. MIC Sequence Number Encryption - - The sequence numbers are encrypted in the context key (as defined in - [GSSAPI-KRB5] -- this will be either the Kerberos session key or - asubkey provided by the context initiator), using whatever encryption - system is designated by the type of that context key. The IV is - formed from the first N bytes of the SGN_CKSUM field, where N is the - number of bytes needed for the IV. (With all algorithms described - here and in [GSSAPI-KRB5], the checksum is at least as large as the - IV.) - -4.3. Message Layout - - Both MIC and Wrap tokens, as defined in [GSSAPI-KRB5], contain an - checksum field SGN_CKSUM. In [GSSAPI-KRB5], this field was specified - as being 8 bytes long. We now change this size to be "defined by the - checksum algorithm", and retroactively amend the descriptions of all - the checksum algorithms described in [GSSAPI-KRB5] to explicitly - specify 8-byte output. Application data continues to immediately - follow the checksum field in the Wrap token. - - The revised message descriptions are thus: - - MIC token: - - Byte # Name Description - ---------------------------------------------------------------------- - 0..1 TOK_ID Identification field. - 2..3 SGN_ALG Integrity algorithm indicator. - 4..7 Filler Contains ff ff ff ff - 8..15 SND_SEQ Sequence number field. - 16..s+15 SGN_CKSUM Checksum of "to-be-signed - data", calculated according to - algorithm specified in SGN_ALG - field. - - - - - - - - - - - - - -Raeburn [Page 4] - -INTERNET DRAFT Triple-DES for GSSAPI Kerberos November 2000 - - - Wrap token: - - Byte # 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. - 4..5 SEAL_ALG Sealing algorithm indicator. - 6..7 Filler Contains ff ff - 8..15 SND_SEQ Encrypted sequence number field. - 16..s+15 SGN_CKSUM Checksum of plaintext padded data, - calculated according to algorithm - specified in SGN_ALG field. - s+16..last Data encrypted or plaintext padded data - - - Where "s" indicates the size of the checksum. - - As indicated above in section 2, we define the HMAC SHA1 DES3-KD - checksum algorithm to produce a 20-byte output, so encrypted data - begins at byte 36. - -5. Backwards Compatibility Considerations - - The context initiator should request of the KDC credentials using - session-key cryptosystem types supported by that implementation; if - the only types returned by the KDC are not supported by the mechanism - implementation, it should indicate a failure. This may seem obvious, - but early implementations of both Kerberos and the GSSAPI Kerberos - mechanism supported only DES keys, so the cryptosystem compatibility - question was easy to overlook. - - Under the current mechanism, no negotiation of algorithm types - occurs, so server-side (acceptor) implementations cannot request that - clients not use algorithm types not understood by the server. - However, administration of the server's Kerberos data (e.g., the - service key) has to be done in communication with the KDC, and it is - from the KDC that the client will request credentials. The KDC could - therefore be tasked with limiting session keys for a given service to - types actually supported by the Kerberos and GSSAPI software on the - server. - - This does have a drawback for cases where a service principal name is - used both for GSSAPI-based and non-GSSAPI-based communication (most - notably the "host" service key), if the GSSAPI implementation does - not understand triple-DES but the Kerberos implementation does. It - means that triple-DES session keys cannot be issued for that service - - - -Raeburn [Page 5] - -INTERNET DRAFT Triple-DES for GSSAPI Kerberos November 2000 - - - principal, which keeps the protection of non-GSSAPI services weaker - than necessary. - - It would also be possible to have clients attempt to get single-DES - session keys before trying to get triple-DES session keys, and have - the KDC refuse to issue the single-DES keys only for the most - critical of services, for which single-DES protection is considered - inadequate. However, that would eliminate the possibility of - connecting with the more secure cryptosystem to any service that can - be accessed with the weaker cryptosystem. - - For MIT's 1.2 release, we chose to go with the former approach, - putting the burden on the KDC administration and gaining the best - protection possible for GSSAPI services, possibly at the cost of - weaker protection of non-GSSAPI Kerberos services running earlier - versions of the software. - -6. Security Considerations - - Various tradeoffs arise regarding the mixing of new and old software, - or GSSAPI-based and non-GSSAPI Kerberos authentication. They are - discussed in section 5. - -7. References - - [EFF] Electronic Frontier Foundation, "Cracking DES: Secrets of - Encryption Research, Wiretap Politics, and Chip Design", O'Reilly & - Associates, Inc., May, 1998. - - [GSSAPI] Linn, J., "Generic Security Service Application Program - Interface Version 2, Update 1", RFC 2743, January, 2000. - - [GSSAPI-KRB5] Linn, J., "The Kerberos Version 5 GSS-API Mechanism", - RFC 1964, June, 1996. - - [KrbRev] Neuman, C., Kohl, J., Ts'o, T., "The Kerberos Network - Authentication Service (V5)", draft-ietf-cat-kerberos- - revisions-06.txt, July 4, 2000. - -8. Author's Address - - Kenneth Raeburn Massachusetts Institute of Technology 77 - Massachusetts Avenue Cambridge, MA 02139 - -9. Full Copyright Statement - - Copyright (C) The Internet Society (2000). All Rights Reserved. - - - - -Raeburn [Page 6] - -INTERNET DRAFT Triple-DES for GSSAPI Kerberos November 2000 - - - 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." - -10. Document Change History - ->From -00 to -01: - - Converted master to GNU troff and tbl, rewriting tables in the - process. - - Specify informational category only. Modify some text to emphasize - that this document intends to describe MIT's extensions. - - Point out that while EncryptedData for 3des-kd includes a checksum, - DES3-KD GSS encryption does not. - - Shorten backwards-compatibility descriptions a little. - - Submit to Kerberos working group rather than CAT. - - - - - - - - - - - -Raeburn [Page 7] - diff --git a/crypto/heimdal/doc/standardisation/draft-smedvinsky-dhc-kerbauth-01.txt b/crypto/heimdal/doc/standardisation/draft-smedvinsky-dhc-kerbauth-01.txt deleted file mode 100644 index 321c5ba09986..000000000000 --- a/crypto/heimdal/doc/standardisation/draft-smedvinsky-dhc-kerbauth-01.txt +++ /dev/null @@ -1,929 +0,0 @@ - - -DHC Working Group S. Medvinsky -Internet Draft Motorola -Document: -Category: Standards Track P.Lalwaney -Expires: January 2001 Nokia - - July 2000 - - - Kerberos V Authentication Mode for Uninitialized Clients - - -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. - - The distribution of this memo is unlimited. It is filed as , and expires January 2001. Please - send comments to the authors. - - - -1. Abstract - - The Dynamic Host Configuration Protocol (DHCP) [1] includes an - option that allows authentication of all DHCP messages, as specified - in [2]. This document specifies a DHCP authentication mode based on - Kerberos V tickets. This provides mutual authentication between a - DHCP client and server, as well as authentication of all DHCP - messages. - - This document specifies Kerberos message exchanges between an - uninitialized client and the KDC (Key Distribution Center) using an - IAKERB proxy [7] so that the Kerberos key management phase is - decoupled from, and precedes the address allocation and network - configuration phase that uses the DHCP authentication option. In - order to make use of the IAKERB proxy, this document specifies a - transport mechanism that works with an uninitialized client (i.e. a - -Kerberos V Authentication Mode for Uninitialized Clients July 2000 - - - client without an assigned IP address). In addition, the document - specifies the format of the Kerberos authenticator to be used with - the DHCP authentication option. - -2. Conventions used in this document - - 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. - -3. Introduction - - 3.1 Terminology - - o "DHCP client" - - A DHCP client is an Internet host using DHCP to obtain configuration - parameters such as a network address. - - o "DHCP server" - - A DHCP server is an Internet host that returns configuration - parameters to DHCP clients. - - O "Ticket" - - A Kerberos term for 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. - - o "Key Distribution Center" - - 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 (TGT) 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). - - o "Realm" - - A Kerberos administrative domain that represents a group of - principals registered at a KDC. A single KDC may be responsible for - one or more realms. A fully qualified principal name includes a - realm name along with a principal name unique within that realm. - -3.2 Protocol Overview - - - -S. Medvinsky, P. Lalwaney -2- - -Kerberos V Authentication Mode for Uninitialized Clients July 2000 - - - DHCP as defined in [1] defines the protocol exchanges for a client - to obtain its IP address and network configuration information from - a DHCP Server. Kerberos V5 as described in [6] defines the protocol - and message exchanges to mutually authenticate two parties. It is - our goal to provide authentication support for DHCP using Kerberos. - This implies that the Kerberos key management exchange has to take - place before a client gets its IP address from the DHCP Server. - Kerberos assumes that the client has a network address and can - contact the Key Distribution Center to obtain its credentials for - authenticated communication with an application server. - - In this specification we utilize the key exchange using an IAKERB - proxy described in [7]. This does not require any changes to either - the IAKERB or the Kerberos V5 specification. This document also - specifies a particular transport that allows an uninitialized client - to contact an IAKERB proxy. - - The Kerberos ticket returned from the key management exchange - discussed in Section 5 of this document is passed to the DHCP Server - inside the DHCP authentication option with the new Kerberos - authenticator type. This is described in Section 6 of this draft. - - -3.3 Related Work - - A prior Internet Draft [3] outlined the use of Kerberos-based - authentication for DHCP. The proposal tightly coupled the Kerberos - client state machines and the DHCP client state machines. As a - result, the Kerberos key management messages were carried in DHCP - messages, along with the Kerberos authenticators. In addition, the - first DHCP message exchange (request, offer) is not authenticated. - - We propose a protocol exchange where Kerberos key management is - decoupled from and precedes authenticated DHCP exchanges. This - implies that the Kerberos ticket returned in the initial key - management exchange could be used to authenticate servers assigning - addresses by non-DHCP address assignment mechanisms like RSIP [4] - and for service specific parameter provisioning mechanisms using SLP - [5]. - - - - - - - - - - - - - - -S. Medvinsky, P. Lalwaney -3- - -Kerberos V Authentication Mode for Uninitialized Clients July 2000 - - - -4. System Architecture - - - Client - -------- -------- - | | 5.Authenticated DHCP | | - | DHCP |<------------------------>| DHCP | - | client | | server | - | | | | - | | | | - |Kerberos| | | - | Client | | | - -------- -------- - ^ - | - | - | - | ------- - ------------------------------>| | - Kerberos Key Mgmt | Proxy | - messages: | | - 1. AS Request / 2.AS Reply ------- - 3. TGS Request / 4.TGS Reply ^ - | Kerberos - | Key Mgmt messages - v (1, 2, 3, 4) - -------- - | | - | KDC | - | | - -------- - - Figure 1: System blocks and message interactions between them - - - In this architecture, the DHCP client obtains a Kerberos ticket from - the Key Distribution Center (KDC) using standard Kerberos messages, - as specified in [6]. The client, however, contacts the KDC via a - proxy server, according to the IAKERB mechanism, described in [7]. - The are several reasons why a client has to go through this proxy in - order to contact the KDC: - - a)The client may not know the host address of the KDC and may be - sending its first request message as a broadcast on a local - network. The KDC may not be located on the local network, and - even if it were - it will be unable to communicate with a client - without an IP address. This document describes a specific - mechanism that may be used by a client to communicate with the - Kerberos proxy. - - - -S. Medvinsky, P. Lalwaney -4- - -Kerberos V Authentication Mode for Uninitialized Clients July 2000 - - - b)The client may not know its Kerberos realm name. The proxy is - able to fill in the missing client realm name in an AS Request - message, as specified in IAKERB. Note that in the case that - PKINIT pre-authenticator is used [8], the realm name in the AS - Request may be the KDC realm name and not the clientÆs realm name. - - c) The client does not know the realm name of the DHCP server. - - According to IAKERB, when the client sends a TGS Request with a - missing server realm name, the proxy will return to the client an - error message containing the missing realm name. - - Note that in this case the proxy could return the client a wrong - realm name and the client could be fooled into obtaining a ticket - for the wrong DHCP server (on the same local network). However, - the wrong DHCP server must still be a registered principal in a - KDC database. In some circumstances this may be an acceptable - compromise. Also, see the security considerations section. - - IAKERB describes the proxy as part of an application server - the - DHCP server in this case. However, in this document we are not - requiring the proxy to be integrated with the DHCP server. The - same IAKERB mechanisms apply in the more general case, where the - proxy is an independent application. This proxy, however, MUST be - reachable by a client via a local network broadcast. - - After a client has obtained a Kerberos ticket for the DHCP server, - it will use it as part of an authentication option in the DHCP - messages. The only extension to the DHCP protocol is the addition - of a new authenticator type based on Kerberos tickets. - -4.1 Cross-Realm Authentication - - Figure 1 shows a client communicating with a single KDC via a proxy. - However, the DHCP clientÆs realm may be different from the DHCP - serverÆs realm. In that case, the client may need to first contact - the KDC in its local realm to obtain a cross-realm TGT. Then, the - client would use the cross-realm TGT to contact the KDC in the DHCP - serverÆs realm, as specified in [6]. - - In the following example a client doesnÆt know its realm or the DHCP - serverÆs realm, which happens to be different from the clientÆs - realm. Here are the steps in obtaining the ticket for the DHCP - server (based on [6] and [7]): - - 1) The client sends AS Request with NULL realm to the proxy. - 2) The proxy fills in the realm and forwards the AS Request to - the KDC in the clientÆs realm. - 3) The KDC issues a TGT and sends back an AS Reply to the - proxy. - 4) The proxy forwards AS Reply to the client. - - -S. Medvinsky, P. Lalwaney -5- - -Kerberos V Authentication Mode for Uninitialized Clients July 2000 - - - 5) The client sends TGS Request for a principal name "dhcpsrvr" - with NULL realm to the proxy. - 6) The proxy returns KRB_AP_ERR_REALM_REQUIRED error with the - DHCP serverÆs realm to the client. - 7) The client sends another TGS Request for a cross-realm TGT - to the proxy. - 8) The proxy forwards the TGS Request to the KDC in the - clientÆs realm. - 9) The KDC issues a cross-realm TGT and sends back a TGS Reply - to the proxy. - 10) The proxy forwards TGS Reply to the client. - 11) The client sends a TGS Request to the proxy for a principal - "dhcpsrvr" with the realm name filled in, using a cross-realm - TGT. - 12) The proxy forwards TGS Request to the KDC in the DHCP - server's realm. - 13) The KDC issues a ticket for the DHCP server and sends TGS - Reply back to the proxy. - 14) The proxy forwards TGS Reply to the client. - - In a most general case, the client may need to contact any number of - KDCs in different realms before it can get a ticket for the DHCP - server. In each case, the client would contact a KDC via the proxy - server, as specified in Section 5 of this document. - -4.2 Public Key Authentication - - This specification also allows clients to perform public key - authentication to the KDC, based on the PKINIT specification [8]. - In this case, the size of an AS Request and AS Reply messages is - likely to exceed the size of typical link MTU's. - - Here is an example, where PKINIT is used by a DHCP client that is - not a registered principal in the KDC principal database: - - 1) The client sends AS Request with a PKINIT Request pre- - authenticator to the proxy. This includes the clientÆs - signature and X.509 certificate. The KDC realm field is - left as NULL. - 2) The proxy fills in the realm and forwards the AS Request to - the KDC in the filled in realm. This is the realm of the - DHCP server. Here, the clientÆs realm is the name of a - Certification Authority - not the same as the KDC realm. - 3) The KDC issues a TGT and sends back an AS Reply with a - PKINIT Reply pre-authenticator to the proxy. - 4) The proxy forwards the AS Reply to the client. - 5) The client sends TGS Request for a principal name "dhcpsrvr" - with the realm found in the TGT to the proxy. - 6) The proxy forwards TGS Request to the KDC in the DHCP - serverÆs realm. - 7) The KDC issues a ticket for the DHCP server and sends TGS - Reply back to the proxy. - -S. Medvinsky, P. Lalwaney -6- - -Kerberos V Authentication Mode for Uninitialized Clients July 2000 - - - 8) The proxy forwards TGS Reply to the client. - - - 5. Key Management Exchange that Precedes Network Address Allocation - - An uninitialized host (e.g. on power-on and reset) does not have a - network address. It does have a link layer address or hardware - address. At this time, the client may not have any information on - its realm or the realm of the address allocation server (DHCP - Server). - - In the Kerberos key management exchange, a client gets its ticket - granting ticket (TGT) by contacting the Authentication Server in the - KDC using the AS_Request / Reply messages (shown as messages 1 and 2 - in Figure 1). The client then contacts the Ticket Granting Server in - the KDC to get the DHCP server ticket (to be used for mutual - authentication with the DHCP server) using the TGS_REQ / TGS_REP - messages (shown as messages 3 and 4 in the above figure). It is - also possible for the client to obtain a DHCP server ticket directly - with the AS Request / Reply exchange, without the use of the TGT. - - In the use of Kerberos for DHCP authentication, the client (a) does - not have an IP/network address (b) does not know he KDCÆs IP address - (c) the KDC may not be on the local network and (d) the client may - not know the DHCP ServerÆs IP address and realm. We therefore - require a Kerberos proxy on the local network to accept broadcast - Kerberos request messages (AS_REQ and TGS_REQ) from uninitialized - clients and relay them to the appropriate KDC. - - The uninitialized client formulates a broadcast AS_REQ or TGS_REQ as - follows: - - The request payload contains the client hardware address in - addresses field with a negative value for the address type. Kerberos - v5 [6] allows for the usage of negative address types for "local" - use. Note that IAKERB [7] discourages the use of the addresses field - as network addresses may not be known or may change in situation - where proxies are used. In this draft we incorporate the negative - values permitted in the Kerberos transport in the address type field - of both the AS_REQ and TGS_REQ messages. The negative value SHOULD - be the negative number of the hardware address type "htype" value - (from assigned numbers RFC) used in RFC 2131. The address field of - the message contains the clients hardware address. - - The request payload is UDP encapsulated and addressed to port 88 on - the server/proxy. The UDP source port is selected by the client. The - source and destination network addresses are the all-zeroÆs address - and the broadcast address, respectively. For IPv4, the source IP - address is set to 0.0.0.0 and the destination IP address is set to - 255.255.255.255. The data link layer header source address - corresponds to the link layer/hardware address of the client. The - - -S. Medvinsky, P. Lalwaney -7- - -Kerberos V Authentication Mode for Uninitialized Clients July 2000 - - - destination link layer address is the broadcast address at the link - layer (e.g. for Ethernet the address is ffffffff). - - In the case where AS_REQ message contains a PKINIT pre-authenticator - for public key-based client authentication (based on [8]), the - message will probably not fit into a single UDP packet given typical - link MTU's. - - It is assumed that the proxy server on a network is configured with - a list of KDCÆs, their realms and their IP addresses. The proxy - server will act as a client to the KDC and forward standard Kerberos - messages to/from the KDC using unicast UDP or TCP transport - mechanisms, according to [6]. - - Upon receiving a broadcast request from a client, the proxy MUST - record the clientÆs hardware address that appears as the source - address on the frame as well as in the addresses field of the - request message. Based on the realm of the KDC specified in the - request, the proxy determines the KDC to which this message is - relayed as a unicast message from the proxy to the KDC. In the case - that the client left the KDC realm name as NULL, it is up to the - proxy to first determine the correct realm name and fill it in the - request (according to [7]). - - On receiving a request, the KDC formulates a response (AS_REP or - TGS_REP). It includes the clientÆs addresses field in the encrypted - part of the ticket (according to [6]). This response is unicast to - the proxy. - - Upon receiving the reply, the proxy MUST first determine the - previously saved hardware address of the client. The proxy - broadcasts the reply on its local network. This is a network layer - broadcast. At the link level, it uses the hardware address obtained - from the addresses field of the request. - - The client on receiving the response (link layer destination address - as its hardware address, network layer address is the broadcast - address) must verify that the hardware address in the ticket - corresponds to its link layer address. - - Upon receiving a TGS_REP (or an AS_REP with the application server - ticket) from the proxy, the client will have enough information to - securely communicate with the application server (the DHCP Server in - this case), as specified in the following section. - - - - - - - - - -S. Medvinsky, P. Lalwaney -8- - -Kerberos V Authentication Mode for Uninitialized Clients July 2000 - - - 6. Authenticated Message Exchange Between the DHCP Client and the - DHCP Server - - The ticket returned in the TGS response is used by the DHCP client - in the construction of the Kerberos authenticator. The Kerberos - ticket serves two purposes: to establish a shared session key with - the DHCP server, and is also included as part of a Kerberos - authenticator in the DHCP request. - - If the size of the authenticator is greater than 255 bytes, the DHCP - authentication option is repeated multiple times. When the values - of all the authentication options are concatenated together, they - will make up the complete authenticator. - - Once the session key is established, the Kerberos structure - containing the ticket (AP REQ) can be omitted from the authenticator - for subsequent messages sent by both the DHCP client and the DHCP - server. - - The Kerberos authenticator for a DHCP request message is specified - below: - - 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 - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | Code | Length | Protocol | Algorithm | - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | | - + Replay Detection (64 bits) + - | | - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | | - + Authentication token (n octets) ... + - | | - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - - The format of this authenticator is in accordance with [2]. The code - for the authentication option is TBD, and the length field contains - the length of the remainder of the option, starting with the - protocol field. - - The value of the protocol field for this authenticator MUST be set - to 2. - - The algorithm field MUST take one of the following values: - 1 - HMAC-MD5 - 2 - HMAC-SHA-1 - - Replay protection field is a monotonically increasing counter field. - When the Kerberos AP REQ structure is present in the authenticator - the counter may be set to any value. The AP REQ contains its own - replay protection mechanism in the form of a timestamp. - -S. Medvinsky, P. Lalwaney -9- - -Kerberos V Authentication Mode for Uninitialized Clients July 2000 - - - - Once the session key has been established and the AP REQ is not - included in the authenticator, this field MUST be monotonically - increasing in the messages sent by the client. - - Kerberos authenticator token consists of type-length-value - attributes: - - 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 - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | Type | Reserved | Payload Length | - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | attribute value... - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - - The following attributes are included in the Kerberos authenticator - token: - - Type Attribute Name Value - -------------------------------------------------------------------- - 0 Message Integrity Code Depends on the value of the - algorithm field. Its length is - 16 bytes for HMAC-MD5 [9, 10] - and 20 bytes for HMAC-SHA-1 - [11, 10]. The HMAC key must be - derived from Kerberos session - key found in the Kerberos - ticket according to the key - derivation rules in [6]: - - HMAC Key = DK(sess key, - key usage | 0x99) - - Here, DK is defined in [12] and - the key usage value for DHCP is - TBD. - - The HMAC is calculated over the - entire DHCP message. The - Message Integrity Code - attribute MUST be set to all 0s - for the computation of the - HMAC. Because a DHCP relay - agent may alter the values of - the 'giaddr' and 'hops' fields - in the DHCP message, the - contents of those two fields - MUST also be set to zero for - the computation of the HMAC. - Rules specified in Section 3 of - [2] for the exclusion and - -S. Medvinsky, P. Lalwaney -10- - -Kerberos V Authentication Mode for Uninitialized Clients July 2000 - - - processing of the relay agent - information are applicable here - too. - - This field MUST always be - present in the Kerberos - authenticator. - - 1 AP_REQ ASN.1 encoding of a Kerberos - AP_REQ message, as specified - in [6]. This MUST be included - by the client when establishing - a new session key. In all - other cases, this attribute - MUST be omitted. - - AP_REQ contains the Kerberos ticket for the DHCP server and also - contains information needed by the DHCP server to authenticate the - client. After verifying the AP_REQ and decrypting the Kerberos - ticket, the DHCP server is able to extract a session key which it - now shares with the DHCP client. - - The Kerberos authenticator token contains its own replay protection - mechanism inside the AP_REQ structure. The AP_REQ contains a - timestamp that must be within an agreed upon time window at the DHCP - server. However, this does not require the DHCP clients to maintain - an accurate clock between reboots. Kerberos allows clients to - synchronize their clock with the KDC with the help of Kerberos - KRB_AP_ERR_SKEW error message, as specified in [6]. - - The DHCP server MUST save both the session key and its associated - expiration time found in the Kerberos ticket. Up until the - expiration time, the server must accept client requests with the - Kerberos authenticator that does not include the AP REQ, using the - saved session key in calculating HMAC values. - - The Kerberos authenticator inside all DHCP server responses MUST NOT - contain the AP REQ and MUST use the saved Kerberos session key in - calculating HMAC values. - - When the session key expires, it is the client's responsibility to - obtain a new ticket from the KDC and to include an AP REQ inside the - Kerberos authenticator for the next DHCP request message. - - - - - - - - - - -S. Medvinsky, P. Lalwaney -11- - -Kerberos V Authentication Mode for Uninitialized Clients July 2000 - - -7. Detailed message flows for Kerberos and DHCP message Exchanges - - The following flow depicts the Kerberos exchange in which a AS REQ - message is used to directly request the DHCP Server ticket. There - are no changes to transport mechanisms below when the additional - phase of using TGS requests/responses with TGTÆs is used. - - Client IAKERB Proxy KDC - - KB-client-------- AS_REQ ------> - - AS REQ Address type = - (htype) - AS REQ Address= hw address - - src UDP port = senders port - destination UDP port = 88 - - src IP = 0.0.0.0 - destination IP = 255.255.255.255 - - src link layer address = - clientÆs HW/link address [e.g Ethernet address] - - destination link layer address = - link broadcast address [e.g. ffffffff for Ethernet] - - - ---------------------------> - (unicast to UDP port 88) - - - - <-------------------------- - (unicast AS REP) - Encrypted portion of ticket - Includes clients HW address - - - <---------------AS_REP ----------- - - - Ticket includes clientÆs hardware address - - src UDP port = 88 - destination UDP port = copied from src port in AS_REQ - - src IP = ProxyÆs IP address - destination IP = 255.255.255.255 - - src link layer address = ProxyÆs HW/link address - destination link layer address = - ClientÆs link layer address from AS_REQ - - -S. Medvinsky, P. Lalwaney -12- - -Kerberos V Authentication Mode for Uninitialized Clients July 2000 - - - - - - The client uses the ticket received from the KDC in the DHCP -Authentication option as described in Section 6. - - - Client - DHCP-client DHCP Server - - ------DHCPDISCOVER ----> - (Auth Protocol = 2, includes Kerberos - authenticator with AP REQ ) - ----------------------------------- - | HMAC | AP REQ | - ---------------------------------- - | Ticket| Client Authent | - -------------------------- - - 1. Server decrypts ticket - (inside AP REQ) with service - key - 2. Server decrypts client - authenticator (inside AP REQ) - and checks content and - checksum to validate the - client. - 3. Recompute HMAC with session - key and compare. - - - <-------DHCPOFFER---------- - (Auth Protocol = 2, no AP REQ ) - - - - ---------DHCPREQUEST-------> - (Auth Protocol = 2, no AP REQ) - - - <--------DHCPACK------------- - (Auth Protocol = 2, no AP REQ ) - - - - -8. Security Considerations - - DHCP clients that do not know the DHCP serverÆs realm name will get - it from the proxy, as specified in IAKERB [7]. Since the proxy is - not authenticated, a DHCP client can be fooled into obtaining a - ticket for the wrong DHCP server in the wrong realm. - -S. Medvinsky, P. Lalwaney -13- - -Kerberos V Authentication Mode for Uninitialized Clients July 2000 - - - - This could happen when the client leaves out the server realm name - in a TGS Request message to the proxy. It is also possible, - however, for a client to directly request a DHCP server ticket with - an AS Request message. In those cases, the same situation occurs - when the client leaves out the realm name in an AS Request. - - This wrong DHCP server is still registered as a valid principal in a - database of a KDC that can be trusted by the client. In some - circumstances a client may assume that a DHCP server that is a - Kerberos principal registered with a trusted KDC will not attempt to - deliberately misconfigure a client. - - This specification provides a tradeoff between: - - 1) The DHCP clients knowing DHCP serverÆs realm ahead of time, - which provides for full 2-way authentication at the cost of - an additional configuration parameter. - 2) The DHCP clients not requiring any additional configuration - information, besides a password or a key (and a public key - certificate if PKINIT is used). This is at the cost of not - being able to fully authenticate the identity of the DHCP - server. - - - -9. References - - - [1]Droms, R., Arbaugh, W., "Dynamic Host Configuration Protocol", - RFC 2131, Bucknell University, March 1997. - - [2]Droms, R., Arbaugh, W., "Authentication for DHCP Messages", - draft-ietf-dhc-authentication-13.txt, June 2000. - - [3]Hornstein, K., Lemon, T., "DHCP Authentication Via Kerberos V", - draft-hornstein-dhc-kerbauth-02.txt, February 2000. - - [4]Borella, M., Grabelsky, D., Lo, J., Tuniguchi, K., "Realm - Specific IP: Protocol Specification ", draft-ietf-nat-rsip- - protocol-06.txt, March 2000. - - [5]Guttman, E., Perkins, C., Veizades, J., Day, M., "Service - Location Protocol, Version 2", RFC 2608, June 1999. - - [6]Neuman, C., Kohl, J., Ts'o, T., "The Kerberos Network - Authentication Service (V5)", draft-ietf-cat-kerberos-revisions- - 05.txt, March 2000. - - - - - -S. Medvinsky, P. Lalwaney -14- - -Kerberos V Authentication Mode for Uninitialized Clients July 2000 - - - - [7]Swift, M., Trostle, J., "Initial Authentication and Pass Through - Authentication Using Kerberos V5 and the GSS-API (IAKERB)", - draft-ietf-cat-iakerb-03.txt, September 1999. - - [8]Tung, B., C. Neuman, M. Hur, A. Medvinsky, S. Medvinsky, J. Wray, - J. Trostle, "Public Key Cryptography for Initial Authentication - in Kerberos", draft-ietf-cat-pk-init-11.txt, March 2000. - - [9]Rivest, R., "The MD5 Message-Digest Algorithm", RFC 1321, April - 1992. - - [10]Krawczyk H., M. Bellare and R. Canetti, "HMAC: Keyed-Hashing for - Message Authentication," RFC 2104, February 1997. - - [11]NIST, FIPS PUB 180-1, "Secure Hash Standard", April 1995. - - [12]Horowitz, M., "Key Derivation for Authentication, Integrity, and - Privacy", draft-horowitz-key-derivation-02.txt, August 1998. - - [13]Bradner, S. "The Internet Standards Process -- Revision 3", RFC - 2026. - - - - 10. Author's Addresses - - Sasha Medvinsky - Motorola - 6450 Sequence Drive - San Diego, CA 92121 - Email: smedvinsky@gi.com - - Poornima Lalwaney - Nokia - 12278 Scripps Summit Drive - San Diego, CA 92131 - Email: poornima.lalwaney@nokia.com - - -11. Expiration - - This memo is filed as , and - expires January 1, 2001. - - - -12. Intellectual Property Notices - - - - - - -S. Medvinsky, P. Lalwaney -15- - -Kerberos V Authentication Mode for Uninitialized Clients March 2000 - - - This section contains two notices as required by [13] for - standards track documents. Per [13], section 10.4(A): - - The IETF takes no position regarding the validity or scope of any - intellectual property or other rights that might be claimed to - pertain to the implementation or use of the technology described in - this document or the extent to which any license under such rights - might or might not be available; neither does it represent that it - has made any effort to identify any such rights. Information on the - IETF's procedures with respect to rights in standards-track and - standards-related documentation can be found in BCP-11. Copies of - claims of rights made available for publication and any assurances - of licenses to be made available, or the result of an attempt made - to obtain a general license or permission for the use of such - proprietary rights by implementers or users of this specification - can be obtained from the IETF Secretariat. - - Per [13] section 10.4(D): - - The IETF has been notified of intellectual property rights - claimed in regard to some or all of the specification contained in - this document. For more information consult the online list of - claimed rights. - - 13. 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. - - - - - -S. Medvinsky, P. Lalwaney -16- - \ No newline at end of file diff --git a/crypto/heimdal/doc/standardisation/draft-swift-win2k-krb-referrals-01.txt b/crypto/heimdal/doc/standardisation/draft-swift-win2k-krb-referrals-01.txt deleted file mode 100644 index 85d745684b2a..000000000000 --- a/crypto/heimdal/doc/standardisation/draft-swift-win2k-krb-referrals-01.txt +++ /dev/null @@ -1,5 +0,0 @@ -This Internet-Draft has expired and is no longer available. - -Unrevised documents placed in the Internet-Drafts directories have a -maximum life of six months. After that time, they must be updated, or -they will be deleted. This document was deleted on July 17, 2000. diff --git a/crypto/heimdal/doc/standardisation/draft-swift-win2k-krb-user2user-01.txt b/crypto/heimdal/doc/standardisation/draft-swift-win2k-krb-user2user-01.txt deleted file mode 100644 index 85d745684b2a..000000000000 --- a/crypto/heimdal/doc/standardisation/draft-swift-win2k-krb-user2user-01.txt +++ /dev/null @@ -1,5 +0,0 @@ -This Internet-Draft has expired and is no longer available. - -Unrevised documents placed in the Internet-Drafts directories have a -maximum life of six months. After that time, they must be updated, or -they will be deleted. This document was deleted on July 17, 2000. diff --git a/crypto/heimdal/doc/standardisation/draft-thomas-snmpv3-kerbusm-00.txt b/crypto/heimdal/doc/standardisation/draft-thomas-snmpv3-kerbusm-00.txt deleted file mode 100644 index 68c170b499ed..000000000000 --- a/crypto/heimdal/doc/standardisation/draft-thomas-snmpv3-kerbusm-00.txt +++ /dev/null @@ -1,1140 +0,0 @@ - - - - - - -INTERNET-DRAFT Kerberized USM Keying M. Thomas - Cisco Systems - K. McCloghrie - Cisco Systems - July 13, 2000 - - - - - - - Kerberized USM Keying - - draft-thomas-snmpv3-kerbusm-00.txt - - - -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. - -Abstract - - The KerbUSM MIB provides a means of leveraging a trusted third party - authentication and authorization mechanism using Kerberos for SNMP V3 - USM users and their associated VACM views. The MIB encodes the normal - Kerberos AP-REQ and AP-REP means of both authenticating and creating - a shared secret between the SNMP V3 Manager and Agent. - -The SNMP Management Framework - - The SNMP Management Framework presently consists of five major - components: An overall architecture, described in RFC 2571 - - - -Thomas draft-thomas-snmpv3-kerbusm-00 [Page 1] - - - - - -INTERNET-DRAFT Kerberized USM Keying 13 July 2000 - - - [RFC2571]. Mechanisms for describing and naming objects and events - for the purpose of management. The first version of this Structure - of Management Information (SMI) is called SMIv1 and described in STD - 16, RFC 1155 [RFC1155], STD 16, RFC 1212 [RFC1212] and RFC 1215 - [RFC1215]. The second version, called SMIv2, is described in STD 58, - RFC 2578 [RFC2578], STD 58, RFC 2579 [RFC2579] and STD 58, RFC 2580 - [RFC2580]. Message protocols for transferring management - information. The first version of the SNMP message protocol is - called SNMPv1 and described in STD 15, RFC 1157 [RFC1157]. A second - version of the SNMP message protocol, which is not an Internet - standards track protocol, is called SNMPv2c and described in RFC 1901 - [RFC1901] and RFC 1906 [RFC1906]. The third version of the message - protocol is called SNMPv3 and described in RFC 1906 [RFC1906], RFC - 2572 [RFC2572] and RFC 2574 [RFC2574]. Protocol operations for - accessing management information. The first set of protocol - operations and associated PDU formats is described in STD 15, RFC - 1157 [RFC1157]. A second set of protocol operations and associated - PDU formats is described in RFC 1905 [RFC1905]. A set of fundamental - applications described in RFC 2573 [RFC2573] and the view-based - access control mechanism described in RFC 2575 [RFC2575]. - - A more detailed introduction to the current SNMP Management Framework - can be found in RFC 2570 [RFC2570]. - - Managed objects are accessed via a virtual information store, termed - the Management Information Base or MIB. Objects in the MIB are - defined using the mechanisms defined in the SMI. - - This memo specifies a MIB module that is compliant to the SMIv2. A - MIB conforming to the SMIv1 can be produced through the appropriate - translations. The resulting translated MIB must be semantically - equivalent, except where objects or events are omitted because no - translation is possible (use of Counter64). Some machine readable - information in SMIv2 will be converted into textual descriptions in - SMIv1 during the translation process. However, this loss of machine - readable information is not considered to change the semantics of the - MIB. - - -Introduction - - The User based Security Model of SNMP V3 (USM) [2] provides a means - of associating different users with different access privileges of - the various MIB's that an agent supports. In conjunction with the - View based Access Control Model of SNMP V3 (VACM) [3], SNMP V3 - provides a means of providing resistance from various threats both - from outside attacks such as spoofing, and inside attacks such as an - user having, say, SET access to MIB variable for which they are not - - - -Thomas draft-thomas-snmpv3-kerbusm-00 [Page 2] - - - - - -INTERNET-DRAFT Kerberized USM Keying 13 July 2000 - - - authorized. - - SNMP V3, unfortunately, does not specify a means of doing key - distribution between the managers and the agents. For small numbers - of agents and managers, the O(n*m) manual keying is a cumbersome, but - possibly tractable problem. For a large number of agents with - distribution of managers, the key distribution quickly goes from - cumbersome to unmanageable. Also: there is always the lingering - concern of the security precautions taken for keys on either local - management stations, or even directories. - - Kerberos [1] provides a means of centralizing key management into an - authentication and authorization server known as a Key Distribution - Center (KDC). At a minimum, Kerberos changes the key distribution - problem from a O(n*m) problem to a O(n) problem since keys are shared - between the KDC and the Kerberos principals rather directly between - each host pair. Kerberos also provides a means to use public key - based authentication which can be used to further scale down the - number of pre-shared secrets required. Furthermore, a KDC is intended - and explicitly expected to be a standalone server which is managed - with a much higher level of security concern than a management - station or even a central directory which may host many services and - thus be exposed to many more possible vectors of attack. - - The MIB defined in this memo describes a means of using the desirable - properties of Kerberos within the context of SNMP V3. Kerberos - defines a standardized means of communicating with the KDC as well as - a standard format of Kerberos tickets which Kerberos principals - exchange in order to authenticate to one another. The actual means of - exchanging tickets, however, is left as application specific. This - MIB defines the SNMP MIB designed to transport Kerberos tickets and - by doing so set up SNMP V3 USM keys for authentication and privacy. - - It should be noted that using Kerberos does introduce reliance on a - key network element, the KDC. This flies in the face of one of SNMP's - dictums of working when the network is misbehaving. While this is a - valid concern, the risk of reliance on the KDC can be significantly - diminished with a few common sense actions. Since Kerberos tickets - can have long life times (days, weeks) a manager of key network - elements can and should maintain Kerberos tickets well ahead ticket - expiration so that likelihood of not being able to rekey a session - while the network is misbehaving is minimized. For non-critical, but - high fanout elements such as user CPE, etc, requiring a pre-fetched - ticket may not be practical, which puts the KDC into the critical - path. However, if all KDC's are unreachable, the non-critical network - elements are probably the least of the worries. - - - - - -Thomas draft-thomas-snmpv3-kerbusm-00 [Page 3] - - - - - -INTERNET-DRAFT Kerberized USM Keying 13 July 2000 - - -Operation - - The normal Kerberos application ticket exchange is accomplished by a - client first fetching a service ticket from a KDC for the service - principal and then sending an AP-REQ to a server to authenticate - itself to the server. The server then sends a AP-REP to finish the - exchange. This MIB maps Kerberos' concept of client and server into - the SNMP V3 concept of Manager and Agent by designating that the - Kerberos Client is the SNMP V3 Agent. Although it could be argued - that an Agent is really a server, in practice there may be many, many - agents and relatively few managers. Also: Kerberos clients may make - use of public key authentication as defined in [4], and it is very - advantageous to take advantage of that capability for Agents rather - than Managers. - - The MIB is intended to be stateless and map USM users to Kerberos - principals. This mapping is explicitly done by putting a Kerberos - principal name into the usmUserSecurityName in the usmUser MIB and - instatiating the krbUsmMibEntry for the usmUserEntry. MIB variables - are accessed with INFORM's or TRAP PDU's and SET's to perform a - normal Kerberos AP-REQ/AP-REP exchange transaction which causes the - keys for a USM user to be derived and installed. The basic structure - of the MIB is a table which augements usmUserEntry's with a Kerberos - principal name as well as the transaction varbinds. In the normal - case, multiple varbinds should be sent in a single PDU which prevents - various race conditions, as well as increasing efficiency. - - It should be noted that this MIB is silent on the subject of how the - Agent and Manager find the KDC. In practice, this may be either - statically provisioned or use either DNS SRV records (RFC 2782) or - Service Location (RFC 2608). This MIB is does not provide for a means - of doing cipher suite negotiation either. It is expected that the - choices for ciphers in the USM MIB will reflect site specific choices - for ciphers. This matches well with the general philosophy of - centralized keying. - -Keying Transactions - - The following shows an error free transaction: - - Note: optional steps or parameters are shown like [ ] - - - - - - - - - - -Thomas draft-thomas-snmpv3-kerbusm-00 [Page 4] - - - - - -INTERNET-DRAFT Kerberized USM Keying 13 July 2000 - - - - Agent Manager KDC - +-- --+ - | 1) <------------------------------- | - | SET (krbUsmPrinTable[usmUserName].krbUsmMibNonce = xxxx; | - | [ krbUsmPrinTable[usmUserName].krbUsmMibTgt = | - | TGT[usmUserSecurityName] ]); | - | | - | 2) -------------------------------> | - | Response | - +-- (optional) --+ - - 3) ---------------------------------------------------------------> - TGS-REQ (krbUsmPrinTable[usmUserName].krbUsmMibMgrPrinName - [, krbUsmPrinTable[usmUserName].krbUsmMibTgt]); - - 4) <-------------------------------------------------------------- - Tick[usmUserSecurityName] = TGS-REP (); - - 5) ------------------------------> - INFORM (krbUsmPrinTable[usmUserName].krbUsmMibApReq = - AP_REQ[Tick[usmUserSecurityName]]; - [ krbUsmPrinTable[usmUserName].krbUsmMibNonce = xxxx]); - - 6) <------------------------------ - SET (krbUsmPrinTable[usmUserName].krbUsmMibApRep = AP_REP[]); - - - 7) ------------------------------> - Response - - - The above flow translates to: - - - 1) This step is used when the Manager does not currently have a ses- - sion with the Agent but wishes to start one. The Manager MAY - place a ticket granting ticket into the krbUsmMibMgrTgt varbind - in the same PDU as the krbUsmMibNonce if it does not share a - secret with the KDC (as would be the case if the Manager used - PKinit to do initial authentication with the KDC). - - - 2) This step acknowledges the SET. There are no MIB specific errors - which can happen here. - - - 3) If the Agent is not already in possession of a service ticket for - - - -Thomas draft-thomas-snmpv3-kerbusm-00 [Page 5] - - - - - -INTERNET-DRAFT Kerberized USM Keying 13 July 2000 - - - the Manager in its ticket cache, it MUST request a service ticket - from the Agent's KDC for the service principal given by - krbUsmMibMgrPrinName in the row that the krbUsmMibNonce was SET - in, optionally adding a krbUsmMibMgrTgt. If the TGT is speci- - fied, the Manager's TGT must be placed in the additional-tickets - field with the ENC-TKT-IN-SKEY option set in the TGS-REQ to - obtain a service ticket (see section 3.3.3 of [1]). - - Note: a Kerberos TGS-REQ is but one way to obtain a service - ticket. An Agent may use any normal Kerberos means to - obtain the service ticket. This flow has also elided ini- - tial authentication (ie, AS-REQ) and any cross realm con- - siderations, though those may be necessary prerequisites - to obtaining the service ticket. - - 4) If step 3 was performed, this step receives the ticket or an - error from the KDC. - - - 5) This step sends a krbUsmMibApReq to the Manager via an INFORM or - TRAP PDU. If the message is the result of a request by the - Manager, krbUsmMibNonce received from the Manager MUST be sent in - the same PDU. If the Manager did not initiate the transaction, - the Agent MUST NOT send a krbUsmMibNonce varbind. The Agent also - MUST check krbUsmMibUnsolicitedNotify is not false, otherwise it - MUST abort the transaction. All krbUsmMibApReq's MUST contain a - sequence nonce so that the resulting krbUsmMibApRep can provide a - proof of the freshness of the message to prevent replay attacks. - - If the Agent encounters an error either generated by the KDC or - internally, the Agent MUST send an INFORM or TRAP PDU indicating - the error in the form of a KRB-ERROR placed in krbUsmMibApReq - with the same rules applied to krbUsmMibNonce and krbUsmMibUnsol- - icitedNotify above. If the Agent suspects that it is being - attacked by a purported Manager which is generating many failed - TGS-REQ's to the KDC, it SHOULD meter its TGS-REQ transactions - for that Manager to the KDC using an exponential backoff mechan- - ism truncated at 10 seconds. - - - - 6) Upon recepit of an INFORM or TRAP PDU with a krbUsmMibApReq, a - Manager may accept the AP-REQ. If it is accompanied with a - krbUsmMibNonce it MUST correlate it with any outstanding transac- - tions using its stored nonce for the transaction. If it does not - correlate with a current nonce, the request MUST be rejected as - it may be a replay. - - - - -Thomas draft-thomas-snmpv3-kerbusm-00 [Page 6] - - - - - -INTERNET-DRAFT Kerberized USM Keying 13 July 2000 - - - If the Manager chooses to reject an unsolicited keying request, - it SHOULD send a WrongValue Error to the Agent with the krbUsmMi- - bApReq as the subject of the WrongValue. If an Agent receives a - WrongValue Error from a Manager it MUST cease retransmission of - the INFORM or TRAP PDU's so as to mitigate event avalanches by - Agents. There is a possible denial of service attack here, but it - must be weighed against the larger problem of network congestion, - flapping, etc. Therefore, if the Agent finds that it cannot can- - cel an unsolicited Notify (ie, it must be reliable), it MUST use - a truncated exponential backoff mechanism with the maximum trun- - cation interval set to 10 minutes. - - Otherwise, the Manager MUST send a SET PDU to the Agent which - contains a krbUsmMibApRep. - - - 7) If the Agent detects an error (including detecting replays) in - the final AP-REP, it MUST send a WrongValue error with a pointer - to the krbUsmMibApRep varbind to indicate its inability to estab- - lish the security association. Otherwise, receipt of the positive - acknowledgement from the final SET indicates to the Manager that - the proper keys have been installed on the Agent in the USM MIB. - -Unsolicited Agent Keying Requests - - An Agent may find that it needs to set up a security association for - a USM user in order to notify a Manager of some event. When the Agent - engine receives a request for a notify, it SHOULD check to see if - keying material has been established for the user and that the keying - material is valid. If the keying material is not valid and the USM - user has been tagged as being a Kerberos principal in a realm, the - Agent SHOULD first try to instantiate a security association by - obtaining a service ticket for the USM User and follow steps 3-7 of - the flow above. This insures that the USM User will have proper key- - ing material and providing a mechanism to allow for casual security - associations to be built up and torn down. This is especially useful - for Agents which may not normally need to be under constant Manager - supervision, such as the case with high fan out user residential CPE - and other SNMP managed "appliances". In all cases, the Agent MUST NOT - send an unsolicited Notify if krbUsmUnsolicitedNotify is set to - false. - - How the Agent obtains the Manager's address, how it determines - whether a Manager, realm, and whether it can be keyed using this MIB - is outside of the scope of this memo. - - Note: Although the MIB allows for a Manager to set up a session - using User-User mode of Kerberos by sending a TGT along with - - - -Thomas draft-thomas-snmpv3-kerbusm-00 [Page 7] - - - - - -INTERNET-DRAFT Kerberized USM Keying 13 July 2000 - - - the nonce, this, is limited to Manager initiated sessions - only since there is no easy way to store the Manager's ticket - in the MIB since it is publicly writable and as such would be - subject to denial of service attacks. Another method might be - to have the Agent send a krbUsmMibNonce to the Manager which - would tell it to instigate a session. Overall, it seems like - a marginal feature to allow a PKinit authenticated user be - the target of unsolicited informs and it would complicate the - transactions. For this reason, this scenario has been omitted - in favor of simplicity. - -Retransmissions - - Since this MIB defines not only variables, but transactions, discus- - sion of the retransmission state machine is in order. There are two - similar but different state machines for the Manager Solicited and - Agent Unsolicited transactions. There is one timer Timeout which - SHOULD take into consideration round trip considerations and MUST - implement a truncated exponential backoff mechanism. In addition, in - the case where an Agent makes an unsolicited Agent keying request, - the Agent SHOULD perform an initial random backoff if the keying - request to the Manager may result in a restart avalanche. A suitable - method is described in section 4.3.4 of [5]. - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Thomas draft-thomas-snmpv3-kerbusm-00 [Page 8] - - - - - -INTERNET-DRAFT Kerberized USM Keying 13 July 2000 - - - -Manager Solicited Retransmission State Machine - - Timeout - +---+ - | | - | V - +-----------+ Set-Ack (2) +----------+ - | |------------>| | - | Set-Nonce | | Ap-Req | - | (1) |<------------| (5) | - +-----------+ Timeout +----------+ - ^ | - | | Set-Ap-Rep - | +----------+ | (6) - +------| |<------+ - Timeout | Estab-wt | - | (7) | - +----------+ - | - | Set-Ap-Rep-Ack (7) - V - +----------+ - | | - | Estab | - | | - - +----------+ - - - - - - - - - - - - - - - - - - - - - - - -Thomas draft-thomas-snmpv3-kerbusm-00 [Page 9] - - - - - -INTERNET-DRAFT Kerberized USM Keying 13 July 2000 - - - -Agent Unsolicited Retransmission State Machine - - Timeout - +---+ - | | - | V - +----------+ - | | - +----> | Ap-Req |-------+ - | | (5) | | - | +----------+ | - | | - | | Set-Ap-Rep - | +----------+ | (6) - +------| |<------+ - Timeout | Estab-wt | - | (7) | - +----------+ - | - | Set-Ap-Rep-Ack (7) - V - +----------+ - | | - | Estab | - | | - +----------+ - -Session Duration and Failures - - The KerbUsmMib uses the ticket lifetime to determine the life of the - USM session. The Agent MUST keep track of whether the ticket which - instigated the session is valid whenever it forms PDU's for that par- - ticular user. If a session expires, or if it wasn't valid to begin - with (from the Agent's perspective), the Agent MUST reject the PDU by - sending a XXX Error [mat: help me here Keith... what does USM say - about this?]. - - Kerberos also inherently implies adding state to the Agent and - Manager since they share not only a key, but a lifetime associated - with that key. This is in some sense soft state because failure of an - Agent will cause it to reject PDU's for Managers with whom it does - not share a secret. The Manager can use the Error PDU's as an indica- - tion that it needs to reauthenticate with the Agent, taking care not - to loop. The Manager is even easier: when it reboots, it can either - check its credential cache to reconstruct state or cause the Agent to - reauthenticate to the Manager with its service ticket by initiating a - authentication transaction with the manager. - - - -Thomas draft-thomas-snmpv3-kerbusm-00 [Page 10] - - - - - -INTERNET-DRAFT Kerberized USM Keying 13 July 2000 - - -Manager Collisions - - Managers may freely set up keys for different USM users using this - MIB without problem since they access different rows in the krbUsm- - PrinTable. However, multiple Managers trying to set up keys for the - same USM user is possible but discouraged. The requirement for the - Manager is that they MUST share the same service key with the KDC so - that they can all decrypt the same service ticket. There are two race - conditions, however, which are not well handled: - - - -1) At the end of a ticket lifetime, one manager may request the agent - to refresh its service ticket causing a new session key to be - installed for the USM user leaving the other managers with stale - keys. The workaround here is that the Agent will reject the stale - manager's PDU's which should inform them to do their own rekeying - operations. - - -2) If multiple managers try to access the same row at the same time, - the Agent SHOULD try to keep the transactions separate based on the - nonce values. The Managers or the Agents SHOULD NOT break the - krbUsmMibNonce and any other additional varbinds into separate PDU's - as this may result in a meta stable state. Given normal MTU sizes, - this should not be an issue in practice, and this should at worst - devolve into the case above. - - In all cases, the krbUsmMibNonce MUST be the last value to be - transmitted, though its position within a PDU is unimportant. - - - - - - - - - - - - - - - - - - - - - -Thomas draft-thomas-snmpv3-kerbusm-00 [Page 11] - - - - - -INTERNET-DRAFT Kerberized USM Keying 13 July 2000 - - - - KrbUSM MIB - - KRB-USM-MIB DEFINITIONS ::= BEGIN - IMPORTS - MODULE-IDENTITY, - OBJECT-TYPE, OBJECT-IDENTITY, - snmpModules, Counter32, Unsigned32 FROM SNMPv2-SMI - TruthValue, DisplayString FROM SNMPv2-TC - usmUserEntry FROM SNMP-USER-BASED-SM-MIB - - - - krbUsmMib MODULE-IDENTITY - LAST-UPDATED "00071300Z" - ORGANIZATION "IETF SNMP V3 Working Group" - CONTACT-INFO - "Michael Thomas - Cisco Systems - 375 E Tasman Drive - San Jose, Ca 95134 - Phone: +1 408-525-5386 - Fax: +1 801-382-5284 - email: mat@cisco.com" - DESCRIPTION - "This MIB contains the MIB variables to - exchange Kerberos credentials and a session - key to be used to authenticate and set up - USM keys" - - ::= { snmpModules nnn } -- not sure what needs to be here. - krbUsmMibObjects OBJECT INDENTIFIER ::= { krbUsmMib 1 } - - krbUsmMibAuthInAttemps - SYNTAX Counter32 - MAX-ACCESS read-only - STATUS current - DESCRIPTION - "Counter of the number of Kerberos - authorization attempts as defined by - receipt of a PDU from a Manager with a - krbUsmMibNonce set in the principal table." - ::= { krbUsmMibObjects 1 } - - krbUsmMibAuthOutAttemps - SYNTAX Counter32 - MAX-ACCESS read-only - STATUS current - - - -Thomas draft-thomas-snmpv3-kerbusm-00 [Page 12] - - - - - -INTERNET-DRAFT Kerberized USM Keying 13 July 2000 - - - DESCRIPTION - "Counter of the number of unsolicited Kerberos - authorization attempts as defined by - an Agent sending an INFORM or TRAP PDU with a - krbUsmMibApRep but without krbUsmApMibNonce - varbind." - ::= { krbUsmMibObjects 2 } - krbUsmMibAuthInFail - SYNTAX Counter32 - MAX-ACCESS read-only - STATUS current - DESCRIPTION - "Counter of the number of Kerberos - authorization failures as defined by - a Manager setting the krbUsmMibNonce - in the principal table which results - in some sort of failure to install keys - in the requested USM user entry." - ::= { krbUsmMibObjects 3 } - - krbUsmMibAuthOutFail - SYNTAX Counter32 - MAX-ACCESS read-only - STATUS current - DESCRIPTION - "Counter of the number of unsolicited Kerberos - authorization failures as defined by - an Agent sending an INFORM or TRAP PDU with a - krbUsmMibApRep but without a krbUsmMibNonce - varbind which does not result in keys being - installed for that USM user entry." - ::= { krbUsmMibObjects 4 } - - krbUsmMibPrinTable OBJECT-TYPE - SYNTAX SEQUENCE OF krbUsmMibEntry - MAX-ACCESS not-accessible - STATUS current - DESCRIPTION - "Table which maps Kerberos principals with USM - users as well as the per user variables to key - up sessions" - ::= { krbUsmMibObjects 5 } - - krbUsmMibPrinEntry OBJECT-TYPE - SYNTAX KrbUsmMibPrinEntry - MAX-ACCESS not-accessible - STATUS current - DESCRIPTION - - - -Thomas draft-thomas-snmpv3-kerbusm-00 [Page 13] - - - - - -INTERNET-DRAFT Kerberized USM Keying 13 July 2000 - - - "an entry into the krbMibPrinTable which is a - parallel table to UsmUserEntry table" - AUGMENTS { usmUserEntry } - ::= { krbUsmMibPrinTable 1 } - - KrbUsmMibPrinEntry SEQUENCE - { - krbUsmMibApReq OCTET STRING, - krbUsmMibApRep OCTET STRING, - krbUsmMibNonce OCTET STRING, - krbUsmMibMgrTGT OCTET STRING, - krbUsmMibUnsolicitedNotify TruthValue, - } - - - krbUsmMibApReq OBJECT-TYPE - SYNTAX OCTET STRING - MAX-ACCESS accessible-for-notify - STATUS current - DESCRIPTION - "This variable contains a DER encoded Kerberos - AP-REQ or KRB-ERROR for the USM user which is - to be keyed. This is sent from the Agent to - the Manager in an INFORM or TRAP request. - KRB-ERROR MUST only be sent to the Manager - if it is in response to a keying request from - the Manager. - " - ::= { krbUsmMibPrinEntry 1 } - - krbUsmMibApRep OBJECT-TYPE - SYNTAX OCTET STRING - MAX-ACCESS read-write - STATUS current - DESCRIPTION - "This variable contains the DER encoded response - to an AP-REQ. This variable is SET by the - Manager to acknowledge receipt of an AP-REQ. If - krbUsmMibApRep contains a Kerberos AP-REP, the - Agent must derive keys from the session key - of the Kerberos ticket in the AP-REQ and place - them in the USM database in a manner specified - by [RFC2574]. If the Manager detects an error, - it will instead place a KRB-ERROR in this - variable to inform the Agent of the error. - - This variable is in effect a write-only variable. - attempts to read this variable will result in a - - - -Thomas draft-thomas-snmpv3-kerbusm-00 [Page 14] - - - - - -INTERNET-DRAFT Kerberized USM Keying 13 July 2000 - - - null octet string being returned" - ::= { krbUsmMibPrinEntry 2 } - - krbUsmMibNonce OBJECT-TYPE - SYNTAX OCTET STRING - MAX-ACCESS read-write - STATUS current - DESCRIPTION - "SET'ing a krbUsmMibnonce allows a Manager to - determine whether an INFORM or TRAP from an - Agent is an outstanding keying request, or - unsolicited from the Agent. The Manager - initiates keying for a particular USM user - by writing a nonce into the row for which - desires to establish a security association. - The nonce is an ASCII string of the form - ``host:port?nonce'' where: - - host: is either an FQDN, or valid ipv4 or ipv6 - numerical notation of the Manager which - desires to initiate keying - port: is the destination port at which that the - Manager may be contacted - nonce: is a number generated by the Manager to - correlate the transaction - - The same nonce MUST be sent to the Manager in a - subsequent INFORM or TRAP with a krbUsmApReq. - The Agent MUST use the host address and port - supplied in the nonce as the destination of a - subsequent INFORM or TRAP. Unsolicited keying - requests MUST NOT contain a nonce, and should - instead use the destination stored Notifies of - this type. - - Nonces MUST be highly collision resistant either - using a time based method or a suitable random - number generator. Managers MUST never create - nonces which are 0. - - This variable is in effect a write-only variable. - Attempts to read this variable will result in a - nonce of value 0 being returned" - - - ::= { krbUsmMibPrinEntry 3 } - - - - - -Thomas draft-thomas-snmpv3-kerbusm-00 [Page 15] - - - - - -INTERNET-DRAFT Kerberized USM Keying 13 July 2000 - - - krbUsmMibMgrTgt OBJECT-TYPE - SYNTAX OCTET STRING - MAX-ACCESS read-write - STATUS current - DESCRIPTION - "If the Manager does not possess a symmetric - key with the KDC as would be the case with - a Manager using PKinit for authentication, - the Manager MUST SET its DER encoded ticket - granting ticket into KrbUsmMgrTgt along - with krbUsmMibNonce. - - The agent will then attach the Manager's TGT - into the additional tickets field of the - TGS-REQ message to the KDC to get a User-User - service ticket. - - This variable is in effect a write-only variable. - Attempts to read this variable will result in a - null octet string being returned" - ::= { krbUsmMibPrinEntry 4 } - - - krbUsmMibUnsolicitedNotify OBJECT-TYPE - SYNTAX TruthValue - MAX-ACCESS read-write - STATUS current - DESCRIPTION - "If this variable is false, the Agent MUST NOT - send unsolicited INFORM or TRAP PDU's to the - Manager. - - Attempts to SET this variable by the no-auth - no-priv user MUST be rejected." - ::= { krbUsmMibPrinEntry 5 } - - -- - -- Conformance section... nothing optional. - - krbUsmMibCompliences MODULE-COMPLIANCE - STATUS current - DESCRIPTION "The compliance statement for SNMP - engines whichimplement the KRB-USM-MIB - " - MODULE -- this module - MANDATORY-GROUPS { krbUsmMib } - ::= { krbUsmMibCompliances 1 } - - - - -Thomas draft-thomas-snmpv3-kerbusm-00 [Page 16] - - - - - -INTERNET-DRAFT Kerberized USM Keying 13 July 2000 - - - END - - -Key Derivation - - The session key provides the basis for the keying material for the - USM user specified in the AP-REQ. The actual keys for use for the - authentication and privacy are produced using the cryptographic hash- - ing function used to protect the ticket itself. The keying material - is derived using this function, F(key, salt), using successive - interations of F over the salt string "SNMPV3RULZ%d", where %d is a - monotonic counter starting at zero. The bits are taken directly from - the successive interations to produce two keys of appropriate size - (as specified in the USM user row) for the authentication transform - first, and the privacy transform second. If the authentication - transform is null, the first bits of the derived key are used for the - privacy transform. - -Security Considerations - - Various elements of this MIB must be readable and writable as the - no-auth, no-priv user. Unless specifically necessary for the key - negotiation, elements of this MIB SHOULD be protected by VACM views - which limit access. In particular, there is no reason anything in - this MIB should be visible to a no-auth, no-priv user with the excep- - tion of KrbUsmMibApReq, KrbUsmMibApRep, KrbUsmMibNonce, and - KrbUsmMibMgrTgt, and then only with the restrictions placed on them - in the MIB. As such, probing attacks are still possible, but should - not be profitable: all of the writable variables with interesting - information in them are defined in such a way as to be write only. - - There are some interesting denial of service attacks which are possi- - ble by attackers spoofing managers and putting load on the KDC to - generate unnecessary tickets. For large numbers or agents this could - be problematic. This can probably be mitigated by the KDC prioritiz- - ing TGS-REQ's though. - - -References - -[1] The CAT Working Group, J. Kohl, C.Neuman, "The Kerberos - Network Authentication Service (V5)", RFC 1510, September - 1993 - -[2] The SNMPV3 Working Group, U. Blumenthal, B. Wijnen, "The - User-based Security Model of SNMP V3", RFC 2574, April 1999 - -[3] The SNMPV3 Working Group, B. Wijnen, R. Presuhn, - - - -Thomas draft-thomas-snmpv3-kerbusm-00 [Page 17] - - - - - -INTERNET-DRAFT Kerberized USM Keying 13 July 2000 - - - K.McCloghrie, "The View-based Access Control Model of SNMP - V3", RFC 2575, April 1999 - -[4] The CAT Working Group, Tung, et al, "Public Key Cryptography - for Initial Authentication in Kerberos", draft-ietf-cat-pk- - init-11, November 1999 - -[5] Arango, et al, "Media Gateway Control Protocl (MGCP)", RFC - 2705, October 1999 - - -[RFC2571] Harrington, D., Presuhn, R., and B. Wijnen, An Architecture - for Describing SNMP Management Frameworks, RFC 2571, April - 1999. - -[RFC1155] Rose, M., and K. McCloghrie, Structure and Identification of - Management Information for TCP/IP-based Internets, STD 16, - RFC 1155, May 1990. - -[RFC1212] Rose, M., and K. McCloghrie, Concise MIB Definitions, STD - 16, RFC 1212, March 1991. - -[RFC1215] M. Rose, A Convention for Defining Traps for use with the - SNMP, RFC 1215, March 1991. - -[RFC2578] McCloghrie, K., Perkins, D., Schoenwaelder, J., Case, J., - Rose, M., and S. Waldbusser, Structure of Management Infor- - mation Version 2 (SMIv2), STD 58, RFC 2578, April 1999. - -[RFC2579] McCloghrie, K., Perkins, D., Schoenwaelder, J., Case, J., - Rose, M., and S. Waldbusser, Textual Conventions for SMIv2, - STD 58, RFC 2579, April 1999. - -[RFC2580] McCloghrie, K., Perkins, D., Schoenwaelder, J., Case, J., - Rose, M., and S. Waldbusser, Conformance Statements for - SMIv2, STD 58, RFC 2580, April 1999. - -[RFC1157] Case, J., Fedor, M., Schoffstall, M., and J. Davin, Simple - Network Management Protocol, STD 15, RFC 1157, May 1990. - -[RFC1901] Case, J., McCloghrie, K., Rose, M., and S. Waldbusser, - Introduction to Community-based SNMPv2, RFC 1901, January - 1996. - -[RFC1906] Case, J., McCloghrie, K., Rose, M., and S. Waldbusser, Tran- - sport Mappings for Version 2 of the Simple Network Manage- - ment Protocol (SNMPv2), RFC 1906, January 1996. - - - - -Thomas draft-thomas-snmpv3-kerbusm-00 [Page 18] - - - - - -INTERNET-DRAFT Kerberized USM Keying 13 July 2000 - - -[RFC2572] Case, J., Harrington D., Presuhn R., and B. Wijnen, Message - Processing and Dispatching for the Simple Network Management - Protocol (SNMP), RFC 2572, April 1999. - -[RFC2574] Blumenthal, U., and B. Wijnen, User-based Security Model - (USM) for version 3 of the Simple Network Management Proto- - col (SNMPv3), RFC 2574, April 1999. - -[RFC1905] Case, J., McCloghrie, K., Rose, M., and S. Waldbusser, Pro- - tocol Operations for Version 2 of the Simple Network Manage- - ment Protocol (SNMPv2), RFC 1905, January 1996. - -[RFC2573] Levi, D., Meyer, P., and B. Stewart, SNMPv3 Applications, - RFC 2573, April 1999. - -[RFC2575] Wijnen, B., Presuhn, R., and K. McCloghrie, View-based - Access Control Model (VACM) for the Simple Network Manage- - ment Protocol (SNMP), RFC 2575, April 1999. - -[RFC2570] Case, J., Mundy, R., Partain, D., and B. Stewart, Introduc- - tion to Version 3 of the Internet-standard Network Manage- - ment Framework, RFC 2570, April 1999. - -Author's Address - - Michael Thomas - Cisco Systems - 375 E Tasman Rd - San Jose, Ca, 95134, USA - Tel: +1 408-525-5386 - email: mat@cisco.com - - - - - - - - - - - - - - - - - - - - -Thomas draft-thomas-snmpv3-kerbusm-00 [Page 19] - - diff --git a/crypto/heimdal/doc/standardisation/draft-trostle-win2k-cat-kerberos-set-passwd-00.txt b/crypto/heimdal/doc/standardisation/draft-trostle-win2k-cat-kerberos-set-passwd-00.txt deleted file mode 100644 index b89108a53be9..000000000000 --- a/crypto/heimdal/doc/standardisation/draft-trostle-win2k-cat-kerberos-set-passwd-00.txt +++ /dev/null @@ -1,227 +0,0 @@ - -CAT Working Group Mike Swift -draft-trostle-win2k-cat-kerberos-set-passwd-00.txt Microsoft -February 2000 Jonathan Trostle -Category: Informational Cisco Systems - John Brezak - Microsoft - - Extending Change Password for Setting Kerberos Passwords - - -0. 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. - - Comments and suggestions on this document are encouraged. Comments - on this document should be sent to the CAT working group discussion - list: - ietf-cat-wg@stanford.edu - -1. Abstract - - The Kerberos [1] change password protocol [2], does not allow for - an administrator to set a password for a new user. This functionality - is useful in some environments, and this proposal extends [2] to - allow password setting. The changes are: adding new fields to the - request message to indicate the principal which is having its - password set, not requiring the initial flag in the service ticket, - using a new protocol version number, and adding three new result - codes. - -2. The Protocol - - The service must accept requests on UDP port 464 and TCP port 464 as - well. The protocol 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. - - For TCP transport, there is a 4 octet header in network byte order - precedes the message and specifies the length of the message. This - - requirement is consistent with the TCP transport header in 1510bis. - -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 / - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - - All 16 bit fields are in big-endian order. - - message length field: contains the number of bytes in the message - including this field. - - protocol version number: contains the hex constant 0xff80 (big-endian - integer). - - AP-REQ length: length of AP-REQ data, in bytes. If the length is zero, - then the last field contains a KRB-ERROR message instead of a KRB-PRIV - message. - - AP-REQ data: (see [1]) The AP-REQ message must be for the service - principal kadmin/changepw@REALM, where REALM is the REALM of the user - who wishes to change/set his password. The ticket in the AP-REQ must - must include a subkey in the Authenticator. To enable setting of - passwords, it is not required that the initial flag be set in the - Kerberos service ticket. - - KRB-PRIV message (see [1]) This KRB-PRIV message must be generated - using the subkey from the authenticator in the AP-REQ data. - - The user-data component of the message consists of the following ASN.1 - structure encoded as an OCTET STRING: - - ChangePasswdData ::= SEQUENCE { - newpasswd[0] OCTET STRING, - targname[2] PrincipalName OPTIONAL, - targrealm[3] Realm OPTIONAL - } - - The server must verify the AP-REQ message, check whether the client - principal in the ticket is authorized to set/change the password - (either for that principal, or for the principal in the targname - field if present), and decrypt the new password. The server also - checks whether the initial flag is required for this request, - replying with status 0x0007 if it is not set and should be. An - authorization failure is cause to respond with status 0x0005. For - forward compatibility, the server should be prepared to ignore fields - after targrealm in the structure that it does not understand. - - The newpasswd field contains the cleartext password, and the server - should apply any local policy checks including password policy checks. - The server then generates the appropriate keytypes from the password - - and stores them in the KDC database. If all goes well, status 0x0000 - is returned to the client in the reply message (see below). - -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 message / - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - - - All 16 bit fields are in big-endian order. - - message length field: contains the number of bytes in the message - including this field. - - protocol version number: contains the hex constant 0x0001 (big-endian - integer). (The reply message has the same format as in [2]). - - AP-REP length: length of AP-REP data, in bytes. If the length is zero, - then the last field contains a KRB-ERROR message instead of a KRB-PRIV - message. - - AP-REP data: the AP-REP is the response to the AP-REQ in the request - packet. - - KRB-PRIV from [2]: This KRB-PRIV message must be generated using the - subkey in the authenticator in the AP-REQ data. - - The server will respond with a KRB-PRIV message unless it cannot - decode the client AP-REQ or KRB-PRIV message, in which case it will - respond with a KRB-ERROR message. NOTE: Unlike change password version - 1, the KRB-ERROR message will be sent back without any encapsulation. - - 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) (result codes 0-4 are from [2]): - The result code must have one of the following values (big- - endian integer): - KRB5_KPASSWD_SUCCESS 0 request succeeds (This value is not - allowed in a KRB-ERROR message) - KRB5_KPASSWD_MALFORMED 1 request fails due to being malformed - KRB5_KPASSWD_HARDERROR 2 request fails due to "hard" error in - processing the request (for example, - there is a resource or other problem - causing the request to fail) - - KRB5_KPASSWD_AUTHERROR 3 request fails due to an error in - authentication processing - KRB5_KPASSWD_SOFTERROR 4 request fails due to a "soft" error - in processing the request - KRB5_KPASSWD_ACCESSDENIED 5 requestor not authorized - KRB5_KPASSWD_BAD_VERSION 6 protocol version unsupported - KRB5_KPASSWD_INITIAL_FLAG_NEEDED 7 initial flag required - 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 - from [2]: - 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. - -3. References - - [1] J. Kohl, C. Neuman. The Kerberos Network Authentication - Service (V5). Request for Comments 1510. - - [2] M. Horowitz. Kerberos Change Password Protocol. - ftp://ds.internic.net/internet-drafts/ - draft-ietf-cat-kerb-chg-password-02.txt - -4. Expiration Date - - This draft expires in August 2000. - -5. Authors' Addresses - - Jonathan Trostle - Cisco Systems - 170 W. Tasman Dr. - San Jose, CA 95134 - Email: jtrostle@cisco.com - - Mike Swift - 1 Microsoft Way - Redmond, WA 98052 - mikesw@microsoft.com - - John Brezak - 1 Microsoft Way - Redmond, WA 98052 - jbrezak@microsoft.com diff --git a/crypto/heimdal/doc/standardisation/draft-tso-telnet-krb5-04.txt b/crypto/heimdal/doc/standardisation/draft-tso-telnet-krb5-04.txt deleted file mode 100644 index e9611e395bfd..000000000000 --- a/crypto/heimdal/doc/standardisation/draft-tso-telnet-krb5-04.txt +++ /dev/null @@ -1,327 +0,0 @@ -Network Working Group T. Ts'o, Editor -Internet-Draft Massachusetts Institute of Technology -draft-tso-telnet-krb5-04.txt April 2000 - - Telnet Authentication: Kerberos Version 5 - -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 mate- - rial 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. - - 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. - -0. Abstract - - This document describes how Kerberos Version 5 [1] is used with the - telnet protocol. It describes an telnet authentication sub-option - to be used with the telnet authentication option [2]. This mecha- - nism can also used to provide keying material to provide data confi- - dentiality services in conjuction with the telnet encryption option - [3]. - -1. Command Names and Codes - - Authentication Types - - KERBEROS_V5 2 - - Sub-option Commands - - Expires Sept 2000 [Page 1] - -Internet-Draft Kerberos Version 5 for Telnet April 2000 - - AUTH 0 - REJECT 1 - ACCEPT 2 - RESPONSE 3 - FORWARD 4 - FORWARD_ACCEPT 5 - FORWARD_REJECT 6 - -2. Command Meanings - - IAC SB AUTHENTICATION IS AUTH IAC SE - - This is used to pass the Kerberos V5 [1] KRB_AP_REQ message to the - remote side of the connection. The first octet of the value is KERBEROS_V5, to indicate that Version 5 - of Kerberos is being used. The Kerberos V5 authenticator in the - KRB_AP_REQ message must contain a Kerberos V5 checksum of the - two-byte authentication type pair. This checksum must be verified - by the server to assure that the authentication type pair was cor- - rectly negotiated. The Kerberos V5 authenticator must also in- - clude the optional subkey field, which shall be filled in with a - randomly chosen key. This key shall be used for encryption pur- - poses if encryption is negotiated, and shall be used as the nego- - tiated session key (i.e., used as keyid 0) for the purposes of the - telnet encryption option; if the subkey is not filled in, then the - ticket session key will be used instead. - - If data confidentiality services is desired the ENCRYPT_US- - ING_TELOPT flag must be set in the authentication-type-pair as - specified in [2]. - - IAC SB AUTHENTICATION REPLY ACCEPT IAC SE - - This command indicates that the authentication was successful. - - If the AUTH_HOW_MUTUAL bit is set in the second octet of the au- - thentication-type-pair, the RESPONSE command must be sent before - the ACCEPT command is sent. - - IAC SB AUTHENTICATION REPLY REJECT IAC SE - - This command indicates that the authentication was not successful, - and if there is any more data in the sub-option, it is an ASCII - text message of the reason for the rejection. - - IAC SB AUTHENTICATION REPLY RESPONSE - IAC SE - - Expires Sept 2000 [Page 2] - -Internet-Draft Kerberos Version 5 for Telnet April 2000 - - This command is used to perform mutual authentication. It is only - used when the AUTH_HOW_MUTUAL bit is set in the second octet of - the authentication-type-pair. After an AUTH command is verified, - a RESPONSE command is sent which contains a Kerberos V5 KRB_AP_REP - message to perform the mutual authentication. - - IAC SB AUTHENTICATION FORWARD IAC SE - - This command is used to forward kerberos credentials for use by - the remote session. The credentials are passed as a Kerberos V5 - KRB_CRED message which includes, among other things, the forwarded - Kerberos ticket and a session key associated with the ticket. Part - of the KRB_CRED message is encrypted in the key previously ex- - changed for the telnet session by the AUTH suboption. - - IAC SB AUTHENTICATION FORWARD_ACCEPT IAC - SE - - This command indicates that the credential forwarding was success- - ful. - - IAC SB AUTHENTICATION FORWARD_REJECT IAC SE - - This command indicates that the credential forwarding was not suc- - cessful, and if there is any more data in the sub-option, it is an - ASCII text message of the reason for the rejection. - -3. Implementation Rules - - If the second octet of the authentication-type-pair has the AUTH_WHO - bit set to AUTH_CLIENT_TO_SERVER, then the client sends the initial - AUTH command, and the server responds with either ACCEPT or REJECT. - In addition, if the AUTH_HOW bit is set to AUTH_HOW_MUTUAL, the serv- - er will send a RESPONSE before it sends the ACCEPT. - - If the second octet of the authentication-type-pair has the AUTH_WHO - bit set to AUTH_SERVER_TO_CLIENT, then the server sends the initial - AUTH command, and the client responds with either ACCEPT or REJECT. - In addition, if the AUTH_HOW bit is set to AUTH_HOW_MUTUAL, the - client will send a RESPONSE before it sends the ACCEPT. - - The Kerberos principal used by the server will generally be of the - form "host/@realm". That is, the first component of the - Kerberos principal is "host"; the second component is the fully qual- - ified lower-case hostname of the server; and the realm is the Ker- - beros realm to which the server belongs. - - Expires Sept 2000 [Page 3] - -Internet-Draft Kerberos Version 5 for Telnet April 2000 - - Any Telnet IAC characters that occur in the KRB_AP_REQ or KRB_AP_REP - messages, the KRB_CRED structure, or the optional rejection text - string must be doubled as specified in [4]. Otherwise the following - byte might be mis-interpreted as a Telnet command. - -4. Examples - - User "joe" may wish to log in as user "pete" on machine "foo". If - "pete" has set things up on "foo" to allow "joe" access to his ac- - count, then the client would send IAC SB AUTHENTICATION NAME "pete" - IAC SE IAC SB AUTHENTICATION IS KERBEROS_V5 AUTH - IAC SE - - The server would then authenticate the user as "joe" from the - KRB_AP_REQ_MESSAGE, and if the KRB_AP_REQ_MESSAGE was accepted by - Kerberos, and if "pete" has allowed "joe" to use his account, the - server would then continue the authentication sequence by sending a - RESPONSE (to do mutual authentication, if it was requested) followed - by the ACCEPT. - - If forwarding has been requested, the client then sends IAC SB AU- - THENTICATION IS KERBEROS_V5 CLIENT|MUTUAL FORWARD IAC SE. If the server succeeds in - reading the forwarded credentials, the server sends FORWARD_ACCEPT - else, a FORWARD_REJECT is sent back. - - Client Server - IAC DO AUTHENTICATION - IAC WILL AUTHENTICATION - - [ The server is now free to request authentication information. - ] - - IAC SB AUTHENTICATION SEND - KERBEROS_V5 CLIENT|MUTUAL - KERBEROS_V5 CLIENT|ONE_WAY IAC - SE - - [ The server has requested mutual Version 5 Kerberos - authentication. If mutual authentication is not supported, - then the server is willing to do one-way authentication. - - The client will now respond with the name of the user that it - wants to log in as, and the Kerberos ticket. ] - - IAC SB AUTHENTICATION NAME - "pete" IAC SE - IAC SB AUTHENTICATION IS - KERBEROS_V5 CLIENT|MUTUAL AUTH - IAC SE - - Expires Sept 2000 [Page 4] - -Internet-Draft Kerberos Version 5 for Telnet April 2000 - - [ Since mutual authentication is desired, the server sends across - a RESPONSE to prove that it really is the right server. ] - - IAC SB AUTHENTICATION REPLY - KERBEROS_V5 CLIENT|MUTUAL - RESPONSE - IAC SE - - [ The server responds with an ACCEPT command to state that the - authentication was successful. ] - - IAC SB AUTHENTICATION REPLY KER- - BEROS_V5 CLIENT|MUTUAL ACCEPT - IAC SE - - [ If so requested, the client now sends the FORWARD command to - forward credentials to the remote site. ] - - IAC SB AUTHENTICATION IS KER- - BEROS_V5 CLIENT|MUTUAL - FORWARD IAC - SE - - [ The server responds with a FORWARD_ACCEPT command to state that - the credential forwarding was successful. ] - - Expires Sept 2000 [Page 5] - -Internet-Draft Kerberos Version 5 for Telnet April 2000 - - IAC SB AUTHENTICATION REPLY KER- - BEROS_V5 CLIENT|MUTUAL FOR- - WARD_ACCEPT IAC SE - -5. Security Considerations - - The selection of the random session key in the Kerberos V5 authenti- - cator is critical, since this key will be used for encrypting the - telnet data stream if encryption is enabled. It is strongly advised - that the random key selection be done using cryptographic techniques - that involve the Kerberos ticket's session key. For example, using - the current time, encrypting it with the ticket session key, and then - correcting for key parity is a strong way to generate a subsession - key, since the ticket session key is assumed to be never disclosed to - an attacker. - - Care should be taken before forwarding a user's Kerberos credentials - to the remote server. If the remote server is not trustworthy, this - could result in the user's credentials being compromised. Hence, the - user interface should not forward credentials by default; it would be - far safer to either require the user to explicitly request creden- - tials forwarding for each connection, or to have a trusted list of - hosts for which credentials forwarding is enabled, but to not enable - credentials forwarding by default for all machines. - -6. IANA Considerations - - The authentication type KERBEROS_V5 and its associated suboption values - are registered with IANA. Any suboption values used to extend - the protocol as described in this document must be registered - with IANA before use. IANA is instructed not to issue new suboption - values without submission of documentation of their use. - -7. Acknowledgments - - This document was originally written by Dave Borman of Cray Research, - Inc. Theodore Ts'o of MIT revised it to reflect the latest implemen- - tation experience. Cliff Neuman and Prasad Upasani of USC's Informa- - tion Sciences Institute developed the credential forwarding support. - - In addition, the contributions of the Telnet Working Group are also - gratefully acknowledged. - -8. References - - [1] Kohl, J. and B. Neuman, "The Kerberos Network Authentication Sys- - tem (V5)", RFC 1510, USC/Information Sciences Institute, Septem- - ber 1993. - - [2] Internet Engineering Task Force, "Telnet Authentication", draft- - tso-telnet-auth-enc-04.txt, T. Ts'o, Editor, VA Linux Systems, - April 2000. - - [3] Internet Engineering Task Force, "Telnet Data Encryption Option", - draft-tso-telnet-encryption-04.txt, T. Ts'o, Editor, VA Linux - Systems, April 2000. - - [4] Postel, J.B. and J. Reynolds, "Telnet Option Specifications", RFC - - Expires Sept 2000 [Page 6] - -Internet-Draft Kerberos Version 5 for Telnet April 2000 - - 855, STD 8, USC/Information Sciences Institute, May 1983. - -Editor's Address - - Theodore Ts'o - Massachusetts Institute of Technology - MIT Room E40-343 - 77 Massachusetts Avenue - Cambridge, MA 02139 - - Phone: (617) 253-8091 - EMail: tytso@mit.edu - - Expires Sept 2000 [Page 7] - - - Jeffrey Altman * Sr.Software Designer * Kermit-95 for Win32 and OS/2 - The Kermit Project * Columbia University - 612 West 115th St #716 * New York, NY * 10025 - http://www.kermit-project.org/k95.html * kermit-support@kermit-project.org - - diff --git a/crypto/heimdal/doc/standardisation/rc4-hmac.txt b/crypto/heimdal/doc/standardisation/rc4-hmac.txt deleted file mode 100644 index 202d44e8639c..000000000000 --- a/crypto/heimdal/doc/standardisation/rc4-hmac.txt +++ /dev/null @@ -1,587 +0,0 @@ -CAT working group M. Swift -Internet Draft J. Brezak -Document: draft-brezak-win2k-krb-rc4-hmac-03.txt Microsoft -Category: Informational June 2000 - - - 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 desire 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 June 2000 - - - 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 (NT Password Hash) 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). - - For an account with a password of "foo", this String2Key("foo") will - return: - - 0xac, 0x8e, 0x65, 0x7f, 0x83, 0xdf, 0x82, 0xbe, - 0xea, 0x5d, 0x43, 0xbd, 0xaf, 0x78, 0x00, 0xcc - -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(Data) returning the checksum of the data. - - RC4 is a stream cipher licensed by RSA Data Security [RSADSI]. A - compatible cipher is described 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. This - summarizes the different key derivation values used in the various - -Swift Category - Informational 2 - - Windows 2000 RC4-HMAC Kerberos E-Type June 2000 - - - operations. Note that these differ from the key derivations used in - other Kerberos encryption types. - - T = 1 for TS-ENC-TS in the AS-Request - T = 8 for the AS-Reply - T = 7 for the Authenticator in the TGS-Request - T = 8 for the TGS-Reply - T = 2 for the Server Ticket in the AP-Request - T = 11 for the Authenticator in the AP-Request - T = 12 for the Server returned AP-Reply - T = 15 in the generation of checksum for the MIC token - T = 0 in the generation of sequence number for the MIC token - T = 13 in the generation of checksum for the WRAP token - T = 0 in the generation of sequence number for the WRAP token - T = 0 in the generation of encrypted data for the WRAPPED token - - All strings in this document are ASCII unless otherwise specified. - 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. - - 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, "signaturekey") //includes zero octet at end - tmp = MD5(concat(T, data)) - CHKSUM = HMAC(Ksign, 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. - -Swift Category - Informational 3 - - Windows 2000 RC4-HMAC Kerberos E-Type June 2000 - - - - BYTE L40[14] = "fortybits"; - BYTE SK = "signaturekey"; - - ENCRYPT (K, fRC4_EXP, T, data, data_len, edata, edata_len) - { - if (fRC4_EXP){ - *((DWORD *)(L40+10)) = T; - HMAC (K, L40, 10 + 4, K1); - }else{ - HMAC (K, &T, 4, K1); - } - memcpy (K2, K1, 16); - if (fRC4_EXP) memset (K1+7, 0xAB, 9); - add_8_random_bytes(data, data_len, conf_plus_data); - HMAC (K2, conf_plus_data, 8 + data_len, checksum); - HMAC (K1, checksum, 16, K3); - RC4(K3, conf_plus_data, 8 + data_len, edata + 16); - memcpy (edata, checksum, 16); - edata_len = 16 + 8 + data_len; - } - - DECRYPT (K, fRC4_EXP, T, edata, edata_len, data, data_len) - { - if (fRC4_EXP){ - *((DWORD *)(L40+10)) = T; - HMAC (K, L40, 14, K1); - }else{ - HMAC (K, &T, 4, K1); - } - memcpy (K2, K1, 16); - if (fRC4_EXP) memset (K1+7, 0xAB, 9); - HMAC (K1, edata, 16, K3); // checksum is at edata - RC4(K3, edata + 16, edata_len - 16, edata + 16); - data_len = edata_len - 16 - 8; - memcpy (data, edata + 16 + 8, data_len); - - // verify generated and received checksums - HMAC (K2, edata + 16, edata_len - 16, checksum); - if (memcmp(edata, checksum, 16) != 0) - printf("CHECKSUM ERROR !!!!!!\n"); - } - - 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; - - The KDC message is encrypted using the ENCRYPT function not - including the Checksum in the RC4_MDx_HEADER. - - -Swift Category - Informational 4 - - Windows 2000 RC4-HMAC Kerberos E-Type June 2000 - - - 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. In this description, the key size is actually 56-bits. - -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. - - The Windows 2000 implementation also defines new GSSAPI flags in the - initial token passed when initializing a security context. These - flags are passed in the checksum field of the authenticator (See [5] - Section 1.1.1). - - GSS_C_DCE_STYLE - This flag was added for use with Microsoft’s - implementation of DCE RPC, which initially expected three legs of - authentication. Setting this flag causes an extra AP reply to be - sent from the client back to the server after receiving the server’s - AP reply. In addition, the context negotiation tokens do not have - GSSAPI framing - they are raw AP message and do not include object - identifiers. - #define GSS_C_DCE_STYLE 0x1000 - - - -Swift Category - Informational 5 - - Windows 2000 RC4-HMAC Kerberos E-Type June 2000 - - - GSS_C_IDENTIFY_FLAG - This flag allows the client to indicate to the - server that it should only allow the server application to identify - the client by name and ID, but not to impersonate the client. - #define GSS_C_IDENTIFY_FLAG 0x2000 - - GSS_C_EXTENDED_ERROR_FLAG - Setting this flag indicates that the - client wants to be informed of extended error information. In - particular, Windows 2000 status codes may be returned in the data - field of a Kerberos error message. This allows the client to - understand a server failure more precisely. In addition, the server - may return errors to the client that are normally handled at the - application layer in the server, in order to let the client try to - recover. After receiving an error message, the client may attempt to - resubmit an AP request. - #define GSS_C_EXTENDED_ERROR_FLAG 0x4000 - - These flags are only used if a client is aware of these conventions - when using the SSPI on the Windows platform, they are not generally - used by default. - - When NetBIOS addresses are used in the GSSAPI, they are identified - by the GSS_C_AF_NETBIOS value. This value is defined as: - #define GSS_C_AF_NETBIOS 0x14 - NetBios addresses are 16-octet addresses typically composed of 1 to th 15 characters, trailing blank (ascii char 20) filled, with a 16 - octet of 0x0. - -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). - - MIC (K, fRC4_EXP, seq_num, MIC_hdr, msg, msg_len, - MIC_seq, MIC_checksum) - { - HMAC (K, SK, 13, K4); - T = 15; - memcpy (T_plus_hdr_plus_msg + 00, &T, 4); - memcpy (T_plus_hdr_plus_msg + 04, MIC_hdr, 8); - // 0101 1100 FFFFFFFF - memcpy (T_plus_hdr_plus_msg + 12, msg, msg_len); - MD5 (T_hdr_msg, 4 + 8 + msg_len, MD5_of_T_hdr_msg); - HMAC (K4, MD5_of_T_hdr_msg, CHKSUM); - memcpy (MIC_checksum, CHKSUM, 8); // use only first 8 bytes - - T = 0; - if (fRC4_EXP){ - *((DWORD *)(L40+10)) = T; - HMAC (K, L40, 14, K5); - }else{ - HMAC (K, &T, 4, K5); - -Swift Category - Informational 6 - - Windows 2000 RC4-HMAC Kerberos E-Type June 2000 - - - } - if (fRC4_EXP) memset(K5+7, 0xAB, 9); - HMAC(K5, MIT_checksum, 8, K6); - copy_seq_num_in_big_endian(seq_num, seq_plus_direction); - //0x12345678 - copy_direction_flag (direction_flag, seq_plus_direction + - 4); //0x12345678FFFFFFFF - RC4(K6, seq_plus_direction, 8, MIC_seq); - } - -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. - - 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 wrap based messages is as - follow: - - - WRAP (K, fRC4_EXP, seq_num, WRAP_hdr, msg, msg_len, - WRAP_seq, WRAP_checksum, edata, edata_len) - { - HMAC (K, SK, 13, K7); - T = 13; - PAD = 1; - memcpy (T_hdr_conf_msg_pad + 00, &T, 4); - memcpy (T_hdr_conf_msg_pad + 04, WRAP_hdr, 8); // 0101 1100 - FFFFFFFF - memcpy (T_hdr_conf_msg_pad + 12, msg, msg_len); - memcpy (T_hdr_conf_msg_pad + 12 + msg_len, &PAD, 1); - MD5 (T_hdr_conf_msg_pad, - 4 + 8 + 8 + msg_len + 1, - MD5_of_T_hdr_conf_msg_pad); - HMAC (K7, MD5_of_T_hdr_conf_msg_pad, CHKSUM); - memcpy (WRAP_checksum, CHKSUM, 8); // use only first 8 - bytes - - T = 0; - if (fRC4_EXP){ - *((DWORD *)(L40+10)) = T; - HMAC (K, L40, 14, K8); - }else{ - HMAC (K, &T, 4, K8); - } - if (fRC4_EXP) memset(K8+7, 0xAB, 9); - HMAC(K8, WRAP_checksum, 8, K9); - copy_seq_num_in_big_endian(seq_num, seq_plus_direction); - //0x12345678 - -Swift Category - Informational 7 - - Windows 2000 RC4-HMAC Kerberos E-Type June 2000 - - - copy_direction_flag (direction_flag, seq_plus_direction + - 4); //0x12345678FFFFFFFF - RC4(K9, seq_plus_direction, 8, WRAP_seq); - - for (i = 0; i < 16; i++) K10 [i] ^= 0xF0; // XOR each byte - of key with 0xF0 - T = 0; - if (fRC4_EXP){ - *(DWORD *)(L40+10) = T; - HMAC(K10, L40, 14, K11); - memset(K11+7, 0xAB, 9); - }else{ - HMAC(K10, &T, 4, K11); - } - HMAC(K11, seq_num, 4, K12); - RC4(K12, T_hdr_conf_msg_pad + 4 + 8, 8 + msg_len + 1, - edata); /* skip T & hdr */ - edata_len = 8 + msg_len + 1; // conf + msg_len + pad - } - - - 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. In this description, the key size is actually 56-bits. - -9. 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. - -10. Acknowledgements - - We would like to thank Salil Dangi for the valuable input in - refining the descriptions of the functions and review input. - -11. 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 - - - -Swift Category - Informational 8 - - Windows 2000 RC4-HMAC Kerberos E-Type June 2000 - - - - 5 Linn, J., "The Kerberos Version 5 GSS-API Mechanism", RFC-1964, - June 1996 - - 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 Thayer, R. and K. Kaukonen, "A Stream Cipher Encryption - Algorithm", Work in Progress. - - 9 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 - - 10 Neuman, C., Kohl, J., Ts'o, T., "The Kerberos Network - Authentication Service (V5)", draft-ietf-cat-kerberos-revisions- - 04.txt, June 25, 1999 - - -12. Author's Addresses - - Mike Swift - Dept. of Computer Science - Sieg Hall - University of Washington - Seattle, WA 98105 - Email: mikesw@cs.washington.edu - - John Brezak - Microsoft - One Microsoft Way - Redmond, Washington - Email: jbrezak@microsoft.com - - - - - - - - - - - - - - - -Swift Category - Informational 9 - - Windows 2000 RC4-HMAC Kerberos E-Type October 1999 - - - -13. Full Copyright Statement - - "Copyright (C) The Internet Society (2000). 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. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Swift Category - Informational 10 - diff --git a/crypto/heimdal/doc/standardisation/rfc1508.txt b/crypto/heimdal/doc/standardisation/rfc1508.txt deleted file mode 100644 index 132b855e05e6..000000000000 --- a/crypto/heimdal/doc/standardisation/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/crypto/heimdal/doc/standardisation/rfc1509.txt b/crypto/heimdal/doc/standardisation/rfc1509.txt deleted file mode 100644 index f36cd80e6dcd..000000000000 --- a/crypto/heimdal/doc/standardisation/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/crypto/heimdal/doc/standardisation/rfc1510.txt b/crypto/heimdal/doc/standardisation/rfc1510.txt deleted file mode 100644 index bc810cc506fa..000000000000 --- a/crypto/heimdal/doc/standardisation/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/crypto/heimdal/doc/standardisation/rfc1750.txt b/crypto/heimdal/doc/standardisation/rfc1750.txt deleted file mode 100644 index 56d478c7eef4..000000000000 --- a/crypto/heimdal/doc/standardisation/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/crypto/heimdal/doc/standardisation/rfc1831.txt b/crypto/heimdal/doc/standardisation/rfc1831.txt deleted file mode 100644 index 0556c9e83f3b..000000000000 --- a/crypto/heimdal/doc/standardisation/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/crypto/heimdal/doc/standardisation/rfc1964.txt b/crypto/heimdal/doc/standardisation/rfc1964.txt deleted file mode 100644 index f2960b961dd6..000000000000 --- a/crypto/heimdal/doc/standardisation/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/crypto/heimdal/doc/standardisation/rfc2078.txt b/crypto/heimdal/doc/standardisation/rfc2078.txt deleted file mode 100644 index 1dd1e4aebd2d..000000000000 --- a/crypto/heimdal/doc/standardisation/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/crypto/heimdal/doc/standardisation/rfc2203.txt b/crypto/heimdal/doc/standardisation/rfc2203.txt deleted file mode 100644 index 2f6a8a0d0f37..000000000000 --- a/crypto/heimdal/doc/standardisation/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/crypto/heimdal/doc/standardisation/rfc2228.txt b/crypto/heimdal/doc/standardisation/rfc2228.txt deleted file mode 100644 index 1fbfcbfa09fc..000000000000 --- a/crypto/heimdal/doc/standardisation/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] - diff --git a/crypto/heimdal/doc/standardisation/rfc2743.txt b/crypto/heimdal/doc/standardisation/rfc2743.txt deleted file mode 100644 index e5da571abb4a..000000000000 --- a/crypto/heimdal/doc/standardisation/rfc2743.txt +++ /dev/null @@ -1,5659 +0,0 @@ - - - - - - -Network Working Group J. Linn -Request for Comments: 2743 RSA Laboratories -Obsoletes: 2078 January 2000 -Category: Standards Track - - - Generic Security Service Application Program Interface - Version 2, Update 1 - - -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 (2000). All Rights Reserved. - -Abstract - - The Generic Security Service Application Program Interface (GSS-API), - Version 2, as defined in [RFC-2078], 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 obsoletes [RFC-2078], 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. - - - - - -Linn Standards Track [Page 1] - -RFC 2743 GSS-API January 2000 - - -TABLE OF CONTENTS - - 1: GSS-API Characteristics and Concepts . . . . . . . . . . . . 4 - 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 - 1.1.2: Tokens . . . . . . . . . . . . . . . . . . . . . . . . . 9 - 1.1.3: Security Contexts . . . . . . . . . . . . . . . . . . . 11 - 1.1.4: Mechanism Types . . . . . . . . . . . . . . . . . . . . 12 - 1.1.5: Naming . . . . . . . . . . . . . . . . . . . . . . . . 13 - 1.1.6: Channel Bindings . . . . . . . . . . . . . . . . . . . 16 - 1.2: GSS-API Features and Issues . . . . . . . . . . . . . . . 17 - 1.2.1: Status Reporting and Optional Service Support . . . . 17 - 1.2.1.1: Status Reporting . . . . . . . . . . . . . . . . . . . 17 - 1.2.1.2: Optional Service Support . . . . . . . . . . . . . . . 19 - 1.2.2: Per-Message Security Service Availability . . . . . . . 20 - 1.2.3: Per-Message Replay Detection and Sequencing . . . . . . 21 - 1.2.4: Quality of Protection . . . . . . . . . . . . . . . . . 24 - 1.2.5: Anonymity Support . . . . . . . . . . . . . . . . . . . 25 - 1.2.6: Initialization . . . . . . . . . . . . . . . . . . . . . 25 - 1.2.7: Per-Message Protection During Context Establishment . . 26 - 1.2.8: Implementation Robustness . . . . . . . . . . . . . . . 27 - 1.2.9: Delegation . . . . . . . . . . . . . . . . . . . . . . . 28 - 1.2.10: Interprocess Context Transfer . . . . . . . . . . . . . 28 - 2: Interface Descriptions . . . . . . . . . . . . . . . . . . 29 - 2.1: Credential management calls . . . . . . . . . . . . . . . 31 - 2.1.1: GSS_Acquire_cred call . . . . . . . . . . . . . . . . . 31 - 2.1.2: GSS_Release_cred call . . . . . . . . . . . . . . . . . 34 - 2.1.3: GSS_Inquire_cred call . . . . . . . . . . . . . . . . . 35 - 2.1.4: GSS_Add_cred call . . . . . . . . . . . . . . . . . . . 37 - 2.1.5: GSS_Inquire_cred_by_mech call . . . . . . . . . . . . . 40 - 2.2: Context-level calls . . . . . . . . . . . . . . . . . . . 41 - 2.2.1: GSS_Init_sec_context call . . . . . . . . . . . . . . . 42 - 2.2.2: GSS_Accept_sec_context call . . . . . . . . . . . . . . 49 - 2.2.3: GSS_Delete_sec_context call . . . . . . . . . . . . . . 53 - 2.2.4: GSS_Process_context_token call . . . . . . . . . . . . 54 - 2.2.5: GSS_Context_time call . . . . . . . . . . . . . . . . . 55 - 2.2.6: GSS_Inquire_context call . . . . . . . . . . . . . . . 56 - 2.2.7: GSS_Wrap_size_limit call . . . . . . . . . . . . . . . 57 - 2.2.8: GSS_Export_sec_context call . . . . . . . . . . . . . . 59 - 2.2.9: GSS_Import_sec_context call . . . . . . . . . . . . . . 61 - 2.3: Per-message calls . . . . . . . . . . . . . . . . . . . . 62 - 2.3.1: GSS_GetMIC call . . . . . . . . . . . . . . . . . . . . 63 - 2.3.2: GSS_VerifyMIC call . . . . . . . . . . . . . . . . . . 64 - 2.3.3: GSS_Wrap call . . . . . . . . . . . . . . . . . . . . . 65 - 2.3.4: GSS_Unwrap call . . . . . . . . . . . . . . . . . . . . 66 - - - -Linn Standards Track [Page 2] - -RFC 2743 GSS-API January 2000 - - - 2.4: Support calls . . . . . . . . . . . . . . . . . . . . . . 68 - 2.4.1: GSS_Display_status call . . . . . . . . . . . . . . . . 68 - 2.4.2: GSS_Indicate_mechs call . . . . . . . . . . . . . . . . 69 - 2.4.3: GSS_Compare_name call . . . . . . . . . . . . . . . . . 70 - 2.4.4: GSS_Display_name call . . . . . . . . . . . . . . . . . 71 - 2.4.5: GSS_Import_name call . . . . . . . . . . . . . . . . . 72 - 2.4.6: GSS_Release_name call . . . . . . . . . . . . . . . . . 73 - 2.4.7: GSS_Release_buffer call . . . . . . . . . . . . . . . . 74 - 2.4.8: GSS_Release_OID_set call . . . . . . . . . . . . . . . 74 - 2.4.9: GSS_Create_empty_OID_set call . . . . . . . . . . . . . 75 - 2.4.10: GSS_Add_OID_set_member call . . . . . . . . . . . . . . 76 - 2.4.11: GSS_Test_OID_set_member call . . . . . . . . . . . . . 76 - 2.4.12: GSS_Inquire_names_for_mech call . . . . . . . . . . . . 77 - 2.4.13: GSS_Inquire_mechs_for_name call . . . . . . . . . . . . 77 - 2.4.14: GSS_Canonicalize_name call . . . . . . . . . . . . . . 78 - 2.4.15: GSS_Export_name call . . . . . . . . . . . . . . . . . 79 - 2.4.16: GSS_Duplicate_name call . . . . . . . . . . . . . . . . 80 - 3: Data Structure Definitions for GSS-V2 Usage . . . . . . . . 81 - 3.1: Mechanism-Independent Token Format . . . . . . . . . . . . 81 - 3.2: Mechanism-Independent Exported Name Object Format . . . . 84 - 4: Name Type Definitions . . . . . . . . . . . . . . . . . . . 85 - 4.1: Host-Based Service Name Form . . . . . . . . . . . . . . . 85 - 4.2: User Name Form . . . . . . . . . . . . . . . . . . . . . . 86 - 4.3: Machine UID Form . . . . . . . . . . . . . . . . . . . . . 87 - 4.4: String UID Form . . . . . . . . . . . . . . . . . . . . . 87 - 4.5: Anonymous Nametype . . . . . . . . . . . . . . . . . . . . 87 - 4.6: GSS_C_NO_OID . . . . . . . . . . . . . . . . . . . . . . . 88 - 4.7: Exported Name Object . . . . . . . . . . . . . . . . . . . 88 - 4.8: GSS_C_NO_NAME . . . . . . . . . . . . . . . . . . . . . . 88 - 5: Mechanism-Specific Example Scenarios . . . . . . . . . . . 88 - 5.1: Kerberos V5, single-TGT . . . . . . . . . . . . . . . . . 89 - 5.2: Kerberos V5, double-TGT . . . . . . . . . . . . . . . . . 89 - 5.3: X.509 Authentication Framework . . . . . . . . . . . . . 90 - 6: Security Considerations . . . . . . . . . . . . . . . . . . 91 - 7: Related Activities . . . . . . . . . . . . . . . . . . . . 92 - 8: Referenced Documents . . . . . . . . . . . . . . . . . . . 93 - Appendix A: Mechanism Design Constraints . . . . . . . . . . . 94 - Appendix B: Compatibility with GSS-V1 . . . . . . . . . . . . . 94 - Appendix C: Changes Relative to RFC-2078 . . . . . . . . . . . 96 - Author's Address . . . . . . . . . . . . . . . . . . . . . . .100 - Full Copyright Statement . . . . . . . . . . . . . . . . . . .101 - - - - - - - - - - -Linn Standards Track [Page 3] - -RFC 2743 GSS-API January 2000 - - -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 - (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. (The definition for the peer entity authentication service, - and other definitions used in this document, corresponds to that - provided in [ISO-7498-2].) When establishing a 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 also 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 some 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 - - - -Linn Standards Track [Page 4] - -RFC 2743 GSS-API January 2000 - - - 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 - 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. - - - - -Linn Standards Track [Page 5] - -RFC 2743 GSS-API January 2000 - - - 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 have been implemented using secret-key technologies - (e.g., Kerberos, per [RFC-1964]) and with public-key approaches - (e.g., SPKM, per [RFC-2025]). - - 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 may be - interposed between applications which call that protocol and the - GSS-API (e.g., as defined in [RFC-2203] for Open Network Computing - Remote Procedure Call (RPC)), 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 - 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 - - - -Linn Standards Track [Page 6] - -RFC 2743 GSS-API January 2000 - - - 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 - 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. - - - - - - -Linn Standards Track [Page 7] - -RFC 2743 GSS-API January 2000 - - - 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 - -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. - In support of application portability, support for the default - resolution behavior described below for initiator credentials - (GSS_Init_sec_context() usage) is mandated; support for the default - resolution behavior described below for acceptor credentials - (GSS_Accept_sec_context() usage) is recommended. If default - credential resolution fails, GSS_S_NO_CRED status is to be returned. - - 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 - - - - - - - - -Linn Standards Track [Page 8] - -RFC 2743 GSS-API January 2000 - - - (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 - - (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 those - 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 - - - - -Linn Standards Track [Page 9] - -RFC 2743 GSS-API January 2000 - - - 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.1 of this - document provides, for designers of GSS-API 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. - - Context-level 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. Per-message tokens, in - contrast, are to be returned only upon successful completion of per- - message calls. Zero-length tokens are never returned by GSS routines - for transfer to a peer. 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. - - 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), - - - - - -Linn Standards Track [Page 10] - -RFC 2743 GSS-API January 2000 - - - - 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 mechanisms 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 - 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 - - - -Linn Standards Track [Page 11] - -RFC 2743 GSS-API January 2000 - - - 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. Messages may be protected and - transferred in both directions on an established GSS-API security - context concurrently; protection of messages in one direction does - not interfere with protection of messages in the reverse direction. - - GSS-API implementations are expected to retain inquirable context - data on a context until the context is released by a caller, even - after the context has expired, although underlying cryptographic data - elements may be deleted after expiration in order to limit their - exposure. - -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. - - For GSS-API purposes, the phrase "negotiating mechanism" refers to a - mechanism which itself performs negotiation in order to select a - concrete mechanism which is shared between peers and is then used for - context establishment. Only those mechanisms which are defined in - their specifications as negotiating mechanisms are to yield selected - mechanisms with different identifier values than the value which is - input by a GSS-API caller, except for the case of a caller requesting - the "default" mech_type. - - 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): - - - - -Linn Standards Track [Page 12] - -RFC 2743 GSS-API January 2000 - - - 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 - - use of a negotiating mechanism - - When transferred between GSS-API peers, mech_type specifiers (per - Section 3 of this document, represented as Object Identifiers (OIDs)) - serve to qualify the interpretation of associated tokens. (The - structure and encoding of Object Identifiers is defined in [ISOIEC- - 8824] and [ISOIEC-8825].) Use of hierarchically structured OIDs - serves to preclude ambiguous interpretation of mech_type specifiers. - The OID representing the DASS ([RFC-1507]) MechType, for example, is - 1.3.12.2.1011.7.5, and that of the Kerberos V5 mechanism ([RFC- - 1964]), having been advanced to the level of Proposed Standard, is - 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 - - - - -Linn Standards Track [Page 13] - -RFC 2743 GSS-API January 2000 - - - 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 - 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. - - - - - -Linn Standards Track [Page 14] - -RFC 2743 GSS-API January 2000 - - - 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, - GSS-API defines a special form of the contiguous string name which - may be compared directly (e.g., with memcmp()). Contiguous 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 symbolic constant GSS_C_NT_EXPORT_NAME - identifies the "export name" type. 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 - exported name is defined in Section 3.2 of this specification. - - 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 operations 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 following diagram illustrates the intended dataflow among name- - related GSS-API processing routines. - - - - - - - - - - - - - - - - - - - - - - - - -Linn Standards Track [Page 15] - -RFC 2743 GSS-API January 2000 - - - 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 - 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 - - - -Linn Standards Track [Page 16] - -RFC 2743 GSS-API January 2000 - - - 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 and Optional Service Support - -1.2.1.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. - - Sequencing-related informatory major_status codes - (GSS_S_DUPLICATE_TOKEN, GSS_S_OLD_TOKEN, GSS_S_UNSEQ_TOKEN, and - GSS_S_GAP_TOKEN) can be indicated in conjunction with either - GSS_S_COMPLETE or GSS_S_FAILURE status for GSS-API per-message calls. - For context establishment calls, these sequencing-related codes will - be indicated only in conjunction with GSS_S_FAILURE status (never in - - - - - -Linn Standards Track [Page 17] - -RFC 2743 GSS-API January 2000 - - - conjunction with GSS_S_COMPLETE or GSS_S_CONTINUE_NEEDED), and, - therefore, always correspond to fatal failures if encountered during - the context establishment phase. - - 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_BAD_MIC preferred alias for GSS_S_BAD_SIG - 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. - - - - - -Linn Standards Track [Page 18] - -RFC 2743 GSS-API January 2000 - - - 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 - with sequences of continuation calls to GSS_Init_sec_context() and - GSS_Accept_sec_context(). The same facility 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.1.2: Optional Service Support - - A context initiator may request various optional services at context - establishment time. 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_GetMIC() and GSS_Wrap() should include message - numbering information to enable GSS_VerifyMIC() and GSS_Unwrap() - to detect if a message has been duplicated. - - - Out-of-sequence detection - In addition to providing message - integrity services, GSS_GetMIC() and GSS_Wrap() should include - message sequencing information to enable GSS_VerifyMIC() and - GSS_Unwrap() to detect if a message has been received out of - sequence. - - - - - - -Linn Standards Track [Page 19] - -RFC 2743 GSS-API January 2000 - - - - Anonymous authentication - The establishment of the security - context should not reveal the initiator's identity to the context - acceptor. - - - Available per-message confidentiality - requests that per- - message confidentiality services be available on the context. - - - Available per-message integrity - requests that per-message - integrity services be available on the context. - - 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. - - 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 GSS-API can correctly indicate - whether the service is supported by the acceptor's 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 - - - - - -Linn Standards Track [Page 20] - -RFC 2743 GSS-API January 2000 - - - 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. - - 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 the selected mechanism, - 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 - - - -Linn Standards Track [Page 21] - -RFC 2743 GSS-API January 2000 - - - 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, without concurrent indication of - GSS_S_DUPLICATE_TOKEN or GSS_S_OLD_TOKEN, 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_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. In addition to identifying duplicated tokens originated - by a context's peer, this status may also be used to identify - reflected copies of locally-generated tokens; it is recommended - that mechanism designers include within their protocols facilities - to detect and report such tokens. - - 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, without concurrent indication of - GSS_S_DUPLICATE_TOKEN, GSS_S_OLD_TOKEN, GSS_S_UNSEQ_TOKEN, or - GSS_S_GAP_TOKEN, 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. In - addition to identifying duplicated tokens originated by a - context's peer, this status may also be used to identify reflected - - - -Linn Standards Track [Page 22] - -RFC 2743 GSS-API January 2000 - - - copies of locally-generated tokens; it is recommended that - mechanism designers include within their protocols facilities to - detect and report such tokens. - - 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.] - - 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 - - - -Linn Standards Track [Page 23] - -RFC 2743 GSS-API January 2000 - - - 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 - 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. - - In the interests of interoperability, mechanisms which allow optional - support of particular QOP values shall satisfy one of the following - conditions. Either: - - (i) All implementations of the mechanism are required to be - capable of processing messages protected using any QOP value, - regardless of whether they can apply protection corresponding to - that QOP, or - - (ii) The set of mutually-supported receiver QOP values must be - determined during context establishment, and messages may be - protected by either peer using only QOP values from this - mutually-supported set. - - NOTE: (i) is just a special-case of (ii), where implementations are - required to support all QOP values on receipt. - - - - - - -Linn Standards Track [Page 24] - -RFC 2743 GSS-API January 2000 - - -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. - - Section 4.5 of this document defines the Object Identifier value used - to identify an anonymous principal. - - 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. - - 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. - - - -Linn Standards Track [Page 25] - -RFC 2743 GSS-API January 2000 - - -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. - Callers making use of per-message protection services in advance of - GSS_S_COMPLETE status should be aware of the possibility that a - subsequent context establishment step may fail, and that certain - context data (e.g., mech_type) as returned for subsequent calls may - change. - - This approach 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 - 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 - - - -Linn Standards Track [Page 26] - -RFC 2743 GSS-API January 2000 - - - 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. - - Invocation of GSS-API calls is to incur no undocumented side effects - visible at the GSS-API level. - - If a token is presented for processing on a GSS-API security context - and that token generates a fatal error in processing or is otherwise - 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. - - A failure of GSS_GetMIC() or GSS_Wrap() due to an attempt to use an - unsupported QOP will not interfere with context validity, nor shall - such a failure impact the ability of the application to subsequently - invoke GSS_GetMIC() or GSS_Wrap() using a supported QOP. Any state - information concerning sequencing of outgoing messages shall be - unchanged by an unsuccessful call of GSS_GetMIC() or GSS_Wrap(). - - - - - - - - - - -Linn Standards Track [Page 27] - -RFC 2743 GSS-API January 2000 - - -1.2.9: 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 GSS-API 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 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 provided at the explicit request of the - application. - -1.2.10: Interprocess Context Transfer - - GSS-API 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 - - - - -Linn Standards Track [Page 28] - -RFC 2743 GSS-API January 2000 - - - 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 GSS-API 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 GSS- - API, 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 context handle 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. - 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() indicating a TRUE - trans_state return value. - -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. - - 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 - - - -Linn Standards Track [Page 29] - -RFC 2743 GSS-API January 2000 - - - 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 - - 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 general GSS-allocated - 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_Inquire_names_for_mech indicate name types supported by - - - -Linn Standards Track [Page 30] - -RFC 2743 GSS-API January 2000 - - - 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 - 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, -- NULL requests - -- system-selected default - - o cred_usage INTEGER -- 0=INITIATE-AND-ACCEPT, 1=INITIATE-ONLY, - -- 2=ACCEPT-ONLY - - - - - -Linn Standards Track [Page 31] - -RFC 2743 GSS-API January 2000 - - - Outputs: - - o major_status INTEGER, - - o minor_status INTEGER, - - o output_cred_handle CREDENTIAL HANDLE, -- if returned non-NULL, - -- caller must release with GSS_Release_cred() - - o actual_mechs SET OF OBJECT IDENTIFIER, -- if returned non-NULL, - -- caller must release with GSS_Release_oid_set() - - 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. - - 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_CREDENTIALS_EXPIRED indicates that underlying credential - elements corresponding to the requested desired_name have expired, so - requested credentials could not be established. - - o GSS_S_NO_CRED indicates that no credential elements corresponding - to the requested desired_name and usage could be accessed, so - requested credentials could not be established. In particular, this - status should be returned upon temporary user-fixable conditions - - - - - -Linn Standards Track [Page 32] - -RFC 2743 GSS-API January 2000 - - - preventing successful credential establishment and upon lack of - authorization to establish and use credentials associated with the - identity named in the input desired_name argument. - - o GSS_S_FAILURE indicates that credential establishment failed for - reasons unspecified at the GSS-API level. - - 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 (GSS_C_NO_NAME) for desired_name, - which will be 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. 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. - - 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 GSS_C_NO_NAME, or a name - resulting from applying GSS_Inquire_context() to an active context, - or a name resulting from applying GSS_Inquire_cred() against a - credential handle corresponding to default behavior. It is important - to recognize that the explicit name which is yielded by resolving a - default reference may change over time, e.g., as a result of local - credential element management operations outside GSS-API; once - resolved, however, the value of such an explicit name will remain - constant. - - 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 - - - -Linn Standards Track [Page 33] - -RFC 2743 GSS-API January 2000 - - - 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 CREDENTIAL HANDLE -- if GSS_C_NO_CREDENTIAL - -- is specified, the call will complete successfully, but - -- will have no effect; no credential elements will 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. - - - - - - - -Linn Standards Track [Page 34] - -RFC 2743 GSS-API January 2000 - - - 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. - - 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 -- if GSS_C_NO_CREDENTIAL - -- is specified, default initiator credentials are queried - - Outputs: - - o major_status INTEGER, - - o minor_status INTEGER, - - o cred_name INTERNAL NAME, -- caller must release with - -- GSS_Release_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 -- caller must release - -- with GSS_Release_oid_set() - - - - - - - - - -Linn Standards Track [Page 35] - -RFC 2743 GSS-API January 2000 - - - 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. - - 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". - - - -Linn Standards Track [Page 36] - -RFC 2743 GSS-API January 2000 - - - 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(). - -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; see text for definition of behavior - -- when GSS_C_NO_CREDENTIAL provided. - - o desired_name INTERNAL NAME - - 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. - -- if credential handle returned, caller must release with - -- GSS_Release_cred() - - o actual_mechs SET OF OBJECT IDENTIFIER, -- if returned, caller must - -- release with GSS_Release_oid_set() - - o initiator_time_rec INTEGER -- in seconds, or reserved value for - -- INDEFINITE - - o acceptor_time_rec INTEGER -- in seconds, or reserved value for - -- INDEFINITE - - - - -Linn Standards Track [Page 37] - -RFC 2743 GSS-API January 2000 - - - 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. - - 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. In particular, this status - should be returned upon temporary user-fixable conditions preventing - successful credential establishment or upon lack of authorization to - establish or use credentials representing the requested identity. - - o GSS_S_CREDENTIALS_EXPIRED indicates that referenced credential - elements have expired, so the GSS_Add_cred() operation could not be - performed. - - o GSS_S_FAILURE indicates that the operation failed for reasons - unspecified at the GSS-API level. - - - - - -Linn Standards Track [Page 38] - -RFC 2743 GSS-API January 2000 - - - 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. A credential - element is identified by the name of the principal to which it - refers. GSS-API 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 GSS-API handle to existing data. Such functions, if required, - should be defined in implementation-specific extension routines. - - If credential acquisition is time-consuming for a mechanism, the - mechanism may choose 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. - - If GSS_C_NO_CREDENTIAL is specified as input_cred_handle, a non-NULL - output_cred_handle must be supplied. For the case of - GSS_C_NO_CREDENTIAL as input_cred_handle, GSS_Add_cred() will create - the credential referenced by its output_cred_handle based on default - behavior. That is, the call will have the same effect as if the - caller had previously called GSS_Acquire_cred(), specifying the same - usage and passing GSS_C_NO_NAME as the desired_name parameter - (thereby obtaining an explicit credential handle corresponding to - default behavior), had passed that credential handle to - GSS_Add_cred(), and had finally called GSS_Release_cred() on the - credential handle received from GSS_Acquire_cred(). - - 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 GSS_C_NO_NAME, or a name - resulting from applying GSS_Inquire_context() to an active context, - or a name resulting from applying GSS_Inquire_cred() against a - credential handle corresponding to default behavior. It is important - to recognize that the explicit name which is yielded by resolving a - default reference may change over time, e.g., as a result of local - - - -Linn Standards Track [Page 39] - -RFC 2743 GSS-API January 2000 - - - credential element management operations outside GSS-API; once - resolved, however, the value of such an explicit name will remain - constant. - - A caller may provide the value NULL (GSS_C_NO_NAME) for desired_name, - which will be 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. - - 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. - -2.1.5: GSS_Inquire_cred_by_mech call - - Inputs: - - o cred_handle CREDENTIAL HANDLE -- if GSS_C_NO_CREDENTIAL - -- specified, default initiator credentials are 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; caller must - -- release with GSS_Release_name() - - 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 - - - -Linn Standards Track [Page 40] - -RFC 2743 GSS-API January 2000 - - - 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. - - 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. - - - -Linn Standards Track [Page 41] - -RFC 2743 GSS-API January 2000 - - - 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 - -- (GSS_C_NO_CONTEXT) specifies "none assigned yet" - - 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 conf_req_flag BOOLEAN, - - o integ_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, - - - - -Linn Standards Track [Page 42] - -RFC 2743 GSS-API January 2000 - - - o output_context_handle CONTEXT HANDLE, -- once returned non-NULL, - -- caller must release with GSS_Delete_sec_context() - - o mech_type OBJECT IDENTIFIER, -- actual mechanism always - -- indicated, never NULL; caller should treat as read-only - -- and should not attempt to release - - o output_token OCTET STRING, -- NULL or token to pass to context - -- target; caller must release with GSS_Release_buffer() - - 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 - - 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 - - - - - -Linn Standards Track [Page 43] - -RFC 2743 GSS-API January 2000 - - - to a continuation call to GSS_Init_sec_context(), before per-message - processing can be performed in conjunction with this context (unless - the prot_ready_state value is concurrently returned TRUE). - - 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 (GSS_S_BAD_MIC) 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, because the - caller lacks authorization to access the referenced credentials, or - because the resolution of default credentials failed. - - 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. - - 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. - - - - - - -Linn Standards Track [Page 44] - -RFC 2743 GSS-API January 2000 - - - 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 an - output_token suitable for use by the target within the selected - mech_type's protocol. For the case of a multi-step exchange, this - output_token will be one in a series, each generated by a successive - call. 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. - In addition to support for other name types, it is recommended (newly - as of GSS-V2, Update 1) that mechanisms be able to accept - GSS_C_NO_NAME as an input type for targ_name. While recommended, - such support is not required, and it is recognized that not all - mechanisms can construct tokens without explicitly naming the context - target, even when mutual authentication of the target is not - obtained. Callers wishing to make use of this facility and concerned - with portability should be aware that support for GSS_C_NO_NAME as - input targ_name type is unlikely to be provided within mechanism - definitions specified prior to GSS-V2, Update 1. - - 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 sequences modeled by the - GSS_S_CONTINUE_NEEDED facility will require access to credentials at - different points in the context establishment sequence. - - The caller-provided input_context_handle argument is to be 0 - (GSS_C_NO_CONTEXT), 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 - - - -Linn Standards Track [Page 45] - -RFC 2743 GSS-API January 2000 - - - 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. If GSS_Init_sec_context() - is passed the handle of a context which is already fully established, - GSS_S_FAILURE status is returned. - - 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. (Note: when the GSS-V2 prot_ready_state - indicator is returned TRUE, it can be possible to transfer a - protected message before context establishment is complete: see also - Section 1.2.7) - - 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 46] - -RFC 2743 GSS-API January 2000 - - - 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. - - The conf_req_flag and integ_req_flag provide informatory inputs to - the GSS-API implementation as to whether, respectively, per-message - confidentiality and per-message integrity services will be required - on the context. This information is important as an input to - negotiating mechanisms. It is important to recognize, however, that - the inclusion of these flags (which are newly defined for GSS-V2) - introduces a backward incompatibility with callers implemented to - GSS-V1, where the flags were not defined. Since no GSS-V1 callers - would set these flags, even if per-message services are desired, - GSS-V2 mechanism implementations which enable such services - selectively based on the flags' values may fail to provide them to - contexts established for GSS-V1 callers. It may be appropriate under - certain circumstances, therefore, for such mechanism implementations - to infer these service request flags to be set if a caller is known - to be implemented to GSS-V1. - - 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. - - - - -Linn Standards Track [Page 47] - -RFC 2743 GSS-API January 2000 - - - 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; it will never indicate the value for - "default". A valid mech_type result must be returned along with a - GSS_S_COMPLETE status return; GSS-API implementations may (but are - not required to) also return mech_type along with predecessor calls - indicating GSS_S_CONTINUE_NEEDED status or (if a mechanism is - determinable) in conjunction with fatal error cases. For the case of - 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, - and the returned value may change between successive calls returning - GSS_S_CONTINUE_NEEDED and the final call returning GSS_S_COMPLETE. - - 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 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. - - - - - -Linn Standards Track [Page 48] - -RFC 2743 GSS-API January 2000 - - -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 - -- (GSS_C_NO_CONTEXT) 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 - -- once returned, caller must release with GSS_Release_name() - - o mech_type OBJECT IDENTIFIER, -- caller should treat as - -- read-only; does not need to be released - - o output_context_handle CONTEXT HANDLE, -- once returned - -- non-NULL in context establishment sequence, caller - -- must release with GSS_Delete_sec_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, -- see Section 1.2.7 for discussion - - o conf_avail BOOLEAN, - - o integ_avail BOOLEAN, - - - - -Linn Standards Track [Page 49] - -RFC 2743 GSS-API January 2000 - - - o lifetime_rec INTEGER, -- in seconds, or reserved value for - -- INDEFINITE - - o delegated_cred_handle CREDENTIAL HANDLE, -- if returned non-NULL, - -- caller must release with GSS_Release_cred() - - o output_token OCTET STRING -- NULL or token to pass to context - -- initiator; if returned non-NULL, caller must release with - -- GSS_Release_buffer() - - 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. - - 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 (GSS_S_BAD_MIC) 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. - - - - - - - -Linn Standards Track [Page 50] - -RFC 2743 GSS-API January 2000 - - - 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, because the - caller lacks authorization to access the referenced credentials, or - because the procedure for default credential resolution failed. - - 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. - - 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. - - - - - -Linn Standards Track [Page 51] - -RFC 2743 GSS-API January 2000 - - - The caller-provided input_context_handle argument is to be 0 - (GSS_C_NO_CONTEXT), 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. - If GSS_Accept_sec_context() is passed the handle of a context which - is already fully established, GSS_S_FAILURE status is returned. - - 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. - - 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 returned mech_type value indicates the specific mechanism - employed on the context; it will never indicate the value for - "default". A valid mech_type result must be returned whenever - GSS_S_COMPLETE status is indicated; GSS-API implementations may (but - are not required to) also return mech_type along with predecessor - calls indicating GSS_S_CONTINUE_NEEDED status or (if a mechanism is - determinable) in conjunction with fatal error cases. For the case of - - - -Linn Standards Track [Page 52] - -RFC 2743 GSS-API January 2000 - - - 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, - and the returned value may change between successive calls returning - GSS_S_CONTINUE_NEEDED and the final call returning GSS_S_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_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, - - 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. - - - - -Linn Standards Track [Page 53] - -RFC 2743 GSS-API January 2000 - - - 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 can be made by either peer in a security context, to flush - context-specific information. Once a non-zero output_context_handle - has been returned by context establishment calls, 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. 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. - - 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. - -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, - - - -Linn Standards Track [Page 54] - -RFC 2743 GSS-API January 2000 - - - 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. - -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. - - - - - -Linn Standards Track [Page 55] - -RFC 2743 GSS-API January 2000 - - - o GSS_S_CONTEXT_EXPIRED indicates that data items related to the - referenced context 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, - - o src_name INTERNAL NAME, -- name of context initiator, - -- guaranteed to be MN; - -- caller must release with GSS_Release_name() if returned - - o targ_name INTERNAL NAME, -- name of context target, - -- guaranteed to be MN; - -- caller must release with GSS_Release_name() if returned - - o lifetime_rec INTEGER -- in seconds, or reserved value for - -- INDEFINITE or EXPIRED - - o mech_type OBJECT IDENTIFIER, -- the mechanism supporting this - -- security context; caller should treat as read-only and not - -- attempt to release - - o deleg_state BOOLEAN, - - o mutual_state BOOLEAN, - - o replay_det_state BOOLEAN, - - o sequence_state BOOLEAN, - - o anon_state BOOLEAN, - - - -Linn Standards Track [Page 56] - -RFC 2743 GSS-API January 2000 - - - 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 - - o open BOOLEAN, -- TRUE if context fully established, FALSE - -- if partly established (in CONTINUE_NEEDED state) - - Return major_status codes: - - o GSS_S_COMPLETE indicates that the referenced context is valid and - that deleg_state, mutual_state, replay_det_state, sequence_state, - anon_state, trans_state, prot_ready_state, conf_avail, integ_avail, - locally_initiated, and open return values describe the corresponding - characteristics of the context. If open is TRUE, lifetime_rec is - also returned: if open is TRUE and the context peer's name is known, - src_name and targ_name are valid in addition to the values listed - above. The mech_type value must be returned for contexts where open - is TRUE and may be returned for contexts where open is FALSE. - - 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. Note that GSS-API implementations are - expected to retain inquirable context data on a context until the - context is released by a caller, even after the context has expired, - although underlying cryptographic data elements may be deleted after - expiration in order to limit their exposure. - -2.2.7: GSS_Wrap_size_limit call - - Inputs: - - o context_handle CONTEXT HANDLE, - - o conf_req_flag BOOLEAN, - - - - -Linn Standards Track [Page 57] - -RFC 2743 GSS-API January 2000 - - - 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 with the - confidentiality request state as provided in conf_req_flag 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. - - 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. - - - - - - - - - -Linn Standards Track [Page 58] - -RFC 2743 GSS-API January 2000 - - -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 -- caller must release - -- with GSS_Release_buffer() - - 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. - - 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). - - - - -Linn Standards Track [Page 59] - -RFC 2743 GSS-API January 2000 - - - A successful GSS_Export_sec_context() operation deactivates the - security context for the calling process; for this case, the GSS-API - implementation shall deallocate all process-wide resources associated - with the security context and shall set the context_handle to - GSS_C_NO_CONTEXT. In the event of an error that makes it impossible - to complete export of the security context, the GSS-API - implementation must not return an interprocess token and should - strive to leave the security context referenced by the context_handle - untouched. If this is impossible, it is permissible for the - implementation to delete the security context, provided that it also - sets the context_handle parameter to GSS_C_NO_CONTEXT. - - 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 - 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. - - - - -Linn Standards Track [Page 60] - -RFC 2743 GSS-API January 2000 - - -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 -- if successfully returned, - -- caller must release with GSS_Delete_sec_context() - - 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_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. - - 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. In particular, the imported context is usable for all per- - message operations and may be deleted or exported by its importer. - The inability to receive delegated credentials through - - - -Linn Standards Track [Page 61] - -RFC 2743 GSS-API January 2000 - - - gss_import_sec_context() precludes establishment of new contexts - based on information delegated to the importer's end system within - the context which is being imported, unless those delegated - credentials are obtained through separate routines (e.g., XGSS-API - calls) outside the GSS-V2 definition. - - 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. - - Although zero-length tokens are never returned by GSS calls for - transfer to a context's peer, a zero-length object may be passed by a - caller into GSS_Wrap(), in which case the corresponding peer calling - GSS_Unwrap() on the transferred token will receive a zero-length - object as output from GSS_Unwrap(). Similarly, GSS_GetMIC() can be - called on an empty object, yielding a MIC which GSS_VerifyMIC() will - successfully verify against the active security context in - conjunction with a zero-length object. - - - - - -Linn Standards Track [Page 62] - -RFC 2743 GSS-API January 2000 - - -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 -- caller must release - -- with GSS_Release_buffer() - - 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_NO_CONTEXT indicates that no 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. - - 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 - (if GSS_S_COMPLETE status is indicated) return the result in - - - -Linn Standards Track [Page 63] - -RFC 2743 GSS-API January 2000 - - - 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. - - 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 (GSS_S_BAD_MIC) indicates that the received - per_msg_token contains an incorrect integrity check for the message. - - - -Linn Standards Track [Page 64] - -RFC 2743 GSS-API January 2000 - - - 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_NO_CONTEXT indicates that no 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. Returns an indication of the quality-of- - protection applied to the processed message in the qop_state result. - - 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. - - 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, - - - - -Linn Standards Track [Page 65] - -RFC 2743 GSS-API January 2000 - - - o conf_state BOOLEAN, - - o output_message OCTET STRING -- caller must release with - -- GSS_Release_buffer() - - 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_NO_CONTEXT indicates that no 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 - 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. - - When GSS_S_COMPLETE status is returned, 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. - - - - - -Linn Standards Track [Page 66] - -RFC 2743 GSS-API January 2000 - - - 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 -- caller must release with - -- GSS_Release_buffer() - - 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. - - o GSS_S_BAD_SIG (GSS_S_BAD_MIC) 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_NO_CONTEXT indicates that no 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. - - - - - - -Linn Standards Track [Page 67] - -RFC 2743 GSS-API January 2000 - - - 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() has deciphered the input_message. - Returns an indication of the quality-of-protection applied to the - processed message in the qop_state result. GSS_Unwrap() 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. - -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 -- required calls for - -- release by caller are specific to language bindings - - 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. - - - - -Linn Standards Track [Page 68] - -RFC 2743 GSS-API January 2000 - - - 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. Note: some - language bindings may employ an iterative approach in order to emit - successive status components; this approach is acceptable but not - required for conformance with the current specification. - - Although not contemplated in [RFC-2078], it has been observed that - some existing GSS-API implementations return GSS_S_CONTINUE_NEEDED - status when iterating through successive messages returned from - GSS_Display_status(). This behavior is deprecated; - GSS_S_CONTINUE_NEEDED should be returned only by - GSS_Init_sec_context() and GSS_Accept_sec_context(). For maximal - portability, however, it is recommended that defensive callers be - able to accept and ignore GSS_S_CONTINUE_NEEDED status if indicated - by GSS_Display_status() or any other call other than - GSS_Init_sec_context() or GSS_Accept_sec_context(). - -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 -- caller must release - -- with GSS_Release_oid_set() - - Return major_status codes: - - o GSS_S_COMPLETE indicates that a set of available mechanisms has - been returned in mech_set. - - - - -Linn Standards Track [Page 69] - -RFC 2743 GSS-API January 2000 - - - 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-API - calls which accept input mechanism type specifiers. - -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 the two input names' types are - different and incomparable, so that the comparison operation could - not be completed. - - 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 - - - - - -Linn Standards Track [Page 70] - -RFC 2743 GSS-API January 2000 - - - 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, -- caller must release - -- with GSS_Release_buffer() - - o name_type OBJECT IDENTIFIER -- caller should treat - -- as read-only; does not need to be released - - 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_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. - - 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. - - The GSS_C_NO_OID name type is to be returned only when the - corresponding internal name was created through import with - GSS_C_NO_OID. It is acceptable for mechanisms to normalize names - imported with GSS_C_NO_OID into other supported types and, therefore, - to display them with types other than GSS_C_NO_OID. - - - - - -Linn Standards Track [Page 71] - -RFC 2743 GSS-API January 2000 - - -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 -- caller must release with - -- GSS_Release_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_BAD_MECH indicates that the input presented for import was - an exported name object and that its enclosed mechanism type was not - recognized or was 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. - - 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. If the - input_name_type's value is GSS_C_NO_OID, a mechanism-specific default - printable syntax (which shall be specified in the corresponding GSS- - V2 mechanism specification) is assumed for the input_name_string; - - - -Linn Standards Track [Page 72] - -RFC 2743 GSS-API January 2000 - - - other input_name_type values as registered by GSS-API implementations - can be used to indicate specific non-default name syntaxes. Note: The - input_name_type argument serves to describe and qualify the - 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. - - - -Linn Standards Track [Page 73] - -RFC 2743 GSS-API January 2000 - - - o GSS_S_BAD_NAME indicates that the input name argument did not - contain a valid name. - - 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, implementation and invocation - of this call may be superfluous (and may be omitted) 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, - implementation and invocation of this call may be superfluous (and - may be omitted) within bindings where memory management is automatic. - -2.4.8: GSS_Release_OID_set call - - Inputs: - - o buffer SET OF OBJECT IDENTIFIER - - - - -Linn Standards Track [Page 74] - -RFC 2743 GSS-API January 2000 - - - 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 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, - implementation and invocation of this call may be superfluous (and - may be omitted) 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 -- caller must release - -- with GSS_Release_oid_set() - - 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 75] - -RFC 2743 GSS-API January 2000 - - -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 76] - -RFC 2743 GSS-API January 2000 - - - 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_Inquire_names_for_mech call - - Input: - - o input_mech_type OBJECT IDENTIFIER, -- mechanism type - - Outputs: - - o major_status INTEGER, - - o minor_status INTEGER, - - o name_type_set SET OF OBJECT IDENTIFIER -- caller must release - -- with GSS_Release_oid_set() - - 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.13: GSS_Inquire_mechs_for_name call - - Inputs: - - o input_name INTERNAL NAME, - - Outputs: - - o major_status INTEGER, - - o minor_status INTEGER, - - - - -Linn Standards Track [Page 77] - -RFC 2743 GSS-API January 2000 - - - o mech_types SET OF OBJECT IDENTIFIER -- caller must release - -- with GSS_Release_oid_set() - - 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 was ill-formed and - could not be processed. - - o GSS_S_BAD_NAMETYPE indicates that the input_name parameter - contained an invalid name type or a name type 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 returns the mechanism set with which the input_name may - be processed. - - 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 GSS-API layer, using the type information - contained within the presented name, and based on registration - information provided by individual mechanism implementations. This - means that the returned mech_types result may indicate that a - particular mechanism will understand a particular name when in fact - it would refuse to accept that name as input to - GSS_Canonicalize_name(), GSS_Init_sec_context(), GSS_Acquire_cred(), - or GSS_Add_cred(), due to some property of the particular name rather - than a property of the name type. Thus, this routine should be used - only as a pre-filter for a call to a subsequent mechanism-specific - routine. - -2.4.14: GSS_Canonicalize_name call - - Inputs: - - o input_name INTERNAL NAME, - - o mech_type OBJECT IDENTIFIER -- must be explicit mechanism, - -- not "default" specifier or identifier of negotiating mechanism - - Outputs: - - o major_status INTEGER, - - - -Linn Standards Track [Page 78] - -RFC 2743 GSS-API January 2000 - - - o minor_status INTEGER, - - o output_name INTERNAL NAME -- caller must release with - -- GSS_Release_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 for this operation; this may correspond either to a - mechanism wholly unsupported by the local GSS-API implementation or - to a negotiating mechanism with which the canonicalization operation - cannot be performed. - - 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. - - This routine reduces a GSS-API internal name input_name, which may in - general contain elements corresponding to multiple mechanisms, to a - mechanism-specific Mechanism Name (MN) output_name by applying the - translations corresponding to the mechanism identified by mech_type. - The contents of input_name are unaffected by the - GSS_Canonicalize_name() operation. References to output_name will - remain valid until output_name is released, independent of whether or - not input_name is subsequently released. - -2.4.15: GSS_Export_name call - - Inputs: - - o input_name INTERNAL NAME, -- required to be MN - - Outputs: - - o major_status INTEGER, - - o minor_status INTEGER, - - - -Linn Standards Track [Page 79] - -RFC 2743 GSS-API January 2000 - - - o output_name OCTET STRING -- caller must release - -- with GSS_Release_buffer() - - 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. - - 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.16: GSS_Duplicate_name call - - Inputs: - - o src_name INTERNAL NAME - - - - -Linn Standards Track [Page 80] - -RFC 2743 GSS-API January 2000 - - - Outputs: - - o major_status INTEGER, - - o minor_status INTEGER, - - o dest_name INTERNAL NAME -- caller must release - -- with GSS_Release_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_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. - -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. - - - -Linn Standards Track [Page 81] - -RFC 2743 GSS-API January 2000 - - - 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: - - 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.) - - - - - - -Linn Standards Track [Page 82] - -RFC 2743 GSS-API January 2000 - - - 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. - - 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 - - - -Linn Standards Track [Page 83] - -RFC 2743 GSS-API January 2000 - - - -- ASN.1 structure not required - sealedUserData ANY - - END - -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. The Object Identifier - value to indicate names of this type is defined in Section 4.7 of - this document. - - 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. - - The bytes within MECH_OID_LEN and NAME_LEN elements are represented - most significant byte first (equivalently, in IP network byte order). - - 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. - - A concrete example of the contents of an exported name object, - derived from the Kerberos Version 5 mechanism, is as follows: - - 04 01 00 0B 06 09 2A 86 48 86 F7 12 01 02 02 hx xx xx xl pp qq ... zz - - 04 01 mandatory token identifier - - 00 0B 2-byte length of the immediately following DER-encoded - ASN.1 value of type OID, most significant octet first - - - - - - - - -Linn Standards Track [Page 84] - -RFC 2743 GSS-API January 2000 - - - 06 09 2A 86 48 86 F7 12 01 02 02 DER-encoded ASN.1 value - of type OID; Kerberos V5 - mechanism OID indicates - Kerberos V5 exported name - - in Detail: 06 Identifier octet (6=OID) - 09 Length octet(s) - 2A 86 48 86 F7 12 01 02 02 Content octet(s) - - hx xx xx xl 4-byte length of the immediately following exported - name blob, most significant octet first - - pp qq ... zz exported name blob of specified length, - bits and bytes specified in the - (Kerberos 5) GSS-API v2 mechanism spec - -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 - - 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 recommended symbolic name for this type is - "GSS_C_NT_HOSTBASED_SERVICE". - - For reasons of compatibility with existing implementations, it is - recommended that this OID be used rather than the alternate value as - included in [RFC-2078]: - - {1(iso), 3(org), 6(dod), 1(internet), 5(security), 6(nametypes), - 2(gss-host-based-services)} - - While it is not recommended that this alternate value be emitted on - output by GSS implementations, it is recommended that it be accepted - on input as equivalent to the recommended value. - - - - - - - - -Linn Standards Track [Page 85] - -RFC 2743 GSS-API January 2000 - - - This name type is used to represent services associated with host - computers. Support for this name form is recommended to mechanism - designers in the interests of portability, but is not mandated by - this specification. 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" - may (as an example implementation strategy) be 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. - - Documents specifying means for GSS integration into a particular - protocol should state either: - - (a) that a specific IANA-registered name associated with that - protocol shall be used for the "service" element (this admits, if - needed, the possibility that a single name can be registered and - shared among a related set of protocols), or - - (b) that the generic name "host" shall be used for the "service" - element, or - - (c) that, for that protocol, fallback in specified order (a, then - b) or (b, then a) shall be applied. - - IANA registration of specific names per (a) should be handled in - accordance with the "Specification Required" assignment policy, - defined by BCP 26, RFC 2434 as follows: "Values and their meaning - must be documented in an RFC or other available reference, in - sufficient detail so that interoperability between independent - implementations is possible." - -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 - - - - -Linn Standards Track [Page 86] - -RFC 2743 GSS-API January 2000 - - - 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 syntax and interpretation may be 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 user ID, 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. - -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 user ID. - -4.5: Anonymous Nametype - - 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: - - - -Linn Standards Track [Page 87] - -RFC 2743 GSS-API January 2000 - - - {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. - -4.6: GSS_C_NO_OID - - The recommended symbolic name GSS_C_NO_OID corresponds to a null - input value instead of an actual object identifier. Where specified, - it indicates interpretation of an associated name based on a - mechanism-specific default printable syntax. - -4.7: Exported Name Object - - Name objects of the Mechanism-Independent Exported Name Object type, - as defined in Section 3.2 of this document, 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)} - - The recommended symbolic name corresponding to this definition is - GSS_C_NT_EXPORT_NAME. - -4.8: GSS_C_NO_NAME - - The recommended symbolic name GSS_C_NO_NAME indicates that no name is - being passed within a particular value of a parameter used for the - purpose of transferring names. Note: GSS_C_NO_NAME is not an actual - name type, and is not represented by an OID; its acceptability in - lieu of an actual name is confined to specific calls - (GSS_Acquire_cred(), GSS_Add_cred(), and GSS_Init_sec_context()) with - usages as identified within this specification. - -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. - - - - - -Linn Standards Track [Page 88] - -RFC 2743 GSS-API January 2000 - - -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. - - 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 - - - -Linn Standards Track [Page 89] - -RFC 2743 GSS-API January 2000 - - - 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, 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. - - - -Linn Standards Track [Page 90] - -RFC 2743 GSS-API January 2000 - - - 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 - 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 - - This document specifies a service interface for security facilities - and services; as such, security considerations are considered - throughout the specification. Nonetheless, it is appropriate to - summarize certain specific points relevant to GSS-API implementors - and calling applications. Usage of the GSS-API interface does not in - itself provide security services or assurance; instead, these - attributes are dependent on the underlying mechanism(s) which support - a GSS-API implementation. Callers must be attentive to the requests - made to GSS-API calls and to the status indicators returned by GSS- - API, as these specify the security service characteristics which - GSS-API will provide. When the interprocess context transfer - facility is used, appropriate local controls should be applied to - constrain access to interprocess tokens and to the sensitive data - which they contain. - - - - - - - - - -Linn Standards Track [Page 91] - -RFC 2743 GSS-API January 2000 - - -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. C Language - bindings for GSS-V2 are defined in [RFC-2744]. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Linn Standards Track [Page 92] - -RFC 2743 GSS-API January 2000 - - -8: Referenced Documents - - [ISO-7498-2] International Standard ISO 7498-2-1988(E), Security - Architecture. - - [ISOIEC-8824] ISO/IEC 8824, "Specification of Abstract Syntax - Notation One (ASN.1)". - - [ISOIEC-8825] ISO/IEC 8825, "Specification of Basic Encoding Rules - for Abstract Syntax Notation One (ASN.1)".) - - [RFC-1507]: Kaufman, C., "DASS: Distributed Authentication Security - Service", RFC 1507, September 1993. - - [RFC-1508]: Linn, J., "Generic Security Service Application Program - Interface", RFC 1508, September 1993. - - [RFC-1509]: Wray, J., "Generic Security Service API: C-bindings", - RFC 1509, September 1993. - - [RFC-1964]: Linn, J., "The Kerberos Version 5 GSS-API Mechanism", - RFC 1964, June 1996. - - [RFC-2025]: Adams, C., "The Simple Public-Key GSS-API Mechanism - (SPKM)", RFC 2025, October 1996. - - [RFC-2078]: Linn, J., "Generic Security Service Application Program - Interface, Version 2", RFC 2078, January 1997. - - [RFC-2203]: Eisler, M., Chiu, A. and L. Ling, "RPCSEC_GSS Protocol - Specification", RFC 2203, September 1997. - - [RFC-2744]: Wray, J., "Generic Security Service API Version 2 : - C-bindings", RFC 2744, January 2000. - - - - - - - - - - - - - - - - - -Linn Standards Track [Page 93] - -RFC 2743 GSS-API January 2000 - - -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. - - This GSS-V2 specification adds the following calls which are not - present in GSS-V1: - - - - -Linn Standards Track [Page 94] - -RFC 2743 GSS-API January 2000 - - - 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_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. - - New conf_req_flag and integ_req_flag inputs are defined for - GSS_Init_sec_context(), primarily to provide information to - negotiating mechanisms. This introduces a compatibility issue with - GSS-V1 callers, discussed in section 2.2.1 of this specification. - - - - - - - - - -Linn Standards Track [Page 95] - -RFC 2743 GSS-API January 2000 - - - 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 - 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. - -APPENDIX C - -CHANGES RELATIVE TO RFC-2078 - - This document incorporates a number of changes relative to RFC-2078, - made primarily in response to implementation experience, for purposes - of alignment with the GSS-V2 C language bindings document, and to add - informative clarification. This section summarizes technical changes - incorporated. - - - - -Linn Standards Track [Page 96] - -RFC 2743 GSS-API January 2000 - - - General: - - Clarified usage of object release routines, and incorporated - statement that some may be omitted within certain operating - environments. - - Removed GSS_Release_OID, GSS_OID_to_str(), and GSS_Str_to_OID() - routines. - - Clarified circumstances under which zero-length tokens may validly - exist as inputs and outputs to/from GSS-API calls. - - Added GSS_S_BAD_MIC status code as alias for GSS_S_BAD_SIG. - - For GSS_Display_status(), deferred to language bindings the choice - of whether to return multiple status values in parallel or via - iteration, and added commentary deprecating return of - GSS_S_CONTINUE_NEEDED. - - Adapted and incorporated clarifying material on optional service - support, delegation, and interprocess context transfer from C - bindings document. - - Added and updated references to related documents, and to current - status of cited Kerberos mechanism OID. - - Added general statement about GSS-API calls having no side effects - visible at the GSS-API level. - - Context-related (including per-message protection issues): - - Clarified GSS_Delete_sec_context() usage for partially-established - contexts. - - Added clarification on GSS_Export_sec_context() and - GSS_Import_sec_context() behavior and context usage following an - export-import sequence. - - Added informatory conf_req_flag, integ_req_flag inputs to - GSS_Init_sec_context(). (Note: this facility introduces a - backward incompatibility with GSS-V1 callers, discussed in Section - 2.2.1; this implication was recognized and accepted in working - group discussion.) - - Stated that GSS_S_FAILURE is to be returned if - GSS_Init_sec_context() or GSS_Accept_sec_context() is passed the - handle of a context which is already fully established. - - - - -Linn Standards Track [Page 97] - -RFC 2743 GSS-API January 2000 - - - Re GSS_Inquire_sec_context(), stated that src_name and targ_name - are not returned until GSS_S_COMPLETE status is reached; removed - use of GSS_S_CONTEXT_EXPIRED status code (replacing with EXPIRED - lifetime return value); stated requirement to retain inquirable - data until context released by caller; added result value - indicating whether or not context is fully open. - - Added discussion of interoperability conditions for mechanisms - permitting optional support of QOPs. Removed reference to - structured QOP elements in GSS_Verify_MIC(). - - Added discussion of use of GSS_S_DUPLICATE_TOKEN status to - indicate reflected per-message tokens. - - Clarified use of informational sequencing codes from per-message - protection calls in conjunction with GSS_S_COMPLETE and - GSS_S_FAILURE major_status returns, adjusting status code - descriptions accordingly. - - Added specific statements about impact of GSS_GetMIC() and - GSS_Wrap() failures on context state information, and generalized - existing statements about impact of processing failures on - received per-message tokens. - - For GSS_Init_sec_context() and GSS_Accept_sec_context(), permitted - returned mech_type to be valid before GSS_S_COMPLETE, recognizing - that the value may change on successive continuation calls in the - negotiated mechanism case. - - Deleted GSS_S_CONTEXT_EXPIRED status from - GSS_Import_sec_context(). - - Added conf_req_flag input to GSS_Wrap_size_limit(). - - Stated requirement for mechanisms' support of per-message - protection services to be usable concurrently in both directions - on a context. - - Credential-related: - - For GSS_Acquire_cred() and GSS_Add_cred(), aligned with C bindings - statement of likely non-support for INITIATE or BOTH credentials - if input name is neither empty nor a name resulting from applying - GSS_Inquire_cred() against the default credential. Further, - stated that an explicit name returned by GSS_Inquire_context() - should also be accepted. Added commentary about potentially - time-variant results of default resolution and attendant - implications. Aligned with C bindings re behavior when - - - -Linn Standards Track [Page 98] - -RFC 2743 GSS-API January 2000 - - - GSS_C_NO_NAME provided for desired_name. In GSS_Acquire_cred(), - stated that NULL, rather than empty OID set, should be used for - desired_mechs in order to request default mechanism set. - - Added GSS_S_CREDENTIALS_EXPIRED as returnable major_status for - GSS_Acquire_cred(), GSS_Add_cred(), also specifying GSS_S_NO_CRED - as appropriate return for temporary, user-fixable credential - unavailability. GSS_Acquire_cred() and GSS_Add_cred() are also to - return GSS_S_NO_CRED if an authorization failure is encountered - upon credential acquisition. - - Removed GSS_S_CREDENTIALS_EXPIRED status return from per-message - protection, GSS_Context_time(), and GSS_Inquire_context() calls. - - For GSS_Add_cred(), aligned with C bindings' description of - behavior when addition of elements to the default credential is - requested. - - Upgraded recommended default credential resolution algorithm to - status of requirement for initiator credentials. - - For GSS_Release_cred(), GSS_Inquire_cred(), and - GSS_Inquire_cred_by_mech(), clarified behavior for input - GSS_C_NO_CREDENTIAL. - - Name-related: - - Aligned GSS_Inquire_mechs_for_name() description with C bindings. - - Removed GSS_S_BAD_NAMETYPE status return from - GSS_Duplicate_name(), GSS_Display_name(); constrained its - applicability for GSS_Compare_name(). - - Aligned with C bindings statement re GSS_Import_name() behavior - with GSS_C_NO_OID input name type, and stated that GSS-V2 - mechanism specifications are to define processing procedures - applicable to their mechanisms. Also clarified GSS_C_NO_OID usage - with GSS_Display_name(). - - Downgraded reference to name canonicalization via DNS lookup to an - example. - - For GSS_Canonicalize_name(), stated that neither negotiated - mechanisms nor the default mechanism are supported input - mech_types for this operation, and specified GSS_S_BAD_MECH status - to be returned in this case. Clarified that the - GSS_Canonicalize_name() operation is non-destructive to its input - name. - - - -Linn Standards Track [Page 99] - -RFC 2743 GSS-API January 2000 - - - Clarified semantics of GSS_C_NT_USER_NAME name type. - - Added descriptions of additional name types. Also added - discussion of GSS_C_NO_NAME and its constrained usage with - specific GSS calls. - - Adapted and incorporated C bindings discussion about name - comparisons with exported name objects. - - Added recommendation to mechanism designers for support of host- - based service name type, deferring any requirement statement to - individual mechanism specifications. Added discussion of host- - based service's service name element and proposed approach for - IANA registration policy therefor. - - Clarified byte ordering within exported name object. Stated that - GSS_S_BAD_MECH is to be returned if, in the course of attempted - import of an exported name object, the name object's enclosed - mechanism type is unrecognized or unsupported. - - Stated that mechanisms may optionally accept GSS_C_NO_NAME as an - input target name to GSS_Init_sec_context(), with comment that - such support is unlikely within mechanisms predating GSS-V2, - Update 1. - -AUTHOR'S ADDRESS - - John Linn - RSA Laboratories - 20 Crosby Drive - Bedford, MA 01730 USA - - Phone: +1 781.687.7817 - EMail: jlinn@rsasecurity.com - - - - - - - - - - - - - - - - - -Linn Standards Track [Page 100] - -RFC 2743 GSS-API January 2000 - - -Full Copyright Statement - - Copyright (C) The Internet Society (2000). 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. - -Acknowledgement - - Funding for the RFC Editor function is currently provided by the - Internet Society. - - - - - - - - - - - - - - - - - - - -Linn Standards Track [Page 101] - diff --git a/crypto/heimdal/doc/standardisation/rfc2744.txt b/crypto/heimdal/doc/standardisation/rfc2744.txt deleted file mode 100644 index 7f0c61946f24..000000000000 --- a/crypto/heimdal/doc/standardisation/rfc2744.txt +++ /dev/null @@ -1,5659 +0,0 @@ - - - - - - -Network Working Group J. Wray -Request for Comments: 2744 Iris Associates -Obsoletes: 1509 January 2000 -Category: Standards Track - - - Generic Security Service API Version 2 : C-bindings - -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 (2000). All Rights Reserved. - -Abstract - - This document specifies C language bindings for Version 2, Update 1 - of the Generic Security Service Application Program Interface (GSS- - API), which is described at a language-independent conceptual level - in RFC-2743 [GSSAPI]. It obsoletes RFC-1509, making specific - incremental changes in response to implementation experience and - liaison requests. It is intended, therefore, that this memo 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, 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. - - - - - - - - - - - -Wray Standards Track [Page 1] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - -1. 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 GSS-API: - - 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 GSS-API 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 GSS-API calls will return a token data - structure, which is an opaque data type that may contain - cryptographically protected data. The caller of such a GSS-API - 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 GSS-API routine - which will decode the token and extract the information, updating - the security context state information accordingly. - - - - - - - - - -Wray Standards Track [Page 2] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - c) Per-message services are invoked to apply either: - - integrity and data origin authentication, or confidentiality, - integrity and data origin authentication to application data, - which are treated by GSS-API as arbitrary octet-strings. An - application transmitting a message that it wishes to protect will - call the appropriate GSS-API 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 - GSS-API 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. - -2. GSS-API Routines - - This section lists the routines that make up the GSS-API, and - offers a brief description of the purpose of each routine. - Detailed descriptions of each routine are listed in alphabetical - order in section 5. - - Table 2-1 GSS-API Credential-management Routines - - Routine Section Function - ------- ------- -------- - gss_acquire_cred 5.2 Assume a global identity; Obtain - a GSS-API credential handle for - pre-existing credentials. - gss_add_cred 5.3 Construct credentials - incrementally - gss_inquire_cred 5.21 Obtain information about a - credential - gss_inquire_cred_by_mech 5.22 Obtain per-mechanism information - about a credential. - gss_release_cred 5.27 Discard a credential handle. - - - - - - - - - -Wray Standards Track [Page 3] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - Table 2-2 GSS-API Context-Level Routines - - Routine Section Function - ------- ------- -------- - gss_init_sec_context 5.19 Initiate a security context with - a peer application - gss_accept_sec_context 5.1 Accept a security context - initiated by a - peer application - gss_delete_sec_context 5.9 Discard a security context - gss_process_context_token 5.25 Process a token on a security - context from a peer application - gss_context_time 5.7 Determine for how long a context - will remain valid - gss_inquire_context 5.20 Obtain information about a - security context - gss_wrap_size_limit 5.34 Determine token-size limit for - gss_wrap on a context - gss_export_sec_context 5.14 Transfer a security context to - another process - gss_import_sec_context 5.17 Import a transferred context - - - Table 2-3 GSS-API Per-message Routines - - Routine Section Function - ------- ------- -------- - gss_get_mic 5.15 Calculate a cryptographic message - integrity code (MIC) for a - message; integrity service - gss_verify_mic 5.32 Check a MIC against a message; - verify integrity of a received - message - gss_wrap 5.33 Attach a MIC to a message, and - optionally encrypt the message - content; - confidentiality service - gss_unwrap 5.31 Verify a message with attached - MIC, and decrypt message content - if necessary. - - - - - - - - - - - -Wray Standards Track [Page 4] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - Table 2-4 GSS-API Name manipulation Routines - - Routine Section Function - ------- ------- -------- - gss_import_name 5.16 Convert a contiguous string name - to internal-form - gss_display_name 5.10 Convert internal-form name to - text - gss_compare_name 5.6 Compare two internal-form names - - gss_release_name 5.28 Discard an internal-form name - gss_inquire_names_for_mech 5.24 List the name-types supported by - the specified mechanism - gss_inquire_mechs_for_name 5.23 List mechanisms that support the - specified name-type - gss_canonicalize_name 5.5 Convert an internal name to an MN - gss_export_name 5.13 Convert an MN to export form - gss_duplicate_name 5.12 Create a copy of an internal name - - - Table 2-5 GSS-API Miscellaneous Routines - - Routine Section Function - ------- ------- -------- - gss_add_oid_set_member 5.4 Add an object identifier to - a set - gss_display_status 5.11 Convert a GSS-API status code - to text - gss_indicate_mechs 5.18 Determine available underlying - authentication mechanisms - gss_release_buffer 5.26 Discard a buffer - gss_release_oid_set 5.29 Discard a set of object - identifiers - gss_create_empty_oid_set 5.8 Create a set containing no - object identifiers - gss_test_oid_set_member 5.30 Determines whether an object - identifier is a member of a set. - - Individual GSS-API 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. - - - - - - - - -Wray Standards Track [Page 5] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - -3. Data Types and Calling Conventions - - The following conventions are used by the GSS-API C-language - bindings: - -3.1. Integer types - - GSS-API 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 GSS-API routine definitions. Individual GSS-API - 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 GSS-API 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 GSS-API implementation should use the smallest - natural unsigned integer type that provides at least 32 bits of - precision. - -3.2. String and similar data - - Many of the GSS-API routines take arguments and return values that - describe contiguous octet-strings. All such data is passed between - the GSS-API 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: - - 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 GSS-API routine - using the gss_buffer_t conventions is allocated by the GSS-API - 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. - - - - - - - -Wray Standards Track [Page 6] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - -3.2.1. Opaque data types - - Certain multiple-word data items are considered opaque data types at - the GSS-API, because their internal structure has no significance - either to the GSS-API 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 GSS-API). Opaque data is passed between the - GSS-API and the application using the gss_buffer_t datatype. - -3.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 GSS-API - routines also return character strings. All such character strings - are passed between the application and the GSS-API 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 GSS-API implementation or the application assume the - presence of an uncounted trailing NUL. - -3.3. Object Identifiers - - Certain GSS-API 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 GSS-API 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; - - 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 - - - -Wray Standards Track [Page 7] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - following octal values: 53,14,2,207,163,7,5. GSS-API 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 3.10). Applications should treat - gss_OID_desc values returned by GSS-API 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]. - -3.4. Object Identifier Sets - - Certain GSS-API procedures take parameters of the type gss_OID_set. - This type represents one or more object identifiers (section 2.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 GSS-API, to request the use - of specific mechanisms, and to indicate which mechanisms a given - credential supports. - - All OID sets returned to the application by GSS-API 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. - -3.5. Credentials - - A credential handle is a caller-opaque atomic datum that identifies a - GSS-API 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. - - GSS-API credentials can contain mechanism-specific principal - authentication data for multiple mechanisms. A GSS-API 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 - - - -Wray Standards Track [Page 8] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - 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 describe the actual mechanism-specific authentication data, one - to be used by GSS-API 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 GSS-API credential should - belong to the same entity, although enforcement of this property is - an implementation-specific matter. The GSS-API does not make the - actual credentials available to applications; instead a credential - handle is used to identify a particular credential, held internally - by GSS-API. The combination of GSS-API 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 - 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 - - 1) 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 - - 2) 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 - - 3) 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 - - - - - -Wray Standards Track [Page 9] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - initiating security contexts using the chosen mechanism, then - the principal corresponding to that identity shall be used, - otherwise - - 4) A user-configurable default identity should be used. - - gss_accept_sec_context - - 1) 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 - - 2) 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 - - 3) 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 - - 4)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. - -3.6. Contexts - - The gss_ctx_id_t data type contains a caller-opaque atomic value that - identifies one end of a GSS-API 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. - - - - - - - - - -Wray Standards Track [Page 10] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - -3.7. Authentication tokens - - A token is a caller-opaque type that GSS-API uses to maintain - synchronization between the context data structures at each end of a - GSS-API security context. The token is a cryptographically protected - octet-string, generated by the underlying mechanism at one end of a - GSS-API 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 GSS-API and the application using the gss_buffer_t conventions. - -3.8. Interprocess tokens - - Certain GSS-API routines are intended to transfer data between - processes in multi-process programs. These routines use a caller- - opaque octet-string, generated by the GSS-API in one process for use - by the GSS-API in another process. The calling application is - responsible for transferring such tokens between processes in an OS- - specific manner. Note that, while GSS-API 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 GSS-API and the application using the gss_buffer_t - conventions. - -3.9. Status values - - Every GSS-API routine returns two distinct values to report status - information to the caller: GSS status codes and Mechanism status - codes. - -3.9.1. GSS status codes - - GSS-API 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. - - - -Wray Standards Track [Page 11] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - 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 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 3-1 Calling Errors - - Name Value in field Meaning - ---- -------------- ------- - 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 Standards Track [Page 12] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - Table 3-2 Routine Errors - - Name Value in field Meaning - ---- -------------- ------- - 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_MIC GSS_S_BAD_SIG 6 A token had an invalid 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 - 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 - provided - GSS_S_UNAUTHORIZED 15 The operation is forbidden - by local security policy - GSS_S_UNAVAILABLE 16 The operation or option is - unavailable - 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 - - - - - - - - - - - -Wray Standards Track [Page 13] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - Table 3-3 Supplementary Status Bits - - Name Bit Number Meaning - ---- ---------- ------- - GSS_S_CONTINUE_NEEDED 0 (LSB) Returned only by - gss_init_sec_context or - gss_accept_sec_context. 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 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 - major status values only. - - The GSS major 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-specific status code will - provide more details about the error. - - - -Wray Standards Track [Page 14] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - -3.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. - -3.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: - - An internal form. This is the GSS-API "native" format for names, - represented by the implementation-specific gss_name_t type. It is - opaque to GSS-API 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 - 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 GSS-API implementations supporting multiple namespaces, - objects of type gss_name_t must contain sufficient information to - determine the namespace to which each primitive name belongs. - - - - - - -Wray Standards Track [Page 15] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - 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 GSS-API 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. - - 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 GSS-API assumes that all primitive names contained within a - - - -Wray Standards Track [Page 16] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - 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, - GSS-API defines a special form of the contiguous string name which - may be compared directly (e.g. with memcmp()). Contiguous 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 GSS-API 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 Standards Track [Page 17] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - -3.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 X.25 - 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 - - - - -Wray Standards Track [Page 18] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - form is used. When not otherwise specified, addresses should be - specified in network byte-order (that is, native byte-ordering for - the address family). - - 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. - -3.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. - -3.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. - -3.12.2. Integer types (input) - - Individual parameter documentation lists values to be used to - indicate default actions. - - - - - -Wray Standards Track [Page 19] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - -3.12.3. Integer types (output) - - Specify NULL as the value for the pointer. - -3.12.4. Pointer types - - Specify NULL as the value. - -3.12.5. Object IDs - - Specify GSS_C_NO_OID as the value. - -3.12.6. Object ID Sets - - Specify GSS_C_NO_OID_SET as the value. - -3.12.7. Channel Bindings - - Specify GSS_C_NO_CHANNEL_BINDINGS to indicate that channel bindings - are not to be used. - -4. 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. - - - -Wray Standards Track [Page 20] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - 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. - - 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 GSS-API can correctly indicate - whether the service is supported by the acceptor's GSS-API. - -4.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 GSS-API 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 - - - -Wray Standards Track [Page 21] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - 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 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 provided at the explicit request of the - application. - -4.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 the - context acceptor has authenticated itself. 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. - - - - - - - - - - - -Wray Standards Track [Page 22] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - -4.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 MIC over an application - message, and returns that MIC 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 MIC of an application message, - and places both the MIC 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 MIC. - - 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: - - GSS_S_DUPLICATE_TOKEN - The token is a duplicate of one that has - already been received and processed. Only - contexts that claim to provide replay detection - may set this bit. - 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. - - - - - -Wray Standards Track [Page 23] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - -4.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 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 ">". - -4.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. - - - -Wray Standards Track [Page 24] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - -4.6. Inter-process context transfer - - GSS-API 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 GSS-API 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 gss_export_sec_context, the - original security context is made inaccessible to the calling process - by GSS-API, 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. - - 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. - -4.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 - - - -Wray Standards Track [Page 25] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - 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. - -5. 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. - -5.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. - - - - -Wray Standards Track [Page 26] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - 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); - 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: - - The value returned via the time_rec parameter is undefined 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. - - - - -Wray Standards Track [Page 27] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - 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 GSS-API 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 GSS-API. 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. - 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). - - During context establishment, the informational status bits - GSS_S_OLD_TOKEN and GSS_S_DUPLICATE_TOKEN indicate fatal errors, and - GSS-API mechanisms should always return them in association with a - routine error of GSS_S_FAILURE. This requirement for pairing did not - exist in version 1 of the GSS-API specification, so applications that - wish to run over version 1 implementations must special-case these - codes. - - - - - - - - - -Wray Standards Track [Page 28] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - 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. 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(). - - - -Wray Standards Track [Page 29] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - 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 - 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 - - - -Wray Standards Track [Page 30] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - 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 - transferable. - 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 - 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. - - 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. - - - -Wray Standards Track [Page 31] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - 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. - - GSS_S_BAD_MECH The received token specified a mechanism that is - not supported by the implementation or the - provided credential. - -5.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) - - - - - - - - -Wray Standards Track [Page 32] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - 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). - - Mechanisms should honor the desired_mechs parameter, and return a - credential that is suitable to use only with the requested - mechanisms. An exception to this is the case where one underlying - credential element can be shared by multiple mechanisms; in this case - it is permissible for an implementation to indicate all mechanisms - with which the credential element may be used. If desired_mechs is - an empty set, behavior is undefined. - - 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 GSS_C_NO_NAME, or a name - produced by applying either gss_inquire_cred to a valid credential, - or gss_inquire_context to an active context. - - If credential acquisition is time-consuming for a mechanism, the - mechanism may choose 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. - - - - - - - - -Wray Standards Track [Page 33] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - 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 - credentials, the value GSS_C_INDEFINITE will - be returned. Specify NULL if not required - - - - - -Wray Standards Track [Page 34] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - 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. - -5.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) - - Purpose: - - Adds a credential-element to a credential. The credential-element is - identified by the name of the principal to which it refers. GSS-API - 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 GSS-API handle to - existing data. Such functions, if required, should be defined in - implementation-specific extensions to the API. - - - - -Wray Standards Track [Page 35] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - If desired_name is GSS_C_NO_NAME, the call is interpreted as a - request to add a credential element 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 GSS_C_NO_NAME, or a name - produced by applying either gss_inquire_cred to a valid credential, - or gss_inquire_context to an active context. - - If credential acquisition is time-consuming for a mechanism, the - mechanism may choose 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_add_cred - must return valid credential data, and may therefore incur the - overhead of a deferred credential acquisition. - - This routine can be used to either compose 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 handle will be created. - - If GSS_C_NO_CREDENTIAL is specified as the input_cred_handle, - gss_add_cred will compose a credential (and set the - output_cred_handle parameter accordingly) 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. - - - - - - -Wray Standards Track [Page 36] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - Parameters: - - 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 compose 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 - composed 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 - composed credentials are of type GSS_C_INITIATE. - - - -Wray Standards Track [Page 37] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - Specify GSS_C_INDEFINITE to request that the - credentials have the maximum permitted initiator - lifetime. - - 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 - - - - -Wray Standards Track [Page 38] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - 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_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. - -5.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 - GSS-API (e.g. a set returned by gss_create_empty_oid_set()). GSS-API - 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; if the - member_oid is already present, the oid_set should remain unchanged. - - Parameters: - - minor_status Integer, modify - Mechanism specific status code - - - - - -Wray Standards Track [Page 39] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - 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. - - Function value: GSS status code - - GSS_S_COMPLETE Successful completion - -5.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. - - - - - - - -Wray Standards Track [Page 40] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - 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 - - 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 specified - mechanism. - - GSS_S_BAD_NAME The provided internal name was ill-formed. - -5.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 - - - - - - -Wray Standards Track [Page 41] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - 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 - - 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. - -5.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 Standards Track [Page 42] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - -5.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 - -5.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 may be obtained using the context specified by - context_handle. - - - - -Wray Standards Track [Page 43] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - 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 GSS-API 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 Standards Track [Page 44] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - -5.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. - - If input_name was created by a call to gss_import_name, specifying - GSS_C_NO_OID as the name-type, implementations that employ lazy - conversion between name types may return GSS_C_NO_OID via the - output_name_type parameter. - - 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, the application should not attempt - to free it). Specify NULL if not required. - - - - - - - -Wray Standards Track [Page 45] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - Function value: GSS status code - - GSS_S_COMPLETE Successful completion - - GSS_S_BAD_NAME input_name was ill-formed - -5.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_display_status 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 { - - - -Wray Standards Track [Page 46] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - 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", - (int)status_string.length, - - (char *)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 - - - - - -Wray Standards Track [Page 47] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - 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 - - 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. - -5.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(). - - - -Wray Standards Track [Page 48] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - Function value: GSS status code - - GSS_S_COMPLETE Successful completion - - GSS_S_BAD_NAME The src_name parameter was ill-formed. - -5.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 provided internal name was ill-formed. - - GSS_S_BAD_NAMETYPE The internal name was of a type not supported - by the GSS-API implementation. - - - - -Wray Standards Track [Page 49] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - -5.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 GSS-API 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 successful, 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. - - - - -Wray Standards Track [Page 50] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - Parameters: - - minor_status Integer, modify - Mechanism specific status code - - 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. - -5.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. - - Since some application-level protocols may wish to use tokens emitted - by gss_wrap() to provide "secure framing", implementations must - support derivation of MICs from zero-length messages. - - - - - - - -Wray Standards Track [Page 51] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - 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 - - 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. - -5.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) - - - - - -Wray Standards Track [Page 52] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - 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. - - 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 recognized - 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 - - GSS_S_BAD_MECH The input name-type was GSS_C_NT_EXPORT_NAME, - but the mechanism contained within the - input-name is not supported - - - - - - - - -Wray Standards Track [Page 53] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - -5.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. - - 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. - -5.18. gss_indicate_mechs - - OM_uint32 gss_indicate_mechs ( - OM_uint32 *minor_status, - gss_OID_set *mech_set) - - - - - -Wray Standards Track [Page 54] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - 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 - 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 - -5.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 - - - -Wray Standards Track [Page 55] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - 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. - - 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; - }; - - - -Wray Standards Track [Page 56] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - 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: - - The value returned via the time_rec parameter is undefined 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. - - 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. - - GSS-API implementations that support per-message protection are - encouraged to 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). However, applications should not rely on this - behavior as the flag was not defined in Version 1 of the GSS-API. - Instead, applications should determine what per-message services - are available after a successful context establishment according - to the GSS_C_INTEG_FLAG and GSS_C_CONF_FLAG values. - - - -Wray Standards Track [Page 57] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - 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). - - During context establishment, the informational status bits - GSS_S_OLD_TOKEN and GSS_S_DUPLICATE_TOKEN indicate fatal errors, and - GSS-API mechanisms should always return them in association with a - routine error of GSS_S_FAILURE. This requirement for pairing did not - exist in version 1 of the GSS-API specification, so applications that - wish to run over version 1 implementations must special-case these - codes. - - 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 gss_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 - - - -Wray Standards Track [Page 58] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - 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 - - 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_CONF_FLAG - True - Request that confidentiality service - be made available (via gss_wrap) - False - No per-message confidentiality service - is required. - - GSS_C_INTEG_FLAG - True - Request that integrity service be - made available (via gss_wrap or - gss_get_mic) - False - No per-message integrity service - is required. - - - - - - -Wray Standards Track [Page 59] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - 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 - logically-ANDed with the ret_flags value to test - whether a given option is supported by the - context. The flags are: - - - -Wray Standards Track [Page 60] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - GSS_C_DELEG_FLAG - True - Credentials were delegated to - the remote peer - False - No credentials were delegated - - GSS_C_MUTUAL_FLAG - True - The remote peer has authenticated - itself. - False - Remote peer has not authenticated - 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 - - - -Wray Standards Track [Page 61] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - 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. - 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 - transferable. - - 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 - - - -Wray Standards Track [Page 62] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - 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 - - 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. - -5.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. - - - - - - - -Wray Standards Track [Page 63] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - 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. - 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(). If the context acceptor - did not authenticate itself, and if the initiator - did not specify a target name in its call to - gss_init_sec_context(), the value GSS_C_NO_NAME - will be returned. 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. - - - - - -Wray Standards Track [Page 64] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - 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 - - 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. - - - -Wray Standards Track [Page 65] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - 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 - transferable. - - 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. - - - - -Wray Standards Track [Page 66] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - -5.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. - - 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. - - 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. - - - - - -Wray Standards Track [Page 67] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - 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. - -5.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. - - 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. - - - - -Wray Standards Track [Page 68] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - 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 - 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. - - - - - -Wray Standards Track [Page 69] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - GSS_S_CREDENTIALS_EXPIRED The referenced credentials have expired. - If the lifetime parameter was not passed as NULL, - it will be set to 0. - -5.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 GSS-API 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 GSS-API layer, using the type - information contained within the presented name, and based on - registration information 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. - - - -Wray Standards Track [Page 70] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - GSS_S_BAD_NAMETYPE The input_name parameter contained an invalid or - unsupported type of name - -5.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. - - 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 - -5.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 an asynchronous token to the security service. - Most context-level tokens are emitted and processed synchronously by - gss_init_sec_context and gss_accept_sec_context, and the application - is informed as to whether further tokens are expected by the - GSS_C_CONTINUE_NEEDED major status bit. Occasionally, a mechanism - may need to emit a context-level token at a point when the peer - entity is not expecting a token. For example, the initiator's final - - - -Wray Standards Track [Page 71] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - call to gss_init_sec_context may emit a token and return a status of - GSS_S_COMPLETE, but the acceptor's call to gss_accept_sec_context may - fail. The acceptor's mechanism may wish to send a token containing - an error indication to the initiator, but the initiator is not - expecting a token at this point, believing that the context is fully - established. Gss_process_context_token provides a way to pass such a - token to the mechanism at any time. - - 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 - - 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 - -5.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, and implementations - are encouraged to additionally set the pointer field in the - descriptor to NULL. Any buffer object returned by a GSS-API routine - may be passed to gss_release_buffer (even if there is no storage - associated with the buffer). - - - - - - -Wray Standards Track [Page 72] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - 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 - -5.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. - Implementations are encouraged to set the cred_handle to - GSS_C_NO_CREDENTIAL on successful completion of this call. - - 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. - - - - - - - -Wray Standards Track [Page 73] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - -5.28. 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. - Implementations are encouraged to set the name to GSS_C_NO_NAME on - successful completion of this call. - - Parameters: - - minor_status Integer, modify - Mechanism specific status code - - 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 - -5.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 - GSS-API 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. - - Implementations are encouraged to set the gss_OID_set parameter to - GSS_C_NO_OID_SET on successful completion of this routine. - - Parameters: - - minor_status Integer, modify - Mechanism specific status code - - - - -Wray Standards Track [Page 74] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - 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 - -5.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 - - - - - - - - - -Wray Standards Track [Page 75] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - -5.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) - - 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. - - Since some application-level protocols may wish to use tokens emitted - by gss_wrap() to provide "secure framing", implementations must - support the wrapping and unwrapping 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 - 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 - - - - - - -Wray Standards Track [Page 76] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - qop_state gss_qop_t, modify, optional - Quality of protection provided. - 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 - -5.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) - - - - - - - - -Wray Standards Track [Page 77] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - 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. - - Since some application-level protocols may wish to use tokens emitted - by gss_wrap() to provide "secure framing", implementations must - support the calculation and verification of MICs over 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 - arrived - - message_buffer buffer, opaque, read - Message to be verified - - token_buffer buffer, opaque, read - Token associated with message - - 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 Standards Track [Page 78] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - 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 - -5.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 ) - - 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 must - 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 - - - - - - - -Wray Standards Track [Page 79] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - 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 - - 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. - - - - - - - - - - -Wray Standards Track [Page 80] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - -5.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. - - GSS-API implementations are recommended but not required to detect - invalid QOP values when gss_wrap_size_limit() is called. This routine - guarantees only a maximum message size, not the availability of - specific QOP values for message 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 - which the messages will be sent. - - conf_req_flag Boolean, read - Indicates whether gss_wrap will be asked - to apply confidentiality protection in - - - - - -Wray Standards Track [Page 81] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - 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. - -6. Security Considerations - - This document specifies a service interface for security facilities - and services; as such, security considerations appear throughout the - specification. Nonetheless, it is appropriate to summarize certain - specific points relevant to GSS-API implementors and calling - applications. Usage of the GSS-API interface does not in itself - provide security services or assurance; instead, these attributes are - dependent on the underlying mechanism(s) which support a GSS-API - implementation. Callers must be attentive to the requests made to - GSS-API calls and to the status indicators returned by GSS-API, as - these specify the security service characteristics which GSS-API will - provide. When the interprocess context transfer facility is used, - appropriate local controls should be applied to constrain access to - interprocess tokens and to the sensitive data which they contain. - - - - - -Wray Standards Track [Page 82] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - 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; - - - -Wray Standards Track [Page 83] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - #else - - /* - * 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. - */ - - - - - - - - -Wray Standards Track [Page 84] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - #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 - - /* - * 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 - - - - -Wray Standards Track [Page 85] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - #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} - - /* - * 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 GSS-API 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. - - - -Wray Standards Track [Page 86] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - */ - 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; - - /* - * 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 - * {iso(1) org(3) dod(6) internet(1) security(5) - * nametypes(6) gss-host-based-services(2)). The constant - * GSS_C_NT_HOSTBASED_SERVICE_X should be initialized to point - * to that gss_OID_desc. This is a deprecated OID value, and - * implementations wishing to support hostbased-service names - * should instead use the GSS_C_NT_HOSTBASED_SERVICE OID, - * defined below, to identify such names; - * GSS_C_NT_HOSTBASED_SERVICE_X should be accepted a synonym - * for GSS_C_NT_HOSTBASED_SERVICE when presented as an input - * parameter, but should not be emitted by GSS-API - * implementations - */ - extern gss_OID GSS_C_NT_HOSTBASED_SERVICE_X; - - - - -Wray Standards Track [Page 87] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - /* - * 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\x04"}, corresponding to an - * object-identifier value of {iso(1) member-body(2) - * Unites States(840) mit(113554) infosys(1) gssapi(2) - * generic(1) service_name(4)}. 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; - - - /* 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 - - - -Wray Standards Track [Page 88] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - #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 GSS-API 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) - #define GSS_S_BAD_BINDINGS (4ul << - GSS_C_ROUTINE_ERROR_OFFSET) - #define GSS_S_BAD_STATUS (5ul << - - - -Wray Standards Track [Page 89] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - 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. - */ - - - - - -Wray Standards Track [Page 90] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - 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 */ - 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 */ - ); - - - - -Wray Standards Track [Page 91] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - 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 */ - 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 */ - ); - - - - - - - - -Wray Standards Track [Page 92] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - 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 */ - 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 */ - ); - - - - - - -Wray Standards Track [Page 93] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - 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 */ - 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 */ - ); - - - - - - - - - - -Wray Standards Track [Page 94] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - 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 ( - OM_uint32 , /* minor_status */ - const gss_buffer_t, /* interprocess_token */ - gss_ctx_id_t * /* context_handle */ - ); - - - - - - - -Wray Standards Track [Page 95] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - 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 - * provided by GSS-API V2 implementations for backwards - * compatibility with V1 applications. Distinct entrypoints - - - -Wray Standards Track [Page 96] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - * (as opposed to #defines) should be provided, both to allow - * GSS-API V1 applications to link against GSS-API 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 Standards Track [Page 97] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - -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. - - - - - -Wray Standards Track [Page 98] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - -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. - -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. - - The size of the handle type must be the same as sizeof(void *), using - the appropriate memory model. - - 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) - - 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 - - - -Wray Standards Track [Page 99] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - 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 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 GSS-API implementations. - -References - - [GSSAPI] Linn, J., "Generic Security Service Application Program - Interface Version 2, Update 1", RFC 2743, January 2000. - - [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 - Iris Associates - 5 Technology Park Drive, - Westford, MA 01886 - USA - - Phone: +1-978-392-6689 - EMail: John_Wray@Iris.com - - - - - - -Wray Standards Track [Page 100] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - -Full Copyright Statement - - Copyright (C) The Internet Society (2000). 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. - -Acknowledgement - - Funding for the RFC Editor function is currently provided by the - Internet Society. - - - - - - - - - - - - - - - - - - - -Wray Standards Track [Page 101] -