* 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 Protocol 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 of the Mechanism Drivers * to help it perform authentication, where all parameters to * be used in encryption from then on are determined. In a protocol- * specific way, the Protocol Driver examines each byte string received * from the server 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 * and 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 Security 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 (at least on the client * side). That means that a Mechanism Driver may need to call up to * an application during the authentication process. In the following, * an interface SASLAuthenticationCB has been defined, allowing * an application to (if necessary) provide a user with prompts and * obtain additional information required to continue the process. *
* For LDAP, the Protocol Driver can be considered built in to * the LDAPConnection class (actually it is more likely an object * to which an LDAPConnection object has a reference). *
* However, * there should be a generalized framework for registering and * finding Mechanism Drivers. Maybe best to do something like * content and protocol handlers in java: look for them in some * predefined place in the general class hierarchy, e.g. * netscape.security.mechanisms. So if a Protocol Driver is * asked to use "GSSAPI", it would attempt to instantiate * netscape.security.mechanisms.gssapi. A non-standard place can * also be specified, e.g. "myclasses.mechanisms.GSSAPI". * This functionality should be folded into a mechanism driver * factory, which knows where to find candidate classes for * instantiation. *
* The Mechanism Drivers are protocol-independent, and don't deal * directly with network connections, just byte arrays, so they * should 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. *
* One way to allow specifying an open-ended list of parameters is * with a Properties object. That is what is done in the following. * * @author rweltman@netscape.com * @version 1.0 */ public interface SASLClientMechanismDriver { /** * 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. * @param id Protocol-dependent identification, e.g. user name or * distinguished name. * @param protocol A protocol supported by the mechanism driver, e.g. * "pop3", "ldap" * @param serverName Only used in kerberos, currently: fully qualified * name of server to authenticate to. * @param props Additional configuration for the session, e.g. *
* "security.policy.encryption.minimum" Minimum key length;
* default 0
* "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" Reject frames larger than
* this; default 0 (client
* will not use the security
* layer)
*
* @param authCB An optional object which can be invoked by the
* mechanism driver to acquire additional authentication information,
* such as user name and password.
* @return A byte array to be used for the initial authentication. It
* may be null for a standard initial sequence in some
* protocols, such as POP, SMTP, and IMAP.
* @exception SASLException if an initial authentication request can
* not be formulated with the supplied parameters.
*/
public byte[] startAuthentication( String id,
String protocol,
String serverName,
java.util.Properties props,
SASLClientCB authCB )
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.
* @param challenge Received server challenge.
* @return Request to submit to server.
* @exception SASLException if the server challenge could not
* be handled or the driver is unable for other reasons to
* continue the authentication process.
*/
public byte[] evaluateResponse( byte[] challenge )
throws SASLException;
/**
* The following method may be called at any time to determine if
* the authentication 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.
* @return true if authentication is complete.
*/
public boolean isComplete();
/**
* Once authentication is complete, the Protocol Driver calls the
* following 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 authentication). An exception is thrown if
* authentication is not yet complete.
* @return A SASLSecurityLayer object capable of doing
* encoding/decoding during the session.
* @exception SASLException if no security layer has been negotiated
* or if authentication is not complete.
*/
public SASLSecurityLayer getSecurityLayer() throws SASLException;
/**
* Report the name of this driver, e.g. "GSSAPI".
* @return The name of the mechanism driver, without any location
* qualification.
*/
public String getMechanismName();
}