signature for the message, but has been
verified out of sequence; an earlier token has
been signed or sealed by the remote
application, but not yet been processed
locally.
GSS_S_CONTEXT_EXPIRED The context has already expired
GSS_S_CREDENTIALS_EXPIRED The context is recognized, but
associated credentials have expired
GSS_S_NO_CONTEXT The context_handle parameter did not identify a
valid context
GSS_S_FAILURE Failure. See minor_status for more information.
3.10. gss_seal
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)
Purpose:
Cryptographically signs and optionally encrypts the specified
input_message. The output_message contains both the signature and
the message. The qop_req parameter allows a choice between several
cryptographic algorithms, if supported by the chosen mechanism.
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
True - Both confidentiality and integrity
services are requested
False - Only integrity service is requested
qop_req integer, 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_seal will return a major_status of
GSS_S_FAILURE.
input_message_buffer buffer, opaque, read
message to be sealed
conf_state boolean, modify
True - Confidentiality, data origin
authentication and integrity services
have been applied
False - Integrity and data origin services only
has been applied.
output_message_buffer buffer, opaque, modify
buffer to receive sealed message
Function value:
GSS status code:
GSS_S_COMPLETE Successful completion
GSS_S_CONTEXT_EXPIRED The context has already expired
GSS_S_CREDENTIALS_EXPIRED The context is recognized, but
associated credentials have expired
GSS_S_NO_CONTEXT The context_handle parameter did not identify a
valid context
GSS_S_FAILURE Failure. See minor_status for more information.
3.11. gss_unseal
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)
Purpose:
Converts a previously sealed message back to a usable form, verifying
the embedded signature. 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.
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
sealed message
output_message_buffer buffer, opaque, modify
buffer to receive unsealed message
conf_state boolean, modify
True - Confidentiality and integrity protection
were used
False - Inteegrity service only was used
qop_state integer, modify
quality of protection gained from signature
Function value:
GSS status code:
GSS_S_COMPLETE Successful completion
GSS_S_DEFECTIVE_TOKEN The token failed consistency checks
GSS_S_BAD_SIG The signature was incorrect
GSS_S_DUPLICATE_TOKEN The token was valid, and contained a
correct signature for the message, but it had
already been processed
GSS_S_OLD_TOKEN The token was valid, and contained a correct
signature for the message, but it is too old
GSS_S_UNSEQ_TOKEN The token was valid, and contained a correct
signature for the message, but has been
verified out of sequence; an earlier token has
been signed or sealed by the remote
application, but not yet been processed
locally.
GSS_S_CONTEXT_EXPIRED The context has already expired
GSS_S_CREDENTIALS_EXPIRED The context is recognized, but
associated credentials have expired
GSS_S_NO_CONTEXT The context_handle parameter did not identify a
valid context
GSS_S_FAILURE Failure. See minor_status for more information.
3.12. gss_display_status
OM_uint32 gss_display_status (
OM_uint32 * minor_status,
int status_value,
int status_type,
gss_OID mech_type,
int * message_context,
gss_buffer_t status_string)
Purpose:
Allows an application to obtain a textual representation of a GSSAPI
status code, for display to the user or for logging purposes. Since
some status values may indicate multiple errors, applications may
need to call gss_display_status multiple times, each call generating
a single text string. The message_context parameter is used to
indicate which error message should be extracted from a given
status_value; message_context should be initialized to 0, and
gss_display_status will return a non-zero value if there are further
messages to extract.
Parameters:
minor_status integer, modify
Mechanism specific status code.
status_value integer, read
Status value to be converted
status_type integer, read
GSS_C_GSS_CODE - status_value is a GSS status
code
GSS_C_MECH_CODE - status_value is a mechanism
status code
mech_type Object ID, read, optional
Underlying mechanism (used to interpret a
minor status value) Supply GSS_C_NULL_OID to
obtain the system default.
message_context integer, read/modify
Should be initialized to zero by caller
on first call. If further messages are
contained in the status_value parameter,
message_context will be non-zero on return,
and this value should be passed back to
subsequent calls, along with the same
status_value, status_type and mech_type
parameters.
status_string buffer, character string, modify
textual interpretation of the status_value
Function value:
GSS status code:
GSS_S_COMPLETE Successful completion
GSS_S_BAD_MECH Indicates that translation in accordance with
an unsupported mechanism type was requested
GSS_S_BAD_STATUS The status value was not recognized, or the
status type was neither GSS_C_GSS_CODE nor
GSS_C_MECH_CODE.
3.13. gss_indicate_mechs
OM_uint32 gss_indicate_mechs (
OM_uint32 * minor_status,
gss_OID_set * mech_set)
Purpose:
Allows an application to determine which underlying security
mechanisms are available.
Parameters:
minor_status integer, modify
Mechanism specific status code.
mech_set set of Object IDs, modify
set of implementation-supported mechanisms.
The returned gss_OID_set value will be a
pointer into static storage, and should be
treated as read-only by the caller.
Function value:
GSS status code:
GSS_S_COMPLETE Successful completion
3.14. gss_compare_name
OM_uint32 gss_compare_name (
OM_uint32 * minor_status,
gss_name_t name1,
gss_name_t name2,
int * name_equal)
Purpose:
Allows an application to compare two internal-form names to determine
whether they refer to the same entity.
Parameters:
minor_status integer, modify
Mechanism specific status code.
name1 gss_name_t, read
internal-form name
name2 gss_name_t, read
internal-form name
name_equal boolean, modify
True - names refer to same entity
False - names refer to different entities
(strictly, the names are not known to
refer to the same identity).
Function value:
GSS status code:
GSS_S_COMPLETE Successful completion
GSS_S_BAD_NAMETYPE The type contained within either name1 or
name2 was unrecognized, or the names were of
incomparable types.
GSS_S_BAD_NAME One or both of name1 or name2 was ill-formed
3.15. gss_display_name
OM_uint32 gss_display_name (
OM_uint32 * minor_status,
gss_name_t input_name,
gss_buffer_t output_name_buffer,
gss_OID * output_name_type)
Purpose:
Allows an application to obtain a textual representation of an opaque
internal-form name for display purposes. The syntax of a printable
name is defined by the GSSAPI implementation.
Parameters:
minor_status integer, modify
Mechanism specific status code.
input_name gss_name_t, read
name to be displayed
output_name_buffer buffer, character-string, modify
buffer to receive textual name string
output_name_type Object ID, modify
The type of the returned name. The returned
gss_OID will be a pointer into static storage,
and should be treated as read-only by the caller
Function value:
GSS status code:
GSS_S_COMPLETE Successful completion
GSS_S_BAD_NAMETYPE The type of input_name was not recognized
GSS_S_BAD_NAME input_name was ill-formed
3.16. gss_import_name
OM_uint32 gss_import_name (
OM_uint32 * minor_status,
gss_buffer_t input_name_buffer,
gss_OID input_name_type,
gss_name_t * output_name)
Purpose:
Convert a printable name to internal form.
Parameters:
minor_status integer, modify
Mechanism specific status code
input_name_buffer buffer, character-string, read
buffer containing printable name to convert
input_name_type Object ID, read, optional
Object Id specifying type of printable
name. Applications may specify either
GSS_C_NULL_OID to use a local system-specific
printable syntax, or an OID registered by the
GSSAPI implementation to name a particular
namespace.
output_name gss_name_t, modify
returned name in internal form
Function value:
GSS status code
GSS_S_COMPLETE Successful completion
GSS_S_BAD_NAMETYPE The input_name_type was unrecognized
GSS_S_BAD_NAME The input_name parameter could not be
interpreted as a name of the specified type
3.17. gss_release_name
OM_uint32 gss_release_name (
OM_uint32 * minor_status,
gss_name_t * name)
Purpose:
Free GSSAPI-allocated storage associated with an internal form name.
Parameters:
minor_status integer, modify
Mechanism specific status code
name gss_name_t, modify
The name to be deleted
Function value:
GSS status code
GSS_S_COMPLETE Successful completion
GSS_S_BAD_NAME The name parameter did not contain a valid name
3.18. gss_release_buffer
OM_uint32 gss_release_buffer (
OM_uint32 * minor_status,
gss_buffer_t buffer)
Purpose:
Free storage associated with a buffer format name. The storage must
have been allocated by a GSSAPI routine. In addition to freeing the
associated storage, the routine will zero the length field in the
buffer parameter.
Parameters:
minor_status integer, modify
Mechanism specific status code
buffer buffer, modify
The storage associated with the buffer will be
deleted. The gss_buffer_desc object will not
be freed, but its length field will be zeroed.
Function value:
GSS status code
GSS_S_COMPLETE Successful completion
3.19. gss_release_oid_set
OM_uint32 gss_release_oid_set (
OM_uint32 * minor_status,
gss_OID_set * set)
Purpose:
Free storage associated with a gss_OID_set object. The storage must
have been allocated by a GSSAPI routine.
Parameters:
minor_status integer, modify
Mechanism specific status code
set Set of Object IDs, modify
The storage associated with the gss_OID_set
will be deleted.
Function value:
GSS status code
GSS_S_COMPLETE Successful completion
3.20. gss_inquire_cred
OM_uint32 gss_inquire_cred (
OM_uint32 * minor_status,
gss_cred_id_t cred_handle,
gss_name_t * name,
OM_uint32 * lifetime,
int * cred_usage,
gss_OID_set * mechanisms )
Purpose:
Obtains information about a credential. The caller must already have
obtained a handle that refers to the credential.
Parameters:
minor_status integer, modify
Mechanism specific status code
cred_handle gss_cred_id_t, read
A handle that refers to the target credential.
Specify GSS_C_NO_CREDENTIAL to inquire about
the default credential.
name gss_name_t, modify
The name whose identity the credential asserts.
Specify NULL if not required.
lifetime Integer, modify
The number of seconds for which the credential
will remain valid. If the credential has
expired, this parameter will be set to zero.
If the implementation does not support
credential expiration, the value
GSS_C_INDEFINITE will be returned. Specify
NULL if not required.
cred_usage Integer, modify
How the credential may be used. One of the
following:
GSS_C_INITIATE
GSS_C_ACCEPT
GSS_C_BOTH
Specify NULL if not required.
mechanisms gss_OID_set, modify
Set of mechanisms supported by the credential.
Specify NULL if not required.
Function value:
GSS status code
GSS_S_COMPLETE Successful completion
GSS_S_NO_CRED The referenced credentials could not be
accessed.
GSS_S_DEFECTIVE_CREDENTIAL The referenced credentials were
invalid.
GSS_S_CREDENTIALS_EXPIRED The referenced credentials have expired.
If the lifetime parameter was not passed as
NULL, it will be set to 0.
#ifndef GSSAPI_H_
#define GSSAPI_H_
/*
* First, define the platform-dependent types.
*/
typedef <platform-specific> OM_uint32;
typedef <platform-specific> gss_ctx_id_t;
typedef <platform-specific> gss_cred_id_t;
typedef <platform-specific> gss_name_t;
/*
* Note that a platform supporting the xom.h X/Open header file
* may make use of that header for the definitions of OM_uint32
* and the structure to which gss_OID_desc equates.
*/
typedef struct gss_OID_desc_struct {
OM_uint32 length;
void *elements;
} gss_OID_desc, *gss_OID;
typedef struct gss_OID_set_desc_struct {
int 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;
/*
* Six independent flags each of which indicates that a context
* supports a specific service option.
*/
#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
/*
* 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;
#define GSS_C_NO_BUFFER ((gss_buffer_t) 0)
#define GSS_C_NULL_OID ((gss_OID) 0)
#define GSS_C_NULL_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}
/*
* Define the default Quality of Protection for per-message
* services. Note that an implementation that offers multiple
* levels of QOP may either reserve a value (for example zero,
* as assumed here) to mean "default protection", or alternatively
* may simply equate GSS_C_QOP_DEFAULT to a specific explicit QOP
* value.
*/
#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
/* 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
*/
#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) \
((GSS_CALLING_ERROR(x) != 0) || (GSS_ROUTINE_ERROR(x) != 0))
/*
* 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_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)
/*
* 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))
/*
* Finally, function prototypes for the GSSAPI routines.
*/
OM_uint32 gss_acquire_cred
(OM_uint32*, /* minor_status */
gss_name_t, /* desired_name */
OM_uint32, /* time_req */
gss_OID_set, /* desired_mechs */
int, /* 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 */
gss_cred_id_t, /* claimant_cred_handle */
gss_ctx_id_t*, /* context_handle */
gss_name_t, /* target_name */
gss_OID, /* mech_type */
int, /* req_flags */
OM_uint32, /* time_req */
gss_channel_bindings_t,
/* input_chan_bindings */
gss_buffer_t, /* input_token */
gss_OID*, /* actual_mech_type */
gss_buffer_t, /* output_token */
int*, /* ret_flags */
OM_uint32* /* time_rec */
);
OM_uint32 gss_accept_sec_context
(OM_uint32*, /* minor_status */
gss_ctx_id_t*, /* context_handle */
gss_cred_id_t, /* verifier_cred_handle */
gss_buffer_t, /* input_token_buffer */
gss_channel_bindings_t,
/* input_chan_bindings */
gss_name_t*, /* src_name */
gss_OID*, /* mech_type */
gss_buffer_t, /* output_token */
int*, /* ret_flags */
OM_uint32*, /* time_rec */
gss_cred_id_t* /* delegated_cred_handle */
);
OM_uint32 gss_process_context_token
(OM_uint32*, /* minor_status */
gss_ctx_id_t, /* context_handle */
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 */
gss_ctx_id_t, /* context_handle */
OM_uint32* /* time_rec */
);
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_uitn32 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 */
);
OM_uint32 gss_display_status
(OM_uint32*, /* minor_status */
OM_uint32, /* status_value */
int, /* status_type */
gss_OID, /* mech_type */
int*, /* 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 */
gss_name_t, /* name1 */
gss_name_t, /* name2 */
int* /* name_equal */
);
OM_uint32 gss_display_name,
(OM_uint32*, /* minor_status */
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 */
gss_buffer_t, /* input_name_buffer */
gss_OID, /* input_name_type */
gss_name_t* /* output_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 */
gss_cred_id_t, /* cred_handle */
gss_name_t *, /* name */
OM_uint32 *, /* lifetime */
int *, /* cred_usage */
gss_OID_set * /* mechanisms */
);
#endif /* GSSAPI_H_ */
References
[1] Linn, J., "Generic Security Service Application Program
Interface", RFC1508, Geer Zolot Associate, September 1993.
[2] "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.
Security Considerations
Security issues are discussed throughout this memo.
Author's Address
John Wray
Digital Equipment Corporation
550 King Street, LKG2-2/AA6
Littleton, MA 01460
USA
Phone: +1-508-486-5210
EMail: Wray@tuxedo.enet.dec.com