One document matched: draft-engert-ggf-gss-extensions-00.txt
INTERNET DRAFT S. Meder
V. Welch
Document: U. Chicago
draft-engert-ggf-gss-extensions-00.txt
GWD: draft-ggf-gss-extensions-07 S. Tuecke
D. Engert
ANL
February 20, 2003
Expires: Aug 20, 2003
GSS-API Extensions
Status of this Memo
This document is an Internet-Draft and is subject to all
provisions of Section 10 of RFC2026 except that the right to
produce derivative works is not granted.
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 and may be updated, replaced, or obsoleted by other
documents at any time. It is inappropriate to use Internet-
Drafts as reference material or to cite them other than as "work
in progress."
The list of current Internet-Drafts can be accessed at
http://www.ietf.org/1id-abstracts.html
The list of Internet-Draft Shadow Directories can be accessed at
http://www.ietf.org/shadow.html
This draft is the original work of the Global Grid Forum (GGF),
known as draft-ggf-gss-extensions-07.
The draft is being submitted as a courtesy to the IETF to garner
support and request comments from the IETF members. If
sufficient support is expressed, consideration will be given to
making this an IETF RFC.
GGF Status of this Memo
This document provides information to the community regarding
extensions to GSS-API as defined in RFC 2743 and RFC 2744.
meder@mcs.anl.gov
GWD-R.P GSS-API Extensions February 2003
This document is a product of the Grid Security Infrastructure
(GSI) Working Group of the Global Grid Forum. The latest version
of this document is available from the GSI WG webpage:
http://www.gridforum.org/2_SEC/GSI.htm
Distribution of this document is unlimited.
Copyright
Copyright (c) Global Grid Forum (2/20/2003). All Rights
Reserved.
Please see Section 0 for full Copyright statement.
Abstract
This document defines extensions to RFC 2743, Generic Security
Service Application Program Interface Version 2, Update 1.
Extensions include: credential export and import; delegation at
any time; credential extensions (e.g. restrictions) handling.
meder@mcs.anl.gov 2
GWD-R.P GSS-API Extensions February 2003
Table of Contents
GSS-API Extensions.................................................1
Introduction.......................................................4
1.1. Extension Specifications....................................5
1.2. Credential Export and Import................................5
gss_export_cred call........................................7
gss_import_cred.............................................9
1.3. Delegation At Any Time.....................................11
gss_init_delegation........................................11
gss_accept_delegation......................................13
1.4. Extended Credential Inquiry................................15
gss_inquire_sec_context_by_oid call........................16
gss_inquire_cred_by_oid call...............................17
1.5. Context options............................................18
gss_set_sec_context_option call............................19
1.6. Buffer Set Functions.......................................20
gss_create_empty_buffer_set................................20
gss_add_buffer_set_member call.............................20
gss_release_buffer_set call................................21
Changes to existing functions.....................................23
1.7. gss_accept_sec_context.....................................23
1.8. gss_init_sec_context.......................................23
1.9. gss_getMIC, gss_verifyMIC, gss_wrap, gss_unwrap............23
Additional Desired Functionality..................................23
1.10. Token Framing..............................................23
1.11. Different levels of verbosity with gss_display_status......24
Security Considerations...........................................26
1.12. Credential export and import...............................26
1.13. Delegation at any time and restricted delegation handling..26
C-Bindings........................................................27
References........................................................29
Acknowledgments...................................................29
Change Log........................................................29
Contact Information...............................................31
Copyright Notice..................................................31
Intellectual Property Statement...................................32
meder@mcs.anl.gov 3
GWD-R.P GSS-API Extensions February 2003
Introduction
RFC 2743 defines the Generic Security Service Application
Program Interface (GSS-API) Version 2, Update 1 [3, 4], as an
API for portably adding authentication, delegation, and message
protection to distributed computing applications.
In 1997, the Globus Project (www.globus.org) introduced an
implementation of GSS-API called the Grid Security
Infrastructure (GSI). This implementation uses public key
protocols for use in programming Grid applications [2] -- that
is, applications that run in dynamic, inter-domain distributed
computing environments. Based on this implementation, a great
deal of experience has been gained on the use of GSS-API in
numerous real applications and middleware toolkits. While this
experience has been overwhelmingly positive, it has also led to
an understanding of some deficiencies in the existing GSS-API.
This document defines extensions to the GSS-API to address these
deficiencies. These extensions are:
* Credential export and import: Processes need to be able, in a
controlled and standard fashion, to export credentials to and
import credentials from other processes. This includes
processes that are not written to the GSS-API.
* Delegation at any time: GSS-API only allows for delegation
during the initial context establishment, via an argument to
gss_init_sec_context. This document extends GSS-API to also
allow for delegation at any time after initial context
establishment.
* Credential extensions handling: When delegating a credential,
it is often useful to attach additional data, such as
restriction policies, to that delegated credential which
restricts its usage. This document defines extensions to the
GSS-API to allow such extensions to be specified during
delegation and to be extracted from a security context after
authentication. However, the approach is neutral to the
actual attached data.
Section 1.1 defines the GSS-API extensions.
Section 0 contains changes to existing GSS-API functions.
meder@mcs.anl.gov 4
GWD-R.P GSS-API Extensions February 2003
Section 0 contains discussions of problems with the existing
GSS-API that the authors have found, but have not had time to
work out solutions for.
Section 0 contains security considerations.
Section 6 contains the references.
Section 7 contains acknowledgements.
Section 8 contains contact information for the authors.
Section 9 contains C-bindings for the API extensions.
Section 10 contains the change log for this document.
Section 0 contains the copyright information for this document.
Section 0 contains the intellectual property information for
this document.
This document was written under the auspices of the Global Grid
Forum Grid Security Infrastructure Working Group. For more
information on this and other related work, see
http://www.gridforum.org/2_SEC/GSI.htm.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL
NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described
in RFC-2119 [1].
1.1. Extension Specifications
The following sections explain needed extensions to the GSS-API
as defined in RFC 2743 and give proposed additional functions to
be added to the API.
1.2. Credential Export and Import
In order to portably implement a reliable service that can
accept delegated credentials from multiple clients, these
functions are needed to allow the service to checkpoint and
reload the delegated credential to and from permanent storage.
These functions also provide support for servers that need to
pass a credential on to other processes, for example a sshd
meder@mcs.anl.gov 5
GWD-R.P GSS-API Extensions February 2003
daemon that accepts a delegated credential from a client and
then wants to make that credential available to the spawned
shell process.
Previously applications which needed this functionality were
forced to use mechanism specific lower level routines, defeating
the purpose of a generic interface.
The gss_export_cred function allows exporting credentials in one
of two forms as selected by the option_req parameter.
When option_req is equal to 0, it exports an opaque buffer
suitable for storage in memory or on disk or passing to another
process, which can import the buffer with gss_import_cred. This
method of invocation will normally be used by applications that
want to transfer a credential to another GSS application or save
a credential to some storage medium so it can be loaded later
(perhaps after a restart).
With option_req is equal to 1, it exports a buffer filled with
mechanism-specific information that the calling application can
use to pass the credential to another process that is not
written to the GSS-API. This is intended to work with the
existing Kerberos and GSI GSS implementations. These
implementation normally store credentials by writing the
credentials to a file and then storing the path to that file in
an environment variable. In the case of these implementations
this function stores the credential on disk and returns a buffer
containing a string suitable for passing to putenv(3). This
method of invocation will normally be used by applications, such
as SSHD, which accept a delegated GSS credential and then want
to make this credential available to the shell process they
spawn.
Note that in either case, you cannot pass the exported
credential to another machine over the network and assume it
will work. Passing a credential to another process may also fail
if the process does not have the same privileges as the original
process.
A credential can also expire between export and import. In this
case the import of the credential may fail, returning an error.
The gss_import_cred function is the complimentary function to
gss_export_cred. When called with the exported buffer and
option_req set to the same value used in the gss_export_cred
meder@mcs.anl.gov 6
GWD-R.P GSS-API Extensions February 2003
call it will return a credential handle suitable for use with
other GSS-API functions. While this function is similar in
function to gss_acquire_cred, there is no compatibility between
the two (i.e. one cannot take a buffer from gss_export_cred and
use gss_acquire_cred to import it).
gss_export_cred call
Inputs:
. option_req INTEGER û 0 = Export simple data good only for
reuse with gss_import_cred, 1 = Export mechanism-specific data
that can be passed to non-GSS applications (see following
function description).
. cred_handle CREDENTIAL HANDLE û credential to be exported. May
be modified but is stable and usable after call.
. desired_mech OBJECT IDENTIFIER û desired mechanism for
exported credential, may be NULL to indicate system default
. protection_key OPTIONAL OCTET STRING û if specified, a key
used to protect (e.g. encrypt) the exported credential.
Outputs:
. major_status INTEGER
. minor_status INTEGER
. export_buffer OCTET STRING û token to be used in future
gss_import_cred call (if option_req == 0) or mechanism
specific data (if option_req == 1). To be freed by caller
using gss_release_buffer.
. actual_mech OBJECT_IDENTIFIER û actual mechanism of the
exported credential
Returned major_status codes:
. GSS_S_COMPLETE indicates that the operation was successfully
completed and export_buffer contains the requested data.
. GSS_S_CREDENTIALS_EXPIRED indicates the credential referred to
by cred_handle has expired and cannot be exported.
meder@mcs.anl.gov 7
GWD-R.P GSS-API Extensions February 2003
. GSS_S_UNAVAILABLE indicates that the requested operation is
not supported by the underlying mechanism.
. GSS_S_BAD_MECH indicates that the requested mechanism is
unsupported.
. GSS_S_FAILURE indicates a failure unspecified at the GSS-API
level.
GSS_export_cred is used to export a credential so that it can be
passed to another process or reloaded by the same process after
its use of a different credential in the interim.
If the caller passes in a value of 0 for option_req the returned
data will be suitable for use in a call to gss_import_cred at a
later date or in a different process. Note that the data may
contain the actual credential itself or just a pointer to it
(e.g. a filename). In any case it should be assumed that the
returned buffer contains sensitive information and care should
be taken to protect the privacy of its contents.
If the caller passes in a value of 1 for option_req the return
data contains mechanism-specific data that the calling
application can use to pass the credential to another process
that does not use the GSS-API. The caller is responsible for
understanding this data and knowing what to do with it. For
example in the case of both Kerberos 5 and GSI the credential
will be stored to a file and the returned data will be a string
suitable for passing to putenv(3). In this case the caller may
need to change the ownership of the credential file.
In either case the data is returned in export_buffer, which the
calling application is responsible for freeing using
gss_release_buffer.
If the protection_key is provided by the caller, the underlying
mechanism MUST use this key to protect the exported key
(probably by encryption but this is mechanism-specific). If a
protection_key is provided and protection is not supported by
the underlying mechanism a GSS_S_UNAVAILABLE error MUST be
returned.
This function is intended to be used primarily by complex
servers that must juggle multiple credentials, storing them for
a time in files and/or passing them to other processes.
meder@mcs.anl.gov 8
GWD-R.P GSS-API Extensions February 2003
gss_import_cred
Inputs:
. option_req INTEGER û 0 = import_buffer is opaque data as
created by gss_export_cred called with option_req = 0, 1 =
import_buffer is handle to a credential as created by
gss_export_cred called with option_req = 1 (e.g. strings of
the form ôKRB5CCNAME=FILE:filenameö).
. desired_mech OBJECT IDENTIFIER û desired mechanism for the
imported credential, may be NULL to indicate system default.
. import_buffer OCTET STRING û buffer containing data for import
as created by a call to gss_export_cred.
. lifetime_req INTEGER û in seconds, 0 requests default.
. protection_key OPTIONAL OCTET STRING û if specified, a key
used to access the imported credential.
Outputs:
. major_status INTEGER
. minor_status INTEGER
. cred_handle CREDENTIAL HANDLE û the returned credential
handle. Resources associated with the credential handle must
be released by the application after use with a call to
gss_release_cred.
. lifetime_rec INTEGER û in seconds, with reserved value for
INDEFINITE.
. actual_mech OBJECT_IDENTIFIER û actual mechanism of the
imported credential.
Returned major_status codes:
. GSS_S_COMPLETE indicates that the operation was successful and
cred_handle contains a handle to a usable credential.
. GSS_S_BAD_MECH indicates that the requested mechanism is
unsupported.
meder@mcs.anl.gov 9
GWD-R.P GSS-API Extensions February 2003
. GSS_S_DEFECTIVE_TOKEN indicates the import buffer is
unparsable.
. GSS_S_NO_CRED indicates that the imported credential is
unusable or inaccessible.
. GSS_S_CREDENTIALS_EXPIRED indicates that the imported
credential has expired.
. GSS_S_FAILURE indicates an error unspecified at the GSS-API
level.
Gss_import_cred is the complimentary function to gss_export_cred
and is intended to be used to allow use of a credential that was
passed from another process or read from storage.
The credential, or the handle to the credential, is read from
import_buffer, which is unmodified. A handle to the credential
is returned in cred_handle.
The lifetime_rec result indicates the length of time for which
the acquired credential will be valid, as an offset from the
present. A mechanism may return a reserved value indicating
INDEFINITE if no constraints on credential lifetime are imposed.
A caller of gss_import_cred can request a length of time for
which acquired the credential is to be valid (using the
lifetime_req parameter), beginning at the present, or can
request a credential with a default validity interval. Requests
for postdated credentials are not supported within the GSS-API.
Certain mechanisms and implementations may supply credential
validity period specifiers at a point prior to invocation of the
gss_import_cred call (e.g., in conjunction with user login
procedures). As a result, callers requesting non-default values
for lifetime_req must recognize that such requests cannot always
be honored and must be prepared to accommodate the return of a
credential with a different lifetime as indicated by
lifetime_rec. The lifetime_req parameter should be viewed as
advisory and no error should be returned if the lifetime request
cannot be honored.
The protection_key parameters should be used to provide a key to
the underlying mechanism to be used to access the credentials in
the event they are protected. If the credentials are not
protected and a key is provided it SHOULD be ignored. If the
credentials are protected and no key is provided a GSS_S_NO_CRED
error MUST be returned.
meder@mcs.anl.gov 10
GWD-R.P GSS-API Extensions February 2003
1.3. Delegation At Any Time
These functions are designed to allow more flexible protocols to
be built on top of the GSS-API. They allow delegation to happen
at times other than context initiation, in either direction
regardless of the direction of context initiation (i.e. the
acceptor in context initiation can be the delegator) and with a
credential other than the credential used for context setup.
These functions also allow the initiator and acceptor to attach
extensions, such as restriction polices, to a delegated
credential. These extensions are mechanism-specific and
completely opaque to the GSS-API. See the following section on
Credential Extension Handling for information about accessing
the extension data.
Furthermore, these functions make it possible to delegate
credentials associated with mechanisms other than the mechanism
used for context establishment. Application may for example wish
to delegate a Kerberos credential over a security context
established using GSI.
The two functions for doing delegation are gss_init_delegation
and gss_accept_delegation. These functions are used in a similar
manner as gss_init_sec_context and gss_accept_sec_context; they
should be called in a loop as long as they return
GSS_S_CONTINUE_NEEDED and the tokens output by each should be
passed into the other.
Note that mechanisms are not required to support intermingling
of calls to other GSS-API functions (e.g. gss_wrap) with the
sequence of calls to needed to perform delegation of a
credential. This also implies that if an application initiates a
second delegation while a previous one has yet to complete the
results may be undefined.
gss_init_delegation
Inputs:
. context_handle CONTEXT HANDLE û handle to existing security
context.
meder@mcs.anl.gov 11
GWD-R.P GSS-API Extensions February 2003
. cred_handle CREDENTIAL HANDLE û handle to credential to be
delegated. NULL (GSS_C_NO_CREDENTIAL) specifies the use of the
default credential.
. mech_type OBJECT IDENTIFIER û NULL parameter specifies that
the system default should be used.
. lifetime_req INTEGER - 0 specifies default lifetime
. extension_oids SEQUENCE OF OBJECT IDENTIFIER û identifiers for
the type of data in the extensions_buffers. See description
below for a discussion of this option.
. extension_buffers SEQUENCE OF OCTET STRINGS û opaque extension
data to be applied to the delegated credential. See
description below for a discussion of this option.
. input_token OCTET STRING û GCC_C_NO_BUFFER or token received
from target.
Outputs:
. major_status INTEGER
. minor_status INTEGER
. output_token OCTET STRING ûtoken to pass to target. May be
empty. Caller must release with gss_release_buffer.
Returned major_status codes:
. GSS_S_COMPLETE indicates that delegation is complete and it is
not necessary to call gss_init_delegation again. The returned
output_token may have data to be sent to the target to
successfully complete the delegation.
. GSS_S_CONTINUE_NEEDED indicates that the information in the
returned output_token must be sent to the target and a reply
must be received and passed as the input_token argument in a
subsequent call to gss_init_delegation.
. GSS_S_DEFECTIVE_TOKEN û consistency checks on input token
failed.
. GSS_S_BAD_SIG û bad integrity check on input token.
meder@mcs.anl.gov 12
GWD-R.P GSS-API Extensions February 2003
. GSS_S_NO_CRED û credential is invalid.
. GSS_S_CREDENTIALS_EXPIRED û provided credential has expired.
. GSS_S_OLD_TOKEN û input_token is too old.
. GSS_S_DUPLICATE_TOKEN û input_token is a duplicate.
. GSS_S_BAD_MECH û unsupported mechanism.
. GSS_S_BAD_BINDINGS û this indicates that the extensions
provided were invalid (e.g. a mismatch of number of OIDs and
buffers).
. GSS_S_FAILURE û error unspecified at the GSS-API level.
This routine is used by either side of a security context to
perform a delegation to the peer. The credential being delegated
can either be the same credential used to setup the context or a
different one.
Input parameters other than input_token must correspond to the
same valid GSS-API structures during the delegation process.
The extension_oids and extension_buffers parameters can be used
to specify a set of extensions for the delegated credential.
There should be an identical number of OIDs and buffers, with
each OID indicating what the type of data (e.g. policy language)
its corresponding buffer contains. These values may be
GSS_C_NO_OID_SET and GSS_C_NO_BUFFER_SET, respectively, to
indicate that no extensions are to be applied to the credential.
gss_accept_delegation
Inputs:
. sec_context CONTEXT HANDLE û handle to existing security
context.
. input_token OCTET STRING û token received from initiator.
. extension_oids SEQUENCE OF OBJECT IDENTIFIER û identifiers for
the type of data in the extension_buffers. See description
below for a discussion of this option.
meder@mcs.anl.gov 13
GWD-R.P GSS-API Extensions February 2003
. extension_buffers SEQUENCE OF OCTET STRINGS û requested data
for extensions to be applied to the delegated credential. See
description below for a discussion of this option.
. lifetime_req INTEGER - in seconds, 0 requests default
Outputs:
. delegated_cred CREDENTIAL HANDLE û on completion this will
contain a handle to the delegated credential. The caller must
release with gss_release_cred.
. lifetime_rec INTEGER - in seconds, or reserved value for
INDEFINITE
. output_token OCTET STRING û token to pass to initiator. May be
empty. Caller must release with gss_release_buffer.
. mech_type OBJECT_IDENTIFIER û mechanism corresponding to
delegated credential; read only, caller should not attempt to
release.
Return major_status codes:
. GSS_S_COMPLETE indicates that the delegation has been
successful and delegated_cred contains a handle to a usable
credential.
. GSS_S_CONTINUE_NEEDED indicates that the information in the
returned output_token must be sent to the initiator and a
reply must be received and passed as the input_token argument
in a subsequent call to gss_accept_delegation.
. GSS_S_DEFECTIVE_TOKEN û malformed token.
. GSS_S_BAD_SIG û integrity check failed.
. GSS_S_OLD_TOKEN û token too old.
. GSS_S_NO_CONTEXT û bad context.
. GSS_S_BAD_MECH û unsupported mechanism for the delegated
credential.
meder@mcs.anl.gov 14
GWD-R.P GSS-API Extensions February 2003
. GSS_S_BAD_BINDINGS û this indicates that the extensions
provided were invalid (e.g. a mismatch of number of OIDs and
buffers).
. GSS_S_FAILURE û Error unspecified at the GSS-API level.
This routine is used by either side of a security context to
accept a delegation being performed by gss_init_delegation. The
credential being delegated can be either the same credential
used to setup the context or a different one.
Input parameters other than input_token must correspond to the
same valid GSS-API structures during the delegation process.
The lifetime_rec parameter, on successful completion, will
contain the remaining lifetime, in seconds, of the delegated
credential. A mechanism may return a reserved value indicating
INDEFINITE if no constraints on credential lifetime are imposed.
A caller of gss_accept_delegation may also request that the
delegated credential be valid for a specified period of time
(via the lifetime_req argument), but should be prepared to
handle a delegated credential with shorter than requested
lifetime.
The extension_oids and extension_buffers parameters can be used
to request extensions to be applied to the delegated credential.
There should be an identical number of OIDs and buffers with
each OID indicating the type of data (e.g. policy language) its
corresponding buffer contains. See gss_init_delegation for a
discussion of these OIDs. Note that depending on the mechanism,
the initiator may ultimately decide to ignore the extensions
requested by the acceptor. These values may be GSS_C_NO_OID_SET
and GSS_C_NO_BUFFER_SET, respectively, to indicate that no
extensions are requested in the credential.
1.4. Extended Credential Inquiry
Applications wanting to make more complex authorization
decisions require more information about a clientÆs credential
than just the clientÆs identity. In order to provide this
information the gss_inquire_sec_context_by_oid and
gss_inquire_cred_by_oid functions were added. These functions
give applications a means to retrieve arbitrary data about a
context or credential.
meder@mcs.anl.gov 15
GWD-R.P GSS-API Extensions February 2003
The gss_inquire_sec_context_by_oid and gss_inquire_cred_by_oid
functions are called with an object identifier identifying the
information that the application is interested in. This object
identifier will either be one of a number of generic OIDs or may
be mechanism-specific. Generic OIDs should be defined in a
future GGF OID namespace. In the absence of such a namespace we
recommend the use of the following OID from the Globus OID
namespace:
1.3.6.1.4.1.3536.1.1.1.3 û A OID designating any restrictions
placed on a credential. Normally these restrictions are placed
in a credential using the extensions parameter in the
ôdelegation at any timeö functions.
gss_inquire_sec_context_by_oid call
Inputs:
. sec_context CONTEXT HANDLE û handle to existing security
context.
. desired_object OBJECT IDENTIFIER û OID of desired objects.
Outputs:
. major_status INTEGER
. minor_status INTEGER
. data_set SET OF OCTET STRING û zero or more pieces of data
corresponding to the data associated with the desired_object
OID. To be freed by caller using gss_release_buffer_set.
Return major_status codes:
. GSS_S_COMPLETE indicates that the function completed
successfully and data was returned.
. GSS_S_CONTINUE_NEEDED indicates that there are more data items
to be returned (see following description).
. GSS_S_NO_CONTEXT indicates that no valid context was
recognized for the input context handle provided.
. GSS_S_FAILURE indicates that the requested operation failed
for reasons unspecified at the GSS-API level.
meder@mcs.anl.gov 16
GWD-R.P GSS-API Extensions February 2003
The desired_object parameter should contain an OID that
references information the application is interested in. This
may for example be a OID that identifies a extension used in the
delegation routines.
If the requested data is not present, major_status will be set
to GSS_S_COMPLETE and 0 objects will be returned in data_set.
Note that there is disagreement between the current GSS-API RFC
[3] and the RFC specifying the C-language bindings [4]. While
the GSS-API RFC states that functions that functions of this
nature should not iterate using GSS_S_CONTINUE_NEEDED, the RFC
specifying language bindings does so. Applications should be
prepared to handle this function returning only a single piece
of data per call and call it iteratively if it returns
GSS_S_CONTINUE_NEEDED.
gss_inquire_cred_by_oid call
Inputs:
. cred_handle CREDENTIAL HANDLE - handle to existing credential.
. desired_object OBJECT IDENTIFIER - OID of desired objects.
Outputs:
. major_status INTEGER
. minor_status INTEGER
. data_set SET OF OCTET STRING - zero or more pieces of data
corresponding to the data associated with the desired_object
OID. To be freed by caller using gss_release_buffer_set.
Return major_status codes:
. GSS_S_COMPLETE indicates that the function completed
successfully and data was returned.
. GSS_S_CONTINUE_NEEDED indicates that there are more data items
to be returned (see following description).
. GSS_S_NO_CRED indicates there was no valid credential
meder@mcs.anl.gov 17
GWD-R.P GSS-API Extensions February 2003
. GSS_S_FAILURE indicates that the requested operation failed
for reasons unspecified at the GSS-API level.
The desired_object parameter should contain an OID that
references information the application is interested in. This
may for example correspond to a OID used in the extended
delegation routines.
If the requested data is not present, major_status will be set
to GSS_S_COMPLETE and 0 objects will be returned in data_set.
Note there is disagreement between the current GSS-API RFC [3]
and the RFC specifying the C-language bindings [4]. While the
GSS-API RFC states that functions that functions of this nature
should not iterate using GSS_S_CONTINUE_NEEDED, the RFC
specifying language bindings does so. Applications should be
prepared to handle this function returning only a single piece
of data per call and call it iteratively if it returns
GSS_S_CONTINUE_NEEDED.
1.5. Context options
Currently there is no method for passing flags into the
gss_accept_sec_context call. Instead of changing the arguments
to this function we propose a method that allows us to set
options on a security context and then pass the context into a
first call of gss_accept_sec_context or gss_init_sec_context.
This provides the means for an application to achieve more fine-
grained control of the underlying GSS-API mechanism.
The option being changed may be mechanism specific or one of the
generic options defined below. The Global Grid Forum will define
OIDs for the options below.
Generic options:
GSS_DISALLOW_ENCRYPTION û Setting this option to 1 will cause
the underlying GSS library to disallow any encryption of
application data.
GSS_PROTECTION_FAIL_ON_CONTEXT_EXPIRATION û Setting this option
to 1 will case the underlying GSS library to fail if any message
protection operation is attempted after the security context has
expired. It is recommended that the underlying mechanism allow
this option to be set to 0 after such an error in returned so
that an application can finish an ongoing process before
meder@mcs.anl.gov 18
GWD-R.P GSS-API Extensions February 2003
returning an error to the user. For example, an application may
wish to complete a file transfer already in progress before
refusing to start another transfer. Note that some
implementations may not be able to perform message protection
after security context expiration.
GSS_APPLICATION_WILL_CHECK_EXTENSIONS û Setting this option to a
list of OIDs (using the SET OF OBJECT IDENTIFIER data type) will
inform the underlying GSSAPI library that the application will
take responsibility for checking any extensions in the peer
credential identified by these OIDs . If the GSS mechanism
encounters a extension during context establishment that the
application has not declared its responsibility for, then the
GSS mechanism may choose to fail the authentication. The reason
for this is that without the knowledge that the application is
aware of and taking responsibility for handling the extensions
the GSSAPI mechanism cannot be assured they will be respected
and must take the safe course of failure.
gss_set_sec_context_option call
Inputs:
. sec_context CONTEXT HANDLE û handle to security context. NULL
specifies that a new security context should be created.
. option OBJECT IDENTIFIER û OID of desired option.
. value OCTET STRING û value of option.
Outputs:
. major_status INTEGER
. minor_status INTEGER
Return major_status codes:
. GSS_S_COMPLETE indicates that the function completed
successfully.
. GSS_S_FAILURE indicates that the requested operation failed
for reasons unspecified at the GSS-API level. This includes an
attempt to change an immutable option.
meder@mcs.anl.gov 19
GWD-R.P GSS-API Extensions February 2003
The sec_context parameter should either be an existing security
context or NULL, indicating a new security context should be
initialized and the specified option set on the new context.
The option parameter should contain an OID that references the
option that the application wishes to set.
The value parameter should contain the value the option should
be set to. The size of the octet string will vary depending on
the option being set (analogous to the UNIX setsockopt
function).
1.6. Buffer Set Functions
These functions are needed to support other new functions added
in this section.
gss_create_empty_buffer_set
Inputs:
. None
Outputs:
. buffer_set SET OF OCTET STRING To be freed by caller using
gss_release_buffer_set.
. major_status INTEGER
. minor_status INTEGER
Return major_status codes:
. GSS_S_COMPLETE indicates that the function completed
successfully.
. GSS_S_FAILURE indicates that the requested operation failed
for reasons unspecified at the GSS-API level.
Creates a empty buffer set, to which members may subsequently be
added using the gss_add_buffer_set_member routine.
gss_add_buffer_set_member call
Inputs:
meder@mcs.anl.gov 20
GWD-R.P GSS-API Extensions February 2003
. member_buffer OCTET_STRING
. buffer_set SET OF OCTET STRING
Outputs:
. major_status INTEGER
. minor_status INTEGER
Return major_status codes:
. GSS_S_COMPLETE indicates that the function completed
successfully.
. GSS_S_FAILURE indicates that the requested operation failed
for reasons unspecified at the GSS-API level.
This function adds a buffer to a buffer set. The member_buffer
argument may be released after the completion of this call.
gss_release_buffer_set call
Inputs:
. buffer_set SET OF OCTET STRING
Outputs:
. major_status INTEGER
. minor_status INTEGER
Return major_status codes:
. GSS_S_COMPLETE indicates that the function completed
successfully and data was returned.
. GSS_S_FAILURE indicates that the requested operation failed
for reasons unspecified at the GSS-API level.
This function allows callers to release the storage associated
with a SET OF OCTET STRING allocated by another GSS-API call.
This call's specific behavior depends on the language and
programming environment within which a GSS-API implementation
operates, and is therefore detailed within applicable bindings
specifications; in particular, implementation and invocation of
meder@mcs.anl.gov 21
GWD-R.P GSS-API Extensions February 2003
this call may be superfluous (and may be omitted) within
bindings where memory management is automatic.
meder@mcs.anl.gov 22
GWD-R.P GSS-API Extensions February 2003
Changes to existing functions
This section contains changes to the behavior of the existing
GSSAPI functions.
1.7. gss_accept_sec_context
The gss_accept_sec_context call will now accept a non-NULL
security context, as created by the gss_set_sec_context_option
call, on initial call.
1.8. gss_init_sec_context
The gss_init_sec_context call will now accept a non-NULL
security context, as created by the gss_set_sec_context_option
call, on initial call.
1.9. gss_getMIC, gss_verifyMIC, gss_wrap, gss_unwrap
If the GSS_PROTECTION_FAIL_ON_CONTEXT_EXPIRATION option has been
set to 1 by the gss_set_sec_context_option call then these
functions should fail if the security context being used has
expired.
If the GSS_PROTECTION_FAIL_ON_CONTEXT_EXPIRATION option is set
to 0 then functions should continue to function as long as they
possibly can regardless of the expiration of security context.
Some implementation may not be able to continue functioning
after security context expiration.
Additional Desired Functionality
The following sections describe shortcomings in the GSSAPI and
propose possible schemes for modifying the API to address these
but do not lay out a specific proposal for change. It is the
authorsÆ intention to propose a scheme at a later date.
1.10. Token Framing
One major shortcoming in the GSS-API specification is that it
does not prescribe or recommend a standard mechanism independent
way of framing tokens generated by GSS-API functions.
We feel that the absence of a framing mechanism negates the
utility of the mech_type and similar parameters, since
demultiplexing tokens based on mechanism without said framing
becomes nearly impossible.
meder@mcs.anl.gov 23
GWD-R.P GSS-API Extensions February 2003
We realize that almost all mechanisms used to implement the GSS-
API provide their own framing mechanism and may not want to add
additional framing since this may hinder interoperability with
non-GSS-API using applications. Thus any proposed framing should
not be mandatory.
It is our opinion that any proposed framing mechanism should at
the bare minimum allow for the following:
1. A mechanism for determining the length of the token
2. A way of determining the mechanism that produced the token
3. A mechanism for identifying the token type, where token
type indicates the origin (e.g. context establishment,
application data à) of the token
Finally, it may be argued that framing could and should be done
at the application level, but even in this case a recommendation
would give the benefit of greater interoperability between
mechanisms which implement framing at the GSSAPI level.
1.11. Different levels of verbosity with gss_display_status
It is desirable to have different levels of error message
verbosity at different times. When returning an error message to
a user, simplicity is often the best course. Users tend to want
a simple description of the error and maybe a little guidance on
how to fix the problem. Long error messages tend to scare them
away.
On the other hand, if a developer or other user seriously
interested in debugging is reading the error message, the more
information the better.
The gss_display_status call currently offers no way to select
different levels of verbosity in the messages it returns. Some
possible ways of implementing this are:
. Add a way of passing in a flag to the gss_display_call
perhaps by defining more values for status type.
. Defining a predefined string at the beginning of all
strings returned by gss_display_status to indicate the
verbosity level of the string. This has the advantage that
the server can send these strings over the network to a
client that can decide the level of verbosity without
meder@mcs.anl.gov 24
GWD-R.P GSS-API Extensions February 2003
involving the server.
. Defining a new call, gss_display_status_ext, that has an
option to specify verbosity level.
meder@mcs.anl.gov 25
GWD-R.P GSS-API Extensions February 2003
Security Considerations
1.12. Credential export and import
Since exported credential buffers may contain sensitive
information (e.g. the credential itself) care must be taken to
maintain the privacy of this information. Precautions should
include:
. Storing the exported credential only in files with carefully
controlled access polices
. Not sending the exported credential over the network in the
clear (unencrypted)
. Being careful which processes are given access to the
credential
1.13. Delegation at any time and restricted delegation handling
Applications delegating credentials need to be sure that they
are delegating credentials only to other processes and systems
that can be trusted. Since credentials are often stored on disk,
compromises of systems can lead to stolen credentials from
trusted processes.
The use of restrictive policies is encouraged for this reason as
it can greatly limit the use of any stolen credential.
meder@mcs.anl.gov 26
GWD-R.P GSS-API Extensions February 2003
C-Bindings
The following are the C-bindings for the API extensions:
typedef gss_buffer_set_desc_struct {
size_t count;
gss_buffer_desc * elements;
} gss_buffer_set_desc, *gss_buffer_set_t;
OM_uint32
gss_create_empty_buffer_set(
OM_uint32 * minor_status,
gss_buffer_set_t * buffer_set)
OM_uint32
gss_add_buffer_set_member(
OM_uint32 * minor_status,
const gss_buffer_t member_buffer,
gss_buffer_set_t * buffer_set)
OM_uint32
gss_release_buffer_set(
OM_uint32 * minor_status,
gss_buffer_set_t buffer_set)
OM_uint32
gss_export_cred(
OM_uint32 * minor_status,
const gss_cred_id_t cred_handle,
const gss_OID desired_mech,
gss_OID * actual_mech,
OM_uint32 option_req,
const gss_buffer_t protection_key,
gss_buffer_t export_buffer);
OM_uint32
gss_import_cred(
OM_uint32 * minor_status,
gss_cred_id_t * output_cred_handle,
const gss_OID desired_mech,
gss_OID * actual_mech,
OM_uint32 option_req,
const gss_buffer_t import_buffer,
const gss_buffer_t protection_key,
OM_uint32 time_req,
meder@mcs.anl.gov 27
GWD-R.P GSS-API Extensions February 2003
OM_uint32 * time_rec);
OM_uint32
gss_init_delegation(
OM_uint32 * minor_status,
const gss_ctx_id_t context_handle,
const gss_cred_id_t cred_handle,
const gss_OID desired_mech,
const gss_OID_set extension_oids,
const gss_buffer_set_t extension_buffers,
const gss_buffer_t input_token,
OM_uint32 time_req,
gss_buffer_t output_token);
OM_uint32
gss_accept_delegation(
OM_uint32 * minor_status,
const gss_ctx_id_t context_handle,
const gss_OID_set extension_oids,
const gss_buffer_set_t extension_buffers,
const gss_buffer_t input_token,
OM_uint32 time_req,
OM_uint32 * time_rec,
gss_cred_id_t * delegated_cred_handle,
gss_OID mech_type,
gss_buffer_t output_token);
OM_uint32
gss_inquire_sec_context_by_oid(
OM_uint32 * minor_status,
const gss_ctx_id_t context_handle,
const gss_OID desired_object,
gss_buffer_set_t data_set);
OM_uint32
gss_inquire_cred_by_oid(
OM_uint32 * minor_status,
const gss_ced_id_t cred_handle,
const gss_OID desired_object,
gss_buffer_set_t * data_set);
OM_uint32
gss_set_sec_context_option(
OM_uint32 * minor_status,
meder@mcs.anl.gov 28
GWD-R.P GSS-API Extensions February 2003
gss_ctx_id_t * context_handle,
const gss_OID option,
gss_buffer_t value);
References
[1] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels," BCP 14, RFC 2119, March 1997.
[2] Foster, I., C. Kesselman, and S. Tuecke, "The Anatomy of
the Grid: Enabling Scalable Virtual Organizations,"
International Journal of Supercomputer Applications, 2001.
[3] Linn, J., "Generic Security Service Application Program
Interface, Version 2, Update 1," RFC 2743, January 2000.
[4] Wray, J., "Generic Security Service API Version 2, C-
bindings," RFC 2744, January 2000.
Acknowledgments
We are grateful to numerous colleagues for discussions on the
topics covered in this paper, in particular (in alphabetical
order, with apologies to anybody we've missed): Joe Bester,
Randy Butler, Carl Kesselman, Keith Jackson, Bill Johnston, Ian
Foster, Marty Humphrey, Cliff Neuman, Laura Pearlman, Frank
Siebenlist, Mary Thompson, Gene Tsudik.
This work was supported in part by the Mathematical,
Information, and Computational Sciences Division subprogram of
the Office of Advanced Scientific Computing Research, U.S.
Department of Energy, under Contract W-31-109-Eng-38; by the
Defense Advanced Research Projects Agency under contract N66001-
96-C-8523; by the National Science Foundation; and by the NASA
Information Power Grid project.
Change Log
Changes between version 0.6 and 0.7
1. Added protection_key parameter to gss_import_cred() and
gss_export_cred() functions.
Changes between version 0.5 and 0.6
2. Updated section on token framing
meder@mcs.anl.gov 29
GWD-R.P GSS-API Extensions February 2003
3. Added lifetime_req parameter to gss_accept_delegation
4. Changed formatting to comply with GGF standard
5. Added actual_mech parameter to gss_export_cred and
gss_import_cred
6. Updated C bindings
Changes between version 0.4 and 0.5:
1. Renamed delegation restrictions to more generic delegation
extensions.
2. Added gss_create_empty_buffer_set() and
gss_add_buffer_set_member()
3. Added gss_inquire_cred_by_oid()
Changes between version 0.3 and 0.4:
1. Added time_req argument to gss_init_delegation().
2. NULL credential to gss_init_delegation() means to use the
default credential.
3. Oids and buffers in calls to init_delegation and
accept_delegation are now sequences and not sets.
4. Added text to 2.2 stating essentially that only one
delegation is allowed to be in progress at a given time.
5. Revised text in 2.2.1 and 2.2.2 to attempt to clarify
restriction oids specify policy languages in restriction
buffers.
6. Added text to 2.3 about generic oids for retrieving
information from the credential and in particular an oid
for policies inserted by gss_init_delegation().
7. Added lifetime_rec output to gss_accept_delegation().
8. Added lifetime_req and lifetime_rec parameters to
gss_import_context().
9. Added section 2.4: gss_set_sec_context_option(). Deleted
section in section 3 that talked about wanting to do this.
10. Added new section 3 disussing changes to existing
functions with renumbering elsewhere in the document.
11. Added section 2.5, Housekeeping functions, with
subsection 2.5.1 describing the gss_release_buffer_set
call.
meder@mcs.anl.gov 30
GWD-R.P GSS-API Extensions February 2003
12. Message protection behavior on context expiration
is now defined by sections 2.4 and 3.3.
13. Added section 4.2 on the need for verbosity levels
in gss_display_status.
14. In Section 5.1 now use credential singular
consistently
15. In 2.2.1 and 2.2.2 renamed restrictions_oid to
restrictions_oid and restrictions_buffers to
restriction_buffers. Also indicated these may be
GSS_C_NO_OID_SET and GSS_C_NO_BUFFER_SET respectively.
16. 2.2.1 input_token: GSS_C_NO_BUFFER instead of NULL
17. 2.2.1 and 2.2.2 output_token: May be empty instead
of NULL
Contact Information
Samuel Meder
Distributed Systems Laboratory
Mathematics and Computer Science Division
Argonne National Laboratory
Argonne, IL 60439
Phone: 630-252-1752
Email: meder@mcs.anl.gov
Von Welch
University of Chicago
Email: welch@mcs.anl.gov
Steven Tuecke
Argonne National Laboratory
Email: tuecke@mcs.anl.gov
Doug Engert
Argonne National Laboratory
Email: deengert@anl.gov
Copyright Notice
Copyright (C) Global Grid Forum (2/20/2003). All Rights
Reserved.
This document and translations of it may be copied and furnished
to others, and derivative works that comment on or otherwise
explain it or assist in its implementation may be prepared,
meder@mcs.anl.gov 31
GWD-R.P GSS-API Extensions February 2003
copied, published and distributed, in whole or in part, without
restriction of any kind, provided that the above copyright
notice and this paragraph are included on all such copies and
derivative works. However, this document itself may not be
modified in any way, such as by removing the copyright notice or
references to the GGF or other organizations, except as needed
for the purpose of developing Grid Recommendations in which case
the procedures for copyrights defined in the GGF Document
process must be followed, or as required to translate it into
languages other than English.
The limited permissions granted above are perpetual and will not
be revoked by the GGF or its successors or assigns.
This document and the information contained herein is provided
on an "AS IS" basis and THE GLOBAL GRID FORUM DISCLAIMS ALL
WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY
WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT
INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY
OR FITNESS FOR A PARTICULAR PURPOSE.
Intellectual Property Statement
The GGF takes no position regarding the validity or scope of any
intellectual property or other rights that might be claimed to
pertain to the implementation or use of the technology described
in this document or the extent to which any license under such
rights might or might not be available; neither does it
represent that it has made any effort to identify any such
rights. Copies of claims of rights made available for
publication and any assurances of licenses to be made available,
or the result of an attempt made to obtain a general license or
permission for the use of such proprietary rights by
implementers or users of this specification can be obtained from
the GGF Secretariat.
The GGF invites any interested party to bring to its attention
any copyrights, patents or patent applications, or other
proprietary rights which may cover technology that may be
required to practice this recommendation. Please address the
information to the GGF Executive Director.
meder@mcs.anl.gov 32 | PAFTECH AB 2003-2026 | 2026-04-24 09:04:07 |