001/*
002 * CDDL HEADER START
003 *
004 * The contents of this file are subject to the terms of the
005 * Common Development and Distribution License, Version 1.0 only
006 * (the "License").  You may not use this file except in compliance
007 * with the License.
008 *
009 * You can obtain a copy of the license at legal-notices/CDDLv1_0.txt
010 * or http://forgerock.org/license/CDDLv1.0.html.
011 * See the License for the specific language governing permissions
012 * and limitations under the License.
013 *
014 * When distributing Covered Code, include this CDDL HEADER in each
015 * file and include the License file at legal-notices/CDDLv1_0.txt.
016 * If applicable, add the following below this CDDL HEADER, with the
017 * fields enclosed by brackets "[]" replaced with your own identifying
018 * information:
019 *      Portions Copyright [yyyy] [name of copyright owner]
020 *
021 * CDDL HEADER END
022 *
023 *
024 *      Copyright 2010 Sun Microsystems, Inc.
025 *      Portions Copyright 2011-2014 ForgeRock AS
026 */
027
028package org.forgerock.opendj.ldap.requests;
029
030import java.util.List;
031import java.util.Map;
032
033import org.forgerock.i18n.LocalizedIllegalArgumentException;
034import org.forgerock.opendj.ldap.DecodeException;
035import org.forgerock.opendj.ldap.DecodeOptions;
036import org.forgerock.opendj.ldap.LdapException;
037import org.forgerock.opendj.ldap.controls.Control;
038import org.forgerock.opendj.ldap.controls.ControlDecoder;
039
040/**
041 * The DIGEST-MD5 SASL bind request as defined in RFC 2831. This SASL mechanism
042 * allows a client to perform a challenge-response authentication method,
043 * similar to HTTP Digest Access Authentication. This mechanism can be used to
044 * negotiate integrity and/or privacy protection for the underlying connection.
045 * <p>
046 * Compared to CRAM-MD5, DIGEST-MD5 prevents chosen plain-text attacks, and
047 * permits the use of third party authentication servers, mutual authentication,
048 * and optimized re-authentication if a client has recently authenticated to a
049 * server.
050 * <p>
051 * The authentication and optional authorization identity is specified using an
052 * authorization ID, or {@code authzId}, as defined in RFC 4513 section 5.2.1.8.
053 *
054 * @see <a href="http://tools.ietf.org/html/rfc2831">RFC 2831 - Using Digest
055 *      Authentication as a SASL Mechanism </a>
056 * @see <a href="http://tools.ietf.org/html/rfc4513#section-5.2.1.8">RFC 4513 -
057 *      SASL Authorization Identities (authzId) </a>
058 */
059public interface DigestMD5SASLBindRequest extends SASLBindRequest {
060
061    /**
062     * Indicates that the client will accept connection encryption using the
063     * high strength triple-DES cipher.
064     */
065    String CIPHER_3DES = "3des";
066
067    /**
068     * Indicates that the client will accept connection encryption using the
069     * medium strength DES cipher.
070     */
071    String CIPHER_DES = "des";
072
073    /**
074     * Indicates that the client will accept connection encryption using the
075     * strongest supported cipher, as long as the cipher is considered to be
076     * high strength.
077     */
078    String CIPHER_HIGH = "high";
079
080    /**
081     * Indicates that the client will accept connection encryption using the
082     * strongest supported cipher, even if the strongest cipher is considered to
083     * be medium or low strength.
084     */
085    String CIPHER_LOW = "low";
086
087    /**
088     * Indicates that the client will accept connection encryption using the
089     * strongest supported cipher, as long as the cipher is considered to be
090     * high or medium strength.
091     */
092    String CIPHER_MEDIUM = "medium";
093
094    /**
095     * Indicates that the client will accept connection encryption using the
096     * high strength 128-bit RC4 cipher.
097     */
098    String CIPHER_RC4_128 = "rc4";
099
100    /**
101     * Indicates that the client will accept connection encryption using the low
102     * strength 40-bit RC4 cipher.
103     */
104    String CIPHER_RC4_40 = "rc4-40";
105
106    /**
107     * Indicates that the client will accept connection encryption using the
108     * medium strength 56-bit RC4 cipher.
109     */
110    String CIPHER_RC4_56 = "rc4-56";
111
112    /**
113     * Indicates that the client will accept authentication only. More
114     * specifically, the underlying connection will not be protected using
115     * integrity protection or encryption, unless previously established using
116     * SSL/TLS. This is the default if no QOP option is present in the bind
117     * request.
118     */
119    String QOP_AUTH = "auth";
120
121    /**
122     * Indicates that the client will accept authentication with connection
123     * integrity protection and encryption.
124     */
125    String QOP_AUTH_CONF = "auth-conf";
126
127    /**
128     * Indicates that the client will accept authentication with connection
129     * integrity protection. More specifically, the underlying connection will
130     * not be encrypted, unless previously established using SSL/TLS.
131     */
132    String QOP_AUTH_INT = "auth-int";
133
134    /**
135     * The name of the SASL mechanism based on DIGEST-MD5 authentication.
136     */
137    String SASL_MECHANISM_NAME = "DIGEST-MD5";
138
139    /**
140     * Adds the provided additional authentication parameter to the list of
141     * parameters to be passed to the underlying mechanism implementation. This
142     * method is provided in order to allow for future extensions.
143     *
144     * @param name
145     *            The name of the additional authentication parameter.
146     * @param value
147     *            The value of the additional authentication parameter.
148     * @return This bind request.
149     * @throws UnsupportedOperationException
150     *             If this bind request does not permit additional
151     *             authentication parameters to be added.
152     * @throws NullPointerException
153     *             If {@code name} or {@code value} was {@code null}.
154     */
155    DigestMD5SASLBindRequest addAdditionalAuthParam(String name, String value);
156
157    @Override
158    DigestMD5SASLBindRequest addControl(Control control);
159
160    /**
161     * Adds the provided quality of protection (QOP) values to the ordered list
162     * of QOP values that the client is willing to accept. The order of the list
163     * specifies the preference order, high to low. Authentication will fail if
164     * no QOP values are recognized or accepted by the server.
165     * <p>
166     * By default the client will accept {@link #QOP_AUTH AUTH}.
167     *
168     * @param qopValues
169     *            The quality of protection values that the client is willing to
170     *            accept.
171     * @return This bind request.
172     * @throws UnsupportedOperationException
173     *             If this bind request does not permit QOP values to be added.
174     * @throws NullPointerException
175     *             If {@code qopValues} was {@code null}.
176     * @see #QOP_AUTH
177     * @see #QOP_AUTH_INT
178     * @see #QOP_AUTH_CONF
179     */
180    DigestMD5SASLBindRequest addQOP(String... qopValues);
181
182    @Override
183    BindClient createBindClient(String serverName) throws LdapException;
184
185    /**
186     * Returns a map containing the provided additional authentication
187     * parameters to be passed to the underlying mechanism implementation. This
188     * method is provided in order to allow for future extensions.
189     *
190     * @return A map containing the provided additional authentication
191     *         parameters to be passed to the underlying mechanism
192     *         implementation.
193     */
194    Map<String, String> getAdditionalAuthParams();
195
196    /**
197     * Returns the authentication ID of the user. The authentication ID usually
198     * has the form "dn:" immediately followed by the distinguished name of the
199     * user, or "u:" followed by a user ID string, but other forms are
200     * permitted.
201     *
202     * @return The authentication ID of the user.
203     */
204    String getAuthenticationID();
205
206    /**
207     * Returns the authentication mechanism identifier for this SASL bind
208     * request as defined by the LDAP protocol, which is always {@code 0xA3}.
209     *
210     * @return The authentication mechanism identifier.
211     */
212    @Override
213    byte getAuthenticationType();
214
215    /**
216     * Returns the optional authorization ID of the user which represents an
217     * alternate authorization identity which should be used for subsequent
218     * operations performed on the connection. The authorization ID usually has
219     * the form "dn:" immediately followed by the distinguished name of the
220     * user, or "u:" followed by a user ID string, but other forms are
221     * permitted.
222     *
223     * @return The authorization ID of the user, which may be {@code null}.
224     */
225    String getAuthorizationID();
226
227    /**
228     * Returns the cipher name or strength that the client is willing to use
229     * when connection encryption quality of protection, {@link #QOP_AUTH_CONF
230     * AUTH-CONF}, is requested.
231     * <p>
232     * By default the client will accept connection encryption using the
233     * strongest supported cipher, even if the strongest cipher is considered to
234     * be medium or low strength. This is equivalent to {@link #CIPHER_LOW}.
235     *
236     * @return The cipher that the client is willing to use if connection
237     *         encryption QOP is negotiated. May be {@code null}, indicating
238     *         that the default cipher should be used.
239     */
240    String getCipher();
241
242    @Override
243    <C extends Control> C getControl(ControlDecoder<C> decoder, DecodeOptions options)
244            throws DecodeException;
245
246    @Override
247    List<Control> getControls();
248
249    /**
250     * Returns the maximum size of the receive buffer in bytes. The actual
251     * maximum number of bytes will be the minimum of this number and the peer's
252     * maximum send buffer size. The default size is 65536.
253     *
254     * @return The maximum size of the receive buffer in bytes.
255     */
256    int getMaxReceiveBufferSize();
257
258    /**
259     * Returns the maximum size of the send buffer in bytes. The actual maximum
260     * number of bytes will be the minimum of this number and the peer's maximum
261     * receive buffer size. The default size is 65536.
262     *
263     * @return The maximum size of the send buffer in bytes.
264     */
265    int getMaxSendBufferSize();
266
267    /**
268     * Returns the name of the Directory object that the client wishes to bind
269     * as, which is always the empty string for SASL authentication.
270     *
271     * @return The name of the Directory object that the client wishes to bind
272     *         as.
273     */
274    @Override
275    String getName();
276
277    /**
278     * Returns the password of the user that the client wishes to bind as.
279     * <p>
280     * Unless otherwise indicated, implementations will store a reference to the
281     * returned password byte array, allowing applications to overwrite the
282     * password after it has been used.
283     *
284     * @return The password of the user that the client wishes to bind as.
285     */
286    byte[] getPassword();
287
288    /**
289     * Returns the ordered list of quality of protection (QOP) values that the
290     * client is willing to accept. The order of the list specifies the
291     * preference order, high to low. Authentication will fail if no QOP values
292     * are recognized or accepted by the server.
293     * <p>
294     * By default the client will accept {@link #QOP_AUTH AUTH}.
295     *
296     * @return The list of quality of protection values that the client is
297     *         willing to accept. The returned list may be empty indicating that
298     *         the default QOP will be accepted.
299     */
300    List<String> getQOPs();
301
302    /**
303     * Returns the optional realm containing the user's account.
304     *
305     * @return The name of the realm containing the user's account, which may be
306     *         {@code null}.
307     */
308    String getRealm();
309
310    @Override
311    String getSASLMechanism();
312
313    /**
314     * Returns {@code true} if the server must authenticate to the client. The
315     * default is {@code false}.
316     *
317     * @return {@code true} if the server must authenticate to the client.
318     */
319    boolean isServerAuth();
320
321    /**
322     * Sets the authentication ID of the user. The authentication ID usually has
323     * the form "dn:" immediately followed by the distinguished name of the
324     * user, or "u:" followed by a user ID string, but other forms are
325     * permitted.
326     *
327     * @param authenticationID
328     *            The authentication ID of the user.
329     * @return This bind request.
330     * @throws LocalizedIllegalArgumentException
331     *             If {@code authenticationID} was non-empty and did not contain
332     *             a valid authorization ID type.
333     * @throws UnsupportedOperationException
334     *             If this bind request does not permit the authentication ID to
335     *             be set.
336     * @throws NullPointerException
337     *             If {@code authenticationID} was {@code null}.
338     */
339    DigestMD5SASLBindRequest setAuthenticationID(String authenticationID);
340
341    /**
342     * Sets the optional authorization ID of the user which represents an
343     * alternate authorization identity which should be used for subsequent
344     * operations performed on the connection. The authorization ID usually has
345     * the form "dn:" immediately followed by the distinguished name of the
346     * user, or "u:" followed by a user ID string, but other forms are
347     * permitted.
348     *
349     * @param authorizationID
350     *            The authorization ID of the user, which may be {@code null}.
351     * @return This bind request.
352     * @throws LocalizedIllegalArgumentException
353     *             If {@code authorizationID} was non-empty and did not contain
354     *             a valid authorization ID type.
355     * @throws UnsupportedOperationException
356     *             If this bind request does not permit the authorization ID to
357     *             be set.
358     */
359    DigestMD5SASLBindRequest setAuthorizationID(String authorizationID);
360
361    /**
362     * Sets the cipher name or strength that the client is willing to use when
363     * connection encryption quality of protection, {@link #QOP_AUTH_CONF
364     * AUTH-CONF}, is requested.
365     * <p>
366     * By default the client will accept connection encryption using the
367     * strongest supported cipher, even if the strongest cipher is considered to
368     * be medium or low strength. This is equivalent to {@link #CIPHER_LOW}.
369     *
370     * @param cipher
371     *            The cipher that the client is willing to use if connection
372     *            encryption QOP is negotiated. May be {@code null}, indicating
373     *            that the default cipher should be used.
374     * @return This bind request.
375     * @throws UnsupportedOperationException
376     *             If this bind request does not permit the cipher name or
377     *             strength to be set.
378     * @see #QOP_AUTH_CONF
379     * @see #CIPHER_3DES
380     * @see #CIPHER_RC4_128
381     * @see #CIPHER_DES
382     * @see #CIPHER_RC4_56
383     * @see #CIPHER_RC4_40
384     * @see #CIPHER_HIGH
385     * @see #CIPHER_MEDIUM
386     * @see #CIPHER_LOW
387     */
388    DigestMD5SASLBindRequest setCipher(String cipher);
389
390    /**
391     * Sets the maximum size of the receive buffer in bytes. The actual maximum
392     * number of bytes will be the minimum of this number and the peer's maximum
393     * send buffer size. The default size is 65536.
394     *
395     * @param size
396     *            The maximum size of the receive buffer in bytes.
397     * @return This bind request.
398     * @throws UnsupportedOperationException
399     *             If this bind request does not permit the buffer size to be
400     *             set.
401     */
402    DigestMD5SASLBindRequest setMaxReceiveBufferSize(int size);
403
404    /**
405     * Sets the maximum size of the send buffer in bytes. The actual maximum
406     * number of bytes will be the minimum of this number and the peer's maximum
407     * receive buffer size. The default size is 65536.
408     *
409     * @param size
410     *            The maximum size of the send buffer in bytes.
411     * @return This bind request.
412     * @throws UnsupportedOperationException
413     *             If this bind request does not permit the buffer size to be
414     *             set.
415     */
416    DigestMD5SASLBindRequest setMaxSendBufferSize(int size);
417
418    /**
419     * Sets the password of the user that the client wishes to bind as.
420     * <p>
421     * Unless otherwise indicated, implementations will store a reference to the
422     * provided password byte array, allowing applications to overwrite the
423     * password after it has been used.
424     *
425     * @param password
426     *            The password of the user that the client wishes to bind as,
427     *            which may be empty.
428     * @return This bind request.
429     * @throws UnsupportedOperationException
430     *             If this bind request does not permit the password to be set.
431     * @throws NullPointerException
432     *             If {@code password} was {@code null}.
433     */
434    DigestMD5SASLBindRequest setPassword(byte[] password);
435
436    /**
437     * Sets the password of the user that the client wishes to bind as. The
438     * password will be converted to a UTF-8 octet string.
439     *
440     * @param password
441     *            The password of the user that the client wishes to bind as.
442     * @return This bind request.
443     * @throws UnsupportedOperationException
444     *             If this bind request does not permit the password to be set.
445     * @throws NullPointerException
446     *             If {@code password} was {@code null}.
447     */
448    DigestMD5SASLBindRequest setPassword(char[] password);
449
450    /**
451     * Sets the optional realm containing the user's account.
452     *
453     * @param realm
454     *            The name of the realm containing the user's account, which may
455     *            be {@code null}.
456     * @return This bind request.
457     * @throws UnsupportedOperationException
458     *             If this bind request does not permit the realm to be set.
459     * @throws NullPointerException
460     *             If {@code realm} was {@code null}.
461     */
462    DigestMD5SASLBindRequest setRealm(String realm);
463
464    /**
465     * Specifies whether or not the server must authenticate to the client. The
466     * default is {@code false}.
467     *
468     * @param serverAuth
469     *            {@code true} if the server must authenticate to the client or
470     *            {@code false} otherwise.
471     * @return This bind request.
472     * @throws UnsupportedOperationException
473     *             If this bind request does not permit server auth to be set.
474     */
475    DigestMD5SASLBindRequest setServerAuth(boolean serverAuth);
476}