to illustrate structural relationships among token and tag objects.
For interoperability purposes, token and tag encoding shall be
performed using the concrete encoding procedures described earlier in
this subsection.
GSS-API DEFINITIONS ::=
BEGIN
MechType ::= OBJECT IDENTIFIER
-- data structure definitions
-- callers must be able to distinguish among
-- InitialContextToken, SubsequentContextToken,
-- PerMsgToken, and SealedMessage data elements
-- based on the usage in which they occur
InitialContextToken ::=
-- option indication (delegation, etc.) indicated within
-- mechanism-specific token
[APPLICATION 0] IMPLICIT SEQUENCE {
thisMech MechType,
innerContextToken ANY DEFINED BY thisMech
-- contents mechanism-specific
-- ASN.1 structure not required
}
SubsequentContextToken ::= innerContextToken ANY
-- interpretation based on predecessor InitialContextToken
-- ASN.1 structure not required
PerMsgToken ::=
-- as emitted by GSS_GetMIC and processed by GSS_VerifyMIC
-- ASN.1 structure not required
innerMsgToken ANY
SealedMessage ::=
-- as emitted by GSS_Wrap and processed by GSS_Unwrap
-- includes internal, mechanism-defined indicator
-- of whether or not encrypted
-- ASN.1 structure not required
sealedUserData ANY
END
3.2: Mechanism-Independent Exported Name Object Format
This section specifies a mechanism-independent level of encapsulating
representation for names exported via the GSS_Export_name() call,
including an object identifier representing the exporting mechanism.
The format of names encapsulated via this representation shall be
defined within individual mechanism drafts. Name objects of this
type will be identified with the following Object Identifier:
{1(iso), 3(org), 6(dod), 1(internet), 5(security), 6(nametypes),
4(gss-api-exported-name)}
No name type OID is included in this mechanism-independent level of
format definition, since (depending on individual mechanism
specifications) the enclosed name may be implicitly typed or may be
explicitly typed using a means other than OID encoding.
Length Name Description
2 TOK_ID Token Identifier
For exported name objects, this
must be hex 04 01.
2 MECH_OID_LEN Length of the Mechanism OID
MECH_OID_LEN MECH_OID Mechanism OID, in DER
4 NAME_LEN Length of name
NAME_LEN NAME Exported name; format defined in
applicable mechanism draft.
4: Name Type Definitions
This section includes definitions for name types and associated
syntaxes which are defined in a mechanism-independent fashion at the
GSS-API level rather than being defined in individual mechanism
specifications.
4.1: Host-Based Service Name Form
The following Object Identifier value is provided as a means to
identify this name form:
{1(iso), 3(org), 6(dod), 1(internet), 5(security), 6(nametypes),
2(gss-host-based-services)}
The recommended symbolic name for this type is
"GSS_C_NT_HOSTBASED_SERVICE".
This name type is used to represent services associated with host
computers. This name form is constructed using two elements,
"service" and "hostname", as follows:
service@hostname
When a reference to a name of this type is resolved, the "hostname"
is canonicalized by attempting a DNS lookup and using the fully-
qualified domain name which is returned, or by using the "hostname"
as provided if the DNS lookup fails. The canonicalization operation
also maps the host's name into lower-case characters.
The "hostname" element may be omitted. If no "@" separator is
included, the entire name is interpreted as the service specifier,
with the "hostname" defaulted to the canonicalized name of the local
host.
Values for the "service" element are registered with the IANA.
4.2: User Name Form
This name form shall be represented by the Object Identifier {iso(1)
member-body(2) United States(840) mit(113554) infosys(1) gssapi(2)
generic(1) user_name(1)}. The recommended mechanism-independent
symbolic name for this type is "GSS_C_NT_USER_NAME". (Note: the same
name form and OID is defined within the Kerberos V5 GSS-API
mechanism, but the symbolic name recommended there begins with a
"GSS_KRB5_NT_" prefix.)
This name type is used to indicate a named user on a local system.
Its interpretation is OS-specific. This name form is constructed as:
username
4.3: Machine UID Form
This name form shall be represented by the Object Identifier {iso(1)
member-body(2) United States(840) mit(113554) infosys(1) gssapi(2)
generic(1) machine_uid_name(2)}. The recommended mechanism-
independent symbolic name for this type is
"GSS_C_NT_MACHINE_UID_NAME". (Note: the same name form and OID is
defined within the Kerberos V5 GSS-API mechanism, but the symbolic
name recommended there begins with a "GSS_KRB5_NT_" prefix.)
This name type is used to indicate a numeric user identifier
corresponding to a user on a local system. Its interpretation is
OS-specific. The gss_buffer_desc representing a name of this type
should contain a locally-significant uid_t, represented in host byte
order. The GSS_Import_name() operation resolves this uid into a
username, which is then treated as the User Name Form.
4.4: String UID Form
This name form shall be represented by the Object Identifier {iso(1)
member-body(2) United States(840) mit(113554) infosys(1) gssapi(2)
generic(1) string_uid_name(3)}. The recommended symbolic name for
this type is "GSS_C_NT_STRING_UID_NAME". (Note: the same name form
and OID is defined within the Kerberos V5 GSS-API mechanism, but the
symbolic name recommended there begins with a "GSS_KRB5_NT_" prefix.)
This name type is used to indicate a string of digits representing
the numeric user identifier of a user on a local system. Its
interpretation is OS-specific. This name type is similar to the
Machine UID Form, except that the buffer contains a string
representing the uid_t.
5: Mechanism-Specific Example Scenarios
This section provides illustrative overviews of the use of various
candidate mechanism types to support the GSS-API. These discussions
are intended primarily for readers familiar with specific security
technologies, demonstrating how GSS-API functions can be used and
implemented by candidate underlying mechanisms. They should not be
regarded as constrictive to implementations or as defining the only
means through which GSS-API functions can be realized with a
particular underlying technology, and do not demonstrate all GSS-API
features with each technology.
5.1: Kerberos V5, single-TGT
OS-specific login functions yield a TGT to the local realm Kerberos
server; TGT is placed in a credentials structure for the client.
Client calls GSS_Acquire_cred() to acquire a cred_handle in order to
reference the credentials for use in establishing security contexts.
Client calls GSS_Init_sec_context(). If the requested service is
located in a different realm, GSS_Init_sec_context() gets the
necessary TGT/key pairs needed to traverse the path from local to
target realm; these data are placed in the owner's TGT cache. After
any needed remote realm resolution, GSS_Init_sec_context() yields a
service ticket to the requested service with a corresponding session
key; these data are stored in conjunction with the context. GSS-API
code sends KRB_TGS_REQ request(s) and receives KRB_TGS_REP
response(s) (in the successful case) or KRB_ERROR.
Assuming success, GSS_Init_sec_context() builds a Kerberos-formatted
KRB_AP_REQ message, and returns it in output_token. The client sends
the output_token to the service.
The service passes the received token as the input_token argument to
GSS_Accept_sec_context(), which verifies the authenticator, provides
the service with the client's authenticated name, and returns an
output_context_handle.
Both parties now hold the session key associated with the service
ticket, and can use this key in subsequent GSS_GetMIC(),
GSS_VerifyMIC(), GSS_Wrap(), and GSS_Unwrap() operations.
5.2: Kerberos V5, double-TGT
TGT acquisition as above.
Note: To avoid unnecessary frequent invocations of error paths when
implementing the GSS-API atop Kerberos V5, it seems appropriate to
represent "single-TGT K-V5" and "double-TGT K-V5" with separate
mech_types, and this discussion makes that assumption.
Based on the (specified or defaulted) mech_type,
GSS_Init_sec_context() determines that the double-TGT protocol
should be employed for the specified target. GSS_Init_sec_context()
returns GSS_S_CONTINUE_NEEDED major_status, and its returned
output_token contains a request to the service for the service's TGT.
(If a service TGT with suitably long remaining lifetime already
exists in a cache, it may be usable, obviating the need for this
step.) The client passes the output_token to the service. Note: this
scenario illustrates a different use for the GSS_S_CONTINUE_NEEDED
status return facility than for support of mutual authentication;
note that both uses can coexist as successive operations within a
single context establishment operation.
The service passes the received token as the input_token argument to
GSS_Accept_sec_context(), which recognizes it as a request for TGT.
(Note that current Kerberos V5 defines no intra-protocol mechanism to
represent such a request.) GSS_Accept_sec_context() returns
GSS_S_CONTINUE_NEEDED major_status and provides the service's TGT in
its output_token. The service sends the output_token to the client.
The client passes the received token as the input_token argument to a
continuation of GSS_Init_sec_context(). GSS_Init_sec_context() caches
the received service TGT and uses it as part of a service ticket
request to the Kerberos authentication server, storing the returned
service ticket and session key in conjunction with the context.
GSS_Init_sec_context() builds a Kerberos-formatted authenticator,
and returns it in output_token along with GSS_S_COMPLETE return
major_status. The client sends the output_token to the service.
Service passes the received token as the input_token argument to a
continuation call to GSS_Accept_sec_context().
GSS_Accept_sec_context() verifies the authenticator, provides the
service with the client's authenticated name, and returns
major_status GSS_S_COMPLETE.
GSS_GetMIC(), GSS_VerifyMIC(), GSS_Wrap(), and GSS_Unwrap() as
above.
5.3: X.509 Authentication Framework
This example illustrates use of the GSS-API in conjunction with
public-key mechanisms, consistent with the X.509 Directory
Authentication Framework.
The GSS_Acquire_cred() call establishes a credentials structure,
making the client's private key accessible for use on behalf of the
client.
The client calls GSS_Init_sec_context(), which interrogates the
Directory to acquire (and validate) a chain of public-key
certificates, thereby collecting the public key of the service. The
certificate validation operation determines that suitable integrity
checks were applied by trusted authorities and that those
certificates have not expired. GSS_Init_sec_context() generates a
secret key for use in per-message protection operations on the
context, and enciphers that secret key under the service's public
key.
The enciphered secret key, along with an authenticator quantity
signed with the client's private key, is included in the output_token
from GSS_Init_sec_context(). The output_token also carries a
certification path, consisting of a certificate chain leading from
the service to the client; a variant approach would defer this path
resolution to be performed by the service instead of being asserted
by the client. The client application sends the output_token to the
service.
The service passes the received token as the input_token argument to
GSS_Accept_sec_context(). GSS_Accept_sec_context() validates the
certification path, and as a result determines a certified binding
between the client's distinguished name and the client's public key.
Given that public key, GSS_Accept_sec_context() can process the
input_token's authenticator quantity and verify that the client's
private key was used to sign the input_token. At this point, the
client is authenticated to the service. The service uses its private
key to decipher the enciphered secret key provided to it for per-
message protection operations on the context.
The client calls GSS_GetMIC() or GSS_Wrap() on a data message, which
causes per-message authentication, integrity, and (optional)
confidentiality facilities to be applied to that message. The service
uses the context's shared secret key to perform corresponding
GSS_VerifyMIC() and GSS_Unwrap() calls.
6: Security Considerations
Security issues are discussed throughout this memo.
7: Related Activities
In order to implement the GSS-API atop existing, emerging, and future
security mechanisms:
object identifiers must be assigned to candidate GSS-API
mechanisms and the name types which they support
concrete data element formats and processing procedures must be
defined for candidate mechanisms
Calling applications must implement formatting conventions which will
enable them to distinguish GSS-API tokens from other data carried in
their application protocols.
Concrete language bindings are required for the programming
environments in which the GSS-API is to be employed, as RFC-1509
defines for the C programming language and GSS-V1.
APPENDIX A
MECHANISM DESIGN CONSTRAINTS
The following constraints on GSS-API mechanism designs are adopted in
response to observed caller protocol requirements, and adherence
thereto is anticipated in subsequent descriptions of GSS-API
mechanisms to be documented in standards-track Internet
specifications.
It is strongly recommended that mechanisms offering per-message
protection services also offer at least one of the replay detection
and sequencing services, as mechanisms offering neither of the latter
will fail to satisfy recognized requirements of certain candidate
caller protocols.
APPENDIX B
COMPATIBILITY WITH GSS-V1
It is the intent of this document to define an interface and
procedures which preserve compatibility between GSS-V1 (RFC-1508)
callers and GSS- V2 providers. All calls defined in GSS-V1 are
preserved, and it has been a goal that GSS-V1 callers should be able
to operate atop GSS-V2 provider implementations. Certain detailed
changes, summarized in this section, have been made in order to
resolve omissions identified in GSS-V1.
The following GSS-V1 constructs, while supported within GSS-V2, are
deprecated:
Names for per-message processing routines: GSS_Seal() deprecated
in favor of GSS_Wrap(); GSS_Sign() deprecated in favor of
GSS_GetMIC(); GSS_Unseal() deprecated in favor of GSS_Unwrap();
GSS_Verify() deprecated in favor of GSS_VerifyMIC().
GSS_Delete_sec_context() facility for context_token usage,
allowing mechanisms to signal context deletion, is retained for
compatibility with GSS-V1. For current usage, it is recommended
that both peers to a context invoke GSS_Delete_sec_context()
independently, passing a null output_context_token buffer to
indicate that no context_token is required. Implementations of
GSS_Delete_sec_context() should delete relevant locally-stored
context information.
This GSS-V2 specification adds the following calls which are not
present in GSS-V1:
Credential management calls: GSS_Add_cred(),
GSS_Inquire_cred_by_mech().
Context-level calls: GSS_Inquire_context(), GSS_Wrap_size_limit(),
GSS_Export_sec_context(), GSS_Import_sec_context().
Per-message calls: No new calls. Existing calls have been renamed.
Support calls: GSS_Create_empty_OID_set(),
GSS_Add_OID_set_member(), GSS_Test_OID_set_member(),
GSS_Release_OID(), GSS_OID_to_str(), GSS_Str_to_OID(),
GSS_Inquire_names_for_mech(), GSS_Inquire_mechs_for_name(),
GSS_Canonicalize_name(), GSS_Export_name(), GSS_Duplicate_name().
This GSS-V2 specification introduces three new facilities applicable
to security contexts, indicated using the following context state
values which are not present in GSS-V1:
anon_state, set TRUE to indicate that a context's initiator is
anonymous from the viewpoint of the target; Section 1.2.5 of this
specification provides a summary description of the GSS-V2
anonymity support facility, support and use of which is optional.
prot_ready_state, set TRUE to indicate that a context may be used
for per-message protection before final completion of context
establishment; Section 1.2.7 of this specification provides a
summary description of the GSS-V2 facility enabling mechanisms to
selectively permit per-message protection during context
establishment, support and use of which is optional.
trans_state, set TRUE to indicate that a context is transferable to
another process using the GSS-V2 GSS_Export_sec_context() facility.
These state values are represented (at the C bindings level) in
positions within a bit vector which are unused in GSS-V1, and may be
safely ignored by GSS-V1 callers.
Relative to GSS-V1, GSS-V2 provides additional guidance to GSS-API
implementors in the following areas: implementation robustness,
credential management, behavior in multi-mechanism configurations,
naming support, and inclusion of optional sequencing services. The
token tagging facility as defined in GSS-V2, Section 3.1, is now
described directly in terms of octets to facilitate interoperable
implementation without general ASN.1 processing code; the
corresponding ASN.1 syntax, included for descriptive purposes, is
unchanged from that in GSS-V1. For use in conjunction with added
naming support facilities, a new Exported Name Object construct is
added. Additional name types are introduced in Section 4.
This GSS-V2 specification adds the following major_status values
which are not defined in GSS-V1:
GSS_S_BAD_QOP unsupported QOP value
GSS_S_UNAUTHORIZED operation unauthorized
GSS_S_UNAVAILABLE operation unavailable
GSS_S_DUPLICATE_ELEMENT duplicate credential element requested
GSS_S_NAME_NOT_MN name contains multi-mechanism elements
GSS_S_GAP_TOKEN skipped predecessor token(s)
detected
Of these added status codes, only two values are defined to be
returnable by calls existing in GSS-V1: GSS_S_BAD_QOP (returnable by
GSS_GetMIC() and GSS_Wrap()), and GSS_S_GAP_TOKEN (returnable by
GSS_VerifyMIC() and GSS_Unwrap()).
Additionally, GSS-V2 descriptions of certain calls present in GSS-V1
have been updated to allow return of additional major_status values
from the set as defined in GSS-V1: GSS_Inquire_cred() has
GSS_S_DEFECTIVE_CREDENTIAL and GSS_S_CREDENTIALS_EXPIRED defined as
returnable, GSS_Init_sec_context() has GSS_S_OLD_TOKEN,
GSS_S_DUPLICATE_TOKEN, and GSS_S_BAD_MECH defined as returnable, and
GSS_Accept_sec_context() has GSS_S_BAD_MECH defined as returnable.
Author's Address
John Linn
OpenVision Technologies
One Main St.
Cambridge, MA 02142 USA
Phone: +1 617.374.2245
EMail: John.Linn@ov.com