Network Working Group Rob Weltman John Gardiner Myers Prasad Yendluri Christine Ho INTERNET-DRAFT Netscape Communications Corp. March 6, 1997 The Java SASL Application Program Interface Status of this Memo This draft document, draft-weltman-java-sasl-00.txt, will be submitted to the RFC Editor as an informational document. Distribution of this memo is unlimited. Please send comments to the authors. This document is an Internet-Draft. Internet-Drafts are working docu- ments 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.'' To learn the current status of any Internet-Draft, please check the ``1id-abstracts.txt'' listing contained in the Internet-Drafts Shadow Directories on ds.internic.net (US East Coast), nic.nordu.net (Europe), ftp.isi.edu (US West Coast), or munnari.oz.au (Pacific Rim). Abstract This document defines a client-side java language interface for using the Simple Authentication and Security Layer (SASL) mechanisms for adding authentication support to connection-based protocols. The inter- face promotes sharing of SASL mechanism drivers and security layers between applications using different protocols. It complements but does not replace [1], which defines and exemplifies use of the SASL protocol in a language-independent way. 1. Introduction See [1], section 3, for an introduction to and overview of the SASL framework for authentication and negotiation of a security layer. The following presents an outline of the concepts. Expires 9/98 [Page 1] JAVA SASL API March 1998 Mechanism Drivers --------------- ------------------- ----------------- | Application |-----| Protocol Driver |------| MD5 | --------------- ------------------- | ----------------- | | ----------------- |--| Kerberos v5 | | ----------------- | | ----------------- |--| PKCS-11 | | ----------------- | | | | - - - - - - - - - |--| xxxYYYxxx | - - - - - - - - - An application chooses a Protocol Driver specific to the protocol it wants to use, and specifies one or more acceptable mechanisms. The Pro- tocol Driver controls the socket, and knows the format/packaging of bytes sent down and received from the socket, but does not know how to authenticate or to encrypt/ decrypt the bytes. It uses one of the Mechanism Drivers to help it perform authentication. The Protocol Driver examines each byte string received from the server during the authenti- cation in a protocol-specific way to determine if the authentication process has been completed. If not, the byte string is passed to the Mechanism Driver to be interpreted as a server challenge; the Mechanism Driver returns an appropriate response, which the Protocol Driver can encode in a protocol-specific way and return to the server. If the Protocol Driver concludes from the byte string received from the server that authentication is complete, it may query the Mechanism Driver if it considers the authentication process complete, in order to thwart early completion messages inserted by an intruder. On completed authentication, the Protocol Driver receives from the Mechanism Driver a Security Layer Driver object. From this point on, the Protocol Driver passes byte arrays received from its socket to the Secu- rity Layer Driver object for decoding before returning them to the application, and passes application byte arrays to the Security Layer Driver object for encryption before passing them down the socket. A complication here is that some authentication methods may require additional user/application input. That means that a Mechanism Driver Expires 9/98 [Page 2] JAVA SASL API March 1998 may need to call up to an application during the authentication process. In the following, a number of callback interfaces have been defined, allowing an application to (if necessary) provide a user with prompts and obtain additional information required to continue the process. Additional callback interfaces may be defined in the future. Typically, a client will construct an object that implements all of these inter- faces. Protocol Drivers are protocol-dependent, and may be built in to a proto- col package or an application. However, there should be a generalized framework for registering and finding Mechanism Drivers. This can be handled in a way similar to content and protocol handlers in java: look for them in a predefined place in the general class hierarchy, e.g. javax.security.mechanisms. So if a Protocol Driver is asked to use "GSSAPI", it would attempt to instantiate javax.security.mechanisms.gssapi.class. A non-standard place can also be specified, e.g. "myclasses.mechanisms.GSSAPI". This functionality is provided by a mechanism driver factory, which knows where to find candi- date classes for instantiation. The Mechanism Drivers are protocol-independent, and don't deal directly with network connections, just byte arrays, so they can be implemented in a generalizable way for all protocols. A Security Layer Driver typically inherits a State object from the Mechanism Driver, where parameters and resolutions reached during authentication have been stored. Different Mechanism Drivers may require different parameters to carry out the authentication process. This is handled in the following with a java.util.Properties object. 2. Overview of the SASL classes 2.1. Interfaces SASLClientMechanismDriver Interface for all SASL Mechanism Drivers. SASLSecurityLayer An object implementing this interface translates buffers back and forth during a session, after the authentication pro- cess has completed, to provide a secu- rity layer. Expires 9/98 [Page 3] JAVA SASL API March 1998 SASLClientCB Base interface for classes which can be used by a Mechanism Driver to obtain additional client information during negotiation of authentication with a server. SASLNamePasswordClientCB An interface to provide a Mechanism Driver with a user name and password during negotiation of authentication with a server. SASLPasswordClientCB An interface to provide a Mechanism Driver with a password or other single textual credential item during negotia- tion of authentication with a server. SASLInfoClientCB An interface that can be used by a Mechanism Driver to present the user with arbitrary textual information dur- ing negotiation of authentication with a server. SASLWarningClientCB An interface that can be used by a Mechanism Driver to present the user with arbitrary textual information dur- ing negotiation of authentication with a server, and wait for user confirmation. SASLOkayCancelClientCB An interface that can be used by a Mechanism Driver to present the user with a choice of continuing or cancel- ling during negotiation of authentica- tion with a server. SASLGetLanguageCB An interface that can be used by a Mechanism Driver to query for a language to use in localization of client-visible text. Expires 9/98 [Page 4] JAVA SASL API March 1998 2.2. Classes SASLMechanismFactory A class capable of instantiating a Mechanism Driver. SASLException Exception thrown on errors and failures in the authentication process. 3. Overview of SASL API Use An application generally uses the SASL API as follows: - Pass a list of acceptable or known Mechanism Drivers to a SASLMechanismFactory. The factory returns an object implementing SASLClientMechanismDriver on success. - Create an object implementing the client authentication callback interfaces, which can provide credentials when required by the Mechanism Driver. - Have the SASLClientMechanismDriver object begin the authentication process by providing an initial server request. - Requests/responses are exchanged with the server. If a response indicates authentication has completed, the Mechanism Driver is queried for validation, and a SASLSecurityLayer object is obtained from it. If not, the Mechanism Driver is queried for an appropriate next request to the server. This continues until authentication has completed. - For the rest of the session, requests to the server are encoded first by the Security Layer, and responses from the server are decoded by it before processing in the application. The following sections describe the SASL classes in more detail. 4. The java SASL classes 4.1. public interface SASLClientMechanismDriver An object implementing this interface can negotiate authentication using one or more authentication methods. Expires 9/98 [Page 5] JAVA SASL API March 1998 4.1.1. startAuthentication public byte[] startAuthentication(String id, String protocol, String serverName, java.util.Properties props, SASLClientCB authCB) throws SASLException This method prepares a byte array to use for the initial request to authenticate. A SASLException is thrown if the driver cannot initiate authentication with the supplied parameters. The return value may be null, indicating there is no initial response to send to the server. Parameters are: id Protocol-dependent identification, e.g. user name or distinguished name. protocol A protocol supported by the mechanism driver, e.g. "POP", "LDAP". serverName Fully qualified name of server to authenticate to. props Additional configuration for the session, e.g. security.policy.encryption.minimum Minimum key length; default 0 (no session protection). 1 means integrity protection only. security.policy.encryption.maximum Maximum key length; default 256. security.policy.server_authentication True if server must authenticate to client; default false. security.ip.local For kerberos v4; no default. security.ip.remote For kerberos v4; no default. security.maxbuffer Maximum size of secu- rity layer frames; Expires 9/98 [Page 6] JAVA SASL API March 1998 default 0 (client will not use the security layer). authCB An optional object which can be invoked by the mechan- ism driver to acquire additional authentication infor- mation, such as user name and password. 4.1.2. evaluateResponse public byte[] evaluateResponse(byte[] challenge) throws SASLException If a challenge is received from the server during the authentication process, this method is called by the Protocol Driver to prepare an appropriate next request to submit to the server. A SASLException is thrown if no response can be generated for the challenge. Parameters are: challenge Received server challenge. 4.1.3. isComplete public boolean isComplete() This method may be called at any time to determine if the authentica- tion process is finished. Typically, the protocol driver will not do this until it has received something from the server which indicates (in a protocol-specific manner) that the process has completed. 4.1.4. getSecurityLayer public SASLSecurityLayer getSecurityLayer() throws SASLException Once authentication is complete, the Protocol Driver calls this method to obtain an object capable of encoding/decoding data content for the rest of the session (or until there is a new round of authen- tication). An exception is thrown if authentication is not yet com- plete. Expires 9/98 [Page 7] JAVA SASL API March 1998 4.1.5. getMechanismName public String getMechanismName() Report the name of this driver, e.g. "GSSAPI". 4.2. public interface SASLNamePasswordClientCB extends SASLClientCB An object implementing this interface can be called by a Mechanism Driver to provide more information for authentication. Typically what is provided by the object is an ID and a password. 4.2.1. promptNamePassword() public boolean promptNamePassword (String defaultID, String serverFQDN, String protocol, String prompt) Method to be implemented by client of the mechanism driver. It may or may not pop up a UI and allow a user to enter the information. It returns true unless the operation was cancelled. Parameters are: defaultID A default which may be used in selecting credentials. serverFQDN The fully qualified domain name of the host to which authentication is being attempted. Used with kerberos. protocol "IMAP", "POP", etc. Used with kerberos. prompt Textual information to be provided to the client for obtaining an ID and password. It may be localized. 4.2.2. getID() public String getID () Called by a mechanism driver to retrieve the ID (e.g. user name) obtained by the object during promptNamePassword. Expires 9/98 [Page 8] JAVA SASL API March 1998 4.2.3. getPassword() public String getPassword () Called by a mechanism driver to retrieve the password obtained by the object during promptNamePassword. 4.3. public interface SASLPasswordClientCB extends SASLClientCB An object implementing this interface can be called by a Mechanism Driver to provide more information for authentication. Typically what is provided by the object is a password. 4.3.1. promptPassword() public boolean promptPassword (String defaultID, String serverFQDN, String protocol, String prompt) Method to be implemented by client of the mechanism driver. It may or may not pop up a UI and allow a user to enter the information. It returns true unless the operation was cancelled. Parameters are: defaultID A default which may be used in selecting credentials. serverFQDN The fully qualified domain name of the host to which authentication is being attempted. Used with kerberos. protocol "IMAP", "POP", etc. Used with kerberos. prompt Textual information to be provided to the client for obtaining a password. It may be localized. 4.3.2. getPassword() public String getPassword () Called by a mechanism driver to retrieve the password obtained by the object during promptPassword. Expires 9/98 [Page 9] JAVA SASL API March 1998 4.4. public interface SASLInfoClientCB extends SASLClientCB An object implementing this interface can be called by a Mechanism Driver to present information to a user. No confirmation is expected. 4.4.1. promptInfo() public void promptInfo (String prompt) Method to be implemented by client of the mechanism driver. It presents the user with the supplied textual information. Parameters are: prompt Textual information to be provided to the client. It may be localized. 4.5. public interface SASLWarningClientCB extends SASLClientCB An object implementing this interface can be called by a Mechanism Driver to present information to a user. The user must take some action to proceed. 4.5.1. promptWarning() public void promptWarning (String prompt) Method to be implemented by client of the mechanism driver. It presents the user with the supplied textual information and waits for the user to take some action to proceed. Parameters are: prompt Textual information to be provided to the client. It may be localized. 4.6. public interface SASLOkayCancelClientCB extends SASLClientCB An object implementing this interface can be called by a Mechanism Driver to present information to a user and return an indication that an operation is to proceed or to be cancelled. Expires 9/98 [Page 10] JAVA SASL API March 1998 4.6.1. promptOkayCancel() public boolean promptOkayCancel (String prompt, String okText, String cancelText ) Method to be implemented by client of the mechanism driver. It presents the user with the supplied textual information. The return value is true to continue operations, false to abort. This may be implemented with OK and CANCEL buttons in a dialog. If okText and/or cancelText are non-null and not empty, they may be used to label but- tons. Parameters are: prompt Textual information to be provided to the client. It may be localized. okText Optional label for OK button or selection. cancelText Optional label for Cancel button or selection. 4.7. public interface SASLGetLanguageClientCB extends SASLClientCB An object implementing this interface can be called by a Mechanism Driver to obtain a language to use for localization of user-visible text. 4.7.1. getLanguage() public String getLanguage () Method to be implemented by client of the mechanism driver. It returns a language to use in localizing user-visible text. 4.8. public interface SASLSecurityLayer An object implementing this interface translates buffers back and forth during a session, after the authentication process has completed, to provide a security layer. Expires 9/98 [Page 11] JAVA SASL API March 1998 4.8.1. encode public byte[] encode(byte[] outVals) throws SASLException Take a protocol-dependent byte array and encode it (encrypt, for example) for sending to the server. 4.8.2. decode public byte[] decode(byte[] inVals) throws SASLException Take an encoded byte array received from the server and decode it. Parameters are: outVals A request to be encoded before sending to the server. inVals A response received from the server, to be decoded. 4.9. public class SASLMechanismFactory This class can provide a SASLClientMechanismDriver, or a list of mechan- isms. 4.9.1. getMechanismDriver public static SASLClientMechanismDriver getMechanismDriver(String mechanism, String packageName) throws SASLException public static SASLClientMechanismDriver getMechanismDriver(String[] mechanisms, String packageName) throws SASLException Returns an object implementing a requested Mechanism Driver. A SASLExeption is thrown if no corresponding Mechanism Driver can be instantiated. Parameters are: Expires 9/98 [Page 12] JAVA SASL API March 1998 mechanism A single mechanism name, e.g. "GSSAPI". mechanisms A list of acceptable mechanisms. The first one for which a Mechanism Driver can be instantiated is returned. packageName A package from which to instantiate the Mechanism Driver, e.g. "myclasses.SASL.mechanisms". If null, a system default is used. 4.9.2. getMechanisms public static String[] getMechanisms() public static String[] getMechanisms(String packageName) Returns a list of available mechanisms. Parameters are: packageName A package from which to instantiate the Mechanism Driver, e.g. "myclasses.SASL.mechanisms". If null, a system default is used. 4.10. public class SASLException extends Exception Exception thrown on errors and failures in authentication. 4.10.1. Constructors public SASLException() Constructs a default exception with no specific error information. public SASLException(String message, int resultCode) Constructs a default exception with a specified string as additional information, and a result code. Parameters are: Expires 9/98 [Page 13] JAVA SASL API March 1998 message Additional error information. resultCode The result code to return. Expires 9/98 [Page 14] JAVA SASL API March 1998 5. Security Considerations When SASL authentication is performed over unsecured connections, it is possible for an active attacker to spoof the server's protocol-specific indication that authentication is complete. Clients should protect against this attack by verifying the completion of authentication with the mechanism driver by calling the driver's isComplete() method. Additional security considerations are discussed in [1]. 6. Bibliography [1] J. Myers, "Simple Authentication and Security Layer (SASL)", Inter- net Draft draft-myers-auth-sasl-12.txt, September 1997 7. Authors' Addresses Rob Weltman Netscape Communications Corp. 501 E. Middlefield Rd. Mail Stop MV-029 Mountain View, CA 94043-4042 USA Email: rweltman@netscape.com John Gardiner Myers Netscape Communications Corp. 501 E. Middlefield Rd. Mail Stop MV-029 Mountain View, CA 94043-4042 USA Email: jgmyers@netscape.com Prasad Yandluri Netscape Communications Corp. 501 E. Middlefield Rd. Mail Stop MV-029 Mountain View, CA 94043-4042 USA Email: prasad@netscape.com Christine Ho Netscape Communications Corp. 501 E. Middlefield Rd. Mail Stop MV-029 Mountain View, CA 94043-4042 Expires 9/98 [Page 15] JAVA SASL API March 1998 USA Email: chrisho@netscape.com Expires 9/98 [Page 16] JAVA SASL API March 1998 8. Appendix A - Sample java LDAP program using SASL /******************************************************************** It might look like this in LDAP. The Protocol Driver is implemented as part of the authenticate method of LDAPConnection. ********************************************************************/ public class LDAPConnection { public void authenticate( String dn, String mechanism, String packageName, Properties props, SASLClientCB getter ) throws LDAPException { SASLClientMechanismDriver driver; try { // Get a mechanism driver driver = SASLMechanismFactory.getMechanismDriver( mechanism, packageName ); // Get the initial request to start authentication byte[] outVals = driver.startAuthentication( dn, "LDAP", getHost(), props, getter ); getSocketOutput().writeRequest( outVals ); // Get the server response byte[] inVals = getSocketInput().readResponse(); // Authentication done? while ( !checkForCompletion( inVals ) ) { // No, get an appropriate next request and send it off outVals = driver.evaluateResponse( inVals ); getSocketOutput().writeRequest( outVals ); inVals = getSocketInput().readResponse(); } // Make sure authentication REALLY is complete if ( !driver.isComplete() ) { /* Authentication session hijacked! */ throw new LDAPException(); } security = driver.getSecurityLayer(); } catch ( SASLException e ) { throw new LDAPException(); } catch ( IOException e ) { throw new LDAPException(); } } Expires 9/98 [Page 17] JAVA SASL API March 1998 private SASLSecurityLayer security = null; } /******************************************************************** This might be in an application ********************************************************************/ // Object to supply credentials when needed class RequestedInfoGetter implements SASLNamePasswordClientCB, SASLPasswordClientCB, SASLInfoClientCB, SASLWarningClientCB, SASLGetLanguageClientCB, SASLOkayCancelClientCB { public RequestedInfoGetter() {} public boolean promptNamePassword ( String defaultID, String serverFQDN, String protocol, String prompt ) { // Put up a dialog box, get user's selected ID and password UserIDDialog dlg = new UserIDDialog(); if ( dlg.doDialog( defaultID, prompt ) == OK ) { _id = dlg.getID(); _password = dlg.getPassword(); return true; } return false; } public boolean promptPassword ( String defaultID, String serverFQDN, String protocol, String prompt ) { // Put up a dialog box, get user's selected password PasswordDialog dlg = new PasswordDialog(); if ( dlg.doDialog( defaultID, prompt ) == OK ) { _password = dlg.getPassword(); return true; } return false; } public void promptWarning ( String prompt ) { // Put up a dialog box, wait for confirmation WarningDialog dlg = new WarningDialog(); dlg.doDialog( prompt ); } public void promptInfo ( String prompt ) { Expires 9/98 [Page 18] JAVA SASL API March 1998 // Put the text in the status box statusWin.addText( prompt ); } public boolean promptOkayCancel ( String prompt, String ok, String cancel ) { // Put up a dialog box, wait for OK or Cancel OkayCancelDialog dlg = new OkayCancelDialog(); return dlg.doDialog( prompt ); } public String getLanguage () { // Get the language from the locale String lang = locale.getLanguage(); if ( (locale.getCountry() != null) && (locale.getCountry().length() > 0) ) { lang += "-" + locale.getCountry(); if ( (locale.getVariant() != null) && (locale.getVariant().length() > 0) ) { lang += "-" + locale.getVariant(); } } return lang; } public String getID() { return _id; } public String getPassword() { return _password; } private String _id; private String _password; } /******************************************************************* And so the application code to do authentication ********************************************************************/ // Set up all SASL parameters; some may have reasonable defaults Properties props = new Properties(); props.add( "security.policy.encryption.minimum", "40"); props.add( "security.policy.encryption.maximum", "128"); props.add( "security.policy.server_authentication", "true"); props.add( "security.maxbuffer", "4096"); // The following two for kerberos v4, only //props.add( "security.ip.local", "192.68.1.10"); //props.add( "security.ip.remote", "192.68.1.50"); // What we want to authenticate as String dn = "cn=Directory Manager"; // Create an object for possible use by the authentication Expires 9/98 [Page 19] JAVA SASL API March 1998 // process RequestedInfoGetter getter = new RequestedInfoGetter(); try { // Note: getter methods may be called during authentication // Note: "connection" includes the SASL Protocol Driver // functionality, and it will internally manage a Mechanism // Driver for GSSAPI, and then a Security Layer object for // data translation connection.authenticate( dn, "GSSAPI", props, getter ); } catch ( LDAPException e ) { // Abort, return, maybe try some other authentication } // Okay. From here on, everything goes through security, but the // methods have the same signatures as if we were not using SASL Expires 9/98 [Page 20] 1. Introduction...................................................1 2. Overview of the SASL classes...................................3 2.1. Interfaces..................................................3 2.2. Classes.....................................................5 3. Overview of SASL API Use.......................................5 4. The java SASL classes..........................................5 4.1. SASLClientMechanismDriver....................................5 4.1.1. startAuthentication......................................6 4.1.2. evaluateResponse.........................................7 4.1.3. isComplete...............................................7 4.1.4. getSecurityLayer.........................................7 4.1.5. getMechanismName.........................................8 4.2. SASLNamePasswordClientCB.....................................8 4.2.1. promptNamePassword().....................................8 4.2.2. getID()..................................................8 4.2.3. getPassword()............................................9 4.3. SASLPasswordClientCB.........................................9 4.3.1. promptPassword().........................................9 4.3.2. getPassword()............................................9 4.4. SASLInfoClientCB.............................................10 4.4.1. promptInfo().............................................10 4.5. SASLWarningClientCB..........................................10 4.5.1. promptWarning()..........................................10 4.6. SASLOkayCancelClientCB.......................................10 4.6.1. promptOkayCancel().......................................11 4.7. SASLGetLanguageClientCB......................................11 4.7.1. getLanguage()............................................11 4.8. SASLSecurityLayer............................................11 4.8.1. encode...................................................12 4.8.2. decode...................................................12 4.9. SASLMechanismFactory.........................................12 4.9.1. getMechanismDriver.......................................12 4.9.2. getMechanisms............................................13 4.10. SASLException................................................13 4.10.1. Constructors.............................................13 5. Security Considerations........................................15 6. Bibliography...................................................15 7. Authors' Addresses.............................................15 8. Appendix A - Sample java LDAP program using SASL...............17