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 2010 Sun Microsystems, Inc. 025 */ 026package org.forgerock.opendj.ldap.controls; 027 028import static com.forgerock.opendj.ldap.CoreMessages.ERR_AUTHZIDREQ_CONTROL_BAD_OID; 029import static com.forgerock.opendj.ldap.CoreMessages.ERR_AUTHZIDREQ_CONTROL_HAS_VALUE; 030 031import org.forgerock.i18n.LocalizableMessage; 032import org.forgerock.opendj.ldap.ByteString; 033import org.forgerock.opendj.ldap.DecodeException; 034import org.forgerock.opendj.ldap.DecodeOptions; 035 036import org.forgerock.util.Reject; 037 038/** 039 * The authorization request control as defined in RFC 3829. The authorization 040 * identity control extends the Lightweight Directory Access Protocol (LDAP) 041 * bind operation with a mechanism for requesting and returning the 042 * authorization identity it establishes. 043 * <p> 044 * The following excerpt shows how to get the authorization identity established 045 * when binding to the directory server. 046 * 047 * <pre> 048 * Connection connection = ...; 049 * String bindDN = ...; 050 * String bindPassword = ...; 051 * 052 * BindRequest request = 053 * Requests.newSimpleBindRequest(bindDN, bindPassword.toCharArray()) 054 * .addControl(AuthorizationIdentityRequestControl 055 * .newControl(true)); 056 * 057 * BindResult result = connection.bind(request); 058 * AuthorizationIdentityResponseControl control = 059 * result.getControl(AuthorizationIdentityResponseControl.DECODER, 060 * new DecodeOptions()); 061 * // Authorization ID returned: control.getAuthorizationID() 062 * </pre> 063 * 064 * @see AuthorizationIdentityResponseControl 065 * @see org.forgerock.opendj.ldap.requests.WhoAmIExtendedRequest 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 * @see <a href="http://tools.ietf.org/html/rfc4532">RFC 4532 - Lightweight 070 * Directory Access Protocol (LDAP) "Who am I?" Operation </a> 071 */ 072public final class AuthorizationIdentityRequestControl implements Control { 073 /** 074 * The OID for the authorization identity request control. 075 */ 076 public static final String OID = "2.16.840.1.113730.3.4.16"; 077 078 private final boolean isCritical; 079 080 private static final AuthorizationIdentityRequestControl CRITICAL_INSTANCE = 081 new AuthorizationIdentityRequestControl(true); 082 083 private static final AuthorizationIdentityRequestControl NONCRITICAL_INSTANCE = 084 new AuthorizationIdentityRequestControl(false); 085 086 /** 087 * A decoder which can be used for decoding the authorization identity 088 * request control. 089 */ 090 public static final ControlDecoder<AuthorizationIdentityRequestControl> DECODER = 091 new ControlDecoder<AuthorizationIdentityRequestControl>() { 092 093 public AuthorizationIdentityRequestControl decodeControl(final Control control, 094 final DecodeOptions options) throws DecodeException { 095 Reject.ifNull(control); 096 097 if (control instanceof AuthorizationIdentityRequestControl) { 098 return (AuthorizationIdentityRequestControl) control; 099 } 100 101 if (!control.getOID().equals(OID)) { 102 final LocalizableMessage message = 103 ERR_AUTHZIDREQ_CONTROL_BAD_OID.get(control.getOID(), OID); 104 throw DecodeException.error(message); 105 } 106 107 if (control.hasValue()) { 108 final LocalizableMessage message = ERR_AUTHZIDREQ_CONTROL_HAS_VALUE.get(); 109 throw DecodeException.error(message); 110 } 111 112 return control.isCritical() ? CRITICAL_INSTANCE : NONCRITICAL_INSTANCE; 113 } 114 115 public String getOID() { 116 return OID; 117 } 118 }; 119 120 /** 121 * Creates a new authorization identity request control having the provided 122 * criticality. 123 * 124 * @param isCritical 125 * {@code true} if it is unacceptable to perform the operation 126 * without applying the semantics of this control, or 127 * {@code false} if it can be ignored. 128 * @return The new control. 129 */ 130 public static AuthorizationIdentityRequestControl newControl(final boolean isCritical) { 131 return isCritical ? CRITICAL_INSTANCE : NONCRITICAL_INSTANCE; 132 } 133 134 /** Prevent direct instantiation. */ 135 private AuthorizationIdentityRequestControl(final boolean isCritical) { 136 this.isCritical = isCritical; 137 } 138 139 /** {@inheritDoc} */ 140 public String getOID() { 141 return OID; 142 } 143 144 /** {@inheritDoc} */ 145 public ByteString getValue() { 146 return null; 147 } 148 149 /** {@inheritDoc} */ 150 public boolean hasValue() { 151 return false; 152 } 153 154 /** {@inheritDoc} */ 155 public boolean isCritical() { 156 return isCritical; 157 } 158 159 /** {@inheritDoc} */ 160 @Override 161 public String toString() { 162 final StringBuilder builder = new StringBuilder(); 163 builder.append("AuthorizationIdentityRequestControl(oid="); 164 builder.append(getOID()); 165 builder.append(", criticality="); 166 builder.append(isCritical()); 167 builder.append(")"); 168 return builder.toString(); 169 } 170 171}