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