diff options
Diffstat (limited to 'doc/draft-ietf-secsh-gsskeyex-06.txt')
| -rw-r--r-- | doc/draft-ietf-secsh-gsskeyex-06.txt | 1509 |
1 files changed, 1509 insertions, 0 deletions
diff --git a/doc/draft-ietf-secsh-gsskeyex-06.txt b/doc/draft-ietf-secsh-gsskeyex-06.txt new file mode 100644 index 0000000..da44257 --- /dev/null +++ b/doc/draft-ietf-secsh-gsskeyex-06.txt @@ -0,0 +1,1509 @@ + + +Network Working Group J. Hutzelman +Internet-Draft CMU +Expires: August 31, 2003 J. Salowey + Cisco Systems + J. Galbraith + Van Dyke Technologies, Inc. + V. Welch + U Chicago / ANL + March 2, 2003 + + + GSSAPI Authentication and Key Exchange for the Secure Shell Protocol + draft-ietf-secsh-gsskeyex-06 + +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 Internet-Draft will expire on August 31, 2003. + +Copyright Notice + + Copyright (C) The Internet Society (2003). All Rights Reserved. + +Abstract + + The Secure Shell protocol (SSH) is a protocol for secure remote + login and other secure network services over an insecure network. + + The Generic Security Service Application Program Interface (GSS-API) + [2] provides security services to callers in a mechanism-independent + fashion. + + + +Hutzelman, et. al. Expires August 31, 2003 [Page 1] + +Internet-Draft SSH GSSAPI Methods March 2003 + + + This memo describes methods for using the GSS-API for authentication + and key exchange in SSH. It defines an SSH user authentication + method which uses a specified GSSAPI mechanism to authenticate a + user, and a family of SSH key exchange methods which use GSSAPI to + authenticate the Diffie-Hellman exchange described in [8]. + + This memo also defines a new host public key algorithm which can be + used when no operations are needed using a host's public key, and a + new user authentication method which allows an authorization name to + be used in conjunction with any authentication which has already + occurred as a side-effect of key exchange. + + 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 [5]. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Hutzelman, et. al. Expires August 31, 2003 [Page 2] + +Internet-Draft SSH GSSAPI Methods March 2003 + + +1. Introduction + + This document describes the methods used to perform key exchange and + user authentication in the Secure Shell protocol using the GSSAPI. + To do this, it defines a family of key exchange methods, two user + authentication methods, and a new host key algorithm. These + definitions allow any GSSAPI mechanism to be used with the Secure + Shell protocol. + + This document should be read only after reading the documents + describing the SSH protocol architecture [6], transport layer + protocol [8], and user authentication protocol [9]. This document + freely uses terminology and notation from the architecture document + without reference or further explanation. + +1.1 SSH terminology + + The data types used in the packets are defined in the SSH + architecture document [6]. It is particularly important to note the + definition of string allows binary content. + + The SSH_MSG_USERAUTH_REQUEST packet refers to a service; this + service name is an SSH service name, and has no relationship to + GSSAPI service names. Currently, the only defined service name is + "ssh-connection", which refers to the SSH connection protocol [7]. + + + + + + + + + + + + + + + + + + + + + + + + + + +Hutzelman, et. al. Expires August 31, 2003 [Page 3] + +Internet-Draft SSH GSSAPI Methods March 2003 + + +2. GSSAPI Authenticated Diffie-Hellman Key Exchange + + This section defines a class of key exchange methods which combine + the Diffie-Hellman key exchange from section 6 of [8] with mutual + authentication using GSSAPI. + + Since the GSSAPI key exchange methods described in this section do + not require the use of public key signature or encryption + algorithms, they MAY be used with any host key algorithm, including + the "null" algorithm described in Section 5. + +2.1 Generic GSSAPI Key Exchange + + The following symbols are used in this description: + + o C is the client, and S is the server + + o p is a large safe prime, g is a generator for a subgroup of + GF(p), and q is the order of the subgroup + + o V_S is S's version string, and V_C is C's version string + + o I_C is C's KEXINIT message, and I_S is S's KEXINIT message + + 1. C generates a random number x (1 < x < q) and computes e = g^x + mod p. + + 2. C calls GSS_Init_sec_context, using the most recent reply token + received from S during this exchange, if any. For this call, + the client MUST set the mutual_req_flag to "true" to request + that mutual authentication be performed. It also MUST set the + integ_req_flag to "true" to request that per-message integrity + protection be supported for this context. In addition, the + deleg_req_flag MAY be set to "true" to request access + delegation, if requested by the user. Since the key exchange + process authenticates only the host, the setting of the + anon_req_flag is immaterial to this process. If the client does + not support the "external-keyx" user authentication method + described in Section 4, or does not intend to use that method, + then the anon_req_flag SHOULD be set to "true". Otherwise, this + flag MAY be set to true if the client wishes to hide its + identity. + + * If the resulting major_status code is GSS_S_COMPLETE and the + mutual_state flag is not true, then mutual authentication has + not been established, and the key exchange MUST fail. + + * If the resulting major_status code is GSS_S_COMPLETE and the + integ_avail flag is not true, then per-message integrity + + +Hutzelman, et. al. Expires August 31, 2003 [Page 4] + +Internet-Draft SSH GSSAPI Methods March 2003 + + + protection is not available, and the key exchange MUST fail. + + * If the resulting major_status code is GSS_S_COMPLETE and both + the mutual_state and integ_avail flags are true, the + resulting output token is sent to S. + + * If the resulting major_status code is GSS_S_CONTINUE_NEEDED, + the the output_token is sent to S, which will reply with a + new token to be provided to GSS_Init_sec_context. + + * The client MUST also include "e" with the first message it + sends to the server during this process; if the server + receives more than one "e" or none at all, the key exchange + fails. + + * It is an error if the call does not produce a token of + non-zero length to be sent to the server. In this case, the + key exchange MUST fail. + + 3. S calls GSS_Accept_sec_context, using the token received from C. + + * If the resulting major_status code is GSS_S_COMPLETE and the + mutual_state flag is not true, then mutual authentication has + not been established, and the key exchange MUST fail. + + * If the resulting major_status code is GSS_S_COMPLETE and the + integ_avail flag is not true, then per-message integrity + protection is not available, and the key exchange MUST fail. + + * If the resulting major_status code is GSS_S_COMPLETE and both + the mutual_state and integ_avail flags are true, then the + security context has been established, and processing + continues with step 4. + + * If the resulting major_status code is GSS_S_CONTINUE_NEEDED, + then the output token is sent to C, and processing continues + with step 2. + + * If the resulting major_status code is GSS_S_COMPLETE, but a + non-zero-length reply token is returned, then that token is + sent to the client. + + 4. S generates a random number y (0 < y < q) and computes f = g^y + mod p. It computes K = e ^ y mod p, and H = hash(V_C || V_S || + I_C || I_S || K_S || e || f || K). It then calls GSS_GetMIC to + obtain a GSSAPI message integrity code for H. S then sends f + and the MIC to C. + + 5. This step is performed only if the server's final call to + + +Hutzelman, et. al. Expires August 31, 2003 [Page 5] + +Internet-Draft SSH GSSAPI Methods March 2003 + + + GSS_Accept_sec_context produced a non-zero-length final reply + token to be sent to the client _and_ no previous call by the + client to GSS_Init_sec_context has resulted in a major_status of + GSS_S_COMPLETE. Under these conditions, the client makes an + additional call to GSS_Init_sec_context to process the final + reply token. This call is made exactly as described above. + However, if the resulting major_status is anything other than + GSS_S_COMPLETE, or a non-zero-length token is returned, it is an + error and the key exchange MUST fail. + + 6. C computes K = f^x mod p, and H = hash(V_C || V_S || I_C || I_S + || K_S || e || f || K). It then calls GSS_VerifyMIC to verify + that the MIC sent by S matches H. + + Either side MUST NOT send or accept e or f values that are not in + the range [1, p-1]. If this condition is violated, the key exchange + fails. + + If any call to GSS_Init_sec_context or GSS_Accept_sec_context + returns a major_status other than GSS_S_COMPLETE or + GSS_S_CONTINUE_NEEDED, or any other GSSAPI call returns a + major_status other than GSS_S_COMPLETE, the key exchange fails. In + this case, several mechanisms are available for communicating error + information to the peer before terminating the connection as + required by [8]: + + o If the key exchange fails due to any GSSAPI error on the server + (including errors returned by GSS_Accept_sec_context), the server + MAY send a message informing the client of the details of the + error. In this case, if an error token is also sent (see below), + then this message MUST be sent before the error token. + + o If the key exchange fails due to a GSSAPI error returned from the + server's call to GSS_Accept_sec_context, and an "error token" is + also returned, then the server SHOULD send the error token to the + client to allow completion of the GSS security exchange. + + o If the key exchange fails due to a GSSAPI error returned from the + client's call to GSS_Init_sec_context, and an "error token" is + also returned, then the client SHOULD send the error token to the + server to allow completion of the GSS security exchange. + + As noted in Section 9, it may be desirable under site security + policy to obscure information about the precise nature of the error; + thus, it is RECOMMENDED that implementations provide a method to + suppress these messages as a matter of policy. + + This is implemented with the following messages. The hash algorithm + for computing the exchange hash is defined by the method name, and + + +Hutzelman, et. al. Expires August 31, 2003 [Page 6] + +Internet-Draft SSH GSSAPI Methods March 2003 + + + is called HASH. The group used for Diffie-Hellman key exchange and + the underlying GSSAPI mechanism are also defined by the method name. + + After the client's first call to GSS_Init_sec_context, it sends the + following: + + byte SSH_MSG_KEXGSS_INIT + string output_token (from GSS_Init_sec_context) + mpint e + + Upon receiving the SSH_MSG_KEXGSS_INIT message, the server MAY send + the following message, prior to any other messages, to inform the + client of its host key. + + byte SSH_MSG_KEXGSS_HOSTKEY + string server public host key and certificates (K_S) + + Since this key exchange method does not require the host key to be + used for any encryption operations, this message is OPTIONAL. If + the "null" host key algorithm described in Section 5 is used, this + message MUST NOT be sent. If this message is sent, the server + public host key(s) and/or certificate(s) in this message are encoded + as a single string, in the format specified by the public key type + in use (see [8], section 4.6). + + Each time the server's call to GSS_Accept_sec_context returns a + major_status code of GSS_S_CONTINUE_NEEDED, it sends the following + reply to the client: + + byte SSH_MSG_KEXGSS_CONTINUE + string output_token (from GSS_Accept_sec_context) + + If the client receives this message after a call to + GSS_Init_sec_context has returned a major_status code of + GSS_S_COMPLETE, a protocol error has occurred and the key exchange + MUST fail. + + Each time the client receives the message described above, it makes + another call to GSS_Init_sec_context. It then sends the following: + + byte SSH_MSG_KEXGSS_CONTINUE + string output_token (from GSS_Init_sec_context) + + The server and client continue to trade these two messages as long + as the server's calls to GSS_Accept_sec_context result in + major_status codes of GSS_S_CONTINUE_NEEDED. When a call results in + a major_status code of GSS_S_COMPLETE, it sends one of two final + messages. + + + +Hutzelman, et. al. Expires August 31, 2003 [Page 7] + +Internet-Draft SSH GSSAPI Methods March 2003 + + + If the server's final call to GSS_Accept_sec_context (resulting in a + major_status code of GSS_S_COMPLETE) returns a non-zero-length token + to be sent to the client, it sends the following: + + byte SSH_MSG_KEXGSS_COMPLETE + mpint f + string per_msg_token (MIC of H) + boolean TRUE + string output_token (from GSS_Accept_sec_context) + + If the client receives this message after a call to + GSS_Init_sec_context has returned a major_status code of + GSS_S_COMPLETE, a protocol error has occurred and the key exchange + MUST fail. + + If the server's final call to GSS_Accept_sec_context (resulting in a + major_status code of GSS_S_COMPLETE) returns a zero-length token or + no token at all, it sends the following: + + byte SSH_MSG_KEXGSS_COMPLETE + mpint f + string per_msg_token (MIC of H) + boolean FALSE + + If the client receives this message when no call to + GSS_Init_sec_context has yet resulted in a major_status code of + GSS_S_COMPLETE, a protocol error has occurred and the key exchange + MUST fail. + + If either the client's call to GSS_Init_sec_context or the server's + call to GSS_Accept_sec_context returns an error status and produces + an output token (called an "error token"), then the following SHOULD + be sent to convey the error information to the peer: + + byte SSH_MSG_KEXGSS_CONTINUE + string error_token + + If a server sends both this message and an SSH_MSG_KEXGSS_ERROR + message, the SSH_MSG_KEXGSS_ERROR message MUST be sent first, to + allow clients to record and/or display the error information before + processing the error token. This is important because a client + processing an error token will likely disconnect without reading any + further messages. + + + + + + + + +Hutzelman, et. al. Expires August 31, 2003 [Page 8] + +Internet-Draft SSH GSSAPI Methods March 2003 + + + In the event of a GSSAPI error on the server, the server MAY send + the following message before terminating the connection: + + byte SSH_MSG_KEXGSS_ERROR + uint32 major_status + uint32 minor_status + string message + string language tag + + The message text MUST be encoded in the UTF-8 encoding described in + [10]. Language tags are those described in [11]. Note that the + message text may contain multiple lines separated by carriage + return-line feed (CRLF) sequences. Application developers should + take this into account when displaying these messages. + + The hash H is computed as the HASH hash of the concatenation of the + following: + + string V_C, the client's version string (CR and NL excluded) + string V_S, the server's version string (CR and NL excluded) + string I_C, the payload of the client's SSH_MSG_KEXINIT + string I_S, the payload of the server's SSH_MSG_KEXINIT + string K_S, the host key + mpint e, exchange value sent by the client + mpint f, exchange value sent by the server + mpint K, the shared secret + + This value is called the exchange hash, and it is used to + authenticate the key exchange. The exchange hash SHOULD be kept + secret. If no SSH_MSG_KEXGSS_HOSTKEY message has been sent by the + server or received by the client, then the empty string is used in + place of K_S when computing the exchange hash. + + The GSS_GetMIC call MUST be applied over H, not the original data. + +2.2 gss-group1-sha1-* + + Each of these methods specifies GSSAPI authenticated Diffie-Hellman + key exchange as described in Section 2.1 with SHA-1 as HASH, and the + group defined in section 6.1 of [8]. The method name for each + method is the concatenation of the string "gss-group1-sha1-" with + the Base64 encoding of the MD5 hash [3] of the ASN.1 DER encoding + [1] of the underlying GSSAPI mechanism's OID. Base64 encoding is + described in section 6.8 of [4]. + + Each and every such key exchange method is implicitly registered by + this specification. The IESG is considered to be the owner of all + such key exchange methods; this does NOT imply that the IESG is + considered to be the owner of the underlying GSSAPI mechanism. + + +Hutzelman, et. al. Expires August 31, 2003 [Page 9] + +Internet-Draft SSH GSSAPI Methods March 2003 + + +2.3 Other GSSAPI key exchange methods + + Key exchange method names starting with "gss-" are reserved for key + exchange methods which conform to this document; in particular, for + those methods which use the GSSAPI authenticated Diffie-Hellman key + exchange algorithm described in Section 2.1, including any future + methods which use different groups and/or hash functions. The + intent is that the names for any such future methods methods be + defined in a similar manner to that used in Section 2.2. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Hutzelman, et. al. Expires August 31, 2003 [Page 10] + +Internet-Draft SSH GSSAPI Methods March 2003 + + +3. GSSAPI User Authentication + + This section describes a general-purpose user authentication method + based on [2]. It is intended to be run over the SSH user + authentication protocol [9]. + + The authentication method name for this protocol is "gssapi". + +3.1 GSSAPI Authentication Overview + + GSSAPI authentication must maintain a context. Authentication + begins when the client sends a SSH_MSG_USERAUTH_REQUEST, which + specifies the mechanism OIDs the client supports. + + If the server supports any of the requested mechanism OIDs, the + server sends a SSH_MSG_USERAUTH_GSSAPI_RESPONSE message containing + the mechanism OID. + + After the client receives SSH_MSG_USERAUTH_GSSAPI_RESPONSE, the + client and server exchange SSH_MSG_USERAUTH_GSSAPI_TOKEN packets + until the authentication mechanism either succeeds or fails. + + If at any time during the exchange, the client sends a new + SSH_MSG_USERAUTH_REQUEST packet, the GSSAPI context is completely + discarded and destroyed, and any further GSSAPI authentication MUST + restart from the beginning. + +3.2 Initiating GSSAPI authentication + + The GSSAPI authentication method is initiated when the client sends + a SSH_MSG_USERAUTH_REQUEST: + + byte SSH_MSG_USERAUTH_REQUEST + string user name (in ISO-10646 UTF-8 encoding) + string service name (in US-ASCII) + string "gssapi" (US-ASCII method name) + uint32 n, the number of mechanism OIDs client supports + string[n] mechanism OIDs + + Mechanism OIDs are encoded according to the ASN.1 distinguished + encoding rules (DER), as described in [1] and in section 3.1 of [2]. + The mechanism OIDs MUST be listed in order of preference, and the + server must choose the first mechanism OID on the list that it + supports. + + The client SHOULD NOT send more then one gssapi mechanism OID unless + there are no non-GSSAPI authentication methods between the GSSAPI + mechanisms in the order of preference, otherwise, authentication + methods may be executed out of order. + + +Hutzelman, et. al. Expires August 31, 2003 [Page 11] + +Internet-Draft SSH GSSAPI Methods March 2003 + + + If the server does not support any of the specified OIDs, the server + MUST fail the request by sending a SSH_MSG_USERAUTH_FAILURE packet. + + The user name may be an empty string if it can be deduced from the + results of the gssapi authentication. If the user name is not + empty, and the requested user does not exist, the server MAY + disconnect, or MAY send a bogus list of acceptable authentications + but never accept any. This makes it possible for the server to + avoid disclosing information about which accounts exist. In any + case, if the user does not exist, the authentication request MUST + NOT be accepted. + + The client MAY at any time continue with a new + SSH_MSG_USERAUTH_REQUEST message, in which case the server MUST + abandon the previous authentication attempt and continue with the + new one. + +3.3 Initial server response + + The server responds to the SSH_MSG_USERAUTH_REQUEST with either a + SSH_MSG_USERAUTH_FAILURE if none of the mechanisms are supported, or + with SSH_MSG_USERAUTH_GSSAPI_RESPONSE as follows: + + byte SSH_MSG_USERAUTH_GSSAPI_RESPONSE + string selected mechanism OID + + The mechanism OID must be one of the OIDs sent by the client in the + SSH_MSG_USERAUTH_REQUEST packet. + +3.4 GSSAPI session + + Once the mechanism OID has been selected, the client will then + initiate an exchange of one or more pairs of + SSH_MSG_USERAUTH_GSSAPI_TOKEN packets. These packets contain the + tokens produced from the 'GSS_Init_sec_context()' and + 'GSS_Accept_sec_context()' calls. The actual number of packets + exchanged is determined by the underlying GSSAPI mechanism. + + byte SSH_MSG_USERAUTH_GSSAPI_TOKEN + string data returned from either GSS_Init_sec_context() + or GSS_Accept_sec_context() + + If an error occurs during this exchange on server side, the server + can terminate the method by sending a SSH_MSG_USERAUTH_FAILURE + packet. If an error occurs on client side, the client can terminate + the method by sending a new SSH_MSG_USERAUTH_REQUEST packet. + + The client MAY use the deleg_req_flag in calls to + GSS_Init_sec_context() to request credential delegation. + + +Hutzelman, et. al. Expires August 31, 2003 [Page 12] + +Internet-Draft SSH GSSAPI Methods March 2003 + + + Additional SSH_MSG_USERAUTH_GSSAPI_TOKEN messages are sent if and + only if the calls to the GSSAPI routines produce send tokens of + non-zero length. + + Any major status code other than GSS_S_COMPLETE or + GSS_S_CONTINUE_NEEDED SHOULD be a failure. + +3.5 Client acknowledgement + + It is possible for the server to successfully complete the GSSAPI + method and the client to fail. If the server simply assumed success + on the part of the client and completed the authentication service, + it is possible that the client would fail to complete the + authentication method, but not be able to retry other methods + because the server had already moved on. + + Therefore, the client MUST send the following message when it has + successfully called GSS_Init_sec_context() and gotten GSS_S_COMPLETE: + + byte SSH_MSG_USERAUTH_GSSAPI_EXCHANGE_COMPLETE + + This message MUST be sent if and only if GSS_Init_sec_context() + returned GSS_S_COMPLETE. If a token is returned then the + SSH_MSG_USERAUTH_GSSAPI_TOKEN message MUST be sent before this one. + + If GSS_Init_sec_context() failed, the client MUST terminate the + method by sending a new SSH_MSG_USERAUTH_REQUEST. or by closing the + connection + +3.6 Completion + + As with all SSH authentication methods, successful completion is + indicated by a SSH_MSG_USERAUTH_SUCCESS if no other authentication + is required, or a SSH_MSG_USERAUTH_FAILURE with the partial success + flag set if the server requires further authentication. + + This packet should be sent immediately following receipt of the the + SSH_MSG_USERAUTH_GSSAPI_EXCHANGE_COMPLETE packet. + + + + + + + + + + + + + +Hutzelman, et. al. Expires August 31, 2003 [Page 13] + +Internet-Draft SSH GSSAPI Methods March 2003 + + +3.7 Error Status + + In the event a GSSAPI error occurs on the server during context + establishment, the server MAY send the following message to inform + the client of the details of the error before sending a + SSH_MSG_USERAUTH_FAILURE message: + + byte SSH_MSG_USERAUTH_GSSAPI_ERROR + uint32 major_status + uint32 minor_status + string message + string language tag + + The message text MUST be encoded in the UTF-8 encoding described in + [10]. Language tags are those described in [11]. Note that the + message text may contain multiple lines separated by carriage + return-line feed (CRLF) sequences. Application developers should + take this into account when displaying these messages. + + Clients receiving this message MAY log the error details and/or + report them to the user. Any server sending this message MUST + ignore any SSH_MSG_UNIMPLEMENTED sent by the client in response. + +3.8 Error Token + + In the event that, during context establishment, a client's call to + GSS_Init_sec_context or a server's call to GSS_Accept_sec_context + returns a token along with an error status, the resulting "error + token" SHOULD be sent to the peer using the following message: + + byte SSH_MSG_USERAUTH_GSSAPI_ERRTOK + string error token + + This message implies that the authentication is about to fail, and + is defined to allow the error token to be communicated without + losing synchronization. + + When a server sends this message, it MUST be followed by a + SSH_MSG_USERAUTH_FAILURE message, which is to be interpreted as + applying to the same authentication request. A client receiving + this message SHOULD wait for the following SSH_MSG_USERAUTH_FAILURE + message before beginning another authentication attempt. + + When a client sends this message, it MUST be followed by a new + authentication request or by terminating the connection. A server + receiving this message MUST NOT send a SSH_MSG_USERAUTH_FAILURE in + reply, since such a message might otherwise be interpreted by a + client as a response to the following authentication sequence. + + + +Hutzelman, et. al. Expires August 31, 2003 [Page 14] + +Internet-Draft SSH GSSAPI Methods March 2003 + + + Any server sending this message MUST ignore any + SSH_MSG_UNIMPLEMENTED sent by the client in response. If a server + sends both this message and an SSH_MSG_USERAUTH_GSSAPI_ERROR + message, the SSH_MSG_USERAUTH_GSSAPI_ERROR message MUST be sent + first, to allow the client to store and/or display the error status + before processing the error token. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Hutzelman, et. al. Expires August 31, 2003 [Page 15] + +Internet-Draft SSH GSSAPI Methods March 2003 + + +4. External Key Exchange User Authentication + + This section describes a user authentication method building on the + framework described in [9]. This method relies upon the key + exchange to authenticate both the client and the server. If the key + exchange did not successfully perform these functions then the + server MUST always respond to this request with + SSH_MSG_USERAUTH_FAILURE with partial success set to false. + + The new mechanism is defined as follows: + + byte SSH_MSG_USERAUTH_REQUEST + string user name (in ISO-10646 UTF-8 encoding) + string service name (in US-ASCII) + string "external-keyx" (US-ASCII method name) + + If the authentication performed as part of key exchange can be used + to authorize login as the requested user, this method is successful, + and the server responds with SSH_MSG_USERAUTH_SUCCESS if no more + authentications are needed, or with SSH_MSG_USERAUTH_FAILURE with + partial success set to true if more authentications are needed. + + If the authentication performed as part of key-exchange cannot be + used to authorize login as the requested user, then + SSH_MSG_USERAUTH_FAILURE is returned with partial success set to + false. + + If the user name is not empty, and the requested user does not + exist, the server MAY disconnect, or MAY send a bogus list of + acceptable authentications but never accept any. This makes it + possible for the server to avoid disclosing information about which + accounts exist. In any case, if the user does not exist, the + authentication request MUST NOT be accepted. + + Any implementation supporting at least one key exchange method which + conforms to section 1 of this document SHOULD also support the + "external-keyx" user authentication method, in order to allow user + authentication to be performed at the same time as key exchange, + thereby reducing the number of round trips needed for connection + setup. + + + + + + + + + + + +Hutzelman, et. al. Expires August 31, 2003 [Page 16] + +Internet-Draft SSH GSSAPI Methods March 2003 + + +5. Null Host Key Algorithm + + The "null" host key algorithm has no associated host key material, + and provides neither signature nor encryption algorithms. Thus, it + can be used only with key exchange methods that do not require any + public-key operations and do not require the use of host public key + material. The key exchange methods described in section 1 of this + document are examples of such methods. + + This algorithm is used when, as a matter of configuration, the host + does not have or does not wish to use a public key. For example, it + can be used when the administrator has decided as a matter of policy + to require that all key exchanges be authenticated using Kerberos + [12], and thus the only permitted key exchange method is the + GSSAPI-authenticated Diffie-Hellman exchange described above, with + Kerberos V5 as the underlying GSSAPI mechanism. In such a + configuration, the server implementation supports the "ssh-dss" key + algorithm (as required by [8]), but could be prohibited by + configuration from using it. In this situation, the server needs + some key exchange algorithm to advertise; the "null" algorithm fills + this purpose. + + Note that the use of the "null" algorithm in this way means that the + server will not be able to interoperate with clients which do not + support this algorithm. This is not a significant problem, since in + the configuration described, it will also be unable to interoperate + with implementations that do not support the GSSAPI-authenticated + key exchange and Kerberos. + + Any implementation supporting at least one key exchange method which + conforms to section 1 of this document MUST also support the "null" + host key algorithm. Servers MUST NOT advertise the "null" host key + algorithm unless it is the only algorithm advertised. + + + + + + + + + + + + + + + + + + +Hutzelman, et. al. Expires August 31, 2003 [Page 17] + +Internet-Draft SSH GSSAPI Methods March 2003 + + +6. Summary of Message Numbers + + The following message numbers have been defined for use with + GSSAPI-based key exchange methods: + + #define SSH_MSG_KEXGSS_INIT 30 + #define SSH_MSG_KEXGSS_CONTINUE 31 + #define SSH_MSG_KEXGSS_COMPLETE 32 + #define SSH_MSG_KEXGSS_HOSTKEY 33 + #define SSH_MSG_KEXGSS_ERROR 34 + + The numbers 30-49 are specific to key exchange and may be redefined + by other kex methods. + + The following message numbers have been defined for use with the + 'gssapi' user authentication method: + + #define SSH_MSG_USERAUTH_GSSAPI_RESPONSE 60 + #define SSH_MSG_USERAUTH_GSSAPI_TOKEN 61 + #define SSH_MSG_USERAUTH_GSSAPI_EXCHANGE_COMPLETE 63 + #define SSH_MSG_USERAUTH_GSSAPI_ERROR 64 + + The numbers 60-79 are specific to user authentication and may be + redefined by other user auth methods. Note that in the method + described in this document, message number 62 is unused. + + + + + + + + + + + + + + + + + + + + + + + + + + +Hutzelman, et. al. Expires August 31, 2003 [Page 18] + +Internet-Draft SSH GSSAPI Methods March 2003 + + +7. GSSAPI Considerations + +7.1 Naming Conventions + + In order to establish a GSSAPI security context, the SSH client + needs to determine the appropriate targ_name to use in identifying + the server when calling GSS_Init_sec_context. For this purpose, the + GSSAPI mechanism-independent name form for host-based services is + used, as described in section 4.1 of [2]. + + In particular, the targ_name to pass to GSS_Init_sec_context is + obtained by calling GSS_Import_name with an input_name_type of + GSS_C_NT_HOSTBASED_SERVICE, and an input_name_string consisting of + the string "host@" concatenated with the hostname of the SSH server. + +7.2 Channel Bindings + + This document recommends that channel bindings SHOULD NOT be + specified in the calls during context establishment. This document + does not specify any standard data to be used as channel bindings + and the use of network addresses as channel bindings may break SSH + in environments where it is most useful. + +7.3 SPNEGO + + The use of the Simple and Protected GSS-API Negotiation Mechanism + [14] in conjunction with the authentication and key exchange methods + described in this document is both unnecessary and undesirable. As + a result, mechanisms conforming to this document MUST NOT use SPNEGO + as the underlying GSSAPI mechanism. + + Since SSH performs its own negotiation of authentication and key + exchange methods, the negotiation capability of SPNEGO alone does + not provide any added benefit. In fact, as described below, it has + the potential to result in the use of a weaker method than desired. + + Normally, SPNEGO provides the added benefit of protecting the GSSAPI + mechanism negotiation. It does this by having the server compute a + MIC of the list of mechanisms proposed by the client, and then + checking that value at the client. In the case of key exchange, + this protection is not needed because the key exchange methods + described here already perform an equivalent operation; namely, they + generate a MIC of the SSH exchange hash, which is a hash of several + items including the lists of key exchange mechanisms supported by + both sides. In the case of user authentication, the protection is + not needed because the negotiation occurs over a secure channel, and + the host's identity has already been proved to the user. + + The use of SPNEGO combined with GSSAPI mechanisms used without + + +Hutzelman, et. al. Expires August 31, 2003 [Page 19] + +Internet-Draft SSH GSSAPI Methods March 2003 + + + SPNEGO can lead to interoperability problems. For example, a client + which supports key exchange using the Kerberos V5 GSSAPI mechanism + [13] only underneath SPNEGO will not interoperate with a server + which supports key exchange only using the Kerberos V5 GSSAPI + mechanism directly. As a result, allowing GSSAPI mechanisms to be + used both with and without SPNEGO is undesirable. + + If a client's policy is to first prefer GSSAPI-based key exchange + method X, then non-GSSAPI method Y, then GSSAPI-based method Z, and + if a server supports mechanisms Y and Z but not X, then an attempt + to use SPNEGO to negotiate a GSSAPI mechanism might result in the + use of method Z when method Y would have been preferable. As a + result, the use of SPNEGO could result in the subversion of the + negotiation algorithm for key exchange methods as described in + section 5.1 of [8] and/or the negotiation algorithm for user + authentication methods as described in [9]. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Hutzelman, et. al. Expires August 31, 2003 [Page 20] + +Internet-Draft SSH GSSAPI Methods March 2003 + + +8. IANA Considerations + + Consistent with section 7 of [6], the IANA is directed to make the + following registrations: + + The family of SSH key exchange method names beginning with + "gss-group1-sha1-" and not containing the at-sign ('@'), to name + the key exchange methods defined in Section 2.2. + + All other SSH key exchange method names beginning with "gss-" and + not containing the at-sign ('@'), to be reserved for future key + exchange methods defined in conformance with this document, as + noted in Section 2.3. + + The SSH host public key algorithm name "null", to name the NULL + host key algorithm defined in Section 5. + + The SSH user authentication method name "gssapi", to name the + GSSAPI user authentication method defined in Section 3. + + The SSH user authentication method name "external-keyx", to name + the "external key-exchange" user authentication method defined in + Section 4. + + This document creates no new registries. + + + + + + + + + + + + + + + + + + + + + + + + + + +Hutzelman, et. al. Expires August 31, 2003 [Page 21] + +Internet-Draft SSH GSSAPI Methods March 2003 + + +9. Security Considerations + + This document describes authentication and key-exchange protocols. + As such, security considerations are discussed throughout. + + This protocol depends on the SSH protocol itself, the GSSAPI, any + underlying GSSAPI mechanisms which are used, and any protocols on + which such mechanisms might depend. Each of these components plays + a part in the security of the resulting connection, and each will + have its own security considerations. + + The key exchange method described in section 1 of this document + depends on the underlying GSSAPI mechanism to provide both mutual + authentication and per-message integrity services. If either of + these features is not supported by a particular GSSAPI mechanism, or + by a particular implementation of a GSSAPI mechanism, then the key + exchange is not secure and MUST fail. + + In order for the "external-keyx" user authentication method to be + used, it MUST have access to user authentication information + obtained as a side-effect of the key exchange. If this information + is unavailable, the authentication MUST fail. + + Revealing information about the reason for an authentication failure + may be considered by some sites to be an unacceptable security risk + for a production environment. However, having that information + available can be invaluable for debugging purposes. Thus, it is + RECOMMENDED that implementations provide a means for controlling, as + a matter of policy, whether to send SSH_MSG_USERAUTH_GSSAPI_ERROR, + SSH_MSG_USERAUTH_GSSAPI_ERRTOK, and SSH_MSG_KEXGSS_ERROR messages, + and SSH_MSG_KEXGEE_CONTINUE messages containing a GSSAPI error token. + + + + + + + + + + + + + + + + + + + + +Hutzelman, et. al. Expires August 31, 2003 [Page 22] + +Internet-Draft SSH GSSAPI Methods March 2003 + + +10. Acknowledgements + + The authors would like to thank Sam Hartman, Simon Wilkinson, and + Nicolas Williams for their invaluable assistance with this document. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Hutzelman, et. al. Expires August 31, 2003 [Page 23] + +Internet-Draft SSH GSSAPI Methods March 2003 + + +11. Changes the last version + + This section lists important changes since the previous version of + this internet-draft. This section should be removed at the time of + publication of this document as an RFC. + + o Improved the description of error handling during key exchange. + + o Specified that SSH_MSG_GSSKEX_CONTINUE SHOULD be used to send + error tokens in the event of a failure of GSS_Init_sec_context or + GSS_Accept_sec_context during key exchange. + + o Made SSH_MSG_GSSKEX_ERROR be OPTIONAL instead of RECOMMENDED. + + o Specified a new SSH_MSG_USERAUTH_GSSAPI_ERRTOK message which + SHOULD be used to send error tokens in the event of a failure of + GSS_Init_sec_context or GSS_Accept_sec_context during user + authentication. + + o Made SSH_MSG_USERAUTH_GSSAPI_ERROR be OPTIONAL instead of + RECOMMENDED. + + o Added IANA considerations section. + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Hutzelman, et. al. Expires August 31, 2003 [Page 24] + +Internet-Draft SSH GSSAPI Methods March 2003 + + +Normative References + + [1] ISO/IEC, "ASN.1 Encoding Rules: Specification of Basic + Encoding Rules (BER), Canonical Encoding Rules (CER) and + Distinguished Encoding Rules (DER)", ITU-T Recommendation + X.690 (1997), ISO/IEC 8825-1:1998, November 1998. + + [2] Linn, J., "Generic Security Service Application Program + Interface Version 2, Update 1", RFC 2743, January 2000. + + [3] Rivest, R., "The MD5 Message-Digest Algorithm", RFC 1321, + April 1992. + + [4] Freed, N. and N. Borenstein, "Multipurpose Internet Mail + Extensions (MIME) Part One: Format of Internet Message + Bodies", RFC 2045, November 1996. + + [5] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", RFC 2119, BCP 14, March 1997. + + [6] Ylonen, T., Kivinen, T., Saarinen, M., Rinne, T. and S. + Lehtinen, "SSH Protocol Architecture", + draft-ietf-secsh-architecture-11.txt (work in progress), + November 2001. + + [7] Ylonen, T., Kivinen, T., Saarinen, M., Rinne, T. and S. + Lehtinen, "SSH Connection Protocol", + draft-ietf-secsh-connect-14.txt (work in progress), November + 2001. + + [8] Ylonen, T., Kivinen, T., Saarinen, M., Rinne, T. and S. + Lehtinen, "SSH Transport Layer Protocol", + draft-ietf-secsh-transport-11.txt (work in progress), November + 2001. + + [9] Ylonen, T., Kivinen, T., Saarinen, M., Rinne, T. and S. + Lehtinen, "SSH Authentication Protocol", + draft-ietf-secsh-userauth-13.txt (work in progress), November + 2001. + + [10] Yergeau, F., "UTF-8, a transformation format of ISO 10646", + RFC 2279, January 1998. + + [11] Alvestrand, H., "Tags for the Identification of Languages", + RFC 1766, March 1995. + + + +Hutzelman, et. al. Expires August 31, 2003 [Page 25] + +Internet-Draft SSH GSSAPI Methods March 2003 + + +Non-normative References + + [12] Kohl, J. and C. Neuman, "The Kerberos Network Authentication + Service (V5)", RFC 1510, September 1993. + + [13] Linn, J., "The Kerberos Version 5 GSS-API Mechanism", RFC + 1964, June 1996. + + [14] Baize, E. and D. Pinkas, "The Simple and Protected GSS-API + Negotiation Mechanism", RFC 2478, December 1998. + + +Authors' Addresses + + Jeffrey Hutzelman + Carnegie Mellon University + 5000 Forbes Ave + Pittsburgh, PA 15213 + US + + Phone: +1 412 268 7225 + EMail: jhutz+@cmu.edu + URI: http://www.cs.cmu.edu/~jhutz/ + + + Joseph Salowey + Cisco Systems + 2901 Third Avenue + Seattle, WA 98121 + US + + Phone: +1 206 256 3380 + EMail: jsalowey@cisco.com + + + Joseph Galbraith + Van Dyke Technologies, Inc. + 4848 Tramway Ridge Dr. NE + Suite 101 + Albuquerque, NM 87111 + US + + EMail: galb@vandyke.com + + + Von Welch + University of Chicago & Argonne National Laboratory + Distributed Systems Laboratory + 701 E. Washington + Urbana, IL 61801 + US + + EMail: welch@mcs.anl.gov + + + +Hutzelman, et. al. Expires August 31, 2003 [Page 26] + +Internet-Draft SSH GSSAPI Methods March 2003 + + +Full Copyright Statement + + Copyright (C) The Internet Society (2003). 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. + + + + + + + + + + + + + + +Hutzelman, et. al. Expires August 31, 2003 [Page 27] + |