summaryrefslogtreecommitdiffstats
path: root/crypto/heimdal/doc/standardisation/draft-ietf-cat-gssv2-cbind-04.txt
diff options
context:
space:
mode:
Diffstat (limited to 'crypto/heimdal/doc/standardisation/draft-ietf-cat-gssv2-cbind-04.txt')
-rw-r--r--crypto/heimdal/doc/standardisation/draft-ietf-cat-gssv2-cbind-04.txt6188
1 files changed, 6188 insertions, 0 deletions
diff --git a/crypto/heimdal/doc/standardisation/draft-ietf-cat-gssv2-cbind-04.txt b/crypto/heimdal/doc/standardisation/draft-ietf-cat-gssv2-cbind-04.txt
new file mode 100644
index 0000000..518f4c6
--- /dev/null
+++ b/crypto/heimdal/doc/standardisation/draft-ietf-cat-gssv2-cbind-04.txt
@@ -0,0 +1,6188 @@
+
+ Internet draft J.Wray
+ IETF Common Authentication Technology WG Digital Equipment Corporation
+ <draft-ietf-cat-gssv2-cbind-04.txt> March 1997
+
+
+
+ Generic Security Service API Version 2 : C-bindings
+
+
+ 1. STATUS OF THIS MEMO
+
+ This document is an Internet Draft. Internet Drafts are working
+ documents of the Internet Engineering Task Force (IETF), its Areas, and
+ its Working Groups. Note that other groups may also distribute working
+ documents as Internet Drafts. Internet Drafts are draft documents valid
+ for a maximum of six months. Internet Drafts may be updated, replaced,
+ or obsoleted by other documents at any time. It is not appropriate to
+ use Internet Drafts as reference material or to cite them other than as
+ a "working draft" or "work in progress." Please check the I-D abstract
+ listing contained in each Internet Draft directory to learn the current
+ status of this or any other Internet Draft.
+
+ Comments on this document should be sent to "cat-ietf@MIT.EDU", the IETF
+ Common Authentication Technology WG discussion list.
+
+
+ 2. ABSTRACT
+
+ This draft document specifies C language bindings for Version 2 of the
+ Generic Security Service Application Program Interface (GSSAPI), which
+ is described at a language-independent conceptual level in other drafts
+ [GSSAPI]. It revises RFC-1509, making specific incremental changes in
+ response to implementation experience and liaison requests. It is
+ intended, therefore, that this draft or a successor version thereof will
+ become the basis for subsequent progression of the GSS-API specification
+ on the standards track.
+
+ The Generic Security Service Application Programming Interface provides
+ security services to its callers, and is intended for implementation
+ atop a variety of underlying cryptographic mechanisms. Typically,
+ GSSAPI callers will be application protocols into which security
+ enhancements are integrated through invocation of services provided by
+ the GSSAPI. The GSSAPI allows a caller application to authenticate a
+ principal identity associated with a peer application, to delegate
+ rights to a peer, and to apply security services such as confidentiality
+ and integrity on a per-message basis.
+
+
+
+
+
+
+
+
+ Wray Document Expiration: 1 September 1997 [Page 1]
+
+
+
+
+
+
+
+ INTERNET-DRAFT GSS-API V2 - C bindings March 1997
+
+
+
+ 3. INTRODUCTION
+
+ The Generic Security Service Application Programming Interface [GSSAPI]
+ provides security services to calling applications. It allows a
+ communicating application to authenticate the user associated with
+ another application, to delegate rights to another application, and to
+ apply security services such as confidentiality and integrity on a per-
+ message basis.
+
+ There are four stages to using the GSSAPI:
+
+ (a) The application acquires a set of credentials with which it may
+ prove its identity to other processes. The application's
+ credentials vouch for its global identity, which may or may not be
+ related to any local username under which it may be running.
+
+ (b) A pair of communicating applications establish a joint security
+ context using their credentials. The security context is a pair
+ of GSSAPI data structures that contain shared state information,
+ which is required in order that per-message security services may
+ be provided. Examples of state that might be shared between
+ applications as part of a security context are cryptographic keys,
+ and message sequence numbers. As part of the establishment of a
+ security context, the context initiator is authenticated to the
+ responder, and may require that the responder is authenticated in
+ turn. The initiator may optionally give the responder the right
+ to initiate further security contexts, acting as an agent or
+ delegate of the initiator. This transfer of rights is termed
+ delegation, and is achieved by creating a set of credentials,
+ similar to those used by the initiating application, but which may
+ be used by the responder.
+
+ To establish and maintain the shared information that makes up the
+ security context, certain GSSAPI calls will return a token data
+ structure, which is a cryptographically protected opaque data
+ type. The caller of such a GSSAPI routine is responsible for
+ transferring the token to the peer application, encapsulated if
+ necessary in an application-application protocol. On receipt of
+ such a token, the peer application should pass it to a
+ corresponding GSSAPI routine which will decode the token and
+ extract the information, updating the security context state
+ information accordingly.
+
+ (c) Per-message services are invoked to apply either:
+
+ (i) integrity and data origin authentication, or
+
+ (ii) confidentiality, integrity and data origin authentication
+
+ to application data, which are treated by GSSAPI as arbitrary
+ octet-strings. An application transmitting a message that it
+
+
+
+ Wray Document Expiration: 1 September 1997 [Page 2]
+
+
+
+
+
+
+
+ INTERNET-DRAFT GSS-API V2 - C bindings March 1997
+
+
+
+ wishes to protect will call the appropriate GSSAPI routine
+ (gss_get_mic or gss_wrap) to apply protection, specifying the
+ appropriate security context, and send the resulting token to the
+ receiving application. The receiver will pass the received token
+ (and, in the case of data protected by gss_get_mic, the
+ accompanying message-data) to the corresponding decoding routine
+ (gss_verify_mic or gss_unwrap) to remove the protection and
+ validate the data.
+
+ (d) At the completion of a communications session (which may extend
+ across several transport connections), each application calls a
+ GSSAPI routine to delete the security context. Multiple contexts
+ may also be used (either successively or simultaneously) within a
+ single communications association, at the option of the
+ applications.
+
+
+ 4. GSSAPI ROUTINES
+
+ This section lists the routines that make up the GSSAPI, and offers a
+ brief description of the purpose of each routine. Detailed descriptions
+ of each routine are listed in alphabetical order in section 7.
+
+ Table 4-1 GSSAPI Credential-management Routines
+
+ ROUTINE SECTION FUNCTION
+
+ gss_acquire_cred 7.2 Assume a global identity;
+ Obtain a GSSAPI credential
+ handle for pre-existing
+ credentials.
+
+ gss_add_cred 7.3 Construct credentials
+ incrementally
+
+ gss_inquire_cred 7.21 Obtain information about
+ a credential.
+
+ gss_inquire_cred_by_mech 7.22 Obtain per-mechanism information
+ about a credential.
+
+ gss_release_cred 7.27 Discard a credential handle.
+
+
+
+
+
+
+
+
+
+
+
+
+ Wray Document Expiration: 1 September 1997 [Page 3]
+
+
+
+
+
+
+
+ INTERNET-DRAFT GSS-API V2 - C bindings March 1997
+
+
+
+ Table 4-2 GSSAPI Context-level Routines
+
+ ROUTINE SECTION FUNCTION
+
+ gss_init_sec_context 7.19 Initiate a security context
+ with a peer application
+
+
+ gss_accept_sec_context 7.1 Accept a security context
+ initiated by a peer
+ application
+
+ gss_delete_sec_context 7.9 Discard a security context
+
+ gss_process_context_token 7.25 Process a token on a security
+ context from a peer
+ application
+
+ gss_context_time 7.7 Determine for how long a
+ context will remain valid
+
+ gss_inquire_context 7.20 Obtain information about a
+ security context
+
+ gss_wrap_size_limit 7.33 Determine token-size limit for
+ gss_wrap on a context
+
+ gss_export_sec_context 7.14 Transfer a security context to
+ another process
+
+ gss_import_sec_context 7.17 Import a transferred context
+
+
+
+
+ Table 4-3 GSSAPI Per-message Routines
+
+ ROUTINE SECTION FUNCTION
+
+ gss_get_mic 7.15 Calculate a cryptographic
+ Message Integrity Code (MIC)
+ for a message; integrity service
+
+ gss_verify_mic 7.32 Check a MIC against a message;
+ verify integrity of a received
+ message
+
+ gss_wrap 7.36 Attach a MIC to a message, and
+ optionally encrypt the message
+ content; confidentiality service
+
+
+
+
+ Wray Document Expiration: 1 September 1997 [Page 4]
+
+
+
+
+
+
+
+ INTERNET-DRAFT GSS-API V2 - C bindings March 1997
+
+
+
+ gss_unwrap 7.31 Verify a message with attached
+ MIC, and decrypt message
+ content if necessary.
+
+
+
+
+ Table 4-4 GSSAPI Name manipulation Routines
+
+ ROUTINE SECTION FUNCTION
+
+ gss_import_name 7.16 Convert a contiguous string name
+ to internal-form
+
+ gss_display_name 7.10 Convert internal-form name
+ to text
+
+ gss_compare_name 7.6 Compare two internal-form names
+
+ gss_release_name 7.28 Discard an internal-form name
+
+ gss_inquire_names_for_mech 7.24 List the name-types supported
+ by a specified mechanism
+
+ gss_inquire_mechs_for_name 7.23 List mechanisms that support
+ a given nametype
+
+ gss_canonicalize_name 7.5 Convert an internal name to
+ an MN.
+
+ gss_export_name 7.13 Convert an MN to export form
+
+ gss_duplicate_name 7.12 Create a copy of an internal name
+
+
+
+
+ Table 4-5 GSSAPI Miscellaneous Routines
+
+ ROUTINE SECTION FUNCTION
+
+ gss_display_status 7.11 Convert a GSSAPI status code
+ to text
+
+ gss_indicate_mechs 7.18 Determine available underlying
+ authentication mechanisms
+
+ gss_release_buffer 7.26 Discard a buffer
+
+ gss_release_oid_set 7.29 Discard a set of object
+ identifiers
+
+
+
+ Wray Document Expiration: 1 September 1997 [Page 5]
+
+
+
+
+
+
+
+ INTERNET-DRAFT GSS-API V2 - C bindings March 1997
+
+
+
+ gss_create_empty_oid_set 7.8 Create a set containing no
+ object identifiers
+
+ gss_add_oid_set_member 7.4 Add an object identifier to
+ a set
+
+ gss_test_oid_set_member 7.30 Determines whether an object
+ identifier is a member of a set
+
+
+
+
+
+ Individual GSSAPI implementations may augment these routines by
+ providing additional mechanism-specific routines if required
+ functionality is not available from the generic forms. Applications are
+ encouraged to use the generic routines wherever possible on portability
+ grounds.
+
+
+ 5. DATA TYPES AND CALLING CONVENTIONS
+
+ The following conventions are used by the GSSAPI C-language bindings:
+
+ 5.1. Integer types
+
+ GSSAPI uses the following integer data type:
+
+ OM_uint32 32-bit unsigned integer
+
+ Where guaranteed minimum bit-count is important, this portable data type
+ is used by the GSSAPI routine definitions. Individual GSSAPI
+ implementations will include appropriate typedef definitions to map this
+ type onto a built-in data type. If the platform supports the X/Open
+ xom.h header file, the OM_uint32 definition contained therein should be
+ used; the GSSAPI header file in Appendix A contains logic that will
+ detect the prior inclusion of xom.h, and will not attempt to re-declare
+ OM_uint32. If the X/Open header file is not available on the platform,
+ the GSSAPI implementation should use the smallest natural unsigned
+ integer type that provides at least 32 bits of precision.
+
+ 5.2. String and similar data
+
+ Many of the GSSAPI routines take arguments and return values that
+ describe contiguous octet-strings. All such data is passed between the
+ GSSAPI and the caller using the gss_buffer_t data type. This data type
+ is a pointer to a buffer descriptor, which consists of a length field
+ that contains the total number of bytes in the datum, and a value field
+ which contains a pointer to the actual datum:
+
+
+
+
+
+ Wray Document Expiration: 1 September 1997 [Page 6]
+
+
+
+
+
+
+
+ INTERNET-DRAFT GSS-API V2 - C bindings March 1997
+
+
+
+ typedef struct gss_buffer_desc_struct {
+ size_t length;
+ void *value;
+ } gss_buffer_desc, *gss_buffer_t;
+
+ Storage for data returned to the application by a GSSAPI routine using
+ the gss_buffer_t conventions is allocated by the GSSAPI routine. The
+ application may free this storage by invoking the gss_release_buffer
+ routine. Allocation of the gss_buffer_desc object is always the
+ responsibility of the application; unused gss_buffer_desc objects may
+ be initialized to the value GSS_C_EMPTY_BUFFER.
+
+ 5.2.1. Opaque data types
+
+ Certain multiple-word data items are considered opaque data types at the
+ GSSAPI, because their internal structure has no significance either to
+ the GSSAPI or to the caller. Examples of such opaque data types are the
+ input_token parameter to gss_init_sec_context (which is opaque to the
+ caller), and the input_message parameter to gss_wrap (which is opaque to
+ the GSSAPI). Opaque data is passed between the GSSAPI and the
+ application using the gss_buffer_t datatype.
+
+ 5.2.2. Character strings
+
+ Certain multiple-word data items may be regarded as simple ISO Latin-1
+ character strings. Examples are the printable strings passed to
+ gss_import_name via the input_name_buffer parameter. Some GSSAPI
+ routines also return character strings. All such character strings are
+ passed between the application and the GSSAPI implementation using the
+ gss_buffer_t datatype, which is a pointer to a gss_buffer_desc object.
+
+ When a gss_buffer_desc object describes a printable string, the length
+ field of the gss_buffer_desc should only count printable characters
+ within the string. In particular, a trailing NUL character should NOT
+ be included in the length count, nor should either the GSSAPI
+ implementation or the application assume the presence of an uncounted
+ trailing NUL.
+
+ 5.3. Object Identifiers
+
+ Certain GSSAPI procedures take parameters of the type gss_OID, or Object
+ identifier. This is a type containing ISO-defined tree-structured
+ values, and is used by the GSSAPI caller to select an underlying
+ security mechanism and to specify namespaces. A value of type gss_OID
+ has the following structure:
+
+ typedef struct gss_OID_desc_struct {
+ OM_uint32 length;
+ void *elements;
+ } gss_OID_desc, *gss_OID;
+
+
+
+
+ Wray Document Expiration: 1 September 1997 [Page 7]
+
+
+
+
+
+
+
+ INTERNET-DRAFT GSS-API V2 - C bindings March 1997
+
+
+
+ The elements field of this structure points to the first byte of an
+ octet string containing the ASN.1 BER encoding of the value portion of
+ the normal BER TLV encoding of the gss_OID. The length field contains
+ the number of bytes in this value. For example, the gss_OID value
+ corresponding to {iso(1) identified-organization(3) icd-ecma(12)
+ member-company(2) dec(1011) cryptoAlgorithms(7) DASS(5)}, meaning the
+ DASS X.509 authentication mechanism, has a length field of 7 and an
+ elements field pointing to seven octets containing the following octal
+ values: 53,14,2,207,163,7,5. GSSAPI implementations should provide
+ constant gss_OID values to allow applications to request any supported
+ mechanism, although applications are encouraged on portability grounds
+ to accept the default mechanism. gss_OID values should also be provided
+ to allow applications to specify particular name types (see section
+ 5.10). Applications should treat gss_OID_desc values returned by GSSAPI
+ routines as read-only. In particular, the application should not
+ attempt to deallocate them with free(). The gss_OID_desc datatype is
+ equivalent to the X/Open OM_object_identifier datatype[XOM].
+
+ 5.4. Object Identifier Sets
+
+ Certain GSSAPI procedures take parameters of the type gss_OID_set. This
+ type represents one or more object identifiers (section 5.3). A
+ gss_OID_set object has the following structure:
+
+ typedef struct gss_OID_set_desc_struct {
+ size_t count;
+ gss_OID elements;
+ } gss_OID_set_desc, *gss_OID_set;
+
+ The count field contains the number of OIDs within the set. The
+ elements field is a pointer to an array of gss_OID_desc objects, each of
+ which describes a single OID. gss_OID_set values are used to name the
+ available mechanisms supported by the GSSAPI, to request the use of
+ specific mechanisms, and to indicate which mechanisms a given credential
+ supports.
+
+ All OID sets returned to the application by GSSAPI are dynamic objects
+ (the gss_OID_set_desc, the "elements" array of the set, and the
+ "elements" array of each member OID are all dynamically allocated), and
+ this storage must be deallocated by the application using the
+ gss_release_oid_set() routine.
+
+
+ 5.5. Credentials
+
+ A credential handle is a caller-opaque atomic datum that identifies a
+ GSSAPI credential data structure. It is represented by the caller-
+ opaque type gss_cred_id_t, which should be implemented as a pointer or
+ arithmetic type. If a pointer implementation is chosen, care must be
+ taken to ensure that two gss_cred_id_t values may be compared with the
+ == operator.
+
+
+
+ Wray Document Expiration: 1 September 1997 [Page 8]
+
+
+
+
+
+
+
+ INTERNET-DRAFT GSS-API V2 - C bindings March 1997
+
+
+
+ GSSAPI credentials can contain mechanism-specific principal
+ authentication data for multiple mechanisms. A GSSAPI credential is
+ composed of a set of credential-elements, each of which is applicable to
+ a single mechanism. A credential may contain at most one credential-
+ element for each supported mechanism. A credential-element identifies
+ the data needed by a single mechanism to authenticate a single
+ principal, and conceptually contains two credential-references that
+ describing the actual mechanism-specific authentication data, one to be
+ used by GSSAPI for initiating contexts, and one to be used for
+ accepting contexts. For mechanisms that do not distinguish between
+ acceptor and initiator credentials, both references would point to the
+ same underlying mechanism-specific authentication data.
+
+ Credentials describe a set of mechanism-specific principals, and give
+ their holder the ability to act as any of those principals. All
+ principal identities asserted by a single GSSAPI credential should
+ belong to the same entity, although enforcement of this property is an
+ implementation-specific matter. The GSSAPI does not make the actual
+ credentials available to applications; instead a credential handle is
+ used to identify a particular credential, held internally by GSSAPI.
+ The combination of GSSAPI credential handle and mechanism identifies the
+ principal whose identity will be asserted by the credential when used
+ with that mechanism.
+
+ The gss_init_sec_context and gss_accept_sec_context routines allow the
+ value GSS_C_NO_CREDENTIAL to be specified as their credential handle
+ parameter. This special credential-handle indicates a desire by the
+ application to act as a default principal. While individual GSSAPI
+ implementations are free to determine such default behavior as
+ appropriate to the mechanism, the following default behavior by these
+ routines is recommended for portability:
+
+ (a) gss_init_sec_context
+
+ (i) If there is only a single principal capable of initiating
+ security contexts for the chosen mechanism that the
+ application is authorized to act on behalf of, then that
+ principal shall be used, otherwise
+
+ (ii) If the platform maintains a concept of a default network-
+ identity for the chosen mechanism, and if the application is
+ authorized to act on behalf of that identity for the purpose
+ of initiating security contexts, then the principal
+ corresponding to that identity shall be used, otherwise
+
+ (iii) If the platform maintains a concept of a default local
+ identity, and provides a means to map local identities into
+ network-identities for the chosen mechanism, and if the
+ application is authorized to act on behalf of the network-
+ identity image of the default local identity for the purpose
+ of initiating security contexts using the chosen mechanism,
+
+
+
+ Wray Document Expiration: 1 September 1997 [Page 9]
+
+
+
+
+
+
+
+ INTERNET-DRAFT GSS-API V2 - C bindings March 1997
+
+
+
+ then the principal corresponding to that identity shall be
+ used, otherwise
+
+ (iv) A user-configurable default identity should be used.
+
+ (b) gss_accept_sec_context
+
+ (i) If there is only a single authorized principal identity
+ capable of accepting security contexts for the chosen
+ mechanism, then that principal shall be used, otherwise
+
+ (ii) If the mechanism can determine the identity of the target
+ principal by examining the context-establishment token, and
+ if the accepting application is authorized to act as that
+ principal for the purpose of accepting security contexts
+ using the chosen mechanism, then that principal identity
+ shall be used, otherwise
+
+ (iii) If the mechanism supports context acceptance by any
+ principal, and if mutual authentication was not requested,
+ any principal that the application is authorized to accept
+ security contexts under using the chosen mechanism may be
+ used, otherwise
+
+ (iv) A user-configurable default identity shall be used.
+
+ The purpose of the above rules is to allow security contexts to be
+ established by both initiator and acceptor using the default behavior
+ wherever possible. Applications requesting default behavior are likely
+ to be more portable across mechanisms and platforms than ones that use
+ gss_acquire_cred to request a specific identity.
+
+ 5.6. Contexts
+
+ The gss_ctx_id_t data type contains a caller-opaque atomic value that
+ identifies one end of a GSSAPI security context. It should be
+ implemented as a pointer or arithmetic type. If a pointer type is
+ chosen, care should be taken to ensure that two gss_ctx_id_t values may
+ be compared with the == operator.
+
+ The security context holds state information about each end of a peer
+ communication, including cryptographic state information.
+
+ 5.7. Authentication tokens
+
+ A token is a caller-opaque type that GSSAPI uses to maintain
+ synchronization between the context data structures at each end of a
+ GSSAPI security context. The token is a cryptographically protected
+ octet-string, generated by the underlying mechanism at one end of a
+ GSSAPI security context for use by the peer mechanism at the other end.
+ Encapsulation (if required) and transfer of the token are the
+
+
+
+ Wray Document Expiration: 1 September 1997 [Page 10]
+
+
+
+
+
+
+
+ INTERNET-DRAFT GSS-API V2 - C bindings March 1997
+
+
+
+ responsibility of the peer applications. A token is passed between the
+ GSSAPI and the application using the gss_buffer_t conventions.
+
+ 5.8. Interprocess tokens
+
+ Certain GSSAPI routines are intended to transfer data between processes
+ in multi-process programs. These routines use a caller-opaque octet-
+ string, generated by the GSSAPI in one process for use by the GSSAPI in
+ another process. The calling application is responsible for
+ transferring such tokens between processes in an OS-specific manner.
+ Note that, while GSSAPI implementors are encouraged to avoid placing
+ sensitive information within interprocess tokens, or to
+ cryptographically protect them, many implementations will be unable to
+ avoid placing key material or other sensitive data within them. It is
+ the application's responsibility to ensure that interprocess tokens are
+ protected in transit, and transferred only to processes that are
+ trustworthy. An interprocess token is passed between the GSSAPI and the
+ application using the gss_buffer_t conventions.
+
+ 5.9. Status values
+
+ One or more status codes are returned by each GSSAPI routine. Two
+ distinct sorts of status codes are returned. These are termed GSS
+ status codes and Mechanism status codes.
+
+ 5.9.1. GSS status codes
+
+ GSSAPI routines return GSS status codes as their OM_uint32 function
+ value. These codes indicate errors that are independent of the
+ underlying mechanism(s) used to provide the security service. The
+ errors that can be indicated via a GSS status code are either generic
+ API routine errors (errors that are defined in the GSS-API
+ specification) or calling errors (errors that are specific to these
+ language bindings).
+
+ A GSS status code can indicate a single fatal generic API error from the
+ routine and a single calling error. In addition, supplementary status
+ information may be indicated via the setting of bits in the
+ supplementary info field of a GSS status code.
+
+ These errors are encoded into the 32-bit GSS status code as follows:
+
+ MSB LSB
+ |------------------------------------------------------------|
+ | Calling Error | Routine Error | Supplementary Info |
+ |------------------------------------------------------------|
+ Bit 31 24 23 16 15 0
+
+
+ Hence if a GSS-API routine returns a GSS status code whose upper 16 bits
+ contain a non-zero value, the call failed. If the calling error field
+
+
+
+ Wray Document Expiration: 1 September 1997 [Page 11]
+
+
+
+
+
+
+
+ INTERNET-DRAFT GSS-API V2 - C bindings March 1997
+
+
+
+ is non-zero, the invoking application's call of the routine was
+ erroneous. Calling errors are defined in table 5-1. If the routine
+ error field is non-zero, the routine failed for one of the routine-
+ specific reasons listed below in table 5-2. Whether or not the upper 16
+ bits indicate a failure or a success, the routine may indicate
+ additional information by setting bits in the supplementary info field
+ of the status code. The meaning of individual bits is listed below in
+ table 5-3.
+
+ Table 5-1 Calling Errors
+
+ Name Value in Meaning
+ Field
+ GSS_S_CALL_INACCESSIBLE_READ 1 A required input
+ parameter could
+ not be read.
+ GSS_S_CALL_INACCESSIBLE_WRITE 2 A required output
+ parameter could
+ not be written.
+ GSS_S_CALL_BAD_STRUCTURE 3 A parameter was
+ malformed
+
+
+
+
+ Table 5-2 Routine Errors
+
+ Name Value in Meaning
+ Field
+
+ GSS_S_BAD_MECH 1 An unsupported mechanism was
+ requested
+ GSS_S_BAD_NAME 2 An invalid name was supplied
+ GSS_S_BAD_NAMETYPE 3 A supplied name was of an
+ unsupported type
+ GSS_S_BAD_BINDINGS 4 Incorrect channel bindings
+ were supplied
+ GSS_S_BAD_STATUS 5 An invalid status code was
+ supplied
+ GSS_S_BAD_SIG 6 A token had an invalid
+ GSS_S_BAD_MIC MIC
+ GSS_S_NO_CRED 7 No credentials were supplied,
+ or the credentials were
+ unavailable or inaccessible.
+ GSS_S_NO_CONTEXT 8 No context has been
+ established
+ GSS_S_DEFECTIVE_TOKEN 9 A token was invalid
+ GSS_S_DEFECTIVE_CREDENTIAL 10 A credential was invalid
+ GSS_S_CREDENTIALS_EXPIRED 11 The referenced credentials
+ have expired
+
+
+
+
+ Wray Document Expiration: 1 September 1997 [Page 12]
+
+
+
+
+
+
+
+ INTERNET-DRAFT GSS-API V2 - C bindings March 1997
+
+
+
+ GSS_S_CONTEXT_EXPIRED 12 The context has expired
+ GSS_S_FAILURE 13 Miscellaneous failure
+ (see text)
+ GSS_S_BAD_QOP 14 The quality-of-protection
+ requested could not be
+ provide
+ GSS_S_UNAUTHORIZED 15 The operation is forbidden by
+ local security policy
+ GSS_S_UNAVAILABLE 16 The operation or option is not
+ available
+ GSS_S_DUPLICATE_ELEMENT 17 The requested credential element
+ already exists
+ GSS_S_NAME_NOT_MN 18 The provided name was not a
+ mechanism name.
+
+
+
+
+
+ Table 5-3 Supplementary Status Bits
+
+ Name Bit Number Meaning
+ GSS_S_CONTINUE_NEEDED 0 (LSB) The routine must be called
+ again to complete its function.
+ See routine documentation for
+ detailed description.
+ GSS_S_DUPLICATE_TOKEN 1 The token was a duplicate of
+ an earlier token
+ GSS_S_OLD_TOKEN 2 The token's validity period
+ has expired
+ GSS_S_UNSEQ_TOKEN 3 A later token has already been
+ processed
+ GSS_S_GAP_TOKEN 4 An expected per-message token
+ was not received
+
+
+ The routine documentation also uses the name GSS_S_COMPLETE, which is a
+ zero value, to indicate an absence of any API errors or supplementary
+ information bits.
+
+ All GSS_S_xxx symbols equate to complete OM_uint32 status codes, rather
+ than to bitfield values. For example, the actual value of the symbol
+ GSS_S_BAD_NAMETYPE (value 3 in the routine error field) is 3 << 16.
+
+ The macros GSS_CALLING_ERROR(), GSS_ROUTINE_ERROR() and
+ GSS_SUPPLEMENTARY_INFO() are provided, each of which takes a GSS status
+ code and removes all but the relevant field. For example, the value
+ obtained by applying GSS_ROUTINE_ERROR to a status code removes the
+ calling errors and supplementary info fields, leaving only the routine
+ errors field. The values delivered by these macros may be directly
+ compared with a GSS_S_xxx symbol of the appropriate type. The macro
+
+
+
+ Wray Document Expiration: 1 September 1997 [Page 13]
+
+
+
+
+
+
+
+ INTERNET-DRAFT GSS-API V2 - C bindings March 1997
+
+
+
+ GSS_ERROR() is also provided, which when applied to a GSS status code
+ returns a non-zero value if the status code indicated a calling or
+ routine error, and a zero value otherwise. All macros defined by GSS-
+ API evaluate their argument(s) exactly once.
+
+ A GSS-API implementation may choose to signal calling errors in a
+ platform-specific manner instead of, or in addition to the routine
+ value; routine errors and supplementary info should be returned via
+ routine status values only.
+
+ 5.9.2. Mechanism-specific status codes
+
+ GSS-API routines return a minor_status parameter, which is used to
+ indicate specialized errors from the underlying security mechanism.
+ This parameter may contain a single mechanism-specific error, indicated
+ by a OM_uint32 value.
+
+ The minor_status parameter will always be set by a GSS-API routine, even
+ if it returns a calling error or one of the generic API errors indicated
+ above as fatal, although most other output parameters may remain unset
+ in such cases. However, output parameters that are expected to return
+ pointers to storage allocated by a routine must always be set by the
+ routine, even in the event of an error, although in such cases the GSS-
+ API routine may elect to set the returned parameter value to NULL to
+ indicate that no storage was actually allocated. Any length field
+ associated with such pointers (as in a gss_buffer_desc structure) should
+ also be set to zero in such cases.
+
+ The GSS status code GSS_S_FAILURE is used to indicate that the
+ underlying mechanism detected an error for which no specific GSS status
+ code is defined. The mechanism status code will provide more details
+ about the error.
+
+ 5.10. Names
+
+ A name is used to identify a person or entity. GSS-API authenticates
+ the relationship between a name and the entity claiming the name.
+
+ Since different authentication mechanisms may employ different
+ namespaces for identifying their principals, GSSAPI's naming support is
+ necessarily complex in multi-mechanism environments (or even in some
+ single-mechanism environments where the underlying mechanism supports
+ multiple namespaces).
+
+ Two distinct representations are defined for names:
+
+ (a) An internal form. This is the GSSAPI "native" format for names,
+ represented by the implementation-specific gss_name_t type. It is
+ opaque to GSSAPI callers. A single gss_name_t object may contain
+ multiple names from different namespaces, but all names should
+ refer to the same entity. An example of such an internal name
+
+
+
+ Wray Document Expiration: 1 September 1997 [Page 14]
+
+
+
+
+
+
+
+ INTERNET-DRAFT GSS-API V2 - C bindings March 1997
+
+
+
+ would be the name returned from a call to the gss_inquire_cred
+ routine, when applied to a credential containing credential
+ elements for multiple authentication mechanisms employing
+ different namespaces. This gss_name_t object will contain a
+ distinct name for the entity for each authentication mechanism.
+
+ For GSSAPI implementations supporting multiple namespaces, objects
+ of type gss_name_t must contain sufficient information to
+ determine the namespace to which each primitive name belongs.
+
+ (b) Mechanism-specific contiguous octet-string forms. A format
+ capable of containing a single name (from a single namespace).
+ Contiguous string names are always accompanied by an object
+ identifier specifying the namespace to which the name belongs, and
+ their format is dependent on the authentication mechanism that
+ employs the name. Many, but not all, contiguous string names will
+ be printable, and may therefore be used by GSSAPI applications for
+ communication with their users.
+
+ Routines (gss_import_name and gss_display_name) are provided to convert
+ names between contiguous string representations and the internal
+ gss_name_t type. gss_import_name may support multiple syntaxes for each
+ supported namespace, allowing users the freedom to choose a preferred
+ name representation. gss_display_name should use an implementation-
+ chosen printable syntax for each supported name-type.
+
+ If an application calls gss_display_name(), passing the internal name
+ resulting from a call to gss_import_name(), there is no guarantee the
+ the resulting contiguous string name will be the same as the original
+ imported string name. Nor do name-space identifiers necessarily survive
+ unchanged after a journey through the internal name-form. An example of
+ this might be a mechanism that authenticates X.500 names, but provides
+ an algorithmic mapping of Internet DNS names into X.500. That
+ mechanism's implementation of gss_import_name() might, when presented
+ with a DNS name, generate an internal name that contained both the
+ original DNS name and the equivalent X.500 name. Alternatively, it might
+ only store the X.500 name. In the latter case, gss_display_name() would
+ most likely generate a printable X.500 name, rather than the original
+ DNS name.
+
+ The process of authentication delivers to the context acceptor an
+ internal name. Since this name has been authenticated by a single
+ mechanism, it contains only a single name (even if the internal name
+ presented by the context initiator to gss_init_sec_context had multiple
+ components). Such names are termed internal mechanism names, or "MN"s
+ and the names emitted by gss_accept_sec_context() are always of this
+ type. Since some applications may require MNs without wanting to incur
+ the overhead of an authentication operation, a second function,
+ gss_canonicalize_name(), is provided to convert a general internal name
+ into an MN.
+
+
+
+
+ Wray Document Expiration: 1 September 1997 [Page 15]
+
+
+
+
+
+
+
+ INTERNET-DRAFT GSS-API V2 - C bindings March 1997
+
+
+
+ Comparison of internal-form names may be accomplished via the
+ gss_compare_name() routine, which returns true if the two names being
+ compared refer to the same entity. This removes the need for the
+ application program to understand the syntaxes of the various printable
+ names that a given GSS-API implementation may support. Since GSSAPI
+ assumes that all primitive names contained within a given internal name
+ refer to the same entity, gss_compare_name() can return true if the two
+ names have at least one primitive name in common. If the implementation
+ embodies knowledge of equivalence relationships between names taken from
+ different namespaces, this knowledge may also allow successful
+ comparison of internal names containing no overlapping primitive
+ elements.
+
+ When used in large access control lists, the overhead of invoking
+ gss_import_name() and gss_compare_name() on each name from the ACL may
+ be prohibitive. As an alternative way of supporting this case, GSSAPI
+ defines a special form of the contiguous string name which may be
+ compared directly (e.g. with memcmp()). Contigous names suitable for
+ comparison are generated by the gss_export_name() routine, which
+ requires an MN as input. Exported names may be re-imported by the
+ gss_import_name() routine, and the resulting internal name will also be
+ an MN. The gss_OID constant GSS_C_NT_EXPORT_NAME indentifies the
+ "export name" type, and the value of this constant is given in Appendix
+ A. Structurally, an exported name object consists of a header
+ containing an OID identifying the mechanism that authenticated the name,
+ and a trailer containing the name itself, where the syntax of the
+ trailer is defined by the individual mechanism specification. The
+ precise format of an export name is defined in the language-independent
+ GSSAPI specification [GSSAPI].
+
+ Note that the results obtained by using gss_compare_name() will in
+ general be different from those obtained by invoking
+ gss_canonicalize_name() and gss_export_name(), and then comparing the
+ exported names. The first series of operation determines whether two
+ (unauthenticated) names identify the same principal; the second whether
+ a particular mechanism would authenticate them as the same principal.
+ These two operations will in general give the same results only for MNs.
+
+ The gss_name_t datatype should be implemented as a pointer type. To
+ allow the compiler to aid the application programmer by performing
+ type-checking, the use of (void *) is discouraged. A pointer to an
+ implementation-defined type is the preferred choice.
+
+ Storage is allocated by routines that return gss_name_t values. A
+ procedure, gss_release_name, is provided to free storage associated with
+ an internal-form name.
+
+
+
+
+
+
+
+
+ Wray Document Expiration: 1 September 1997 [Page 16]
+
+
+
+
+
+
+
+ INTERNET-DRAFT GSS-API V2 - C bindings March 1997
+
+
+
+ 5.11. Channel Bindings
+
+ GSS-API supports the use of user-specified tags to identify a given
+ context to the peer application. These tags are intended to be used to
+ identify the particular communications channel that carries the context.
+ Channel bindings are communicated to the GSS-API using the following
+ structure:
+
+ 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;
+
+ The initiator_addrtype and acceptor_addrtype fields denote the type of
+ addresses contained in the initiator_address and acceptor_address
+ buffers. The address type should be one of the following:
+
+ GSS_C_AF_UNSPEC Unspecified address type
+ GSS_C_AF_LOCAL Host-local address type
+ GSS_C_AF_INET Internet address type (e.g. IP)
+ GSS_C_AF_IMPLINK ARPAnet IMP address type
+ GSS_C_AF_PUP pup protocols (eg BSP) address type
+ GSS_C_AF_CHAOS MIT CHAOS protocol address type
+ GSS_C_AF_NS XEROX NS address type
+ GSS_C_AF_NBS nbs address type
+ GSS_C_AF_ECMA ECMA address type
+ GSS_C_AF_DATAKIT datakit protocols address type
+ GSS_C_AF_CCITT CCITT protocols
+ GSS_C_AF_SNA IBM SNA address type
+ GSS_C_AF_DECnet DECnet address type
+ GSS_C_AF_DLI Direct data link interface address type
+ GSS_C_AF_LAT LAT address type
+ GSS_C_AF_HYLINK NSC Hyperchannel address type
+ GSS_C_AF_APPLETALK AppleTalk address type
+ GSS_C_AF_BSC BISYNC 2780/3780 address type
+ GSS_C_AF_DSS Distributed system services address type
+ GSS_C_AF_OSI OSI TP4 address type
+ GSS_C_AF_X25 X25
+ GSS_C_AF_NULLADDR No address specified
+
+ Note that these symbols name address families rather than specific
+ addressing formats. For address families that contain several
+ alternative address forms, the initiator_address and acceptor_address
+ fields must contain sufficient information to determine which address
+ form is used. When not otherwise specified, addresses should be
+ specified in network byte-order (that is, native byte-ordering for the
+ address family).
+
+
+
+
+ Wray Document Expiration: 1 September 1997 [Page 17]
+
+
+
+
+
+
+
+ INTERNET-DRAFT GSS-API V2 - C bindings March 1997
+
+
+
+ Conceptually, the GSS-API concatenates the initiator_addrtype,
+ initiator_address, acceptor_addrtype, acceptor_address and
+ application_data to form an octet string. The mechanism calculates a
+ MIC over this octet string, and binds the MIC to the context
+ establishment token emitted by gss_init_sec_context. The same bindings
+ are presented by the context acceptor to gss_accept_sec_context, and a
+ MIC is calculated in the same way. The calculated MIC is compared with
+ that found in the token, and if the MICs differ, gss_accept_sec_context
+ will return a GSS_S_BAD_BINDINGS error, and the context will not be
+ established. Some mechanisms may include the actual channel binding
+ data in the token (rather than just a MIC); applications should
+ therefore not use confidential data as channel-binding components.
+ Individual mechanisms may impose additional constraints on addresses and
+ address types that may appear in channel bindings. For example, a
+ mechanism may verify that the initiator_address field of the channel
+ bindings presented to gss_init_sec_context contains the correct network
+ address of the host system. Portable applications should therefore
+ ensure that they either provide correct information for the address
+ fields, or omit addressing information, specifying GSS_C_AF_NULLADDR as
+ the address-types.
+
+ 5.12. Optional parameters
+
+ Various parameters are described as optional. This means that they
+ follow a convention whereby a default value may be requested. The
+ following conventions are used for omitted parameters. These
+ conventions apply only to those parameters that are explicitly
+ documented as optional.
+
+ 5.12.1. gss_buffer_t types
+
+ Specify GSS_C_NO_BUFFER as a value. For an input parameter this
+ signifies that default behavior is requested, while for an output
+ parameter it indicates that the information that would be returned via
+ the parameter is not required by the application.
+
+ 5.12.2. Integer types (input)
+
+ Individual parameter documentation lists values to be used to indicate
+ default actions.
+
+ 5.12.3. Integer types (output)
+
+ Specify NULL as the value for the pointer.
+
+ 5.12.4. Pointer types
+
+ Specify NULL as the value.
+
+
+
+
+
+
+ Wray Document Expiration: 1 September 1997 [Page 18]
+
+
+
+
+
+
+
+ INTERNET-DRAFT GSS-API V2 - C bindings March 1997
+
+
+
+ 5.12.5. Object IDs
+
+ Specify GSS_C_NO_OID as the value.
+
+ 5.12.6. Object ID Sets
+
+ Specify GSS_C_NO_OID_SET as the value.
+
+ 5.12.7. Channel Bindings
+
+ Specify GSS_C_NO_CHANNEL_BINDINGS to indicate that channel bindings are
+ not to be used.
+
+
+ 6. ADDITIONAL CONTROLS
+
+ This section discusses the optional services that a context initiator
+ may request of the GSS-API at context establishment. Each of these
+ services is requested by setting a flag in the req_flags input parameter
+ to gss_init_sec_context.
+
+ The optional services currently defined are:
+
+ Delegation - The (usually temporary) transfer of rights from initiator
+ to acceptor, enabling the acceptor to authenticate itself as an
+ agent of the initiator.
+
+ Mutual Authentication - In addition to the initiator authenticating its
+ identity to the context acceptor, the context acceptor should also
+ authenticate itself to the initiator.
+
+ Replay detection - In addition to providing message integrity services,
+ gss_get_mic and gss_wrap should include message numbering
+ information to enable gss_verify_mic and gss_unwrap to detect if a
+ message has been duplicated.
+
+ Out-of-sequence detection - In addition to providing message integrity
+ services, gss_get_mic and gss_wrap should include message
+ sequencing information to enable gss_verify_mic and gss_unwrap to
+ detect if a message has been received out of sequence.
+
+ Anonymous authentication - The establishment of the security context
+ should not reveal the initiator's identity to the context
+ acceptor.
+
+ Any currently undefined bits within such flag arguments should be
+ ignored by GSS-API implementations when presented by an application, and
+ should be set to zero when returned to the application by the GSS-API
+ implementation.
+
+
+
+
+
+ Wray Document Expiration: 1 September 1997 [Page 19]
+
+
+
+
+
+
+
+ INTERNET-DRAFT GSS-API V2 - C bindings March 1997
+
+
+
+ Some mechanisms may not support all optional services, and some
+ mechanisms may only support some services in conjunction with others.
+ Both gss_init_sec_context and gss_accept_sec_context inform the
+ applications which services will be available from the context when the
+ establishment phase is complete, via the ret_flags output parameter. In
+ general, if the security mechanism is capable of providing a requested
+ service, it should do so, even if additional services must be enabled in
+ order to provide the requested service. If the mechanism is incapable
+ of providing a requested service, it should proceed without the service,
+ leaving the application to abort the context establishment process if it
+ considers the requested service to be mandatory.
+
+ Some mechanisms may specify that support for some services is optional,
+ and that implementors of the mechanism need not provide it. This is
+ most commonly true of the confidentiality service, often because of
+ legal restrictions on the use of data-encryption, but may apply to any
+ of the services. Such mechanisms are required to send at least one
+ token from acceptor to initiator during context establishment when the
+ initiator indicates a desire to use such a service, so that the
+ initiating GSSAPI can correctly indicate whether the service is
+ supported by the acceptor's GSSAPI.
+
+ 6.1. Delegation
+
+ The GSS-API allows delegation to be controlled by the initiating
+ application via a boolean parameter to gss_init_sec_context(), the
+ routine that establishes a security context. Some mechanisms do not
+ support delegation, and for such mechanisms attempts by an application
+ to enable delegation are ignored.
+
+ The acceptor of a security context for which the initiator enabled
+ delegation will receive (via the delegated_cred_handle parameter of
+ gss_accept_sec_context) a credential handle that contains the delegated
+ identity, and this credential handle may be used to initiate subsequent
+ GSSAPI security contexts as an agent or delegate of the initiator. If
+ the original initiator's identity is "A" and the delegate's identity is
+ "B", then, depending on the underlying mechanism, the identity embodied
+ by the delegated credential may be either "A" or "B acting for A".
+
+ For many mechanisms that support delegation, a simple boolean does not
+ provide enough control. Examples of additional aspects of delegation
+ control that a mechanism might provide to an application are duration of
+ delegation, network addresses from which delegation is valid, and
+ constraints on the tasks that may be performed by a delegate. Such
+ controls are presently outside the scope of the GSS-API. GSS-API
+ implementations supporting mechanisms offering additional controls
+ should provide extension routines that allow these controls to be
+ exercised (perhaps by modifying the initiator's GSS-API credential prior
+ to its use in establishing a context). However, the simple delegation
+ control provided by GSS-API should always be able to over-ride other
+ mechanism-specific delegation controls - If the application instructs
+
+
+
+ Wray Document Expiration: 1 September 1997 [Page 20]
+
+
+
+
+
+
+
+ INTERNET-DRAFT GSS-API V2 - C bindings March 1997
+
+
+
+ gss_init_sec_context() that delegation is not desired, then the
+ implementation must not permit delegation to occur. This is an
+ exception to the general rule that a mechanism may enable services even
+ if they are not requested - delegation may only be provide at the
+ explicit request of the application.
+
+ 6.2. Mutual authentication
+
+ Usually, a context acceptor will require that a context initiator
+ authenticate itself so that the acceptor may make an access-control
+ decision prior to performing a service for the initiator. In some
+ cases, the initiator may also request that the acceptor authenticate
+ itself. GSS-API allows the initiating application to request this
+ mutual authentication service by setting a flag when calling
+ gss_init_sec_context.
+
+ The initiating application is informed as to whether or not mutual
+ authentication is being requested of the context acceptor. Note that
+ some mechanisms may not support mutual authentication, and other
+ mechanisms may always perform mutual authentication, whether or not the
+ initiating application requests it. In particular, mutual
+ authentication my be required by some mechanisms in order to support
+ replay or out-of-sequence message detection, and for such mechanisms a
+ request for either of these services will automatically enable mutual
+ authentication.
+
+ 6.3. Replay and out-of-sequence detection
+
+ The GSS-API may provide detection of mis-ordered message once a security
+ context has been established. Protection may be applied to messages by
+ either application, by calling either gss_get_mic or gss_wrap, and
+ verified by the peer application by calling gss_verify_mic or
+ gss_unwrap.
+
+ gss_get_mic calculates a cryptographic checksum of an application
+ message, and returns that checksum in a token. The application should
+ pass both the token and the message to the peer application, which
+ presents them to gss_verify_mic.
+
+ gss_wrap calculates a cryptographic checksum of an application message,
+ and places both the checksum and the message inside a single token. The
+ application should pass the token to the peer application, which
+ presents it to gss_unwrap to extract the message and verify the
+ checksum.
+
+ Either pair of routines may be capable of detecting out-of-sequence
+ message delivery, or duplication of messages. Details of such mis-
+ ordered messages are indicated through supplementary status bits in the
+ major status code returned by gss_verify_mic or gss_unwrap. The
+ relevant supplementary bits are:
+
+
+
+
+ Wray Document Expiration: 1 September 1997 [Page 21]
+
+
+
+
+
+
+
+ INTERNET-DRAFT GSS-API V2 - C bindings March 1997
+
+
+
+ GSS_S_DUPLICATE_TOKEN - The token is a duplicate of one that has already
+ been received and processed. Contexts that do not claim to
+ provide replay detection may still set this bit if the duplicate
+ message is processed immediately after the original, with no
+ intervening messages.
+
+ GSS_S_OLD_TOKEN - The token is too old to determine whether or not it is
+ a duplicate. Contexts supporting out-of-sequence detection but
+ not replay detection should always set this bit if
+ GSS_S_UNSEQ_TOKEN is set; contexts that support replay detection
+ should only set this bit if the token is so old that it cannot be
+ checked for duplication.
+
+ GSS_S_UNSEQ_TOKEN - A later token has already been processed.
+
+ GSS_S_GAP_TOKEN - An earlier token has not yet been received.
+
+ A mechanism need not maintain a list of all tokens that have been
+ processed in order to support these status codes. A typical mechanism
+ might retain information about only the most recent "N" tokens
+ processed, allowing it to distinguish duplicates and missing tokens
+ within the most recent "N" messages; the receipt of a token older than
+ the most recent "N" would result in a GSS_S_OLD_TOKEN status.
+
+ 6.4. Anonymous Authentication
+
+ In certain situations, an application may wish to initiate the
+ authentication process to authenticate a peer, without revealing its own
+ identity. As an example, consider an application providing access to a
+ database containing medical information, and offering unrestricted
+ access to the service. A client of such a service might wish to
+ authenticate the service (in order to establish trust in any information
+ retrieved from it), but might not wish the service to be able to obtain
+ the client's identity (perhaps due to privacy concerns about the
+ specific inquiries, or perhaps simply to avoid being placed on mailing-
+ lists).
+
+ In normal use of the GSS-API, the initiator's identity is made available
+ to the acceptor as a result of the context establishment process.
+ However, context initiators may request that their identity not be
+ revealed to the context acceptor. Many mechanisms do not support
+ anonymous authentication, and for such mechanisms the request will not
+ be honored. An authentication token will be still be generated, but the
+ application is always informed if a requested service is unavailable,
+ and has the option to abort context establishment if anonymity is valued
+ above the other security services that would require a context to be
+ established.
+
+ In addition to informing the application that a context is established
+ anonymously (via the ret_flags outputs from gss_init_sec_context and
+ gss_accept_sec_context), the optional src_name output from
+
+
+
+ Wray Document Expiration: 1 September 1997 [Page 22]
+
+
+
+
+
+
+
+ INTERNET-DRAFT GSS-API V2 - C bindings March 1997
+
+
+
+ gss_accept_sec_context and gss_inquire_context will, for such contexts,
+ return a reserved internal-form name, defined by the implementation.
+ When presented to gss_display_name, this reserved internal-form name
+ will result in a printable name that is syntactically distinguishable
+ from any valid principal name supported by the implementation,
+ associated with a name-type object identifier with the value
+ GSS_C_NT_ANONYMOUS, whose value us given in Appendix A. The printable
+ form of an anonymous name should be chosen such that it implies
+ anonymity, since this name may appear in, for example, audit logs. For
+ example, the string "<anonymous>" might be a good choice, if no valid
+ printable names supported by the implementation can begin with "<" and
+ end with ">".
+
+ 6.5. Confidentiality
+
+ If a context supports the confidentiality service, gss_wrap may be used
+ to encrypt application messages. Messages are selectively encrypted,
+ under the control of the conf_req_flag input parameter to gss_wrap.
+
+ 6.6. Inter-process context transfer
+
+ GSSAPI V2 provides routines (gss_export_sec_context and
+ gss_import_sec_context) which allow a security context to be transferred
+ between processes on a single machine. The most common use for such a
+ feature is a client-server design where the server is implemented as a
+ single process that accepts incoming security contexts, which then
+ launches child processes to deal with the data on these contexts. In
+ such a design, the child processes must have access to the security
+ context data structure created within the parent by its call to
+ gss_accept_sec_context so that they can use per-message protection
+ services and delete the security context when the communication session
+ ends.
+
+ Since the security context data structure is expected to contain
+ sequencing information, it is impractical in general to share a context
+ between processes. Thus GSSAPI provides a call (gss_export_sec_context)
+ that the process which currently owns the context can call to declare
+ that it has no intention to use the context subsequently, and to create
+ an inter-process token containing information needed by the adopting
+ process to successfully import the context. After successful completion
+ of this call, the original security context is made inaccessible to the
+ calling process by GSSAPI, and any context handles referring to this
+ context are no longer valid. The originating process transfers the
+ inter-process token to the adopting process, which passes it to
+ gss_import_sec_context, and a fresh gss_ctx_id_t is created such that it
+ is functionally identical to the original context.
+
+ The inter-process token may contain sensitive data from the original
+ security context (including cryptographic keys). Applications using
+ inter-process tokens to transfer security contexts must take appropriate
+ steps to protect these tokens in transit.
+
+
+
+ Wray Document Expiration: 1 September 1997 [Page 23]
+
+
+
+
+
+
+
+ INTERNET-DRAFT GSS-API V2 - C bindings March 1997
+
+
+
+ Implementations are not required to support the inter-process transfer
+ of security contexts. The ability to transfer a security context is
+ indicated when the context is created, by gss_init_sec_context or
+ gss_accept_sec_context setting the GSS_C_TRANS_FLAG bit in their
+ ret_flags parameter.
+
+
+ 6.7. The use of incomplete contexts
+
+ Some mechanisms may allow the per-message services to be used before the
+ context establishment process is complete. For example, a mechanism may
+ include sufficient information in its initial context-level token for
+ the context acceptor to immediately decode messages protected with
+ gss_wrap or gss_get_mic. For such a mechanism, the initiating
+ application need not wait until subsequent context-level tokens have
+ been sent and received before invoking the per-message protection
+ services.
+
+ The ability of a context to provide per-message services in advance of
+ complete context establishment is indicated by the setting of the
+ GSS_C_PROT_READY_FLAG bit in the ret_flags parameter from
+ gss_init_sec_context and gss_accept_sec_context. Applications wishing
+ to use per-message protection services on partially-established contexts
+ should check this flag before attempting to invoke gss_wrap or
+ gss_get_mic.
+
+
+
+ 7. GSS-API routine descriptions
+
+ In addition to the explicit major status codes documented here, the code
+ GSS_S_FAILURE may be returned by any routine, indicating an
+ implementation-specific or mechanism-specific error condition, further
+ details of which are reported via the minor_status parameter.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Wray Document Expiration: 1 September 1997 [Page 24]
+
+
+
+
+
+
+
+ INTERNET-DRAFT GSS-API V2 - C bindings March 1997
+
+
+
+ 7.1. gss_accept_sec_context
+
+ 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,
+ const 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)
+
+ Purpose:
+
+ Allows a remotely initiated security context between the application and
+ a remote peer to be established. The routine may return a output_token
+ which should be transferred to the peer application, where the peer
+ application will present it to gss_init_sec_context. If no token need
+ be sent, gss_accept_sec_context will indicate this by setting the length
+ field of the output_token argument to zero. To complete the context
+ establishment, one or more reply tokens may be required from the peer
+ application; if so, gss_accept_sec_context will return a status flag of
+ GSS_S_CONTINUE_NEEDED, in which case it should be called again when the
+ reply token is received from the peer application, passing the token to
+ gss_accept_sec_context via the input_token parameters.
+
+ Portable applications should be constructed to use the token length and
+ return status to determine whether a token needs to be sent or waited
+ for. Thus a typical portable caller should always invoke
+ gss_accept_sec_context within a loop:
+
+ gss_ctx_id_t context_hdl = GSS_C_NO_CONTEXT;
+ ...
+
+ do {
+ receive_token_from_peer(input_token);
+ maj_stat = gss_accept_sec_context(&min_stat,
+ &context_hdl,
+ cred_hdl,
+ input_token,
+ input_bindings,
+ &client_name,
+ &mech_type,
+ output_token,
+ &ret_flags,
+ &time_rec,
+ &deleg_cred);
+
+
+
+ Wray Document Expiration: 1 September 1997 [Page 25]
+
+
+
+
+
+
+
+ INTERNET-DRAFT GSS-API V2 - C bindings March 1997
+
+
+
+ if (GSS_ERROR(maj_stat)) {
+ report_error(maj_stat, min_stat);
+ };
+ if (output_token->length != 0) {
+ send_token_to_peer(output_token);
+ gss_release_buffer(&min_stat,
+ output_token)
+ };
+ if (GSS_ERROR(maj_stat)) {
+ if (context_hdl != GSS_C_NO_CONTEXT)
+ gss_delete_sec_context(&min_stat,
+ &context_hdl,
+ GSS_C_NO_BUFFER);
+ break;
+ };
+ } while (maj_stat & GSS_S_CONTINUE_NEEDED);
+
+
+ Whenever the routine returns a major status that includes the value
+ GSS_S_CONTINUE_NEEDED, the context is not fully established and the
+ following restrictions apply to the output parameters:
+
+ (a) The value returned via the time_rec parameter is undefined
+
+ (b) Unless the accompanying ret_flags parameter contains the bit
+ GSS_C_PROT_READY_FLAG, indicating that per-message services may be
+ applied in advance of a successful completion status, the value
+ returned via the mech_type parameter may be undefined until the
+ routine returns a major status value of GSS_S_COMPLETE.
+
+ (c) The values of the GSS_C_DELEG_FLAG, GSS_C_MUTUAL_FLAG,
+ GSS_C_REPLAY_FLAG, GSS_C_SEQUENCE_FLAG, GSS_C_CONF_FLAG,
+ GSS_C_INTEG_FLAG and GSS_C_ANON_FLAG bits returned via the
+ ret_flags parameter should contain the values that the
+ implementation expects would be valid if context establishment
+ were to succeed.
+
+ The values of the GSS_C_PROT_READY_FLAG and GSS_C_TRANS_FLAG bits
+ within ret_flags should indicate the actual state at the time
+ gss_accept_sec_context returns, whether or not the context is
+ fully established.
+
+ Although this requires that GSSAPI implementations set the
+ GSS_C_PROT_READY_FLAG in the final ret_flags returned to a caller
+ (i.e. when accompanied by a GSS_S_COMPLETE status code),
+ applications should not rely on this behavior as the flag was not
+ defined in Version 1 of the GSSAPI. Instead, applications should
+ be prepared to use per-message services after a successful context
+ establishment, according to the GSS_C_INTEG_FLAG and
+ GSS_C_CONF_FLAG values.
+
+
+
+
+ Wray Document Expiration: 1 September 1997 [Page 26]
+
+
+
+
+
+
+
+ INTERNET-DRAFT GSS-API V2 - C bindings March 1997
+
+
+
+ All other bits within the ret_flags argument should be set to
+ zero.
+
+
+ While the routine returns GSS_S_CONTINUE_NEEDED, the values returned via
+ the ret_flags argument indicate the services that the implementation
+ expects to be available from the established context.
+
+ If the initial call of gss_accept_sec_context() fails, the
+ implementation should not create a context object, and should leave the
+ value of the context_handle parameter set to GSS_C_NO_CONTEXT to
+ indicate this. In the event of a failure on a subsequent call, the
+ implementation is permitted to delete the "half-built" security context
+ (in which case it should set the context_handle parameter to
+ GSS_C_NO_CONTEXT), but the preferred behavior is to leave the security
+ context (and the context_handle parameter) untouched for the application
+ to delete (using gss_delete_sec_context).
+
+ Parameters:
+
+ context_handle gss_ctx_id_t, read/modify
+ context handle for new context. Supply
+ GSS_C_NO_CONTEXT for first call; use value
+ returned in subsequent calls. Once
+ gss_accept_sec_context() has returned a value
+ via this parameter, resources have been assigned
+ to the corresponding context, and must be
+ freed by the application after use with a call
+ to gss_delete_sec_context().
+
+
+ acceptor_cred_handle gss_cred_id_t, read
+ Credential handle claimed by context acceptor.
+ Specify GSS_C_NO_CREDENTIAL to accept the
+ context as a default principal. If
+ GSS_C_NO_CREDENTIAL is specified, but no
+ default acceptor principal is defined,
+ GSS_S_NO_CRED will be returned.
+
+ input_token_buffer buffer, opaque, read
+ token obtained from remote application.
+
+ input_chan_bindings channel bindings, read, optional
+ Application-specified bindings. Allows
+ application to securely bind channel
+ identification information to the security
+ context. If channel bindings are not
+ used, specify GSS_C_NO_CHANNEL_BINDINGS.
+
+ src_name gss_name_t, modify, optional
+ Authenticated name of context initiator.
+
+
+
+ Wray Document Expiration: 1 September 1997 [Page 27]
+
+
+
+
+
+
+
+ INTERNET-DRAFT GSS-API V2 - C bindings March 1997
+
+
+
+ After use, this name should be deallocated by
+ passing it to gss_release_name(). If not
+ required, specify NULL.
+
+ mech_type Object ID, modify, optional
+ Security mechanism used. The returned
+ OID value will be a pointer into static
+ storage, and should be treated as read-only
+ by the caller (in particular, it does not
+ need to be freed). If not required, specify
+ NULL.
+
+ output_token buffer, opaque, modify
+ Token to be passed to peer application. If the
+ length field of the returned token buffer is 0,
+ then no token need be passed to the peer
+ application. If a non-zero length field is
+ returned, the associated storage must be freed
+ after use by the application with a call to
+ gss_release_buffer().
+
+ ret_flags bit-mask, modify, optional
+ Contains various independent flags, each of
+ which indicates that the context supports a
+ specific service option. If not needed,
+ specify NULL. Symbolic names are
+ provided for each flag, and the symbolic names
+ corresponding to the required flags
+ should be logically-ANDed with the ret_flags
+ value to test whether a given option is
+ supported by the context. The flags are:
+ GSS_C_DELEG_FLAG
+ True - Delegated credentials are available
+ via the delegated_cred_handle
+ parameter
+ False - No credentials were delegated
+ GSS_C_MUTUAL_FLAG
+ True - Remote peer asked for mutual
+ authentication
+ False - Remote peer did not ask for mutual
+ authentication
+ GSS_C_REPLAY_FLAG
+ True - replay of protected messages
+ will be detected
+ False - replayed messages will not be
+ detected
+ GSS_C_SEQUENCE_FLAG
+ True - out-of-sequence protected
+ messages will be detected
+ False - out-of-sequence messages will not
+ be detected
+
+
+
+ Wray Document Expiration: 1 September 1997 [Page 28]
+
+
+
+
+
+
+
+ INTERNET-DRAFT GSS-API V2 - C bindings March 1997
+
+
+
+ GSS_C_CONF_FLAG
+ True - Confidentiality service may be invoked
+ by calling the gss_wrap routine
+ False - No confidentiality service (via
+ gss_wrap) available. gss_wrap will
+ provide message encapsulation,
+ data-origin authentication and
+ integrity services only.
+ GSS_C_INTEG_FLAG
+ True - Integrity service may be invoked by
+ calling either gss_get_mic or gss_wrap
+ routines.
+ False - Per-message integrity service
+ unavailable.
+ GSS_C_ANON_FLAG
+ True - The initiator does not wish to
+ be authenticated; the src_name
+ parameter (if requested) contains
+ an anonymous internal name.
+ False - The initiator has been
+ authenticated normally.
+ GSS_C_PROT_READY_FLAG
+ True - Protection services (as specified
+ by the states of the GSS_C_CONF_FLAG
+ and GSS_C_INTEG_FLAG) are available
+ if the accompanying major status return
+ value is either GSS_S_COMPLETE or
+ GSS_S_CONTINUE_NEEDED.
+ False - Protection services (as specified
+ by the states of the GSS_C_CONF_FLAG
+ and GSS_C_INTEG_FLAG) are available
+ only if the accompanying major status
+ return value is GSS_S_COMPLETE.
+ GSS_C_TRANS_FLAG
+ True - The resultant security context may
+ be transferred to other processes via
+ a call to gss_export_sec_context().
+ False - The security context is not
+ transferrable.
+ All other bits should be set to zero.
+
+ time_rec Integer, modify, optional
+ number of seconds for which the context
+ will remain valid. Specify NULL if not required.
+
+ delegated_cred_handle
+ gss_cred_id_t, modify, optional
+ credential handle for credentials received from
+ context initiator. Only valid if deleg_flag in
+ ret_flags is true, in which case an explicit
+
+
+
+ Wray Document Expiration: 1 September 1997 [Page 29]
+
+
+
+
+
+
+
+ INTERNET-DRAFT GSS-API V2 - C bindings March 1997
+
+
+
+ credential handle (i.e. not GSS_C_NO_CREDENTIAL)
+ will be returned; if deleg_flag is false,
+ gss_accept_context() will set this parameter to
+ GSS_C_NO_CREDENTIAL. If a credential handle is
+ returned, the associated resources must be released
+ by the application after use with a call to
+ gss_release_cred(). Specify NULL if not required.
+
+
+ minor_status Integer, modify
+ Mechanism specific status code.
+
+
+ Function value: GSS status code
+
+ GSS_S_COMPLETE Successful completion
+
+ GSS_S_CONTINUE_NEEDED Indicates that a token from the peer application
+ is required to complete the context, and that
+ gss_accept_sec_context must be called again with that
+ token.
+
+ GSS_S_DEFECTIVE_TOKEN Indicates that consistency checks performed on the
+ input_token failed.
+
+ GSS_S_DEFECTIVE_CREDENTIAL Indicates that consistency checks performed
+ on the credential failed.
+
+ GSS_S_NO_CRED The supplied credentials were not valid for context
+ acceptance, or the credential handle did not reference
+ any credentials.
+
+ GSS_S_CREDENTIALS_EXPIRED The referenced credentials have expired.
+
+ GSS_S_BAD_BINDINGS The input_token contains different channel bindings
+ to those specified via the input_chan_bindings
+ parameter.
+
+ GSS_S_NO_CONTEXT Indicates that the supplied context handle did not
+ refer to a valid context.
+
+ GSS_S_BAD_SIG The input_token contains an invalid MIC.
+
+ GSS_S_OLD_TOKEN The input_token was too old. This is a fatal error
+ during context establishment.
+
+ GSS_S_DUPLICATE_TOKEN The input_token is valid, but is a duplicate of a
+ token already processed. This is a fatal error during
+ context establishment.
+
+
+
+
+
+ Wray Document Expiration: 1 September 1997 [Page 30]
+
+
+
+
+
+
+
+ INTERNET-DRAFT GSS-API V2 - C bindings March 1997
+
+
+
+ GSS_S_BAD_MECH The received token specified a mechanism that is not
+ supported by the implementation or the provided
+ credential.
+
+
+
+
+
+
+
+ 7.2. gss_acquire_cred
+
+
+ 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)
+
+ Purpose:
+
+ Allows an application to acquire a handle for a pre-existing credential
+ by name. GSS-API implementations must impose a local access-control
+ policy on callers of this routine to prevent unauthorized callers from
+ acquiring credentials to which they are not entitled. This routine is
+ not intended to provide a ``login to the network'' function, as such a
+ function would involve the creation of new credentials rather than
+ merely acquiring a handle to existing credentials. Such functions, if
+ required, should be defined in implementation-specific extensions to the
+ API.
+
+ If desired_name is GSS_C_NO_NAME, the call is interpreted as a request
+ for a credential handle that will invoke default behavior when passed to
+ gss_init_sec_context() (if cred_usage is GSS_C_INITIATE or GSS_C_BOTH)
+ or gss_accept_sec_context() (if cred_usage is GSS_C_ACCEPT or
+ GSS_C_BOTH).
+
+ This routine is expected to be used primarily by context acceptors,
+ since implementations are likely to provide mechanism-specific ways of
+ obtaining GSS-API initiator credentials from the system login process.
+ Some implementations may therefore not support the acquisition of
+ GSS_C_INITIATE or GSS_C_BOTH credentials via gss_acquire_cred for any
+ name other than an empty name.
+
+ If credential acquisition is time-consuming for a mechanism, the
+ mechanism may chooses to delay the actual acquisition until the
+ credential is required (e.g. by gss_init_sec_context or
+
+
+
+ Wray Document Expiration: 1 September 1997 [Page 31]
+
+
+
+
+
+
+
+ INTERNET-DRAFT GSS-API V2 - C bindings March 1997
+
+
+
+ gss_accept_sec_context). Such mechanism-specific implementation
+ decisions should be invisible to the calling application; thus a call of
+ gss_inquire_cred immediately following the call of gss_acquire_cred must
+ return valid credential data, and may therefore incur the overhead of a
+ deferred credential acquisition.
+
+ Parameters:
+
+ desired_name gss_name_t, read
+ Name of principal whose credential
+ should be acquired
+
+ time_req Integer, read, optional
+ number of seconds that credentials
+ should remain valid. Specify GSS_C_INDEFINITE
+ to request that the credentials have the maximum
+ permitted lifetime.
+
+ desired_mechs Set of Object IDs, read, optional
+ set of underlying security mechanisms that
+ may be used. GSS_C_NO_OID_SET may be used
+ to obtain an implementation-specific default.
+
+ cred_usage gss_cred_usage_t, read
+ GSS_C_BOTH - Credentials may be used
+ either to initiate or accept
+ security contexts.
+ GSS_C_INITIATE - Credentials will only be
+ used to initiate security
+ contexts.
+ GSS_C_ACCEPT - Credentials will only be used to
+ accept security contexts.
+
+ output_cred_handle gss_cred_id_t, modify
+ The returned credential handle. Resources
+ associated with this credential handle must
+ be released by the application after use
+ with a call to gss_release_cred().
+
+ actual_mechs Set of Object IDs, modify, optional
+ The set of mechanisms for which the
+ credential is valid. Storage associated
+ with the returned OID-set must be released by
+ the application after use with a call to
+ gss_release_oid_set(). Specify NULL if not
+ required.
+
+ time_rec Integer, modify, optional
+ Actual number of seconds for which the
+ returned credentials will remain valid. If the
+ implementation does not support expiration of
+
+
+
+ Wray Document Expiration: 1 September 1997 [Page 32]
+
+
+
+
+
+
+
+ INTERNET-DRAFT GSS-API V2 - C bindings March 1997
+
+
+
+ credentials, the value GSS_C_INDEFINITE will
+ be returned. Specify NULL if not required
+
+ minor_status Integer, modify
+ Mechanism specific status code.
+
+ Function value: GSS status code
+
+ GSS_S_COMPLETE Successful completion
+
+ GSS_S_BAD_MECH Unavailable mechanism requested
+
+ GSS_S_BAD_NAMETYPE Type contained within desired_name parameter is not
+ supported
+
+ GSS_S_BAD_NAME Value supplied for desired_name parameter is ill-
+ formed.
+
+ GSS_S_CREDENTIALS_EXPIRED The credentials could not be acquired because
+ they have expired.
+
+ GSS_S_NO_CRED No credentials were found for the specified name.
+
+
+
+
+
+
+
+ 7.3. gss_add_cred
+
+
+ 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)
+
+
+
+
+
+
+
+
+
+
+ Wray Document Expiration: 1 September 1997 [Page 33]
+
+
+
+
+
+
+
+ INTERNET-DRAFT GSS-API V2 - C bindings March 1997
+
+
+
+ Purpose:
+
+ Adds a credential-element to a credential. The credential-element is
+ identified by the name of the principal to which it refers. GSSAPI
+ implementations must impose a local access-control policy on callers of
+ this routine to prevent unauthorized callers from acquiring credential-
+ elements to which they are not entitled. This routine is not intended to
+ provide a ``login to the network'' function, as such a function would
+ involve the creation of new mechanism-specific authentication data,
+ rather than merely acquiring a GSSAPI handle to existing data. Such
+ functions, if required, should be defined in implementation-specific
+ extensions to the API.
+
+ This routine is expected to be used primarily by context acceptors,
+ since implementations are likely to provide mechanism-specific ways of
+ obtaining GSS-API initiator credentials from the system login process.
+ Some implementations may therefore not support the acquisition of
+ GSS_C_INITIATE or GSS_C_BOTH credentials via gss_acquire_cred.
+
+ If credential acquisition is time-consuming for a mechanism, the
+ mechanism may chooses to delay the actual acquisition until the
+ credential is required (e.g. by gss_init_sec_context or
+ gss_accept_sec_context). Such mechanism-specific implementation
+ decisions should be invisible to the calling application; thus a call of
+ gss_inquire_cred immediately following the call of gss_acquire_cred must
+ return valid credential data, and may therefore incur the overhead of a
+ deferred credential acquisition.
+
+ This routine can be used to either create a new credential containing
+ all credential-elements of the original in addition to the newly-acquire
+ credential-element, or to add the new credential-element to an existing
+ credential. If NULL is specified for the output_cred_handle parameter
+ argument, the new credential-element will be added to the credential
+ identified by input_cred_handle; if a valid pointer is specified for the
+ output_cred_handle parameter, a new credential and handle will be
+ created.
+
+ If GSS_C_NO_CREDENTIAL is specified as the input_cred_handle, the
+ gss_add_cred will create its output_cred_handle based on default
+ behavior. That is, the call will have the same effect as if the
+ application had first made a call to gss_acquire_cred(), specifying the
+ same usage and passing GSS_C_NO_NAME as the desired_name parameter to
+ obtain an explicit credential handle embodying default behavior, passed
+ this credential handle to gss_add_cred(), and finally called
+ gss_release_cred() on the first credential handle.
+
+ If GSS_C_NO_CREDENTIAL is specified as the input_cred_handle parameter,
+ a non-NULL output_cred_handle must be supplied.
+
+ Parameters:
+
+
+
+
+ Wray Document Expiration: 1 September 1997 [Page 34]
+
+
+
+
+
+
+
+ INTERNET-DRAFT GSS-API V2 - C bindings March 1997
+
+
+
+ minor_status Integer, modify
+ Mechanism specific status code.
+
+ input_cred_handle gss_cred_id_t, read, optional
+ The credential to which a credential-element
+ will be added. If GSS_C_NO_CREDENTIAL is
+ specified, the routine will create the new
+ credential based on default behavior (see
+ description above). Note that, while the
+ credential-handle is not modified by
+ gss_add_cred(), the underlying credential
+ will be modified if output_credential_handle
+ is NULL.
+
+ desired_name gss_name_t, read.
+ Name of principal whose credential
+ should be acquired.
+
+ desired_mech Object ID, read
+ Underlying security mechanism with which the
+ credential may be used.
+
+ cred_usage gss_cred_usage_t, read
+ GSS_C_BOTH - Credential may be used
+ either to initiate or accept
+ security contexts.
+ GSS_C_INITIATE - Credential will only be
+ used to initiate security
+ contexts.
+ GSS_C_ACCEPT - Credential will only be used to
+ accept security contexts.
+
+ initiator_time_req Integer, read, optional
+ number of seconds that the credential
+ should remain valid for initiating security
+ contexts. This argument is ignored if the
+ created credentials are of type GSS_C_ACCEPT.
+ Specify GSS_C_INDEFINITE to request that the
+ credentials have the maximum permitted initiator
+ lifetime.
+
+ acceptor_time_req Integer, read, optional
+ number of seconds that the credential
+ should remain valid for accepting security
+ contexts. This argument is ignored if the
+ created credentials are of type GSS_C_INITIATE.
+ Specify GSS_C_INDEFINITE to request that the
+ credentials have the maximum permitted initiator
+ lifetime.
+
+
+
+
+ Wray Document Expiration: 1 September 1997 [Page 35]
+
+
+
+
+
+
+
+ INTERNET-DRAFT GSS-API V2 - C bindings March 1997
+
+
+
+ output_cred_handle gss_cred_id_t, modify, optional
+ The returned credential handle, containing
+ the new credential-element and all the
+ credential-elements from input_cred_handle.
+ If a valid pointer to a gss_cred_id_t is
+ supplied for this parameter, gss_add_cred
+ creates a new credential handle containing all
+ credential-elements from the input_cred_handle
+ and the newly acquired credential-element; if
+ NULL is specified for this parameter, the newly
+ acquired credential-element will be added
+ to the credential identified by input_cred_handle.
+ The resources associated with any credential
+ handle returned via this parameter must be
+ released by the application after use with a
+ call to gss_release_cred().
+
+ actual_mechs Set of Object IDs, modify, optional
+ The complete set of mechanisms for which
+ the new credential is valid. Storage for
+ the returned OID-set must be freed by the
+ application after use with a call to
+ gss_release_oid_set(). Specify NULL if
+ not required.
+
+ initiator_time_rec Integer, modify, optional
+ Actual number of seconds for which the
+ returned credentials will remain valid for
+ initiating contexts using the specified
+ mechanism. If the implementation or mechanism
+ does not support expiration of credentials, the
+ value GSS_C_INDEFINITE will be returned. Specify
+ NULL if not required
+
+ acceptor_time_rec Integer, modify, optional
+ Actual number of seconds for which the
+ returned credentials will remain valid for
+ accepting security contexts using the specified
+ mechanism. If the implementation or mechanism
+ does not support expiration of credentials, the
+ value GSS_C_INDEFINITE will be returned. Specify
+ NULL if not required
+
+ Function value: GSS status code
+
+ GSS_S_COMPLETE Successful completion
+
+ GSS_S_BAD_MECH Unavailable mechanism requested
+
+ GSS_S_BAD_NAMETYPE Type contained within desired_name parameter is not
+ supported
+
+
+
+
+ Wray Document Expiration: 1 September 1997 [Page 36]
+
+
+
+
+
+
+
+ INTERNET-DRAFT GSS-API V2 - C bindings March 1997
+
+
+
+ GSS_S_BAD_NAME Value supplied for desired_name parameter is ill-
+ formed.
+
+ GSS_S_DUPLICATE_ELEMENT The credential already contains an element for
+ the requested mechanism with overlapping usage and
+ validity period.
+
+ GSS_S_CREDENTIALS_EXPIRED The required credentials could not be added
+ because they have expired.
+
+ GSS_S_NO_CRED No credentials were found for the specified name.
+
+
+
+
+
+
+
+ 7.4. gss_add_oid_set_member
+
+ OM_uint32 gss_add_oid_set_member (
+ OM_uint32 * minor_status,
+ const gss_OID member_oid,
+ gss_OID_set * oid_set)
+
+ Purpose:
+
+ Add an Object Identifier to an Object Identifier set. This routine is
+ intended for use in conjunction with gss_create_empty_oid_set when
+ constructing a set of mechanism OIDs for input to gss_acquire_cred.
+
+ The oid_set parameter must refer to an OID-set that was created by
+ GSSAPI (e.g. a set returned by gss_create_empty_oid_set()). GSSAPI
+ creates a copy of the member_oid and inserts this copy into the set,
+ expanding the storage allocated to the OID-set's elements array if
+ necessary. The routine may add the new member OID anywhere within the
+ elements array, and implementations should verify that the new
+ member_oid is not already contained within the elements array.
+
+ Parameters:
+
+ minor_status Integer, modify
+ Mechanism specific status code
+
+ member_oid Object ID, read
+ The object identifier to copied into
+ the set.
+
+ oid_set Set of Object ID, modify
+ The set in which the object identifier
+ should be inserted.
+
+
+
+ Wray Document Expiration: 1 September 1997 [Page 37]
+
+
+
+
+
+
+
+ INTERNET-DRAFT GSS-API V2 - C bindings March 1997
+
+
+
+ Function value: GSS status code
+
+ GSS_S_COMPLETE Successful completion
+
+
+
+
+
+
+
+ 7.5. gss_canonicalize_name
+
+ 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)
+
+ Purpose:
+
+ Generate a canonical mechanism name (MN) from an arbitrary internal
+ name. The mechanism name is the name that would be returned to a
+ context acceptor on successful authentication of a context where the
+ initiator used the input_name in a successful call to gss_acquire_cred,
+ specifying an OID set containing <mech_type> as its only member,
+ followed by a call to gss_init_sec_context, specifying <mech_type> as
+ the authentication mechanism.
+
+ Parameters:
+
+ minor_status Integer, modify
+ Mechanism specific status code
+
+ input_name gss_name_t, read
+ The name for which a canonical form is
+ desired
+
+ mech_type Object ID, read
+ The authentication mechanism for which the
+ canonical form of the name is desired. The
+ desired mechanism must be specified explicitly;
+ no default is provided.
+
+ output_name gss_name_t, modify
+ The resultant canonical name. Storage
+ associated with this name must be freed by
+ the application after use with a call to
+ gss_release_name().
+
+ Function value: GSS status code
+
+
+
+
+ Wray Document Expiration: 1 September 1997 [Page 38]
+
+
+
+
+
+
+
+ INTERNET-DRAFT GSS-API V2 - C bindings March 1997
+
+
+
+ GSS_S_COMPLETE Successful completion.
+
+ GSS_S_BAD_MECH The identified mechanism is not supported.
+
+ GSS_S_BAD_NAMETYPE The provided internal name contains no elements that
+ could be processed by the sepcified mechanism.
+
+ GSS_S_BAD_NAME The provided internal name was ill-formed.
+
+
+
+
+
+
+
+ 7.6. gss_compare_name
+
+ OM_uint32 gss_compare_name (
+ OM_uint32 * minor_status,
+ const gss_name_t name1,
+ const 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.
+
+ If either name presented to gss_compare_name denotes an anonymous
+ principal, the routines should indicate that the two names do not refer
+ to the same identity.
+
+ 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
+ non-zero - names refer to same entity
+ zero - names refer to different entities
+ (strictly, the names are not known
+ to refer to the same identity).
+
+ Function value: GSS status code
+
+
+
+
+ Wray Document Expiration: 1 September 1997 [Page 39]
+
+
+
+
+
+
+
+ INTERNET-DRAFT GSS-API V2 - C bindings March 1997
+
+
+
+ GSS_S_COMPLETE Successful completion
+
+ GSS_S_BAD_NAMETYPE The two names were of incomparable types.
+
+ GSS_S_BAD_NAME One or both of name1 or name2 was ill-formed
+
+
+
+
+
+
+
+ 7.7. gss_context_time
+
+ OM_uint32 gss_context_time (
+ OM_uint32 * minor_status,
+ const gss_ctx_id_t context_handle,
+ OM_uint32 * time_rec)
+
+ Purpose:
+
+ Determines the number of seconds for which the specified context will
+ remain valid.
+
+ Parameters:
+
+ minor_status Integer, modify
+ Implementation specific status code.
+
+ context_handle gss_ctx_id_t, read
+ Identifies the context to be interrogated.
+
+ time_rec Integer, modify
+ Number of seconds that the context will remain
+ valid. If the context has already expired,
+ zero will be returned.
+
+ 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
+
+
+
+
+
+
+
+
+
+ Wray Document Expiration: 1 September 1997 [Page 40]
+
+
+
+
+
+
+
+ INTERNET-DRAFT GSS-API V2 - C bindings March 1997
+
+
+
+ 7.8. gss_create_empty_oid_set
+
+ OM_uint32 gss_create_empty_oid_set (
+ OM_uint32 * minor_status,
+ gss_OID_set * oid_set)
+
+ Purpose:
+
+ Create an object-identifier set containing no object identifiers, to
+ which members may be subsequently added using the
+ gss_add_oid_set_member() routine. These routines are intended to be
+ used to construct sets of mechanism object identifiers, for input to
+ gss_acquire_cred.
+
+ Parameters:
+
+ minor_status Integer, modify
+ Mechanism specific status code
+
+ oid_set Set of Object IDs, modify
+ The empty object identifier set.
+ The routine will allocate the
+ gss_OID_set_desc object, which the
+ application must free after use with
+ a call to gss_release_oid_set().
+
+ Function value: GSS status code
+
+ GSS_S_COMPLETE Successful completion
+
+
+
+
+
+
+
+ 7.9. gss_delete_sec_context
+
+ OM_uint32 gss_delete_sec_context (
+ OM_uint32 * minor_status,
+ gss_ctx_id_t * context_handle,
+ gss_buffer_t output_token)
+
+ Purpose:
+
+ Delete a security context. gss_delete_sec_context will delete the local
+ data structures associated with the specified security context, and may
+ generate an output_token, which when passed to the peer
+ gss_process_context_token will instruct it to do likewise. If no token
+ is required by the mechanism, the GSS-API should set the length field of
+ the output_token (if provided) to zero. No further security services
+
+
+
+ Wray Document Expiration: 1 September 1997 [Page 41]
+
+
+
+
+
+
+
+ INTERNET-DRAFT GSS-API V2 - C bindings March 1997
+
+
+
+ may be obtained using the context specified by context_handle.
+
+ In addition to deleting established security contexts,
+ gss_delete_sec_context must also be able to delete "half-built" security
+ contexts resulting from an incomplete sequence of
+ gss_init_sec_context()/gss_accept_sec_context() calls.
+
+ The output_token parameter is retained for compatibility with version 1
+ of the GSS-API. It is recommended that both peer applications invoke
+ gss_delete_sec_context passing the value GSS_C_NO_BUFFER for the
+ output_token parameter, indicating that no token is required, and that
+ gss_delete_sec_context should simply delete local context data
+ structures. If the application does pass a valid buffer to
+ gss_delete_sec_context, mechanisms are encouraged to return a zero-
+ length token, indicating that no peer action is necessary, and that no
+ token should be transferred by the application.
+
+ Parameters:
+
+ minor_status Integer, modify
+ Mechanism specific status code.
+
+ context_handle gss_ctx_id_t, modify
+ context handle identifying context to delete.
+ After deleting the context, the GSSAPI will set
+ this context handle to GSS_C_NO_CONTEXT.
+
+ output_token buffer, opaque, modify, optional
+ token to be sent to remote application to
+ instruct it to also delete the context. It
+ is recommended that applications specify
+ GSS_C_NO_BUFFER for this parameter, requesting
+ local deletion only. If a buffer parameter is
+ provided by the application, the mechanism may
+ return a token in it; mechanisms that implement
+ only local deletion should set the length field of
+ this token to zero to indicate to the application
+ that no token is to be sent to the peer.
+
+ Function value: GSS status code
+
+ GSS_S_COMPLETE Successful completion
+
+ GSS_S_NO_CONTEXT No valid context was supplied
+
+
+
+
+
+
+
+
+
+
+ Wray Document Expiration: 1 September 1997 [Page 42]
+
+
+
+
+
+
+
+ INTERNET-DRAFT GSS-API V2 - C bindings March 1997
+
+
+
+ 7.10. gss_display_name
+
+ 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)
+
+ 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 GSS-API implementation.
+
+ If input_name denotes an anonymous principal, the implementation should
+ return the gss_OID value GSS_C_NT_ANONYMOUS as the output_name_type, and
+ a textual name that is syntactically distinct from all valid supported
+ printable names in output_name_buffer.
+
+ 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.
+ The application must free storage associated
+ with this name after use with a call to
+ gss_release_buffer().
+
+ output_name_type Object ID, modify, optional
+ 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
+ (in particular, it does not need to be freed).
+ Specify NULL if not required.
+
+ Function value: GSS status code
+
+ GSS_S_COMPLETE Successful completion
+
+ GSS_S_BAD_NAME input_name was ill-formed
+
+
+
+
+
+
+
+
+
+ Wray Document Expiration: 1 September 1997 [Page 43]
+
+
+
+
+
+
+
+ INTERNET-DRAFT GSS-API V2 - C bindings March 1997
+
+
+
+ 7.11. gss_display_status
+
+ 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)
+
+ Purpose:
+
+ Allows an application to obtain a textual representation of a GSS-API
+ status code, for display to the user or for logging purposes. Since
+ some status values may indicate multiple conditions, applications may
+ need to call gss_display_status multiple times, each call generating a
+ single text string. The message_context parameter is used by
+ gss_acquire_cred to store state information about which error messages
+ have already been extracted from a given status_value; message_context
+ must be initialized to 0 by the application prior to the first call, and
+ gss_display_status will return a non-zero value in this parameter if
+ there are further messages to extract. The message_context parameter
+ contains all state information required by gss_display_status in order
+ to extract further messages from the status_value; even when a non-zero
+ value is returned in this parameter, the application is not required to
+ call gss_display_status again unless subsequent messages are desired.
+ The following code extracts all messages from a given status code and
+ prints them to stderr:
+
+
+ OM_uint32 message_context;
+ OM_uint32 status_code;
+ OM_uint32 maj_status;
+ OM_uint32 min_status;
+ gss_buffer_desc status_string;
+
+ ...
+
+ message_context = 0;
+
+ do {
+
+ maj_status = gss_display_status (&min_status,
+ status_code,
+ GSS_C_GSS_CODE,
+ GSS_C_NO_OID,
+ &message_context,
+ &status_string)
+
+ fprintf(stderr,
+ "%.*s\n",
+
+
+
+ Wray Document Expiration: 1 September 1997 [Page 44]
+
+
+
+
+
+
+
+ INTERNET-DRAFT GSS-API V2 - C bindings March 1997
+
+
+
+ status_string.length,
+ status_string.value);
+
+ gss_release_buffer(&min_status,
+ &status_string);
+
+ } while (message_context != 0);
+
+
+
+ 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_NO_OID to
+ obtain the system default.
+
+ message_context Integer, read/modify
+ Should be initialized to zero by the
+ application prior to the first call.
+ On return from gss_display_status(),
+ a non-zero status_value parameter indicates
+ that additional messages may be extracted
+ from the status code via subsequent calls
+ to gss_display_status(), passing the same
+ status_value, status_type, mech_type, and
+ message_context parameters.
+
+ status_string buffer, character string, modify
+ textual interpretation of the status_value.
+ Storage associated with this parameter 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
+
+
+
+
+
+ Wray Document Expiration: 1 September 1997 [Page 45]
+
+
+
+
+
+
+
+ INTERNET-DRAFT GSS-API V2 - C bindings March 1997
+
+
+
+ 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.
+
+
+
+
+
+
+
+ 7.12. gss_duplicate_name
+
+ OM_uint32 gss_duplicate_name (
+ OM_uint32 * minor_status,
+ const gss_name_t src_name,
+ gss_name_t * dest_name)
+
+ Purpose:
+
+ Create an exact duplicate of the existing internal name src_name. The
+ new dest_name will be independent of src_name (i.e. src_name and
+ dest_name must both be released, and the release of one shall not affect
+ the validity of the other).
+
+ Parameters:
+
+ minor_status Integer, modify
+ Mechanism specific status code.
+
+ src_name gss_name_t, read
+ internal name to be duplicated.
+
+ dest_name gss_name_t, modify
+ The resultant copy of <src_name>.
+ Storage associated with this name must
+ be freed by the application after use
+ with a call to gss_release_name().
+
+ Function value: GSS status code
+
+ GSS_S_COMPLETE Successful completion
+
+ GSS_S_BAD_NAME The src_name parameter was ill-formed.
+
+
+
+
+
+
+
+
+
+ Wray Document Expiration: 1 September 1997 [Page 46]
+
+
+
+
+
+
+
+ INTERNET-DRAFT GSS-API V2 - C bindings March 1997
+
+
+
+ 7.13. gss_export_name
+
+ OM_uint32 gss_export_name (
+ OM_uint32 * minor_status,
+ const gss_name_t input_name,
+ gss_buffer_t exported_name)
+
+ Purpose:
+
+ To produce a canonical contiguous string representation of a mechanism
+ name (MN), suitable for direct comparison (e.g. with memcmp) for use in
+ authorization functions (e.g. matching entries in an access-control
+ list).
+
+ The <input_name> parameter must specify a valid MN (i.e. an internal
+ name generated by gss_accept_sec_context or by gss_canonicalize_name).
+
+
+ Parameters:
+
+ minor_status Integer, modify
+ Mechanism specific status code
+
+ input_name gss_name_t, read
+ The MN to be exported
+
+ exported_name gss_buffer_t, octet-string, modify
+ The canonical contiguous string form of
+ <input_name>. Storage associated with
+ this string must freed by the application
+ after use with gss_release_buffer().
+
+ Function value: GSS status code
+
+ GSS_S_COMPLETE Successful completion
+
+ GSS_S_NAME_NOT_MN The provided internal name was not a mechanism name.
+
+ GSS_S_BAD_NAME The provide internal name was ill-formed.
+
+ GSS_S_BAD_NAMETYPE The internal name was of a type not supported by the
+ GSSAPI implementation.
+
+
+
+
+
+
+
+
+
+
+
+
+ Wray Document Expiration: 1 September 1997 [Page 47]
+
+
+
+
+
+
+
+ INTERNET-DRAFT GSS-API V2 - C bindings March 1997
+
+
+
+ 7.14. gss_export_sec_context
+
+ OM_uint32 gss_export_sec_context (
+ OM_uint32 * minor_status,
+ gss_ctx_id_t * context_handle,
+ gss_buffer_t interprocess_token)
+
+ Purpose:
+
+ Provided to support the sharing of work between multiple processes.
+ This routine will typically be used by the context-acceptor, in an
+ application where a single process receives incoming connection requests
+ and accepts security contexts over them, then passes the established
+ context to one or more other processes for message exchange.
+ gss_export_sec_context() deactivates the security context for the
+ calling process and creates an interprocess token which, when passed to
+ gss_import_sec_context in another process, will re-activate the context
+ in the second process. Only a single instantiation of a given context
+ may be active at any one time; a subsequent attempt by a context
+ exporter to access the exported security context will fail.
+
+ The implementation may constrain the set of processes by which the
+ interprocess token may be imported, either as a function of local
+ security policy, or as a result of implementation decisions. For
+ example, some implementations may constrain contexts to be passed only
+ between processes that run under the same account, or which are part of
+ the same process group.
+
+ The interprocess token may contain security-sensitive information (for
+ example cryptographic keys). While mechanisms are encouraged to either
+ avoid placing such sensitive information within interprocess tokens, or
+ to encrypt the token before returning it to the application, in a
+ typical object-library GSSAPI implementation this may not be possible.
+ Thus the application must take care to protect the interprocess token,
+ and ensure that any process to which the token is transferred is
+ trustworthy.
+
+ If creation of the interprocess token is succesful, the implementation
+ shall deallocate all process-wide resources associated with the security
+ context, and set the context_handle to GSS_C_NO_CONTEXT. In the event
+ of an error that makes it impossible to complete the export of the
+ security context, the implementation must not return an interprocess
+ token, and should strive to leave the security context referenced by the
+ context_handle parameter untouched. If this is impossible, it is
+ permissible for the implementation to delete the security context,
+ providing it also sets the context_handle parameter to GSS_C_NO_CONTEXT.
+
+ Parameters:
+
+ minor_status Integer, modify
+ Mechanism specific status code
+
+
+
+ Wray Document Expiration: 1 September 1997 [Page 48]
+
+
+
+
+
+
+
+ INTERNET-DRAFT GSS-API V2 - C bindings March 1997
+
+
+
+ context_handle gss_ctx_id_t, modify
+ context handle identifying the context to transfer.
+
+ interprocess_token buffer, opaque, modify
+ token to be transferred to target process.
+ Storage associated with this token 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 expired
+
+ GSS_S_NO_CONTEXT The context was invalid
+
+ GSS_S_UNAVAILABLE The operation is not supported.
+
+
+
+
+
+
+
+ 7.15. gss_get_mic
+
+ 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 msg_token)
+
+ Purpose:
+
+ Generates a cryptographic MIC for the supplied message, and places the
+ MIC in a token for transfer to the peer application. The qop_req
+ parameter allows a choice between several cryptographic algorithms, if
+ supported by the chosen mechanism.
+
+ Parameters:
+
+ minor_status Integer, modify
+ Implementation specific status code.
+
+ context_handle gss_ctx_id_t, read
+ identifies the context on which the message
+ will be sent
+
+
+
+
+ Wray Document Expiration: 1 September 1997 [Page 49]
+
+
+
+
+
+
+
+ INTERNET-DRAFT GSS-API V2 - C bindings March 1997
+
+
+ qop_req gss_qop_t, read, optional
+ Specifies requested quality of protection.
+ Callers are encouraged, on portability grounds,
+ to accept the default quality of protection
+ offered by the chosen mechanism, which may be
+ requested by specifying GSS_C_QOP_DEFAULT for
+ this parameter. If an unsupported protection
+ strength is requested, gss_get_mic will return a
+ major_status of GSS_S_BAD_QOP.
+
+ message_buffer buffer, opaque, read
+ message to be protected
+
+ msg_token buffer, opaque, modify
+ buffer to receive token. The application must
+ free storage associated with this buffer 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.
+
+
+
+
+
+
+
+ 7.16. gss_import_name
+
+ 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)
+
+ Purpose:
+
+ Convert a contiguous string name to internal form. In general, the
+ internal name returned (via the <output_name> parameter) will not be an
+ MN; the exception to this is if the <input_name_type> indicates that the
+ contiguous string provided via the <input_name_buffer> parameter is of
+ type GSS_C_NT_EXPORT_NAME, in which case the returned internal name will
+ be an MN for the mechanism that exported the name.
+
+
+
+
+ Wray Document Expiration: 1 September 1997 [Page 50]
+
+
+
+
+
+
+
+ INTERNET-DRAFT GSS-API V2 - C bindings March 1997
+
+
+
+ Parameters:
+
+ minor_status Integer, modify
+ Mechanism specific status code
+
+ input_name_buffer buffer, octet-string, read
+ buffer containing contiguous string name to convert
+
+ input_name_type Object ID, read, optional
+ Object ID specifying type of printable
+ name. Applications may specify either
+ GSS_C_NO_OID to use a mechanism-specific
+ default printable syntax, or an OID registered
+ by the GSS-API implementation to name a
+ specific namespace.
+
+ output_name gss_name_t, modify
+ returned name in internal form. Storage
+ associated with this name must be freed
+ by the application after use with a call
+ to gss_release_name().
+
+ 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
+
+
+
+
+
+
+
+
+ 7.17. gss_import_sec_context
+
+ OM_uint32 gss_import_sec_context (
+ OM_uint32 * minor_status,
+ const gss_buffer_t interprocess_token,
+ gss_ctx_id_t * context_handle)
+
+ Purpose:
+
+ Allows a process to import a security context established by another
+ process. A given interprocess token may be imported only once. See
+ gss_export_sec_context.
+
+
+
+
+ Wray Document Expiration: 1 September 1997 [Page 51]
+
+
+
+
+
+
+
+ INTERNET-DRAFT GSS-API V2 - C bindings March 1997
+
+
+
+ Parameters:
+
+ minor_status Integer, modify
+ Mechanism specific status code
+
+ interprocess_token buffer, opaque, modify
+ token received from exporting process
+
+ context_handle gss_ctx_id_t, modify
+ context handle of newly reactivated context.
+ Resources associated with this context handle
+ must be released by the application after use
+ with a call to gss_delete_sec_context().
+
+
+ Function value: GSS status code
+
+ GSS_S_COMPLETE Successful completion.
+
+ GSS_S_NO_CONTEXT The token did not contain a valid context reference.
+
+ GSS_S_DEFECTIVE_TOKEN The token was invalid.
+
+ GSS_S_UNAVAILABLE The operation is unavailable.
+
+ GSS_S_UNAUTHORIZED Local policy prevents the import of this context by
+ the current process..
+
+
+
+
+
+
+
+ 7.18. 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.
+
+
+
+
+ Wray Document Expiration: 1 September 1997 [Page 52]
+
+
+
+
+
+
+
+ INTERNET-DRAFT GSS-API V2 - C bindings March 1997
+
+
+ mech_set set of Object IDs, modify
+ set of implementation-supported mechanisms.
+ The returned gss_OID_set value will be a
+ dynamically-allocated OID set, that should
+ be released by the caller after use with a
+ call to gss_release_oid_set().
+
+ Function value: GSS status code
+
+ GSS_S_COMPLETE Successful completion
+
+
+
+
+
+
+
+ 7.19. gss_init_sec_context
+
+ 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 )
+
+ Purpose:
+
+ Initiates the establishment of a security context between the
+ application and a remote peer. Initially, the input_token parameter
+ should be specified either as GSS_C_NO_BUFFER, or as a pointer to a
+ gss_buffer_desc object whose length field contains the value zero. The
+ routine may return a output_token which should be transferred to the
+ peer application, where the peer application will present it to
+ gss_accept_sec_context. If no token need be sent, gss_init_sec_context
+ will indicate this by setting the length field of the output_token
+ argument to zero. To complete the context establishment, one or more
+ reply tokens may be required from the peer application; if so,
+ gss_init_sec_context will return a status containing the supplementary
+ information bit GSS_S_CONTINUE_NEEDED. In this case,
+ gss_init_sec_context should be called again when the reply token is
+ received from the peer application, passing the reply token to
+ gss_init_sec_context via the input_token parameters.
+
+
+
+ Wray Document Expiration: 1 September 1997 [Page 53]
+
+
+
+
+
+
+
+ INTERNET-DRAFT GSS-API V2 - C bindings March 1997
+
+
+
+ Portable applications should be constructed to use the token length and
+ return status to determine whether a token needs to be sent or waited
+ for. Thus a typical portable caller should always invoke
+ gss_init_sec_context within a loop:
+
+ int context_established = 0;
+ gss_ctx_id_t context_hdl = GSS_C_NO_CONTEXT;
+ ...
+ input_token->length = 0;
+
+ while (!context_established) {
+ maj_stat = gss_init_sec_context(&min_stat,
+ cred_hdl,
+ &context_hdl,
+ target_name,
+ desired_mech,
+ desired_services,
+ desired_time,
+ input_bindings,
+ input_token,
+ &actual_mech,
+ output_token,
+ &actual_services,
+ &actual_time);
+ if (GSS_ERROR(maj_stat)) {
+ report_error(maj_stat, min_stat);
+ };
+ if (output_token->length != 0) {
+ send_token_to_peer(output_token);
+ gss_release_buffer(&min_stat,
+ output_token)
+ };
+ if (GSS_ERROR(maj_stat)) {
+ if (context_hdl != GSS_C_NO_CONTEXT)
+ gss_delete_sec_context(&min_stat,
+ &context_hdl,
+ GSS_C_NO_BUFFER);
+ break;
+ };
+ if (maj_stat & GSS_S_CONTINUE_NEEDED) {
+ receive_token_from_peer(input_token);
+ } else {
+ context_established = 1;
+ };
+ };
+
+ Whenever the routine returns a major status that includes the value
+ GSS_S_CONTINUE_NEEDED, the context is not fully established and the
+ following restrictions apply to the output parameters:
+
+
+
+
+
+ Wray Document Expiration: 1 September 1997 [Page 54]
+
+
+
+
+
+
+
+ INTERNET-DRAFT GSS-API V2 - C bindings March 1997
+
+
+
+ (a) The value returned via the time_rec parameter is undefined
+
+ (b) Unless the accompanying ret_flags parameter contains the bit
+ GSS_C_PROT_READY_FLAG, indicating that per-message services may be
+ applied in advance of a successful completion status, the value
+ returned via the actual_mech_type parameter is undefined until the
+ routine returns a major status value of GSS_S_COMPLETE.
+
+ (c) The values of the GSS_C_DELEG_FLAG, GSS_C_MUTUAL_FLAG,
+ GSS_C_REPLAY_FLAG, GSS_C_SEQUENCE_FLAG, GSS_C_CONF_FLAG,
+ GSS_C_INTEG_FLAG and GSS_C_ANON_FLAG bits returned via the
+ ret_flags parameter should contain the values that the
+ implementation expects would be valid if context establishment
+ were to succeed. In particular, if the application has requested
+ a service such as delegation or anonymous authentication via the
+ req_flags argument, and such a service is unavailable from the
+ underlying mechanism, gss_init_sec_context should generate a token
+ that will not provide the service, and indicate via the ret_flags
+ argument that the service will not be supported. The application
+ may choose to abort the context establishment by calling
+ gss_delete_sec_context (if it cannot continue in the absence of
+ the service), or it may choose to transmit the token and continue
+ context establishment (if the service was merely desired but not
+ mandatory).
+
+ The values of the GSS_C_PROT_READY_FLAG and GSS_C_TRANS_FLAG bits
+ within ret_flags should indicate the actual state at the time
+ gss_init_sec_context returns, whether or not the context is fully
+ established.
+
+ Although this requires that GSSAPI implementations set the
+ GSS_C_PROT_READY_FLAG in the final ret_flags returned to a caller
+ (i.e. when accompanied by a GSS_S_COMPLETE status code),
+ applications should not rely on this behavior as the flag was not
+ defined in Version 1 of the GSSAPI. Instead, applications should
+ be prepared to use per-message services after a successful context
+ establishment, according to the GSS_C_INTEG_FLAG and
+ GSS_C_CONF_FLAG values.
+
+ All other bits within the ret_flags argument should be set to
+ zero.
+
+ If the initial call of gss_init_sec_context() fails, the implementation
+ should not create a context object, and should leave the value of the
+ context_handle parameter set to GSS_C_NO_CONTEXT to indicate this. In
+ the event of a failure on a subsequent call, the implementation is
+ permitted to delete the "half-built" security context (in which case it
+ should set the context_handle parameter to GSS_C_NO_CONTEXT), but the
+ preferred behavior is to leave the security context untouched for the
+ application to delete (using gss_delete_sec_context).
+
+
+
+
+ Wray Document Expiration: 1 September 1997 [Page 55]
+
+
+
+
+
+
+
+ INTERNET-DRAFT GSS-API V2 - C bindings March 1997
+
+
+
+ Parameters:
+
+ minor_status Integer, modify
+ Mechanism specific status code.
+
+ initiator_cred_handle gss_cred_id_t, read, optional
+ handle for credentials claimed. Supply
+ GSS_C_NO_CREDENTIAL to act as a default
+ initiator principal. If no default
+ initiator is defined, the function will
+ return GSS_S_NO_CRED.
+
+ context_handle gss_ctx_id_t, read/modify
+ context handle for new context. Supply
+ GSS_C_NO_CONTEXT for first call; use value
+ returned by first call in continuation calls.
+ Resources associated with this context-handle
+ must be released by the application after use
+ with a call to gee_delete_sec_context().
+
+ target_name gss_name_t, read
+ Name of target
+
+ mech_type OID, read, optional
+ Object ID of desired mechanism. Supply
+ GSS_C_NO_OID to obtain an implementation
+ specific default
+
+ req_flags bit-mask, read
+ Contains various independent flags, each of
+ which requests that the context support a
+ specific service option. Symbolic
+ names are provided for each flag, and the
+ symbolic names corresponding to the required
+ flags should be logically-ORed
+ together to form the bit-mask value. The
+ flags are:
+
+ GSS_C_DELEG_FLAG
+ True - Delegate credentials to remote peer
+ False - Don't delegate
+ GSS_C_MUTUAL_FLAG
+ True - Request that remote peer
+ authenticate itself
+ False - Authenticate self to remote peer
+ only
+ GSS_C_REPLAY_FLAG
+ True - Enable replay detection for
+ messages protected with gss_wrap
+ or gss_get_mic
+ False - Don't attempt to detect
+ replayed messages
+
+
+ Wray Document Expiration: 1 September 1997 [Page 56]
+
+
+
+
+
+
+
+ INTERNET-DRAFT GSS-API V2 - C bindings March 1997
+
+
+
+ GSS_C_SEQUENCE_FLAG
+ True - Enable detection of out-of-sequence
+ protected messages
+ False - Don't attempt to detect
+ out-of-sequence messages
+ GSS_C_ANON_FLAG
+ True - Do not reveal the initiator's
+ identity to the acceptor.
+ False - Authenticate normally.
+
+ time_req Integer, read, optional
+ Desired number of seconds for which context
+ should remain valid. Supply 0 to request a
+ default validity period.
+
+ input_chan_bindings channel bindings, read, optional
+ Application-specified bindings. Allows
+ application to securely bind channel
+ identification information to the security
+ context. Specify GSS_C_NO_CHANNEL_BINDINGS
+ if channel bindings are not used.
+
+ input_token buffer, opaque, read, optional (see text)
+ Token received from peer application.
+ Supply GSS_C_NO_BUFFER, or a pointer to
+ a buffer containing the value GSS_C_EMPTY_BUFFER
+ on initial call.
+
+ actual_mech_type OID, modify, optional
+ Actual mechanism used. The OID returned via
+ this parameter will be a pointer to static
+ storage that should be treated as read-only;
+ In particular the application should not attempt
+ to free it. Specify NULL if not required.
+
+ output_token buffer, opaque, modify
+ token to be sent to peer application. If
+ the length field of the returned buffer is
+ zero, no token need be sent to the peer
+ application. Storage associated with this
+ buffer must be freed by the application
+ after use with a call to gss_release_buffer().
+
+ ret_flags bit-mask, modify, optional
+ Contains various independent flags, each of which
+ indicates that the context supports a specific
+ service option. Specify NULL if not
+ required. Symbolic names are provided
+ for each flag, and the symbolic names
+ corresponding to the required flags should be
+
+
+
+ Wray Document Expiration: 1 September 1997 [Page 57]
+
+
+
+
+
+
+
+ INTERNET-DRAFT GSS-API V2 - C bindings March 1997
+
+
+
+ logically-ANDed with the ret_flags value to test
+ whether a given option is supported by the
+ context. The flags are:
+
+ GSS_C_DELEG_FLAG
+ True - Credentials were delegated to
+ the remote peer
+ False - No credentials were delegated
+ GSS_C_MUTUAL_FLAG
+ True - Remote peer has been asked to
+ authenticated itself
+ False - Remote peer has not been asked to
+ authenticate itself
+ GSS_C_REPLAY_FLAG
+ True - replay of protected messages
+ will be detected
+ False - replayed messages will not be
+ detected
+ GSS_C_SEQUENCE_FLAG
+ True - out-of-sequence protected
+ messages will be detected
+ False - out-of-sequence messages will
+ not be detected
+ GSS_C_CONF_FLAG
+ True - Confidentiality service may be
+ invoked by calling gss_wrap routine
+ False - No confidentiality service (via
+ gss_wrap) available. gss_wrap will
+ provide message encapsulation,
+ data-origin authentication and
+ integrity services only.
+ GSS_C_INTEG_FLAG
+ True - Integrity service may be invoked by
+ calling either gss_get_mic or gss_wrap
+ routines.
+ False - Per-message integrity service
+ unavailable.
+ GSS_C_ANON_FLAG
+ True - The initiator's identity has not been
+ revealed, and will not be revealed if
+ any emitted token is passed to the
+ acceptor.
+ False - The initiator's identity has been or
+ will be authenticated normally.
+ GSS_C_PROT_READY_FLAG
+ True - Protection services (as specified
+ by the states of the GSS_C_CONF_FLAG
+ and GSS_C_INTEG_FLAG) are available for
+ use if the accompanying major status
+ return value is either GSS_S_COMPLETE or
+ GSS_S_CONTINUE_NEEDED.
+
+
+
+ Wray Document Expiration: 1 September 1997 [Page 58]
+
+
+
+
+
+
+
+ INTERNET-DRAFT GSS-API V2 - C bindings March 1997
+
+
+
+ False - Protection services (as specified
+ by the states of the GSS_C_CONF_FLAG
+ and GSS_C_INTEG_FLAG) are available
+ only if the accompanying major status
+ return value is GSS_S_COMPLETE.
+ GSS_C_TRANS_FLAG
+ True - The resultant security context may
+ be transferred to other processes via
+ a call to gss_export_sec_context().
+ False - The security context is not
+ transferrable.
+ All other bits should be set to zero.
+
+ time_rec Integer, modify, optional
+ number of seconds for which the context
+ will remain valid. If the implementation does
+ not support context expiration, the value
+ GSS_C_INDEFINITE will be returned. Specify
+ NULL if not required.
+
+ Function value: GSS status code
+
+ GSS_S_COMPLETE Successful completion
+
+ GSS_S_CONTINUE_NEEDED Indicates that a token from the peer application
+ is required to complete the context, and that
+ gss_init_sec_context must be called again with that
+ token.
+
+ GSS_S_DEFECTIVE_TOKEN Indicates that consistency checks performed on the
+ input_token failed
+
+ GSS_S_DEFECTIVE_CREDENTIAL Indicates that consistency checks performed
+ on the credential failed.
+
+ GSS_S_NO_CRED The supplied credentials were not valid for context
+ initiation, or the credential handle did not reference
+ any credentials.
+
+ GSS_S_CREDENTIALS_EXPIRED The referenced credentials have expired
+
+ GSS_S_BAD_BINDINGS The input_token contains different channel bindings
+ to those specified via the input_chan_bindings
+ parameter
+
+ GSS_S_BAD_SIG The input_token contains an invalid MIC, or a MIC that
+ could not be verified
+
+ GSS_S_OLD_TOKEN The input_token was too old. This is a fatal error
+ during context establishment
+
+
+
+
+ Wray Document Expiration: 1 September 1997 [Page 59]
+
+
+
+
+
+
+
+ INTERNET-DRAFT GSS-API V2 - C bindings March 1997
+
+
+
+ GSS_S_DUPLICATE_TOKEN The input_token is valid, but is a duplicate of a
+ token already processed. This is a fatal error during
+ context establishment.
+
+ GSS_S_NO_CONTEXT Indicates that the supplied context handle did not
+ refer to a valid context
+
+ GSS_S_BAD_NAMETYPE The provided target_name parameter contained an
+ invalid or unsupported type of name
+
+ GSS_S_BAD_NAME The provided target_name parameter was ill-formed.
+
+ GSS_S_BAD_MECH The specified mechanism is not supported by the
+ provided credential, or is unrecognized by the
+ implementation.
+
+
+
+
+
+
+
+ 7.20. gss_inquire_context
+
+ 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 )
+
+ Purpose:
+
+ Obtains information about a security context. The caller must already
+ have obtained a handle that refers to the context, although the context
+ need not be fully established.
+
+ Parameters:
+
+ minor_status Integer, modify
+ Mechanism specific status code
+
+ context_handle gss_ctx_id_t, read
+ A handle that refers to the security context.
+
+ src_name gss_name_t, modify, optional
+ The name of the context initiator.
+
+
+
+ Wray Document Expiration: 1 September 1997 [Page 60]
+
+
+
+
+
+
+
+ INTERNET-DRAFT GSS-API V2 - C bindings March 1997
+
+
+
+ If the context was established using anonymous
+ authentication, and if the application invoking
+ gss_inquire_context is the context acceptor,
+ an anonymous name will be returned. Storage
+ associated with this name must be freed by the
+ application after use with a call to
+ gss_release_name(). Specify NULL if not
+ required.
+
+ targ_name gss_name_t, modify, optional
+ The name of the context acceptor.
+ Storage associated with this name must be
+ freed by the application after use with a call
+ to gss_release_name(). Specify NULL if not
+ Specify NULL if not required.
+
+ lifetime_rec Integer, modify, optional
+ The number of seconds for which the context
+ will remain valid. If the context has
+ expired, this parameter will be set to zero.
+ If the implementation does not support
+ context expiration, the value
+ GSS_C_INDEFINITE will be returned. Specify
+ NULL if not required.
+
+ mech_type gss_OID, modify, optional
+ The security mechanism providing the
+ context. The returned OID will be a
+ pointer to static storage that should
+ be treated as read-only by the application;
+ in particular the application should not
+ attempt to free it. Specify NULL if not
+ required.
+
+ ctx_flags bit-mask, modify, optional
+ Contains various independent flags, each of
+ which indicates that the context supports
+ (or is expected to support, if ctx_open is
+ false) a specific service option. If not
+ needed, specify NULL. Symbolic names are
+ provided for each flag, and the symbolic names
+ corresponding to the required flags
+ should be logically-ANDed with the ret_flags
+ value to test whether a given option is
+ supported by the context. The flags are:
+
+ GSS_C_DELEG_FLAG
+ True - Credentials were delegated from
+ the initiator to the acceptor.
+ False - No credentials were delegated
+
+
+
+ Wray Document Expiration: 1 September 1997 [Page 61]
+
+
+
+
+
+
+
+ INTERNET-DRAFT GSS-API V2 - C bindings March 1997
+
+
+ GSS_C_MUTUAL_FLAG
+ True - The acceptor was authenticated
+ to the initiator
+ False - The acceptor did not authenticate
+ itself.
+ GSS_C_REPLAY_FLAG
+ True - replay of protected messages
+ will be detected
+ False - replayed messages will not be
+ detected
+ GSS_C_SEQUENCE_FLAG
+ True - out-of-sequence protected
+ messages will be detected
+ False - out-of-sequence messages will not
+ be detected
+ GSS_C_CONF_FLAG
+ True - Confidentiality service may be invoked
+ by calling gss_wrap routine
+ False - No confidentiality service (via
+ gss_wrap) available. gss_wrap will
+ provide message encapsulation,
+ data-origin authentication and
+ integrity services only.
+ GSS_C_INTEG_FLAG
+ True - Integrity service may be invoked by
+ calling either gss_get_mic or gss_wrap
+ routines.
+ False - Per-message integrity service
+ unavailable.
+ GSS_C_ANON_FLAG
+ True - The initiator's identity will not
+ be revealed to the acceptor.
+ The src_name parameter (if
+ requested) contains an anonymous
+ internal name.
+ False - The initiator has been
+ authenticated normally.
+ GSS_C_PROT_READY_FLAG
+ True - Protection services (as specified
+ by the states of the GSS_C_CONF_FLAG
+ and GSS_C_INTEG_FLAG) are available
+ for use.
+ False - Protection services (as specified
+ by the states of the GSS_C_CONF_FLAG
+ and GSS_C_INTEG_FLAG) are available
+ only if the context is fully
+ established (i.e. if the open parameter
+ is non-zero).
+ GSS_C_TRANS_FLAG
+ True - The resultant security context may
+ be transferred to other processes via
+ a call to gss_export_sec_context().
+ False - The security context is not
+ transferrable.
+
+ Wray Document Expiration: 1 September 1997 [Page 62]
+
+
+
+
+
+
+
+ INTERNET-DRAFT GSS-API V2 - C bindings March 1997
+
+
+
+
+
+ locally_initiated Boolean, modify
+ Non-zero if the invoking application is the
+ context initiator.
+ Specify NULL if not required.
+
+ open Boolean, modify
+ Non-zero if the context is fully established;
+ Zero if a context-establishment token
+ is expected from the peer application.
+ Specify NULL if not required.
+
+ 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. If the lifetime_rec
+ parameter was requested, it will be set to 0.
+
+
+
+
+
+
+
+ 7.21. gss_inquire_cred
+
+ 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 )
+
+ 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 initiator principal.
+
+
+ Wray Document Expiration: 1 September 1997 [Page 63]
+
+
+
+
+
+
+
+ INTERNET-DRAFT GSS-API V2 - C bindings March 1997
+
+
+
+
+ name gss_name_t, modify, optional
+ The name whose identity the credential asserts.
+ Storage associated with this name should be freed
+ by the application after use with a call to
+ gss_release_name(). Specify NULL if not required.
+
+ lifetime Integer, modify, optional
+ 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 gss_cred_usage_t, modify, optional
+ 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, optional
+ Set of mechanisms supported by the credential.
+ Storage associated with this OID set must be
+ freed by the application after use with a call
+ to gss_release_oid_set(). 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.
+
+
+
+
+
+
+
+
+
+ Wray Document Expiration: 1 September 1997 [Page 64]
+
+
+
+
+
+
+
+ INTERNET-DRAFT GSS-API V2 - C bindings March 1997
+
+
+
+ 7.22. gss_inquire_cred_by_mech
+
+ 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 )
+
+ Purpose:
+
+ Obtains per-mechanism 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 initiator principal.
+
+ mech_type gss_OID, read
+ The mechanism for which information should be
+ returned.
+
+ name gss_name_t, modify, optional
+ The name whose identity the credential asserts.
+ Storage associated with this name must be
+ freed by the application after use with a call
+ to gss_release_name(). Specify NULL if not
+ required.
+
+ initiator_lifetime Integer, modify, optional
+ The number of seconds for which the credential
+ will remain capable of initiating security contexts
+ under the specified mechanism. If the credential
+ can no longer be used to initiate contexts, or if
+ the credential usage for this mechanism is
+ GSS_C_ACCEPT,
+ this parameter will be set to zero. If the
+ implementation does not support expiration of
+ initiator credentials, the value GSS_C_INDEFINITE
+ will be returned. Specify NULL if not required.
+
+ acceptor_lifetime Integer, modify, optional
+ The number of seconds for which the credential
+
+
+
+ Wray Document Expiration: 1 September 1997 [Page 65]
+
+
+
+
+
+
+
+ INTERNET-DRAFT GSS-API V2 - C bindings March 1997
+
+
+
+ will remain capable of accepting security contexts
+ under the specified mechanism. If the credential
+ can no longer be used to accept contexts, or if
+ the credential usage for this mechanism is
+ GSS_C_INITIATE, this parameter will be set to zero.
+ If the implementation does not support expiration
+ of acceptor credentials, the value GSS_C_INDEFINITE
+ will be returned. Specify NULL if not required.
+
+ cred_usage gss_cred_usage_t, modify, optional
+ How the credential may be used with the specified
+ mechanism. One of the following:
+ GSS_C_INITIATE
+ GSS_C_ACCEPT
+ GSS_C_BOTH
+ 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.
+
+
+
+
+
+
+
+ 7.23. gss_inquire_mechs_for_name
+
+ OM_uint32 gss_inquire_mechs_for_name (
+ OM_uint32 * minor_status,
+ const gss_name_t input_name,
+ gss_OID_set * mech_types )
+
+ Purpose:
+
+ Returns the set of mechanisms supported by the GSSAPI implementation
+ that may be able to process the specified name.
+
+ Each mechanism returned will recognize at least one element within the
+ name. It is permissible for this routine to be implemented within a
+ mechanism-independent GSSAPI layer, using the type information contained
+ within the presented name, and based on registration information
+
+
+
+ Wray Document Expiration: 1 September 1997 [Page 66]
+
+
+
+
+
+
+
+ INTERNET-DRAFT GSS-API V2 - C bindings March 1997
+
+
+
+ provided by individual mechanism implementations. This means that the
+ returned mech_types set may indicate that a particular mechanism will
+ understand the name when in fact it would refuse to accept the name as
+ input to gss_canonicalize_name, gss_init_sec_context, gss_acquire_cred
+ or gss_add_cred (due to some property of the specific name, as opposed
+ to the name type). Thus this routine should be used only as a pre-
+ filter for a call to a subsequent mechanism-specific routine.
+
+
+
+ Parameters:
+
+ minor_status Integer, modify
+ Implementation specific status code.
+
+ input_name gss_name_t, read
+ The name to which the inquiry relates.
+
+ mech_types gss_OID_set, modify
+ Set of mechanisms that may support the
+ specified name. The returned OID set
+ must be freed by the caller after use
+ with a call to gss_release_oid_set().
+
+ Function value: GSS status code
+
+ GSS_S_COMPLETE Successful completion
+
+ GSS_S_BAD_NAME The input_name parameter was ill-formed.
+
+ GSS_S_BAD_NAMETYPE The input_name parameter contained an invalid or
+ unsupported type of name
+
+
+
+
+
+
+ 7.24. gss_inquire_names_for_mech
+
+ OM_uint32 gss_inquire_names_for_mech (
+ OM_uint32 * minor_status,
+ const gss_OID mechanism,
+ gss_OID_set * name_types)
+
+ Purpose:
+
+ Returns the set of nametypes supported by the specified mechanism.
+
+
+
+
+
+
+ Wray Document Expiration: 1 September 1997 [Page 67]
+
+
+
+
+
+
+
+ INTERNET-DRAFT GSS-API V2 - C bindings March 1997
+
+
+
+ Parameters:
+
+ minor_status Integer, modify
+ Implementation specific status code.
+
+ mechanism gss_OID, read
+ The mechanism to be interrogated.
+
+ name_types gss_OID_set, modify
+ Set of name-types supported by the specified
+ mechanism. The returned OID set must be
+ freed by the application after use with a
+ call to gss_release_oid_set().
+
+ Function value: GSS status code
+
+ GSS_S_COMPLETE Successful completion
+
+
+
+
+
+
+
+ 7.25. gss_process_context_token
+
+ OM_uint32 gss_process_context_token (
+ OM_uint32 * minor_status,
+ const gss_ctx_id_t context_handle,
+ const gss_buffer_t token_buffer)
+
+ Purpose:
+
+ Provides a way to pass a token to the security service. Used with
+ tokens emitted by gss_delete_sec_context. Note that mechanisms are
+ encouraged to perform local deletion, and not emit tokens from
+ gss_delete_sec_context. This routine, therefore, is primarily for
+ backwards compatibility with V1 applications.
+
+ Parameters:
+
+ minor_status Integer, modify
+ Implementation specific status code.
+
+ context_handle gss_ctx_id_t, read
+ context handle of context on which token is to
+ be processed
+
+ token_buffer buffer, opaque, read
+ token to process
+
+
+
+
+ Wray Document Expiration: 1 September 1997 [Page 68]
+
+
+
+
+
+
+
+ INTERNET-DRAFT GSS-API V2 - C bindings March 1997
+
+
+
+ Function value: GSS status code
+
+ GSS_S_COMPLETE Successful completion
+
+ GSS_S_DEFECTIVE_TOKEN Indicates that consistency checks performed on the
+ token failed
+
+ GSS_S_NO_CONTEXT The context_handle did not refer to a valid context
+
+
+
+
+
+
+
+ 7.26. gss_release_buffer
+
+ OM_uint32 gss_release_buffer (
+ OM_uint32 * minor_status,
+ gss_buffer_t buffer)
+
+ Purpose:
+
+ Free storage associated with a buffer. The storage must have been
+ allocated by a GSS-API routine. In addition to freeing the associated
+ storage, the routine will zero the length field in the descriptor to
+ which the buffer parameter refers.
+
+ 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
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Wray Document Expiration: 1 September 1997 [Page 69]
+
+
+
+
+
+
+
+ INTERNET-DRAFT GSS-API V2 - C bindings March 1997
+
+
+
+ 7.27. gss_release_cred
+
+ OM_uint32 gss_release_cred (
+ OM_uint32 * minor_status,
+ gss_cred_id_t * cred_handle)
+
+ Purpose:
+
+ Informs GSS-API that the specified credential handle is no longer
+ required by the application, and frees associated resources.
+
+ Parameters:
+
+ cred_handle gss_cred_id_t, modify, optional
+ Opaque handle identifying credential
+ to be released. If GSS_C_NO_CREDENTIAL
+ is supplied, the routine will complete
+ successfully, but will do nothing.
+
+ minor_status Integer, modify
+ Mechanism specific status code.
+
+ Function value: GSS status code
+
+ GSS_S_COMPLETE Successful completion
+
+ GSS_S_NO_CRED Credentials could not be accessed.
+
+
+
+
+
+
+
+ 7.28. gss_release_name
+
+ OM_uint32 gss_release_name (
+ OM_uint32 * minor_status,
+ gss_name_t * name)
+
+ Purpose:
+
+ Free GSSAPI-allocated storage by 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
+
+
+
+ Wray Document Expiration: 1 September 1997 [Page 70]
+
+
+
+
+
+
+
+ INTERNET-DRAFT GSS-API V2 - C bindings March 1997
+
+
+
+ Function value: GSS status code
+
+ GSS_S_COMPLETE Successful completion
+
+ GSS_S_BAD_NAME The name parameter did not contain a valid name
+
+
+
+
+
+
+
+ 7.29. gss_release_oid_set
+
+ OM_uint32 gss_release_oid_set (
+ OM_uint32 * minor_status,
+ gss_OID_set * set)
+
+ Purpose:
+
+ Free storage associated with a GSSAPI-generated gss_OID_set object. The
+ set parameter must refer to an OID-set that was returned from a GSSAPI
+ routine. gss_release_oid_set() will free the storage associated with
+ each individual member OID, the OID set's elements array, and the
+ gss_OID_set_desc.
+
+
+ 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
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Wray Document Expiration: 1 September 1997 [Page 71]
+
+
+
+
+
+
+
+ INTERNET-DRAFT GSS-API V2 - C bindings March 1997
+
+
+
+ 7.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
+
+
+
+
+
+
+
+ 7.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)
+
+
+
+
+ Wray Document Expiration: 1 September 1997 [Page 72]
+
+
+
+
+
+
+
+ INTERNET-DRAFT GSS-API V2 - C bindings March 1997
+
+
+
+ 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.
+
+ 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 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.
+
+
+
+
+ Wray Document Expiration: 1 September 1997 [Page 73]
+
+
+
+
+
+
+
+ INTERNET-DRAFT GSS-API V2 - C bindings March 1997
+
+
+
+ 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
+
+
+
+
+
+
+
+ 7.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.
+
+ 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
+
+
+
+
+ Wray Document Expiration: 1 September 1997 [Page 74]
+
+
+
+
+
+
+
+ INTERNET-DRAFT GSS-API V2 - C bindings March 1997
+
+
+ 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
+
+
+
+
+
+
+
+ 7.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 )
+
+
+
+
+
+
+
+ Wray Document Expiration: 1 September 1997 [Page 75]
+
+
+
+
+
+
+
+ INTERNET-DRAFT GSS-API V2 - C bindings March 1997
+
+
+
+ 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 should 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
+
+
+
+ Wray Document Expiration: 1 September 1997 [Page 76]
+
+
+
+
+
+
+
+ INTERNET-DRAFT GSS-API V2 - C bindings March 1997
+
+
+
+ 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.
+
+
+
+
+
+
+
+ 7.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.
+
+ 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
+
+
+
+ Wray Document Expiration: 1 September 1997 [Page 77]
+
+
+
+
+
+
+
+ INTERNET-DRAFT GSS-API V2 - C bindings March 1997
+
+
+
+ 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.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Wray Document Expiration: 1 September 1997 [Page 78]
+
+
+
+
+
+
+
+ INTERNET-DRAFT GSS-API V2 - C bindings March 1997
+
+
+
+ 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
+
+
+
+ Wray Document Expiration: 1 September 1997 [Page 79]
+
+
+
+
+
+
+
+ INTERNET-DRAFT GSS-API V2 - C bindings March 1997
+
+
+
+ /*
+ * 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
+
+
+
+ Wray Document Expiration: 1 September 1997 [Page 80]
+
+
+
+
+
+
+
+ INTERNET-DRAFT GSS-API V2 - C bindings March 1997
+
+
+
+ /*
+ * 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}
+
+
+
+ Wray Document Expiration: 1 September 1997 [Page 81]
+
+
+
+
+
+
+
+ INTERNET-DRAFT GSS-API V2 - C bindings March 1997
+
+
+
+ /*
+ * 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 GSSAPI 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;
+
+ /*
+
+
+
+ Wray Document Expiration: 1 September 1997 [Page 82]
+
+
+
+
+
+
+
+ INTERNET-DRAFT GSS-API V2 - C bindings March 1997
+
+
+
+ * 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
+ * {1(iso), 3(org), 6(dod), 1(internet), 5(security),
+ * 6(nametypes), 2(gss-host-based-services)}. 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;
+
+
+
+
+
+ Wray Document Expiration: 1 September 1997 [Page 83]
+
+
+
+
+
+
+
+ INTERNET-DRAFT GSS-API V2 - C bindings March 1997
+
+
+
+ /* 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 GSSAPI 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)
+
+
+
+ Wray Document Expiration: 1 September 1997 [Page 84]
+
+
+
+
+
+
+
+ INTERNET-DRAFT GSS-API V2 - C bindings March 1997
+
+
+
+ #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 */
+
+
+
+ Wray Document Expiration: 1 September 1997 [Page 85]
+
+
+
+
+
+
+
+ INTERNET-DRAFT GSS-API V2 - C bindings March 1997
+
+
+
+ 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 */
+
+
+
+ Wray Document Expiration: 1 September 1997 [Page 86]
+
+
+
+
+
+
+
+ INTERNET-DRAFT GSS-API V2 - C bindings March 1997
+
+
+
+ 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 */
+
+
+
+ Wray Document Expiration: 1 September 1997 [Page 87]
+
+
+
+
+
+
+
+ INTERNET-DRAFT GSS-API V2 - C bindings March 1997
+
+
+
+ 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 */
+
+
+
+ Wray Document Expiration: 1 September 1997 [Page 88]
+
+
+
+
+
+
+
+ INTERNET-DRAFT GSS-API V2 - C bindings March 1997
+
+
+
+ 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 (
+
+
+
+ Wray Document Expiration: 1 September 1997 [Page 89]
+
+
+
+
+
+
+
+ INTERNET-DRAFT GSS-API V2 - C bindings March 1997
+
+
+
+ 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
+
+
+
+ Wray Document Expiration: 1 September 1997 [Page 90]
+
+
+
+
+
+
+
+ INTERNET-DRAFT GSS-API V2 - C bindings March 1997
+
+
+
+ * provided by GSSAPI V2 implementations for backwards
+ * compatibility with V1 applications. Distinct entrypoints
+ * (as opposed to #defines) should be provided, both to allow
+ * GSSAPI V1 applications to link against GSSAPI 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_ */
+
+
+
+
+
+ Wray Document Expiration: 1 September 1997 [Page 91]
+
+
+
+
+
+
+
+ INTERNET-DRAFT GSS-API V2 - C bindings March 1997
+
+
+
+ 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.
+
+
+
+ Wray Document Expiration: 1 September 1997 [Page 92]
+
+
+
+
+
+
+
+ INTERNET-DRAFT GSS-API V2 - C bindings March 1997
+
+
+
+ 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.
+
+ (a) The size of the handle type must be the same as sizeof(void *),
+ using the appropriate memory model.
+
+ (b) 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)
+
+ (c) 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
+
+
+
+ Wray Document Expiration: 1 September 1997 [Page 93]
+
+
+
+
+
+
+
+ INTERNET-DRAFT GSS-API V2 - C bindings March 1997
+
+
+
+ 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
+ GSSAPI implementations.
+
+
+ REFERENCES
+
+ [GSSAPI] J. Linn, "Generic Security Service Application Program
+ Interface, Version 2", Internet-Draft draft-ietf-cat-gssv2-
+ 08, 26 August 1996. (This Internet-Draft, like all other
+ Internet-Drafts, is not an archival document and is subject
+ to change or deletion. It is available at the time of this
+ writing by anonymous ftp from ds.internic.net, directory
+ internet-drafts. Would-be readers should check for successor
+ Internet-Draft versions or Internet RFCs before relying on
+ this document.)
+
+ [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 Internet email: Wray@tuxedo.enet.dec.com
+ Digital Equipment Corporation Telephone: +1-508-486-5210
+ 550 King Street, LKG2-2/Z7
+ Littleton, MA 01460
+ USA
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Wray Document Expiration: 1 September 1997 [Page 94]
+
+
+
OpenPOWER on IntegriCloud