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 a97ef9d191e..00000000000 --- 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 1fc9927dea4..00000000000 --- 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 202d44e8639..00000000000 --- 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 8174d4678f8..00000000000 --- 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 62b109afa52..00000000000 --- 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 0fa695f640f..00000000000 --- 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 7e0fa0a6281..00000000000 --- 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 2b8b7bb5775..00000000000 --- 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 c024ca355cd..00000000000 --- 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 89e64524c47..00000000000 --- 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 4dcff486b93..00000000000 --- 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 ccba35eeb4a..00000000000 --- 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 518f4c63d17..00000000000 --- 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 208d057f24c..00000000000 --- 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 e235bec58c0..00000000000 --- 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 2583a84da0a..00000000000 --- 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 46a41585270..00000000000 --- 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 c5e4d05e7e3..00000000000 --- 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 b3ec336b651..00000000000 --- 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 d09a2ded5bc..00000000000 --- 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 4b193c57390..00000000000 --- 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 1ab2b03e079..00000000000 --- 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 d91c087dddf..00000000000 --- 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 9b0e76adad9..00000000000 --- 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 b1e596836eb..00000000000 --- 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 6581dd5810a..00000000000 --- 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 2284c3c6b57..00000000000 --- 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 78db9d78f3c..00000000000 --- 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 06d997d48cc..00000000000 --- 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 16af15dbce9..00000000000 --- 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 15921248c11..00000000000 --- 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 ae79e8a7c4f..00000000000 --- 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 6f7dae0dea7..00000000000 --- 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 0319f8bf347..00000000000 --- 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 e76a0e402ad..00000000000 --- 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 bd31750a15a..00000000000 --- 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 11e5dc9f954..00000000000 --- 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 885cf496767..00000000000 --- 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 5845995f2d9..00000000000 --- 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 a6dec9d1e07..00000000000 --- 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 24325fdbda7..00000000000 --- 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 64ca1ac498b..00000000000 --- 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 321c5ba0998..00000000000 --- 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 85d745684b2..00000000000 --- 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 85d745684b2..00000000000 --- 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 68c170b499e..00000000000 --- 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 b89108a53be..00000000000 --- 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 e9611e395bf..00000000000 --- 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 202d44e8639..00000000000 --- 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 132b855e05e..00000000000 --- 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 f36cd80e6dc..00000000000 --- 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 bc810cc506f..00000000000 --- 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 56d478c7eef..00000000000 --- 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 0556c9e83f3..00000000000 --- 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 f2960b961dd..00000000000 --- 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 1dd1e4aebd2..00000000000 --- 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 2f6a8a0d0f3..00000000000 --- 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 1fbfcbfa09f..00000000000 --- 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 e5da571abb4..00000000000 --- 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 7f0c61946f2..00000000000 --- 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] -