diff options
Diffstat (limited to 'crypto/heimdal/doc/standardisation/rfc2744.txt')
| -rw-r--r-- | crypto/heimdal/doc/standardisation/rfc2744.txt | 5659 |
1 files changed, 0 insertions, 5659 deletions
diff --git a/crypto/heimdal/doc/standardisation/rfc2744.txt b/crypto/heimdal/doc/standardisation/rfc2744.txt deleted file mode 100644 index 7f0c619..0000000 --- a/crypto/heimdal/doc/standardisation/rfc2744.txt +++ /dev/null @@ -1,5659 +0,0 @@ - - - - - - -Network Working Group J. Wray -Request for Comments: 2744 Iris Associates -Obsoletes: 1509 January 2000 -Category: Standards Track - - - Generic Security Service API Version 2 : C-bindings - -Status of this Memo - - This document specifies an Internet standards track protocol for the - Internet community, and requests discussion and suggestions for - improvements. Please refer to the current edition of the "Internet - Official Protocol Standards" (STD 1) for the standardization state - and status of this protocol. Distribution of this memo is unlimited. - -Copyright Notice - - Copyright (C) The Internet Society (2000). All Rights Reserved. - -Abstract - - This document specifies C language bindings for Version 2, Update 1 - of the Generic Security Service Application Program Interface (GSS- - API), which is described at a language-independent conceptual level - in RFC-2743 [GSSAPI]. It obsoletes RFC-1509, making specific - incremental changes in response to implementation experience and - liaison requests. It is intended, therefore, that this memo 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, GSS-API callers will be application protocols into which - security enhancements are integrated through invocation of services - provided by the GSS-API. The GSS-API 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 Standards Track [Page 1] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - -1. 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 GSS-API: - - 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 GSS-API 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 GSS-API calls will return a token data - structure, which is an opaque data type that may contain - cryptographically protected data. The caller of such a GSS-API - 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 GSS-API routine - which will decode the token and extract the information, updating - the security context state information accordingly. - - - - - - - - - -Wray Standards Track [Page 2] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - c) Per-message services are invoked to apply either: - - integrity and data origin authentication, or confidentiality, - integrity and data origin authentication to application data, - which are treated by GSS-API as arbitrary octet-strings. An - application transmitting a message that it wishes to protect will - call the appropriate GSS-API 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 - GSS-API 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. - -2. GSS-API Routines - - This section lists the routines that make up the GSS-API, and - offers a brief description of the purpose of each routine. - Detailed descriptions of each routine are listed in alphabetical - order in section 5. - - Table 2-1 GSS-API Credential-management Routines - - Routine Section Function - ------- ------- -------- - gss_acquire_cred 5.2 Assume a global identity; Obtain - a GSS-API credential handle for - pre-existing credentials. - gss_add_cred 5.3 Construct credentials - incrementally - gss_inquire_cred 5.21 Obtain information about a - credential - gss_inquire_cred_by_mech 5.22 Obtain per-mechanism information - about a credential. - gss_release_cred 5.27 Discard a credential handle. - - - - - - - - - -Wray Standards Track [Page 3] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - Table 2-2 GSS-API Context-Level Routines - - Routine Section Function - ------- ------- -------- - gss_init_sec_context 5.19 Initiate a security context with - a peer application - gss_accept_sec_context 5.1 Accept a security context - initiated by a - peer application - gss_delete_sec_context 5.9 Discard a security context - gss_process_context_token 5.25 Process a token on a security - context from a peer application - gss_context_time 5.7 Determine for how long a context - will remain valid - gss_inquire_context 5.20 Obtain information about a - security context - gss_wrap_size_limit 5.34 Determine token-size limit for - gss_wrap on a context - gss_export_sec_context 5.14 Transfer a security context to - another process - gss_import_sec_context 5.17 Import a transferred context - - - Table 2-3 GSS-API Per-message Routines - - Routine Section Function - ------- ------- -------- - gss_get_mic 5.15 Calculate a cryptographic message - integrity code (MIC) for a - message; integrity service - gss_verify_mic 5.32 Check a MIC against a message; - verify integrity of a received - message - gss_wrap 5.33 Attach a MIC to a message, and - optionally encrypt the message - content; - confidentiality service - gss_unwrap 5.31 Verify a message with attached - MIC, and decrypt message content - if necessary. - - - - - - - - - - - -Wray Standards Track [Page 4] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - Table 2-4 GSS-API Name manipulation Routines - - Routine Section Function - ------- ------- -------- - gss_import_name 5.16 Convert a contiguous string name - to internal-form - gss_display_name 5.10 Convert internal-form name to - text - gss_compare_name 5.6 Compare two internal-form names - - gss_release_name 5.28 Discard an internal-form name - gss_inquire_names_for_mech 5.24 List the name-types supported by - the specified mechanism - gss_inquire_mechs_for_name 5.23 List mechanisms that support the - specified name-type - gss_canonicalize_name 5.5 Convert an internal name to an MN - gss_export_name 5.13 Convert an MN to export form - gss_duplicate_name 5.12 Create a copy of an internal name - - - Table 2-5 GSS-API Miscellaneous Routines - - Routine Section Function - ------- ------- -------- - gss_add_oid_set_member 5.4 Add an object identifier to - a set - gss_display_status 5.11 Convert a GSS-API status code - to text - gss_indicate_mechs 5.18 Determine available underlying - authentication mechanisms - gss_release_buffer 5.26 Discard a buffer - gss_release_oid_set 5.29 Discard a set of object - identifiers - gss_create_empty_oid_set 5.8 Create a set containing no - object identifiers - gss_test_oid_set_member 5.30 Determines whether an object - identifier is a member of a set. - - Individual GSS-API 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. - - - - - - - - -Wray Standards Track [Page 5] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - -3. Data Types and Calling Conventions - - The following conventions are used by the GSS-API C-language - bindings: - -3.1. Integer types - - GSS-API 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 GSS-API routine definitions. Individual GSS-API - 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 GSS-API 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 GSS-API implementation should use the smallest - natural unsigned integer type that provides at least 32 bits of - precision. - -3.2. String and similar data - - Many of the GSS-API routines take arguments and return values that - describe contiguous octet-strings. All such data is passed between - the GSS-API 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: - - 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 GSS-API routine - using the gss_buffer_t conventions is allocated by the GSS-API - 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. - - - - - - - -Wray Standards Track [Page 6] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - -3.2.1. Opaque data types - - Certain multiple-word data items are considered opaque data types at - the GSS-API, because their internal structure has no significance - either to the GSS-API 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 GSS-API). Opaque data is passed between the - GSS-API and the application using the gss_buffer_t datatype. - -3.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 GSS-API - routines also return character strings. All such character strings - are passed between the application and the GSS-API 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 GSS-API implementation or the application assume the - presence of an uncounted trailing NUL. - -3.3. Object Identifiers - - Certain GSS-API 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 GSS-API 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; - - 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 - - - -Wray Standards Track [Page 7] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - following octal values: 53,14,2,207,163,7,5. GSS-API 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 3.10). Applications should treat - gss_OID_desc values returned by GSS-API 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]. - -3.4. Object Identifier Sets - - Certain GSS-API procedures take parameters of the type gss_OID_set. - This type represents one or more object identifiers (section 2.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 GSS-API, to request the use - of specific mechanisms, and to indicate which mechanisms a given - credential supports. - - All OID sets returned to the application by GSS-API 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. - -3.5. Credentials - - A credential handle is a caller-opaque atomic datum that identifies a - GSS-API 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. - - GSS-API credentials can contain mechanism-specific principal - authentication data for multiple mechanisms. A GSS-API 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 - - - -Wray Standards Track [Page 8] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - 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 describe the actual mechanism-specific authentication data, one - to be used by GSS-API 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 GSS-API credential should - belong to the same entity, although enforcement of this property is - an implementation-specific matter. The GSS-API does not make the - actual credentials available to applications; instead a credential - handle is used to identify a particular credential, held internally - by GSS-API. The combination of GSS-API 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 - GSS-API implementations are free to determine such default behavior - as appropriate to the mechanism, the following default behavior by - these routines is recommended for portability: - - gss_init_sec_context - - 1) 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 - - 2) 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 - - 3) 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 - - - - - -Wray Standards Track [Page 9] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - initiating security contexts using the chosen mechanism, then - the principal corresponding to that identity shall be used, - otherwise - - 4) A user-configurable default identity should be used. - - gss_accept_sec_context - - 1) 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 - - 2) 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 - - 3) 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 - - 4)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. - -3.6. Contexts - - The gss_ctx_id_t data type contains a caller-opaque atomic value that - identifies one end of a GSS-API 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. - - - - - - - - - -Wray Standards Track [Page 10] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - -3.7. Authentication tokens - - A token is a caller-opaque type that GSS-API uses to maintain - synchronization between the context data structures at each end of a - GSS-API security context. The token is a cryptographically protected - octet-string, generated by the underlying mechanism at one end of a - GSS-API security context for use by the peer mechanism at the other - end. Encapsulation (if required) and transfer of the token are the - responsibility of the peer applications. A token is passed between - the GSS-API and the application using the gss_buffer_t conventions. - -3.8. Interprocess tokens - - Certain GSS-API routines are intended to transfer data between - processes in multi-process programs. These routines use a caller- - opaque octet-string, generated by the GSS-API in one process for use - by the GSS-API in another process. The calling application is - responsible for transferring such tokens between processes in an OS- - specific manner. Note that, while GSS-API 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 GSS-API and the application using the gss_buffer_t - conventions. - -3.9. Status values - - Every GSS-API routine returns two distinct values to report status - information to the caller: GSS status codes and Mechanism status - codes. - -3.9.1. GSS status codes - - GSS-API 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. - - - -Wray Standards Track [Page 11] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - 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 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 3-1 Calling Errors - - Name Value in field Meaning - ---- -------------- ------- - 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 - - - - - - - - - - - - - - - - - - - - - - - -Wray Standards Track [Page 12] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - Table 3-2 Routine Errors - - Name Value in field Meaning - ---- -------------- ------- - 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_MIC GSS_S_BAD_SIG 6 A token had an invalid 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 - 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 - provided - GSS_S_UNAUTHORIZED 15 The operation is forbidden - by local security policy - GSS_S_UNAVAILABLE 16 The operation or option is - unavailable - 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 - - - - - - - - - - - -Wray Standards Track [Page 13] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - Table 3-3 Supplementary Status Bits - - Name Bit Number Meaning - ---- ---------- ------- - GSS_S_CONTINUE_NEEDED 0 (LSB) Returned only by - gss_init_sec_context or - gss_accept_sec_context. 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 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 - major status values only. - - The GSS major 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-specific status code will - provide more details about the error. - - - -Wray Standards Track [Page 14] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - -3.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. - -3.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: - - An internal form. This is the GSS-API "native" format for names, - represented by the implementation-specific gss_name_t type. It is - opaque to GSS-API 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 - 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 GSS-API implementations supporting multiple namespaces, - objects of type gss_name_t must contain sufficient information to - determine the namespace to which each primitive name belongs. - - - - - - -Wray Standards Track [Page 15] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - 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 GSS-API 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. - - 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 GSS-API assumes that all primitive names contained within a - - - -Wray Standards Track [Page 16] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - 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, - GSS-API defines a special form of the contiguous string name which - may be compared directly (e.g. with memcmp()). Contiguous 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 GSS-API 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 Standards Track [Page 17] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - -3.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 X.25 - 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 - - - - -Wray Standards Track [Page 18] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - form is used. When not otherwise specified, addresses should be - specified in network byte-order (that is, native byte-ordering for - the address family). - - 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. - -3.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. - -3.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. - -3.12.2. Integer types (input) - - Individual parameter documentation lists values to be used to - indicate default actions. - - - - - -Wray Standards Track [Page 19] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - -3.12.3. Integer types (output) - - Specify NULL as the value for the pointer. - -3.12.4. Pointer types - - Specify NULL as the value. - -3.12.5. Object IDs - - Specify GSS_C_NO_OID as the value. - -3.12.6. Object ID Sets - - Specify GSS_C_NO_OID_SET as the value. - -3.12.7. Channel Bindings - - Specify GSS_C_NO_CHANNEL_BINDINGS to indicate that channel bindings - are not to be used. - -4. 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. - - - -Wray Standards Track [Page 20] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - 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. - - 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 GSS-API can correctly indicate - whether the service is supported by the acceptor's GSS-API. - -4.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 GSS-API 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 - - - -Wray Standards Track [Page 21] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - 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 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 provided at the explicit request of the - application. - -4.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 the - context acceptor has authenticated itself. 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. - - - - - - - - - - - -Wray Standards Track [Page 22] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - -4.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 MIC over an application - message, and returns that MIC 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 MIC of an application message, - and places both the MIC 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 MIC. - - 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: - - GSS_S_DUPLICATE_TOKEN - The token is a duplicate of one that has - already been received and processed. Only - contexts that claim to provide replay detection - may set this bit. - 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. - - - - - -Wray Standards Track [Page 23] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - -4.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 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 ">". - -4.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. - - - -Wray Standards Track [Page 24] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - -4.6. Inter-process context transfer - - GSS-API 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 GSS-API 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 gss_export_sec_context, the - original security context is made inaccessible to the calling process - by GSS-API, 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. - - 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. - -4.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 - - - -Wray Standards Track [Page 25] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - 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. - -5. 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. - -5.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. - - - - -Wray Standards Track [Page 26] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - 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); - 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: - - The value returned via the time_rec parameter is undefined 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. - - - - -Wray Standards Track [Page 27] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - 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 GSS-API 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 GSS-API. 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. - 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). - - During context establishment, the informational status bits - GSS_S_OLD_TOKEN and GSS_S_DUPLICATE_TOKEN indicate fatal errors, and - GSS-API mechanisms should always return them in association with a - routine error of GSS_S_FAILURE. This requirement for pairing did not - exist in version 1 of the GSS-API specification, so applications that - wish to run over version 1 implementations must special-case these - codes. - - - - - - - - - -Wray Standards Track [Page 28] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - 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. 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(). - - - -Wray Standards Track [Page 29] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - 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 - 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 - - - -Wray Standards Track [Page 30] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - 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 - transferable. - 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 - 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. - - 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. - - - -Wray Standards Track [Page 31] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - 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. - - GSS_S_BAD_MECH The received token specified a mechanism that is - not supported by the implementation or the - provided credential. - -5.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) - - - - - - - - -Wray Standards Track [Page 32] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - 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). - - Mechanisms should honor the desired_mechs parameter, and return a - credential that is suitable to use only with the requested - mechanisms. An exception to this is the case where one underlying - credential element can be shared by multiple mechanisms; in this case - it is permissible for an implementation to indicate all mechanisms - with which the credential element may be used. If desired_mechs is - an empty set, behavior is undefined. - - 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 GSS_C_NO_NAME, or a name - produced by applying either gss_inquire_cred to a valid credential, - or gss_inquire_context to an active context. - - If credential acquisition is time-consuming for a mechanism, the - mechanism may choose 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. - - - - - - - - -Wray Standards Track [Page 33] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - 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 - credentials, the value GSS_C_INDEFINITE will - be returned. Specify NULL if not required - - - - - -Wray Standards Track [Page 34] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - 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. - -5.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) - - Purpose: - - Adds a credential-element to a credential. The credential-element is - identified by the name of the principal to which it refers. GSS-API - 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 GSS-API handle to - existing data. Such functions, if required, should be defined in - implementation-specific extensions to the API. - - - - -Wray Standards Track [Page 35] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - If desired_name is GSS_C_NO_NAME, the call is interpreted as a - request to add a credential element 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 GSS_C_NO_NAME, or a name - produced by applying either gss_inquire_cred to a valid credential, - or gss_inquire_context to an active context. - - If credential acquisition is time-consuming for a mechanism, the - mechanism may choose 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_add_cred - must return valid credential data, and may therefore incur the - overhead of a deferred credential acquisition. - - This routine can be used to either compose 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 handle will be created. - - If GSS_C_NO_CREDENTIAL is specified as the input_cred_handle, - gss_add_cred will compose a credential (and set the - output_cred_handle parameter accordingly) 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. - - - - - - -Wray Standards Track [Page 36] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - Parameters: - - 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 compose 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 - composed 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 - composed credentials are of type GSS_C_INITIATE. - - - -Wray Standards Track [Page 37] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - Specify GSS_C_INDEFINITE to request that the - credentials have the maximum permitted initiator - lifetime. - - 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 - - - - -Wray Standards Track [Page 38] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - 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_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. - -5.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 - GSS-API (e.g. a set returned by gss_create_empty_oid_set()). GSS-API - 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; if the - member_oid is already present, the oid_set should remain unchanged. - - Parameters: - - minor_status Integer, modify - Mechanism specific status code - - - - - -Wray Standards Track [Page 39] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - 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. - - Function value: GSS status code - - GSS_S_COMPLETE Successful completion - -5.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. - - - - - - - -Wray Standards Track [Page 40] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - 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 - - 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 specified - mechanism. - - GSS_S_BAD_NAME The provided internal name was ill-formed. - -5.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 - - - - - - -Wray Standards Track [Page 41] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - 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 - - 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. - -5.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 Standards Track [Page 42] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - -5.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 - -5.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 may be obtained using the context specified by - context_handle. - - - - -Wray Standards Track [Page 43] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - 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 GSS-API 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 Standards Track [Page 44] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - -5.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. - - If input_name was created by a call to gss_import_name, specifying - GSS_C_NO_OID as the name-type, implementations that employ lazy - conversion between name types may return GSS_C_NO_OID via the - output_name_type parameter. - - 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, the application should not attempt - to free it). Specify NULL if not required. - - - - - - - -Wray Standards Track [Page 45] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - Function value: GSS status code - - GSS_S_COMPLETE Successful completion - - GSS_S_BAD_NAME input_name was ill-formed - -5.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_display_status 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 { - - - -Wray Standards Track [Page 46] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - 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", - (int)status_string.length, - - (char *)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 - - - - - -Wray Standards Track [Page 47] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - 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 - - 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. - -5.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(). - - - -Wray Standards Track [Page 48] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - Function value: GSS status code - - GSS_S_COMPLETE Successful completion - - GSS_S_BAD_NAME The src_name parameter was ill-formed. - -5.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 provided internal name was ill-formed. - - GSS_S_BAD_NAMETYPE The internal name was of a type not supported - by the GSS-API implementation. - - - - -Wray Standards Track [Page 49] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - -5.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 GSS-API 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 successful, 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. - - - - -Wray Standards Track [Page 50] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - Parameters: - - minor_status Integer, modify - Mechanism specific status code - - 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. - -5.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. - - Since some application-level protocols may wish to use tokens emitted - by gss_wrap() to provide "secure framing", implementations must - support derivation of MICs from zero-length messages. - - - - - - - -Wray Standards Track [Page 51] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - 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 - - 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. - -5.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) - - - - - -Wray Standards Track [Page 52] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - 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. - - 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 recognized - 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 - - GSS_S_BAD_MECH The input name-type was GSS_C_NT_EXPORT_NAME, - but the mechanism contained within the - input-name is not supported - - - - - - - - -Wray Standards Track [Page 53] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - -5.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. - - 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. - -5.18. gss_indicate_mechs - - OM_uint32 gss_indicate_mechs ( - OM_uint32 *minor_status, - gss_OID_set *mech_set) - - - - - -Wray Standards Track [Page 54] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - Purpose: - - Allows an application to determine which underlying security - mechanisms are available. - - Parameters: - - minor_status Integer, modify - Mechanism specific status code. - - mech_set set of Object IDs, modify - set of implementation-supported mechanisms. - The returned gss_OID_set value will be a - 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 - -5.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 - - - -Wray Standards Track [Page 55] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - 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. - - 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; - }; - - - -Wray Standards Track [Page 56] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - 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: - - The value returned via the time_rec parameter is undefined 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. - - 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. - - GSS-API implementations that support per-message protection are - encouraged to 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). However, applications should not rely on this - behavior as the flag was not defined in Version 1 of the GSS-API. - Instead, applications should determine what per-message services - are available after a successful context establishment according - to the GSS_C_INTEG_FLAG and GSS_C_CONF_FLAG values. - - - -Wray Standards Track [Page 57] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - 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). - - During context establishment, the informational status bits - GSS_S_OLD_TOKEN and GSS_S_DUPLICATE_TOKEN indicate fatal errors, and - GSS-API mechanisms should always return them in association with a - routine error of GSS_S_FAILURE. This requirement for pairing did not - exist in version 1 of the GSS-API specification, so applications that - wish to run over version 1 implementations must special-case these - codes. - - 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 gss_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 - - - -Wray Standards Track [Page 58] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - 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 - - 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_CONF_FLAG - True - Request that confidentiality service - be made available (via gss_wrap) - False - No per-message confidentiality service - is required. - - GSS_C_INTEG_FLAG - True - Request that integrity service be - made available (via gss_wrap or - gss_get_mic) - False - No per-message integrity service - is required. - - - - - - -Wray Standards Track [Page 59] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - 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 - logically-ANDed with the ret_flags value to test - whether a given option is supported by the - context. The flags are: - - - -Wray Standards Track [Page 60] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - GSS_C_DELEG_FLAG - True - Credentials were delegated to - the remote peer - False - No credentials were delegated - - GSS_C_MUTUAL_FLAG - True - The remote peer has authenticated - itself. - False - Remote peer has not authenticated - 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 - - - -Wray Standards Track [Page 61] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - 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. - 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 - transferable. - - 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 - - - -Wray Standards Track [Page 62] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - 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 - - 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. - -5.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. - - - - - - - -Wray Standards Track [Page 63] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - 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. - 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(). If the context acceptor - did not authenticate itself, and if the initiator - did not specify a target name in its call to - gss_init_sec_context(), the value GSS_C_NO_NAME - will be returned. 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. - - - - - -Wray Standards Track [Page 64] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - 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 - - 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. - - - -Wray Standards Track [Page 65] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - 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 - transferable. - - 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. - - - - -Wray Standards Track [Page 66] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - -5.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. - - 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. - - 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. - - - - - -Wray Standards Track [Page 67] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - 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. - -5.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. - - 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. - - - - -Wray Standards Track [Page 68] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - 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 - 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. - - - - - -Wray Standards Track [Page 69] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - GSS_S_CREDENTIALS_EXPIRED The referenced credentials have expired. - If the lifetime parameter was not passed as NULL, - it will be set to 0. - -5.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 GSS-API 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 GSS-API layer, using the type - information contained within the presented name, and based on - registration information provided by individual mechanism - implementations. This means that the returned mech_types 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. - - - -Wray Standards Track [Page 70] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - GSS_S_BAD_NAMETYPE The input_name parameter contained an invalid or - unsupported type of name - -5.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. - - 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 - -5.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 an asynchronous token to the security service. - Most context-level tokens are emitted and processed synchronously by - gss_init_sec_context and gss_accept_sec_context, and the application - is informed as to whether further tokens are expected by the - GSS_C_CONTINUE_NEEDED major status bit. Occasionally, a mechanism - may need to emit a context-level token at a point when the peer - entity is not expecting a token. For example, the initiator's final - - - -Wray Standards Track [Page 71] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - call to gss_init_sec_context may emit a token and return a status of - GSS_S_COMPLETE, but the acceptor's call to gss_accept_sec_context may - fail. The acceptor's mechanism may wish to send a token containing - an error indication to the initiator, but the initiator is not - expecting a token at this point, believing that the context is fully - established. Gss_process_context_token provides a way to pass such a - token to the mechanism at any time. - - 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 - - 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 - -5.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, and implementations - are encouraged to additionally set the pointer field in the - descriptor to NULL. Any buffer object returned by a GSS-API routine - may be passed to gss_release_buffer (even if there is no storage - associated with the buffer). - - - - - - -Wray Standards Track [Page 72] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - 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 - -5.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. - Implementations are encouraged to set the cred_handle to - GSS_C_NO_CREDENTIAL on successful completion of this call. - - 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. - - - - - - - -Wray Standards Track [Page 73] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - -5.28. gss_release_name - - OM_uint32 gss_release_name ( - OM_uint32 *minor_status, - gss_name_t *name) - - Purpose: - - Free GSSAPI-allocated storage associated with an internal-form name. - Implementations are encouraged to set the name to GSS_C_NO_NAME on - successful completion of this call. - - Parameters: - - minor_status Integer, modify - Mechanism specific status code - - name gss_name_t, modify - The name to be deleted - - Function value: GSS status code - - GSS_S_COMPLETE Successful completion - - GSS_S_BAD_NAME The name parameter did not contain a valid name - -5.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 - GSS-API 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. - - Implementations are encouraged to set the gss_OID_set parameter to - GSS_C_NO_OID_SET on successful completion of this routine. - - Parameters: - - minor_status Integer, modify - Mechanism specific status code - - - - -Wray Standards Track [Page 74] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - 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 - -5.30. gss_test_oid_set_member - - OM_uint32 gss_test_oid_set_member ( - OM_uint32 *minor_status, - const gss_OID member, - const gss_OID_set set, - int *present) - - Purpose: - - Interrogate an Object Identifier set to determine whether a specified - Object Identifier is a member. This routine is intended to be used - with OID sets returned by gss_indicate_mechs(), gss_acquire_cred(), - and gss_inquire_cred(), but will also work with user-generated sets. - - Parameters: - - minor_status Integer, modify - Mechanism specific status code - - member Object ID, read - The object identifier whose presence - is to be tested. - - set Set of Object ID, read - The Object Identifier set. - - present Boolean, modify - non-zero if the specified OID is a member - of the set, zero if not. - - Function value: GSS status code - - GSS_S_COMPLETE Successful completion - - - - - - - - - -Wray Standards Track [Page 75] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - -5.31. gss_unwrap - - OM_uint32 gss_unwrap ( - OM_uint32 *minor_status, - const gss_ctx_id_t context_handle, - const gss_buffer_t input_message_buffer, - gss_buffer_t output_message_buffer, - int *conf_state, - gss_qop_t *qop_state) - - Purpose: - - Converts a message previously protected by gss_wrap back to a usable - form, verifying the embedded MIC. The conf_state parameter indicates - whether the message was encrypted; the qop_state parameter indicates - the strength of protection that was used to provide the - confidentiality and integrity services. - - Since some application-level protocols may wish to use tokens emitted - by gss_wrap() to provide "secure framing", implementations must - support the wrapping and unwrapping of zero-length messages. - - Parameters: - - minor_status Integer, modify - Mechanism specific status code. - - context_handle gss_ctx_id_t, read - Identifies the context on which the message - arrived - - input_message_buffer buffer, opaque, read - protected message - - output_message_buffer buffer, opaque, modify - Buffer to receive unwrapped message. - Storage associated with this buffer must - be freed by the application after use use - with a call to gss_release_buffer(). - - conf_state boolean, modify, optional - Non-zero - Confidentiality and integrity - protection were used - Zero - Integrity service only was used - Specify NULL if not required - - - - - - -Wray Standards Track [Page 76] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - qop_state gss_qop_t, modify, optional - Quality of protection provided. - Specify NULL if not required - - Function value: GSS status code - - GSS_S_COMPLETE Successful completion - - GSS_S_DEFECTIVE_TOKEN The token failed consistency checks - - GSS_S_BAD_SIG The MIC was incorrect - - GSS_S_DUPLICATE_TOKEN The token was valid, and contained a correct - MIC for the message, but it had already been - processed - - GSS_S_OLD_TOKEN The token was valid, and contained a correct MIC - for the message, but it is too old to check for - duplication. - - GSS_S_UNSEQ_TOKEN The token was valid, and contained a correct MIC - for the message, but has been verified out of - sequence; a later token has already been - received. - - GSS_S_GAP_TOKEN The token was valid, and contained a correct MIC - for the message, but has been verified out of - sequence; an earlier expected token has not yet - been received. - - GSS_S_CONTEXT_EXPIRED The context has already expired - - GSS_S_NO_CONTEXT The context_handle parameter did not identify - a valid context - -5.32. gss_verify_mic - - OM_uint32 gss_verify_mic ( - OM_uint32 *minor_status, - const gss_ctx_id_t context_handle, - const gss_buffer_t message_buffer, - const gss_buffer_t token_buffer, - gss_qop_t *qop_state) - - - - - - - - -Wray Standards Track [Page 77] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - Purpose: - - Verifies that a cryptographic MIC, contained in the token parameter, - fits the supplied message. The qop_state parameter allows a message - recipient to determine the strength of protection that was applied to - the message. - - Since some application-level protocols may wish to use tokens emitted - by gss_wrap() to provide "secure framing", implementations must - support the calculation and verification of MICs over zero-length - messages. - - Parameters: - - minor_status Integer, modify - Mechanism specific status code. - - context_handle gss_ctx_id_t, read - Identifies the context on which the message - arrived - - message_buffer buffer, opaque, read - Message to be verified - - token_buffer buffer, opaque, read - Token associated with message - - qop_state gss_qop_t, modify, optional - quality of protection gained from MIC - Specify NULL if not required - - Function value: GSS status code - - GSS_S_COMPLETE Successful completion - - GSS_S_DEFECTIVE_TOKEN The token failed consistency checks - - GSS_S_BAD_SIG The MIC was incorrect - - GSS_S_DUPLICATE_TOKEN The token was valid, and contained a correct - MIC for the message, but it had already been - processed - - GSS_S_OLD_TOKEN The token was valid, and contained a correct MIC - for the message, but it is too old to check for - duplication. - - - - - -Wray Standards Track [Page 78] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - GSS_S_UNSEQ_TOKEN The token was valid, and contained a correct MIC - for the message, but has been verified out of - sequence; a later token has already been received. - - GSS_S_GAP_TOKEN The token was valid, and contained a correct MIC - for the message, but has been verified out of - sequence; an earlier expected token has not yet - been received. - - GSS_S_CONTEXT_EXPIRED The context has already expired - - GSS_S_NO_CONTEXT The context_handle parameter did not identify a - valid context - -5.33. gss_wrap - - OM_uint32 gss_wrap ( - OM_uint32 *minor_status, - const gss_ctx_id_t context_handle, - int conf_req_flag, - gss_qop_t qop_req - const gss_buffer_t input_message_buffer, - int *conf_state, - gss_buffer_t output_message_buffer ) - - Purpose: - - Attaches a cryptographic MIC and optionally encrypts the specified - input_message. The output_message contains both the MIC and the - message. The qop_req parameter allows a choice between several - cryptographic algorithms, if supported by the chosen mechanism. - - Since some application-level protocols may wish to use tokens emitted - by gss_wrap() to provide "secure framing", implementations must - support the wrapping of zero-length messages. - - Parameters: - - minor_status Integer, modify - Mechanism specific status code. - - context_handle gss_ctx_id_t, read - Identifies the context on which the message - will be sent - - - - - - - -Wray Standards Track [Page 79] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - conf_req_flag boolean, read - Non-zero - Both confidentiality and integrity - services are requested - Zero - Only integrity service is requested - - qop_req gss_qop_t, read, optional - Specifies required quality of protection. A - mechanism-specific default may be requested by - setting qop_req to GSS_C_QOP_DEFAULT. If an - unsupported protection strength is requested, - gss_wrap will return a major_status of - GSS_S_BAD_QOP. - - input_message_buffer buffer, opaque, read - Message to be protected - - conf_state boolean, modify, optional - Non-zero - Confidentiality, data origin - authentication and integrity - services have been applied - Zero - Integrity and data origin services only - has been applied. - Specify NULL if not required - - output_message_buffer buffer, opaque, modify - Buffer to receive protected message. - Storage associated with this message must - be freed by the application after use with - a call to gss_release_buffer(). - - Function value: GSS status code - - GSS_S_COMPLETE Successful completion - - GSS_S_CONTEXT_EXPIRED The context has already expired - - GSS_S_NO_CONTEXT The context_handle parameter did not identify a - valid context - - GSS_S_BAD_QOP The specified QOP is not supported by the - mechanism. - - - - - - - - - - -Wray Standards Track [Page 80] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - -5.34. gss_wrap_size_limit - - OM_uint32 gss_wrap_size_limit ( - OM_uint32 *minor_status, - const gss_ctx_id_t context_handle, - int conf_req_flag, - gss_qop_t qop_req, - OM_uint32 req_output_size, - OM_uint32 *max_input_size) - - Purpose: - - Allows an application to determine the maximum message size that, if - presented to gss_wrap with the same conf_req_flag and qop_req - parameters, will result in an output token containing no more than - req_output_size bytes. - - This call is intended for use by applications that communicate over - protocols that impose a maximum message size. It enables the - application to fragment messages prior to applying protection. - - GSS-API implementations are recommended but not required to detect - invalid QOP values when gss_wrap_size_limit() is called. This routine - guarantees only a maximum message size, not the availability of - specific QOP values for message protection. - - Successful completion of this call does not guarantee that gss_wrap - will be able to protect a message of length max_input_size bytes, - since this ability may depend on the availability of system resources - at the time that gss_wrap is called. However, if the implementation - itself imposes an upper limit on the length of messages that may be - processed by gss_wrap, the implementation should not return a value - via max_input_bytes that is greater than this length. - - Parameters: - - minor_status Integer, modify - Mechanism specific status code - - context_handle gss_ctx_id_t, read - A handle that refers to the security over - which the messages will be sent. - - conf_req_flag Boolean, read - Indicates whether gss_wrap will be asked - to apply confidentiality protection in - - - - - -Wray Standards Track [Page 81] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - addition to integrity protection. See - the routine description for gss_wrap - for more details. - - qop_req gss_qop_t, read - Indicates the level of protection that - gss_wrap will be asked to provide. See - the routine description for gss_wrap for - more details. - - req_output_size Integer, read - The desired maximum size for tokens emitted - by gss_wrap. - - max_input_size Integer, modify - The maximum input message size that may - be presented to gss_wrap in order to - guarantee that the emitted token shall - be no larger than req_output_size bytes. - - Function value: GSS status code - - GSS_S_COMPLETE Successful completion - - GSS_S_NO_CONTEXT The referenced context could not be accessed. - - GSS_S_CONTEXT_EXPIRED The context has expired. - - GSS_S_BAD_QOP The specified QOP is not supported by the - mechanism. - -6. Security Considerations - - This document specifies a service interface for security facilities - and services; as such, security considerations appear throughout the - specification. Nonetheless, it is appropriate to summarize certain - specific points relevant to GSS-API implementors and calling - applications. Usage of the GSS-API interface does not in itself - provide security services or assurance; instead, these attributes are - dependent on the underlying mechanism(s) which support a GSS-API - implementation. Callers must be attentive to the requests made to - GSS-API calls and to the status indicators returned by GSS-API, as - these specify the security service characteristics which GSS-API will - provide. When the interprocess context transfer facility is used, - appropriate local controls should be applied to constrain access to - interprocess tokens and to the sensitive data which they contain. - - - - - -Wray Standards Track [Page 82] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - 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; - - - -Wray Standards Track [Page 83] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - #else - - /* - * We can't use X/Open definitions, so roll our own. - */ - - typedef gss_uint32 OM_uint32; - - typedef struct gss_OID_desc_struct { - OM_uint32 length; - void *elements; - } gss_OID_desc, *gss_OID; - - #endif - - typedef struct gss_OID_set_desc_struct { - size_t count; - gss_OID elements; - } gss_OID_set_desc, *gss_OID_set; - - typedef struct gss_buffer_desc_struct { - size_t length; - void *value; - } gss_buffer_desc, *gss_buffer_t; - - typedef struct gss_channel_bindings_struct { - OM_uint32 initiator_addrtype; - gss_buffer_desc initiator_address; - OM_uint32 acceptor_addrtype; - gss_buffer_desc acceptor_address; - gss_buffer_desc application_data; - } *gss_channel_bindings_t; - - /* - * For now, define a QOP-type as an OM_uint32 - */ - typedef OM_uint32 gss_qop_t; - - typedef int gss_cred_usage_t; - - /* - * Flag bits for context-level services. - */ - - - - - - - - -Wray Standards Track [Page 84] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - #define GSS_C_DELEG_FLAG 1 - #define GSS_C_MUTUAL_FLAG 2 - #define GSS_C_REPLAY_FLAG 4 - #define GSS_C_SEQUENCE_FLAG 8 - #define GSS_C_CONF_FLAG 16 - #define GSS_C_INTEG_FLAG 32 - #define GSS_C_ANON_FLAG 64 - #define GSS_C_PROT_READY_FLAG 128 - #define GSS_C_TRANS_FLAG 256 - - /* - * Credential usage options - */ - #define GSS_C_BOTH 0 - #define GSS_C_INITIATE 1 - #define GSS_C_ACCEPT 2 - - /* - * Status code types for gss_display_status - */ - #define GSS_C_GSS_CODE 1 - #define GSS_C_MECH_CODE 2 - - /* - * The constant definitions for channel-bindings address families - */ - #define GSS_C_AF_UNSPEC 0 - #define GSS_C_AF_LOCAL 1 - #define GSS_C_AF_INET 2 - #define GSS_C_AF_IMPLINK 3 - #define GSS_C_AF_PUP 4 - #define GSS_C_AF_CHAOS 5 - #define GSS_C_AF_NS 6 - #define GSS_C_AF_NBS 7 - #define GSS_C_AF_ECMA 8 - #define GSS_C_AF_DATAKIT 9 - #define GSS_C_AF_CCITT 10 - #define GSS_C_AF_SNA 11 - #define GSS_C_AF_DECnet 12 - #define GSS_C_AF_DLI 13 - #define GSS_C_AF_LAT 14 - #define GSS_C_AF_HYLINK 15 - #define GSS_C_AF_APPLETALK 16 - #define GSS_C_AF_BSC 17 - #define GSS_C_AF_DSS 18 - #define GSS_C_AF_OSI 19 - #define GSS_C_AF_X25 21 - - - - -Wray Standards Track [Page 85] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - #define GSS_C_AF_NULLADDR 255 - - /* - * Various Null values - */ - #define GSS_C_NO_NAME ((gss_name_t) 0) - #define GSS_C_NO_BUFFER ((gss_buffer_t) 0) - #define GSS_C_NO_OID ((gss_OID) 0) - #define GSS_C_NO_OID_SET ((gss_OID_set) 0) - #define GSS_C_NO_CONTEXT ((gss_ctx_id_t) 0) - #define GSS_C_NO_CREDENTIAL ((gss_cred_id_t) 0) - #define GSS_C_NO_CHANNEL_BINDINGS ((gss_channel_bindings_t) 0) - #define GSS_C_EMPTY_BUFFER {0, NULL} - - /* - * Some alternate names for a couple of the above - * values. These are defined for V1 compatibility. - */ - #define GSS_C_NULL_OID GSS_C_NO_OID - #define GSS_C_NULL_OID_SET GSS_C_NO_OID_SET - - /* - * Define the default Quality of Protection for per-message - * services. Note that an implementation that offers multiple - * levels of QOP may define GSS_C_QOP_DEFAULT to be either zero - * (as done here) to mean "default protection", or to a specific - * explicit QOP value. However, a value of 0 should always be - * interpreted by a GSS-API implementation as a request for the - * default protection level. - */ - #define GSS_C_QOP_DEFAULT 0 - - /* - * Expiration time of 2^32-1 seconds means infinite lifetime for a - * credential or security context - */ - #define GSS_C_INDEFINITE 0xfffffffful - - /* - * The implementation must reserve static storage for a - * gss_OID_desc object containing the value - * {10, (void *)"\x2a\x86\x48\x86\xf7\x12" - * "\x01\x02\x01\x01"}, - * corresponding to an object-identifier value of - * {iso(1) member-body(2) United States(840) mit(113554) - * infosys(1) gssapi(2) generic(1) user_name(1)}. The constant - * GSS_C_NT_USER_NAME should be initialized to point - * to that gss_OID_desc. - - - -Wray Standards Track [Page 86] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - */ - extern gss_OID GSS_C_NT_USER_NAME; - - /* - * The implementation must reserve static storage for a - * gss_OID_desc object containing the value - * {10, (void *)"\x2a\x86\x48\x86\xf7\x12" - * "\x01\x02\x01\x02"}, - * corresponding to an object-identifier value of - * {iso(1) member-body(2) United States(840) mit(113554) - * infosys(1) gssapi(2) generic(1) machine_uid_name(2)}. - * The constant GSS_C_NT_MACHINE_UID_NAME should be - * initialized to point to that gss_OID_desc. - */ - extern gss_OID GSS_C_NT_MACHINE_UID_NAME; - - /* - * The implementation must reserve static storage for a - * gss_OID_desc object containing the value - * {10, (void *)"\x2a\x86\x48\x86\xf7\x12" - * "\x01\x02\x01\x03"}, - * corresponding to an object-identifier value of - * {iso(1) member-body(2) United States(840) mit(113554) - * infosys(1) gssapi(2) generic(1) string_uid_name(3)}. - * The constant GSS_C_NT_STRING_UID_NAME should be - * initialized to point to that gss_OID_desc. - */ - extern gss_OID GSS_C_NT_STRING_UID_NAME; - - /* - * The implementation must reserve static storage for a - * gss_OID_desc object containing the value - * {6, (void *)"\x2b\x06\x01\x05\x06\x02"}, - * corresponding to an object-identifier value of - * {iso(1) org(3) dod(6) internet(1) security(5) - * nametypes(6) gss-host-based-services(2)). The constant - * GSS_C_NT_HOSTBASED_SERVICE_X should be initialized to point - * to that gss_OID_desc. This is a deprecated OID value, and - * implementations wishing to support hostbased-service names - * should instead use the GSS_C_NT_HOSTBASED_SERVICE OID, - * defined below, to identify such names; - * GSS_C_NT_HOSTBASED_SERVICE_X should be accepted a synonym - * for GSS_C_NT_HOSTBASED_SERVICE when presented as an input - * parameter, but should not be emitted by GSS-API - * implementations - */ - extern gss_OID GSS_C_NT_HOSTBASED_SERVICE_X; - - - - -Wray Standards Track [Page 87] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - /* - * The implementation must reserve static storage for a - * gss_OID_desc object containing the value - * {10, (void *)"\x2a\x86\x48\x86\xf7\x12" - * "\x01\x02\x01\x04"}, corresponding to an - * object-identifier value of {iso(1) member-body(2) - * Unites States(840) mit(113554) infosys(1) gssapi(2) - * generic(1) service_name(4)}. The constant - * GSS_C_NT_HOSTBASED_SERVICE should be initialized - * to point to that gss_OID_desc. - */ - extern gss_OID GSS_C_NT_HOSTBASED_SERVICE; - - /* - * The implementation must reserve static storage for a - * gss_OID_desc object containing the value - * {6, (void *)"\x2b\x06\01\x05\x06\x03"}, - * corresponding to an object identifier value of - * {1(iso), 3(org), 6(dod), 1(internet), 5(security), - * 6(nametypes), 3(gss-anonymous-name)}. The constant - * and GSS_C_NT_ANONYMOUS should be initialized to point - * to that gss_OID_desc. - */ - extern gss_OID GSS_C_NT_ANONYMOUS; - - - /* - * The implementation must reserve static storage for a - * gss_OID_desc object containing the value - * {6, (void *)"\x2b\x06\x01\x05\x06\x04"}, - * corresponding to an object-identifier value of - * {1(iso), 3(org), 6(dod), 1(internet), 5(security), - * 6(nametypes), 4(gss-api-exported-name)}. The constant - * GSS_C_NT_EXPORT_NAME should be initialized to point - * to that gss_OID_desc. - */ - extern gss_OID GSS_C_NT_EXPORT_NAME; - - - /* Major status codes */ - - #define GSS_S_COMPLETE 0 - - /* - * Some "helper" definitions to make the status code macros obvious. - */ - #define GSS_C_CALLING_ERROR_OFFSET 24 - #define GSS_C_ROUTINE_ERROR_OFFSET 16 - - - -Wray Standards Track [Page 88] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - #define GSS_C_SUPPLEMENTARY_OFFSET 0 - #define GSS_C_CALLING_ERROR_MASK 0377ul - #define GSS_C_ROUTINE_ERROR_MASK 0377ul - #define GSS_C_SUPPLEMENTARY_MASK 0177777ul - - /* - * The macros that test status codes for error conditions. - * Note that the GSS_ERROR() macro has changed slightly from - * the V1 GSS-API so that it now evaluates its argument - * only once. - */ - #define GSS_CALLING_ERROR(x) \ - (x & (GSS_C_CALLING_ERROR_MASK << GSS_C_CALLING_ERROR_OFFSET)) - #define GSS_ROUTINE_ERROR(x) \ - (x & (GSS_C_ROUTINE_ERROR_MASK << GSS_C_ROUTINE_ERROR_OFFSET)) - #define GSS_SUPPLEMENTARY_INFO(x) \ - (x & (GSS_C_SUPPLEMENTARY_MASK << GSS_C_SUPPLEMENTARY_OFFSET)) - #define GSS_ERROR(x) \ - (x & ((GSS_C_CALLING_ERROR_MASK << GSS_C_CALLING_ERROR_OFFSET) | \ - (GSS_C_ROUTINE_ERROR_MASK << GSS_C_ROUTINE_ERROR_OFFSET))) - - /* - * Now the actual status code definitions - */ - - /* - * Calling errors: - - */ - #define GSS_S_CALL_INACCESSIBLE_READ \ - (1ul << GSS_C_CALLING_ERROR_OFFSET) - #define GSS_S_CALL_INACCESSIBLE_WRITE \ - (2ul << GSS_C_CALLING_ERROR_OFFSET) - #define GSS_S_CALL_BAD_STRUCTURE \ - (3ul << GSS_C_CALLING_ERROR_OFFSET) - - /* - * Routine errors: - */ - #define GSS_S_BAD_MECH (1ul << - GSS_C_ROUTINE_ERROR_OFFSET) - #define GSS_S_BAD_NAME (2ul << - GSS_C_ROUTINE_ERROR_OFFSET) - #define GSS_S_BAD_NAMETYPE (3ul << - GSS_C_ROUTINE_ERROR_OFFSET) - #define GSS_S_BAD_BINDINGS (4ul << - GSS_C_ROUTINE_ERROR_OFFSET) - #define GSS_S_BAD_STATUS (5ul << - - - -Wray Standards Track [Page 89] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - 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. - */ - - - - - -Wray Standards Track [Page 90] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - OM_uint32 gss_acquire_cred - (OM_uint32 , /* minor_status */ - const gss_name_t, /* desired_name */ - OM_uint32, /* time_req */ - const gss_OID_set, /* desired_mechs */ - gss_cred_usage_t, /* cred_usage */ - gss_cred_id_t , /* output_cred_handle */ - gss_OID_set , /* actual_mechs */ - OM_uint32 * /* time_rec */ - ); - - OM_uint32 gss_release_cred - (OM_uint32 , /* minor_status */ - gss_cred_id_t * /* cred_handle */ - ); - - OM_uint32 gss_init_sec_context - (OM_uint32 , /* minor_status */ - const gss_cred_id_t, /* initiator_cred_handle */ - gss_ctx_id_t , /* context_handle */ - const gss_name_t, /* target_name */ - const gss_OID, /* mech_type */ - OM_uint32, /* req_flags */ - OM_uint32, /* time_req */ - const gss_channel_bindings_t, - /* input_chan_bindings */ - const gss_buffer_t, /* input_token */ - gss_OID , /* actual_mech_type */ - gss_buffer_t, /* output_token */ - OM_uint32 , /* ret_flags */ - OM_uint32 * /* time_rec */ - ); - - OM_uint32 gss_accept_sec_context - (OM_uint32 , /* minor_status */ - gss_ctx_id_t , /* context_handle */ - const gss_cred_id_t, /* acceptor_cred_handle */ - const gss_buffer_t, /* input_token_buffer */ - const gss_channel_bindings_t, - /* input_chan_bindings */ - gss_name_t , /* src_name */ - gss_OID , /* mech_type */ - gss_buffer_t, /* output_token */ - OM_uint32 , /* ret_flags */ - OM_uint32 , /* time_rec */ - gss_cred_id_t * /* delegated_cred_handle */ - ); - - - - -Wray Standards Track [Page 91] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - OM_uint32 gss_process_context_token - (OM_uint32 , /* minor_status */ - const gss_ctx_id_t, /* context_handle */ - const gss_buffer_t /* token_buffer */ - ); - - OM_uint32 gss_delete_sec_context - (OM_uint32 , /* minor_status */ - gss_ctx_id_t , /* context_handle */ - gss_buffer_t /* output_token */ - ); - - OM_uint32 gss_context_time - (OM_uint32 , /* minor_status */ - const gss_ctx_id_t, /* context_handle */ - OM_uint32 * /* time_rec */ - ); - - OM_uint32 gss_get_mic - (OM_uint32 , /* minor_status */ - const gss_ctx_id_t, /* context_handle */ - gss_qop_t, /* qop_req */ - const gss_buffer_t, /* message_buffer */ - gss_buffer_t /* message_token */ - ); - - OM_uint32 gss_verify_mic - (OM_uint32 , /* minor_status */ - const gss_ctx_id_t, /* context_handle */ - const gss_buffer_t, /* message_buffer */ - const gss_buffer_t, /* token_buffer */ - gss_qop_t * /* qop_state */ - ); - - OM_uint32 gss_wrap - (OM_uint32 , /* minor_status */ - const gss_ctx_id_t, /* context_handle */ - int, /* conf_req_flag */ - gss_qop_t, /* qop_req */ - const gss_buffer_t, /* input_message_buffer */ - int , /* conf_state */ - gss_buffer_t /* output_message_buffer */ - ); - - - - - - - - -Wray Standards Track [Page 92] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - OM_uint32 gss_unwrap - (OM_uint32 , /* minor_status */ - const gss_ctx_id_t, /* context_handle */ - const gss_buffer_t, /* input_message_buffer */ - gss_buffer_t, /* output_message_buffer */ - int , /* conf_state */ - gss_qop_t * /* qop_state */ - ); - - - - OM_uint32 gss_display_status - (OM_uint32 , /* minor_status */ - OM_uint32, /* status_value */ - int, /* status_type */ - const gss_OID, /* mech_type */ - OM_uint32 , /* message_context */ - gss_buffer_t /* status_string */ - ); - - OM_uint32 gss_indicate_mechs - (OM_uint32 , /* minor_status */ - gss_OID_set * /* mech_set */ - ); - - OM_uint32 gss_compare_name - (OM_uint32 , /* minor_status */ - const gss_name_t, /* name1 */ - const gss_name_t, /* name2 */ - int * /* name_equal */ - ); - - OM_uint32 gss_display_name - (OM_uint32 , /* minor_status */ - const gss_name_t, /* input_name */ - gss_buffer_t, /* output_name_buffer */ - gss_OID * /* output_name_type */ - ); - - OM_uint32 gss_import_name - (OM_uint32 , /* minor_status */ - const gss_buffer_t, /* input_name_buffer */ - const gss_OID, /* input_name_type */ - gss_name_t * /* output_name */ - ); - - - - - - -Wray Standards Track [Page 93] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - OM_uint32 gss_export_name - (OM_uint32, /* minor_status */ - const gss_name_t, /* input_name */ - gss_buffer_t /* exported_name */ - ); - - OM_uint32 gss_release_name - (OM_uint32 *, /* minor_status */ - gss_name_t * /* input_name */ - ); - - OM_uint32 gss_release_buffer - (OM_uint32 , /* minor_status */ - gss_buffer_t /* buffer */ - ); - - OM_uint32 gss_release_oid_set - (OM_uint32 , /* minor_status */ - gss_OID_set * /* set */ - ); - - OM_uint32 gss_inquire_cred - (OM_uint32 , /* minor_status */ - const gss_cred_id_t, /* cred_handle */ - gss_name_t , /* name */ - OM_uint32 , /* lifetime */ - gss_cred_usage_t , /* cred_usage */ - gss_OID_set * /* mechanisms */ - ); - - OM_uint32 gss_inquire_context ( - OM_uint32 , /* minor_status */ - const gss_ctx_id_t, /* context_handle */ - gss_name_t , /* src_name */ - gss_name_t , /* targ_name */ - OM_uint32 , /* lifetime_rec */ - gss_OID , /* mech_type */ - OM_uint32 , /* ctx_flags */ - int , /* locally_initiated */ - int * /* open */ - ); - - - - - - - - - - -Wray Standards Track [Page 94] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - OM_uint32 gss_wrap_size_limit ( - OM_uint32 , /* minor_status */ - const gss_ctx_id_t, /* context_handle */ - int, /* conf_req_flag */ - gss_qop_t, /* qop_req */ - OM_uint32, /* req_output_size */ - OM_uint32 * /* max_input_size */ - ); - - OM_uint32 gss_add_cred ( - OM_uint32 , /* minor_status */ - const gss_cred_id_t, /* input_cred_handle */ - const gss_name_t, /* desired_name */ - const gss_OID, /* desired_mech */ - gss_cred_usage_t, /* cred_usage */ - OM_uint32, /* initiator_time_req */ - OM_uint32, /* acceptor_time_req */ - gss_cred_id_t , /* output_cred_handle */ - gss_OID_set , /* actual_mechs */ - OM_uint32 , /* initiator_time_rec */ - OM_uint32 * /* acceptor_time_rec */ - ); - - OM_uint32 gss_inquire_cred_by_mech ( - OM_uint32 , /* minor_status */ - const gss_cred_id_t, /* cred_handle */ - const gss_OID, /* mech_type */ - gss_name_t , /* name */ - OM_uint32 , /* initiator_lifetime */ - OM_uint32 , /* acceptor_lifetime */ - gss_cred_usage_t * /* cred_usage */ - ); - - OM_uint32 gss_export_sec_context ( - OM_uint32 , /* minor_status */ - gss_ctx_id_t , /* context_handle */ - gss_buffer_t /* interprocess_token */ - ); - - OM_uint32 gss_import_sec_context ( - OM_uint32 , /* minor_status */ - const gss_buffer_t, /* interprocess_token */ - gss_ctx_id_t * /* context_handle */ - ); - - - - - - - -Wray Standards Track [Page 95] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - OM_uint32 gss_create_empty_oid_set ( - OM_uint32 , /* minor_status */ - gss_OID_set * /* oid_set */ - ); - - OM_uint32 gss_add_oid_set_member ( - OM_uint32 , /* minor_status */ - const gss_OID, /* member_oid */ - gss_OID_set * /* oid_set */ - ); - - OM_uint32 gss_test_oid_set_member ( - OM_uint32 , /* minor_status */ - const gss_OID, /* member */ - const gss_OID_set, /* set */ - int * /* present */ - ); - - OM_uint32 gss_inquire_names_for_mech ( - OM_uint32 , /* minor_status */ - const gss_OID, /* mechanism */ - gss_OID_set * /* name_types */ - ); - - OM_uint32 gss_inquire_mechs_for_name ( - OM_uint32 , /* minor_status */ - const gss_name_t, /* input_name */ - gss_OID_set * /* mech_types */ - ); - - OM_uint32 gss_canonicalize_name ( - OM_uint32 , /* minor_status */ - const gss_name_t, /* input_name */ - const gss_OID, /* mech_type */ - gss_name_t * /* output_name */ - ); - - OM_uint32 gss_duplicate_name ( - OM_uint32 , /* minor_status */ - const gss_name_t, /* src_name */ - gss_name_t * /* dest_name */ - ); - - /* - * The following routines are obsolete variants of gss_get_mic, - * gss_verify_mic, gss_wrap and gss_unwrap. They should be - * provided by GSS-API V2 implementations for backwards - * compatibility with V1 applications. Distinct entrypoints - - - -Wray Standards Track [Page 96] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - * (as opposed to #defines) should be provided, both to allow - * GSS-API V1 applications to link against GSS-API V2 - implementations, - * and to retain the slight parameter type differences between the - * obsolete versions of these routines and their current forms. - */ - - OM_uint32 gss_sign - (OM_uint32 , /* minor_status */ - gss_ctx_id_t, /* context_handle */ - int, /* qop_req */ - gss_buffer_t, /* message_buffer */ - gss_buffer_t /* message_token */ - ); - - - OM_uint32 gss_verify - (OM_uint32 , /* minor_status */ - gss_ctx_id_t, /* context_handle */ - gss_buffer_t, /* message_buffer */ - gss_buffer_t, /* token_buffer */ - int * /* qop_state */ - ); - - OM_uint32 gss_seal - (OM_uint32 , /* minor_status */ - gss_ctx_id_t, /* context_handle */ - int, /* conf_req_flag */ - int, /* qop_req */ - gss_buffer_t, /* input_message_buffer */ - int , /* conf_state */ - gss_buffer_t /* output_message_buffer */ - ); - - - OM_uint32 gss_unseal - (OM_uint32 , /* minor_status */ - gss_ctx_id_t, /* context_handle */ - gss_buffer_t, /* input_message_buffer */ - gss_buffer_t, /* output_message_buffer */ - int , /* conf_state */ - int * /* qop_state */ - ); - - #endif /* GSSAPI_H_ */ - - - - - - -Wray Standards Track [Page 97] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - -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. - - - - - -Wray Standards Track [Page 98] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - -B.2. Internal structure alignment - - GSS-API defines several data-structures containing differently-sized - fields. An ABI specification should include a detailed description - of how the fields of such structures are aligned, and if there is any - internal padding in these data structures. The use of compiler - defaults for the platform is recommended. - -B.3. Handle types - - The C bindings specify that the gss_cred_id_t and gss_ctx_id_t types - should be implemented as either pointer or arithmetic types, and that - if pointer types are used, care should be taken to ensure that two - handles may be compared with the == operator. Note that ANSI-C does - not guarantee that two pointer values may be compared with the == - operator unless either the two pointers point to members of a single - array, or at least one of the pointers contains a NULL value. - - For binary portability, additional constraints are required. The - following is an attempt at defining platform-independent constraints. - - The size of the handle type must be the same as sizeof(void *), using - the appropriate memory model. - - The == operator for the chosen type must be a simple bit-wise - comparison. That is, for two in-memory handle objects h1 and h2, the - boolean value of the expression - - (h1 == h2) - - should always be the same as the boolean value of the expression - - (memcmp(&h1, &h2, sizeof(h1)) == 0) - - The actual use of the type (void *) for handle types is discouraged, - not for binary portability reasons, but since it effectively disables - much of the compile-time type-checking that the compiler can - otherwise perform, and is therefore not "programmer-friendly". If a - pointer implementation is desired, and if the platform's - implementation of pointers permits, the handles should be implemented - as pointers to distinct implementation-defined types. - -B.4. The gss_name_t type - - The gss_name_t type, representing the internal name object, should be - implemented as a pointer type. The use of the (void *) type is - discouraged as it does not allow the compiler to perform strong - type-checking. However, the pointer type chosen should be of the - - - -Wray Standards Track [Page 99] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - - same size as the (void *) type. Provided this rule is obeyed, ABI - specifications need not further constrain the implementation of - gss_name_t objects. - -B.5. The int and size_t types - - Some platforms may support differently sized implementations of the - "int" and "size_t" types, perhaps chosen through compiler switches, - and perhaps dependent on memory model. An ABI specification for such - a platform should include required implementations for these types. - It is recommended that the default implementation (for the chosen - memory model, if appropriate) is chosen. - -B.6. Procedure-calling conventions - - Some platforms support a variety of different binary conventions for - calling procedures. Such conventions cover things like the format of - the stack frame, the order in which the routine parameters are pushed - onto the stack, whether or not a parameter count is pushed onto the - stack, whether some argument(s) or return values are to be passed in - registers, and whether the called routine or the caller is - responsible for removing the stack frame on return. For such - platforms, an ABI specification should specify which calling - convention is to be used for GSS-API implementations. - -References - - [GSSAPI] Linn, J., "Generic Security Service Application Program - Interface Version 2, Update 1", RFC 2743, January 2000. - - [XOM] OSI Object Management API Specification, Version 2.0 t", - X.400 API Association & X/Open Company Limited, August - 24, 1990 Specification of datatypes and routines for - manipulating information objects. - -Author's Address - - John Wray - Iris Associates - 5 Technology Park Drive, - Westford, MA 01886 - USA - - Phone: +1-978-392-6689 - EMail: John_Wray@Iris.com - - - - - - -Wray Standards Track [Page 100] - -RFC 2744 GSS-API V2: C-bindings January 2000 - - -Full Copyright Statement - - Copyright (C) The Internet Society (2000). All Rights Reserved. - - This document and translations of it may be copied and furnished to - others, and derivative works that comment on or otherwise explain it - or assist in its implementation may be prepared, copied, published - and distributed, in whole or in part, without restriction of any - kind, provided that the above copyright notice and this paragraph are - included on all such copies and derivative works. However, this - document itself may not be modified in any way, such as by removing - the copyright notice or references to the Internet Society or other - Internet organizations, except as needed for the purpose of - developing Internet standards in which case the procedures for - copyrights defined in the Internet Standards process must be - followed, or as required to translate it into languages other than - English. - - The limited permissions granted above are perpetual and will not be - revoked by the Internet Society or its successors or assigns. - - This document and the information contained herein is provided on an - "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING - TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING - BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION - HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF - MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. - -Acknowledgement - - Funding for the RFC Editor function is currently provided by the - Internet Society. - - - - - - - - - - - - - - - - - - - -Wray Standards Track [Page 101] - |
