One document matched: draft-ietf-cat-gssv2-javabind-ifs-00.txt
Internet-Draft M. Smith
Common Authentication technology WG TIAA-CREF
<draft-ietf-cat-gssv2-javabind-ifs-00.txt> April 1999
Expires: September 1, 1999
A Java GSS binding, Part I: Interfaces
1. Status of this Memo
This document is an Internet-Draft and is in full conformance with
all provisions of Section 10 of RFC2026.
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/ietf/1id-abstracts.txt
The list of Internet-Draft Shadow Directories can be accessed at
http://www.ietf.org/shadow.html.
2. Abstract
This document specifies a set of Java interfaces representing the
semantics of the Generic Security Service API for the Java language.
3. Introduction and background
The Generic Security Service API (GSS-API)[1], a product of the CAT
working group, specifies a language- and mechanism-independent
interface by which application programs can use security services
(e.g. authentication and privacy). Companion documents specify
"language bindings" of the abstract GSS-API to particular languages.
This document represents part of such a language binding for the Java
Smith Document Expiration: 1 Sept 1999 [Page 1]
Java-GSS Bindings, Part I: Interfaces April 1999
language.
The present document is derived from a Java implementation of GSS at
TIAA-CREF (Javadoc format at [2]). A slightly different approach was
submitted to the Working Group in [3], which was discussed
extensively on the WG's mailing list and at the 44th IETF in
Minneapolis. That discussion centered on the question of whether the
Java binding ought to be specified in terms of "concrete classes" or
Java "interfaces." Consensus seemed to emerge on the proposition that
both interfaces and concrete classes would be useful; the latter
should implement the former. The proposal in [3] took the concrete
class approach and depends rather extensively on the use of
"constructors," which are not available in interfaces; on the other
hand, it contains richer functionality than the TIAA-CREF version in
some areas. The TIAA-CREF implementation, however, used the
interface approach from the beginning, and thus arrived at a mapping
of the GSS semantics which does not depend on constructors; in
addition, the TIAA-CREF approach appears to be somewhat simpler for
the application programmer in some areas.
The current TIAA-CREF implementation also reflects certain lessons
learned in the course of defining a Service Provider Interface
(SPI), to be used in the context of a GSS implementation consisting
of a "shim" layer called by applications, and a set of dynamically
loaded and registered mechanism providers, used by the shim to
provide actual security services to applications [4].
It seems useful, therefore, to describe the TIAA-CREF approach
formally in this Internet-Draft, so as to facilitate the comparison
and ultimate convergence of the two existing approaches in a final
specification.
4. Acknowledgments
This document is the result of work done in the Common Authentication
Technology (CAT) working group of the IETF. Special thanks are due to
Jack Kabat. Errors, of course, remain the author's own.
5. General
5.1. Repertoire of object types
The representation of the GSS-API in this document consists of
several Java interfaces, plus one Java class (the GSSException class,
which must be a class rather than an interface as a Java
requirement). For the sake of brevity, general issues of binding, as
well as detailed semantics of the GSS calls, are not discussed in
Smith Document Expiration: 1 Sept 1999 [Page 2]
Java-GSS Bindings, Part I: Interfaces April 1999
this document.
In this document, we shall employ inaccurate phrases like "instance
of X," "an X," or even "Xs," where X is the name of an interface, as
shorthand for the more accurate, but hopelessly cumbersome, "(an)
instance(s) of a class implementing X."
The interfaces defined here are:
GSSImplementation
GSSCredential
GSSName
GSSMechName
GSSContextHatchery
GSSSecurityContext
GSSOIDString
GSSStatus
GSSPerMessageCallResult
The single class defined here is:
GSSException
5.2. Operational paradigm
The "master class" for a Java GSS implementation is an instance of
GSSImplementation. Applications that need to use GSS services must
obtain a reference to such an instance. The means by which this
reference is obtained are not specified by this document, and are
left as a local matter; for some suggestions, however, see section 8
below.
The GSSImplementation instance provides methods which generate
instances of the interfaces GSSName and GSSCredential; these
respectively encapsulate the GSS entities "internal name" and
"credential". GSSImplementation also provides a method which returns
an instance of GSSContextHatchery. This interface, which does not
directly correspond to any entity defined in abstract GSS, is
provided for the convenience of the programmer, and to adapt the
context establishment calls of abstract GSS to Java idiom. It
permits the application programmer to set selectively those of the
numerous parameters required for GSS context calls that he or she
needs, to take reasonable defaults for those not explicitly
specified, and to obtain a GSSSecurityContext based on those
parameters. GSSSecurityContext encapsulates the GSS notion of a
"security context", and provides methods for its use to provide
security services for messages.
Smith Document Expiration: 1 Sept 1999 [Page 3]
Java-GSS Bindings, Part I: Interfaces April 1999
Some GSS functions specify that a mechanism-specific type of
"internal name" -- a "name for mechanism" in abstract GSS -- must be
supplied as a parameter or will be returned as a result. This feature
of abstract GSS is reflected in this binding by the interface
GSSMechName, which extends GSSName but encapsulates a "name for
mechanism" rather than a (potentially multi-mechanism) generic name.
A GSS-specific encapsulation of an ASN.1 OID, GSSOIDString, is also
provided, to avoid depending on outside packages mapping ASN.1; this
decision was made in order to avoid the excess baggage of unneeded
ASN.1 functionality.
The various functions of abstract GSS tend to follow a common design
pattern in terms of "output parameters"; in particular, it is
commonplace to find a major and minor status output, frequently
accompanied by an "output token." This set of associated output
parameters is encapsulated in the interface GSSStatus, which also
incorporates methods corresponding to some of the GSS calls that
reference statuses.
GSSStatus is extended by the interface GSSPerMessageCallResult, which
adds to GSSStatus certain additional output parameters returned by
per-message calls on a security context.
GSSStatus and GSSPerMessageCallResult are frequently the return types
of methods of the various GSS interfaces.
A concrete class, GSSException, is also provided. Java requires that
exceptions extend the class java.lang.Exception, and thus they must
be concrete classes. GSSException encapsulates (inter alia) an
instance of GSSStatus; thus the consistent appearance of the various
elements of status (major status, minor status, and possible output
token) across both successful and failed method invocations is
preserved.
In the following section, the various interfaces (and the single
class) defined by the Java binding are described in detail. A
subsequent section cross-references the abstract GSS calls and their
parameters to methods and members of the Java-GSS interfaces.
6. The interfaces (and the class) of the Java GSS binding
6.1. GSSOIDString
Encapsulation of an ASN.1 OID string for GSS purposes.
Actual implementations of this interface could be expected to provide
constructors from an array of integers and/or a String containing a
Smith Document Expiration: 1 Sept 1999 [Page 4]
Java-GSS Bindings, Part I: Interfaces April 1999
dotted-decimal representation of an OID.
This interface in the TIAA-CREF implementation is quite minimal,
providing only two methods, equals() and toString(). (Note: The
repertoire of methods defined for the equivalent of this interface in
[3] is considerably richer and may be preferable.)
6.1.1. Methods
6.1.1.1. equals()
The standard Java equals() method; returns true if the parameter is a
GSSOIDString object whose value is the same as that of the
GSSOIDString object being invoked.
6.1.1.2. toString()
The standard Java toString() method; returns a String containing a
dotted-decimal representation of the value of this GSSOIDString
object.
6.2. GSSImplementation
The "master class" for GSS implementations. All other interfaces are
obtained, directly or indirectly, from methods of this class. A
number of GSS constants are also defined as static members of this
interface, or (in two cases) as methods of this interface.
6.2.1. Fields and constants
The various GSS OID constants, for convenience, are each mapped twice
into Java: once as static GSSOIDString objects, and once as static
arrays of integers. The latter have the same names as the former,
with the suffix "_array" added.
Note that the abstract GSS constants GSS_C_NO_CREDENTIAL and
GSS_C_NO_NAME are mapped to Java _methods_, rather than fields. These
methods return instances of GSSCredential and GSSName respectively;
the expectation is that implementations of GSSCredential and GSSName
will in many cases be the best place to incorporate no-credential or
no-name behavior, rather than placing this behavior in special-case
paths of other classes (e.g., implementations of GSSSecurityContext).
static int GSS_C_ACCEPT
static int GSS_C_BOTH
static int GSS_C_INITIATE
static GSSOIDString GSS_C_NO_OID
Smith Document Expiration: 1 Sept 1999 [Page 5]
Java-GSS Bindings, Part I: Interfaces April 1999
static int[] GSS_C_NT_ANONYMOUS_array
static GSSOIDString GSS_C_NT_ANONYMOUS
static int[] GSS_C_NT_EXPORT_NAME_array
static GSSOIDString GSS_C_NT_EXPORT_NAME
static int[] GSS_C_NT_HOSTBASED_SERVICE_array
static GSSOIDString GSS_C_NT_HOSTBASED_SERVICE
static int[] GSS_C_NT_MACHINE_UID_NAME_array
static GSSOIDString GSS_C_NT_MACHINE_UID_NAME
static int[] GSS_C_NT_STRING_UID_NAME_array
static GSSOIDString GSS_C_NT_STRING_UID_NAME
static int[] GSS_C_NT_USER_NAME_array
static GSSOIDString GSS_C_NT_USER_NAME
6.2.2. Methods
6.2.2.1. GSSCredential acquireCredential(int lifetimeReq,
GSSOIDString[] desiredMechs, int credentialUsage)
Mapping of GSS_Acquire_Credential, with null name parameter (for
default credentials)
6.2.2.2. GSSCredential acquireCredential(GSSName name, int lifetimeReq,
GSSOIDString[] desiredMechs, int credentialUsage)
Mapping of GSS_Acquire_Credential
6.2.2.3. GSSContextHatchery getContextHatchery()
This method returns an instance of GSSContextHatchery (q.v., 6.9)
which can be used to construct parameter sets for context initiation
and acceptance. See also section 5.2 above.
6.2.2.4. GSSCredential GSS_C_NO_CREDENTIAL()
Mapping of the GSS constant GSS_C_NO_CREDENTIAL. Here this takes the
form of a method, which returns an object implementing GSSCredential,
corresponding to credential-related functionality for the default
identity in the current processing context.
6.2.2.5. GSSName GSS_C_NO_NAME()
Mapping of the GSS constant GSS_C_NO_NAME. Here this takes the form
of a method, which returns an object implementing GSSName,
corresponding to name-related functionality for the default identity
in the current processing context.
Smith Document Expiration: 1 Sept 1999 [Page 6]
Java-GSS Bindings, Part I: Interfaces April 1999
6.2.2.6. GSSSecurityContext importContext(byte[] interprocessToken)
Mapping of GSS_Import_security_context.
6.2.2.7. GSSName importName(byte[] externalrep, GSSOIDString nametype)
This is the mapping of GSS_Import_name.
6.2.2.8. GSSOIDString[] indicateMechs()
Mapping of GSS_Indicate_mechs
6.2.2.9. GSSOIDString[] inquireNamesForMech(GSSOIDString mechoid)
Mapping of GSS_Inquire_names_for_mech.
6.3. GSSName
This represents the encapsulation of the GSS notion of a "name."
A subinterface of this interface, GSSMechName (q.v. infra, 6.4),
encapsulates the GSS notion of a "name for mechanism."
6.3.1. Methods
6.3.1.1. GSSMechName canonicalize(GSSOIDString mechoid)
The mapping of GSS_Canonicalize_name.
6.3.1.2. boolean compare(GSSName othername)
Mapping of GSS_Compare_name
6.3.1.3. java.lang.String getNameForDisplay()
Part of the mapping of GSS_Display_name.
6.3.1.4. java.lang.String getNameTypeForDisplay()
Part of the mapping of GSS_Display_name.
6.3.1.5. GSSOIDString[] inquireMechs()
The mapping of GSS_Inquire_mechs_for_name.
Smith Document Expiration: 1 Sept 1999 [Page 7]
Java-GSS Bindings, Part I: Interfaces April 1999
6.4. GSSMechName
A mapping of the GSS notion of a "name for mechanism". Extends
GSSName (q.v. supra, 6.3).
6.4.1. Methods (in addition to those of GSSName)
6.4.1.1. byte[] export()
Mapping of GSS_Export_name.
6.5. GSSCredential
This interface encapsulates the abstract GSS notion of a
"credential".
6.5.1. Methods
6.5.1.1. GSSCredential addCredential(GSSName desiredName, int timeReq,
GSSOIDString desiredMech, int credentialUsage)
Mapping of one of the versions of GSS_Add_credential.
6.5.1.2. void addCredentialInPlace(GSSName desiredName, int timeReq,
GSSOIDString desiredMech, int credentialUsage)
Mapping of the other version of GSS_Add_credential.
6.5.1.3. int getLifetimeAccept(GSSOIDString mechoid)
Mapping of "lifetime_rec_accept" return value from
GSS_Inquire_credential_by_mech.
6.5.1.4. int getLifetime()
Mapping of "lifetime_rec" return value from GSS_Inquire_credential.
6.5.1.5. int getLifetimeInitiate(GSSOIDString mechoid)
Mapping of "lifetime_rec_initiate" return value from
GSS_Inquire_credential_by_mech.
6.5.1.6. GSSOIDString[] getMechSet()
Mapping of "mech_set" return value from GSS_Inquire_credential.
Smith Document Expiration: 1 Sept 1999 [Page 8]
Java-GSS Bindings, Part I: Interfaces April 1999
6.5.1.7. GSSName getName()
Mapping of "cred_name" return value from GSS_Inquire_credential.
6.5.1.8. GSSMechName getName(GSSOIDString mechoid)
Mapping of "cred_name" return value from
GSS_Inquire_credential_by_mech.
6.5.1.9. int getUsage()
Mapping of "cred_usage" return value from GSS_Inquire_credential.
6.5.1.10. int getUsage(GSSOIDString mechoid)
Mapping of "cred_usage" return value from
GSS_Inquire_credential_by_mech.
6.6. GSSStatus
As described above (5.2), this interface collects a number of the
common "output parameters" from various GSS calls. An instance of
GSSStatus is manufactured and returned by various methods of the GSS
interfaces, and there is also an instance in GSSException (q.v.
infra, 6.8).
This interface is extended by GSSPerMessageCallResult below (6.7).
6.6.1. Fields
This interface defines a number of static constants corresponding to
the GSS major status and informatory status values. These have the
same names as in the GSS spec [1].
static short GSS_S_BAD_BINDINGS
static short GSS_S_BAD_MECH
static short GSS_S_BAD_MIC
static short GSS_S_BAD_NAME
static short GSS_S_BAD_NAMETYPE
static short GSS_S_BAD_QOP
static short GSS_S_BAD_SIG
static short GSS_S_BAD_STATUS
static short GSS_S_COMPLETE
static short GSS_S_CONTEXT_EXPIRED
static short GSS_S_CONTINUE_NEEDED
static short GSS_S_CREDENTIALS_EXPIRED
static short GSS_S_DEFECTIVE_CREDENTIAL
static short GSS_S_DEFECTIVE_TOKEN
Smith Document Expiration: 1 Sept 1999 [Page 9]
Java-GSS Bindings, Part I: Interfaces April 1999
static short GSS_S_DUPLICATE_ELEMENT
static short GSS_S_DUPLICATE_TOKEN
static short GSS_S_FAILURE
static short GSS_S_GAP_TOKEN
static short GSS_S_NAME_NOT_MN
static short GSS_S_NO_CONTEXT
static short GSS_S_NO_CRED
static short GSS_S_OLD_TOKEN
static short GSS_S_UNAUTHORIZED
static short GSS_S_UNAVAILABLE
static short GSS_S_UNSEQ_TOKEN
6.6.2. Methods
6.6.2.1. java.lang.String displayMajorStatus()
Obtain an intelligible printable message corresponding to the major
status value.
6.6.2.2. java.lang.String displayMinorStatus(GSSOIDString oid)
Obtain an intelligible printable message corresponding to the minor
status value.
6.6.2.3. boolean getContinueNeeded()
Get the continue-needed status.
6.6.2.4. boolean getDuplicateToken()
Get the duplicate token status.
6.6.2.5. short getFlags()
Get the flags related to token sequencing and aging, and context
establishment completion.
6.6.2.6. boolean getGapToken()
Get the gap token status.
6.6.2.7. short getMajorStatus()
Retrieve the major status value.
Smith Document Expiration: 1 Sept 1999 [Page 10]
Java-GSS Bindings, Part I: Interfaces April 1999
6.6.2.8. short getMinorStatus()
Retrieve the minor status value.
6.6.2.9. boolean getOldToken()
Get the old token status.
6.6.2.10. byte[] getOperationOutput()
Get output data, from context establishment or per-message call to
GSSSecurityContext. This may be a context token or a message token or
a message, depending on the call.
6.6.2.11. boolean getUnseqToken()
Get the unsequenced token status.
6.7. GSSPerMessageCallResult extends GSSStatus
This interface extends GSSStatus and constitutes the return value of
some varieties of per-message calls on a context. It adds to
GSSStatus "get" functions for some per-message output parameters.
6.7.1. Methods (in addition to those of GSSStatus)
6.7.1.1. boolean getConfState()
Maps a returned value from the wrap and unwrap calls.
6.7.1.2. short getQop()
Maps a returned value from the wrap and unwrap calls.
6.8. GSSException
Because exceptions in Java must extend the class java.lang.Exception,
and therefore must be concrete classes rather than interfaces, this
is the only class (as opposed to interface) defined in the interfaces
portion of the GSS Java binding spec.
6.8.1. Constructors
6.8.1.1. GSSException(GSSStatus status)
Smith Document Expiration: 1 Sept 1999 [Page 11]
Java-GSS Bindings, Part I: Interfaces April 1999
6.8.1.2. GSSException()
6.8.2. Methods
6.8.2.1. GSSStatus getStatus()
Method to obtain the status values associated with this exception.
6.9. GSSContextHatchery
This interface facilitates the collection of all the parameters
relevant to context establishment -- user credential, services
requested, target name, channel bindings, etc. -- before a request is
actually made to initialize or accept a context.
The expectation is that applications will obtain an instance of this
interface from GSSImplementation (using getContextHatchery()), set
the necessary parameters (which map the numerous input parameters to
GSS_Accept_sec_context and GSS_Init_sec_context) and then call
bindForInit() or bindForAccept() to obtain an actual instance of
GSSSecurityContext. The accept() and init() methods of the latter are
then called for all subsequent phases of context setup after the
first.
This class does not correspond directly to any explicit notion in
abstract GSS. It is defined in order to avoid the bulky (13 items!)
parameter list to GSS_Init_sec_context and at the same time to avoid
returning a GSSSecurityContext object (which for some implementations
will require binding to a mechanism) before all parameters relevant
to mechanism choice have been supplied.
GSSContextHatchery objects must be re-usable -- that is, when
bindForAccept() or bindForInit() are called, a context will be
generated depending solely on the present state of the various
parameters, without regard to the hatchery's previous reproductive
history.
6.9.1. Methods
6.9.1.1. void setAnonReq(boolean anonReq)
One of the "set" methods that replace the numerous parameters of
GSS_Init_sec_context and GSS_Accept_sec_context. If this parameter is
not set, the default is "false".
Smith Document Expiration: 1 Sept 1999 [Page 12]
Java-GSS Bindings, Part I: Interfaces April 1999
6.9.1.2. void setChanBindings(Object[] chanBindings)
One of the "set" methods that replace the numerous parameters of
GSS_Init_sec_context and GSS_Accept_sec_context. For the
representation of channel bindings, see 7.1.4 below. If this
parameter is not set, the default is null, and the context will not
be bound to a channel.
6.9.1.3. void setConfReq(boolean confReq)
One of the "set" methods that replace the numerous parameters of
GSS_Init_sec_context and GSS_Accept_sec_context. If this parameter is
not set, the default is "true".
6.9.1.4. void setDelegReq(boolean delegReq)
One of the "set" methods that replace the numerous parameters of
GSS_Init_sec_context and GSS_Accept_sec_context. If this parameter is
not set, the default is "false".
6.9.1.5. void setIntegReq(boolean integReq)
One of the "set" methods that replace the numerous parameters of
GSS_Init_sec_context and GSS_Accept_sec_context. If this parameter is
not set, the default is "true".
6.9.1.6. void setlifetimeReq(int lifetimeReq)
One of the "set"methods that replace the numerous parameters of
GSS_Init_sec_context and GSS_Accept_sec_context. If this parameter is
not set, the default is zero, which requests a default value
determined by the implementation.
6.9.1.7. void setMechType(GSSOIDString mechType)
One of the "set"methods that replace the numerous parameters of
GSS_Init_sec_context and GSS_Accept_sec_context. If this parameter is
not set, the default is GSS_C_NO_OID, which requests the default
mechanism.
6.9.1.8. void setMutualReq(boolean mutualReq)
One of the "set"methods that replace the numerous parameters of
GSS_Init_sec_context and GSS_Accept_sec_context. If this parameter
is not set, the default is "true".
Smith Document Expiration: 1 Sept 1999 [Page 13]
Java-GSS Bindings, Part I: Interfaces April 1999
6.9.1.9. void setReplayDetectReq(boolean replayDetectReq)
One of the "set"methods that replace the numerous parameters of
GSS_Init_sec_context and GSS_Accept_sec_context. If this parameter is
not set, the default is "true".
6.9.1.10. void setSequenceReq(boolean sequenceReq)
One of the "set"methods that replace the numerous parameters of
GSS_Init_sec_context and GSS_Accept_sec_context. If this parameter is
not set, the default is "true".
6.9.1.11. GSSSecurityContext bindForAccept(byte[] token)
Used to obtain a GSSSecurityContext object on the accepting side of a
connection. Parameters relevant to context acceptance (i.e.
credential and channel bindings) should have been set, if other than
default values are desired, before calling this method. The input
token parameter contains the context token received from the
initiator.
6.9.1.12. GSSSecurityContext bindForAccept(inputStream inputToken,
outputStream outputToken)
Used to obtain a GSSSecurityContext object on the accepting side of a
connection. Parameters relevant to context acceptance (i.e.
credential and channel bindings) should have been set, if other than
default values are desired, before calling this method. The input
token stream contains the context token received from the initiator;
the output token stream will contain the output token (if any).
6.9.1.13. GSSSecurityContext bindForInit(GSSName targname)
Used to obtain a GSSSecurityContext object on the initiating side of
a connection. Parameters relevant to context acceptance (i.e.
credential and channel bindings, lifetime, and service flags) should
have been set, if other than default values are desired, before
calling this method. The targname parameter contains a GSSName
indicating the accepting side of the context.
6.9.1.14. GSSSecurityContext bindForInit(GSSName targname, outputStream
outputToken)
Used to obtain a GSSSecurityContext object on the initiating side of
a connection. Parameters relevant to context acceptance (i.e.
credential and channel bindings, lifetime, and service flags) should
have been set, if other than default values are desired, before
calling this method. The targname parameter contains a GSSName
Smith Document Expiration: 1 Sept 1999 [Page 14]
Java-GSS Bindings, Part I: Interfaces April 1999
indicating the accepting side of the context; the output token stream
will contain the output token (if any).
6.9.1.15. GSSStatus getLastStatus()
Returns the GSSStatus object generated by the most recent
bindForInit() or bindForAccept() method. Note that the
getLastStatus() of the context itself returned by these calls will
NOT contain a GSSStatus resulting from the initial operation;
getLastStatus() of the context itself will only be valid after a
method of the context itself has been called. This is because the
operation which returns the context may in some cases produce an
output token which is not, or not entirely, the output of the
particular mechanism selected (e.g. when the mechanism has been
selected by SPNEGO[5]).
6.10. GSSSecurityContext
This encapsulates the GSS notion of a security context; nearly all
the functions of abstract GSS which reference a security context are
mapped to methods of this interface.
As noted above (5.2 and 6.9), GSSSecurityContexts are obtained
initially from GSSContextHatchery by calling the latter's
bindForInit() or bindForAccept() methods; then the context's own
init() or accept() method may need to be called as well, for
subsequent phases of context establishment.
6.10.1. Methods
6.10.1.1. GSSStatus accept(byte[] inputToken)
A mapping of "continuation" calls to GSS_accept_sec_context (the
initial call maps to bindForAccept of GSSContextHatchery, above,
6.9.1.11).
6.10.1.2. boolean accept(java.io.InputStream inputToken,
java.io.OutputStream outputToken)
A "stream-flavored" mapping of "continuation" calls to
GSS_accept_sec_context (the initial stream-flavored call maps to
bindForAccept of GSSContextHatchery, above, 6.9.1.12). The return
value indicates whether or not context establishment is locally
complete.
Smith Document Expiration: 1 Sept 1999 [Page 15]
Java-GSS Bindings, Part I: Interfaces April 1999
6.10.1.3. byte[] export()
Mapping of GSS_Export_security_context.
6.10.1.4. boolean getAnonState()
One of the mappings of a returned value from the context-
establishment calls.
6.10.1.5. boolean getConfAvailState()
One of the mappings of a returned value from the context-
establishment calls.
6.10.1.6. java.lang.Class[] getContextTokenClasses()
Utility function to tell callers what kinds of objects are acceptable
as context-establishment tokens.
6.10.1.7. GSSCredential getDelegatedCredential()
One of the mappings of a returned value from the context-
establishment calls.
6.10.1.8. boolean getDelegState()
One of the mappings of a returned value from the context-
establishment calls.
6.10.1.9. boolean getIntegAvailState()
One of the mappings of a returned value from the context-
establishment calls.
6.10.1.10. GSSStatus getLastStatus()
Utility function, intended to supply some of the "output parameter"
functionality required by the abstract GSS-API. Returns the GSSStatus
object generated by the last operation (context-establishment or per-
message) on this context. Note that this excludes operations on the
GSSContextHatchery which produced the present context; that is,
bindForAccept() and bindForInit() will NOT set the GSSStatus
retrieved from the context so produced, but only that of the
hatchery that produced it. This is because these operations may in
some cases produce an output token which is not, or not entirely, the
output of the particular mechanism selected (e.g. when the mechanism
has been selected by SPNEGO[5]).
Smith Document Expiration: 1 Sept 1999 [Page 16]
Java-GSS Bindings, Part I: Interfaces April 1999
6.10.1.11. int getLifetimeRec()
One of the mappings of a returned value from the context-
establishment calls.
6.10.1.12. GSSOIDString getMechType()
One of the mappings of a returned value from the context-
establishment calls.
6.10.1.13. java.lang.Class[] getMessageTokenClasses()
Utility function to tell callers what kinds of objects are acceptable
as message tokens.
6.10.1.14. GSSPerMessageCallResult getMIC(int qopreq, byte[] message)
Mapping of GSS_Get_MIC.
6.10.1.15. boolean getMutualState()
One of the mappings of a returned value from the context-
establishment calls.
6.10.1.16. boolean getProtReadyState()
One of the mappings of a returned value from the context-
establishment calls.
6.10.1.17. boolean getReplayDetState()
One of the mappings of a returned value from the context-
establishment calls.
6.10.1.18. boolean getSequenceState()
One of the mappings of a returned value from the context-
establishment calls.
6.10.1.19. GSSMechName getSrcName()
One of the mappings of a returned value from the context-
establishment calls.
6.10.1.20. boolean getTransState()
One of the mappings of a returned value from the context-
establishment calls.
Smith Document Expiration: 1 Sept 1999 [Page 17]
Java-GSS Bindings, Part I: Interfaces April 1999
6.10.1.21. int getWrapSizeLimit(int outputSize)
Mapping of GSS_Get_wrap_size_limit
6.10.1.22. GSSStatus init(byte[] inputToken)
A mapping of continuation calls to GSS_init_sec_context; the initial
call maps to bindForInit() of GSSContextHatchery, above, 6.9.1.13.
The parameter contains a context token returned by the context
acceptor.
6.10.1.23. boolean init(java.io.InputStream inputToken,
java.io.OutputStream outputToken)
A "stream-flavored" mapping of continuation calls to
GSS_init_sec_context; the stream-flavored version of the initial call
maps to bindForInit() of GSSContextHatchery, above, 6.9.1.14. The
inputToken stream contains a context token returned by the context
acceptor; the outputToken stream will receive an ouput token (if any
is generated) to be sent back to the acceptor. The return value
indicates whether or not context establishment is locally complete.
6.10.1.24. boolean locallyInitiated()
One of the mappings of a returned value from the context-
establishment calls.
6.10.1.25. boolean open()
One of the mappings of a returned value from the context-
establishment calls.
6.10.1.26. GSSStatus processToken(byte[] inputToken)
Mapping of GSS_Process_context_token.
6.10.1.27. GSSPerMessageCallResult unwrap(byte[] message)
A mapping of GSS_Unwrap.
6.10.1.28. GSSPerMessageCallResult unwrap(java.io.InputStream
wrappedMessage, java.io.OutputStream message)
A mapping of GSS_Unwrap.
Smith Document Expiration: 1 Sept 1999 [Page 18]
Java-GSS Bindings, Part I: Interfaces April 1999
6.10.1.29. GSSPerMessageCallResult verifyMIC(byte[] message, byte[]
token)
Mapping of verifyMIC.
6.10.1.30. GSSPerMessageCallResult wrap(boolean confreq, int qopreq,
byte[] message)
A mapping of GSS_Wrap.
6.10.1.31. GSSPerMessageCallResult wrap(boolean confreq, int qopreq,
java.io.InputStream message, java.io.OutputStream wrappedMessage)
A mapping of GSS_Wrap.
7. Cross reference
This section lists GSS-API, constructs, constants and calls and
indicates, for each, how it is mapped in the present specification.
7.1. Constructs
7.1.1. Credentials
Credential functionality is mapped, generally, to the GSSCredential
interface. Instances of this interface are produced by the methods
acquireCredential() and GSS_C_NO_CREDENTIAL() of GSSImplementation
and getDelegatedCredential() of GSSSecurityContext, and by
addCredential() of GSSCredential itself. The method
GSS_C_NO_CREDENTIAL() of GSSImplementation provides a GSSCredential
object embodying "default credential" functionality.
7.1.2. Security contexts
The GSS notion of a "security context" is in general mapped to the
interface GSSSecurityContext. GSSSecurityContexts are produced from
GSSContextHatchery objects, which in turn are obtained from the
getContextHatchery method of GSSImplementation. GSSContextHatchery
provides two methods, bindForInit() and bindForAccept(), which are
called once the context establishment parameters of the
GSSContextHatchery have been set to the desired values. These two
methods serve the function of the first GSS_Init_sec_context and the
first GSS_Accept_sec_context call respectively; by "first" is meant
the versions of those calls (as defined in abstract GSS) which take a
null credential handle, and create and return a credential handle to
the caller. "Continuation" calls to GSS_Init_sec_context and
GSS_Accept_sec_context are mapped to the init() and accept() methods
of GSSSecurityContext itself.
Smith Document Expiration: 1 Sept 1999 [Page 19]
Java-GSS Bindings, Part I: Interfaces April 1999
7.1.3. Names
The GSS notion of an "internal name" is in general mapped to the
interface GSSName; instances of this interface are produced by the
methods importName() and GSS_C_NO_NAME() of GSSImplementation, and by
one of the versions of the getName() method of GSSCredential. An
extension of this interface, GSSMechName, maps the GSS notion of a
"name for mechanism"; GSSMechNames are produced by the canonicalize()
method of GSSName and the getSrcName() method of GSSSecurityContext,
as well as a version of the getName() method of GSSCredential which
specifies a mechanism.
7.1.4. Channel bindings
Channel bindings are represented as an array of Objects. In general,
the nature of these objects cannot be specified in advance, since it
may depend on transport protocol and/or application requirements.
Two different flavors of channel binding, however, must be acceptable
to all mechanism implementations:
1) That consisting of three elements: a java.net.InetAddress
representing the initiator, a java.net.InetAddress representing the
acceptor, and an arbitrary byte[] determined by the communicating
applications; and
2) that consisting of the model described in section 5.11 of [6],
namely, five elements as follows: an Integer giving the initiator's
addresstype, a byte[] giving the initator's address in accordance
with that type, an Integer giving the acceptor's address type, a
byte[] giving the acceptor's address in accordance with that type,
and a byte[] containing arbitrary application data.
For the second of these models, Integer constants are defined for the
addresstype codes in GSSImplementation, corresponding to those
defined in [6], section 5.11.
7.1.5. Status reporting
An interface, GSSStatus, is defined which contains the major, minor,
and informatory status codes defined by GSS, plus a byte[] for output
tokens and messages. This interface also contains methods to query
individual portions of the status code fields, and to obtain
printable messages in the form of Java Strings for the major and
minor status values. An extension to GSSStatus,
GSSPerMessageCallResult, adds methods to obtain per-message
information regarding replay detection and sequencing. GSSStatus and
GSSPerMessageCallResult frequently constitute the return values of
per-message and context-establishment calls, and are also available
Smith Document Expiration: 1 Sept 1999 [Page 20]
Java-GSS Bindings, Part I: Interfaces April 1999
from the getLastStatus() methods of GSSSecurityContext and
GSSContextHatchery.
7.2. Calls
7.2.1. GSS_Acquire_cred
Maps to acquireCredential methods of GSSImplementation
7.2.2. GSS_Release_cred
Not mapped. Relies on normal Java object life cycle mechanisms.
7.2.3. GSS_Inquire_cred
Maps to the following "get" methods of GSSCredential:
int getLifetime()
GSSOIDString[] getMechSet()
GSSName getName()
int getUsage()
7.2.4. GSS_Add_cred
Maps to the addCredential and addCredentialInPlace calls of
GSSCredential.
7.2.5. GSS_Inquire_cred_by_mech
Maps to the following "get" methods of GSSCredential:
int getLifetimeAccept(GSSOIDString mechoid)
int getLifetimeInitiate(GSSOIDString mechoid)
GSSMechName getName(GSSOIDString mechoid)
int getUsage(GSSOIDString mechoid)
7.2.6. GSS_Init_sec_context
In abstract GSS, there are two flavors of this call: one, the
"initial" call, is made without a context handle parameter, and has
the effect of creating a context de novo. The other flavor, in which
an existing credential context handle is passed as a parameter, is
referred to as a "continuation" call, and is used when context
initiation requires that one or more context tokens returned by the
acceptor must be processed. These two flavors of the call are mapped
differently in this binding. The initial call maps to bindForInit()
Smith Document Expiration: 1 Sept 1999 [Page 21]
Java-GSS Bindings, Part I: Interfaces April 1999
of GSSContextHatchery, which returns a reference to an instance of
GSSSecurityContext, and the continuation call maps to init() of the
GSSSecurityContext itself.
One parameter of the initial call -- the target name -- is passed as
a parameter to bindForInit(). The others are mapped by the following
"set" methods of GSSContextHatchery:
void setAnonReq(boolean anonReq)
void setChanBindings(java.lang.Object[] chanBindings)
void setConfReq(boolean confReq)
void setCredential(GSSCredential cred)
void setDelegReq(boolean delegReq)
void setIntegReq(boolean integReq)
void setlifetimeReq(int lifetimeReq)
void setMechType(GSSOIDString mechType)
void setMutualReq(boolean mutualReq)
void setReplayDetectReq(boolean replayDetectReq)
void setSequenceReq(boolean sequenceReq)
The outputs from GSS_Init_sec_context are mapped to two sets of "get"
methods:
1) the following "get" methods of GSSStatus:
short getMajorStatus()
short getMinorStatus()
boolean getContinueNeeded()
byte[] getOperationOutput()
and 2) the following "get" methods of GSSSecurityContext:
boolean getDelegState()
boolean getIntegAvailState()
int getLifetimeRec()
GSSOIDString getMechType()
boolean getMutualState()
boolean getProtReadyState()
boolean getReplayDetState()
boolean getSequenceState()
GSSMechName getSrcName()
boolean getTransState()
boolean open()
Smith Document Expiration: 1 Sept 1999 [Page 22]
Java-GSS Bindings, Part I: Interfaces April 1999
7.2.7. GSS_Accept_sec_context
In abstract GSS, there are two flavors of this call: one, the
"initial" call, is made without a context handle parameter, and has
the effect of creating a context de novo. The other flavor, in which
an existing credential context handle is passed as a parameter, is
referred to as a "continuation" call, and is used when context
acceptance requires that a second or further context token received
from the initiator must be processed. These two flavors of the call
are mapped differently in this binding. The initial call maps to
bindForAccept() of GSSContextHatchery, which returns a reference to
an instance of GSSSecurityContext, and the continuation call maps to
accept() of the GSSSecurityContext itself.
One parameter of the initial call -- the initial token received from
the initiator -- is passed as a parameter to bindForAccept(). The
others are mapped by the following "set" methods of
GSSContextHatchery:
void setChanBindings(java.lang.Object[] chanBindings)
void setCredential(GSSCredential cred)
The outputs from GSS_Init_sec_context are mapped to two sets of "get"
methods:
1) the following "get" methods of GSSStatus:
short getMajorStatus()
short getMinorStatus()
boolean getContinueNeeded()
byte[] getOperationOutput()
and 2) the following "get" methods of GSSSecurityContext:
boolean getDelegState()
boolean getIntegAvailState()
int getLifetimeRec()
GSSOIDString getMechType()
boolean getMutualState()
boolean getProtReadyState()
boolean getReplayDetState()
boolean getSequenceState()
GSSMechName getSrcName()
boolean getTransState()
boolean open()
GSSCredential getDelegatedCredential()
Smith Document Expiration: 1 Sept 1999 [Page 23]
Java-GSS Bindings, Part I: Interfaces April 1999
7.2.8. GSS_Delete_sec_context
Not mapped; the normal Java object lifecycle mechanisms are used.
7.2.9. GSS_Process_context_token
Maps to processToken() method of GSSSecurityContext. Return values
are available from methods of the GSSStatus object.
7.2.10. GSS_Context_time
Maps to getLifetimeRec() of GSSSecurityContext.
7.2.11. GSS_Inquire_Context
Maps to the same "get" methods as the return values of
GSS_Init_sec_context and GSS_Accept_sec_context (see above, 7.2.6 and
7.2.7).
7.2.12. GSS_Wrap_size_limit
Maps to getWrapSizeLimit() of GSSSecurityContext.
7.2.13. GSS_Export_sec_context
Maps to export() method of GSSSecurityContext.
7.2.14. GSS_Import_sec_context
Maps to importContext() method of GSSImplementation.
7.2.15. GSS_Get_MIC
Maps to getMIC() method of GSSSecurityContext.
7.2.16. GSS_Verify_MIC
Maps to verifyMIC() method of GSSSecurityContext.
7.2.17. GSS_Wrap
Maps to wrap() method of GSSSecurityContext.
7.2.18. GSS_Unwrap
Maps to unwrap() method of GSSSecurityContext.
Smith Document Expiration: 1 Sept 1999 [Page 24]
Java-GSS Bindings, Part I: Interfaces April 1999
7.2.19. GSS_Display_status
Maps to displayMajorStatus() and displayMinorStatus() of GSSStatus.
7.2.20. GSS_Indicate_mechs
Maps to indicateMechs() method of GSSImplementation.
7.2.21. GSS_Compare_name
Maps to equals() method of GSSName.
7.2.22. GSS_Display_name
Maps to toString() method of GSSName.
7.2.23. GSS_Import_name
Maps to importName() method of GSSImplementation.
7.2.24. GSS_Release_name
Not mapped. Uses normal Java lifecycle mechanisms.
7.2.25. GSS_Release_buffer
Not mapped. Uses normal Java lifecycle mechanisms.
7.2.26. GSS_Release_OID_set
Not mapped. Uses normal Java lifecycle mechanisms.
7.2.27. GSS_Create_empty_OID_set
Not mapped. Uses normal Java array creation mechanism.
7.2.28. GSS_Add_OID_set_member
Not mapped. Uses normal Java array mechanism.
7.2.29. GSS_Test_OID_set_member
Not mapped. Uses normal Java array mechanism.
7.2.30. GSS_Inquire_names_for_mech
Maps to inquireNamesForMech method of GSSImplementation.
Smith Document Expiration: 1 Sept 1999 [Page 25]
Java-GSS Bindings, Part I: Interfaces April 1999
7.2.31. GSS_Inquire_mechs_for_name
Maps to inquireMechs method of GSSName.
7.2.32. GSS_Canonicalize_name
Maps to canonicalize() method of GSSName.
7.2.33. GSS_Export_name
Maps to export() method of GSSMechName.
7.2.34. GSS_Duplicate_name
Maps to clone() method of GSSName (inherited from java.lang.Object).
Note that this implies that implementations of GSSName must implement
the Cloneable [sic] interface.
8. Obtaining the initial instance of GSSImplementation
All the objects defined in this specification are obtained, directly
or indirectly, from an instance of GSSImplementation. This
specification does not mandate a means by which that instance is
obtained. Various solutions are possible, and different users will
have different requirements.
The technique used at TIAA-CREF is to define a SystemProperty which
holds the name of a class implementing GSSImplementation. This class
has a no-parameter constructor, and applications obtain an instance
by calling Class.forName() on the value of that SystemProperty.
Applications may, of course, simply know the name of the implementing
class and instantiate it directly. As noted in the Introduction
(above, section 3), it remains a goal of the CAT Working Group to
define a "concrete classes" specification for the GSS-API in Java, as
well as an "interfaces" specification to which the present document
is a contribution. Such classes are likely to have well-known names.
One particular case of such a well-known concrete-class
implementation is the "shim" design discussed in [4].
9. Security Considerations
This entire document deals with security.
10. Conclusion
This document specifies a set of Java interfaces representing the
semantics of the Generic Security Service API for the Java language.
Smith Document Expiration: 1 Sept 1999 [Page 26]
Java-GSS Bindings, Part I: Interfaces April 1999
11. References
[1] J. Linn, "Generic Security Service Application Program Interface,
Version 2, Update 1," Internet-Draft, <draft-ietf-cat-
rfc2078bis-08.txt>, December 1998
[2] The TIAA-CREF Java GSS binding:
<http://www.panix.com/~jlefevre/GSS>
[3] Jack Kabat, "Generic Security Service API Version 2 : Java
bindings," Internet-Draft, <draft-ietf-cat-gssv2-javabind-00.txt>,
August 1998
[4] Michael Smith, "A Service Provider API for GSS Mechanisms in Java,"
Internet-Draft, <draft-ietf-cat-gssv2-javabind-spi-01.txt>, April
1999
[5] E. Baize and D. Pinkas, "The Simple and Protected GSS-API
Negotiation Mechanism," RFC 2478.
[6] J. Wray, "Generic Security Service API Version 2 : C-bindings,"
Internet-Draft, <draft-ietf-cat-gssv2-cbind-09.txt>, February 1999
12. Author's Address
Michael Smith
TIAA-CREF
730 Third Avenue
Mailstop 485-27-02
New York, NY 10017
USA
Phone: 212 490 9000 x 1760
Email: ms@gf.org
Smith Document Expiration: 1 Sept 1999 [Page 27]
| PAFTECH AB 2003-2026 | 2026-04-23 06:23:03 |