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