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 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.ResultCode;
036import org.forgerock.opendj.ldap.controls.Control;
037import org.forgerock.opendj.ldap.controls.ControlDecoder;
038
039/**
040 * A generic Bind request which should be used for unsupported authentication
041 * methods. Servers that do not support a choice supplied by a client return a
042 * Bind response with the result code set to
043 * {@link ResultCode#AUTH_METHOD_NOT_SUPPORTED}.
044 */
045public interface GenericBindRequest extends BindRequest {
046
047    @Override
048    GenericBindRequest addControl(Control control);
049
050    @Override
051    BindClient createBindClient(String serverName) throws LdapException;
052
053    @Override
054    byte getAuthenticationType();
055
056    /**
057     * Returns the authentication information for this bind request. The content
058     * is defined by the authentication mechanism.
059     * <p>
060     * Unless otherwise indicated, implementations will store a reference to the
061     * returned byte array, allowing applications to overwrite any sensitive
062     * data such as passwords after it has been used.
063     *
064     * @return The authentication information.
065     */
066    byte[] getAuthenticationValue();
067
068    @Override
069    <C extends Control> C getControl(ControlDecoder<C> decoder, DecodeOptions options)
070            throws DecodeException;
071
072    @Override
073    List<Control> getControls();
074
075    @Override
076    String getName();
077
078    /**
079     * Sets the authentication mechanism identifier for this generic bind
080     * request. Note that value {@code 0} is reserved for simple authentication,
081     * {@code 1} and {@code 2} are reserved but unused, and {@code 3} is
082     * reserved for SASL authentication.
083     *
084     * @param type
085     *            The authentication mechanism identifier for this generic bind
086     *            request.
087     * @return This generic bind request.
088     * @throws UnsupportedOperationException
089     *             If this generic bind request does not permit the
090     *             authentication type to be set.
091     */
092    GenericBindRequest setAuthenticationType(byte type);
093
094    /**
095     * Sets the authentication information for this generic bind request in a
096     * form defined by the authentication mechanism.
097     * <p>
098     * Unless otherwise indicated, implementations will store a reference to the
099     * returned byte array, allowing applications to overwrite any sensitive
100     * data such as passwords after it has been used.
101     *
102     * @param bytes
103     *            The authentication information for this generic bind request
104     *            in a form defined by the authentication mechanism.
105     * @return This generic bind request.
106     * @throws UnsupportedOperationException
107     *             If this generic bind request does not permit the
108     *             authentication bytes to be set.
109     * @throws NullPointerException
110     *             If {@code bytes} was {@code null}.
111     */
112    GenericBindRequest setAuthenticationValue(byte[] bytes);
113
114    /**
115     * Sets the name of the Directory object that the client wishes to bind as.
116     * The name may be empty (but never {@code null} when used for of anonymous
117     * binds, or when using SASL authentication. The server shall not
118     * dereference any aliases in locating the named object.
119     * <p>
120     * The LDAP protocol defines the Bind name to be a distinguished name,
121     * however some LDAP implementations have relaxed this constraint and allow
122     * other identities to be used, such as the user's email address.
123     *
124     * @param name
125     *            The name of the Directory object that the client wishes to
126     *            bind as.
127     * @return This bind request.
128     * @throws UnsupportedOperationException
129     *             If this bind request does not permit the distinguished name
130     *             to be set.
131     * @throws NullPointerException
132     *             If {@code name} was {@code null}.
133     */
134    GenericBindRequest setName(String name);
135
136}