KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > javax > security > sasl > SaslClient


1 /*
2  * @(#)SaslClient.java 1.14 03/12/19
3  *
4  * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5  * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6  */
7
8 package javax.security.sasl;
9
10 /**
11  * Performs SASL authentication as a client.
12  *<p>
13  * A protocol library such as one for LDAP gets an instance of this
14  * class in order to perform authentication defined by a specific SASL
15  * mechanism. Invoking methods on the <tt>SaslClient</tt> instance
16  * process challenges and create responses according to the SASL
17  * mechanism implemented by the <tt>SaslClient</tt>.
18  * As the authentication proceeds, the instance
19  * encapsulates the state of a SASL client's authentication exchange.
20  *<p>
21  * Here's an example of how an LDAP library might use a <tt>SaslClient</tt>.
22  * It first gets an instance of a <tt>SaslClient</tt>:
23  *<blockquote><pre>
24  * SaslClient sc = Sasl.createSaslClient(mechanisms,
25  * authorizationId, protocol, serverName, props, callbackHandler);
26  *</pre></blockquote>
27  * It can then proceed to use the client for authentication.
28  * For example, an LDAP library might use the client as follows:
29  *<blockquote><pre>
30  * // Get initial response and send to server
31  * byte[] response = (sc.hasInitialResponse() ? sc.evaluateChallenge(new byte[0]) :
32  * null);
33  * LdapResult res = ldap.sendBindRequest(dn, sc.getName(), response);
34  * while (!sc.isComplete() &&
35  * (res.status == SASL_BIND_IN_PROGRESS || res.status == SUCCESS)) {
36  * response = sc.evaluateChallenge(res.getBytes());
37  * if (res.status == SUCCESS) {
38  * // we're done; don't expect to send another BIND
39  * if (response != null) {
40  * throw new SaslException(
41  * "Protocol error: attempting to send response after completion");
42  * }
43  * break;
44  * }
45  * res = ldap.sendBindRequest(dn, sc.getName(), response);
46  * }
47  * if (sc.isComplete() && res.status == SUCCESS) {
48  * String qop = (String) sc.getNegotiatedProperty(Sasl.QOP);
49  * if (qop != null
50  * && (qop.equalsIgnoreCase("auth-int")
51  * || qop.equalsIgnoreCase("auth-conf"))) {
52  *
53  * // Use SaslClient.wrap() and SaslClient.unwrap() for future
54  * // communication with server
55  * ldap.in = new SecureInputStream(sc, ldap.in);
56  * ldap.out = new SecureOutputStream(sc, ldap.out);
57  * }
58  * }
59  *</pre></blockquote>
60  *
61  * If the mechanism has an initial response, the library invokes
62  * <tt>evaluateChallenge()</tt> with an empty
63  * challenge and to get initial response.
64  * Protocols such as IMAP4, which do not include an initial response with
65  * their first authentication command to the server, initiates the
66  * authentication without first calling <tt>hasInitialResponse()</tt>
67  * or <tt>evaluateChallenge()</tt>.
68  * When the server responds to the command, it sends an initial challenge.
69  * For a SASL mechanism in which the client sends data first, the server should
70  * have issued a challenge with no data. This will then result in a call
71  * (on the client) to <tt>evaluateChallenge()</tt> with an empty challenge.
72  *
73  * @since 1.5
74  *
75  * @see Sasl
76  * @see SaslClientFactory
77  *
78  * @author Rosanna Lee
79  * @author Rob Weltman
80  */
81 public abstract interface SaslClient {
82
83     /**
84      * Returns the IANA-registered mechanism name of this SASL client.
85      * (e.g. "CRAM-MD5", "GSSAPI").
86      * @return A non-null string representing the IANA-registered mechanism name.
87      */
88     public abstract String JavaDoc getMechanismName();
89
90     /**
91      * Determines whether this mechanism has an optional initial response.
92      * If true, caller should call <tt>evaluateChallenge()</tt> with an
93      * empty array to get the initial response.
94      *
95      * @return true if this mechanism has an initial response.
96      */
97     public abstract boolean hasInitialResponse();
98
99     /**
100      * Evaluates the challenge data and generates a response.
101      * If a challenge is received from the server during the authentication
102      * process, this method is called to prepare an appropriate next
103      * response to submit to the server.
104      *
105      * @param challenge The non-null challenge sent from the server.
106      * The challenge array may have zero length.
107      *
108      * @return The possibly null reponse to send to the server.
109      * It is null if the challenge accompanied a "SUCCESS" status and the challenge
110      * only contains data for the client to update its state and no response
111      * needs to be sent to the server. The response is a zero-length byte
112      * array if the client is to send a response with no data.
113      * @exception SaslException If an error occurred while processing
114      * the challenge or generating a response.
115      */
116     public abstract byte[] evaluateChallenge(byte[] challenge)
117     throws SaslException JavaDoc;
118
119     /**
120       * Determines whether the authentication exchange has completed.
121       * This method may be called at any time, but typically, it
122       * will not be called until the caller has received indication
123       * from the server
124       * (in a protocol-specific manner) that the exchange has completed.
125       *
126       * @return true if the authentication exchange has completed; false otherwise.
127       */
128     public abstract boolean isComplete();
129
130     /**
131      * Unwraps a byte array received from the server.
132      * This method can be called only after the authentication exchange has
133      * completed (i.e., when <tt>isComplete()</tt> returns true) and only if
134      * the authentication exchange has negotiated integrity and/or privacy
135      * as the quality of protection; otherwise, an
136      * <tt>IllegalStateException</tt> is thrown.
137      *<p>
138      * <tt>incoming</tt> is the contents of the SASL buffer as defined in RFC 2222
139      * without the leading four octet field that represents the length.
140      * <tt>offset</tt> and <tt>len</tt> specify the portion of <tt>incoming</tt>
141      * to use.
142      *
143      * @param incoming A non-null byte array containing the encoded bytes
144      * from the server.
145      * @param offset The starting position at <tt>incoming</tt> of the bytes to use.
146      * @param len The number of bytes from <tt>incoming</tt> to use.
147      * @return A non-null byte array containing the decoded bytes.
148      * @exception SaslException if <tt>incoming</tt> cannot be successfully
149      * unwrapped.
150      * @exception IllegalStateException if the authentication exchange has
151      * not completed, or if the negotiated quality of protection
152      * has neither integrity nor privacy.
153      */
154     public abstract byte[] unwrap(byte[] incoming, int offset, int len)
155     throws SaslException JavaDoc;
156
157     /**
158      * Wraps a byte array to be sent to the server.
159      * This method can be called only after the authentication exchange has
160      * completed (i.e., when <tt>isComplete()</tt> returns true) and only if
161      * the authentication exchange has negotiated integrity and/or privacy
162      * as the quality of protection; otherwise, an
163      * <tt>IllegalStateException</tt> is thrown.
164      *<p>
165      * The result of this method will make up the contents of the SASL buffer
166      * as defined in RFC 2222 without the leading four octet field that
167      * represents the length.
168      * <tt>offset</tt> and <tt>len</tt> specify the portion of <tt>outgoing</tt>
169      * to use.
170      *
171      * @param outgoing A non-null byte array containing the bytes to encode.
172      * @param offset The starting position at <tt>outgoing</tt> of the bytes to use.
173      * @param len The number of bytes from <tt>outgoing</tt> to use.
174      * @return A non-null byte array containing the encoded bytes.
175      * @exception SaslException if <tt>outgoing</tt> cannot be successfully
176      * wrapped.
177      * @exception IllegalStateException if the authentication exchange has
178      * not completed, or if the negotiated quality of protection
179      * has neither integrity nor privacy.
180      */
181     public abstract byte[] wrap(byte[] outgoing, int offset, int len)
182     throws SaslException JavaDoc;
183
184     /**
185      * Retrieves the negotiated property.
186      * This method can be called only after the authentication exchange has
187      * completed (i.e., when <tt>isComplete()</tt> returns true); otherwise, an
188      * <tt>IllegalStateException</tt> is thrown.
189      *
190      * @param propName The non-null property name.
191      * @return The value of the negotiated property. If null, the property was
192      * not negotiated or is not applicable to this mechanism.
193      * @exception IllegalStateException if this authentication exchange
194      * has not completed
195      */
196
197     public abstract Object JavaDoc getNegotiatedProperty(String JavaDoc propName);
198
199      /**
200       * Disposes of any system resources or security-sensitive information
201       * the SaslClient might be using. Invoking this method invalidates
202       * the SaslClient instance. This method is idempotent.
203       * @throws SaslException If a problem was encountered while disposing
204       * the resources.
205       */
206     public abstract void dispose() throws SaslException JavaDoc;
207 }
208
Popular Tags