KickJava   Java API By Example, From Geeks To Geeks.

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


1 /*
2  * @(#)SaslServer.java 1.13 04/02/03
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 server.
12  *<p>
13  * A server such an LDAP server gets an instance of this
14  * class in order to perform authentication defined by a specific SASL
15  * mechanism. Invoking methods on the <tt>SaslServer</tt> instance
16  * generates challenges according to the SASL
17  * mechanism implemented by the <tt>SaslServer</tt>.
18  * As the authentication proceeds, the instance
19  * encapsulates the state of a SASL server's authentication exchange.
20  *<p>
21  * Here's an example of how an LDAP server might use a <tt>SaslServer</tt>.
22  * It first gets an instance of a <tt>SaslServer</tt> for the SASL mechanism
23  * requested by the client:
24  *<blockquote><pre>
25  * SaslServer ss = Sasl.createSaslServer(mechanism,
26  * "ldap", myFQDN, props, callbackHandler);
27  *</pre></blockquote>
28  * It can then proceed to use the server for authentication.
29  * For example, suppose the LDAP server received an LDAP BIND request
30  * containing the name of the SASL mechanism and an (optional) initial
31  * response. It then might use the server as follows:
32  *<blockquote><pre>
33  * while (!ss.isComplete()) {
34  * try {
35  * byte[] challenge = ss.evaluateResponse(response);
36  * if (ss.isComplete()) {
37  * status = ldap.sendBindResponse(mechanism, challenge, SUCCESS);
38  * } else {
39  * status = ldap.sendBindResponse(mechanism, challenge,
40                SASL_BIND_IN_PROGRESS);
41  * response = ldap.readBindRequest();
42  * }
43  * } catch (SaslException e) {
44  * status = ldap.sendErrorResponse(e);
45  * break;
46  * }
47  * }
48  * if (ss.isComplete() && status == SUCCESS) {
49  * String qop = (String) sc.getNegotiatedProperty(Sasl.QOP);
50  * if (qop != null
51  * && (qop.equalsIgnoreCase("auth-int")
52  * || qop.equalsIgnoreCase("auth-conf"))) {
53  *
54  * // Use SaslServer.wrap() and SaslServer.unwrap() for future
55  * // communication with client
56  * ldap.in = new SecureInputStream(ss, ldap.in);
57  * ldap.out = new SecureOutputStream(ss, ldap.out);
58  * }
59  * }
60  *</pre></blockquote>
61  *
62  * @since 1.5
63  *
64  * @see Sasl
65  * @see SaslServerFactory
66  *
67  * @author Rosanna Lee
68  * @author Rob Weltman
69  */
70 public abstract interface SaslServer {
71
72     /**
73      * Returns the IANA-registered mechanism name of this SASL server.
74      * (e.g. "CRAM-MD5", "GSSAPI").
75      * @return A non-null string representing the IANA-registered mechanism name.
76      */
77     public abstract String JavaDoc getMechanismName();
78
79     /**
80      * Evaluates the response data and generates a challenge.
81      *
82      * If a response is received from the client during the authentication
83      * process, this method is called to prepare an appropriate next
84      * challenge to submit to the client. The challenge is null if the
85      * authentication has succeeded and no more challenge data is to be sent
86      * to the client. It is non-null if the authentication must be continued
87      * by sending a challenge to the client, or if the authentication has
88      * succeeded but challenge data needs to be processed by the client.
89      * <tt>isComplete()</tt> should be called
90      * after each call to <tt>evaluateResponse()</tt>,to determine if any further
91      * response is needed from the client.
92      *
93      * @param response The non-null (but possibly empty) response sent
94      * by the client.
95      *
96      * @return The possibly null challenge to send to the client.
97      * It is null if the authentication has succeeded and there is
98      * no more challenge data to be sent to the client.
99      * @exception SaslException If an error occurred while processing
100      * the response or generating a challenge.
101      */
102     public abstract byte[] evaluateResponse(byte[] response)
103     throws SaslException JavaDoc;
104
105     /**
106       * Determines whether the authentication exchange has completed.
107       * This method is typically called after each invocation of
108       * <tt>evaluateResponse()</tt> to determine whether the
109       * authentication has completed successfully or should be continued.
110       * @return true if the authentication exchange has completed; false otherwise.
111       */
112     public abstract boolean isComplete();
113
114     /**
115      * Reports the authorization ID in effect for the client of this
116      * session.
117      * This method can only be called if isComplete() returns true.
118      * @return The authorization ID of the client.
119      * @exception IllegalStateException if this authentication session has not completed
120      */
121     public String JavaDoc getAuthorizationID();
122     
123     /**
124      * Unwraps a byte array received from the client.
125      * This method can be called only after the authentication exchange has
126      * completed (i.e., when <tt>isComplete()</tt> returns true) and only if
127      * the authentication exchange has negotiated integrity and/or privacy
128      * as the quality of protection; otherwise,
129      * an <tt>IllegalStateException</tt> is thrown.
130      *<p>
131      * <tt>incoming</tt> is the contents of the SASL buffer as defined in RFC 2222
132      * without the leading four octet field that represents the length.
133      * <tt>offset</tt> and <tt>len</tt> specify the portion of <tt>incoming</tt>
134      * to use.
135      *
136      * @param incoming A non-null byte array containing the encoded bytes
137      * from the client.
138      * @param offset The starting position at <tt>incoming</tt> of the bytes to use.
139      * @param len The number of bytes from <tt>incoming</tt> to use.
140      * @return A non-null byte array containing the decoded bytes.
141      * @exception SaslException if <tt>incoming</tt> cannot be successfully
142      * unwrapped.
143      * @exception IllegalStateException if the authentication exchange has
144      * not completed, or if the negotiated quality of protection
145      * has neither integrity nor privacy
146      */
147     public abstract byte[] unwrap(byte[] incoming, int offset, int len)
148     throws SaslException JavaDoc;
149
150     /**
151      * Wraps a byte array to be sent to the client.
152      * This method can be called only after the authentication exchange has
153      * completed (i.e., when <tt>isComplete()</tt> returns true) and only if
154      * the authentication exchange has negotiated integrity and/or privacy
155      * as the quality of protection; otherwise, a <tt>SaslException</tt> is thrown.
156      *<p>
157      * The result of this method
158      * will make up the contents of the SASL buffer as defined in RFC 2222
159      * without the leading four octet field that represents the length.
160      * <tt>offset</tt> and <tt>len</tt> specify the portion of <tt>outgoing</tt>
161      * to use.
162      *
163      * @param outgoing A non-null byte array containing the bytes to encode.
164      * @param offset The starting position at <tt>outgoing</tt> of the bytes to use.
165      * @param len The number of bytes from <tt>outgoing</tt> to use.
166      * @return A non-null byte array containing the encoded bytes.
167      * @exception SaslException if <tt>outgoing</tt> cannot be successfully
168      * wrapped.
169      * @exception IllegalStateException if the authentication exchange has
170      * not completed, or if the negotiated quality of protection has
171      * neither integrity nor privacy.
172      */
173     public abstract byte[] wrap(byte[] outgoing, int offset, int len)
174     throws SaslException JavaDoc;
175
176     /**
177      * Retrieves the negotiated property.
178      * This method can be called only after the authentication exchange has
179      * completed (i.e., when <tt>isComplete()</tt> returns true); otherwise, an
180      * <tt>IllegalStateException</tt> is thrown.
181      *
182      * @param propName the property
183      * @return The value of the negotiated property. If null, the property was
184      * not negotiated or is not applicable to this mechanism.
185      * @exception IllegalStateException if this authentication exchange has not completed
186      */
187
188     public abstract Object JavaDoc getNegotiatedProperty(String JavaDoc propName);
189
190      /**
191       * Disposes of any system resources or security-sensitive information
192       * the SaslServer might be using. Invoking this method invalidates
193       * the SaslServer instance. This method is idempotent.
194       * @throws SaslException If a problem was encountered while disposing
195       * the resources.
196       */
197     public abstract void dispose() throws SaslException JavaDoc;
198 }
199
Popular Tags