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 2009-2010 Sun Microsystems, Inc.
025 *      Portions Copyright 2011-2014 ForgeRock AS
026 */
027
028package org.forgerock.opendj.ldap.requests;
029
030import java.util.List;
031
032import org.forgerock.opendj.ldap.DecodeException;
033import org.forgerock.opendj.ldap.DecodeOptions;
034import org.forgerock.opendj.ldap.LdapException;
035import org.forgerock.opendj.ldap.controls.Control;
036import org.forgerock.opendj.ldap.controls.ControlDecoder;
037
038/**
039 * The simple authentication method of the Bind Operation provides three
040 * authentication mechanisms:
041 * <ul>
042 * <li>An anonymous authentication mechanism, in which both the name and
043 * password are zero length.
044 * <li>An unauthenticated authentication mechanism using credentials consisting
045 * of a name and a zero length password.
046 * <li>A name/password authentication mechanism using credentials consisting of
047 * a name and a password.
048 * </ul>
049 * {@link Requests} has methods to create a {@code SimpleBindRequest}.
050 *
051 * <pre>
052 * String bindDN = ...;
053 * char[] bindPassword = ...;
054 *
055 * SimpleBindRequest sbr = Requests.newSimpleBindRequest(bindDN, bindPassword);
056 * </pre>
057 *
058 * Alternatively, use
059 * {@link org.forgerock.opendj.ldap.Connection#bind(String, char[])
060 * Connection.bind}.
061 *
062 * <pre>
063 * Connection connection;
064 * String bindDN = ...;
065 * char[] bindPassword = ...;
066 *
067 * connection.bind(bindDN, bindPassword);
068 * </pre>
069 */
070public interface SimpleBindRequest extends BindRequest {
071
072    @Override
073    SimpleBindRequest addControl(Control control);
074
075    @Override
076    BindClient createBindClient(String serverName) throws LdapException;
077
078    /**
079     * Returns the authentication mechanism identifier for this simple bind
080     * request as defined by the LDAP protocol, which is always {@code 0x80}.
081     *
082     * @return The authentication mechanism identifier.
083     */
084    @Override
085    byte getAuthenticationType();
086
087    @Override
088    <C extends Control> C getControl(ControlDecoder<C> decoder, DecodeOptions options)
089            throws DecodeException;
090
091    @Override
092    List<Control> getControls();
093
094    @Override
095    String getName();
096
097    /**
098     * Returns the password of the Directory object that the client wishes to
099     * bind as. The password may be empty (but never {@code null}) when used for
100     * of anonymous or unauthenticated binds.
101     * <p>
102     * Unless otherwise indicated, implementations will store a reference to the
103     * returned password byte array, allowing applications to overwrite the
104     * password after it has been used.
105     *
106     * @return The password of the Directory object that the client wishes to
107     *         bind as.
108     */
109    byte[] getPassword();
110
111    /**
112     * Sets the name of the Directory object that the client wishes to bind as.
113     * The name may be empty (but never {@code null} when used for of anonymous
114     * binds, or when using SASL authentication. The server shall not
115     * dereference any aliases in locating the named object.
116     * <p>
117     * The LDAP protocol defines the Bind name to be a distinguished name,
118     * however some LDAP implementations have relaxed this constraint and allow
119     * other identities to be used, such as the user's email address.
120     *
121     * @param name
122     *            The name of the Directory object that the client wishes to
123     *            bind as.
124     * @return This bind request.
125     * @throws UnsupportedOperationException
126     *             If this bind request does not permit the distinguished name
127     *             to be set.
128     * @throws NullPointerException
129     *             If {@code name} was {@code null}.
130     */
131    SimpleBindRequest setName(String name);
132
133    /**
134     * Sets the password of the Directory object that the client wishes to bind
135     * as. The password may be empty (but never {@code null}) when used for of
136     * anonymous or unauthenticated binds.
137     * <p>
138     * Unless otherwise indicated, implementations will store a reference to the
139     * provided password byte array, allowing applications to overwrite the
140     * password after it has been used.
141     *
142     * @param password
143     *            The password of the Directory object that the client wishes to
144     *            bind as, which may be empty.
145     * @return This simple bind request.
146     * @throws UnsupportedOperationException
147     *             If this simple bind request does not permit the password to
148     *             be set.
149     * @throws NullPointerException
150     *             If {@code password} was {@code null}.
151     */
152    SimpleBindRequest setPassword(byte[] password);
153
154    /**
155     * Sets the password of the Directory object that the client wishes to bind
156     * as. The password will be converted to a UTF-8 octet string. The password
157     * may be empty (but never {@code null}) when used for of anonymous or
158     * unauthenticated binds. Subsequent modifications to the {@code password}
159     * array will not alter this bind request.
160     *
161     * @param password
162     *            The password of the Directory object that the client wishes to
163     *            bind as, which may be empty.
164     * @return This simple bind request.
165     * @throws UnsupportedOperationException
166     *             If this simple bind request does not permit the password to
167     *             be set.
168     * @throws NullPointerException
169     *             If {@code password} was {@code null}.
170     */
171    SimpleBindRequest setPassword(char[] password);
172
173}