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