tech-invite   World Map     

3GPP     Specs     Glossaries     Architecture     IMS     UICC       IETF     RFCs     Groups     SIP     ABNFs       Search

RFC 2744

 
 
 

Generic Security Service API Version 2 : C-bindings

Part 4 of 4, p. 75 to 101
Prev RFC Part

 


prevText      Top       Page 75 
5.30. gss_test_oid_set_member

   OM_uint32 gss_test_oid_set_member (
     OM_uint32         *minor_status,
     const gss_OID     member,
     const gss_OID_set set,
     int               *present)

   Purpose:

   Interrogate 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(), but will also work with user-generated sets.

   Parameters:

   minor_status      Integer, modify
                     Mechanism specific status code

   member            Object ID, read
                     The object identifier whose presence
                     is to be tested.

   set               Set of Object ID, read
                     The Object Identifier set.

   present           Boolean, modify
                     non-zero if the specified OID is a member
                     of the set, zero if not.

   Function value:   GSS status code

   GSS_S_COMPLETE    Successful completion

Top       Page 76 
5.31. gss_unwrap

   OM_uint32 gss_unwrap (
     OM_uint32          *minor_status,
     const gss_ctx_id_t context_handle,
     const gss_buffer_t input_message_buffer,
     gss_buffer_t       output_message_buffer,
     int                *conf_state,
     gss_qop_t          *qop_state)

   Purpose:

   Converts a message previously protected by gss_wrap back to a usable
   form, verifying the embedded MIC.  The conf_state parameter indicates
   whether the message was encrypted; the qop_state parameter indicates
   the strength of protection that was used to provide the
   confidentiality and integrity services.

   Since some application-level protocols may wish to use tokens emitted
   by gss_wrap() to provide "secure framing", implementations must
   support the wrapping and unwrapping of zero-length messages.

   Parameters:

   minor_status      Integer, modify
                     Mechanism specific status code.

   context_handle    gss_ctx_id_t, read
                     Identifies the context on which the message
                     arrived

   input_message_buffer  buffer, opaque, read
                     protected message

   output_message_buffer  buffer, opaque, modify
                     Buffer to receive unwrapped message.
                     Storage associated with this buffer must
                     be freed by the application after use use
                     with a call to gss_release_buffer().

   conf_state        boolean, modify, optional
                     Non-zero - Confidentiality and integrity
                                protection were used
                     Zero - Integrity service only was used
                     Specify NULL if not required

Top       Page 77 
   qop_state         gss_qop_t, modify, optional
                     Quality of protection provided.
                     Specify NULL if not required

   Function value:   GSS status code

   GSS_S_COMPLETE    Successful completion

   GSS_S_DEFECTIVE_TOKEN The token failed consistency checks

   GSS_S_BAD_SIG     The MIC was incorrect

   GSS_S_DUPLICATE_TOKEN The token was valid, and contained a correct
                         MIC for the message, but it had already been
                         processed

   GSS_S_OLD_TOKEN   The token was valid, and contained a correct MIC
                     for the message, but it is too old to check for
                     duplication.

   GSS_S_UNSEQ_TOKEN The token was valid, and contained a correct MIC
                     for the message, but has been verified out of
                     sequence; a later token has already been
                     received.

   GSS_S_GAP_TOKEN   The token was valid, and contained a correct MIC
                     for the message, but has been verified out of
                     sequence; an earlier expected token has not yet
                     been received.

   GSS_S_CONTEXT_EXPIRED The context has already expired

   GSS_S_NO_CONTEXT  The context_handle parameter did not identify
                     a valid context

5.32. gss_verify_mic

   OM_uint32 gss_verify_mic (
     OM_uint32          *minor_status,
     const gss_ctx_id_t context_handle,
     const gss_buffer_t message_buffer,
     const gss_buffer_t token_buffer,
     gss_qop_t          *qop_state)

Top       Page 78 
   Purpose:

   Verifies that a cryptographic MIC, contained in the token parameter,
   fits the supplied message.  The qop_state parameter allows a message
   recipient to determine the strength of protection that was applied to
   the message.

   Since some application-level protocols may wish to use tokens emitted
   by gss_wrap() to provide "secure framing", implementations must
   support the calculation and verification of MICs over zero-length
   messages.

   Parameters:

   minor_status      Integer, modify
                     Mechanism specific status code.

   context_handle    gss_ctx_id_t, read
                     Identifies the context on which the message
                     arrived

   message_buffer    buffer, opaque, read
                     Message to be verified

   token_buffer      buffer, opaque, read
                     Token associated with message

   qop_state         gss_qop_t, modify, optional
                     quality of protection gained from MIC
                     Specify NULL if not required

   Function value:   GSS status code

   GSS_S_COMPLETE    Successful completion

   GSS_S_DEFECTIVE_TOKEN The token failed consistency checks

   GSS_S_BAD_SIG     The MIC was incorrect

   GSS_S_DUPLICATE_TOKEN The token was valid, and contained a correct
                     MIC for the message, but it had already been
                     processed

   GSS_S_OLD_TOKEN   The token was valid, and contained a correct MIC
                     for the message, but it is too old to check for
                     duplication.

Top       Page 79 
   GSS_S_UNSEQ_TOKEN The token was valid, and contained a correct MIC
                     for the message, but has been verified out of
                     sequence; a later token has already been received.

   GSS_S_GAP_TOKEN   The token was valid, and contained a correct MIC
                     for the message, but has been verified out of
                     sequence; an earlier expected token has not yet
                     been received.

   GSS_S_CONTEXT_EXPIRED The context has already expired

   GSS_S_NO_CONTEXT  The context_handle parameter did not identify a
                     valid context

5.33. gss_wrap

   OM_uint32 gss_wrap (
     OM_uint32          *minor_status,
     const gss_ctx_id_t context_handle,
     int               conf_req_flag,
     gss_qop_t          qop_req
     const gss_buffer_t input_message_buffer,
     int                *conf_state,
     gss_buffer_t       output_message_buffer )

   Purpose:

   Attaches a cryptographic MIC and optionally encrypts the specified
   input_message.  The output_message contains both the MIC and the
   message.  The qop_req parameter allows a choice between several
   cryptographic algorithms, if supported by the chosen mechanism.

   Since some application-level protocols may wish to use tokens emitted
   by gss_wrap() to provide "secure framing", implementations must
   support the wrapping of zero-length messages.

   Parameters:

   minor_status      Integer, modify
                     Mechanism specific status code.

   context_handle    gss_ctx_id_t, read
                     Identifies the context on which the message
                     will be sent

Top       Page 80 
   conf_req_flag     boolean, read
                     Non-zero - Both confidentiality and integrity
                                services are requested
                     Zero - Only integrity service is requested

   qop_req           gss_qop_t, read, optional
                     Specifies required quality of protection.  A
                     mechanism-specific default may be requested by
                     setting qop_req to GSS_C_QOP_DEFAULT.  If an
                     unsupported protection strength is requested,
                     gss_wrap will return a major_status of
                     GSS_S_BAD_QOP.

   input_message_buffer  buffer, opaque, read
                     Message to be protected

   conf_state        boolean, modify, optional
                     Non-zero - Confidentiality, data origin
                                authentication and integrity
                                services have been applied
                     Zero - Integrity and data origin services only
                            has been applied.
                     Specify NULL if not required

   output_message_buffer  buffer, opaque, modify
                     Buffer to receive protected message.
                     Storage associated with this message must
                     be freed by the application after use with
                     a call to gss_release_buffer().

   Function value:   GSS status code

   GSS_S_COMPLETE    Successful completion

   GSS_S_CONTEXT_EXPIRED The context has already expired

   GSS_S_NO_CONTEXT  The context_handle parameter did not identify a
                     valid context

   GSS_S_BAD_QOP     The specified QOP is not supported by the
                     mechanism.

Top       Page 81 
5.34. gss_wrap_size_limit

   OM_uint32 gss_wrap_size_limit (
     OM_uint32          *minor_status,
     const gss_ctx_id_t context_handle,
     int                conf_req_flag,
     gss_qop_t          qop_req,
     OM_uint32          req_output_size,
     OM_uint32          *max_input_size)

   Purpose:

   Allows an application to determine the maximum message size that, if
   presented to gss_wrap with the same conf_req_flag and qop_req
   parameters, will result in an output token containing no more than
   req_output_size bytes.

   This call is intended for use by applications that communicate over
   protocols that impose a maximum message size.  It enables the
   application to fragment messages prior to applying protection.

   GSS-API implementations are recommended but not required to detect
   invalid QOP values when gss_wrap_size_limit() is called. This routine
   guarantees only a maximum message size, not the availability of
   specific QOP values for message protection.

   Successful completion of this call does not guarantee that gss_wrap
   will be able to protect a message of length max_input_size bytes,
   since this ability may depend on the availability of system resources
   at the time that gss_wrap is called.  However, if the implementation
   itself imposes an upper limit on the length of messages that may be
   processed by gss_wrap, the implementation should not return a value
   via max_input_bytes that is greater than this length.

   Parameters:

   minor_status      Integer, modify
                     Mechanism specific status code

   context_handle    gss_ctx_id_t, read
                     A handle that refers to the security over
                     which the messages will be sent.

   conf_req_flag     Boolean, read
                     Indicates whether gss_wrap will be asked
                     to apply confidentiality protection in

Top       Page 82 
                     addition to integrity protection.  See
                     the routine description for gss_wrap
                     for more details.

   qop_req           gss_qop_t, read
                     Indicates the level of protection that
                     gss_wrap will be asked to provide.  See
                     the routine description for gss_wrap for
                     more details.

   req_output_size   Integer, read
                     The desired maximum size for tokens emitted
                     by gss_wrap.

   max_input_size    Integer, modify
                     The maximum input message size that may
                     be presented to gss_wrap in order to
                     guarantee that the emitted token shall
                     be no larger than req_output_size bytes.

   Function value:   GSS status code

   GSS_S_COMPLETE    Successful completion

   GSS_S_NO_CONTEXT  The referenced context could not be accessed.

   GSS_S_CONTEXT_EXPIRED The context has expired.

   GSS_S_BAD_QOP     The specified QOP is not supported by the
                     mechanism.

6.   Security Considerations

   This document specifies a service interface for security facilities
   and services; as such, security considerations appear 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.

Top       Page 83 
Appendix A. GSS-API C header file gssapi.h

   C-language GSS-API implementations should include a copy of the
   following header-file.

   #ifndef GSSAPI_H_
   #define GSSAPI_H_



   /*
    * First, include stddef.h to get size_t defined.
    */
   #include <stddef.h>

   /*
    * If the platform supports the xom.h header file, it should be
    * included here.
    */
   #include <xom.h>


   /*
    * Now define the three implementation-dependent types.
    */
   typedef <platform-specific> gss_ctx_id_t;
   typedef <platform-specific> gss_cred_id_t;
   typedef <platform-specific> gss_name_t;

   /*
    * The following type must be defined as the smallest natural
    * unsigned integer supported by the platform that has at least
    * 32 bits of precision.
    */
   typedef <platform-specific> gss_uint32;


   #ifdef OM_STRING
   /*
    * We have included the xom.h header file.  Verify that OM_uint32
    * is defined correctly.
    */

   #if sizeof(gss_uint32) != sizeof(OM_uint32)
   #error Incompatible definition of OM_uint32 from xom.h
   #endif

   typedef OM_object_identifier gss_OID_desc, *gss_OID;

Top       Page 84 
   #else

   /*
    * We can't use X/Open definitions, so roll our own.
    */

   typedef gss_uint32 OM_uint32;

   typedef struct gss_OID_desc_struct {
     OM_uint32 length;
     void      *elements;
   } gss_OID_desc, *gss_OID;

   #endif

   typedef struct gss_OID_set_desc_struct  {
     size_t     count;
     gss_OID    elements;
   } gss_OID_set_desc, *gss_OID_set;

   typedef struct gss_buffer_desc_struct {
     size_t length;
     void *value;
   } gss_buffer_desc, *gss_buffer_t;

   typedef struct gss_channel_bindings_struct {
     OM_uint32 initiator_addrtype;
     gss_buffer_desc initiator_address;
     OM_uint32 acceptor_addrtype;
     gss_buffer_desc acceptor_address;
     gss_buffer_desc application_data;
   } *gss_channel_bindings_t;

   /*
    * For now, define a QOP-type as an OM_uint32
    */
   typedef OM_uint32 gss_qop_t;

   typedef int gss_cred_usage_t;

   /*
    * Flag bits for context-level services.
    */

Top       Page 85 
   #define GSS_C_DELEG_FLAG      1
   #define GSS_C_MUTUAL_FLAG     2
   #define GSS_C_REPLAY_FLAG     4
   #define GSS_C_SEQUENCE_FLAG   8
   #define GSS_C_CONF_FLAG       16
   #define GSS_C_INTEG_FLAG      32
   #define GSS_C_ANON_FLAG       64
   #define GSS_C_PROT_READY_FLAG 128
   #define GSS_C_TRANS_FLAG      256

   /*
    * Credential usage options
    */
   #define GSS_C_BOTH     0
   #define GSS_C_INITIATE 1
   #define GSS_C_ACCEPT   2

   /*
    * Status code types for gss_display_status
    */
   #define GSS_C_GSS_CODE  1
   #define GSS_C_MECH_CODE 2

   /*
    * The constant definitions for channel-bindings address families
    */
   #define GSS_C_AF_UNSPEC     0
   #define GSS_C_AF_LOCAL      1
   #define GSS_C_AF_INET       2
   #define GSS_C_AF_IMPLINK    3
   #define GSS_C_AF_PUP        4
   #define GSS_C_AF_CHAOS      5
   #define GSS_C_AF_NS         6
   #define GSS_C_AF_NBS        7
   #define GSS_C_AF_ECMA       8
   #define GSS_C_AF_DATAKIT    9
   #define GSS_C_AF_CCITT      10
   #define GSS_C_AF_SNA        11
   #define GSS_C_AF_DECnet     12
   #define GSS_C_AF_DLI        13
   #define GSS_C_AF_LAT        14
   #define GSS_C_AF_HYLINK     15
   #define GSS_C_AF_APPLETALK  16
   #define GSS_C_AF_BSC        17
   #define GSS_C_AF_DSS        18
   #define GSS_C_AF_OSI        19
   #define GSS_C_AF_X25        21

Top       Page 86 
   #define GSS_C_AF_NULLADDR   255

   /*
    * Various Null values
    */
   #define GSS_C_NO_NAME ((gss_name_t) 0)
   #define GSS_C_NO_BUFFER ((gss_buffer_t) 0)
   #define GSS_C_NO_OID ((gss_OID) 0)
   #define GSS_C_NO_OID_SET ((gss_OID_set) 0)
   #define GSS_C_NO_CONTEXT ((gss_ctx_id_t) 0)
   #define GSS_C_NO_CREDENTIAL ((gss_cred_id_t) 0)
   #define GSS_C_NO_CHANNEL_BINDINGS ((gss_channel_bindings_t) 0)
   #define GSS_C_EMPTY_BUFFER {0, NULL}

   /*
    * Some alternate names for a couple of the above
    * values.  These are defined for V1 compatibility.
    */
   #define GSS_C_NULL_OID GSS_C_NO_OID
   #define GSS_C_NULL_OID_SET GSS_C_NO_OID_SET

   /*
    * Define the default Quality of Protection for per-message
    * services.  Note that an implementation that offers multiple
    * levels of QOP may define GSS_C_QOP_DEFAULT to be either zero
    * (as done here) to mean "default protection", or to a specific
    * explicit QOP value.  However, a value of 0 should always be
    * interpreted by a GSS-API implementation as a request for the
    * default protection level.
    */
   #define GSS_C_QOP_DEFAULT 0

   /*
    * Expiration time of 2^32-1 seconds means infinite lifetime for a
    * credential or security context
    */
   #define GSS_C_INDEFINITE 0xfffffffful

   /*
    * The implementation must reserve static storage for a
    * gss_OID_desc object containing the value
    * {10, (void *)"\x2a\x86\x48\x86\xf7\x12"
    * "\x01\x02\x01\x01"},
    * corresponding to an object-identifier value of
    * {iso(1) member-body(2) United States(840) mit(113554)
    * infosys(1) gssapi(2) generic(1) user_name(1)}.  The constant
    * GSS_C_NT_USER_NAME should be initialized to point
    * to that gss_OID_desc.

Top       Page 87 
    */
   extern gss_OID GSS_C_NT_USER_NAME;

   /*
    * The implementation must reserve static storage for a
    * gss_OID_desc object containing the value
    * {10, (void *)"\x2a\x86\x48\x86\xf7\x12"
    *              "\x01\x02\x01\x02"},
    * corresponding to an object-identifier value of
    * {iso(1) member-body(2) United States(840) mit(113554)
    * infosys(1) gssapi(2) generic(1) machine_uid_name(2)}.
    * The constant GSS_C_NT_MACHINE_UID_NAME should be
    * initialized to point to that gss_OID_desc.
    */
   extern gss_OID GSS_C_NT_MACHINE_UID_NAME;

   /*
    * The implementation must reserve static storage for a
    * gss_OID_desc object containing the value
    * {10, (void *)"\x2a\x86\x48\x86\xf7\x12"
    *              "\x01\x02\x01\x03"},
    * corresponding to an object-identifier value of
    * {iso(1) member-body(2) United States(840) mit(113554)
    * infosys(1) gssapi(2) generic(1) string_uid_name(3)}.
    * The constant GSS_C_NT_STRING_UID_NAME should be
    * initialized to point to that gss_OID_desc.
    */
   extern gss_OID GSS_C_NT_STRING_UID_NAME;

   /*
    * The implementation must reserve static storage for a
    * gss_OID_desc object containing the value
    * {6, (void *)"\x2b\x06\x01\x05\x06\x02"},
    * corresponding to an object-identifier value of
    * {iso(1) org(3) dod(6) internet(1) security(5)
    * nametypes(6) gss-host-based-services(2)).  The constant
    * GSS_C_NT_HOSTBASED_SERVICE_X should be initialized to point
    * to that gss_OID_desc.  This is a deprecated OID value, and
    * implementations wishing to support hostbased-service names
    * should instead use the GSS_C_NT_HOSTBASED_SERVICE OID,
    * defined below, to identify such names;
    * GSS_C_NT_HOSTBASED_SERVICE_X should be accepted a synonym
    * for GSS_C_NT_HOSTBASED_SERVICE when presented as an input
    * parameter, but should not be emitted by GSS-API
    * implementations
    */
   extern gss_OID GSS_C_NT_HOSTBASED_SERVICE_X;

Top       Page 88 
   /*
    * The implementation must reserve static storage for a
    * gss_OID_desc object containing the value
    * {10, (void *)"\x2a\x86\x48\x86\xf7\x12"
    *              "\x01\x02\x01\x04"}, corresponding to an
    * object-identifier value of {iso(1) member-body(2)
    * Unites States(840) mit(113554) infosys(1) gssapi(2)
    * generic(1) service_name(4)}.  The constant
    * GSS_C_NT_HOSTBASED_SERVICE should be initialized
    * to point to that gss_OID_desc.
    */
   extern gss_OID GSS_C_NT_HOSTBASED_SERVICE;

   /*
    * The implementation must reserve static storage for a
    * gss_OID_desc object containing the value
    * {6, (void *)"\x2b\x06\01\x05\x06\x03"},
    * corresponding to an object identifier value of
    * {1(iso), 3(org), 6(dod), 1(internet), 5(security),
    * 6(nametypes), 3(gss-anonymous-name)}.  The constant
    * and GSS_C_NT_ANONYMOUS should be initialized to point
    * to that gss_OID_desc.
    */
   extern gss_OID GSS_C_NT_ANONYMOUS;


   /*
    * The implementation must reserve static storage for a
    * gss_OID_desc object containing the value
    * {6, (void *)"\x2b\x06\x01\x05\x06\x04"},
    * corresponding to an object-identifier value of
    * {1(iso), 3(org), 6(dod), 1(internet), 5(security),
    * 6(nametypes), 4(gss-api-exported-name)}.  The constant
    * GSS_C_NT_EXPORT_NAME should be initialized to point
    * to that gss_OID_desc.
    */
   extern gss_OID GSS_C_NT_EXPORT_NAME;


   /* Major status codes */

   #define GSS_S_COMPLETE 0

   /*
    * Some "helper" definitions to make the status code macros obvious.
    */
   #define GSS_C_CALLING_ERROR_OFFSET 24
   #define GSS_C_ROUTINE_ERROR_OFFSET 16

Top       Page 89 
   #define GSS_C_SUPPLEMENTARY_OFFSET 0
   #define GSS_C_CALLING_ERROR_MASK 0377ul
   #define GSS_C_ROUTINE_ERROR_MASK 0377ul
   #define GSS_C_SUPPLEMENTARY_MASK 0177777ul

   /*
    * The macros that test status codes for error conditions.
    * Note that the GSS_ERROR() macro has changed slightly from
    * the V1 GSS-API so that it now evaluates its argument
    * only once.
    */
   #define GSS_CALLING_ERROR(x) \
    (x & (GSS_C_CALLING_ERROR_MASK << GSS_C_CALLING_ERROR_OFFSET))
   #define GSS_ROUTINE_ERROR(x) \
    (x & (GSS_C_ROUTINE_ERROR_MASK << GSS_C_ROUTINE_ERROR_OFFSET))
   #define GSS_SUPPLEMENTARY_INFO(x) \
    (x & (GSS_C_SUPPLEMENTARY_MASK << GSS_C_SUPPLEMENTARY_OFFSET))
   #define GSS_ERROR(x) \
    (x & ((GSS_C_CALLING_ERROR_MASK << GSS_C_CALLING_ERROR_OFFSET) | \
          (GSS_C_ROUTINE_ERROR_MASK << GSS_C_ROUTINE_ERROR_OFFSET)))

   /*
    * Now the actual status code definitions
    */

   /*
    * Calling errors:

    */
   #define GSS_S_CALL_INACCESSIBLE_READ \
   (1ul << GSS_C_CALLING_ERROR_OFFSET)
   #define GSS_S_CALL_INACCESSIBLE_WRITE \
   (2ul << GSS_C_CALLING_ERROR_OFFSET)
   #define GSS_S_CALL_BAD_STRUCTURE \
   (3ul << GSS_C_CALLING_ERROR_OFFSET)

   /*
    * Routine errors:
    */
   #define GSS_S_BAD_MECH             (1ul <<
   GSS_C_ROUTINE_ERROR_OFFSET)
   #define GSS_S_BAD_NAME             (2ul <<
   GSS_C_ROUTINE_ERROR_OFFSET)
   #define GSS_S_BAD_NAMETYPE         (3ul <<
   GSS_C_ROUTINE_ERROR_OFFSET)
   #define GSS_S_BAD_BINDINGS         (4ul <<
   GSS_C_ROUTINE_ERROR_OFFSET)
   #define GSS_S_BAD_STATUS           (5ul <<

Top       Page 90 
   GSS_C_ROUTINE_ERROR_OFFSET)
   #define GSS_S_BAD_SIG              (6ul <<
   GSS_C_ROUTINE_ERROR_OFFSET)
   #define GSS_S_BAD_MIC GSS_S_BAD_SIG
   #define GSS_S_NO_CRED              (7ul <<
   GSS_C_ROUTINE_ERROR_OFFSET)
   #define GSS_S_NO_CONTEXT           (8ul <<
   GSS_C_ROUTINE_ERROR_OFFSET)
   #define GSS_S_DEFECTIVE_TOKEN      (9ul <<
   GSS_C_ROUTINE_ERROR_OFFSET)
   #define GSS_S_DEFECTIVE_CREDENTIAL (10ul <<
   GSS_C_ROUTINE_ERROR_OFFSET)
   #define GSS_S_CREDENTIALS_EXPIRED  (11ul <<
   GSS_C_ROUTINE_ERROR_OFFSET)
   #define GSS_S_CONTEXT_EXPIRED      (12ul <<
   GSS_C_ROUTINE_ERROR_OFFSET)
   #define GSS_S_FAILURE              (13ul <<
   GSS_C_ROUTINE_ERROR_OFFSET)
   #define GSS_S_BAD_QOP              (14ul <<
   GSS_C_ROUTINE_ERROR_OFFSET)
   #define GSS_S_UNAUTHORIZED         (15ul <<
   GSS_C_ROUTINE_ERROR_OFFSET)
   #define GSS_S_UNAVAILABLE          (16ul <<
   GSS_C_ROUTINE_ERROR_OFFSET)
   #define GSS_S_DUPLICATE_ELEMENT    (17ul <<
   GSS_C_ROUTINE_ERROR_OFFSET)
   #define GSS_S_NAME_NOT_MN          (18ul <<
   GSS_C_ROUTINE_ERROR_OFFSET)

   /*
    * Supplementary info bits:
    */
   #define GSS_S_CONTINUE_NEEDED \
            (1ul << (GSS_C_SUPPLEMENTARY_OFFSET + 0))
   #define GSS_S_DUPLICATE_TOKEN \
            (1ul << (GSS_C_SUPPLEMENTARY_OFFSET + 1))
   #define GSS_S_OLD_TOKEN \
            (1ul << (GSS_C_SUPPLEMENTARY_OFFSET + 2))
   #define GSS_S_UNSEQ_TOKEN \
            (1ul << (GSS_C_SUPPLEMENTARY_OFFSET + 3))
   #define GSS_S_GAP_TOKEN \
            (1ul << (GSS_C_SUPPLEMENTARY_OFFSET + 4))

   /*
    * Finally, function prototypes for the GSS-API routines.
    */

Top       Page 91 
   OM_uint32 gss_acquire_cred
                 (OM_uint32 ,             /*  minor_status */
                  const gss_name_t,       /* desired_name */
                  OM_uint32,              /* time_req */
                  const gss_OID_set,      /* desired_mechs */
                  gss_cred_usage_t,       /* cred_usage */
                  gss_cred_id_t ,         /* output_cred_handle */
                  gss_OID_set ,           /* actual_mechs */
                  OM_uint32 *             /* time_rec */
                 );

   OM_uint32 gss_release_cred
                 (OM_uint32 ,             /* minor_status */
                  gss_cred_id_t *         /* cred_handle */
                 );

   OM_uint32 gss_init_sec_context
                 (OM_uint32 ,             /* minor_status */
                  const gss_cred_id_t,    /* initiator_cred_handle */
                  gss_ctx_id_t ,          /* context_handle */
                  const gss_name_t,       /* target_name */
                  const gss_OID,          /* mech_type */
                  OM_uint32,              /* req_flags */
                  OM_uint32,              /* time_req */
                  const gss_channel_bindings_t,
                                          /* input_chan_bindings */
                  const gss_buffer_t,     /* input_token */
                  gss_OID ,               /* actual_mech_type */
                  gss_buffer_t,           /* output_token */
                  OM_uint32 ,             /* ret_flags */
                  OM_uint32 *             /* time_rec */
                 );

   OM_uint32 gss_accept_sec_context
                 (OM_uint32 ,             /* minor_status */
                  gss_ctx_id_t ,          /* context_handle */
                  const gss_cred_id_t,    /* acceptor_cred_handle */
                  const gss_buffer_t,     /* input_token_buffer */
                  const gss_channel_bindings_t,
                                          /* input_chan_bindings */
                  gss_name_t ,            /* src_name */
                  gss_OID ,               /* mech_type */
                  gss_buffer_t,           /* output_token */
                  OM_uint32 ,             /* ret_flags */
                  OM_uint32 ,             /* time_rec */
                  gss_cred_id_t *         /* delegated_cred_handle */
                 );

Top       Page 92 
   OM_uint32 gss_process_context_token
                 (OM_uint32 ,             /* minor_status */
                  const gss_ctx_id_t,     /* context_handle */
                  const gss_buffer_t      /* token_buffer */
                 );

   OM_uint32 gss_delete_sec_context
                 (OM_uint32 ,             /* minor_status */
                  gss_ctx_id_t ,          /* context_handle */
                  gss_buffer_t            /* output_token */
                 );

   OM_uint32 gss_context_time
                 (OM_uint32 ,             /* minor_status */
                  const gss_ctx_id_t,     /* context_handle */
                  OM_uint32 *             /* time_rec */
                 );

   OM_uint32 gss_get_mic
                 (OM_uint32 ,             /* minor_status */
                  const gss_ctx_id_t,     /* context_handle */
                  gss_qop_t,              /* qop_req */
                  const gss_buffer_t,     /* message_buffer */
                  gss_buffer_t            /* message_token */
                 );

   OM_uint32 gss_verify_mic
                 (OM_uint32 ,             /* minor_status */
                  const gss_ctx_id_t,     /* context_handle */
                  const gss_buffer_t,     /* message_buffer */
                  const gss_buffer_t,     /* token_buffer */
                  gss_qop_t *             /* qop_state */
                 );

   OM_uint32 gss_wrap
                 (OM_uint32 ,             /* minor_status */
                  const gss_ctx_id_t,     /* context_handle */
                  int,                    /* conf_req_flag */
                  gss_qop_t,              /* qop_req */
                  const gss_buffer_t,     /* input_message_buffer */
                  int ,                   /* conf_state */
                  gss_buffer_t            /* output_message_buffer */
                 );

Top       Page 93 
   OM_uint32 gss_unwrap
                 (OM_uint32 ,             /* minor_status */
                  const gss_ctx_id_t,     /* context_handle */
                  const gss_buffer_t,     /* input_message_buffer */
                  gss_buffer_t,           /* output_message_buffer */
                  int ,                   /* conf_state */
                  gss_qop_t *             /* qop_state */
                 );



   OM_uint32 gss_display_status
                 (OM_uint32 ,             /* minor_status */
                  OM_uint32,              /* status_value */
                  int,                    /* status_type */
                  const gss_OID,          /* mech_type */
                  OM_uint32 ,             /* message_context */
                  gss_buffer_t            /* status_string */
                 );

   OM_uint32 gss_indicate_mechs
                 (OM_uint32 ,             /* minor_status */
                  gss_OID_set *           /* mech_set */
                 );

   OM_uint32 gss_compare_name
                 (OM_uint32 ,             /* minor_status */
                  const gss_name_t,       /* name1 */
                  const gss_name_t,       /* name2 */
                  int *                   /* name_equal */
                 );

   OM_uint32 gss_display_name
                 (OM_uint32 ,             /* minor_status */
                  const gss_name_t,       /* input_name */
                  gss_buffer_t,           /* output_name_buffer */
                  gss_OID *               /* output_name_type */
                 );

   OM_uint32 gss_import_name
                 (OM_uint32 ,             /* minor_status */
                  const gss_buffer_t,     /* input_name_buffer */
                  const gss_OID,          /* input_name_type */
                  gss_name_t *            /* output_name */
                 );

Top       Page 94 
   OM_uint32 gss_export_name
                 (OM_uint32,              /* minor_status */
                  const gss_name_t,       /* input_name */
                  gss_buffer_t            /* exported_name */
                 );

   OM_uint32 gss_release_name
                 (OM_uint32 *,            /* minor_status */
                  gss_name_t *            /* input_name */
                 );

   OM_uint32 gss_release_buffer
                 (OM_uint32 ,             /* minor_status */
                  gss_buffer_t            /* buffer */
                 );

   OM_uint32 gss_release_oid_set
                 (OM_uint32 ,             /* minor_status */
                  gss_OID_set *           /* set */
                 );

   OM_uint32 gss_inquire_cred
                 (OM_uint32 ,             /* minor_status */
                  const gss_cred_id_t,    /* cred_handle */
                  gss_name_t ,            /* name */
                  OM_uint32 ,             /* lifetime */
                  gss_cred_usage_t ,      /* cred_usage */
                  gss_OID_set *           /* mechanisms */
                 );

   OM_uint32 gss_inquire_context (
                  OM_uint32 ,             /* minor_status */
                  const gss_ctx_id_t,     /* context_handle */
                  gss_name_t ,            /* src_name */
                  gss_name_t ,            /* targ_name */
                  OM_uint32 ,             /* lifetime_rec */
                  gss_OID ,               /* mech_type */
                  OM_uint32 ,             /* ctx_flags */
                  int ,                   /* locally_initiated */
                  int *                   /* open */
                 );

Top       Page 95 
   OM_uint32 gss_wrap_size_limit (
                  OM_uint32 ,             /* minor_status */
                  const gss_ctx_id_t,     /* context_handle */
                  int,                    /* conf_req_flag */
                  gss_qop_t,              /* qop_req */
                  OM_uint32,              /* req_output_size */
                  OM_uint32 *             /* max_input_size */
                 );

   OM_uint32 gss_add_cred (
                  OM_uint32 ,             /* minor_status */
                  const gss_cred_id_t,    /* input_cred_handle */
                  const gss_name_t,       /* desired_name */
                  const gss_OID,          /* desired_mech */
                  gss_cred_usage_t,       /* cred_usage */
                  OM_uint32,              /* initiator_time_req */
                  OM_uint32,              /* acceptor_time_req */
                  gss_cred_id_t ,         /* output_cred_handle */
                  gss_OID_set ,           /* actual_mechs */
                  OM_uint32 ,             /* initiator_time_rec */
                  OM_uint32 *             /* acceptor_time_rec */
                 );

   OM_uint32 gss_inquire_cred_by_mech (
                  OM_uint32 ,             /* minor_status */
                  const gss_cred_id_t,    /* cred_handle */
                  const gss_OID,          /* mech_type */
                  gss_name_t ,            /* name */
                  OM_uint32 ,             /* initiator_lifetime */
                  OM_uint32 ,             /* acceptor_lifetime */
                  gss_cred_usage_t *      /* cred_usage */
                 );

   OM_uint32 gss_export_sec_context (
                  OM_uint32 ,             /* minor_status */
                  gss_ctx_id_t ,          /* context_handle */
                  gss_buffer_t            /* interprocess_token */
                 );

   OM_uint32 gss_import_sec_context (
                  OM_uint32 ,             /* minor_status */
                  const gss_buffer_t,     /* interprocess_token */
                  gss_ctx_id_t *          /* context_handle */
                 );

Top       Page 96 
   OM_uint32 gss_create_empty_oid_set (
                  OM_uint32 ,             /* minor_status */
                  gss_OID_set *           /* oid_set */
                 );

   OM_uint32 gss_add_oid_set_member (
                  OM_uint32 ,             /* minor_status */
                  const gss_OID,          /* member_oid */
                  gss_OID_set *           /* oid_set */
                 );

   OM_uint32 gss_test_oid_set_member (
                  OM_uint32 ,             /* minor_status */
                  const gss_OID,          /* member */
                  const gss_OID_set,      /* set */
                  int *                   /* present */
                 );

   OM_uint32 gss_inquire_names_for_mech (
                  OM_uint32 ,             /* minor_status */
                  const gss_OID,          /* mechanism */
                  gss_OID_set *           /* name_types */
                 );

   OM_uint32 gss_inquire_mechs_for_name (
                  OM_uint32 ,             /* minor_status */
                  const gss_name_t,       /* input_name */
                  gss_OID_set *           /* mech_types */
                 );

   OM_uint32 gss_canonicalize_name (
                  OM_uint32 ,             /* minor_status */
                  const gss_name_t,       /* input_name */
                  const gss_OID,          /* mech_type */
                  gss_name_t *            /* output_name */
                 );

   OM_uint32 gss_duplicate_name (
                  OM_uint32 ,             /* minor_status */
                  const gss_name_t,       /* src_name */
                  gss_name_t *            /* dest_name */
                 );

   /*
    * The following routines are obsolete variants of gss_get_mic,
    * gss_verify_mic, gss_wrap and gss_unwrap.  They should be
    * provided by GSS-API V2 implementations for backwards
    * compatibility with V1 applications.  Distinct entrypoints

Top       Page 97 
    * (as opposed to #defines) should be provided, both to allow
    * GSS-API V1 applications to link against GSS-API V2
      implementations,
    * and to retain the slight parameter type differences between the
    * obsolete versions of these routines and their current forms.
    */

   OM_uint32 gss_sign
                 (OM_uint32 ,        /* minor_status */
                  gss_ctx_id_t,      /* context_handle */
                  int,               /* qop_req */
                  gss_buffer_t,      /* message_buffer */
                  gss_buffer_t       /* message_token */
                 );


   OM_uint32 gss_verify
                 (OM_uint32 ,        /* minor_status */
                  gss_ctx_id_t,      /* context_handle */
                  gss_buffer_t,      /* message_buffer */
                  gss_buffer_t,      /* token_buffer */
                  int *              /* qop_state */
                 );

   OM_uint32 gss_seal
                 (OM_uint32 ,        /* minor_status */
                  gss_ctx_id_t,      /* context_handle */
                  int,               /* conf_req_flag */
                  int,               /* qop_req */
                  gss_buffer_t,      /* input_message_buffer */
                  int ,              /* conf_state */
                  gss_buffer_t       /* output_message_buffer */
                 );


   OM_uint32 gss_unseal
                 (OM_uint32 ,        /* minor_status */
                  gss_ctx_id_t,      /* context_handle */
                  gss_buffer_t,      /* input_message_buffer */
                  gss_buffer_t,      /* output_message_buffer */
                  int ,              /* conf_state */
                  int *              /* qop_state */
                 );

   #endif /* GSSAPI_H_ */

Top       Page 98 
Appendix B. Additional constraints for application binary portability

   The purpose of this C-bindings document is to encourage source-level
   portability of applications across GSS-API implementations on
   different platforms and atop different mechanisms.  Additional goals
   that have not been explicitly addressed by this document are link-
   time and run-time portability.

   Link-time portability provides the ability to compile an application
   against one implementation of GSS-API, and then link it against a
   different implementation on the same platform.  It is a stricter
   requirement than source-level portability.

   Run-time portability differs from link-time portability only on those
   platforms that implement dynamically loadable GSS-API
   implementations, but do not offer load-time symbol resolution. On
   such platforms, run-time portability is a stricter requirement than
   link-time portability, and will typically include the precise
   placement of the various GSS-API routines within library entrypoint
   vectors.

   Individual platforms will impose their own rules that must be
   followed to achieve link-time (and run-time, if different)
   portability.  In order to ensure either form of binary portability,
   an ABI specification must be written for GSS-API implementations on
   that platform.  However, it is recognized that there are some issues
   that are likely to be common to all such ABI specifications. This
   appendix is intended to be a repository for such common issues, and
   contains some suggestions that individual ABI specifications may
   choose to reference. Since machine architectures vary greatly, it may
   not be possible or desirable to follow these suggestions on all
   platforms.

B.1. Pointers

   While ANSI-C provides a single pointer type for each declared type,
   plus a single (void *) type, some platforms (notably those using
   segmented memory architectures) augment this with various modified
   pointer types (e.g. far pointers, near pointers). These language
   bindings assume ANSI-C, and thus do not address such non-standard
   implementations.  GSS-API implementations for such platforms must
   choose an appropriate memory model, and should use it consistently
   throughout.  For example, if a memory model is chosen that requires
   the use of far pointers when passing routine parameters, then far
   pointers should also be used within the structures defined by GSS-
   API.

Top       Page 99 
B.2. Internal structure alignment

   GSS-API defines several data-structures containing differently-sized
   fields.  An ABI specification should include a detailed description
   of how the fields of such structures are aligned, and if there is any
   internal padding in these data structures.  The use of compiler
   defaults for the platform is recommended.

B.3. Handle types

   The C bindings specify that the gss_cred_id_t and gss_ctx_id_t types
   should be implemented as either pointer or arithmetic types, and that
   if pointer types are used, care should be taken to ensure that two
   handles may be compared with the == operator. Note that ANSI-C does
   not guarantee that two pointer values may be compared with the ==
   operator unless either the two pointers point to members of a single
   array, or at least one of the pointers contains a NULL value.

   For binary portability, additional constraints are required. The
   following is an attempt at defining platform-independent constraints.

   The size of the handle type must be the same as sizeof(void *), using
   the appropriate memory model.

   The == operator for the chosen type must be a simple bit-wise
   comparison.  That is, for two in-memory handle objects h1 and h2, the
   boolean value of the expression

      (h1 == h2)

   should always be the same as the boolean value of the expression

      (memcmp(&h1, &h2, sizeof(h1)) == 0)

   The actual use of the type (void *) for handle types is discouraged,
   not for binary portability reasons, but since it effectively disables
   much of the compile-time type-checking that the compiler can
   otherwise perform, and is therefore not "programmer-friendly".  If a
   pointer implementation is desired, and if the platform's
   implementation of pointers permits, the handles should be implemented
   as pointers to distinct implementation-defined types.

B.4. The gss_name_t type

   The gss_name_t type, representing the internal name object, should be
   implemented as a pointer type.  The use of the (void *) type is
   discouraged as it does not allow the compiler to perform strong
   type-checking.  However, the pointer type chosen should be of the

Top       Page 100 
   same size as the (void *) type.  Provided this rule is obeyed, ABI
   specifications need not further constrain the implementation of
   gss_name_t objects.

B.5. The int and size_t types

   Some platforms may support differently sized implementations of the
   "int" and "size_t" types, perhaps chosen through compiler switches,
   and perhaps dependent on memory model.  An ABI specification for such
   a platform should include required implementations for these types.
   It is recommended that the default implementation (for the chosen
   memory model, if appropriate) is chosen.

B.6. Procedure-calling conventions

   Some platforms support a variety of different binary conventions for
   calling procedures.  Such conventions cover things like the format of
   the stack frame, the order in which the routine parameters are pushed
   onto the stack, whether or not a parameter count is pushed onto the
   stack, whether some argument(s) or return values are to be passed in
   registers, and whether the called routine or the caller is
   responsible for removing the stack frame on return.  For such
   platforms, an ABI specification should specify which calling
   convention is to be used for GSS-API implementations.

References

   [GSSAPI]    Linn, J., "Generic Security Service Application Program
               Interface Version 2, Update 1", RFC 2743, January 2000.

   [XOM]       OSI Object Management API Specification, Version 2.0 t",
               X.400 API Association & X/Open Company Limited, August
               24, 1990 Specification of datatypes and routines for
               manipulating information objects.

Author's Address

   John Wray
   Iris Associates
   5 Technology Park Drive,
   Westford, MA  01886
   USA

   Phone: +1-978-392-6689
   EMail: John_Wray@Iris.com

Top       Page 101 
Full Copyright Statement

   Copyright (C) The Internet Society (2000).  All Rights Reserved.

   This document and translations of it may be copied and furnished to
   others, and derivative works that comment on or otherwise explain it
   or assist in its implementation may be prepared, copied, published
   and distributed, in whole or in part, without restriction of any
   kind, provided that the above copyright notice and this paragraph are
   included on all such copies and derivative works.  However, this
   document itself may not be modified in any way, such as by removing
   the copyright notice or references to the Internet Society or other
   Internet organizations, except as needed for the purpose of
   developing Internet standards in which case the procedures for
   copyrights defined in the Internet Standards process must be
   followed, or as required to translate it into languages other than
   English.

   The limited permissions granted above are perpetual and will not be
   revoked by the Internet Society or its successors or assigns.

   This document and the information contained herein is provided on an
   "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
   TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
   BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
   HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
   MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

Acknowledgement

   Funding for the RFC Editor function is currently provided by the
   Internet Society.