diff options
Diffstat (limited to 'crypto/heimdal/doc/standardisation/rfc1509.txt')
| -rw-r--r-- | crypto/heimdal/doc/standardisation/rfc1509.txt | 2691 |
1 files changed, 2691 insertions, 0 deletions
diff --git a/crypto/heimdal/doc/standardisation/rfc1509.txt b/crypto/heimdal/doc/standardisation/rfc1509.txt new file mode 100644 index 0000000..f36cd80 --- /dev/null +++ b/crypto/heimdal/doc/standardisation/rfc1509.txt @@ -0,0 +1,2691 @@ + + + + + + +Network Working Group J. Wray +Request for Comments: 1509 Digital Equipment Corporation + September 1993 + + + Generic Security Service API : C-bindings + +Status of this Memo + + This RFC 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" for the standardization state and status + of this protocol. Distribution of this memo is unlimited. + +Abstract + + This document specifies C language bindings for the Generic Security + Service Application Program Interface (GSS-API), which is described + at a language-independent conceptual level in other documents. + + The Generic Security Service Application Programming Interface (GSS- + API) provides security services to its callers, and is intended for + implementation atop alternative 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. + +1. INTRODUCTION + + The Generic Security Service Application Programming Interface [1] + provides security services to calling applications. It allows a + communicating application to authenticate the user associated with + another application, to delegate rights to another application, and + to apply security services such as confidentiality and integrity on a + per-message basis. + + There are four stages to using the GSSAPI: + + (a) The application acquires a set of credentials with which it may + prove its identity to other processes. The application's + credentials vouch for its global identity, which may or may not + be related to the local username under which it is running. + + + + + +Wray [Page 1] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + (b) A pair of communicating applications establish a joint security + context using their credentials. The security context is a + pair of GSSAPI data structures that contain shared state + information, which is required in order that per-message + security services may be provided. 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. This transfer of rights is termed + delegation, and is achieved by creating a set of credentials, + similar to those used by the originating application, but which + may be used by the responder. To establish and maintain the + shared information that makes up the security context, certain + GSSAPI calls will return a token data structure, which is a + cryptographically protected opaque data type. The caller of + such a GSSAPI routine is responsible for transferring the token + to the peer application, which should then pass it to a + corresponding GSSAPI routine which will decode it and extract + the information. + + (c) Per-message services are invoked to apply either: + + (i) integrity and data origin authentication, or + + (ii) confidentiality, integrity and data origin authentication + to application data, which are treated by GSSAPI as + arbitrary octet-strings. The application transmitting a + message that it wishes to protect will call the appropriate + GSSAPI routine (sign or seal) to apply protection, specifying + the appropriate security context, and send the result to the + receiving application. The receiver will pass the received + data to the corresponding decoding routine (verify or unseal) + to remove the protection and validate the data. + + (d) At the completion of a communications session (which may extend + across several connections), the peer applications call GSSAPI + routines to delete the security context. Multiple contexts may + also be used (either successively or simultaneously) within a + single communications association. + +2. GSSAPI Routines + + This section lists the functions performed by each of the GSSAPI + routines and discusses their major parameters, describing how they + are to be passed to the routines. The routines are listed in figure + 4-1. + + + + +Wray [Page 2] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + Figure 4-1 GSSAPI Routines + + + Routine Function + + gss_acquire_cred Assume a global identity + + gss_release_cred Discard credentials + + gss_init_sec_context Initiate a security context + with a peer application + + gss_accept_sec_context Accept a security context + initiated by a peer + application + + gss_process_context_token Process a token on a security + context from a peer + application + + gss_delete_sec_context Discard a security context + + gss_context_time Determine for how long a + context will remain valid + + gss_sign Sign a message; integrity + service + + gss_verify Check signature on a message + + gss_seal Sign (optionally encrypt) a + message; confidentiality + service + + gss_unseal Verify (optionally decrypt) + message + + gss_display_status Convert an API status code + to text + + gss_indicate_mechs Determine underlying + authentication mechanism + + gss_compare_name Compare two internal-form + names + + gss_display_name Convert opaque name to text + + + + +Wray [Page 3] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + gss_import_name Convert a textual name to + internal-form + + gss_release_name Discard an internal-form + name + + gss_release_buffer Discard a buffer + + gss_release_oid_set Discard a set of object + identifiers + + gss_inquire_cred Determine information about + a credential + + Individual GSSAPI implementations may augment these routines by + providing additional mechanism-specific routines if required + functionality is not available from the generic forms. Applications + are encouraged to use the generic routines wherever possible on + portability grounds. + +2.1. Data Types and Calling Conventions + + The following conventions are used by the GSSAPI: + +2.1.1. Structured data types + + Wherever these GSSAPI C-bindings describe structured data, only + fields that must be provided by all GSSAPI implementation are + documented. Individual implementations may provide additional + fields, either for internal use within GSSAPI routines, or for use by + non-portable applications. + +2.1.2. Integer types + + GSSAPI defines the following integer data type: + + OM_uint32 32-bit unsigned integer + + Where guaranteed minimum bit-count is important, this portable data + type is used by the GSSAPI routine definitions. Individual GSSAPI + implementations will include appropriate typedef definitions to map + this type onto a built-in data type. + +2.1.3. String and similar data + + Many of the GSSAPI routines take arguments and return values that + describe contiguous multiple-byte data. All such data is passed + between the GSSAPI and the caller using the gss_buffer_t data type. + + + +Wray [Page 4] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + 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 passed to the application by a GSSAPI routine using + the gss_buffer_t conventions is allocated by the GSSAPI routine. The + application may free this storage by invoking the gss_release_buffer + routine. Allocation of the gss_buffer_desc object is always the + responsibility of the application; Unused gss_buffer_desc objects + may be initialized to the value GSS_C_EMPTY_BUFFER. + +2.1.3.1. Opaque data types + + Certain multiple-word data items are considered opaque data types at + the GSSAPI, because their internal structure has no significance + either to the GSSAPI or to the caller. Examples of such opaque data + types are the input_token parameter to gss_init_sec_context (which is + opaque to the caller), and the input_message parameter to gss_seal + (which is opaque to the GSSAPI). Opaque data is passed between the + GSSAPI and the application using the gss_buffer_t datatype. + +2.1.3.2. Character strings + + Certain multiple-word data items may be regarded as simple ISO + Latin-1 character strings. An example of this is the + input_name_buffer parameter to gss_import_name. Some GSSAPI routines + also return character strings. Character strings are passed between + the application and the GSSAPI using the gss_buffer_t datatype, + defined earlier. + +2.1.4. Object Identifiers + + Certain GSSAPI procedures take parameters of the type gss_OID, or + Object identifier. This is a type containing ISO-defined tree- + structured values, and is used by the GSSAPI caller to select an + underlying security mechanism. A value of type gss_OID has the + following structure: + + typedef struct gss_OID_desc_struct { + OM_uint32 length; + void *elements; + } gss_OID_desc, *gss_OID; + + + + +Wray [Page 5] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + The elements field of this structure points to the first byte of an + octet string containing the ASN.1 BER encoding of the value 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- oganization(3) icd-ecma(12) member-company(2) dec(1011) + cryptoAlgorithms(7) SPX(5)} meaning SPX (Digital's X.509 + authentication mechanism) has a length field of 7 and an elements + field pointing to seven octets containing the following octal values: + 53,14,2,207,163,7,5. GSSAPI implementations should provide constant + gss_OID values to allow callers 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 + 2.1.10). Applications should treat gss_OID_desc values returned by + GSSAPI routines as read-only. In particular, the application should + not attempt to deallocate them. The gss_OID_desc datatype is + equivalent to the X/Open OM_object_identifier datatype [2]. + +2.1.5. Object Identifier Sets + + Certain GSSAPI procedures take parameters of the type gss_OID_set. + This type represents one or more object identifiers (section 2.1.4). + A gss_OID_set object has the following structure: + + typedef struct gss_OID_set_desc_struct { + int count; + gss_OID elements; + } gss_OID_set_desc, *gss_OID_set; + + The count field contains the number of OIDs within the set. The + elements field is a pointer to an array of gss_OID_desc objects, each + of which describes a single OID. gss_OID_set values are used to name + the available mechanisms supported by the GSSAPI, to request the use + of specific mechanisms, and to indicate which mechanisms a given + credential supports. Storage associated with gss_OID_set values + returned to the application by the GSSAPI may be deallocated by the + gss_release_oid_set routine. + +2.1.6. Credentials + + A credential handle is a caller-opaque atomic datum that identifies a + GSSAPI credential data structure. It is represented by the caller- + opaque type gss_cred_id_t, which may be implemented as either an + arithmetic or a pointer type. Credentials describe a principal, and + they give their holder the ability to act as that principal. The + GSSAPI does not make the actual credentials available to + applications; instead the credential handle is used to identify a + particular credential, held internally by GSSAPI or underlying + + + +Wray [Page 6] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + mechanism. Thus the credential handle contains no security-relavent + information, and requires no special protection by the application. + Depending on the implementation, a given credential handle may refer + to different credentials when presented to the GSSAPI by different + callers. Individual GSSAPI implementations should define both the + scope of a credential handle and the scope of a credential itself + (which must be at least as wide as that of a handle). Possibilities + for credential handle scope include the process that acquired the + handle, the acquiring process and its children, or all processes + sharing some local identification information (e.g., UID). If no + handles exist by which a given credential may be reached, the GSSAPI + may delete the credential. + + Certain routines allow credential handle parameters to be omitted to + indicate the use of a default credential. The mechanism by which a + default credential is established and its scope should be defined by + the individual GSSAPI implementation. + +2.1.7. Contexts + + The gss_ctx_id_t data type contains a caller-opaque atomic value that + identifies one end of a GSSAPI security context. It may be + implemented as either an arithmetic or a pointer type. Depending on + the implementation, a given gss_ctx_id_t value may refer to different + GSSAPI security contexts when presented to the GSSAPI by different + callers. The security context holds state information about each end + of a peer communication, including cryptographic state information. + Individual GSSAPI implementations should define the scope of a + context. Since no way is provided by which a new gss_ctx_id_t value + may be obtained for an existing context, the scope of a context + should be the same as the scope of a gss_ctx_id_t. + +2.1.8. Authentication tokens + + A token is a caller-opaque type that GSSAPI uses to maintain + synchronization between the context data structures at each end of a + GSSAPI security context. The token is a cryptographically protected + bit-string, generated by the underlying mechanism at one end of a + GSSAPI security context for use by the peer mechanism at the other + end. Encapsulation (if required) and transfer of the token are the + responsibility of the peer applications. A token is passed between + the GSSAPI and the application using the gss_buffer_t conventions. + +2.1.9. Status values + + One or more status codes are returned by each GSSAPI routine. Two + distinct sorts of status codes are returned. These are termed GSS + status codes and Mechanism status codes. + + + +Wray [Page 7] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + +2.1.9.1. GSS status codes + + GSSAPI routines return GSS status codes as their OM_uint32 function + value. These codes indicate errors that are independent of the + underlying mechanism 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 GSSAPI + specification) or calling errors (errors that are specific to these + bindings). + + A GSS status code can indicate a single fatal generic API error from + the routine and a single calling error. In addition, supplementary + status information may be indicated via the setting of bits in the + supplementary info field of a GSS status code. + + These errors are encoded into the 32-bit GSS status code as follows: + + MSB LSB + |------------------------------------------------------------| + | Calling Error | Routine Error | Supplementary Info | + |------------------------------------------------------------| + Bit 31 24 23 16 15 0 + + Hence if a GSSAPI 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 5-1 Calling Errors + + Name Value in Meaning + Field + GSS_S_CALL_INACCESSIBLE_READ 1 A required input + parameter could + not be read. + GSS_S_CALL_INACCESSIBLE_WRITE 2 A required output + parameter could + not be written. + GSS_S_CALL_BAD_STRUCTURE 3 A parameter was + malformed + + + + + +Wray [Page 8] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + Table 5-2 Routine Errors + + Name Value in Meaning + Field + + GSS_S_BAD_MECH 1 An unsupported mechanism was + requested + GSS_S_BAD_NAME 2 An invalid name was supplied + GSS_S_BAD_NAMETYPE 3 A supplied name was of an + unsupported type + GSS_S_BAD_BINDINGS 4 Incorrect channel bindings + were supplied + GSS_S_BAD_STATUS 5 An invalid status code was + supplied + + GSS_S_BAD_SIG 6 A token had an invalid + signature + GSS_S_NO_CRED 7 No credentials were supplied + 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) + + Table 5-3 Supplementary Status Bits + + Name Bit Number Meaning + GSS_S_CONTINUE_NEEDED 0 (LSB) The routine must be called + again to complete its + function. + See routine documentation for + detailed description. + GSS_S_DUPLICATE_TOKEN 1 The token was a duplicate of + an earlier token + GSS_S_OLD_TOKEN 2 The token's validity period + has expired + GSS_S_UNSEQ_TOKEN 3 A later token has already been + processed + + 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. + + + + + +Wray [Page 9] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + 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. + + A GSSAPI implementation may choose to signal calling errors in a + platform-specific manner instead of, or in addition to the routine + value; routine errors and supplementary info should be returned via + routine status values only. + +2.1.9.2. Mechanism-specific status codes + + GSSAPI 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 GSSAPI routine, + even if it returns a calling error or one of the generic API errors + indicated above as fatal, although 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 set set + by the routine, even in the event of an error, although in such cases + the GSSAPI routine may elect to set the returned parameter value to + NULL to indicate that no storage was actually allocated. Any length + field associated with such pointers (as in a gss_buffer_desc + structure) should also be set to zero in such cases. + + The GSS status code GSS_S_FAILURE is used to indicate that the + underlying mechanism detected an error for which no specific GSS + status code is defined. The mechanism status code will provide more + details about the error. + +2.1.10. Names + + A name is used to identify a person or entity. GSSAPI authenticates + the relationship between a name and the entity claiming the name. + + + +Wray [Page 10] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + Two distinct representations are defined for names: + + (a) A printable form, for presentation to a user + + (b) An internal form, for presentation at the API + + The syntax of a printable name is defined by the GSSAPI + implementation, and may be dependent on local system configuration, + or on individual user preference. The internal form provides a + canonical representation of the name that is independent of + configuration. + + A given GSSAPI implementation may support names drawn from multiple + namespaces. In such an implementation, the internal form of the name + must include fields that identify the namespace from which the name + is drawn. The namespace from which a printable name is drawn is + specified by an accompanying object identifier. + + Routines (gss_import_name and gss_display_name) are provided to + convert names between their printable representations and the + 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 preferred syntax for each supported name-type. + + Comparison of internal-form names is accomplished via the + gss_compare_names routine. This removes the need for the application + program to understand the syntaxes of the various printable names + that a given GSSAPI implementation may support. + + Storage is allocated by routines that return gss_name_t values. A + procedure, gss_release_name, is provided to free storage associated + with a name. + +2.1.11. Channel Bindings + + GSSAPI supports the use of user-specified tags to identify a given + context to the peer application. These tags are used to identify the + particular communications channel that carries the context. Channel + bindings are communicated to the GSSAPI using the following + structure: + + + + + + + + + + +Wray [Page 11] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + 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 DARPA Internet address type + GSS_C_AF_IMPLINK ARPAnet IMP address type (eg IP) + 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 (eg X.25) + GSS_C_AF_SNA IBM SNA address type + GSS_C_AF_DECnet DECnet address type + GSS_C_AF_DLI Direct data link interface address type + GSS_C_AF_LAT LAT address type + GSS_C_AF_HYLINK NSC Hyperchannel address type + GSS_C_AF_APPLETALK AppleTalk address type + GSS_C_AF_BSC BISYNC 2780/3780 address type + GSS_C_AF_DSS Distributed system services address type + GSS_C_AF_OSI OSI TP4 address type + GSS_C_AF_X25 X25 + GSS_C_AF_NULLADDR No address specified + + Note that these name address families rather than specific addressing + formats. For address families that contain several alternative + address forms, the initiator_address and acceptor_address fields must + contain sufficient information to determine which address form is + used. When not otherwise specified, addresses should be specified in + network byte-order. + + Conceptually, the GSSAPI concatenates the initiator_addrtype, + initiator_address, acceptor_addrtype, acceptor_address and + application_data to form an octet string. The mechanism signs this + octet string, and binds the signature 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 + + + +Wray [Page 12] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + signature is calculated in the same way. The calculated signature is + compared with that found in the token, and if the signatures 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 + signature); 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. + +2.1.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. + +2.1.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. + +2.1.12.2. Integer types (input) + + Individual parameter documentation lists values to be used to + indicate default actions. + +2.1.12.3. Integer types (output) + + Specify NULL as the value for the pointer. + +2.1.12.4. Pointer types + + Specify NULL as the value. + +2.1.12.5. Object IDs + + Specify GSS_C_NULL_OID as the value. + +2.1.12.6. Object ID Sets + + Specify GSS_C_NULL_OID_SET as the value. + + + +Wray [Page 13] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + +2.1.12.7. Credentials + + Specify GSS_C_NO_CREDENTIAL to use the default credential handle. + +2.1.12.8. Channel Bindings + + Specify GSS_C_NO_CHANNEL_BINDINGS to indicate that channel bindings + are not to be used. + +3. GSSAPI routine descriptions + +2.1. gss_acquire_cred + + OM_uint32 gss_acquire_cred ( + OM_uint32 * minor_status, + gss_name_t desired_name, + OM_uint32 time_req, + gss_OID_set desired_mechs, + int cred_usage, + gss_cred_id_t * output_cred_handle, + gss_OID_set * actual_mechs, + OM_int32 * time_rec) + Purpose: + + Allows an application to acquire a handle for a pre-existing + credential by name. GSSAPI 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 result in 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 credential acquisition is time-consuming for a mechanism, the + mechanism may chooses to delay the actual acquisition until the + credential is required (e.g., by gss_init_sec_context or + gss_accept_sec_context). Such mechanism-specific implementation + decisions should be invisible to the calling application; thus a call + of gss_inquire_cred immediately following the call of + gss_acquire_cred must return valid credential data, and may therefore + incur the overhead of a deferred credential acquisition. + + Parameters: + + desired_name gss_name_t, read + Name of principal whose credential + should be acquired + + + +Wray [Page 14] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + time_req integer, read + number of seconds that credentials + should remain valid + + desired_mechs Set of Object IDs, read + set of underlying security mechanisms that + may be used. GSS_C_NULL_OID_SET may be used + to obtain an implementation-specific default. + + cred_usage integer, 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. + + actual_mechs Set of Object IDs, modify, optional + The set of mechanisms for which the + credential is valid. 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 + + 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 + + + +Wray [Page 15] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + ill-formed. + + GSS_S_FAILURE Unspecified failure. The minor_status parameter + contains more detailed information + +3.2. gss_release_cred + + OM_uint32 gss_release_cred ( + OM_uint32 * minor_status, + gss_cred_id_t * cred_handle) + + Purpose: + + Informs GSSAPI that the specified credential handle is no longer + required by the process. When all processes have released a + credential, it will be deleted. + + Parameters: + + cred_handle gss_cred_id_t, modify, optional + buffer containing opaque credential + handle. If GSS_C_NO_CREDENTIAL is supplied, + the default credential will be released + + 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 [Page 16] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + +3.3. gss_init_sec_context + + OM_uint32 gss_init_sec_context ( + OM_uint32 * minor_status, + gss_cred_id_t claimant_cred_handle, + gss_ctx_id_t * context_handle, + gss_name_t target_name, + gss_OID mech_type, + int req_flags, + int time_req, + gss_channel_bindings_t + input_chan_bindings, + gss_buffer_t input_token + gss_OID * actual_mech_type, + gss_buffer_t output_token, + int * ret_flags, + OM_uint32 * time_rec ) + + Purpose: + + Initiates the establishment of a security context between the + application and a remote peer. Initially, the input_token parameter + should be specified as GSS_C_NO_BUFFER. The routine may return a + output_token which should be transferred to the peer application, + where the peer application will present it to gss_accept_sec_context. + If no token need be sent, gss_init_sec_context will indicate this by + setting the length field of the output_token argument to zero. To + complete the context establishment, one or more reply tokens may be + required from the peer application; if so, gss_init_sec_context will + return a status indicating 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_init_sec_context via the + input_token parameters. + + The values returned via the ret_flags and time_rec parameters are not + defined unless the routine returns GSS_S_COMPLETE. + + Parameters: + + claimant_cred_handle gss_cred_id_t, read, optional + handle for credentials claimed. Supply + GSS_C_NO_CREDENTIAL to use default + credentials. + + 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. + + + +Wray [Page 17] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + target_name gss_name_t, read + Name of target + + mech_type OID, read, optional + Object ID of desired mechanism. Supply + GSS_C_NULL_OID to obtain an implementation + specific default + + req_flags bit-mask, read + Contains four 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 signed + or sealed messages + False - Don't attempt to detect + replayed messages + GSS_C_SEQUENCE_FLAG + True - Enable detection of out-of-sequence + signed or sealed messages + False - Don't attempt to detect + out-of-sequence messages + + time_req integer, read + Desired number of seconds for which context + should remain valid. Supply 0 to request a + default validity period. + + input_chan_bindings channel bindings, read + Application-specified bindings. Allows + application to securely bind channel + identification information to the security + context. + + + + +Wray [Page 18] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + input_token buffer, opaque, read, optional (see text) + Token received from peer application. + Supply GSS_C_NO_BUFFER on initial call. + + actual_mech_type OID, modify + actual mechanism used. + + 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. + + ret_flags bit-mask, modify + Contains six independent flags, each of which + indicates that the context supports a specific + service option. 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 to + the remote peer + False - No credentials were delegated + GSS_C_MUTUAL_FLAG + True - Remote peer has been asked to + authenticated itself + False - Remote peer has not been asked to + authenticate itself + GSS_C_REPLAY_FLAG + True - replay of signed or sealed messages + will be detected + False - replayed messages will not be + detected + GSS_C_SEQUENCE_FLAG + True - out-of-sequence signed or sealed + 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 seal routine + False - No confidentiality service (via + seal) available. seal will provide + message encapsulation, data-origin + + + +Wray [Page 19] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + authentication and integrity + services only. + GSS_C_INTEG_FLAG + True - Integrity service may be invoked by + calling either gss_sign or gss_seal + routines. + False - Per-message integrity service + unavailable. + + time_rec integer, modify, optional + number of seconds for which the context + will remain valid. If the implementation does + not support credential expiration, the value + GSS_C_INDEFINITE will be returned. Specify + NULL if not required. + + minor_status integer, modify + Mechanism specific status code. + + Function value: + + GSS status code: + + GSS_S_COMPLETE Successful completion + + GSS_S_CONTINUE_NEEDED Indicates that a token from the peer + application is required to complete thecontext, and + that gss_init_sec_context must be called again with + that token. + + GSS_S_DEFECTIVE_TOKEN Indicates that consistency checks performed on + the input_token failed + + GSS_S_DEFECTIVE_CREDENTIAL Indicates that consistency checks + performed on the credential failed. + + GSS_S_NO_CRED The supplied credentials were not valid for context + initiation, or the credential handle did not + reference any credentials. + + GSS_S_CREDENTIALS_EXPIRED The referenced credentials have expired + + GSS_S_BAD_BINDINGS The input_token contains different channel + bindings to those specified via the + input_chan_bindings parameter + + GSS_S_BAD_SIG The input_token contains an invalid signature, or a + signature that could not be verified + + + +Wray [Page 20] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + 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_FAILURE Failure. See minor_status for more information + +3.4. gss_accept_sec_context + + OM_uint32 gss_accept_sec_context ( + OM_uint32 * minor_status, + gss_ctx_id_t * context_handle, + gss_cred_id_t verifier_cred_handle, + gss_buffer_t input_token_buffer + gss_channel_bindings_t + input_chan_bindings, + gss_name_t * src_name, + gss_OID * mech_type, + gss_buffer_t output_token, + int * ret_flags, + OM_uint32 * time_rec, + gss_cred_id_t * delegated_cred_handle) + + 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 [Page 21] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + The values returned via the src_name, ret_flags, time_rec, and + delegated_cred_handle parameters are not defined unless the routine + returns GSS_S_COMPLETE. + + 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. + + verifier_cred_handle gss_cred_id_t, read, optional + Credential handle claimed by context + acceptor. + Specify GSS_C_NO_CREDENTIAL to use default + credentials. If GSS_C_NO_CREDENTIAL is + specified, but the caller has no default + credentials established, an + implementation-defined default credential + may be used. + + input_token_buffer buffer, opaque, read + token obtained from remote application + + input_chan_bindings channel bindings, read + Application-specified bindings. Allows + application to securely bind channel + identification information to the security + context. + + 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 + Security mechanism used. The returned + OID value will be a pointer into static + storage, and should be treated as read-only + by the caller. + + 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. + + + + +Wray [Page 22] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + ret_flags bit-mask, modify + Contains six independent flags, each of + which indicates that the context supports a + specific service option. 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 signed or sealed messages + will be detected + False - replayed messages will not be + detected + GSS_C_SEQUENCE_FLAG + True - out-of-sequence signed or sealed + 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 seal routine + False - No confidentiality service (via + seal) available. seal 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_sign or + gss_seal routines. + False - Per-message integrity service + unavailable. + + time_rec integer, modify, optional + number of seconds for which the context + will remain valid. Specify NULL if not required. + + + + +Wray [Page 23] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + delegated_cred_handle + gss_cred_id_t, modify + credential handle for credentials received from + context initiator. Only valid if deleg_flag in + ret_flags is true. + + minor_status integer, modify + Mechanism specific status code. + + Function value: + + GSS status code: + + GSS_S_COMPLETE Successful completion + + GSS_S_CONTINUE_NEEDED Indicates that a token from the peer + application is required to complete the context, + and that gss_accept_sec_context must be called + again with that token. + + GSS_S_DEFECTIVE_TOKEN Indicates that consistency checks + performed on the input_token failed. + + GSS_S_DEFECTIVE_CREDENTIAL Indicates that consistency checks + performed on the credential failed. + + GSS_S_NO_CRED The supplied credentials were not valid for + context acceptance, or the credential handle + did not reference any credentials. + + GSS_S_CREDENTIALS_EXPIRED The referenced credentials have + expired. + + GSS_S_BAD_BINDINGS The input_token contains different channel + bindings to those specified via the + input_chan_bindings parameter. + + GSS_S_NO_CONTEXT Indicates that the supplied context handle did + not refer to a valid context. + + GSS_S_BAD_SIG The input_token contains an invalid signature. + + GSS_S_OLD_TOKEN The input_token was too old. This is a fatal + error during context establishment. + + GSS_S_DUPLICATE_TOKEN The input_token is valid, but is a + duplicate of a token already processed. This + is a fatal error during context establishment. + + + +Wray [Page 24] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + GSS_S_FAILURE Failure. See minor_status for more information. + +3.5. gss_process_context_token + + OM_uint32 gss_process_context_token ( + OM_uint32 * minor_status, + gss_ctx_id_t context_handle, + gss_buffer_t token_buffer) + + Purpose: + + Provides a way to pass a token to the security service. Usually, + tokens are associated either with context establishment (when they + would be passed to gss_init_sec_context or gss_accept_sec_context) or + with per-message security service (when they would be passed to + gss_verify or gss_unseal). Occasionally, tokens may be received at + other times, and gss_process_context_token allows such tokens to be + passed to the underlying security service for processing. At + present, such additional tokens may only be generated by + gss_delete_sec_context. GSSAPI implementation may use this service + to implement deletion of the security context. + + Parameters: + + context_handle gss_ctx_id_t, read + context handle of context on which token is to + be processed + + token_buffer buffer, opaque, read + pointer to first byte of token to process + + minor_status integer, modify + Implementation specific status code. + + 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_FAILURE Failure. See minor_status for more information + + GSS_S_NO_CONTEXT The context_handle did not refer to a valid + context + + + + +Wray [Page 25] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + +3.6. 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 generate an output_token, which when passed to the peer + gss_process_context_token will instruct it to do likewise. No + further security services may be obtained using the context specified + by context_handle. + + Parameters: + + minor_status integer, modify + Mechanism specific status code. + + context_handle gss_ctx_id_t, modify + context handle identifying context to delete. + + output_token buffer, opaque, modify + token to be sent to remote application to + instruct it to also delete the context + + Function value: + + GSS status code: + + GSS_S_COMPLETE Successful completion + + GSS_S_FAILURE Failure, see minor_status for more information + + GSS_S_NO_CONTEXT No valid context was supplied + +3.7. gss_context_time + + OM_uint32 gss_context_time ( + OM_uint32 * minor_status, + gss_ctx_id_t context_handle, + OM_uint32 * time_rec) + Purpose: + + Determines the number of seconds for which the specified context will + remain valid. + + + +Wray [Page 26] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + 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_CREDENTIALS_EXPIRED The context is recognized, but + associated credentials have expired + + GSS_S_NO_CONTEXT The context_handle parameter did not identify a + valid context + +3.8. gss_sign + + 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 msg_token) + Purpose: + + Generates a cryptographic signature for the supplied message, and + places the signature in a token for transfer to the peer application. + The qop_req parameter allows a choice between several cryptographic + algorithms, if supported by the chosen mechanism. + + Parameters: + + minor_status integer, modify + Implementation specific status code. + + context_handle gss_ctx_id_t, read + identifies the context on which the message + + + +Wray [Page 27] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + will be sent + + qop_req integer, 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_sign will return a + major_status of GSS_S_FAILURE. + + message_buffer buffer, opaque, read + message to be signed + + msg_token buffer, opaque, modify + buffer to receive token + + Function value: + + GSS status code: + + GSS_S_COMPLETE Successful completion + + GSS_S_CONTEXT_EXPIRED The context has already expired + + GSS_S_CREDENTIALS_EXPIRED The context is recognized, but + associated credentials have expired + + GSS_S_NO_CONTEXT The context_handle parameter did not identify a + valid context + + GSS_S_FAILURE Failure. See minor_status for more information. + +3.9. gss_verify + + 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) + Purpose: + + Verifies that a cryptographic signature, 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. + + + +Wray [Page 28] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + 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 integer, modify + quality of protection gained from signature + + Function value: + + GSS status code: + + GSS_S_COMPLETE Successful completion + + GSS_S_DEFECTIVE_TOKEN The token failed consistency checks + + GSS_S_BAD_SIG The signature was incorrect + + GSS_S_DUPLICATE_TOKEN The token was valid, and contained a correct + signature for the message, but it had already + been processed + + GSS_S_OLD_TOKEN The token was valid, and contained a correct + signature for the message, but it is too old + + GSS_S_UNSEQ_TOKEN The token was valid, and contained a correct + signature for the message, but has been + verified out of sequence; an earlier token has + been signed or sealed by the remote + application, but not yet been processed + locally. + + GSS_S_CONTEXT_EXPIRED The context has already expired + + GSS_S_CREDENTIALS_EXPIRED The context is recognized, but + associated credentials have expired + + + + + +Wray [Page 29] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + GSS_S_NO_CONTEXT The context_handle parameter did not identify a + valid context + + GSS_S_FAILURE Failure. See minor_status for more information. + +3.10. gss_seal + + OM_uint32 gss_seal ( + OM_uint32 * minor_status, + gss_ctx_id_t context_handle, + int conf_req_flag, + int qop_req + gss_buffer_t input_message_buffer, + int * conf_state, + gss_buffer_t output_message_buffer) + + Purpose: + + Cryptographically signs and optionally encrypts the specified + input_message. The output_message contains both the signature and + the message. The qop_req parameter allows a choice between several + cryptographic algorithms, if supported by the chosen mechanism. + + Parameters: + + minor_status integer, modify + Mechanism specific status code. + + context_handle gss_ctx_id_t, read + identifies the context on which the message + will be sent + + conf_req_flag boolean, read + True - Both confidentiality and integrity + services are requested + False - Only integrity service is requested + + qop_req integer, read, optional + Specifies required quality of protection. A + mechanism-specific default may be requested by + setting qop_req to GSS_C_QOP_DEFAULT. If an + unsupported protection strength is requested, + gss_seal will return a major_status of + GSS_S_FAILURE. + + input_message_buffer buffer, opaque, read + message to be sealed + + + + +Wray [Page 30] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + conf_state boolean, modify + True - Confidentiality, data origin + authentication and integrity services + have been applied + False - Integrity and data origin services only + has been applied. + + output_message_buffer buffer, opaque, modify + buffer to receive sealed message + + Function value: + + GSS status code: + + GSS_S_COMPLETE Successful completion + + GSS_S_CONTEXT_EXPIRED The context has already expired + + GSS_S_CREDENTIALS_EXPIRED The context is recognized, but + associated credentials have expired + + GSS_S_NO_CONTEXT The context_handle parameter did not identify a + valid context + + GSS_S_FAILURE Failure. See minor_status for more information. + +3.11. gss_unseal + + OM_uint32 gss_unseal ( + OM_uint32 * minor_status, + gss_ctx_id_t context_handle, + gss_buffer_t input_message_buffer, + gss_buffer_t output_message_buffer, + int * conf_state, + int * qop_state) + + Purpose: + + Converts a previously sealed message back to a usable form, verifying + the embedded signature. The conf_state parameter indicates whether + the message was encrypted; the qop_state parameter indicates the + strength of protection that was used to provide the confidentiality + and integrity services. + + Parameters: + + minor_status integer, modify + Mechanism specific status code. + + + +Wray [Page 31] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + context_handle gss_ctx_id_t, read + identifies the context on which the message + arrived + + input_message_buffer buffer, opaque, read + sealed message + + output_message_buffer buffer, opaque, modify + buffer to receive unsealed message + + conf_state boolean, modify + True - Confidentiality and integrity protection + were used + False - Inteegrity service only was used + + qop_state integer, modify + quality of protection gained from signature + + Function value: + + GSS status code: + + GSS_S_COMPLETE Successful completion + + GSS_S_DEFECTIVE_TOKEN The token failed consistency checks + + GSS_S_BAD_SIG The signature was incorrect + + GSS_S_DUPLICATE_TOKEN The token was valid, and contained a + correct signature for the message, but it had + already been processed + + GSS_S_OLD_TOKEN The token was valid, and contained a correct + signature for the message, but it is too old + + GSS_S_UNSEQ_TOKEN The token was valid, and contained a correct + signature for the message, but has been + verified out of sequence; an earlier token has + been signed or sealed by the remote + application, but not yet been processed + locally. + + GSS_S_CONTEXT_EXPIRED The context has already expired + + GSS_S_CREDENTIALS_EXPIRED The context is recognized, but + associated credentials have expired + + + + + +Wray [Page 32] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + GSS_S_NO_CONTEXT The context_handle parameter did not identify a + valid context + + GSS_S_FAILURE Failure. See minor_status for more information. + +3.12. gss_display_status + + OM_uint32 gss_display_status ( + OM_uint32 * minor_status, + int status_value, + int status_type, + gss_OID mech_type, + int * message_context, + gss_buffer_t status_string) + + Purpose: + + Allows an application to obtain a textual representation of a GSSAPI + status code, for display to the user or for logging purposes. Since + some status values may indicate multiple errors, applications may + need to call gss_display_status multiple times, each call generating + a single text string. The message_context parameter is used to + indicate which error message should be extracted from a given + status_value; message_context should be initialized to 0, and + gss_display_status will return a non-zero value if there are further + messages to extract. + + Parameters: + + minor_status integer, modify + Mechanism specific status code. + + status_value integer, read + Status value to be converted + + status_type integer, read + GSS_C_GSS_CODE - status_value is a GSS status + code + GSS_C_MECH_CODE - status_value is a mechanism + status code + + mech_type Object ID, read, optional + Underlying mechanism (used to interpret a + minor status value) Supply GSS_C_NULL_OID to + obtain the system default. + + message_context integer, read/modify + Should be initialized to zero by caller + + + +Wray [Page 33] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + on first call. If further messages are + contained in the status_value parameter, + message_context will be non-zero on return, + and this value should be passed back to + subsequent calls, along with the same + status_value, status_type and mech_type + parameters. + + status_string buffer, character string, modify + textual interpretation of the status_value + + Function value: + + GSS status code: + + GSS_S_COMPLETE Successful completion + + GSS_S_BAD_MECH Indicates that translation in accordance with + an unsupported mechanism type was requested + + GSS_S_BAD_STATUS The status value was not recognized, or the + status type was neither GSS_C_GSS_CODE nor + GSS_C_MECH_CODE. + + +3.13. gss_indicate_mechs + + OM_uint32 gss_indicate_mechs ( + OM_uint32 * minor_status, + gss_OID_set * mech_set) + + Purpose: + + Allows an application to determine which underlying security + mechanisms are available. + + Parameters: + + minor_status integer, modify + Mechanism specific status code. + + mech_set set of Object IDs, modify + set of implementation-supported mechanisms. + The returned gss_OID_set value will be a + pointer into static storage, and should be + treated as read-only by the caller. + + + + + +Wray [Page 34] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + Function value: + + GSS status code: + + GSS_S_COMPLETE Successful completion + +3.14. gss_compare_name + + OM_uint32 gss_compare_name ( + OM_uint32 * minor_status, + gss_name_t name1, + gss_name_t name2, + int * name_equal) + + Purpose: + + Allows an application to compare two internal-form names to determine + whether they refer to the same entity. + + Parameters: + + minor_status integer, modify + Mechanism specific status code. + + name1 gss_name_t, read + internal-form name + + name2 gss_name_t, read + internal-form name + + name_equal boolean, modify + True - names refer to same entity + False - names refer to different entities + (strictly, the names are not known to + refer to the same identity). + Function value: + + GSS status code: + + GSS_S_COMPLETE Successful completion + + GSS_S_BAD_NAMETYPE The type contained within either name1 or + name2 was unrecognized, or the names were of + incomparable types. + + GSS_S_BAD_NAME One or both of name1 or name2 was ill-formed + + + + + +Wray [Page 35] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + +3.15. gss_display_name + + OM_uint32 gss_display_name ( + OM_uint32 * minor_status, + gss_name_t input_name, + gss_buffer_t output_name_buffer, + gss_OID * output_name_type) + + Purpose: + + Allows an application to obtain a textual representation of an opaque + internal-form name for display purposes. The syntax of a printable + name is defined by the GSSAPI implementation. + + Parameters: + + minor_status integer, modify + Mechanism specific status code. + + input_name gss_name_t, read + name to be displayed + + output_name_buffer buffer, character-string, modify + buffer to receive textual name string + + output_name_type Object ID, modify + The type of the returned name. The returned + gss_OID will be a pointer into static storage, + and should be treated as read-only by the caller + + Function value: + + GSS status code: + + GSS_S_COMPLETE Successful completion + + GSS_S_BAD_NAMETYPE The type of input_name was not recognized + + GSS_S_BAD_NAME input_name was ill-formed + +3.16. gss_import_name + + OM_uint32 gss_import_name ( + OM_uint32 * minor_status, + gss_buffer_t input_name_buffer, + gss_OID input_name_type, + gss_name_t * output_name) + + + + +Wray [Page 36] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + Purpose: + + Convert a printable name to internal form. + + Parameters: + + minor_status integer, modify + Mechanism specific status code + + input_name_buffer buffer, character-string, read + buffer containing printable name to convert + + input_name_type Object ID, read, optional + Object Id specifying type of printable + name. Applications may specify either + GSS_C_NULL_OID to use a local system-specific + printable syntax, or an OID registered by the + GSSAPI implementation to name a particular + namespace. + + output_name gss_name_t, modify + returned name in internal form + + Function value: + + GSS status code + + GSS_S_COMPLETE Successful completion + + GSS_S_BAD_NAMETYPE The input_name_type was unrecognized + + GSS_S_BAD_NAME The input_name parameter could not be + interpreted as a name of the specified type + +3.17. gss_release_name + + OM_uint32 gss_release_name ( + OM_uint32 * minor_status, + gss_name_t * name) + + Purpose: + + Free GSSAPI-allocated storage associated with an internal form name. + + Parameters: + + minor_status integer, modify + Mechanism specific status code + + + +Wray [Page 37] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + name gss_name_t, modify + The name to be deleted + + Function value: + + GSS status code + + GSS_S_COMPLETE Successful completion + + GSS_S_BAD_NAME The name parameter did not contain a valid name + +3.18. gss_release_buffer + + OM_uint32 gss_release_buffer ( + OM_uint32 * minor_status, + gss_buffer_t buffer) + + Purpose: + + Free storage associated with a buffer format name. The storage must + have been allocated by a GSSAPI routine. In addition to freeing the + associated storage, the routine will zero the length field in the + buffer parameter. + + Parameters: + + minor_status integer, modify + Mechanism specific status code + + buffer buffer, modify + The storage associated with the buffer will be + deleted. The gss_buffer_desc object will not + be freed, but its length field will be zeroed. + + Function value: + + GSS status code + + GSS_S_COMPLETE Successful completion + +3.19. gss_release_oid_set + + OM_uint32 gss_release_oid_set ( + OM_uint32 * minor_status, + gss_OID_set * set) + + Purpose: + + + + +Wray [Page 38] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + Free storage associated with a gss_OID_set object. The storage must + have been allocated by a GSSAPI routine. + + Parameters: + + minor_status integer, modify + Mechanism specific status code + + set Set of Object IDs, modify + The storage associated with the gss_OID_set + will be deleted. + + Function value: + + GSS status code + + GSS_S_COMPLETE Successful completion + +3.20. gss_inquire_cred + + OM_uint32 gss_inquire_cred ( + OM_uint32 * minor_status, + gss_cred_id_t cred_handle, + gss_name_t * name, + OM_uint32 * lifetime, + int * cred_usage, + gss_OID_set * mechanisms ) + + Purpose: + + Obtains information about a credential. The caller must already have + obtained a handle that refers to the credential. + + Parameters: + + minor_status integer, modify + Mechanism specific status code + + cred_handle gss_cred_id_t, read + A handle that refers to the target credential. + Specify GSS_C_NO_CREDENTIAL to inquire about + the default credential. + + name gss_name_t, modify + The name whose identity the credential asserts. + Specify NULL if not required. + + lifetime Integer, modify + + + +Wray [Page 39] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + The number of seconds for which the credential + will remain valid. If the credential has + expired, this parameter will be set to zero. + If the implementation does not support + credential expiration, the value + GSS_C_INDEFINITE will be returned. Specify + NULL if not required. + + cred_usage Integer, modify + How the credential may be used. One of the + following: + GSS_C_INITIATE + GSS_C_ACCEPT + GSS_C_BOTH + Specify NULL if not required. + + mechanisms gss_OID_set, modify + Set of mechanisms supported by the credential. + Specify NULL if not required. + + Function value: + + GSS status code + + GSS_S_COMPLETE Successful completion + + GSS_S_NO_CRED The referenced credentials could not be + accessed. + + GSS_S_DEFECTIVE_CREDENTIAL The referenced credentials were + invalid. + + GSS_S_CREDENTIALS_EXPIRED The referenced credentials have expired. + If the lifetime parameter was not passed as + NULL, it will be set to 0. + + + #ifndef GSSAPI_H_ + #define GSSAPI_H_ + + /* + * First, define the platform-dependent types. + */ + typedef <platform-specific> OM_uint32; + typedef <platform-specific> gss_ctx_id_t; + typedef <platform-specific> gss_cred_id_t; + typedef <platform-specific> gss_name_t; + + + + +Wray [Page 40] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + /* + * Note that a platform supporting the xom.h X/Open header file + * may make use of that header for the definitions of OM_uint32 + * and the structure to which gss_OID_desc equates. + */ + + typedef struct gss_OID_desc_struct { + OM_uint32 length; + void *elements; + } gss_OID_desc, *gss_OID; + + typedef struct gss_OID_set_desc_struct { + int count; + gss_OID elements; + } gss_OID_set_desc, *gss_OID_set; + + typedef struct gss_buffer_desc_struct { + size_t length; + void *value; + } gss_buffer_desc, *gss_buffer_t; + + typedef struct gss_channel_bindings_struct { + OM_uint32 initiator_addrtype; + gss_buffer_desc initiator_address; + OM_uint32 acceptor_addrtype; + gss_buffer_desc acceptor_address; + gss_buffer_desc application_data; + } *gss_channel_bindings_t; + + + /* + * Six independent flags each of which indicates that a context + * supports a specific service option. + */ + #define GSS_C_DELEG_FLAG 1 + #define GSS_C_MUTUAL_FLAG 2 + #define GSS_C_REPLAY_FLAG 4 + #define GSS_C_SEQUENCE_FLAG 8 + #define GSS_C_CONF_FLAG 16 + #define GSS_C_INTEG_FLAG 32 + + + /* + * Credential usage options + */ + #define GSS_C_BOTH 0 + #define GSS_C_INITIATE 1 + #define GSS_C_ACCEPT 2 + + + +Wray [Page 41] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + /* + * Status code types for gss_display_status + */ + #define GSS_C_GSS_CODE 1 + #define GSS_C_MECH_CODE 2 + + /* + * The constant definitions for channel-bindings address families + */ + #define GSS_C_AF_UNSPEC 0; + #define GSS_C_AF_LOCAL 1; + #define GSS_C_AF_INET 2; + #define GSS_C_AF_IMPLINK 3; + #define GSS_C_AF_PUP 4; + #define GSS_C_AF_CHAOS 5; + #define GSS_C_AF_NS 6; + #define GSS_C_AF_NBS 7; + #define GSS_C_AF_ECMA 8; + #define GSS_C_AF_DATAKIT 9; + #define GSS_C_AF_CCITT 10; + #define GSS_C_AF_SNA 11; + #define GSS_C_AF_DECnet 12; + #define GSS_C_AF_DLI 13; + #define GSS_C_AF_LAT 14; + #define GSS_C_AF_HYLINK 15; + #define GSS_C_AF_APPLETALK 16; + #define GSS_C_AF_BSC 17; + #define GSS_C_AF_DSS 18; + #define GSS_C_AF_OSI 19; + #define GSS_C_AF_X25 21; + + #define GSS_C_AF_NULLADDR 255; + + #define GSS_C_NO_BUFFER ((gss_buffer_t) 0) + #define GSS_C_NULL_OID ((gss_OID) 0) + #define GSS_C_NULL_OID_SET ((gss_OID_set) 0) + #define GSS_C_NO_CONTEXT ((gss_ctx_id_t) 0) + #define GSS_C_NO_CREDENTIAL ((gss_cred_id_t) 0) + #define GSS_C_NO_CHANNEL_BINDINGS ((gss_channel_bindings_t) 0) + #define GSS_C_EMPTY_BUFFER {0, NULL} + + /* + * Define the default Quality of Protection for per-message + * services. Note that an implementation that offers multiple + * levels of QOP may either reserve a value (for example zero, + * as assumed here) to mean "default protection", or alternatively + * may simply equate GSS_C_QOP_DEFAULT to a specific explicit QOP + * value. + + + +Wray [Page 42] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + */ + #define GSS_C_QOP_DEFAULT 0 + + /* + * Expiration time of 2^32-1 seconds means infinite lifetime for a + * credential or security context + */ + #define GSS_C_INDEFINITE 0xfffffffful + + + /* Major status codes */ + + #define GSS_S_COMPLETE 0 + + /* + * Some "helper" definitions to make the status code macros obvious. + */ + #define GSS_C_CALLING_ERROR_OFFSET 24 + #define GSS_C_ROUTINE_ERROR_OFFSET 16 + #define GSS_C_SUPPLEMENTARY_OFFSET 0 + #define GSS_C_CALLING_ERROR_MASK 0377ul + #define GSS_C_ROUTINE_ERROR_MASK 0377ul + #define GSS_C_SUPPLEMENTARY_MASK 0177777ul + + /* + * The macros that test status codes for error conditions + */ + #define GSS_CALLING_ERROR(x) \ + (x & (GSS_C_CALLING_ERROR_MASK << GSS_C_CALLING_ERROR_OFFSET)) + #define GSS_ROUTINE_ERROR(x) \ + (x & (GSS_C_ROUTINE_ERROR_MASK << GSS_C_ROUTINE_ERROR_OFFSET)) + #define GSS_SUPPLEMENTARY_INFO(x) \ + (x & (GSS_C_SUPPLEMENTARY_MASK << GSS_C_SUPPLEMENTARY_OFFSET)) + #define GSS_ERROR(x) \ + ((GSS_CALLING_ERROR(x) != 0) || (GSS_ROUTINE_ERROR(x) != 0)) + + + /* + * Now the actual status code definitions + */ + + /* + * Calling errors: + */ + #define GSS_S_CALL_INACCESSIBLE_READ \ + (1ul << GSS_C_CALLING_ERROR_OFFSET) + #define GSS_S_CALL_INACCESSIBLE_WRITE \ + (2ul << GSS_C_CALLING_ERROR_OFFSET) + + + +Wray [Page 43] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + #define GSS_S_CALL_BAD_STRUCTURE \ + (3ul << GSS_C_CALLING_ERROR_OFFSET) + + /* + * Routine errors: + */ + #define GSS_S_BAD_MECH (1ul << GSS_C_ROUTINE_ERROR_OFFSET) + #define GSS_S_BAD_NAME (2ul << GSS_C_ROUTINE_ERROR_OFFSET) + #define GSS_S_BAD_NAMETYPE (3ul << GSS_C_ROUTINE_ERROR_OFFSET) + #define GSS_S_BAD_BINDINGS (4ul << GSS_C_ROUTINE_ERROR_OFFSET) + #define GSS_S_BAD_STATUS (5ul << GSS_C_ROUTINE_ERROR_OFFSET) + #define GSS_S_BAD_SIG (6ul << GSS_C_ROUTINE_ERROR_OFFSET) + #define GSS_S_NO_CRED (7ul << GSS_C_ROUTINE_ERROR_OFFSET) + #define GSS_S_NO_CONTEXT (8ul << GSS_C_ROUTINE_ERROR_OFFSET) + #define GSS_S_DEFECTIVE_TOKEN (9ul << GSS_C_ROUTINE_ERROR_OFFSET) + #define GSS_S_DEFECTIVE_CREDENTIAL (10ul << GSS_C_ROUTINE_ERROR_OFFSET) + #define GSS_S_CREDENTIALS_EXPIRED (11ul << GSS_C_ROUTINE_ERROR_OFFSET) + #define GSS_S_CONTEXT_EXPIRED (12ul << GSS_C_ROUTINE_ERROR_OFFSET) + #define GSS_S_FAILURE (13ul << GSS_C_ROUTINE_ERROR_OFFSET) + + /* + * Supplementary info bits: + */ + #define GSS_S_CONTINUE_NEEDED (1ul << (GSS_C_SUPPLEMENTARY_OFFSET + 0)) + #define GSS_S_DUPLICATE_TOKEN (1ul << (GSS_C_SUPPLEMENTARY_OFFSET + 1)) + #define GSS_S_OLD_TOKEN (1ul << (GSS_C_SUPPLEMENTARY_OFFSET + 2)) + #define GSS_S_UNSEQ_TOKEN (1ul << (GSS_C_SUPPLEMENTARY_OFFSET + 3)) + + + /* + * Finally, function prototypes for the GSSAPI routines. + */ + + OM_uint32 gss_acquire_cred + (OM_uint32*, /* minor_status */ + gss_name_t, /* desired_name */ + OM_uint32, /* time_req */ + gss_OID_set, /* desired_mechs */ + int, /* cred_usage */ + gss_cred_id_t*, /* output_cred_handle */ + gss_OID_set*, /* actual_mechs */ + OM_uint32* /* time_rec */ + ); + + OM_uint32 gss_release_cred, + (OM_uint32*, /* minor_status */ + gss_cred_id_t* /* cred_handle */ + ); + + + +Wray [Page 44] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + OM_uint32 gss_init_sec_context + (OM_uint32*, /* minor_status */ + gss_cred_id_t, /* claimant_cred_handle */ + gss_ctx_id_t*, /* context_handle */ + gss_name_t, /* target_name */ + gss_OID, /* mech_type */ + int, /* req_flags */ + OM_uint32, /* time_req */ + gss_channel_bindings_t, + /* input_chan_bindings */ + gss_buffer_t, /* input_token */ + gss_OID*, /* actual_mech_type */ + gss_buffer_t, /* output_token */ + int*, /* ret_flags */ + OM_uint32* /* time_rec */ + ); + + OM_uint32 gss_accept_sec_context + (OM_uint32*, /* minor_status */ + gss_ctx_id_t*, /* context_handle */ + gss_cred_id_t, /* verifier_cred_handle */ + gss_buffer_t, /* input_token_buffer */ + gss_channel_bindings_t, + /* input_chan_bindings */ + gss_name_t*, /* src_name */ + gss_OID*, /* mech_type */ + gss_buffer_t, /* output_token */ + int*, /* ret_flags */ + OM_uint32*, /* time_rec */ + gss_cred_id_t* /* delegated_cred_handle */ + ); + + OM_uint32 gss_process_context_token + (OM_uint32*, /* minor_status */ + gss_ctx_id_t, /* context_handle */ + gss_buffer_t /* token_buffer */ + ); + + OM_uint32 gss_delete_sec_context + (OM_uint32*, /* minor_status */ + gss_ctx_id_t*, /* context_handle */ + gss_buffer_t /* output_token */ + ); + + + + + + + + +Wray [Page 45] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + OM_uint32 gss_context_time + (OM_uint32*, /* minor_status */ + gss_ctx_id_t, /* context_handle */ + OM_uint32* /* time_rec */ + ); + + OM_uint32 gss_sign + (OM_uint32*, /* minor_status */ + gss_ctx_id_t, /* context_handle */ + int, /* qop_req */ + gss_buffer_t, /* message_buffer */ + gss_buffer_t /* message_token */ + ); + + OM_uitn32 gss_verify + (OM_uint32*, /* minor_status */ + gss_ctx_id_t, /* context_handle */ + gss_buffer_t, /* message_buffer */ + gss_buffer_t, /* token_buffer */ + int* /* qop_state */ + ); + + OM_uint32 gss_seal + (OM_uint32*, /* minor_status */ + gss_ctx_id_t, /* context_handle */ + int, /* conf_req_flag */ + int, /* qop_req */ + gss_buffer_t, /* input_message_buffer */ + int*, /* conf_state */ + gss_buffer_t /* output_message_buffer */ + ); + + OM_uint32 gss_unseal + (OM_uint32*, /* minor_status */ + gss_ctx_id_t, /* context_handle */ + gss_buffer_t, /* input_message_buffer */ + gss_buffer_t, /* output_message_buffer */ + int*, /* conf_state */ + int* /* qop_state */ + ); + + + + + + + + + + + +Wray [Page 46] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + OM_uint32 gss_display_status + (OM_uint32*, /* minor_status */ + OM_uint32, /* status_value */ + int, /* status_type */ + gss_OID, /* mech_type */ + int*, /* message_context */ + gss_buffer_t /* status_string */ + ); + + OM_uint32 gss_indicate_mechs + (OM_uint32*, /* minor_status */ + gss_OID_set* /* mech_set */ + ); + + OM_uint32 gss_compare_name + (OM_uint32*, /* minor_status */ + gss_name_t, /* name1 */ + gss_name_t, /* name2 */ + int* /* name_equal */ + ); + + OM_uint32 gss_display_name, + (OM_uint32*, /* minor_status */ + gss_name_t, /* input_name */ + gss_buffer_t, /* output_name_buffer */ + gss_OID* /* output_name_type */ + ); + + OM_uint32 gss_import_name + (OM_uint32*, /* minor_status */ + gss_buffer_t, /* input_name_buffer */ + gss_OID, /* input_name_type */ + gss_name_t* /* output_name */ + ); + + OM_uint32 gss_release_name + (OM_uint32*, /* minor_status */ + gss_name_t* /* input_name */ + ); + + OM_uint32 gss_release_buffer + (OM_uint32*, /* minor_status */ + gss_buffer_t /* buffer */ + ); + + OM_uint32 gss_release_oid_set + (OM_uint32*, /* minor_status */ + gss_OID_set* /* set */ + + + +Wray [Page 47] + +RFC 1509 GSSAPI - Overview and C bindings September 1993 + + + ); + + OM_uint32 gss_inquire_cred + (OM_uint32 *, /* minor_status */ + gss_cred_id_t, /* cred_handle */ + gss_name_t *, /* name */ + OM_uint32 *, /* lifetime */ + int *, /* cred_usage */ + gss_OID_set * /* mechanisms */ + ); + + + + #endif /* GSSAPI_H_ */ + +References + + [1] Linn, J., "Generic Security Service Application Program + Interface", RFC 1508, Geer Zolot Associate, September 1993. + + [2] "OSI Object Management API Specification, Version 2.0 t", X.400 + API Association & X/Open Company Limited, August 24, 1990. + Specification of datatypes and routines for manipulating + information objects. + +Security Considerations + + Security issues are discussed throughout this memo. + +Author's Address + + John Wray + Digital Equipment Corporation + 550 King Street, LKG2-2/AA6 + Littleton, MA 01460 + USA + + Phone: +1-508-486-5210 + EMail: Wray@tuxedo.enet.dec.com + + + + + + + + + + + + +Wray [Page 48] +
\ No newline at end of file |
