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