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-2016 ForgeRock AS.
016 */
017
018package org.forgerock.opendj.ldap.responses;
019
020import java.util.List;
021
022import org.forgerock.opendj.ldap.ByteString;
023import org.forgerock.opendj.ldap.DecodeException;
024import org.forgerock.opendj.ldap.DecodeOptions;
025import org.forgerock.opendj.ldap.ResultCode;
026import org.forgerock.opendj.ldap.controls.Control;
027import org.forgerock.opendj.ldap.controls.ControlDecoder;
028
029/**
030 * A Bind result indicates the status of the client's request for
031 * authentication.
032 * <p>
033 * A successful Bind operation is indicated by a Bind result with a result code
034 * set to {@link ResultCode#SUCCESS} and can be determined by invoking the
035 * {@link #isSuccess} method.
036 * <p>
037 * The server SASL credentials field is used as part of a SASL-defined bind
038 * mechanism to allow the client to authenticate the server to which it is
039 * communicating, or to perform "challenge-response" authentication. If the
040 * client bound using a form of simple authentication, or the SASL mechanism
041 * does not require the server to return information to the client, then this
042 * field shall not be included in the Bind result.
043 * <p>
044 * If the server requires the client to send a new SASL Bind request in order to
045 * continue the authentication process then the result code is set to
046 * {@link ResultCode#SASL_BIND_IN_PROGRESS} and can be determined by invoking
047 * the {@link #isSASLBindInProgress} method.
048 */
049public interface BindResult extends Result {
050
051    @Override
052    BindResult addControl(Control control);
053
054    @Override
055    BindResult addReferralURI(String uri);
056
057    @Override
058    Throwable getCause();
059
060    @Override
061    <C extends Control> C getControl(ControlDecoder<C> decoder, DecodeOptions options)
062            throws DecodeException;
063
064    @Override
065    List<Control> getControls();
066
067    @Override
068    String getDiagnosticMessage();
069
070    @Override
071    String getMatchedDN();
072
073    @Override
074    List<String> getReferralURIs();
075
076    @Override
077    ResultCode getResultCode();
078
079    /**
080     * Returns the server SASL credentials associated with this bind result.
081     *
082     * @return The server SASL credentials, or {@code null} indicating that none
083     *         was provided.
084     */
085    ByteString getServerSASLCredentials();
086
087    @Override
088    boolean isReferral();
089
090    /**
091     * Indicates whether the server requires the client to send a new
092     * SASL Bind request with the same SASL mechanism in order to continue the
093     * authentication process. This typically occurs during multi-stage
094     * (challenge response) authentication.
095     * <p>
096     * Specifically, this method returns {@code true} if the result code is
097     * equal to {@link ResultCode#SASL_BIND_IN_PROGRESS}.
098     *
099     * @return {@code true} if the server requires the client to send a new SASL
100     *         Bind request, otherwise {@code false}.
101     */
102    boolean isSASLBindInProgress();
103
104    @Override
105    boolean isSuccess();
106
107    @Override
108    BindResult setCause(Throwable cause);
109
110    @Override
111    BindResult setDiagnosticMessage(String message);
112
113    @Override
114    BindResult setMatchedDN(String dn);
115
116    @Override
117    BindResult setResultCode(ResultCode resultCode);
118
119    /**
120     * Sets the server SASL credentials associated with this bind result.
121     *
122     * @param credentials
123     *            The server SASL credentials associated with this bind result,
124     *            which may be {@code null} indicating that none was provided.
125     * @return This bind result.
126     * @throws UnsupportedOperationException
127     *             If this bind result does not permit the server SASL
128     *             credentials to be set.
129     */
130    BindResult setServerSASLCredentials(ByteString credentials);
131
132}