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 synchronizat