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 2012-2017 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 Bind operation allows authentication information to be exchanged between
030 * the client and server. The Bind operation should be thought of as the
031 * "authenticate" operation.
032 */
033public interface BindRequest extends Request {
034
035    /**
036     * The authentication type value (0x80) reserved for simple authentication.
037     */
038    byte AUTHENTICATION_TYPE_SIMPLE = (byte) 0x80;
039
040    /**
041     * The authentication type value (0xA3) reserved for SASL authentication.
042     */
043    byte AUTHENTICATION_TYPE_SASL = (byte) 0xA3;
044
045    /**
046     * The value to substitute when obfuscating passwords.
047     */
048    static final String OBFUSCATED_PASSWORD = "******";
049
050    @Override
051    BindRequest addControl(Control control);
052
053    /**
054     * Creates a new bind client which can be used to perform the authentication
055     * process. This method is called by protocol implementations and is not
056     * intended for use by applications.
057     *
058     * @param serverName
059     *            The non-null fully-qualified host name of the server to
060     *            authenticate to.
061     * @return The new bind client.
062     * @throws LdapException
063     *             If an error occurred while creating the bind client context.
064     */
065    BindClient createBindClient(String serverName) throws LdapException;
066
067    /**
068     * Returns the authentication mechanism identifier for this generic bind
069     * request as defined by the LDAP protocol. Note that the value
070     * {@link #AUTHENTICATION_TYPE_SIMPLE} ({@code 0x80}) is reserved for simple
071     * authentication and the value {@link #AUTHENTICATION_TYPE_SASL} (
072     * {@code 0xA3}) is reserved for SASL authentication.
073     *
074     * @return The authentication mechanism identifier.
075     */
076    byte getAuthenticationType();
077
078    @Override
079    <C extends Control> C getControl(ControlDecoder<C> decoder, DecodeOptions options)
080            throws DecodeException;
081
082    @Override
083    List<Control> getControls();
084
085    /**
086     * Returns the name of the Directory object that the client wishes to bind
087     * as. The name may be empty (but never {@code null}) when used for
088     * anonymous binds, or when using SASL authentication. The server shall not
089     * dereference any aliases in locating the named object.
090     * <p>
091     * The LDAP protocol defines the Bind name to be a distinguished name,
092     * however some LDAP implementations have relaxed this constraint and allow
093     * other identities to be used, such as the user's email address.
094     *
095     * @return The name of the Directory object that the client wishes to bind
096     *         as.
097     */
098    String getName();
099
100}