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-2014 ForgeRock AS.
016 */
017
018package org.forgerock.opendj.ldap.requests;
019
020import java.util.List;
021
022import org.forgerock.i18n.LocalizedIllegalArgumentException;
023import org.forgerock.opendj.ldap.DecodeException;
024import org.forgerock.opendj.ldap.DecodeOptions;
025import org.forgerock.opendj.ldap.LdapException;
026import org.forgerock.opendj.ldap.controls.Control;
027import org.forgerock.opendj.ldap.controls.ControlDecoder;
028
029/**
030 * The Plain SASL bind request as defined in RFC 4616. This SASL mechanism
031 * allows a client to authenticate to the server with an authentication ID and
032 * password. This mechanism does not provide a security layer.
033 * <p>
034 * The authentication and optional authorization identity is specified using an
035 * authorization ID, or {@code authzId}, as defined in RFC 4513 section 5.2.1.8.
036 *
037 * <pre>
038 * String authcid = ...;        // Authentication ID, e.g. dn:&lt;dn>, u:&lt;uid>
039 * String authzid = ...;        // Authorization ID, e.g. dn:&lt;dn>, u:&lt;uid>
040 * char[] password = ...;
041 * Connection connection = ...; // Use StartTLS to protect the request
042 *
043 * PlainSASLBindRequest request =
044 *         Requests.newPlainSASLBindRequest(authcid, password)
045 *         .setAuthorizationID(authzid);
046 *
047 * connection.bind(request);
048 * // Authenticated if the connection succeeds
049 * </pre>
050 *
051 * @see <a href="http://tools.ietf.org/html/rfc4616">RFC 4616 - The PLAIN Simple
052 *      Authentication and Security Layer (SASL) Mechanism </a>
053 * @see <a href="http://tools.ietf.org/html/rfc4513#section-5.2.1.8">RFC 4513 -
054 *      SASL Authorization Identities (authzId) </a>
055 */
056public interface PlainSASLBindRequest extends SASLBindRequest {
057
058    /**
059     * The name of the SASL mechanism based on PLAIN authentication.
060     */
061    String SASL_MECHANISM_NAME = "PLAIN";
062
063    @Override
064    PlainSASLBindRequest addControl(Control control);
065
066    @Override
067    BindClient createBindClient(String serverName) throws LdapException;
068
069    /**
070     * Returns the authentication ID of the user. The authentication ID usually
071     * has the form "dn:" immediately followed by the distinguished name of the
072     * user, or "u:" followed by a user ID string, but other forms are
073     * permitted.
074     *
075     * @return The authentication ID of the user.
076     */
077    String getAuthenticationID();
078
079    /**
080     * Returns the authentication mechanism identifier for this SASL bind
081     * request as defined by the LDAP protocol, which is always {@code 0xA3}.
082     *
083     * @return The authentication mechanism identifier.
084     */
085    @Override
086    byte getAuthenticationType();
087
088    /**
089     * Returns the optional authorization ID of the user which represents an
090     * alternate authorization identity which should be used for subsequent
091     * operations performed on the connection. The authorization ID usually has
092     * the form "dn:" immediately followed by the distinguished name of the
093     * user, or "u:" followed by a user ID string, but other forms are
094     * permitted.
095     *
096     * @return The authorization ID of the user, which may be {@code null}.
097     */
098    String getAuthorizationID();
099
100    @Override
101    <C extends Control> C getControl(ControlDecoder<C> decoder, DecodeOptions options)
102            throws DecodeException;
103
104    @Override
105    List<Control> getControls();
106
107    /**
108     * Returns the name of the Directory object that the client wishes to bind
109     * as, which is always the empty string for SASL authentication.
110     *
111     * @return The name of the Directory object that the client wishes to bind
112     *         as.
113     */
114    @Override
115    String getName();
116
117    /**
118     * Returns the password of the user that the client wishes to bind as.
119     * <p>
120     * Unless otherwise indicated, implementations will store a reference to the
121     * returned password byte array, allowing applications to overwrite the
122     * password after it has been used.
123     *
124     * @return The password of the user that the client wishes to bind as.
125     */
126    byte[] getPassword();
127
128    @Override
129    String getSASLMechanism();
130
131    /**
132     * Sets the authentication ID of the user. The authentication ID usually has
133     * the form "dn:" immediately followed by the distinguished name of the
134     * user, or "u:" followed by a user ID string, but other forms are
135     * permitted.
136     *
137     * @param authenticationID
138     *            The authentication ID of the user.
139     * @return This bind request.
140     * @throws UnsupportedOperationException
141     *             If this bind request does not permit the authentication ID to
142     *             be set.
143     * @throws LocalizedIllegalArgumentException
144     *             If {@code authenticationID} was non-empty and did not contain
145     *             a valid authorization ID type.
146     * @throws NullPointerException
147     *             If {@code authenticationID} was {@code null}.
148     */
149    PlainSASLBindRequest setAuthenticationID(String authenticationID);
150
151    /**
152     * Sets the optional authorization ID of the user which represents an
153     * alternate authorization identity which should be used for subsequent
154     * operations performed on the connection. The authorization ID usually has
155     * the form "dn:" immediately followed by the distinguished name of the
156     * user, or "u:" followed by a user ID string, but other forms are
157     * permitted.
158     *
159     * @param authorizationID
160     *            The authorization ID of the user, which may be {@code null}.
161     * @return This bind request.
162     * @throws UnsupportedOperationException
163     *             If this bind request does not permit the authorization ID to
164     *             be set.
165     * @throws LocalizedIllegalArgumentException
166     *             If {@code authorizationID} was non-empty and did not contain
167     *             a valid authorization ID type.
168     */
169    PlainSASLBindRequest setAuthorizationID(String authorizationID);
170
171    /**
172     * Sets the password of the user that the client wishes to bind as.
173     * <p>
174     * Unless otherwise indicated, implementations will store a reference to the
175     * provided password byte array, allowing applications to overwrite the
176     * password after it has been used.
177     *
178     * @param password
179     *            The password of the user that the client wishes to bind as,
180     *            which may be empty.
181     * @return This bind request.
182     * @throws UnsupportedOperationException
183     *             If this bind request does not permit the password to be set.
184     * @throws NullPointerException
185     *             If {@code password} was {@code null}.
186     */
187    PlainSASLBindRequest setPassword(byte[] password);
188
189    /**
190     * Sets the password of the user that the client wishes to bind as. The
191     * password will be converted to a UTF-8 octet string.
192     *
193     * @param password
194     *            The password of the user that the client wishes to bind as.
195     * @return This bind request.
196     * @throws UnsupportedOperationException
197     *             If this bind request does not permit the password to be set.
198     * @throws NullPointerException
199     *             If {@code password} was {@code null}.
200     */
201    PlainSASLBindRequest setPassword(char[] password);
202}