001/* 002 * Copyright 2007-2017 UnboundID Corp. 003 * All Rights Reserved. 004 */ 005/* 006 * Copyright (C) 2008-2017 UnboundID Corp. 007 * 008 * This program is free software; you can redistribute it and/or modify 009 * it under the terms of the GNU General Public License (GPLv2 only) 010 * or the terms of the GNU Lesser General Public License (LGPLv2.1 only) 011 * as published by the Free Software Foundation. 012 * 013 * This program is distributed in the hope that it will be useful, 014 * but WITHOUT ANY WARRANTY; without even the implied warranty of 015 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 016 * GNU General Public License for more details. 017 * 018 * You should have received a copy of the GNU General Public License 019 * along with this program; if not, see <http://www.gnu.org/licenses>. 020 */ 021package com.unboundid.ldap.sdk.controls; 022 023 024 025import com.unboundid.asn1.ASN1OctetString; 026import com.unboundid.ldap.sdk.BindResult; 027import com.unboundid.ldap.sdk.Control; 028import com.unboundid.ldap.sdk.DecodeableControl; 029import com.unboundid.ldap.sdk.LDAPException; 030import com.unboundid.ldap.sdk.ResultCode; 031import com.unboundid.util.NotMutable; 032import com.unboundid.util.ThreadSafety; 033import com.unboundid.util.ThreadSafetyLevel; 034 035import static com.unboundid.ldap.sdk.controls.ControlMessages.*; 036import static com.unboundid.util.Validator.*; 037 038 039 040/** 041 * This class provides an implementation of the authorization identity bind 042 * response control as defined in 043 * <A HREF="http://www.ietf.org/rfc/rfc3829.txt">RFC 3829</A>. It may be used 044 * to provide the primary authorization identity associated with the client 045 * connection after processing of the associated bind operation has completed. 046 * <BR><BR> 047 * The authorization identity value returned may be empty if the resulting 048 * authorization identity is that of the anonymous user. Otherwise, it should 049 * be an "authzId" value as described in section 5.2.1.8 of 050 * <A HREF="http://www.ietf.org/rfc/rfc4513.txt">RFC 4513</A>. That is, it 051 * should be either "dn:" followed by the distinguished name of the target user, 052 * or "u:" followed by the username. 053 * <BR><BR> 054 * Note that the authorization identity response control should only be included 055 * in a bind response message if the corresponding request included the 056 * {@link AuthorizationIdentityRequestControl}, and only if the bind was 057 * successful. 058 */ 059@NotMutable() 060@ThreadSafety(level=ThreadSafetyLevel.COMPLETELY_THREADSAFE) 061public final class AuthorizationIdentityResponseControl 062 extends Control 063 implements DecodeableControl 064{ 065 /** 066 * The OID (2.16.840.1.113730.3.4.15) for the authorization identity response 067 * control. 068 */ 069 public static final String AUTHORIZATION_IDENTITY_RESPONSE_OID = 070 "2.16.840.1.113730.3.4.15"; 071 072 073 074 /** 075 * The serial version UID for this serializable class. 076 */ 077 private static final long serialVersionUID = -6315724175438820336L; 078 079 080 081 // The authorization ID string returned by the server. 082 private final String authorizationID; 083 084 085 086 /** 087 * Creates a new empty control instance that is intended to be used only for 088 * decoding controls via the {@code DecodeableControl} interface. 089 */ 090 AuthorizationIdentityResponseControl() 091 { 092 authorizationID = null; 093 } 094 095 096 097 /** 098 * Creates a new authorization identity response control with the provided 099 * authorization ID. 100 * 101 * @param authorizationID The authorization identity associated with the 102 * client connection. It must not be {@code null}, 103 * although it may be a zero-length string to 104 * indicate that the authorization identity is the 105 * anonymous user. 106 */ 107 public AuthorizationIdentityResponseControl(final String authorizationID) 108 { 109 super(AUTHORIZATION_IDENTITY_RESPONSE_OID, false, 110 new ASN1OctetString(authorizationID)); 111 112 ensureNotNull(authorizationID); 113 114 this.authorizationID = authorizationID; 115 } 116 117 118 119 /** 120 * Creates a new authorization identity response control with the provided 121 * information. 122 * 123 * @param oid The OID for the control. 124 * @param isCritical Indicates whether the control should be marked 125 * critical. 126 * @param value The encoded value for the control. This may be 127 * {@code null} if no value was provided. 128 * 129 * @throws LDAPException If the provided control cannot be decoded as an 130 * authorization identity response control. 131 */ 132 public AuthorizationIdentityResponseControl(final String oid, 133 final boolean isCritical, 134 final ASN1OctetString value) 135 throws LDAPException 136 { 137 super(oid, isCritical, value); 138 139 if (value == null) 140 { 141 throw new LDAPException(ResultCode.DECODING_ERROR, 142 ERR_AUTHZID_RESPONSE_NO_VALUE.get()); 143 } 144 else 145 { 146 authorizationID = value.stringValue(); 147 } 148 } 149 150 151 152 /** 153 * {@inheritDoc} 154 */ 155 public AuthorizationIdentityResponseControl 156 decodeControl(final String oid, final boolean isCritical, 157 final ASN1OctetString value) 158 throws LDAPException 159 { 160 return new AuthorizationIdentityResponseControl(oid, isCritical, value); 161 } 162 163 164 165 /** 166 * Extracts an authorization identity response control from the provided 167 * result. 168 * 169 * @param result The result from which to retrieve the authorization 170 * identity response control. 171 * 172 * @return The authorization identity response control contained in the 173 * provided result, or {@code null} if the result did not contain an 174 * authorization identity response control. 175 * 176 * @throws LDAPException If a problem is encountered while attempting to 177 * decode the authorization identity response control 178 * contained in the provided result. 179 */ 180 public static AuthorizationIdentityResponseControl 181 get(final BindResult result) 182 throws LDAPException 183 { 184 final Control c = 185 result.getResponseControl(AUTHORIZATION_IDENTITY_RESPONSE_OID); 186 if (c == null) 187 { 188 return null; 189 } 190 191 if (c instanceof AuthorizationIdentityResponseControl) 192 { 193 return (AuthorizationIdentityResponseControl) c; 194 } 195 else 196 { 197 return new AuthorizationIdentityResponseControl(c.getOID(), 198 c.isCritical(), c.getValue()); 199 } 200 } 201 202 203 204 /** 205 * Retrieves the authorization ID string for this authorization identity 206 * response control. It may be a zero-length string if the associated 207 * authorization identity is that of the anonymous user. 208 * 209 * @return The authorization ID string for this authorization identity 210 * response control. 211 */ 212 public String getAuthorizationID() 213 { 214 return authorizationID; 215 } 216 217 218 219 /** 220 * {@inheritDoc} 221 */ 222 @Override() 223 public String getControlName() 224 { 225 return INFO_CONTROL_NAME_AUTHZID_RESPONSE.get(); 226 } 227 228 229 230 /** 231 * {@inheritDoc} 232 */ 233 @Override() 234 public void toString(final StringBuilder buffer) 235 { 236 buffer.append("AuthorizationIdentityResponseControl(authorizationID='"); 237 buffer.append(authorizationID); 238 buffer.append("', isCritical="); 239 buffer.append(isCritical()); 240 buffer.append(')'); 241 } 242}