001/*
002 * Licensed to the Apache Software Foundation (ASF) under one
003 * or more contributor license agreements.  See the NOTICE file
004 * distributed with this work for additional information
005 * regarding copyright ownership.  The ASF licenses this file
006 * to you under the Apache License, Version 2.0 (the
007 * "License"); you may not use this file except in compliance
008 * with the License.  You may obtain a copy of the License at
009 *
010 * http://www.apache.org/licenses/LICENSE-2.0
011 *
012 * Unless required by applicable law or agreed to in writing,
013 * software distributed under the License is distributed on an
014 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
015 * KIND, either express or implied.  See the License for the
016 * specific language governing permissions and limitations
017 * under the License.
018 */
019package org.apache.directory.api.ldap.model.message.controls;
020
021
022import org.apache.directory.api.ldap.model.message.Control;
023
024
025/**
026 * Control which defines the Proxy Authorization request. More information is available in <a
027 * href="https://tools.ietf.org/html/rfc4370">RFC 4370</a>. Below we have included section 3 of the RFC describing
028 * this control:
029 *
030 * <pre>
031 *  3. Proxy Authorization Control
032 *
033 *      A single Proxy Authorization Control may be included in any search,
034 *   compare, modify, add, delete, or modify Distinguished Name (DN) or
035 *   extended operation request message.  The exception is any extension
036 *   that causes a change in authentication, authorization, or data
037 *   confidentiality [RFC2829], such as Start TLS [LDAPTLS] as part of the
038 *   controls field of the LDAPMessage, as defined in [RFC2251].
039 *
040 *   The controlType of the proxy authorization control is
041 *   "2.16.840.1.113730.3.4.18".
042 *
043 *   The criticality MUST be present and MUST be TRUE.  This requirement
044 *   protects clients from submitting a request that is executed with an
045 *   unintended authorization identity.
046 *
047 *   Clients MUST include the criticality flag and MUST set it to TRUE.
048 *   Servers MUST reject any request containing a Proxy Authorization
049 *   Control without a criticality flag or with the flag set to FALSE with
050 *   a protocolError error.  These requirements protect clients from
051 *   submitting a request that is executed with an unintended
052 *   authorization identity.
053 *
054 *   The controlValue SHALL be present and SHALL either contain an authzId
055 *   [AUTH] representing the authorization identity for the request or be
056 *   empty if an anonymous association is to be used.
057 *
058 *   The mechanism for determining proxy access rights is specific to the
059 *   server's proxy authorization policy.
060 *
061 *   If the requested authorization identity is recognized by the server,
062 *   and the client is authorized to adopt the requested authorization
063 *   identity, the request will be executed as if submitted by the proxy
064 *   authorization identity; otherwise, the result code 123 is returned.
065 * </pre>
066 *
067 * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a>
068 */
069public interface ProxiedAuthz extends Control
070{
071    /** This control OID */
072    String OID = "2.16.840.1.113730.3.4.18";
073
074
075    /**
076     * @return The authzId 
077     */
078    String getAuthzId();
079
080
081    /**
082     * @param authzId The authzId to set. Must be empty (not null), or a valid DN prefixed by 'dn:', or any
083     * user information prefixed by 'u:'
084     */
085    void setAuthzId( String authzId );
086}