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 2010 Sun Microsystems, Inc.
015 * Portions Copyright 2014 ForgeRock AS.
016 */
017
018package org.forgerock.opendj.ldap.requests;
019
020import org.forgerock.opendj.ldap.ConnectionSecurityLayer;
021import org.forgerock.opendj.ldap.LdapException;
022import org.forgerock.opendj.ldap.responses.BindResult;
023
024/**
025 * An authentication client which can be used to bind to a server. Specifically,
026 * a bind client manages the state associated with multi-stage authentication
027 * attempts and responds to any challenges returned by the server.
028 */
029public interface BindClient {
030    /**
031     * Disposes of any system resources or security-sensitive information that
032     * this bind client might be using. Invoking this method invalidates this
033     * instance.
034     */
035    void dispose();
036
037    /**
038     * Evaluates the provided bind result and returns {@code true} if
039     * authentication has completed successfully, or {@code false} if additional
040     * authentication steps are required (for example during a multi-stage SASL
041     * authentication attempt).
042     * <p>
043     * If additional steps are required then implementations must update their
044     * internal state based on information contained in the bind result (for
045     * example, using the server provided SASL credentials).
046     *
047     * @param result
048     *            The bind result to be evaluated.
049     * @return {@code true} if authentication has completed successfully, of
050     *         {@code false} if additional steps are required.
051     * @throws LdapException
052     *             If the evaluation failed for some reason and authentication
053     *             cannot continue.
054     */
055    boolean evaluateResult(BindResult result) throws LdapException;
056
057    /**
058     * Returns a connection security layer, but only if this bind client has
059     * negotiated integrity and/or privacy protection for the underlying
060     * connection. This method should only be called once authentication has
061     * completed.
062     *
063     * @return A connection security layer, or {@code null} if none was
064     *         negotiated.
065     */
066    ConnectionSecurityLayer getConnectionSecurityLayer();
067
068    /**
069     * Returns the next bind request which should be used for the next stage of
070     * authentication. Initially, this will be a copy of the original bind
071     * request used to create this bind client.
072     *
073     * @return The next bind request which should be used for the next stage of
074     *         authentication.
075     */
076    GenericBindRequest nextBindRequest();
077
078}