RFC 2743
Generic Security Service Application Program Interface Version 2, Update 1
2.3: Per-message calls
This group of calls is used to perform per-message protection processing on an established security context. None of these calls block pending network interactions. These calls may be invoked by a context's initiator or by the context's target. The four members of this group should be considered as two pairs; the output from GSS_GetMIC() is properly input to GSS_VerifyMIC(), and the output from GSS_Wrap() is properly input to GSS_Unwrap(). GSS_GetMIC() and GSS_VerifyMIC() support data origin authentication and data integrity services. When GSS_GetMIC() is invoked on an input message, it yields a per-message token containing data items which allow underlying mechanisms to provide the specified security services. The original message, along with the generated per-message token, is passed to the remote peer; these two data elements are processed by GSS_VerifyMIC(), which validates the message in conjunction with the separate token. GSS_Wrap() and GSS_Unwrap() support caller-requested confidentiality in addition to the data origin authentication and data integrity services offered by GSS_GetMIC() and GSS_VerifyMIC(). GSS_Wrap() outputs a single data element, encapsulating optionally enciphered user data as well as associated token data items. The data element output from GSS_Wrap() is passed to the remote peer and processed by GSS_Unwrap() at that system. GSS_Unwrap() combines decipherment (as required) with validation of data items related to authentication and integrity. Although zero-length tokens are never returned by GSS calls for transfer to a context's peer, a zero-length object may be passed by a caller into GSS_Wrap(), in which case the corresponding peer calling GSS_Unwrap() on the transferred token will receive a zero-length object as output from GSS_Unwrap(). Similarly, GSS_GetMIC() can be called on an empty object, yielding a MIC which GSS_VerifyMIC() will successfully verify against the active security context in conjunction with a zero-length object.
2.3.1: GSS_GetMIC call
Note: This call is functionally equivalent to the GSS_Sign call as defined in previous versions of this specification. In the interests of backward compatibility, it is recommended that implementations support this function under both names for the present; future references to this function as GSS_Sign are deprecated. Inputs: o context_handle CONTEXT HANDLE, o qop_req INTEGER, -- 0 specifies default QOP o message OCTET STRING Outputs: o major_status INTEGER, o minor_status INTEGER, o per_msg_token OCTET STRING -- caller must release -- with GSS_Release_buffer() Return major_status codes: o GSS_S_COMPLETE indicates that an integrity check, suitable for an established security context, was successfully applied and that the message and corresponding per_msg_token are ready for transmission. o GSS_S_CONTEXT_EXPIRED indicates that context-related data items have expired, so that the requested operation cannot be performed. o GSS_S_NO_CONTEXT indicates that no context was recognized for the input context_handle provided. o GSS_S_BAD_QOP indicates that the provided QOP value is not recognized or supported for the context. o GSS_S_FAILURE indicates that the context is recognized, but that the requested operation could not be performed for reasons unspecified at the GSS-API level. Using the security context referenced by context_handle, apply an integrity check to the input message (along with timestamps and/or other data included in support of mech_type-specific mechanisms) and (if GSS_S_COMPLETE status is indicated) return the result in
per_msg_token. The qop_req parameter, interpretation of which is discussed in Section 1.2.4, allows quality-of-protection control. The caller passes the message and the per_msg_token to the target. The GSS_GetMIC() function completes before the message and per_msg_token is sent to the peer; successful application of GSS_GetMIC() does not guarantee that a corresponding GSS_VerifyMIC() has been (or can necessarily be) performed successfully when the message arrives at the destination. Mechanisms which do not support per-message protection services should return GSS_S_FAILURE if this routine is called.2.3.2: GSS_VerifyMIC call
Note: This call is functionally equivalent to the GSS_Verify call as defined in previous versions of this specification. In the interests of backward compatibility, it is recommended that implementations support this function under both names for the present; future references to this function as GSS_Verify are deprecated. Inputs: o context_handle CONTEXT HANDLE, o message OCTET STRING, o per_msg_token OCTET STRING Outputs: o qop_state INTEGER, o major_status INTEGER, o minor_status INTEGER, Return major_status codes: o GSS_S_COMPLETE indicates that the message was successfully verified. o GSS_S_DEFECTIVE_TOKEN indicates that consistency checks performed on the received per_msg_token failed, preventing further processing from being performed with that token. o GSS_S_BAD_SIG (GSS_S_BAD_MIC) indicates that the received per_msg_token contains an incorrect integrity check for the message.
o GSS_S_DUPLICATE_TOKEN, GSS_S_OLD_TOKEN, GSS_S_UNSEQ_TOKEN, and GSS_S_GAP_TOKEN values appear in conjunction with the optional per- message replay detection features described in Section 1.2.3; their semantics are described in that section. o GSS_S_CONTEXT_EXPIRED indicates that context-related data items have expired, so that the requested operation cannot be performed. o GSS_S_NO_CONTEXT indicates that no context was recognized for the input context_handle provided. o GSS_S_FAILURE indicates that the context is recognized, but that the GSS_VerifyMIC() operation could not be performed for reasons unspecified at the GSS-API level. Using the security context referenced by context_handle, verify that the input per_msg_token contains an appropriate integrity check for the input message, and apply any active replay detection or sequencing features. Returns an indication of the quality-of- protection applied to the processed message in the qop_state result. Mechanisms which do not support per-message protection services should return GSS_S_FAILURE if this routine is called.2.3.3: GSS_Wrap call
Note: This call is functionally equivalent to the GSS_Seal call as defined in previous versions of this specification. In the interests of backward compatibility, it is recommended that implementations support this function under both names for the present; future references to this function as GSS_Seal are deprecated. Inputs: o context_handle CONTEXT HANDLE, o conf_req_flag BOOLEAN, o qop_req INTEGER, -- 0 specifies default QOP o input_message OCTET STRING Outputs: o major_status INTEGER, o minor_status INTEGER,
o conf_state BOOLEAN, o output_message OCTET STRING -- caller must release with -- GSS_Release_buffer() Return major_status codes: o GSS_S_COMPLETE indicates that the input_message was successfully processed and that the output_message is ready for transmission. o GSS_S_CONTEXT_EXPIRED indicates that context-related data items have expired, so that the requested operation cannot be performed. o GSS_S_NO_CONTEXT indicates that no context was recognized for the input context_handle provided. o GSS_S_BAD_QOP indicates that the provided QOP value is not recognized or supported for the context. o GSS_S_FAILURE indicates that the context is recognized, but that the GSS_Wrap() operation could not be performed for reasons unspecified at the GSS-API level. Performs the data origin authentication and data integrity functions of GSS_GetMIC(). If the input conf_req_flag is TRUE, requests that confidentiality be applied to the input_message. Confidentiality may not be supported in all mech_types or by all implementations; the returned conf_state flag indicates whether confidentiality was provided for the input_message. The qop_req parameter, interpretation of which is discussed in Section 1.2.4, allows quality-of-protection control. When GSS_S_COMPLETE status is returned, the GSS_Wrap() call yields a single output_message data element containing (optionally enciphered) user data as well as control information. Mechanisms which do not support per-message protection services should return GSS_S_FAILURE if this routine is called.2.3.4: GSS_Unwrap call
Note: This call is functionally equivalent to the GSS_Unseal call as defined in previous versions of this specification. In the interests of backward compatibility, it is recommended that implementations support this function under both names for the present; future references to this function as GSS_Unseal are deprecated.
Inputs: o context_handle CONTEXT HANDLE, o input_message OCTET STRING Outputs: o conf_state BOOLEAN, o qop_state INTEGER, o major_status INTEGER, o minor_status INTEGER, o output_message OCTET STRING -- caller must release with -- GSS_Release_buffer() Return major_status codes: o GSS_S_COMPLETE indicates that the input_message was successfully processed and that the resulting output_message is available. o GSS_S_DEFECTIVE_TOKEN indicates that consistency checks performed on the per_msg_token extracted from the input_message failed, preventing further processing from being performed. o GSS_S_BAD_SIG (GSS_S_BAD_MIC) indicates that an incorrect integrity check was detected for the message. o GSS_S_DUPLICATE_TOKEN, GSS_S_OLD_TOKEN, GSS_S_UNSEQ_TOKEN, and GSS_S_GAP_TOKEN values appear in conjunction with the optional per- message replay detection features described in Section 1.2.3; their semantics are described in that section. o GSS_S_CONTEXT_EXPIRED indicates that context-related data items have expired, so that the requested operation cannot be performed. o GSS_S_NO_CONTEXT indicates that no context was recognized for the input context_handle provided. o GSS_S_FAILURE indicates that the context is recognized, but that the GSS_Unwrap() operation could not be performed for reasons unspecified at the GSS-API level.
Processes a data element generated (and optionally enciphered) by GSS_Wrap(), provided as input_message. The returned conf_state value indicates whether confidentiality was applied to the input_message. If conf_state is TRUE, GSS_Unwrap() has deciphered the input_message. Returns an indication of the quality-of-protection applied to the processed message in the qop_state result. GSS_Unwrap() performs the data integrity and data origin authentication checking functions of GSS_VerifyMIC() on the plaintext data. Plaintext data is returned in output_message. Mechanisms which do not support per-message protection services should return GSS_S_FAILURE if this routine is called.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.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 -- required calls for -- release by caller are specific to language bindings 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. Note: some language bindings may employ an iterative approach in order to emit successive status components; this approach is acceptable but not required for conformance with the current specification. Although not contemplated in [RFC-2078], it has been observed that some existing GSS-API implementations return GSS_S_CONTINUE_NEEDED status when iterating through successive messages returned from GSS_Display_status(). This behavior is deprecated; GSS_S_CONTINUE_NEEDED should be returned only by GSS_Init_sec_context() and GSS_Accept_sec_context(). For maximal portability, however, it is recommended that defensive callers be able to accept and ignore GSS_S_CONTINUE_NEEDED status if indicated by GSS_Display_status() or any other call other than GSS_Init_sec_context() or GSS_Accept_sec_context().2.4.2: GSS_Indicate_mechs call
Input: o (none) Outputs: o major_status INTEGER, o minor_status INTEGER, o mech_set SET OF OBJECT IDENTIFIER -- caller must release -- with GSS_Release_oid_set() 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-API calls which accept input mechanism type specifiers.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 the two input names' types are different and incomparable, so that the comparison operation could not be completed. 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, -- caller must release -- with GSS_Release_buffer() o name_type OBJECT IDENTIFIER -- caller should treat -- as read-only; does not need to be released 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_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. 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. The GSS_C_NO_OID name type is to be returned only when the corresponding internal name was created through import with GSS_C_NO_OID. It is acceptable for mechanisms to normalize names imported with GSS_C_NO_OID into other supported types and, therefore, to display them with types other than GSS_C_NO_OID.
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 -- caller must release with -- GSS_Release_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_BAD_MECH indicates that the input presented for import was an exported name object and that its enclosed mechanism type was not recognized or was 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. 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. If the input_name_type's value is GSS_C_NO_OID, a mechanism-specific default printable syntax (which shall be specified in the corresponding GSS- V2 mechanism specification) is assumed for the input_name_string;
other input_name_type values as registered by GSS-API implementations
can be used to indicate specific non-default name syntaxes. Note: The
input_name_type argument serves to describe and qualify the
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. 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, implementation and invocation of this call may be superfluous (and may be omitted) 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, implementation and invocation of this call may be superfluous (and may be omitted) 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, 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, implementation and invocation of this call may be superfluous (and may be omitted) 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 -- caller must release -- with GSS_Release_oid_set() 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().
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
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_Inquire_names_for_mech call
Input: o input_mech_type OBJECT IDENTIFIER, -- mechanism type Outputs: o major_status INTEGER, o minor_status INTEGER, o name_type_set SET OF OBJECT IDENTIFIER -- caller must release -- with GSS_Release_oid_set() 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.13: 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 -- caller must release -- with GSS_Release_oid_set() 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 was ill-formed and could not be processed. o GSS_S_BAD_NAMETYPE indicates that the input_name parameter contained an invalid name type or a name type 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 returns the mechanism set with which the input_name may be processed. Each mechanism returned will recognize at least one element within the name. It is permissible for this routine to be implemented within a mechanism-independent GSS-API layer, using the type information contained within the presented name, and based on registration information provided by individual mechanism implementations. This means that the returned mech_types result may indicate that a particular mechanism will understand a particular name when in fact it would refuse to accept that name as input to GSS_Canonicalize_name(), GSS_Init_sec_context(), GSS_Acquire_cred(), or GSS_Add_cred(), due to some property of the particular name rather than a property of the name type. Thus, this routine should be used only as a pre-filter for a call to a subsequent mechanism-specific routine.2.4.14: GSS_Canonicalize_name call
Inputs: o input_name INTERNAL NAME, o mech_type OBJECT IDENTIFIER -- must be explicit mechanism, -- not "default" specifier or identifier of negotiating mechanism Outputs: o major_status INTEGER,
o minor_status INTEGER, o output_name INTERNAL NAME -- caller must release with -- GSS_Release_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 for this operation; this may correspond either to a mechanism wholly unsupported by the local GSS-API implementation or to a negotiating mechanism with which the canonicalization operation cannot be performed. 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. This routine reduces a GSS-API internal name input_name, which may in general contain elements corresponding to multiple mechanisms, to a mechanism-specific Mechanism Name (MN) output_name by applying the translations corresponding to the mechanism identified by mech_type. The contents of input_name are unaffected by the GSS_Canonicalize_name() operation. References to output_name will remain valid until output_name is released, independent of whether or not input_name is subsequently released.2.4.15: 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 -- caller must release -- with GSS_Release_buffer() 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. 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.16: GSS_Duplicate_name call
Inputs: o src_name INTERNAL NAME
Outputs: o major_status INTEGER, o minor_status INTEGER, o dest_name INTERNAL NAME -- caller must release -- with GSS_Release_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_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.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:
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.
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
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. The Object Identifier
value to indicate names of this type is defined in Section 4.7 of
this document.
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.
The bytes within MECH_OID_LEN and NAME_LEN elements are represented
most significant byte first (equivalently, in IP network byte order).
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.
A concrete example of the contents of an exported name object,
derived from the Kerberos Version 5 mechanism, is as follows:
04 01 00 0B 06 09 2A 86 48 86 F7 12 01 02 02 hx xx xx xl pp qq ... zz
04 01 mandatory token identifier
00 0B 2-byte length of the immediately following DER-encoded
ASN.1 value of type OID, most significant octet first
06 09 2A 86 48 86 F7 12 01 02 02 DER-encoded ASN.1 value
of type OID; Kerberos V5
mechanism OID indicates
Kerberos V5 exported name
in Detail: 06 Identifier octet (6=OID)
09 Length octet(s)
2A 86 48 86 F7 12 01 02 02 Content octet(s)
hx xx xx xl 4-byte length of the immediately following exported
name blob, most significant octet first
pp qq ... zz exported name blob of specified length,
bits and bytes specified in the
(Kerberos 5) GSS-API v2 mechanism spec
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
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) service_name(4)}.
The recommended symbolic name for this type is
"GSS_C_NT_HOSTBASED_SERVICE".
For reasons of compatibility with existing implementations, it is
recommended that this OID be used rather than the alternate value as
included in [RFC-2078]:
{1(iso), 3(org), 6(dod), 1(internet), 5(security), 6(nametypes),
2(gss-host-based-services)}
While it is not recommended that this alternate value be emitted on
output by GSS implementations, it is recommended that it be accepted
on input as equivalent to the recommended value.
This name type is used to represent services associated with host
computers. Support for this name form is recommended to mechanism
designers in the interests of portability, but is not mandated by
this specification. 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"
may (as an example implementation strategy) be 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.
Documents specifying means for GSS integration into a particular
protocol should state either:
(a) that a specific IANA-registered name associated with that
protocol shall be used for the "service" element (this admits, if
needed, the possibility that a single name can be registered and
shared among a related set of protocols), or
(b) that the generic name "host" shall be used for the "service"
element, or
(c) that, for that protocol, fallback in specified order (a, then
b) or (b, then a) shall be applied.
IANA registration of specific names per (a) should be handled in
accordance with the "Specification Required" assignment policy,
defined by BCP 26, RFC 2434 as follows: "Values and their meaning
must be documented in an RFC or other available reference, in
sufficient detail so that interoperability between independent
implementations is possible."
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 syntax and interpretation may be OS-specific. This name form is constructed as: username4.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 user ID, 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 user ID.4.5: Anonymous Nametype
The following Object Identifier value is provided as a means to identify anonymous names, and can be compared against in order to determine, in a mechanism-independent fashion, whether a name refers to an anonymous principal:
{1(iso), 3(org), 6(dod), 1(internet), 5(security), 6(nametypes),
3(gss-anonymous-name)}
The recommended symbolic name corresponding to this definition is
GSS_C_NT_ANONYMOUS.
4.6: GSS_C_NO_OID
The recommended symbolic name GSS_C_NO_OID corresponds to a null
input value instead of an actual object identifier. Where specified,
it indicates interpretation of an associated name based on a
mechanism-specific default printable syntax.
4.7: Exported Name Object
Name objects of the Mechanism-Independent Exported Name Object type,
as defined in Section 3.2 of this document, 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)}
The recommended symbolic name corresponding to this definition is
GSS_C_NT_EXPORT_NAME.
4.8: GSS_C_NO_NAME
The recommended symbolic name GSS_C_NO_NAME indicates that no name is
being passed within a particular value of a parameter used for the
purpose of transferring names. Note: GSS_C_NO_NAME is not an actual
name type, and is not represented by an OID; its acceptability in
lieu of an actual name is confined to specific calls
(GSS_Acquire_cred(), GSS_Add_cred(), and GSS_Init_sec_context()) with
usages as identified within this specification.
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
This document specifies a service interface for security facilities and services; as such, security considerations are considered throughout the specification. Nonetheless, it is appropriate to summarize certain specific points relevant to GSS-API implementors and calling applications. Usage of the GSS-API interface does not in itself provide security services or assurance; instead, these attributes are dependent on the underlying mechanism(s) which support a GSS-API implementation. Callers must be attentive to the requests made to GSS-API calls and to the status indicators returned by GSS- API, as these specify the security service characteristics which GSS-API will provide. When the interprocess context transfer facility is used, appropriate local controls should be applied to constrain access to interprocess tokens and to the sensitive data which they contain.
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. C Language bindings for GSS-V2 are defined in [RFC-2744].
(next page on part 4)
