Internet DRAFT - draft-galb-secsh-gssapi
draft-galb-secsh-gssapi
Network Working Group J. Galbraith
INTERNET-DRAFT J. Van Dyke
Expires September 2001 Van Dyke Technologies
V. Welch
University of Chicago
March 2001
SECSH GSS-API Authentication Method
< draft-galb-secsh-gssapi-01.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
SECSH is a protocol for secure remote login and other secure network
services over an insecure network.
GSSAPI is a general-purpose user authentication method based on
RFC 2743.
This document describes a method for encoding GSSAPI onto the model
described in the SECSH authentication protocol framework [SSH-AUTH].
1. Introduction
The SECSH GSSAPI authentication method is a general-purpose user
authentication method based on RFC 2743. It is intended to be run
over the SECSH userauth service layer protocol [SSH-AUTH].
This document should be read only after reading the SECSH
architecture document [SSH-ARCH] and the SECSH authentication
document [SSH-AUTH]. This document freely uses terminology and
notation from the architecture document without reference or further
explanation.
The authentication method name for this protocol is "gssapi".
When this method starts, it receives the server's host key from the
lower-level protocol.
2. 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.
2.1 SECSH terminology
The data types used in the packets are defined in the SECSH
architecture document [SSH-ARCH].
It is important to note the definition of string allows binary
content. Quoting from the architecture document:
string
Arbitrary length binary string. Strings are allowed to contain
arbitrary binary data, including null characters and 8-bit
characters. They are stored as a uint32 containing its length
(number of bytes that follow) and zero (= empty string) or more
bytes that are the value of the string. Terminating null
characters are not used.
The SSH_MSG_USERAUTH_REQUEST packet refers to a service; this
service name is a SECSH service name, and has no relationship
to GSSAPI service names. Currently, the only defined service
name is "ssh-connection", which refers to the SECSH connection
protocol [SSH-CONNECT].
3. GSSAPI Authentication Method
The GSSAPI authentication method defines four message identifiers:
SSH_MSG_USERAUTH_GSSAPI_RESPONSE 60
SSH_MSG_USERAUTH_GSSAPI_TOKEN 61
SSH_MSG_USERAUTH_GSSAPI_HASH 62
SSH_MSG_USERAUTH_GSSAPI_EXCHANGE_COMPLETE 63
3.1 Initiating GSSAPI authentication
The GSSAPI authentication method is initiated when the client
sends a SSH_MSG_USERAUTH_REQUEST:
byte SSH_MSG_USERAUTH_REQUEST
string username (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
The mechanism OIDs MUST be listed in order of preference, 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.
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 username may be an empty string if it can be deduced from the
results of the gssapi authentication. If the requested username is
not empty, and 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.
Mechanism OIDs are encoded as specified in RFC2743, section
3.1 item #5:
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).
3.1.1 SPNEGO
The use of the Simple and Protected GSS-API Negotiation Mechanism
[SPNEGO] in conjunction with the gssapi algorithm method described
in this document is both unnecessary and undesirable. As a result,
authentication mechanisms conforming to this document MUST NOT use
SPNEGO as the underlying GSSAPI mechanism.
Since SSH performs its own negotiation of authentication methods,
and this mechanism provides a method to negotiate the gssapi
mechanism to be used, 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. SECSH already provides a secure, integrity
checked layer which this authentication mechanism runs over. Thus,
the extra level of protection offered by SPNEGO is unnecessary in
this case.
The use of SPNEGO combined with GSSAPI mechanisms used without
SPNEGO can lead to interoperability problems. For example, a client
which supports authentication using the Kerberos V5 GSSAPI mechanism
[KRB5-GSS] only underneath SPNEGO will not interoperate with a server
which supports authentication 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 authentication
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 authentication methods.
3.2 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.3 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 library.
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 server ends the GSSAPI session by sending a
SSH_MSG_USERAUTH_GSSAPI_HASH packet (see below.)
The client MAY use the deleg_req_flag in calls to GSS_Init_sec_context()
to request credential delegation.
The mutual_req_flag MUST be specified in order for the GSS_GetMIC()
to provide additional security (see Section 3.4)
The client MUST use the integ_req_flag, since GSS_GetMIC() and
GSS_VerifyMIC() will be used (see Section 3.4)
The authentication MUST fail if GSS_S_COMPLETE is returned
and either the mutual_state or integ avail flags are not
true.
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.
The service name to be used in calling GSS_Init_sec_context()
is a GSSAPI host-based service name, generated by calling
GSS_Import_name() with type GSS_C_NT_HOSTBASED_SERVICE
and the string 'host@foo.bar' where host is the literal
string 'host' and foo.bar is the fully-qualified hostname.
For example, to connect to a host myserver.mydomain.com,
the name 'host@myserver.mydomain.com' would be used.
3.4 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 and both the mutual_state and integ_avail flags
are true.
If GSS_Init_sec_context() failed, or mutual_state or integ_avail were
not true, the client MUST terminate the method by sending a new
SSH_MSG_USERAUTH_REQUEST.
3.5 Increasing confidence in host key authenticity
In order to provide stronger authentication of the host key, the
server MUST send an SSH_MSG_USERAUTH_GSSAPI_HASH packet as soon as
the server receives the SSH_MSG_USERAUTH_GSSAPI_EXCHANGE_COMPLETE
packet.
byte SSH_MSG_USERAUTH_GSSAPI_HASH
string output of GSS_GetMIC() applied to the session id.
This allows the client to verify the session id sent earlier
during key exchange, which, if successful, implies that the
host key sent during key exchange was authentic. This can
prevent a man-in-the-middle attack in situations where the
server's host key is unknown to the client.
If the GSS_VerifyMIC() function fails to verify the session id,
the client MUST disconnect from the server by sending a
SSH_DISCONNECT_HOST_KEY_NOT_VERIFIABLE message.
If the client fails to receive a SSH_MSG_USERAUTH_GSSAPI_HASH
message it MUST disconnect with SSH_DISCONNECT_PROTOCOL_ERROR.
3.6 Completion
As with all SECSH 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 the
SSH_MSG_USERAUTH_GSSAPI_HASH packet.
4. References
[SSH-ARCH] Ylonen, T., et al, "SSH Protocol Architecture", Internet
Draft, draft-secsh-architecture-07.txt
[SSH-TRANS] Ylonen, T., et al, "SSH Transport Layer Protocol",
Internet Draft, draft-secsh-transport-09.txt
[SSH-USERAUTH] Ylonen, T., et al, "SSH Authentication Protocol",
Internet Draft, draft-ietf-secsh-userauth-09.txt
[SSH-CONNECT] Ylonen, T., et al, "SSH Connection Protocol", Internet
Draft, draft-secsh-connect-09.txt
[RFC-2743] Linn, J., "Generic Security Service Application Program
Interface, Version 2, Update 1", January 2000.
[RFC-2279] Yergeau, F., "UTF-8, a Transformation Format of Unicode
and ISO 10646", October 1996.
5. Authors addresses
Joseph Galbraith
Van Dyke Technologies, Inc.
4848 Tramway Ridge Dr. NE
Suite 101
Albuquerque, NM 87111
USA
E-mail: galb@vandyke.com
Jeff Van Dyke
Van Dyke Technologies, Inc.
4848 Tramway Ridge Dr. NE
Suite 101
Albuquerque, NM 87111
USA
E-mail: jpv@vandyke.com
Von Welch
Distributed Systems Laboratory
University of Chicago & Argonne National Laboratory
701 E. Washington
Urbana, IL 61801
USA
E-mail: welch@mcs.anl.gov
This draft expires September 2001.
