RFC 2744
Generic Security Service API Version 2 : C-bindings
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
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
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)
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.
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
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.
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
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.
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;
#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.
*/
#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
#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.
*/
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;
/*
* 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
#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 <<
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.
*/
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 */
);
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 */
);
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 */
);
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 */
);
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 */
);
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
* (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_ */
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.
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
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
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.