| OSF DCE SIG | J. Wray (DEC) | |
| Request For Comments: 5.2 | March 1994 |
Several standards activities based on the Generic Security Service Application Program Interface (GSS-API) are currently underway or under consideration:
There appears to be relatively general acceptance of GSS-API within its present scope of establishing security contexts, performing peer-entity authentication, and yielding shared keys for use in integrity and confidentiality protection of data messages. Many of the activities listed above desire extensions to support authorization features (e.g., indication of group affiliations or other attributes) over and above pure authentication of principal names. We expect to proceed with standards advancement of the current specification, and to position added authorization features as optional extensions for certain environments.
This section defines the specific GSS-API extensions being proposed to OSF for implementation and incorporation within DCE V1.1. In addition to the routines described herein, the complete base GSS-API, as defined in Internet RFCs 1508 and 1509, will be implemented. Specific issues to be resolved in the course of implementing GSS-API over the DCE security mechanism are also identified.
The DCE GSS-API is oriented to the DCE 1.1 operational paradigm in which credentials (represented by chained EPACs) are opaque objects from the viewpoint of applications, and their contents are interpreted within ACL managers which access the data stored within credentials through the new sec_cred_* interrogation interface.
The goal of the DCE GSS-API is to provide non-RPC applications operating within a DCE environment the ability to use the DCE Shared-Secret authentication protocol (and, in future, other authentication protocols) via the GSS-API, and to make use of the DCE Authorization protocol in addition to Name-Based Authorization as supported through the existing GSS-API. This support is intended to afford such applications security features and integration paradigms which are analagous to those which DCE currently affords to RPC-based applications. There is no intent that DCE RPC runtimes will be restructured so as to layer atop GSS-API. Applications making use of the proposed extension will not be portable to non-DCE authorization support environments; received DCE credentials are not assumed to be interpretable by arbitrary non-DCE ACL managers.
This work does not extend the scope of GSS-API to incorporate login functions; currently specified DCE 1.1 "sec_login_*" primitives remain unchanged. This group of DCE primitives includes functions which create a login context, allow a variant login context to be created designating a subset of group memberships or other permissible registry attributes, to annotate login contexts with delegation restrictions, and to import and export login contexts among processes.
DCE login contexts correspond roughly to GSS-API INITIATE-type credentials, and should not be confused with GSS-API security contexts which are pairwise security associations between peers. Conceptually, credentials structures are paired with corresponding login contexts, so that, e.g., a modification to a DCE login context will affect subsequent references to the associated GSS-API credentials. Caller references to default GSS-API credentials for security-context initiation will correspond to the current DCE login context; a gssdce_login_context_to_cred() call is defined for use by those callers (probably to be in the minority) which need to select among alternative credentials sets. Further, already-defined GSS-API per-message primitives can enable applications to protect their transferred data with integrity and confidentiality services.
In use, the GSS-API routines themselves do not generate network traffic (or interprocess communication of any sort) between communicating peer applications. It is true that GSS-API routines typically do generate some network traffic in order to acquire authentication tokens to return to their calling application, but such network traffic is targeted to some sort of "token authority" (depending on the implementation), not to the calling application's communicating peer. It is the responsibility of the calling application itself to encapsulate the returned tokens within a communications protocol, and transfer them to the communicating peer.
In the case of DCE, the token authority from which authentication tokens are acquired is DCE's authentication service (working in concert with DCE's privilege and registry services), as embodied in the DCE security daemon ("secd"). Therefore, the DCE 1.1 GSS-API implementation will acquire its tokens using the existing DCE RPC interfaces to secd.
Note that token acquisition is not the only place that GSS-API might generate network traffic (for example, to translate between names and UUID's, or to create security contexts). The exact places network traffic will get generated can be a bit unpredictable, since both the GSS-API implementation and DCE security use a fair amount of caching. In any case, wherever such network traffic is generated by the DCE GSS-API implementation, it will be done via existing DCE RPC interfaces.
This subsection defines the extension GSS-API primitives to be added for DCE support. These routines will be provided in addition to all routines defined in the GSS-API base specification (Internet RFCs 1508 and 1509).
This routine is used by a context acceptor to extract the client DCE credentials (if any) representing the privilege attributes of the security context's initiator. The security context's initiator may be acting on its own behalf, or it may be acting as a delegate for a third party. Credentials will be transferred as elements of the context establishment tokens; the gssdce_extract_creds_from_sec_context() primitive should not be invoked until context establishment is complete.
Inputs:
Outputs:
Return major_status codes:
This routine is used by a context peer to extract the DCE credentials (if any) representing the privilege attributes of the original intiator of a GSSAPI credentials structure. It is typically used in a delegation environment by a context acceptor wishing to determine the identity of the client on whose behalf the acceptor would authenticate were the GSSAPI credential used to initiate a security context. It can also be used to obtain the identity and rights of the originator principal of any credential suitable for initiating security contexts.
Inputs:
Outputs:
Return major_status codes:
This call, a variant of the GSS-API gss_acquire_cred() call, is provided for use by those callers who need, through an explicit GSS-API credential handle, to make use of GSS-API credentials sets corresponding to other than their current DCE login context. gss_acquire_cred cannot be used in a DCE environment to create INITIATE-type credentials for any identity other than that associated with the process' default login context, since DCE provides no way for GSS-API to search a process' available login-contexts by principal name.
The desired_mechs input parameter allows callers to request credentials suitable for use with a Kerberos V5 mechanism as well as with the DCE Security mechanism.
Inputs:
Outputs:
Return major_status codes:
This routine makes it possible to obtain a reference to the DCE login context on which a GSS-API credential, suitable for initiating security contexts, is based. The primary use of this call will be to enable the recipients of delegations via GSS-API to make use of the delegated rights in subsequent operations (e.g., DCE RPC) which are based on login contexts rather than credential handles, to add further delegation restrictions to a delegated login-context, or for interrogation using the sec_cred_ primitives.
Inputs:
Outputs:
Return major_status codes:
This routine corresponds to the rpc_server_register_auth_info routine (and is in fact merely a jacket to that routine). It allows a GSS-API context-acceptor to specify the use of alternate keytables for constructing credentials suitable for accepting security contexts, or for expanding the scope of the default acceptor credential.
Inputs:
Outputs:
Return major_status codes:
This is a convenience routine for deallocating memory associated with ISO Object Identifier (OID) values. GSS-API uses OID values for naming security mechanisms and name-types. This routine deallocates (via free()) the storage associated with such OIDs, except for those OID values that are supplied as constants with the GSS-API implementation (for which it becomes a no-op). Thus an application may safely mix its own OID values with the constant OIDs supplied by GSS-API.
Inputs:
Outputs:
Return major_status codes:
This is a convenience routine that creates an empty set of Object Identifiers. Object Identifier sets are used by GSS-API to name sets of security mechanisms. This routine is intended to be used in conjunction with the gssdce_add_oid_set_member routine, to construct sets of desired security mechanisms for input to gss_acquire_cred or gssdce_login_context_to_cred.
Inputs: none.
Outputs:
Return major_status codes:
This is a convenience routine that adds a specified Object Identifier to a set of object identifiers. Object Identifier sets are used by GSS-API to name sets of security mechanisms. This routine is intended to be used in conjunction with the gssdce_create_empty_oid_set routine, to construct sets of desired security mechanisms for input to gss_acquire_cred or gssdce_login_context_to_cred.
Inputs:
Outputs:
Return major_status codes:
This is a convenience routine that determines whether a specified Object Identifier is a member of a set of Object Identifiers. Object Identifier sets are used by GSS-API to name sets of security mechanisms. This routine is may be used after the gss_acquire_cred or gss_login_context_to_cred routines have been called, to determine which security mechanisms are supported by the resultant credential.
Inputs:
Outputs:
Return major_status codes:
This section lists the functions performed by each of the GSS-API DCE extension routines and discusses their major parameters, describing how they are to be passed to the routines. The routines are listed below:
Extract a DCE credentials object from a GSS-API security context.
Extract DCE credentials from a GSS-API credential.
Construct a GSS-API credential from a DCE login context.
Construct a DCE login context from a GSS-API credential.
Specify a DCE keytable to be used for accepting contexts under a specified name.
Convenience routine. Deallocate storage associated with an Object Identifer.
Convenience routine. Create an Object Identifier set containing no elements.
Convenience routine. Add a specified Object Identifier to a set of Object Identifiers.
Convenience routine. Determine whether a specified Object Identifier is contained in a set.
The same conventions are adopted by the extension routines as are used by the base GSS-API routines. These conventions are discussed in [GSSAPI-C]. The only point of note here is that the IETF C bindings specify 32-bit unsigned data using the OM_uint32 datatype, defined by the X/Open Object Management header file, whereas the DCE convention is to use the unsigned32 datatype. Since the two types are equivalent, the DCE GSS-API bindings follow the IETF convention. Similarly, the IETF GSS-API bindings use OM_uint32 to represent mechanism-specific status codes, whereas DCE convention is to use the error_status_t type. Again, since error_status_t is equivalent to unsigned32, the DCE GSS-API may follow the IETF specification, while remaining compatible with DCE conventions. The actual values of DCE GSS-API status codes are generated by the SMS message utility.
The following OID shall be used to represent the GSS-API mechanism-type "DCE-security with Kerberos V5 with DES":
This shall also be the default mechanism-type.
Additionally, the following OID shall represent the GSS-API mechanism-type "Kerberos V5 with DES":
The actual value of this OID will be the same as the OID already assigned to indicate GSS-API over Kerberos V5. The OID represents the value:
The following OIDs shall be used to represent the GSS-API name-type "DCE principal name":
This shall also be the default name-type; no other name-types will be supported.
Purpose: Extract DCE credentials from a GSS-API security context. This call is intended for use by a context acceptor, and the returned credentials object contains the privilege attibutes of the context initiator and delegation chain (if any). If the context was established using the Kerberos mechanism type, this call will return a major status of GSS_FAILURE and a minor status indicating no credentials are available.
Synopsis:
OM_uint32
gssdce_extract_creds_from_sec_context (
OM_uint32 *minor_status,
gss_ctx_id_t context_handle,
rpc_authz_cred_handle_t *output_creds );
Parameters:
Function value (GSS status code):
Purpose: Extract DCE credentials from a GSS-API credential. This call extracts privilege attribute information concerning the originator principal described by the credential. Since an initiating process may obtain its own DCE credentials from its login context (via the sec_login_cred_get_initiator routine), this call is primarily intended to be invoked by context acceptors wishing to determine the originator principal of a delegated credential.
Synopsis:
OM_uint32
gssdce_extract_creds_from_cred (
OM_uint32 *minor_status,
gss_cred_id_t cred_handle,
sec_cred_pa_handle_t *output_creds );
Parameters:
Function value (GSS status code):
Purpose: Create a GSS-API credential handle from a DCE login context. This routine will always create a credential suitable for initiating a security context. If a credential of usage-type "ACCEPT" or "BOTH" is desired, it may be created by a call to gssdce_register_acceptor_identity (not required if the key is stored in the default keytable), followed by a call to gss_acquire_cred to convert the key into a GSS-API credential.
Synopsis:
OM_uint32
gssdce_login_context_to_cred (
OM_uint32 *minor_status,
sec_login_handle_t login_context,
OM_uint32 lifetime_req,
gss_OID_set desired_mechs,
gss_cred_id_t *output_cred_handle,
gss_OID_set *actual_mechs,
OM_uint32 lifetime_rec );
Parameters:
Function value (GSS status code):
Purpose: Obtain the DCE login context associated with a GSS-API credential.
Synopsis:
OM_uint32
gssdce_cred_to_login_context (
OM_uint32 *minor_status,
gss_cred_id_t cred_handle,
sec_login_handle_t *output_login_context );
Parameters:
Function value (GSS status code):
Purpose: Associate a keytable with a context-acceptor principal name.
Synopsis:
OM_uint32
gssdce_register_acceptor_identity (
OM_uint32 *minor_status,
gss_name_t server_principal_name,
rpc_auth_key_retrieval_fn_t get_key_fn,
void *arg );
Parameters:
Purpose: Discard storage associated with an OID, unless the OID is one of the supplied GSS-API constant OIDs.
Synopsis:
OM_int32
gssdce_release_oid (
OM_uint3 *minor_status,
gss_OID *oid );
Parameters:
Function value (GSS status code):
Purpose: Create an OID set with no members.
Synopsis:
OM_uint32
gssdce_create_empty_oid_set (
OM_uint32 *minor_status,
gss_OID_set *OID_set );
Parameters:
Function value (GSS status code):
Purpose: Add an OID value to an OID set.
Synopsis:
OM_uint32
gssdce_add_oid_set_member (
OM_uint32 *minor_status,
gss_OID member_OID,
gss_OID_set *OID_set );
Parameters:
Function value (GSS status code):
Purpose: Determine whether a specified OID is a member of an OID set.
Synopsis:
OM_uint32
gssdce_test_oid_set_member (
OM_uint32 *minor_status,
gss_OID member_OID,
gss_OID_set OID_set,
int *present );
Parameters:
Function value (GSS status code):
| John Wray | Internet email: wray@tuxedo.enet.dec.com | |
| Digital Equipment Corporation | Telephone: +1-508-486-5210 | |
| 550 King Street, LKG2-2/Z7 | ||
| Littleton, MA 01460 | ||
| USA |