Internet-Draft M. Smith Common Authentication technology WG TIAA-CREF 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, , December 1998 [2] The TIAA-CREF Java GSS binding: [3] Jack Kabat, "Generic Security Service API Version 2 : Java bindings," Internet-Draft, , August 1998 [4] Michael Smith, "A Service Provider API for GSS Mechanisms in Java," Internet-Draft, , 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, , 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]