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