tech-invite   World Map
3GPP     Specs     Glossaries     UICC       IETF     RFCs     Groups     SIP     ABNFs       T+       Search     Home

RFC 2078

 
 
 

Generic Security Service Application Program Interface, Version 2

Part 3 of 3, p. 59 to 85
Prev RFC Part

 


prevText      Top      Up      ToC       Page 59 
2.4:  Support calls

   This group of calls provides support functions useful to GSS-API
   callers, independent of the state of established contexts. Their
   characterization with regard to blocking or non-blocking status in
   terms of network interactions is unspecified.

Top      Up      ToC       Page 60 
2.4.1:  GSS_Display_status call

   Inputs:

   o  status_value INTEGER,-GSS-API major_status or minor_status
      return value

   o  status_type INTEGER,-1 if major_status, 2 if minor_status

   o  mech_type OBJECT IDENTIFIER-mech_type to be used for minor_
      status translation

   Outputs:

   o  major_status INTEGER,

   o  minor_status INTEGER,

   o  status_string_set SET OF OCTET STRING

   Return major_status codes:

   o  GSS_S_COMPLETE indicates that a valid printable status
      representation (possibly representing more than one status event
      encoded within the status_value) is available in the returned
      status_string_set.

   o  GSS_S_BAD_MECH indicates that translation in accordance with an
      unsupported mech_type was requested, so translation could not
      be performed.

   o  GSS_S_BAD_STATUS indicates that the input status_value was
      invalid, or that the input status_type carried a value other
      than 1 or 2, so translation could not be performed.

   o  GSS_S_FAILURE indicates that the requested operation could not
      be performed for reasons unspecified at the GSS-API level.

   Provides a means for callers to translate GSS-API-returned major and
   minor status codes into printable string representations.

2.4.2:  GSS_Indicate_mechs call

   Input:

   o  (none)

Top      Up      ToC       Page 61 
   Outputs:

   o  major_status INTEGER,

   o  minor_status INTEGER,

   o  mech_set SET OF OBJECT IDENTIFIER

   Return major_status codes:

   o  GSS_S_COMPLETE indicates that a set of available mechanisms has
      been returned in mech_set.

   o  GSS_S_FAILURE indicates that the requested operation could not
      be performed for reasons unspecified at the GSS-API level.

   Allows callers to determine the set of mechanism types available on
   the local system. This call is intended for support of specialized
   callers who need to request non-default mech_type sets from
   GSS_Acquire_cred(),  and should not be needed by other callers.

2.4.3:  GSS_Compare_name call

   Inputs:

   o  name1 INTERNAL NAME,

   o  name2 INTERNAL NAME

   Outputs:

   o  major_status INTEGER,

   o  minor_status INTEGER,

   o  name_equal BOOLEAN

   Return major_status codes:

   o  GSS_S_COMPLETE indicates that name1 and name2 were comparable,
      and that the name_equal result indicates whether name1 and
      name2 represent the same entity.

   o  GSS_S_BAD_NAMETYPE indicates that one or both of name1 and
      name2 contained internal type specifiers uninterpretable
      by the applicable underlying GSS-API mechanism(s), or that
      the two names' types are different and incomparable, so that
      the comparison operation could not be completed.

Top      Up      ToC       Page 62 
   o  GSS_S_BAD_NAME indicates that one or both of the input names
      was ill-formed in terms of its internal type specifier, so
      the comparison operation could not be completed.

   o  GSS_S_FAILURE indicates that the call's operation could not
      be performed for reasons unspecified at the GSS-API level.

   Allows callers to compare two internal name representations to
   determine whether they refer to the same entity.  If either name
   presented to GSS_Compare_name() denotes an anonymous principal,
   GSS_Compare_name() shall indicate FALSE.  It is not required that
   either or both inputs name1 and name2 be MNs; for some
   implementations and cases, GSS_S_BAD_NAMETYPE may be returned,
   indicating name incomparability, for the case where neither input
   name is an MN.

2.4.4:  GSS_Display_name call

   Inputs:

   o  name INTERNAL NAME

   Outputs:

   o  major_status INTEGER,

   o  minor_status INTEGER,

   o  name_string OCTET STRING,

   o  name_type OBJECT IDENTIFIER

   Return major_status codes:

   o  GSS_S_COMPLETE indicates that a valid printable name
      representation is available in the returned name_string.

   o  GSS_S_BAD_NAMETYPE indicates that the provided name was of a
      type uninterpretable by the applicable underlying GSS-API
      mechanism(s), so no printable representation could be generated.

   o  GSS_S_BAD_NAME indicates that the contents of the provided name
      were inconsistent with the internally-indicated name type, so
      no printable representation could be generated.

   o  GSS_S_FAILURE indicates that the requested operation could not
      be performed for reasons unspecified at the GSS-API level.

Top      Up      ToC       Page 63 
   Allows callers to translate an internal name representation into a
   printable form with associated namespace type descriptor. The syntax
   of the printable form is a local matter.

   If the input name represents an anonymous identity, a reserved value
   (GSS_C_NT_ANONYMOUS) shall be returned for name_type.

2.4.5:  GSS_Import_name call

   Inputs:

   o  input_name_string OCTET STRING,

   o  input_name_type OBJECT IDENTIFIER

   Outputs:

   o  major_status INTEGER,

   o  minor_status INTEGER,

   o  output_name INTERNAL NAME

   Return major_status codes:

   o  GSS_S_COMPLETE indicates that a valid name representation is
      output in output_name and described by the type value in
      output_name_type.

   o  GSS_S_BAD_NAMETYPE indicates that the input_name_type is unsupported
      by the applicable underlying GSS-API mechanism(s), so the import
      operation could not be completed.

   o  GSS_S_BAD_NAME indicates that the provided input_name_string
      is ill-formed in terms of the input_name_type, so the import
      operation could not be completed.

   o  GSS_S_FAILURE indicates that the requested operation could not
      be performed for reasons unspecified at the GSS-API level.

   Allows callers to provide a name representation as a contiguous octet
   string, designate the type of namespace in conjunction with which it
   should be parsed, and convert that representation to an internal form
   suitable for input to other GSS-API routines.  The syntax of the
   input_name_string is defined in conjunction with its associated name
   type; depending on the input_name_type, the associated
   input_name_string may or may not be a printable string. Note: The
   input_name_type argument serves to describe and qualify the

Top      Up      ToC       Page 64 
   interpretation of the associated input_name_string; it does not
   specify the data type of the returned output_name.

   If a mechanism claims support for a particular name type, its
   GSS_Import_name() operation shall be able to accept all possible
   values conformant to the external name syntax as defined for that
   name type.  These imported values may correspond to:

      (1) locally registered entities (for which credentials may be
      acquired),

      (2) non-local entities (for which local credentials cannot be
      acquired, but which may be referenced as targets of initiated
      security contexts or initiators of accepted security contexts), or
      to

      (3) neither of the above.

   Determination of whether a particular name belongs to class (1), (2),
   or (3) as described above is not guaranteed to be performed by the
   GSS_Import_name() function.

   The internal name generated by a GSS_Import_name() operation may be a
   single-mechanism MN, and is likely to be an MN within a single-
   mechanism implementation, but portable callers must not depend on
   this property (and must not, therefore, assume that the output from
   GSS_Import_name() can be passed directly to GSS_Export_name() without
   first being processed through GSS_Canonicalize_name()).

2.4.6: GSS_Release_name call

   Inputs:

   o  name INTERNAL NAME

   Outputs:

   o  major_status INTEGER,

   o  minor_status INTEGER

   Return major_status codes:

   o  GSS_S_COMPLETE indicates that the storage associated with the
      input name was successfully released.

   o  GSS_S_BAD_NAME indicates that the input name argument did not
      contain a valid name.

Top      Up      ToC       Page 65 
   o  GSS_S_FAILURE indicates that the requested operation could not
      be performed for reasons unspecified at the GSS-API level.

   Allows callers to release the storage associated with an internal
   name representation.  This call's specific behavior depends on the
   language and programming environment within which a GSS-API
   implementation operates, and is therefore detailed within applicable
   bindings specifications; in particular, this call may be superfluous
   within bindings where memory management is automatic.

2.4.7: GSS_Release_buffer call

   Inputs:

   o  buffer OCTET STRING

   Outputs:

   o  major_status INTEGER,

   o  minor_status INTEGER

   Return major_status codes:

   o  GSS_S_COMPLETE indicates that the storage associated with the
      input buffer was successfully released.

   o  GSS_S_FAILURE indicates that the requested operation could not
      be performed for reasons unspecified at the GSS-API level.

   Allows callers to release the storage associated with an OCTET STRING
   buffer allocated by another GSS-API call.  This call's specific
   behavior depends on the language and programming environment within
   which a GSS-API implementation operates, and is therefore detailed
   within applicable bindings specifications; in particular, this call
   may be superfluous within bindings where memory management is
   automatic.

2.4.8: GSS_Release_OID_set call

   Inputs:

   o  buffer SET OF OBJECT IDENTIFIER

   Outputs:

   o  major_status INTEGER,

Top      Up      ToC       Page 66 
   o  minor_status INTEGER

   Return major_status codes:

   o  GSS_S_COMPLETE indicates that the storage associated with the
      input object identifier set was successfully released.

   o  GSS_S_FAILURE indicates that the requested operation could not
      be performed for reasons unspecified at the GSS-API level.

   Allows callers to release the storage associated with an object
   identifier set object allocated by another GSS-API call.  This call's
   specific behavior depends on the language and programming environment
   within which a GSS-API implementation operates, and is therefore
   detailed within applicable bindings specifications; in particular,
   this call may be superfluous within bindings where memory management
   is automatic.

2.4.9: GSS_Create_empty_OID_set call

   Inputs:

   o  (none)

   Outputs:

   o  major_status INTEGER,

   o  minor_status INTEGER,

   o  oid_set SET OF OBJECT IDENTIFIER

   Return major_status codes:

   o  GSS_S_COMPLETE indicates successful completion

   o  GSS_S_FAILURE indicates that the operation failed

   Creates an object identifier set containing no object identifiers, to
   which members may be subsequently added using the
   GSS_Add_OID_set_member() routine.  These routines are intended to be
   used to construct sets of mechanism object identifiers, for input to
   GSS_Acquire_cred().

Top      Up      ToC       Page 67 
2.4.10: GSS_Add_OID_set_member call

   Inputs:

   o  member_oid OBJECT IDENTIFIER,

   o  oid_set SET OF OBJECT IDENTIFIER

   Outputs:

   o  major_status INTEGER,

   o  minor_status INTEGER,

   Return major_status codes:

   o  GSS_S_COMPLETE indicates successful completion

   o  GSS_S_FAILURE indicates that the operation failed

   Adds an Object Identifier to an Object Identifier set.  This routine
   is intended for use in conjunction with GSS_Create_empty_OID_set()
   when constructing a set of mechanism OIDs for input to
   GSS_Acquire_cred().

2.4.11: GSS_Test_OID_set_member call

   Inputs:

   o  member OBJECT IDENTIFIER,

   o  set SET OF OBJECT IDENTIFIER

   Outputs:

   o  major_status INTEGER,

   o  minor_status INTEGER,

   o  present BOOLEAN

   Return major_status codes:

   o  GSS_S_COMPLETE indicates successful completion

   o  GSS_S_FAILURE indicates that the operation failed

Top      Up      ToC       Page 68 
   Interrogates an Object Identifier set to determine whether a
   specified Object Identifier is a member.  This routine is intended to
   be used with OID sets returned by GSS_Indicate_mechs(),
   GSS_Acquire_cred(), and GSS_Inquire_cred().

2.4.12: GSS_Release_OID call

   Inputs:

   o  oid OBJECT IDENTIFIER

   Outputs:

   o  major_status INTEGER,

   o  minor_status INTEGER

   Return major_status codes:

   o  GSS_S_COMPLETE indicates successful completion

   o  GSS_S_FAILURE indicates that the operation failed

   Allows the caller to release the storage associated with an OBJECT
   IDENTIFIER buffer allocated by another GSS-API call. This call's
   specific behavior depends on the language and programming environment
   within which a GSS-API implementation operates, and is therefore
   detailed within applicable bindings specifications; in particular,
   this call may be superfluous within bindings where memory management
   is automatic.

2.4.13: GSS_OID_to_str call

   Inputs:

   o  oid OBJECT IDENTIFIER

   Outputs:

   o  major_status INTEGER,

   o  minor_status INTEGER,

   o  oid_str OCTET STRING

   Return major_status codes:

   o  GSS_S_COMPLETE indicates successful completion

Top      Up      ToC       Page 69 
   o  GSS_S_FAILURE indicates that the operation failed

   The function GSS_OID_to_str() returns a string representing the input
   OID in numeric ASN.1 syntax format (curly-brace enclosed, space-
   delimited, e.g., "{2 16 840 1 113687 1 2 1}"). The string is
   releasable using GSS_Release_buffer(). If the input "oid" does not
   represent a syntactically valid object identifier, GSS_S_FAILURE
   status is returned and the returned oid_str result is NULL.

2.4.14: GSS_Str_to_OID call

   Inputs:

   o  oid_str OCTET STRING

   Outputs:

   o  major_status INTEGER,

   o  minor_status INTEGER,

   o  oid OBJECT IDENTIFIER

   Return major_status codes:

   o  GSS_S_COMPLETE indicates successful completion

   o  GSS_S_FAILURE indicates that the operation failed

   The function GSS_Str_to_OID() constructs and returns an OID from its
   printable form; implementations should be able to accept the numeric
   ASN.1 syntax form as described for GSS_OID_to_str(), and this form
   should be used for portability, but implementations of this routine
   may also accept other formats (e.g., "1.2.3.3"). The OID is suitable
   for release using the function GSS_Release_OID(). If the input
   oid_str cannot be translated into an OID, GSS_S_FAILURE status is
   returned and the "oid" result is NULL.

2.4.15:  GSS_Inquire_names_for_mech call

   Input:

   o  input_mech_type OBJECT IDENTIFIER, -- mechanism type

   Outputs:

   o  major_status INTEGER,

Top      Up      ToC       Page 70 
   o  minor_status INTEGER,

   o  name_type_set SET OF OBJECT IDENTIFIER

   Return major_status codes:

   o  GSS_S_COMPLETE indicates that the output name_type_set contains
      a list of name types which are supported by the locally available
      mechanism identified by input_mech_type.

   o  GSS_S_BAD_MECH indicates that the mechanism identified by
      input_mech_type was unsupported within the local implementation,
      causing the query to fail.

   o  GSS_S_FAILURE indicates that the requested operation could not
      be performed for reasons unspecified at the GSS-API level.

   Allows callers to determine the set of name types which are
   supportable by a specific locally-available mechanism.

2.4.16: GSS_Inquire_mechs_for_name call

   Inputs:

   o  input_name INTERNAL NAME,

   Outputs:

   o  major_status INTEGER,

   o  minor_status INTEGER,

   o  mech_types SET OF OBJECT IDENTIFIER

   Return major_status codes:

   o  GSS_S_COMPLETE indicates that a set of object identifiers,
      corresponding to the set of mechanisms suitable for processing
      the input_name, is available in mech_types.

   o  GSS_S_BAD_NAME indicates that the input_name could not be
      processed.

   o  GSS_S_BAD_NAMETYPE indicates that the type of the input_name
      is unsupported by the GSS-API implementation.

   o  GSS_S_FAILURE indicates that the requested operation could not
      be performed for reasons unspecified at the GSS-API level.

Top      Up      ToC       Page 71 
   This routine returns the mechanism set with which the input_name may
   be processed.  After use, the mech_types object should be freed by
   the caller via the GSS_Release_OID_set() call.  Note: it is
   anticipated that implementations of GSS_Inquire_mechs_for_name() will
   commonly operate based on type information describing the
   capabilities of available mechanisms; it is not guaranteed that all
   identified mechanisms will necessarily be able to canonicalize (via
   GSS_Canonicalize_name()) a particular name.

2.4.17: GSS_Canonicalize_name call

   Inputs:

   o  input_name INTERNAL NAME,

   o  mech_type OBJECT IDENTIFIER  -- must be explicit mechanism,
                                      not "default" specifier

   Outputs:

   o  major_status INTEGER,

   o  minor_status INTEGER,

   o  output_name INTERNAL NAME

   Return major_status codes:

   o  GSS_S_COMPLETE indicates that a mechanism-specific reduction of
      the input_name, as processed by the mechanism identified by
      mech_type, is available in output_name.

   o  GSS_S_BAD_MECH indicates that the identified mechanism is
      unsupported.

   o  GSS_S_BAD_NAMETYPE indicates that the input name does not
      contain an element with suitable type for processing by the
      identified mechanism.

   o  GSS_S_BAD_NAME indicates that the input name contains an
      element with suitable type for processing by the identified
      mechanism, but that this element could not be processed
      successfully.

   o  GSS_S_FAILURE indicates that the requested operation could not
      be performed for reasons unspecified at the GSS-API level.

Top      Up      ToC       Page 72 
   This routine reduces a GSS-API internal name, which may in general
   contain elements corresponding to multiple mechanisms, to a
   mechanism-specific Mechanism Name (MN) by applying the translations
   corresponding to the mechanism identified by mech_type.

2.4.18: GSS_Export_name call

   Inputs:

   o  input_name INTERNAL NAME, -- required to be MN

   Outputs:

   o  major_status INTEGER,

   o  minor_status INTEGER,

   o  output_name OCTET STRING

   Return major_status codes:

   o  GSS_S_COMPLETE indicates that a flat representation of the
      input name is available in output_name.

   o  GSS_S_NAME_NOT_MN indicates that the input name contained
      elements corresponding to multiple mechanisms, so cannot
      be exported into a single-mechanism flat form.

   o  GSS_S_BAD_NAME indicates that the input name was an MN,
      but could not be processed.

   o  GSS_S_BAD_NAMETYPE indicates that the input name was an MN,
      but that its type is unsupported by the GSS-API implementation.

   o  GSS_S_FAILURE indicates that the requested operation could not
      be performed for reasons unspecified at the GSS-API level.

   This routine creates a flat name representation, suitable for
   bytewise comparison or for input to GSS_Import_name() in conjunction
   with the reserved GSS-API Exported Name Object OID, from a internal-
   form Mechanism Name (MN) as emitted, e.g., by GSS_Canonicalize_name()
   or GSS_Accept_sec_context().

   The emitted GSS-API Exported Name Object is self-describing; no
   associated parameter-level OID need be emitted by this call.  This
   flat representation consists of a mechanism-independent wrapper
   layer, defined in Section 3.2 of this document, enclosing a
   mechanism-defined name representation.

Top      Up      ToC       Page 73 
   In all cases, the flat name output by GSS_Export_name() to correspond
   to a particular input MN must be invariant over time within a
   particular installation.

   The GSS_S_NAME_NOT_MN status code is provided to enable
   implementations to reject input names which are not MNs.  It is not,
   however, required for purposes of conformance to this specification
   that all non-MN input names must necessarily be rejected.

2.4.19: GSS_Duplicate_name call

   Inputs:

   o  src_name INTERNAL NAME

   Outputs:

   o  major_status INTEGER,

   o  minor_status INTEGER,

   o  dest_name INTERNAL NAME

   Return major_status codes:

   o  GSS_S_COMPLETE indicates that dest_name references an internal
      name object containing the same name as passed to src_name.

   o  GSS_S_BAD_NAME indicates that the input name was invalid.

   o  GSS_S_BAD_NAMETYPE indicates that the input name's type
      is unsupported by the GSS-API implementation.

   o  GSS_S_FAILURE indicates that the requested operation could not
      be performed for reasons unspecified at the GSS-API level.

   This routine takes input internal name src_name, and returns another
   reference (dest_name) to that name which can be used even if src_name
   is later freed.  (Note: This may be implemented by copying or through
   use of reference counts.)

3: Data Structure Definitions for GSS-V2 Usage

   Subsections of this section define, for interoperability and
   portability purposes, certain data structures for use with GSS-V2.

Top      Up      ToC       Page 74 
3.1: Mechanism-Independent Token Format

   This section specifies a mechanism-independent level of encapsulating
   representation for the initial token of a GSS-API context
   establishment sequence, incorporating an identifier of the mechanism
   type to be used on that context and enabling tokens to be interpreted
   unambiguously at GSS-API peers. Use of this format is required for
   initial context establishment tokens of Internet standards-track
   GSS-API mechanisms; use in non-initial tokens is optional.

   The encoding format for the token tag is derived from ASN.1 and DER
   (per illustrative ASN.1 syntax included later within this
   subsection), but its concrete representation is defined directly in
   terms of octets rather than at the ASN.1 level in order to facilitate
   interoperable implementation without use of general ASN.1 processing
   code.  The token tag consists of the following elements, in order:

      1. 0x60 -- Tag for [APPLICATION 0] SEQUENCE; indicates that
      constructed form, definite length encoding follows.

      2. Token length octets, specifying length of subsequent data
      (i.e., the summed lengths of elements 3-5 in this list, and of the
      mechanism-defined token object following the tag).  This element
      comprises a variable number of octets:

      2a. If the indicated value is less than 128, it shall be
      represented in a single octet with bit 8 (high order) set to "0"
      and the remaining bits representing the value.

      2b. If the indicated value is 128 or more, it shall be represented
      in two or more octets, with bit 8 of the first octet set to "1"
      and the remaining bits of the first octet specifying the number of
      additional octets.  The subsequent octets carry the value, 8 bits
      per octet, most significant digit first.  The minimum number of
      octets shall be used to encode the length (i.e., no octets
      representing leading zeros shall be included within the length
      encoding).

      3. 0x06 -- Tag for OBJECT IDENTIFIER

      4. Object identifier length -- length (number of octets) of the
      encoded object identifier contained in element 5, encoded per
      rules as described in 2a. and 2b. above.

      5. Object identifier octets -- variable number of octets, encoded
      per ASN.1 BER rules:

Top      Up      ToC       Page 75 
      5a. The first octet contains the sum of two values: (1) the top-
      level object identifier component, multiplied by 40 (decimal), and
      (2) the second-level object identifier component.  This special
      case is the only point within an object identifier encoding where
      a single octet represents contents of more than one component.

      5b. Subsequent octets, if required, encode successively-lower
      components in the represented object identifier.  A component's
      encoding may span multiple octets, encoding 7 bits per octet (most
      significant bits first) and with bit 8 set to "1" on all but the
      final octet in the component's encoding.  The minimum number of
      octets shall be used to encode each component (i.e., no octets
      representing leading zeros shall be included within a component's
      encoding).

      (Note: In many implementations, elements 3-5 may be stored and
      referenced as a contiguous string constant.)

   The token tag is immediately followed by a mechanism-defined token
   object.  Note that no independent size specifier intervenes following
   the object identifier value to indicate the size of the mechanism-
   defined token object.  While ASN.1 usage within mechanism-defined
   tokens is permitted, there is no requirement that the mechanism-
   specific innerContextToken, innerMsgToken, and sealedUserData data
   elements must employ ASN.1 BER/DER encoding conventions.

Top      Up      ToC       Page 76 
   The following ASN.1 syntax is included for descriptive purposes only,
   to illustrate structural relationships among token and tag objects.
   For interoperability purposes, token and tag encoding shall be
   performed using the concrete encoding procedures described earlier in
   this subsection.

       GSS-API DEFINITIONS ::=

       BEGIN

       MechType ::= OBJECT IDENTIFIER
       -- data structure definitions

       -- callers must be able to distinguish among
       -- InitialContextToken, SubsequentContextToken,
       -- PerMsgToken, and SealedMessage data elements
       -- based on the usage in which they occur

       InitialContextToken ::=
       -- option indication (delegation, etc.) indicated within
       -- mechanism-specific token
       [APPLICATION 0] IMPLICIT SEQUENCE {
               thisMech MechType,
               innerContextToken ANY DEFINED BY thisMech
                  -- contents mechanism-specific
                  -- ASN.1 structure not required
               }

       SubsequentContextToken ::= innerContextToken ANY
       -- interpretation based on predecessor InitialContextToken
       -- ASN.1 structure not required

       PerMsgToken ::=
       -- as emitted by GSS_GetMIC and processed by GSS_VerifyMIC
       -- ASN.1 structure not required
               innerMsgToken ANY

       SealedMessage ::=
       -- as emitted by GSS_Wrap and processed by GSS_Unwrap
       -- includes internal, mechanism-defined indicator
       -- of whether or not encrypted
       -- ASN.1 structure not required
               sealedUserData ANY

       END

Top      Up      ToC       Page 77 
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".

Top      Up      ToC       Page 78 
   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

Top      Up      ToC       Page 79 
   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.

Top      Up      ToC       Page 80 
   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,

Top      Up      ToC       Page 81 
   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

Top      Up      ToC       Page 82 
   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.

Top      Up      ToC       Page 83 
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.

Top      Up      ToC       Page 84 
   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

Top      Up      ToC       Page 85 
   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