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 */
016
017package org.forgerock.opendj.ldap.requests;
018
019import java.util.List;
020
021import org.forgerock.opendj.ldap.ByteString;
022import org.forgerock.opendj.ldap.DecodeException;
023import org.forgerock.opendj.ldap.DecodeOptions;
024import org.forgerock.opendj.ldap.controls.Control;
025import org.forgerock.opendj.ldap.controls.ControlDecoder;
026import org.forgerock.opendj.ldap.responses.ExtendedResultDecoder;
027import org.forgerock.opendj.ldap.responses.WhoAmIExtendedResult;
028
029/**
030 * The who am I extended request as defined in RFC 4532. This operation allows
031 * clients to obtain the primary authorization identity, in its primary form,
032 * that the server has associated with the user or application entity.
033 * <p>
034 * The following example demonstrates use of the Who Am I? request and response.
035 *
036 * <pre>
037 * Connection connection = ...;
038 * String name = ...;
039 * char[] password = ...;
040 *
041 * Result result = connection.bind(name, password);
042 * if (result.isSuccess()) {
043 *     WhoAmIExtendedRequest request = Requests.newWhoAmIExtendedRequest();
044 *     WhoAmIExtendedResult extResult = connection.extendedRequest(request);
045 *
046 *     if (extResult.isSuccess()) {
047 *         // Authz ID: "  + extResult.getAuthorizationID());
048 *     }
049 * }
050 * </pre>
051 *
052 * This operation may preferable to the Authorization Identity Controls
053 * mechanism defined in RFC 3829, which uses Bind request and response controls
054 * to request and return the authorization identity. Bind controls are not
055 * protected by security layers established by the Bind operation that includes
056 * them. While it is possible to establish security layers using StartTLS prior
057 * to the Bind operation, it is often desirable to use security layers
058 * established by the Bind operation. An extended operation sent after a Bind
059 * operation is protected by the security layers established by the Bind
060 * operation.
061 *
062 * @see WhoAmIExtendedResult
063 * @see org.forgerock.opendj.ldap.controls.AuthorizationIdentityRequestControl
064 * @see <a href="http://tools.ietf.org/html/rfc4532">RFC 4532 - Lightweight
065 *      Directory Access Protocol (LDAP) "Who am I?" Operation </a>
066 * @see <a href="http://tools.ietf.org/html/rfc3829">RFC 3829 - Lightweight
067 *      Directory Access Protocol (LDAP) Authorization Identity Request and
068 *      Response Controls </a>
069 */
070public interface WhoAmIExtendedRequest extends ExtendedRequest<WhoAmIExtendedResult> {
071
072    /**
073     * A decoder which can be used to decode who am I extended operation
074     * requests.
075     */
076    ExtendedRequestDecoder<WhoAmIExtendedRequest, WhoAmIExtendedResult> DECODER =
077            new WhoAmIExtendedRequestImpl.RequestDecoder();
078
079    /**
080     * The OID for the who am I extended operation request.
081     */
082    String OID = "1.3.6.1.4.1.4203.1.11.3";
083
084    @Override
085    WhoAmIExtendedRequest addControl(Control control);
086
087    @Override
088    <C extends Control> C getControl(ControlDecoder<C> decoder, DecodeOptions options)
089            throws DecodeException;
090
091    @Override
092    List<Control> getControls();
093
094    @Override
095    String getOID();
096
097    @Override
098    ExtendedResultDecoder<WhoAmIExtendedResult> getResultDecoder();
099
100    @Override
101    ByteString getValue();
102
103    @Override
104    boolean hasValue();
105}