1 /* |
1 /* |
2 * Copyright (c) 2000, 2004, Oracle and/or its affiliates. All rights reserved. |
2 * Copyright (c) 2000, 2013, Oracle and/or its affiliates. All rights reserved. |
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. |
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. |
4 * |
4 * |
5 * This code is free software; you can redistribute it and/or modify it |
5 * This code is free software; you can redistribute it and/or modify it |
6 * under the terms of the GNU General Public License version 2 only, as |
6 * under the terms of the GNU General Public License version 2 only, as |
7 * published by the Free Software Foundation. Oracle designates this |
7 * published by the Free Software Foundation. Oracle designates this |
28 /** |
28 /** |
29 * Performs SASL authentication as a server. |
29 * Performs SASL authentication as a server. |
30 *<p> |
30 *<p> |
31 * A server such an LDAP server gets an instance of this |
31 * A server such an LDAP server gets an instance of this |
32 * class in order to perform authentication defined by a specific SASL |
32 * class in order to perform authentication defined by a specific SASL |
33 * mechanism. Invoking methods on the <tt>SaslServer</tt> instance |
33 * mechanism. Invoking methods on the {@code SaslServer} instance |
34 * generates challenges according to the SASL |
34 * generates challenges according to the SASL |
35 * mechanism implemented by the <tt>SaslServer</tt>. |
35 * mechanism implemented by the {@code SaslServer}. |
36 * As the authentication proceeds, the instance |
36 * As the authentication proceeds, the instance |
37 * encapsulates the state of a SASL server's authentication exchange. |
37 * encapsulates the state of a SASL server's authentication exchange. |
38 *<p> |
38 *<p> |
39 * Here's an example of how an LDAP server might use a <tt>SaslServer</tt>. |
39 * Here's an example of how an LDAP server might use a {@code SaslServer}. |
40 * It first gets an instance of a <tt>SaslServer</tt> for the SASL mechanism |
40 * It first gets an instance of a {@code SaslServer} for the SASL mechanism |
41 * requested by the client: |
41 * requested by the client: |
42 *<blockquote><pre> |
42 *<blockquote><pre> |
43 * SaslServer ss = Sasl.createSaslServer(mechanism, |
43 * SaslServer ss = Sasl.createSaslServer(mechanism, |
44 * "ldap", myFQDN, props, callbackHandler); |
44 * "ldap", myFQDN, props, callbackHandler); |
45 *</pre></blockquote> |
45 *</pre></blockquote> |
102 * challenge to submit to the client. The challenge is null if the |
102 * challenge to submit to the client. The challenge is null if the |
103 * authentication has succeeded and no more challenge data is to be sent |
103 * authentication has succeeded and no more challenge data is to be sent |
104 * to the client. It is non-null if the authentication must be continued |
104 * to the client. It is non-null if the authentication must be continued |
105 * by sending a challenge to the client, or if the authentication has |
105 * by sending a challenge to the client, or if the authentication has |
106 * succeeded but challenge data needs to be processed by the client. |
106 * succeeded but challenge data needs to be processed by the client. |
107 * <tt>isComplete()</tt> should be called |
107 * {@code isComplete()} should be called |
108 * after each call to <tt>evaluateResponse()</tt>,to determine if any further |
108 * after each call to {@code evaluateResponse()},to determine if any further |
109 * response is needed from the client. |
109 * response is needed from the client. |
110 * |
110 * |
111 * @param response The non-null (but possibly empty) response sent |
111 * @param response The non-null (but possibly empty) response sent |
112 * by the client. |
112 * by the client. |
113 * |
113 * |
121 throws SaslException; |
121 throws SaslException; |
122 |
122 |
123 /** |
123 /** |
124 * Determines whether the authentication exchange has completed. |
124 * Determines whether the authentication exchange has completed. |
125 * This method is typically called after each invocation of |
125 * This method is typically called after each invocation of |
126 * <tt>evaluateResponse()</tt> to determine whether the |
126 * {@code evaluateResponse()} to determine whether the |
127 * authentication has completed successfully or should be continued. |
127 * authentication has completed successfully or should be continued. |
128 * @return true if the authentication exchange has completed; false otherwise. |
128 * @return true if the authentication exchange has completed; false otherwise. |
129 */ |
129 */ |
130 public abstract boolean isComplete(); |
130 public abstract boolean isComplete(); |
131 |
131 |
139 public String getAuthorizationID(); |
139 public String getAuthorizationID(); |
140 |
140 |
141 /** |
141 /** |
142 * Unwraps a byte array received from the client. |
142 * Unwraps a byte array received from the client. |
143 * This method can be called only after the authentication exchange has |
143 * This method can be called only after the authentication exchange has |
144 * completed (i.e., when <tt>isComplete()</tt> returns true) and only if |
144 * completed (i.e., when {@code isComplete()} returns true) and only if |
145 * the authentication exchange has negotiated integrity and/or privacy |
145 * the authentication exchange has negotiated integrity and/or privacy |
146 * as the quality of protection; otherwise, |
146 * as the quality of protection; otherwise, |
147 * an <tt>IllegalStateException</tt> is thrown. |
147 * an {@code IllegalStateException} is thrown. |
148 *<p> |
148 *<p> |
149 * <tt>incoming</tt> is the contents of the SASL buffer as defined in RFC 2222 |
149 * {@code incoming} is the contents of the SASL buffer as defined in RFC 2222 |
150 * without the leading four octet field that represents the length. |
150 * without the leading four octet field that represents the length. |
151 * <tt>offset</tt> and <tt>len</tt> specify the portion of <tt>incoming</tt> |
151 * {@code offset} and {@code len} specify the portion of {@code incoming} |
152 * to use. |
152 * to use. |
153 * |
153 * |
154 * @param incoming A non-null byte array containing the encoded bytes |
154 * @param incoming A non-null byte array containing the encoded bytes |
155 * from the client. |
155 * from the client. |
156 * @param offset The starting position at <tt>incoming</tt> of the bytes to use. |
156 * @param offset The starting position at {@code incoming} of the bytes to use. |
157 * @param len The number of bytes from <tt>incoming</tt> to use. |
157 * @param len The number of bytes from {@code incoming} to use. |
158 * @return A non-null byte array containing the decoded bytes. |
158 * @return A non-null byte array containing the decoded bytes. |
159 * @exception SaslException if <tt>incoming</tt> cannot be successfully |
159 * @exception SaslException if {@code incoming} cannot be successfully |
160 * unwrapped. |
160 * unwrapped. |
161 * @exception IllegalStateException if the authentication exchange has |
161 * @exception IllegalStateException if the authentication exchange has |
162 * not completed, or if the negotiated quality of protection |
162 * not completed, or if the negotiated quality of protection |
163 * has neither integrity nor privacy |
163 * has neither integrity nor privacy |
164 */ |
164 */ |
166 throws SaslException; |
166 throws SaslException; |
167 |
167 |
168 /** |
168 /** |
169 * Wraps a byte array to be sent to the client. |
169 * Wraps a byte array to be sent to the client. |
170 * This method can be called only after the authentication exchange has |
170 * This method can be called only after the authentication exchange has |
171 * completed (i.e., when <tt>isComplete()</tt> returns true) and only if |
171 * completed (i.e., when {@code isComplete()} returns true) and only if |
172 * the authentication exchange has negotiated integrity and/or privacy |
172 * the authentication exchange has negotiated integrity and/or privacy |
173 * as the quality of protection; otherwise, a <tt>SaslException</tt> is thrown. |
173 * as the quality of protection; otherwise, a {@code SaslException} is thrown. |
174 *<p> |
174 *<p> |
175 * The result of this method |
175 * The result of this method |
176 * will make up the contents of the SASL buffer as defined in RFC 2222 |
176 * will make up the contents of the SASL buffer as defined in RFC 2222 |
177 * without the leading four octet field that represents the length. |
177 * without the leading four octet field that represents the length. |
178 * <tt>offset</tt> and <tt>len</tt> specify the portion of <tt>outgoing</tt> |
178 * {@code offset} and {@code len} specify the portion of {@code outgoing} |
179 * to use. |
179 * to use. |
180 * |
180 * |
181 * @param outgoing A non-null byte array containing the bytes to encode. |
181 * @param outgoing A non-null byte array containing the bytes to encode. |
182 * @param offset The starting position at <tt>outgoing</tt> of the bytes to use. |
182 * @param offset The starting position at {@code outgoing} of the bytes to use. |
183 * @param len The number of bytes from <tt>outgoing</tt> to use. |
183 * @param len The number of bytes from {@code outgoing} to use. |
184 * @return A non-null byte array containing the encoded bytes. |
184 * @return A non-null byte array containing the encoded bytes. |
185 * @exception SaslException if <tt>outgoing</tt> cannot be successfully |
185 * @exception SaslException if {@code outgoing} cannot be successfully |
186 * wrapped. |
186 * wrapped. |
187 * @exception IllegalStateException if the authentication exchange has |
187 * @exception IllegalStateException if the authentication exchange has |
188 * not completed, or if the negotiated quality of protection has |
188 * not completed, or if the negotiated quality of protection has |
189 * neither integrity nor privacy. |
189 * neither integrity nor privacy. |
190 */ |
190 */ |
192 throws SaslException; |
192 throws SaslException; |
193 |
193 |
194 /** |
194 /** |
195 * Retrieves the negotiated property. |
195 * Retrieves the negotiated property. |
196 * This method can be called only after the authentication exchange has |
196 * This method can be called only after the authentication exchange has |
197 * completed (i.e., when <tt>isComplete()</tt> returns true); otherwise, an |
197 * completed (i.e., when {@code isComplete()} returns true); otherwise, an |
198 * <tt>IllegalStateException</tt> is thrown. |
198 * {@code IllegalStateException} is thrown. |
199 * |
199 * |
200 * @param propName the property |
200 * @param propName the property |
201 * @return The value of the negotiated property. If null, the property was |
201 * @return The value of the negotiated property. If null, the property was |
202 * not negotiated or is not applicable to this mechanism. |
202 * not negotiated or is not applicable to this mechanism. |
203 * @exception IllegalStateException if this authentication exchange has not completed |
203 * @exception IllegalStateException if this authentication exchange has not completed |