Internet-Draft
Tom Parker , ICL
Denis Pinkas , Bull
IETF Common Authentication Technology WG
<draft-ietf-cat-xgssapi-acc-cntrl-02.txt> March 25, 1997
Extended Generic Security Service APIs: XGSS-APIs
Access control and delegation extensions
1. STATUS OF THIS MEMO
This document is an Internet Draft. Internet Drafts are working
documents of the Internet Engineering Task Force (IETF), its Areas,
and its Working Groups. Note that other groups may also distribute
working documents as Internet Drafts. Internet Drafts are draft
documents valid for a maximum of six months. Internet Drafts may be
updated, replaced, or obsoleted by other documents at any time. It
is not appropriate to use Internet Drafts as reference material or
to cite them other than as a "working draft" or "work in progress."
Please check the I-D abstract listing contained in each Internet
Draft directory to learn the current status of this or any other
Internet Draft.
Comments on this document should be sent to "cat-ietf@MIT.EDU", the
IETF Common Authentication Technology WG discussion list.
2. ABSTRACT
The Generic Security Service Application Program Interface (GSS-
API), as defined in RFC-1508, provides security services to callers
in a generic fashion, supportable with a range of underlying
mechanisms and technologies and hence allowing source-level
portability of applications to different environments. It defines
GSS-API services and primitives at a level independent of underlying
mechanism and programming language environment.
The GSSAPI allows a caller application to authenticate a principal
identity associated with a peer application, to delegate rights to a
peer, and to apply security services such as confidentiality and
integrity on a per-message basis.
The primitives of the GSS-API do not currently allow support of
security attributes other than a single identity and do not allow
fine control of delegation.
The additional primitives described in this document provide support
for:
* the exchange of a variety of security attributes, and the
construction of authorization functions using these attributes,
including delegated ones, (attribute handling support functions),
Parker, Pinkas Document Expiration: 25 September, 1997 [Page 1]
Internet-Draft March 25 , 1997
* fine control over delegation by allowing specification of the
delegation method, the acceptor(s) of a security context, their type
and the restrictions that may apply (acceptor control and support
functions).
3. SECURITY ATTRIBUTES
A security attribute is defined as:
SecAttribute ::= {
attributeType OBJECT IDENTIFIER,
definingAuthority OCTET STRING OPTIONAL,
securityValue OCTET STRING }
attributeType
Defines the type of the attribute. Attributes of the same type
have the same authorization semantics.
definingAuthority
It indicates the authority responsible for defining the value
within the attribute type. Some policies demand that multiple
sources of values for a given attribute type be supported (e.g. a
policy accepting attribute values defined outside the security
domain), These policies give rise to a risk of value clashes. The
definingAuthority field is used to separate these values. When not
present, the value defaults to the name of the authority that
issued the attribute.
securityValue
The value of the security attribute. Its syntax is determined by
the attribute type.
Security attributes are composed of principal attributes and of
qualifier attributes.
3.1. PRINCIPAL ATTRIBUTES
Principal attributes are composed of security privileges and
miscellaneous attributes.
3.1.1. PRIVILEGES ATTRIBUTES
Security privileges are defined as security attributes attached to a
principal, and only usable for access control purposes. Ones defined
here are: access identity, group memberships, clearance and
capability. The use of OBJECT IDENTIFIERS allows for other types to
be standardised.
Parker, Pinkas Document Expiration: 25 September, 1997 [Page 2]
Internet-Draft March 25 , 1997
3.1.2. MISCELLANEOUS ATTRIBUTES
Miscellaneous attributes are defined as security attributes attached
to a principal, which are not security privileges. They are used for
a variety of purposes. Ones defined here are: the domain name of the
issuer of the security attributes, an audit identity, restrictions
and validity time periods.
3.2. QUALIFIER ATTRIBUTES
Qualifier attributes describe the context acceptors for which
controls are to apply. Ones defined here are: acceptor name and
application trust group.
3.3. ATTRIBUTES DEFINITIONS
3.3.1. PRIVILEGE ATTRIBUTES
A privilege attribute is attached to a principal and is only usable
for access control purposes. Privileges are defined under the OID:
privilege-attribute OBJECT IDENTIFIER ::=
{ iso(1) identified-organisation(3) icd-ecma(012) technical-report(1)
security-in-open-systems(046) privilege-attribute(4) }
3.3.1.1. ROLE ATTRIBUTE
The role attribute represents the principal's role. The type of this
attribute is:
{ privilege-attribute 1 }
The type and the value of this attribute can be set and returned.
3.4.1.2. ACCESS IDENTITY
The access identity represents an identity to be used for access
control purposes. A security context or a credential may not contain
more than a single access identity for a given principal. This attri-
bute does not need to be present. The type of this attribute is :
{ privilege-attribute 2 }
The type and the value of this attribute can be set and returned.
3.4.1.3. PRIMARY GROUP
The primary group represents a uniquely prominent group to which a
principal belongs. A security context or a credential may not
contain more than one primary group for a given principal. The type
of this attribute is :
{ privilege-attribute 3 }
Parker, Pinkas Document Expiration: 25 September, 1997 [Page 3]
Internet-Draft March 25 , 1997
The type and the value of this attribute can be set and returned.
3.4.1.4. GROUP
A group represents a characteristic common to several principals.
A security context or a credential may contain more than one group
for a given principal. The type of this attribute is :
{ privilege-attribute 4 }
The type and the value of this attribute can be set and returned.
3.4.1.5. CAPABILITY
A capability nominates a resource and the operation(s) that can be
performed on that resource. The type of this attribute is :
{ privilege-attribute 5 }
The type and the value of this attribute can be set and returned.
3.3.2. MISCELLANEOUS ATTRIBUTES
Miscellaneous attributes are defined under the OID:
misc-attributeOBJECT IDENTIFIER ::=
{ iso(1) identified-organisation(3) icd-ecma(012) technical-report(1)
security-in-open-systems(046) misc-attribute(3) }
3.4.2.1. AUDIT IDENTITY
The access identity represents the principal's identity to be used
for audit purposes. The type of this attribute is :
{ misc-attribute 2 }
Only the type of this attribute can be set and both the type and the
value can be returned.
3.4.2.2. ISSUER DOMAIN NAME
The issuer domain name represents the name of the domain that has
issued the security attributes. It cannot be set by a call to
GSS_Set_cred_attributes. The type of this attribute is :
{ misc-attribute 10 }
Only the type of this attribute can be set and both the type and the
value can be returned. This attribute may always be returned by a
call to GSS_Get_cred_attributes.
Parker, Pinkas Document Expiration: 25 September, 1997 [Page 4]
Internet-Draft March 25 , 1997
3.4.2.3. VALIDITY PERIODS
The validity periods represent a list of the time periods within
which the security attributes are valid. The type of this attribute
is :
{ misc-attribute 11 }
The type and the values of this attribute can be set and returned.
3.4.2.4. OPTIONAL RESTRICTIONS
The Optional restrictions represent restrictions that apply to the
security context. The context may be accepted, even if the
application is unable to understand the optional restrictions.
The type of this attribute is :
{ misc-attribute 12 }
The type and the values of this attribute can be set and returned.
3.4.2.5. MANDATORY RESTRICTIONS
The mandatory restrictions represent restrictions that apply to the
security context. The context must not be accepted if the
application is unable to understand the mandatory restrictions. The
type of this attribute is :
{ misc-attribute 13 }
The type and the values of this attribute can be set and returned.
3.3.3. QUALIFIER ATTRIBUTES
Qualifier attributes are security attributes which define which
applications are authorized to be a security context acceptor. In
addition to the qualifier attribute it is possible to specify
whether delegation is authorized or not for the context acceptor.
Qualifier attributes describe the context acceptors for which
controls are to apply. Qualifier attributes are defined under the
OID:
qualifier-attribute OBJECT IDENTIFIER ::=
{ iso(1) identified-organisation(3) icd-ecma(012) technical-report(1)
security-in-open-systems(046) qualifier-attribute(5) }
3.4.3.1. ACCEPTOR NAME
An acceptor name represents the name of an application that can
potentially accept the security context. The type of this attribute
is :
Parker, Pinkas Document Expiration: 25 September, 1997 [Page 5]
Internet-Draft March 25 , 1997
{ qualifier-attribute 1 }
3.4.3.2. APPLICATION TRUST GROUP
An application trust group represents a group of acceptors, defined
by the security administrator, that mutually trust each other not to
spoof each others' identity. The type of this attribute is :
{ qualifier-attribute 2 }
4. ATTRIBUTE SET REFERENCE
Attribute set references are defined under the OID:
attribute-set-reference OBJECT IDENTIFIER ::=
{ iso(1) identified-organisation(3) icd-ecma(012) technical-report(1)
security-in-open-systems(046) attribute-set-reference (9)
An Attribute set reference is used to select a set of security
attributes and acceptor controls according to policy. At present
only a role name is defined.
4.1. ROLE NAME
The role name is an attribute set reference used to select a set of
security attributes. The type of this attribute is :
{ attribute-set-reference 1 }
The type and the values of this reference can only be set.
6. INTERFACE DESCRIPTIONS
The interfaces are split between attribute handling support
functions and context acceptor control and support functions.
6.1. ATTRIBUTE HANDLING SUPPORT FUNCTIONS
Three attribute handling support functions are defined :
6.1.1. GSS_Set_cred_attributes
To enable a GSS-API context initiator to specify security
attributes, i.e. security privileges and miscellaneous security
attributes to be included in the caller credentials in order to
become part of a security context.
6.1.2. GSS_Get_sec_attributes
To extract security attributes, either from a GSS-API context, or
from a credential handle. Both privilege attributes and
miscellaneous attributes can be retrieved. The function can be
invoked either by a context initiator or by a context acceptor. When
Parker, Pinkas Document Expiration: 25 September, 1997 [Page 6]
Internet-Draft March 25 , 1997
applied to a GSS-API context and invoked by a context acceptor, if
delegation is being used, the privilege and miscellaneous attributes
which are returned and only those of the initiator, i.e. the
initiator of the delegation chain.
6.2. CONTEXT ACCEPTOR SUPPORT FUNCTION
There is a single function.
6.2.1. GSS_Get_received_creds
To extract credential handles from a GSS-API context (established
with GSS_Accept_sec_context function). This is only applicable for
some forms of delegation supporting multiple incoming credentials,
and can only be invoked by a context acceptor. A call to
GSS_Get_received_creds is an intermediary step for an acceptor,
before extracting the security attributes of each set of credentials
with a call to GSS_Get_sec_attributes. The credential handles are
ordered. They start with the credentials of the first initiator and
finish with the the credentials of the immediate invoker.
6.3. CONTEXT ACCEPTOR CONTROL FUNCTIONS
These functions enable a GSS-API context initiator to impose
constraints on the security context to be established via
GSS_Init_sec_context function, and enable a GSS-API context acceptor
to retrieve the control information that applies to a security
context established using the GSS_Accept_sec_context function, and
to build credentials from others.
Three context acceptor control functions are defined:
6.3.1. GSS_Set_cred_controls function
To enable a GSS-API context initiator to specify acceptor controls
to be included in the caller's credentials in order to be part of a
security context. The controls determine the context acceptors with
which valid security contexts can be established using the
associated credentials, and whether they can act only as targets
only, delegates only as or as delegate/targets.
* an acceptor designated as being a target only may use the
privileges attributes in the received credentials when authorising
access to its own protected resources and may not forward them.
* an acceptor designated as being a delegate only may use the
privilege attributes in the received credentials to forward them
but should not use them when authorising access to its own
protected resources.
Note: Only the acceptor system's AEF (Access Enforcement
Facility as described in ISO/IEC 10181-3: The Access Control
Framework) can prevent an acceptor permitting access based on
Parker, Pinkas Document Expiration: 25 September, 1997 [Page 7]
Internet-Draft March 25 , 1997
attributes not intended for it. However it is not in the
interests of an acceptor or its AEF to permit access to
resources under their control on the basis of attributes that
are explicitly stated as not being appropriate.
* an acceptor designated as being both a target and a delegate may
use the privilege attributes in the received credentials when
authorising access to its own protected resources and may also
forward them.
Restrictions over the operations that are authorised under the
context can also be specified.
6.3.2. GSS_Get_sec_controls function
To enable a GSS-API context initiator or a GSS-API context acceptor
to extract acceptor control information either from a credential
handle or from a security context.
6.3.3. GSS_Compound_creds function
To enable a delegate (which is acting as a GSS-API target for a
context initiator, and as a GSS-API context initiator for another
delegate or target) to build new credentials made from received
credentials and its own credentials.
7. DETAILED DESCRIPTION OF THE CALLS
7.1. ATTRIBUTE HANDLING CALLS
7.1.1. GSS_Set_cred_attributes call
Input :
- cred_handle OCTET STRING,
- required_attributes SET OF SecAttribute,
- new_cred_req BOOLEAN
- commit_cred_req BOOLEAN
Output :
- output_cred_handle OCTET STRING
Return major_status code:
- GSS_S_COMPLETE indicates that the nominated
attributes are permitted to
the caller and have been set.
- GSS_S_CREDENTIALS_EXPIRED indicates that the specified
credentials have expired.
- GSS_S_DEFECTIVE_CREDENTIAL indicates that defective
credentials have been detected.
- GSS_S_FAILURE indicates a failure,unspecified
at the GSS-API level.
Parker, Pinkas Document Expiration: 25 September, 1997 [Page 8]
Internet-Draft March 25 , 1997
- GSS_S_UNAUTHORIZED indicates that the function, or
an argument of the function was
not authorised.
- GSS_S_UNAVAILABLE indicates that the operation is
not supported.
This function enables a caller to request a set of privileges and
miscellaneous attributes, optionally replacing existing credentials
or creating a new set. The effect of this interface is not
cumulative, the requested attributes replace any existing attributes
in the credentials claimed.
Parameters for GSS_Set_cred_attributes:
cred_handle
Handle for credentials claimed, cred_handle refers to an
authenticated principal. Supply NULL to use default credentials.
required_attributes
A set of required privilege and miscellaneous attributes. NULL
specifies default attributes to be requested. Otherwise, only the
privilege and miscellaneous attributes specified will be present.
If a specified attribute is provided with a NULL value field, the
value allocated to the attribute will be the default for the
specified attribute available to the authenticated principal
according to the prevailing security policy. Otherwise the value
specified will be that present. If a value specified clashes with
policy, an error is returned.
If an attribute set reference (e.g.a role name) is specified as a
single attribute required, and policy permits the principal to use
it, it will be used as an attribute set reference to select a set of
attributes and acceptor controls according to policy.
If an attribute set reference (e.g.a role name) is specified along
with other required attributes, and policy permits the principal to
use the role name, the attributes potentially available for the
authenticated principal are taken from a set compounded of the
principal's authorised attributes, and the attributes associated
with the role name.
new_cred_req
TRUE for a new credentials set, FALSE replaces the original.
commit_cred_req
TRUE for immediate attribute acquisition, FALSE for deferred
attribute acquisition.
Parker, Pinkas Document Expiration: 25 September, 1997 [Page 9]
Internet-Draft March 25 , 1997
output_cred_handle
The credentials handle for the changed or new credentials.
GSS_Set_cred_attributes produces a modified version of the input
credentials (cred_handle). The original credentials are changed if
new_cred_req is FALSE, otherwise the output_cred_handle references a
new, and different, copy of the original input credentials (which
remain untouched). GSS_Release_cred can be used when the caller is
finished with any new credentials created by this function.
7.1.2. GSS_Get_sec_attributes call
Input :
- cred_handle OCTET STRING,
- context_handle INTEGER,
- attribute_types_required SET OF OBJECT IDENTIFIER
Output :
- priv_attributes SET OF SecAttribute
- misc_attributes SET OF SecAttribute
- other_cred_present BOOLEAN
Return major_status code :
- GSS_S_COMPLETE indicates that retrieval of
attributes is supported and
that all, some, or none of the
requested attribute types have
been returned.
- GSS_S_CONTEXT_EXPIRED indicates that the specified
security
context has expired.
- GSS_S_CREDENTIALS_EXPIRED indicates that the specified
credentials have expired.
- GSS_S_DEFECTIVE_CREDENTIAL indicates that defective
credentials have been detected.
- GSS_S_FAILURE indicates a failure,
unspecified at the GSS-API
level.
- GSS_S_UNAVAILABLE indicates that the operation is
not supported.
This function can be used by context initiators and context
acceptors to query attributes in credentials or security contexts.
If the credentials or security context represents a delegation
chain, attributes are retrieved only from the initiator of the
chain. If the attribute_types_required parameter is not supplied,
then all attribute types are returned. This option could allow
clients of this interface to query all attributes and pass privilege
attributes to a separate authorization service to make a decision.
Parker, Pinkas Document Expiration: 25 September, 1997 [Page 10]
Internet-Draft March 25 , 1997
To obtain security attributes from intermediates in a delegation
chain, the caller should first call GSS_Get_received_creds (see
section 5.2.1 and section 6.2.1).
Parameters for GSS_Get_sec_attributes:
cred_handle
Handle to credentials, cred_handle refers to an authenticated
principal. Supply NULL to use default credentials, or a context
handle. Note that NULL, without a context handle, is only used for
obtaining the caller's own attributes.
context_handle
GSS-API security context handle, context_handle refers to an
established security context. Context_handle is ignored if a non-
NULL cred_handle is presented. (Note: it is typically only necessary
to use a context_handle parameter rather than cred_handle for the
case when a security context is emitted by gss_accept_sec_context,
but not with an accompanying set of delegated credentials).
attribute_types_required
A set of security attribute types. If the default (NULL) is
specified, then all miscellaneous and privilege attribute types are
returned.
This standard does not specify which attributes must be supported,
but some common security attributes are defined in section 2.
priv_attributes
A set of privilege attributes. Response is conditional on the
"attribute_types_required" input.
misc_attributes
A set of miscellaneous attributes. Response is conditional on the
"attribute_types_required" input.
other_cred_present
TRUE when the caller is a context acceptor querying a security
context and when more than one set of credentials is present. If
interested in the other credential(s), the caller should next call
GSS_Get_received_creds,
FALSE when either the caller is a context initiator or when the
caller is a context acceptor querying a security context and when no
other credential is present.
7.2. CONTEXT ACCEPTOR SUPPORT FUNCTION
Parker, Pinkas Document Expiration: 25 September, 1997 [Page 11]
Internet-Draft March 25 , 1997
7.2.1. GSS_Get_received_creds call
Input :
- context_handle INTEGER,
Output :
- received_creds SEQUENCE OF OCTET STRING
Return major_status code :
- GSS_S_COMPLETE indicates that the requested
delegate
credentials were retrieved.
- GSS_S_CONTEXT_EXPIRED indicates that the specified
security
context has expired.
- GSS_S_FAILURE indicates a failure,
unspecified at the GSS-API
level.
- GSS_S_UNAUTHORIZED indicates that the function, or
an argument of the function was
not authorised.
- GSS_S_UNAVAILABLE indicates that the operation is
not supported.
This function supports the retrieval of all credentials received by
an acceptor. It is intended for context acceptors that require not
only the initiator's credentials, but also delegates' credentials,
to apply their local security policy. A typical example is the
retrieval of delegate credentials to subsequently obtain delegate
privilege attributes (using GSS_Get_sec_attributes) for use in
authorization decisions.
Parameters for GSS_Get_received_creds:
context_handle
GSS-API security context handle, context_handle refers to a security
context that is part of an established association. A default
context is assumed if no context_handle is supplied.
received_creds
Contains an ordered list of credentials for the original initiator
and for each of the intermediate delegates (if any) between the
original initiator and this context acceptor, the first of these
being the credentials of the original initiator, and the last being
of the immediately preceding delegate. It is expected that the
normal use for such credentials would merely be inspection via
GSS_Get_sec_attributes as most known mechanisms would not permit
Parker, Pinkas Document Expiration: 25 September, 1997 [Page 12]
Internet-Draft March 25 , 1997
such delegate credentials to be directly used for initiating further
security contexts. Note that it is the caller's responsibility to
free any received credentials returned from gss_get_received_creds
via gss_release_cred.
7.3. ACCEPTOR CONTROL HANDLING CALLS
The following construct is used in both the GSS_Set_cred_controls
and GSS_Get_sec_controls calls:
AcceptorControl ::= SEQUENCE {
targetOnly SEQUENCE OF SecAttribute OPTIONAL,
delegateOnly SEQUENCE OF SecAttribute OPTIONAL,
delegateTarget SEQUENCE OF SecAttribute OPTIONAL,
delegationMode DelegationMode OPTIONAL,}
DelegationMode ::= ENUMERATED {
default (0),
simple (1),
composite (2),
traced (3),}
The fields targetOnly, delegateOnly and delegateTarget specify one
or several qualifier attributes describing the acceptors (as
targets, delegates or delegate/targets) for which controls are to
apply.
* the targetOnly specifies that the qualifier(s) are identifying
one or more targets, none of which may use the credentials as a
delegate.
* the delegateOnly choice specifies that the qualifier(s) are
identifying one or more delegates, none of which should use the
privilege attributes in the credentials when authorising access to
their own protected resources, but which may use the received
credentials as a delegate.
* the delegateTarget choice specifies that the qualifier is
identifying one or more delegate/targets any of which can use the
received credentials as a delegate and can also use the privileges
attributes in the the credentials when authorising access to its
own protected resources.
delegationMode
Indicates the mode of delegation required.
Currently three delegation modes and one default are specified:
- default: whatever mode of delegation has been set as default (this
may be no delegation).
- simple: only the original initiator's credentials have to be
Parker, Pinkas Document Expiration: 25 September, 1997 [Page 13]
Internet-Draft March 25 , 1997
forwarded in the security context being established,
- composite: the credentials of the original initiator and of the
immediate caller have to be forwarded,
- traced: the credentials of the original initiator, of all the
delegates, including the immediate caller have to be forwarded.
7.3.1. GSS_Set_cred_controls call
Input :
- cred_handle OCTET STRING,
- required_acceptor_control AcceptorControl,
- replace_old_controls BOOLEAN
- new_cred_req BOOLEAN
- commit_cred_req BOOLEAN
Output :
- output_cred_handle OCTET STRING
Return major_status code:
- GSS_S_COMPLETE indicates that the controls
have been set.
- GSS_S_CREDENTIALS_EXPIRED indicates that the specified
credentials have expired.
- GSS_S_DEFECTIVE_CREDENTIAL indicates that defective
credentials have been detected.
- GSS_S_FAILURE indicates a failure,
unspecified at the GSS-API
level.
- GSS_S_UNAUTHORIZED indicates that the function, or
an argument of the function was
not authorised.
- GSS_S_UNAVAILABLE indicates that the operation is
not supported.
This function supports requests to set context acceptor controls,
optionally replacing existing credentials controls or creating a new
set of credentials with new controls. The effect of this interface
is either cumulative or not depending on the value of the
replace_old_controls parameter.
Parameters for GSS_Set_cred_controls:
cred_handle
Handle for credentials claimed, it refers to an authenticated
principal. Supply NULL to use default credentials.
Parker, Pinkas Document Expiration: 25 September, 1997 [Page 14]
Internet-Draft March 25 , 1997
required_acceptor_control
The control settings required.
replace_old_controls
TRUE to replace acceptor controls existing in original credentials.
FALSE to specify additional controls.
new_cred_req
TRUE for a new credentials set, FALSE to modify the original.
commit_cred_req
TRUE for immediate action, FALSE for deferred action.
output_cred_handle
GSS_Set_cred_controls produces a modified version of the input
credentials (cred_handle). The original credentials are directly
changed if duplicate_cred_req is FALSE, otherwise the
output_cred_handle references a new, and potentially different, copy
of the original input credentials (which remain untouched).
gss_release_cred can be used when the caller is finished with any
new credentials created by this function.
7.3.2. GSS_Get_sec_controls call
Input :
- cred_handle OCTET STRING,
- context_handle INTEGER,
Output :
- acceptor_controls SET OF AcceptorControl,
Return major_status code :
- GSS_S_COMPLETE indicates that the acceptor
control
information has been returned
- GSS_S_CREDENTIALS_EXPIRED indicates that the specified
credentials have expired.
- GSS_S_DEFECTIVE_CREDENTIAL indicates that defective
credentials have been detected.
- GSS_S_FAILURE indicates a failure,
unspecified at the GSS-API
level.
- GSS_S_UNAVAILABLE indicates that the operation is
not supported.
Parker, Pinkas Document Expiration: 25 September, 1997 [Page 15]
Internet-Draft March 25 , 1997
This function enables a caller to enquire the current value of the
acceptor controls in the specified credentials or context.
This function can be used by context initiators and context
acceptors to query acceptor controls in credentials or security
contexts.
Parameters for GSS_Get_sec_controls:
cred_handle
Handle to credentials. It refers to an authenticated principal.
Supply NULL to use default credentials, or a context handle.
context_handle
GSS-API security context handle, context_handle refers to a security
context that is part of an established association. Context_handle
is ignored if a non-NULL cred_handle is presented. (Note: it is
typically only necessary to use a context_handle parameter rather
than cred_handle for the case when a security context is emitted by
gss_accept_sec_context, but not with an accompanying set of
delegated credentials).
acceptor_controls
A set of acceptor controls. Acceptor controls are described in
section 6.2.
7.3.3. GSS_Compound_creds call
Input :
- delegated_cred_handle OCTET STRING
- cred_handle OCTET STRING,
Output :
- cred_handle_new OCTET STRING
Return major_status code :
GSS_S_COMPLETE indicates that the credentials
were successfully compounded
- GSS_S_CREDENTIALS_EXPIRED indicates that one or more of
the specified credentials have
expired.
- GSS_S_DEFECTIVE_CREDENTIAL indicates that defective
credentials have been detected.
- GSS_S_FAILURE indicates a failure,
unspecified at the GSS-API
level.
- GSS_S_UNAVAILABLE indicates that the operation is
not supported.
Parker, Pinkas Document Expiration: 25 September, 1997 [Page 16]
Internet-Draft March 25 , 1997
Parameters for gss_compound_cred:
delegated_cred_handle
A handle to the credentials being delegated, it refers to one or
several authenticated principals.
cred_handle
A handle to claimed credentials of the caller, cred_handle refers to
an authenticated principal.
cred_handle_new
A handle to the compounded set of credentials.
8. C-LANGUAGE BINDINGS
This section specifies C language bindings for the extended GSS-API
functions.
8.1. DATA TYPES AND CALLING CONVENTIONS
The following data types :
ú OM_uint32,
ú gss_buffer_t,
ú gss_OID,
ú gss_OID_set,
ú gss_cred_id_t,
ú gss_ctx_id_t,
are defined in [RFC-1508], along with the calling conventions.
8.1.1. SECURITY ATTRIBUTES
A security attribute (see section 2) has the following data
structure:
typedef struct gss_sec_attr_desc {
gss_OID attribute_type;
gss_buffer_t defining_authority;
/* specify GSS_C_NO_BUFFER when
non present */
gss_buffer_t security_value;
} gss_sec_attr;
8.1.2. SECURITY ATTRIBUTE SETS
A set of security attributes has the following structure:
Parker, Pinkas Document Expiration: 25 September, 1997 [Page 17]
Internet-Draft March 25 , 1997
typedef struct gss_sec_attr_set_desc {
OM_uint32 attribute_count;
gss_sec_attr* attributes;
} gss_sec_attr_set;
The attribute_count field contains the number of security attributes
in the set.
8.1.3. CREDENTIALS LIST
A list of credentials has the following structure:
typedef struct {
OM_uint3 cred_count;
gss_cred_id_t* cred_list;
} gss_cred_list;
The cred_count field contains the number of credentials in the list.
8.1.4. ACCEPTOR CONTROL
Acceptor control has the following structure:
typedef struct gss_acceptor_control_desc {
gss_sec_attr target_only;
/* specify GSS_C_NULL_SEC_ATTR when
non present */
gss_sec_attr delegate_only;
/* specify GSS_C_NULL_SEC_ATTR when
non present */
gss_sec_attr delegate_target;
/* specify GSS_C_NULL_SEC_ATTR when
non present */
OM_uint32 delegation_mode;
/* specify NULL when non present */
} gss_acceptor_control;
8.1.5. ACCEPTOR CONTROL SET
A set of Acceptor Control has the following structure :
typedef struct gss_control_set_desc {
OM_uint32 control_count;
gss_acceptor_control* acceptor_controls;
} gss_control_set;
The control_count field contains the number of acceptor controls in
the set.
8.1.6. IDENTIFIER
Identifiers have the following data structure:
Parker, Pinkas Document Expiration: 25 September, 1997 [Page 18]
Internet-Draft March 25 , 1997
typedef struct {
gss_type_en id_type
gss_value id_value;
} gss_id;
Where id_type identifies the syntax within the Identifier type:
typedef enum {
gss_oid_t, /* for OID */
gss_integer, /* for Integer */
gss_string, /* for character string */
gss_uuid, /* for DCE UUID */
gss_buffer_t; /* for gss_buffer */
} gss_type_en;
And where id_value is the actual value of the data of type
Identifier:
struct union {
gss_OID OID;
OM_uint32* integer;
char* string;
uuid_t* uuid;
gss_buffer_t buffer;
} gss_value;
This C type is applicable for the following types of attribute:
access identity, primary group, capability, audit identity, issuer
domain name, and role name.
When one of these attributes is handled in a call, the
security_value field of the gss_sec_attr structure for this
attribute contains a pointer to the gss_id structure.
8.1.7. IDENTIFIER SET
Identifier sets have the following data structure:
typedef struct gss_id_set_desc {
OM_uint32 id_count;
gss_id* ids;
} gss_id_set;
The id_count field contains the number of Identifiers in the set.
This C type is applicable for the following types of attribute:
group, role, optional restrictions, mandatory restrictions, acceptor
name and application trust group.
When one of these attributes is handled in a call, the
security_value field of the gss_sec_attr structure for this
attribute contains a pointer to the gss_id_set structure.
Parker, Pinkas Document Expiration: 25 September, 1997 [Page 19]
Internet-Draft March 25 , 1997
8.1.8. TIME PERIOD
A time period has the following structure:
typedef struct gss_time_period_desc {
time_t start_time;
/* NULL for unconstrained start time */
time_t end_time;
/* NULL for unconstrained end time */
} gss_time_period;
8.1.9. TIME PERIODS LIST
Time period lists have the following data structure:
typedef struct gss_period_list _desc {
OM_uint32 period_count;
gss_time_period* periods;
} gss_period_list;
The period_count field contains the number of time periods in the
list.
This C type is applicable for the miscellaneous attribute: time
period.
When a list of time periods is returned by a GSS_Get_sec_attributes
call, or set by a GSS_Set_cred_attributes call, the security_value
field of the gss_sec_attr structure in gss_sec_attr_set contains a
pointer to the gss_period_list_structure.
8.2. XGSS-API ROUTINE DESCRIPTIONS
8.2.1. gss_set_cred_attributes
/* set attributes values in credentials */
OM_uint32 gss_set_cred _attributes (
gss_cred_id_t cred_handle, /* IN */
gss_sec_attr_set required_attributes, /* IN */
OM_uint32 new_cred_req, /* IN */
OM_uint32 commit_cred_req, /* IN */
OM_uint32* minor_status, /* OUT*/
gss_cred_id_t* output_cred_handle); /* OUT*/
8.2.2. gss_get_sec_attributes
/* get attributes associated with credentials or security context */
OM_uint32 gss_get_sec_attributes (
gss_cred_id_t cred_handle, /* IN */
gss_ctx_id_t context_handle, /* IN */
gss_OID_set attribute_types_required, /* IN */
OM_uint32* minor_status, /* OUT*/
gss_sec_attr_set** priv_attributes, /* OUT*/
Parker, Pinkas Document Expiration: 25 September, 1997 [Page 20]
Internet-Draft March 25 , 1997
gss_sec_attr_set** misc_attributes); /* OUT*/
OM_uint32 other_cred_present /* OUT*/
8.2.3. gss_get_received_creds
/* get received credentials associated with a security context */
OM_uint32 gss_get_received_creds (
gss_ctx_id_t context_handle, /* IN */
OM_uint32* minor_status, /* OUT*/
gss_cred_list** received_creds); /* OUT*/
8.2.4. gss_set_cred_controls
/* Set acceptor controls in credentials for context establishment
*/
OM_uint32 gss_set_cred_controls (
gss_cred_id_t cred_handle, /* IN */
gss_ control_set required_control, /* IN */
OM_uint32 replace_old_controls, /* IN */
OM_uint32 new_cred_req, /* IN */
OM_uint32 commit_cred_req, /* IN */
OM_uint32* minor_status, /* OUT*/
gss_cred_id_t* output_cred_handle); /* OUT*/
8.2.5. gss_get_sec_controls
/* set context acceptor controls on credentials */
OM_uint32 gss_get_sec_controls (
gss_cred_id_t cred_handle, /* IN */
gss_ctx_id_t context_handle, /* IN */
OM_uint32* minor_status, /* OUT*/
gss_control_set* acceptor_controls); /* OUT*/
8.2.6. gss_compound_cred
/* compound credentials for delegation */
OM_uint32 gss_compound_cred (
gss_cred_id_t delegated_cred_handle, /* IN */
gss_cred_id_t cred_handle, /* IN */
OM_uint32* minor_status, /* OUT*/
gss_cred_id_t cred_handle_new); /* OUT*/
9. ACKNOWLEDGEMENTS
Acknowledgements are due to the following people : Eric Baize,
Belinda Fairthorne, Stephen Farell, Jacques Lebastard and Tom Parker
for providing material for the construction of this document and/or
providing useful inputs.
10. SECURITY CONSIDERATIONS
Security issues are discussed throughout this memo.
Parker, Pinkas Document Expiration: 25 September, 1997 [Page 21]
Internet-Draft March 25 , 1997
11. REFERENCES
[RFC 1508] Generic Security Service API, J Linn,
September 1993
[RFC 1509] Generic Security Service API : C-bindings, J Wray,
September 1993
12. AUTHORS'S ADDRESSES
Tom Parker Internet email: t.a.parker@win0199.wins.icl.co.uk
ICL Enterprises Telephone: +44.1344.472169
59 Old Road, Fax : +44.1249.822703
Derry Hill,
Calne,
Wiltshire SN11 9NF,
United Kingdom
Denis Pinkas Internet email: D.Pinkas@frcl.bull.fr
Bull Telephone: +33 1 30 80 34 87
Rue Jean-Jaures Fax: +33 1 30 80 33 21
BP 68
78340 Les Clayes-sous-Bois
FRANCE
Parker, Pinkas Document Expiration: 25 September, 1997 [Page 22]
Internet-Draft March 25 , 1997
13. CONTENT LIST
1. STATUS OF THIS MEMO 1
2. ABSTRACT 1
3. SECURITY ATTRIBUTES 2
3.1. PRINCIPAL ATTRIBUTES 2
3.1.1. PRIVILEGES ATTRIBUTES 2
3.1.2. MISCELLANEOUS ATTRIBUTES 3
3.2. QUALIFIER ATTRIBUTES 3
3.3. ATTRIBUTES DEFINITIONS 3
3.3.1. Privilege attributes 3
3.3.1.1. Role attribute 3
3.4.1.2. Access identity 3
3.4.1.3. Primary group 3
3.4.1.4. Group 4
3.4.1.5. Capability 4
3.3.2. Miscellaneous attributes 4
3.4.2.1. Audit identity 4
3.4.2.2. Issuer domain name 4
3.4.2.3. Validity periods 5
3.4.2.4. Optional restrictions 5
3.4.2.5. Mandatory restrictions 5
3.3.3. QUALIFIER ATTRIBUTES 5
3.4.3.1. Acceptor name 5
3.4.3.2. Application trust group 6
4. ATTRIBUTE SET REFERENCE 6
4.1. ROLE NAME 6
6. INTERFACE DESCRIPTIONS 6
6.1. ATTRIBUTE HANDLING SUPPORT FUNCTIONS 6
6.1.1. GSS_Set_cred_attributes 6
6.1.2. GSS_Get_sec_attributes 6
6.2. CONTEXT ACCEPTOR SUPPORT FUNCTION 7
6.2.1. GSS_Get_received_creds 7
6.3. CONTEXT ACCEPTOR CONTROL FUNCTIONS 7
6.3.1. GSS_Set_cred_controls function 7
6.3.2. GSS_Get_sec_controls function 8
6.3.3. GSS_Compound_creds function 8
7. DETAILED DESCRIPTION OF THE CALLS 8
7.1. Attribute handling calls 8
7.1.1. GSS_Set_cred_attributes call 8
7.1.2. GSS_Get_sec_attributes call 10
7.2. CONTEXT ACCEPTOR SUPPORT FUNCTION 11
7.2.1. GSS_Get_received_creds call 12
7.3. ACEPTOR CONTROL handling calls 13
7.3.1. GSS_Set_cred_controls call 14
7.3.2. GSS_Get_sec_controls call 15
7.3.3. GSS_Compound_creds call 16
8. C-LANGUAGE BINDINGS 17
8.1. DATA TYPES AND CALLING CONVENTIONS 17
8.1.1. Security attributes 17
8.1.2. Security attribute sets 17
8.1.3. Credentials list 18
8.1.4. Acceptor control 18
8.1.5. Acceptor control set 18
Parker, Pinkas Document Expiration: 25 September, 1997 [Page 23]
Internet-Draft March 25 , 1997
8.1.6. Identifier 18
8.1.7. Identifier set 19
8.1.8. Time period 20
8.1.9. Time periods list 20
8.2. XGSS-API ROUTINE DESCRIPTIONS 20
8.2.1. gss_set_cred_attributes 20
8.2.2. gss_get_sec_attributes 20
8.2.3. gss_get_received_creds 21
8.2.4. gss_set_cred_controls 21
8.2.5. gss_get_sec_controls 21
8.2.6. gss_compound_cred 21
9. ACKNOWLEDGEMENTS 21
10. SECURITY CONSIDERATIONS 21
11. REFERENCES 22
12. AUTHORS'S ADDRESSES 22
13. CONTENT LIST 23
Parker, Pinkas Document Expiration: 25 September, 1997 [Page 24]
