 193e69bf87
			
		
	
	193e69bf87
	
	
	
		
			
			git-svn-id: svn://svn.h5l.se/heimdal/trunk/heimdal@13153 ec53bebd-3082-4978-b11e-865c3cabbd6b
		
			
				
	
	
		
			885 lines
		
	
	
		
			37 KiB
		
	
	
	
		
			Plaintext
		
	
	
	
	
	
			
		
		
	
	
			885 lines
		
	
	
		
			37 KiB
		
	
	
	
		
			Plaintext
		
	
	
	
	
	
| 
 | ||
| 
 | ||
| <Network Working Group>                                       Larry Zhu 
 | ||
| Internet Draft                                       Karthik Jaganathan 
 | ||
| Updates: 1964                                                 Microsoft 
 | ||
| Category: Standards Track                                   Sam Hartman 
 | ||
| draft-ietf-krb-wg-gssapi-cfx-04.txt                                 MIT 
 | ||
|                                                       November 21, 2003 
 | ||
|                                                   Expires: May 21, 2004 
 | ||
|  
 | ||
|           The Kerberos Version 5 GSS-API 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 [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. 
 | ||
|     
 | ||
| Abstract 
 | ||
|     
 | ||
|    This memo defines protocols, procedures, and conventions to be 
 | ||
|    employed by peers implementing the Generic Security Service 
 | ||
|    Application Program Interface (GSS-API as specified in [RFC-2743]) 
 | ||
|    when using the Kerberos Version 5 mechanism (as specified in 
 | ||
|    [KRBCLAR]). 
 | ||
|     
 | ||
|    [RFC-1964] is updated and incremental changes are proposed in 
 | ||
|    response to recent developments such as the introduction of Kerberos 
 | ||
|    crypto framework [KCRYPTO].  These changes support the inclusion of 
 | ||
|    new cryptosystems based on crypto profiles [KCRYPTO], by defining 
 | ||
|    new per-message tokens along with their encryption and checksum 
 | ||
|    algorithms.   
 | ||
|     
 | ||
| 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]. 
 | ||
|     
 | ||
| 1. Introduction 
 | ||
|     
 | ||
| 
 | ||
|   
 | ||
| Zhu                         Internet Draft                           1 
 | ||
|                  Kerberos Version 5 GSS-API      November 2003 
 | ||
|  
 | ||
|  
 | ||
|    [KCRYPTO] defines a generic framework for describing encryption and 
 | ||
|    checksum types to be used with the Kerberos protocol and associated 
 | ||
|    protocols. 
 | ||
|     
 | ||
|    [RFC-1964] describes the GSS-API mechanism for Kerberos Version 5.  
 | ||
|    It defines the format of context establishment, per-message and 
 | ||
|    context deletion tokens and uses algorithm identifiers for each 
 | ||
|    cryptosystem in per message and context deletion tokens.   
 | ||
|     
 | ||
|    The approach taken in this document obviates the need for algorithm 
 | ||
|    identifiers.  This is accomplished by using the same encryption 
 | ||
|    algorithm, specified by the crypto profile [KCRYPTO] for the session 
 | ||
|    key or subkey that is created during context negotiation, and its 
 | ||
|    required checksum algorithm.  Message layouts of the per-message 
 | ||
|    tokens are therefore revised to remove algorithm indicators and also 
 | ||
|    to add extra information to support the generic crypto framework 
 | ||
|    [KCRYPTO].  
 | ||
|     
 | ||
|    Tokens transferred between GSS-API peers for security context 
 | ||
|    establishment are also described in this document.  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 [KRBCLAR] rather than within this specification. 
 | ||
|     
 | ||
|    The new token formats specified in this memo MUST be used with all 
 | ||
|    "newer" encryption types [KRBCLAR] and MAY be used with "older" 
 | ||
|    encryption types, provided that the initiator and acceptor know, 
 | ||
|    from the context establishment, that they can both process these new 
 | ||
|    token formats. 
 | ||
|     
 | ||
|    "Newer" encryption types are those which have been specified along 
 | ||
|    with or since the new Kerberos cryptosystem specification [KCRYPTO], 
 | ||
|    as defined in section 3.1.3 of [KRBCLAR].  The list of not-newer 
 | ||
|    encryption types is as follows [KCRYPTO]: 
 | ||
|     
 | ||
|              Encryption Type             Assigned Number     
 | ||
|            ---------------------------------------------- 
 | ||
|             des-cbc-crc                        1              
 | ||
|             des-cbc-md4                        2              
 | ||
|             des-cbc-md5                        3              
 | ||
|             des3-cbc-md5                       5 
 | ||
|             des3-cbc-sha1                      7 
 | ||
|             dsaWithSHA1-CmsOID                 9            
 | ||
|             md5WithRSAEncryption-CmsOID       10            
 | ||
|             sha1WithRSAEncryption-CmsOID      11           
 | ||
|             rc2CBC-EnvOID                     12            
 | ||
|             rsaEncryption-EnvOID              13    
 | ||
|             rsaES-OAEP-ENV-OID                14    
 | ||
|             des-ede3-cbc-Env-OID              15            
 | ||
|             des3-cbc-sha1-kd                  16                       
 | ||
|             rc4-hmac                          23          
 | ||
|     
 | ||
|    Note that in this document, the term "little endian order" is used 
 | ||
|    for brevity to refer to the least-significant-octet-first encoding,
 | ||
|  
 | ||
| 
 | ||
| Zhu                         Internet Draft                           2 
 | ||
|                  Kerberos Version 5 GSS-API      November 2003 
 | ||
|  
 | ||
|  
 | ||
|    while the term "big endian order" is for the most-significant-octet-
 | ||
|    first encoding. 
 | ||
|     
 | ||
| 2. Key Derivation for Per-Message Tokens 
 | ||
|     
 | ||
|    To limit the exposure of a given key, [KCRYPTO] adopted "one-way" 
 | ||
|    "entropy-preserving" derived keys, for different purposes or key 
 | ||
|    usages, from a base key or protocol key.   
 | ||
|     
 | ||
|    This document defines four key usage values below that are used to 
 | ||
|    derive a specific key for signing and sealing messages, from the 
 | ||
|    session key or subkey [KRBCLAR] created during the context 
 | ||
|    establishment. 
 | ||
|     
 | ||
|         Name                         Value 
 | ||
|       ------------------------------------- 
 | ||
|        KG-USAGE-ACCEPTOR-SEAL         22 
 | ||
|        KG-USAGE-ACCEPTOR-SIGN         23 
 | ||
|        KG-USAGE-INITIATOR-SEAL        24 
 | ||
|        KG-USAGE-INITIATOR-SIGN        25 
 | ||
|           
 | ||
|    When the sender is the context acceptor, KG-USAGE-ACCEPTOR-SIGN is 
 | ||
|    used as the usage number in the key derivation function for deriving 
 | ||
|    keys to be used in MIC tokens, and KG-USAGE-ACCEPTOR-SEAL is used 
 | ||
|    for Wrap tokens; similarly when the sender is the context initiator, 
 | ||
|    KG-USAGE-INITIATOR-SIGN is used as the usage number in the key 
 | ||
|    derivation function for MIC tokens, KG-USAGE-INITIATOR-SEAL is used 
 | ||
|    for Wrap Tokens.  Even if the Wrap token does not provide for 
 | ||
|    confidentiality the same usage values specified above are used. 
 | ||
|     
 | ||
|    During the context initiation and acceptance sequence, the acceptor 
 | ||
|    MAY assert a subkey, and if so, subsequent messages MUST use this 
 | ||
|    subkey as the protocol key and these messages MUST be flagged as 
 | ||
|    "AcceptorSubkey" as described in section 4.2.2. 
 | ||
|  
 | ||
| 3. Quality of Protection 
 | ||
|  
 | ||
|    The GSS-API specification [RFC-2743] provides for Quality of 
 | ||
|    Protection (QOP) values that can be used by applications to request 
 | ||
|    a certain type of encryption or signing.  A zero QOP value is used 
 | ||
|    to indicate the "default" protection; applications which do not use 
 | ||
|    the default QOP are not guaranteed to be portable across 
 | ||
|    implementations or even inter-operate with different deployment 
 | ||
|    configurations of the same implementation.  Using an algorithm that 
 | ||
|    is different from the one for which the key is defined may not be 
 | ||
|    appropriate.  Therefore, when the new method in this document is 
 | ||
|    used, the QOP value is ignored. 
 | ||
|     
 | ||
|    The encryption and checksum algorithms in per-message tokens are now 
 | ||
|    implicitly defined by the algorithms associated with the session key 
 | ||
|    or subkey.  Algorithms identifiers as described in [RFC-1964] are 
 | ||
|    therefore no longer needed and removed from the new token headers. 
 | ||
|  
 | ||
| 4. Definitions and Token Formats 
 | ||
| 
 | ||
| 
 | ||
| Zhu                         Internet Draft                           3 
 | ||
|                  Kerberos Version 5 GSS-API      November 2003 
 | ||
|  
 | ||
|  
 | ||
|     
 | ||
|    This section provides terms and definitions, as well as descriptions 
 | ||
|    for tokens specific to the Kerberos Version 5 GSS-API mechanism. 
 | ||
|                                     
 | ||
| 4.1. Context Establishment Tokens 
 | ||
|     
 | ||
|    All context establishment tokens emitted by the Kerberos V5 GSS-API 
 | ||
|    mechanism will have the framing shown below: 
 | ||
|     
 | ||
|          GSS-API DEFINITIONS ::= 
 | ||
|     
 | ||
|          BEGIN 
 | ||
|     
 | ||
|          MechType ::= OBJECT IDENTIFIER 
 | ||
|          -- representing Kerberos V5 mechanism 
 | ||
|     
 | ||
|          GSSAPI-Token ::= 
 | ||
|          -- option indication (delegation, etc.) indicated within 
 | ||
|          -- mechanism-specific token 
 | ||
|          [APPLICATION 0] IMPLICIT SEQUENCE { 
 | ||
|                  thisMech MechType, 
 | ||
|                  innerToken ANY DEFINED BY thisMech 
 | ||
|                     -- contents mechanism-specific 
 | ||
|                     -- ASN.1 structure not required 
 | ||
|                  } 
 | ||
|     
 | ||
|          END 
 | ||
|     
 | ||
|    Where the notation and encoding of this pseudo ASN.1 header, which 
 | ||
|    is referred as the generic GSS-API token framing later in this 
 | ||
|    document, are described in [RFC-2743], and the innerToken field 
 | ||
|    starts with a two-octet token-identifier (TOK_ID) expressed in big 
 | ||
|    endian order, followed by a Kerberos message.   
 | ||
|     
 | ||
|    Here are the TOK_ID values used in the context establishment tokens: 
 | ||
|     
 | ||
|          Token               TOK_ID Value in Hex  
 | ||
|         ----------------------------------------- 
 | ||
|          KRB_AP_REQUEST        01 00 
 | ||
|          KRB_AP_REPLY          02 00 
 | ||
|          KRB_ERROR             03 00 
 | ||
|              
 | ||
|    Where Kerberos message KRB_AP_REQUEST, KRB_AP_REPLY, and KRB_ERROR 
 | ||
|    are defined in [KRBCLAR].   
 | ||
|     
 | ||
|    If an unknown token identifier (TOK_ID) is received in the initial 
 | ||
|    context estalishment token, the receiver MUST return 
 | ||
|    GSS_S_CONTINUE_NEEDED major status, and the returned output token 
 | ||
|    MUST contain a KRB_ERROR message with the error code 
 | ||
|    KRB_AP_ERR_MSG_TYPE [KRBCLAR]. 
 | ||
|     
 | ||
| 4.1.1. Authenticator Checksum 
 | ||
|  
 | ||
| 
 | ||
| Zhu                         Internet Draft                           4 
 | ||
|                  Kerberos Version 5 GSS-API      November 2003 
 | ||
|  
 | ||
|  
 | ||
|    The authenticator in the KRB_AP_REQ message MUST include the 
 | ||
|    optional sequence number and the checksum field.  The checksum field 
 | ||
|    is used to convey service flags, channel bindings, and optional 
 | ||
|    delegation information.  The checksum type MUST be 0x8003.  The 
 | ||
|    length of the checksum MUST be 24 octets when delegation is not 
 | ||
|    used.  When delegation is used, a ticket-granting ticket will be 
 | ||
|    transferred in a KRB_CRED message.  This ticket SHOULD have its 
 | ||
|    forwardable flag set.  The KRB_CRED message MUST be encrypted in the 
 | ||
|    session key of the ticket used to authenticate the context. 
 | ||
|     
 | ||
|    The format of the authenticator checksum field is as follows. 
 | ||
|        
 | ||
|       Octet    Name      Description 
 | ||
|      ----------------------------------------------------------------- 
 | ||
|       0..3    Lgth    Number of octets in Bnd field;  Currently  
 | ||
|                       contains hex value 10 00 00 00 (16, represented  
 | ||
|                       in little-endian order) 
 | ||
|       4..19   Bnd     Channel binding information, as described in  
 | ||
|                       section 4.1.1.2. 
 | ||
|       20..23  Flags   Four-octet context-establishment flags in little- 
 | ||
|                       endian order as described in section 4.1.1.1.  
 | ||
|       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] 
 | ||
|  
 | ||
| 4.1.1.1. Checksum Flags Field 
 | ||
|     
 | ||
|    The checksum "Flags" field is used to convey service options or 
 | ||
|    extension negotiation information.  The following context 
 | ||
|    establishment flags are defined in [RFC-2744]. 
 | ||
|     
 | ||
|         Flag Name              Value     
 | ||
|       --------------------------------- 
 | ||
|        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     
 | ||
|         
 | ||
|    Context establishment flags are exposed to the calling application.  
 | ||
|    If the calling application desires a particular service option then 
 | ||
|    it requests that option via GSS_Init_sec_context() [RFC-2743].  An 
 | ||
|    implementation that supports a particular option or extension SHOULD 
 | ||
|    then set the appropriate flag in the checksum Flags field.   
 | ||
|     
 | ||
|    The most significant eight bits of the checksum flags are reserved 
 | ||
|    for future use.  The receiver MUST ignore unknown checksum flags. 
 | ||
|     
 | ||
| 4.1.1.2. Channel Binding Information 
 | ||
|  
 | ||
|    Channel bindings are user-specified tags to identify a given context 
 | ||
|    to the peer application.  These tags are intended to be used to 
 | ||
| 
 | ||
| 
 | ||
| Zhu                         Internet Draft                           5 
 | ||
|                  Kerberos Version 5 GSS-API      November 2003 
 | ||
|  
 | ||
|  
 | ||
|    identify the particular communications channel that carries the 
 | ||
|    context [RFC-2743] [RFC-2744]. 
 | ||
|     
 | ||
|    When using C language bindings, channel bindings are communicated to 
 | ||
|    the GSS-API using the following structure [RFC-2744]: 
 | ||
|  
 | ||
|       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 member fields and constants used for different address types are 
 | ||
|    defined in [RFC-2744]. 
 | ||
|     
 | ||
|    The "Bnd" field contains the 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. 
 | ||
|     
 | ||
|    In computing the contents of the Bnd field, the following detailed 
 | ||
|    points apply:  
 | ||
|     
 | ||
|    (1) Each integer field shall be formatted into four octets, using 
 | ||
|    little endian octet ordering, for purposes of MD5 hash computation.  
 | ||
|     
 | ||
|    (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 binding structure, the Bnd field shall be set to 16 
 | ||
|    zero-valued octets.  
 | ||
|  
 | ||
| 4.2. Per-Message Tokens 
 | ||
|     
 | ||
|    Two classes of tokens are defined in this section:  "MIC" tokens, 
 | ||
|    emitted by calls to GSS_GetMIC() and consumed by calls to 
 | ||
|    GSS_VerifyMIC(), "Wrap" tokens, emitted by calls to GSS_Wrap() and 
 | ||
|    consumed by calls to GSS_Unwrap(). 
 | ||
|     
 | ||
|    The new per-message tokens introduced here do not include the 
 | ||
|    generic GSS-API token framing used by the context establishment 
 | ||
|    tokens.  These new tokens are designed to be used with newer crypto 
 | ||
|    systems that can, for example, have variable-size checksums.   
 | ||
|     
 | ||
| 4.2.1. Sequence Number 
 | ||
|  
 | ||
| 
 | ||
| Zhu                         Internet Draft                           6 
 | ||
|                  Kerberos Version 5 GSS-API      November 2003 
 | ||
|  
 | ||
|  
 | ||
|    To distinguish intentionally-repeated messages from maliciously-
 | ||
|    replayed ones, per-message tokens contain a sequence number field, 
 | ||
|    which is a 64 bit integer expressed in big endian order.  After 
 | ||
|    sending a GSS_GetMIC() or GSS_Wrap() token, the sender's sequence 
 | ||
|    numbers are incremented by one. 
 | ||
|  
 | ||
| 4.2.2. Flags Field 
 | ||
|  
 | ||
|    The "Flags" field is a one-octet integer used to indicate a set of 
 | ||
|    attributes for the protected message.  For example, one flag is 
 | ||
|    allocated as the direction-indicator, thus preventing an adversary 
 | ||
|    from sending back the same message in the reverse direction and 
 | ||
|    having it accepted.   
 | ||
|     
 | ||
|    The meanings of bits in this field (the least significant bit is bit 
 | ||
|    0) are as follows: 
 | ||
|     
 | ||
|         Bit    Name             Description 
 | ||
|        --------------------------------------------------------------- 
 | ||
|         0   SentByAcceptor    When set, this flag indicates the sender  
 | ||
|                               is the context acceptor.  When not set, 
 | ||
|                               it indicates the sender is the context  
 | ||
|                               initiator. 
 | ||
|         1   Sealed            When set in Wrap tokens, this flag  
 | ||
|                               indicates confidentiality is provided  
 | ||
|                               for.  It SHALL NOT be set in MIC tokens. 
 | ||
|         2   AcceptorSubkey    A subkey asserted by the context acceptor 
 | ||
|                               is used to protect the message. 
 | ||
|     
 | ||
|    The rest of available bits are reserved for future use and MUST be 
 | ||
|    cleared.  The receiver MUST ignore unknown flags. 
 | ||
|     
 | ||
| 4.2.3. EC Field 
 | ||
|  
 | ||
|    The "EC" (Extra Count) field is a two-octet integer field expressed 
 | ||
|    in big endian order.   
 | ||
|     
 | ||
|    In Wrap tokens with confidentiality, the EC field is used to encode 
 | ||
|    the number of octets in the filler, as described in section 4.2.4. 
 | ||
|     
 | ||
|    In Wrap tokens without confidentiality, the EC field is used to 
 | ||
|    encode the number of octets in the trailing checksum, as described 
 | ||
|    in section 4.2.4.   
 | ||
|  
 | ||
| 4.2.4. Encryption and Checksum Operations 
 | ||
|     
 | ||
|    The encryption algorithms defined by the crypto profiles provide for 
 | ||
|    integrity protection [KCRYPTO].  Therefore no separate checksum is 
 | ||
|    needed.  
 | ||
|     
 | ||
|    The result of decryption can be longer than the original plaintext 
 | ||
|    [KCRYPTO] and the extra trailing octets are called "crypto-system 
 | ||
|    garbage".  However, given the size of any plaintext data, one can 
 | ||
|    always find the next (possibly larger) size so that, when padding 
 | ||
| 
 | ||
| 
 | ||
| Zhu                         Internet Draft                           7 
 | ||
|                  Kerberos Version 5 GSS-API      November 2003 
 | ||
|  
 | ||
|  
 | ||
|    the to-be-encrypted text to that size, there will be no crypto-
 | ||
|    system garbage added [KCRYPTO].  
 | ||
|  
 | ||
|    In Wrap tokens that provide for confidentiality, the first 16 octets 
 | ||
|    of the Wrap token (the "header", as defined in section 4.2.6), are 
 | ||
|    appended to the plaintext data before encryption.  Filler octets can 
 | ||
|    be inserted between the plaintext data and the "header", and the 
 | ||
|    values and size of the filler octets are chosen by implementations, 
 | ||
|    such that there is no crypto-system garbage present after the 
 | ||
|    decryption.  The resulting Wrap token is {"header" | 
 | ||
|    encrypt(plaintext-data | filler | "header")}, where encrypt() is the 
 | ||
|    encryption operation (which provides for integrity protection) 
 | ||
|    defined in the crypto profile [KCRYPTO], and the RRC field in the 
 | ||
|    to-be-encrypted header contains the hex value 00 00.   
 | ||
|            
 | ||
|    In Wrap tokens that do not provide for confidentiality, the checksum 
 | ||
|    is calculated first over the to-be-signed plaintext data, and then 
 | ||
|    the first 16 octets of the Wrap token (the "header", as defined in 
 | ||
|    section 4.2.6).  Both the EC field and the RRC field in the token 
 | ||
|    header are filled with zeroes for the purpose of calculating the 
 | ||
|    checksum.  The resulting Wrap token is {"header" | plaintext-data | 
 | ||
|    get_mic(plaintext-data | "header")},  where get_mic() is the 
 | ||
|    checksum operation for the required checksum mechanism of the chosen 
 | ||
|    encryption mechanism defined in the crypto profile [KCRYPTO].  
 | ||
|     
 | ||
|    The parameters for the key and the cipher-state in the encrypt() and 
 | ||
|    get_mic() operations have been omitted for brevity.   
 | ||
|         
 | ||
|    For MIC tokens, the checksum is first calculated over the to-be-
 | ||
|    signed plaintext data, and then the first 16 octets of the MIC 
 | ||
|    token, where the checksum mechanism is the required checksum 
 | ||
|    mechanism of the chosen encryption mechanism defined in the crypto 
 | ||
|    profile [KCRYPTO]. 
 | ||
|    
 | ||
|    The resulting Wrap and MIC tokens bind the data to the token header, 
 | ||
|    including the sequence number and the direction indicator.  
 | ||
|    
 | ||
| 4.2.5. RRC Field 
 | ||
|  
 | ||
|    The "RRC" (Right Rotation Count) field in Wrap tokens is added to 
 | ||
|    allow the data to be encrypted in-place by existing [SSPI] 
 | ||
|    applications that do not provide an additional buffer for the 
 | ||
|    trailer (the cipher text after the in-place-encrypted data) in 
 | ||
|    addition to the buffer for the header (the cipher text before the 
 | ||
|    in-place-encrypted data).  The resulting Wrap token in the previous 
 | ||
|    section, excluding the first 16 octets of the token header, is 
 | ||
|    rotated to the right by "RRC" octets.  The net result is that "RRC" 
 | ||
|    octets of trailing octets are moved toward the header.  Consider the 
 | ||
|    following as an example of this rotation operation:  Assume that the 
 | ||
|    RRC value is 3 and the token before the rotation is {"header" | aa | 
 | ||
|    bb | cc | dd | ee | ff | gg | hh}, the token after rotation would be 
 | ||
|    {"header" | ff | gg | hh | aa | bb | cc | dd | ee }, where {aa | bb 
 | ||
|    | cc |...| hh} is used to indicate the octet sequence. 
 | ||
|   
 | ||
| 
 | ||
| Zhu                         Internet Draft                           8 
 | ||
|                  Kerberos Version 5 GSS-API      November 2003 
 | ||
|  
 | ||
|  
 | ||
|    The RRC field is expressed as a two-octet integer in big endian 
 | ||
|    order. 
 | ||
|     
 | ||
|    The rotation count value is chosen by the sender based on 
 | ||
|    implementation details, and the receiver MUST be able to interpret 
 | ||
|    all possible rotation count values. 
 | ||
|  
 | ||
| 4.2.6. Message Layouts 
 | ||
|     
 | ||
|    Per-message tokens start with a two-octet token identifier (TOK_ID) 
 | ||
|    field, expressed in big endian order.  These tokens are defined 
 | ||
|    separately in subsequent sub-sections. 
 | ||
|     
 | ||
| 4.2.6.1. MIC Tokens 
 | ||
|     
 | ||
|    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: 
 | ||
|     
 | ||
|       Octet no     Name       Description 
 | ||
|       ----------------------------------------------------------------- 
 | ||
|        0..1     TOK_ID     Identification field.  Tokens emitted by  
 | ||
|                            GSS_GetMIC() contain the hex value 04 04  
 | ||
|                            expressed in big endian order in this field. 
 | ||
|        2        Flags      Attributes field, as described in section  
 | ||
|                            4.2.2. 
 | ||
|        3..7     Filler     Contains five octets of hex value FF. 
 | ||
|        8..15    SND_SEQ    Sequence number field in clear text,  
 | ||
|                            expressed in big endian order.  
 | ||
|        16..last SGN_CKSUM  Checksum of octet 0..15 and the "to-be- 
 | ||
|                            signed" data, as described in section 4.2.4. 
 | ||
|     
 | ||
|    The Filler field is included in the checksum calculation for 
 | ||
|    simplicity.   
 | ||
|     
 | ||
| 4.2.6.2. Wrap Tokens 
 | ||
|     
 | ||
|    Use of the GSS_Wrap() call yields a token, which consists of a 
 | ||
|    descriptive header, followed by a body portion that contains either 
 | ||
|    the input user data in plaintext concatenated with the checksum, or 
 | ||
|    the input user data encrypted.  The GSS_Wrap() token has the 
 | ||
|    following format: 
 | ||
|     
 | ||
|       Octet no     Name       Description 
 | ||
|       --------------------------------------------------------------- 
 | ||
|        0..1     TOK_ID     Identification field.  Tokens emitted by  
 | ||
|                            GSS_Wrap() contain the the hex value 05 04                 
 | ||
|                            expressed in big endian order in this field. 
 | ||
|        2        Flags      Attributes field, as described in section  
 | ||
|                            4.2.2. 
 | ||
|        3        Filler     Contains the hex value FF. 
 | ||
|        4..5     EC         Contains the "extra count" field, in big  
 | ||
|                            endian order as described in section 4.2.3. 
 | ||
|        6..7     RRC        Contains the "right rotation count" in big  
 | ||
| 
 | ||
| 
 | ||
| Zhu                         Internet Draft                           9 
 | ||
|                  Kerberos Version 5 GSS-API      November 2003 
 | ||
|  
 | ||
|  
 | ||
|                            endian order, as described in section 4.2.5. 
 | ||
|        8..15    SND_SEQ    Sequence number field in clear text, 
 | ||
|                            expressed in big endian order. 
 | ||
|        16..last Data       Encrypted data for Wrap tokens with  
 | ||
|                            confidentiality, or plaintext data followed  
 | ||
|                            by the checksum for Wrap tokens without  
 | ||
|                            confidentiality, as described in section  
 | ||
|                            4.2.4.         
 | ||
|              
 | ||
| 4.3. Context Deletion Tokens 
 | ||
|  
 | ||
|    Context deletion tokens are empty in this mechanism.  Both peers to 
 | ||
|    a security context invoke GSS_Delete_sec_context() [RFC-2743] 
 | ||
|    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. 
 | ||
|         
 | ||
| 4.4. Token Identifier Assignment Considerations 
 | ||
|     
 | ||
|    Token identifiers (TOK_ID) from 0x60 0x00 through 0x60 0xFF 
 | ||
|    inclusive are reserved and SHALL NOT be assigned.  Thus by examining 
 | ||
|    the first two octets of a token, one can tell unambiguously if it is 
 | ||
|    wrapped with the generic GSS-API token framing.   
 | ||
|     
 | ||
| 5. 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-2744]. 
 | ||
|     
 | ||
| 5.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 implementers 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.  
 | ||
|     
 | ||
| 5.1.1. Non-Kerberos-specific codes 
 | ||
| 
 | ||
| 
 | ||
| Zhu                         Internet Draft                          10 
 | ||
|                  Kerberos Version 5 GSS-API      November 2003 
 | ||
|  
 | ||
|  
 | ||
|  
 | ||
|       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" */ 
 | ||
|     
 | ||
| 5.1.2. Kerberos-specific-codes 
 | ||
|     
 | ||
|       GSS_KRB5_S_KG_CCACHE_NOMATCH  
 | ||
|               /* "Client principal in credentials does not match   
 | ||
|                  specified name" */ 
 | ||
|       GSS_KRB5_S_KG_KEYTAB_NOMATCH 
 | ||
|               /* "No key available for specified service principal" */ 
 | ||
|       GSS_KRB5_S_KG_TGT_MISSING 
 | ||
|               /* "No Kerberos ticket-granting ticket available" */ 
 | ||
|       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" */ 
 | ||
|  
 | ||
| 5.2. Buffer Sizes 
 | ||
|  
 | ||
|    All implementations of this specification shall be capable of 
 | ||
|    accepting buffers of at least 16K octets 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 16K octet input 
 | ||
|    buffer as input to GSS_Unwrap().  Support for larger buffer sizes is 
 | ||
|    optional but recommended. 
 | ||
|  
 | ||
| 6. Backwards Compatibility Considerations 
 | ||
|  
 | ||
|    The new token formats defined in this document will only be 
 | ||
|    recognized by new implementations.  To address this, implementations 
 | ||
|    can always use the explicit sign or seal algorithm in [RFC-1964] 
 | ||
| 
 | ||
| 
 | ||
| Zhu                         Internet Draft                          11 
 | ||
|                  Kerberos Version 5 GSS-API      November 2003 
 | ||
|  
 | ||
|  
 | ||
|    when the key type corresponds to "older" enctypes.  An alternative 
 | ||
|    approach might be to retry sending the message with the sign or seal 
 | ||
|    algorithm explicitly defined as in [RFC-1964].  However this would 
 | ||
|    require either the use of a mechanism such as [RFC-2478] to securely 
 | ||
|    negotiate the method or the use out of band mechanism to choose 
 | ||
|    appropriate mechanism.  For this reason, it is RECOMMENDED that the 
 | ||
|    new token formats defined in this document SHOULD be used only if 
 | ||
|    both peers are known to support the new mechanism during context 
 | ||
|    negotiation because of, for example, the use of "new" enctypes. 
 | ||
|  
 | ||
|    GSS_Unwrap() or GSS_Verify_MIC() can process a message token as 
 | ||
|    follows: it can look at the first octet of the token header, if it 
 | ||
|    is 0x60 then the token must carry the generic GSS-API pseudo ASN.1 
 | ||
|    framing, otherwise the first two octets of the token contain the 
 | ||
|    TOK_ID that uniquely identify the token message format. 
 | ||
|     
 | ||
| 7. Security Considerations 
 | ||
|     
 | ||
|    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 given the task of 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 (for example) AES [AES-KRB5] but the Kerberos 
 | ||
|    implementation does.  It means that AES session keys cannot be 
 | ||
|    issued for that service principal, which keeps the protection of 
 | ||
|    non-GSSAPI services weaker than necessary.  KDC administrators 
 | ||
|    desiring to limit the session key types to support interoperability 
 | ||
|    with such GSSAPI implementations should carefully weigh the 
 | ||
|    reduction in protection offered by such mechanisms against the 
 | ||
|    benefits of interoperability. 
 | ||
|     
 | ||
| 8. Acknowledgments 
 | ||
|  
 | ||
|   Ken Raeburn and Nicolas Williams corrected many of our errors in the 
 | ||
|   use of generic profiles and were instrumental in the creation of this 
 | ||
|   memo.  
 | ||
|    
 | ||
|   The text for security considerations was contributed by Ken Raeburn. 
 | ||
|    
 | ||
|   Sam Hartman and Ken Raeburn suggested the "floating trailer" idea, 
 | ||
|   namely the encoding of the RRC field.   
 | ||
|    
 | ||
|   Sam Hartman and Nicolas Williams recommended the replacing our 
 | ||
|   earlier key derivation function for directional keys with different 
 | ||
| 
 | ||
| 
 | ||
| Zhu                         Internet Draft                          12 
 | ||
|                  Kerberos Version 5 GSS-API      November 2003 
 | ||
|  
 | ||
|  
 | ||
|   key usage numbers for each direction as well as retaining the 
 | ||
|   directional bit for maximum compatibility.   
 | ||
|    
 | ||
|   Paul Leach provided numerous suggestions and comments.  
 | ||
|    
 | ||
|   Scott Field, Richard Ward, Dan Simon, and Kevin Damour also provided 
 | ||
|   valuable inputs on this memo. 
 | ||
|    
 | ||
|   Jeffrey Hutzelman provided comments on channel bindings and suggested 
 | ||
|   many editorial changes. 
 | ||
|  
 | ||
|   Luke Howard provided implementations of this memo for the Heimdal 
 | ||
|   code base, and helped inter-operability testing with the Microsoft 
 | ||
|   code base, together with Love Hornquist Astrand.  These experiments 
 | ||
|   formed the basis of this memo. 
 | ||
|    
 | ||
|   Martin Rex provided suggestions of TOK_ID assignment recommendations 
 | ||
|   thus the token tagging in this memo is unambiguous if the token is 
 | ||
|   wrapped with the pseudo ASN.1 header.  
 | ||
|    
 | ||
|   This document retains some of the text of RFC-1964 in relevant 
 | ||
|   sections. 
 | ||
|    
 | ||
| 9. References 
 | ||
|     
 | ||
| 9.1. Normative References 
 | ||
|     
 | ||
|    [RFC-2026] Bradner, S., "The Internet Standards Process -- Revision 
 | ||
|    3", BCP 9, RFC 2026, October 1996.  
 | ||
|         
 | ||
|    [RFC-2119] Bradner, S., "Key words for use in RFCs to Indicate 
 | ||
|    Requirement Levels", BCP 14, RFC 2119, March 1997. 
 | ||
|     
 | ||
|    [RFC-2743] Linn, J., "Generic Security Service Application Program    
 | ||
|    Interface Version 2, Update 1", RFC 2743, January 2000. 
 | ||
|     
 | ||
|    [RFC-2744] Wray, J., "Generic Security Service API Version 2: C-
 | ||
|    bindings", RFC 2744, January 2000. 
 | ||
|     
 | ||
|    [RFC-1964] Linn, J., "The Kerberos Version 5 GSS-API Mechanism",    
 | ||
|    RFC 1964, June 1996. 
 | ||
|     
 | ||
|    [KCRYPTO] Raeburn, K., "Encryption and Checksum Specifications for 
 | ||
|    Kerberos 5", draft-ietf-krb-wg-crypto-05.txt, June, 2003.  Work in 
 | ||
|    progress.  
 | ||
|     
 | ||
|    [KRBCLAR] Neuman, C., Kohl, J., Ts'o T., Yu T., Hartman, S.,    
 | ||
|    Raeburn, K., "The Kerberos Network Authentication Service (V5)",    
 | ||
|    draft-ietf-krb-wg-kerberos-clarifications-04.txt, February 2002. 
 | ||
|    Work in progress. 
 | ||
|     
 | ||
|    [AES-KRB5] Raeburn, K., "AES Encryption for Kerberos 5", draft-
 | ||
|    raeburn-krb-rijndael-krb-05.txt, June 2003.  Work in progress. 
 | ||
| 
 | ||
|  
 | ||
| Zhu                         Internet Draft                          13 
 | ||
|                  Kerberos Version 5 GSS-API      November 2003 
 | ||
|  
 | ||
|  
 | ||
|     
 | ||
|    [RFC-2478] Baize, E., Pinkas D., "The Simple and Protected GSS-API 
 | ||
|    Negotiation Mechanism", RFC 2478, December 1998. 
 | ||
|  
 | ||
| 9.2. Informative References 
 | ||
|  
 | ||
|    [SSPI] Leach, P., "Security Service Provider Interface", Microsoft 
 | ||
|    Developer Network (MSDN), April 2003. 
 | ||
|     
 | ||
| 10. Author's Address 
 | ||
|     
 | ||
|    Larry Zhu 
 | ||
|    One Microsoft Way 
 | ||
|    Redmond, WA 98052 - USA 
 | ||
|    EMail: LZhu@microsoft.com 
 | ||
|  
 | ||
|    Karthik Jaganathan 
 | ||
|    One Microsoft Way 
 | ||
|    Redmond, WA 98052 - USA 
 | ||
|    EMail: karthikj@microsoft.com 
 | ||
|  
 | ||
|    Sam Hartman 
 | ||
|    Massachusetts Institute of Technology 
 | ||
|    77 Massachusetts Avenue 
 | ||
|    Cambridge, MA 02139 - USA 
 | ||
|    Email: hartmans@MIT.EDU 
 | ||
|     
 | ||
|     
 | ||
| 
 | ||
| 
 | ||
| 
 | ||
| 
 | ||
| 
 | ||
| 
 | ||
| 
 | ||
| 
 | ||
| 
 | ||
| 
 | ||
| 
 | ||
| 
 | ||
| 
 | ||
| 
 | ||
| 
 | ||
| 
 | ||
| 
 | ||
| 
 | ||
| 
 | ||
| 
 | ||
| 
 | ||
| 
 | ||
| 
 | ||
| 
 | ||
| Zhu                         Internet Draft                          14 
 | ||
|                  Kerberos Version 5 GSS-API      November 2003 
 | ||
|  
 | ||
|  
 | ||
|     
 | ||
| Full Copyright Statement 
 | ||
|     
 | ||
|    Copyright (C) The Internet Society (date). 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. 
 | ||
|     
 | ||
| 
 | ||
| 
 | ||
| 
 | ||
| 
 | ||
| 
 | ||
| 
 | ||
| 
 | ||
| 
 | ||
| 
 | ||
| 
 | ||
| 
 | ||
| 
 | ||
| 
 | ||
| 
 | ||
| 
 | ||
| 
 | ||
| 
 | ||
| 
 | ||
| 
 | ||
| 
 | ||
| 
 | ||
| 
 | ||
| 
 | ||
| 
 | ||
| 
 | ||
| Zhu                         Internet Draft                          15 
 |