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 010 * docs/licenses/cddl.txt 011 * or http://www.opensource.org/licenses/cddl1.php. 012 * See the License for the specific language governing permissions 013 * and limitations under the License. 014 * 015 * When distributing Covered Code, include this CDDL HEADER in each 016 * file and include the License file at 017 * docs/licenses/cddl.txt. If applicable, 018 * add the following below this CDDL HEADER, with the fields enclosed 019 * by brackets "[]" replaced with your own identifying information: 020 * Portions Copyright [yyyy] [name of copyright owner] 021 * 022 * CDDL HEADER END 023 * 024 * 025 * Copyright 2010-2018 Ping Identity Corporation 026 */ 027package com.unboundid.directory.sdk.common.types; 028 029 030 031import java.net.InetAddress; 032import java.util.List; 033import java.util.Map; 034import java.util.Set; 035 036import com.unboundid.ldap.sdk.DN; 037import com.unboundid.ldap.sdk.LDAPException; 038import com.unboundid.ldap.sdk.ResultCode; 039import com.unboundid.util.NotExtensible; 040import com.unboundid.util.ThreadSafety; 041import com.unboundid.util.ThreadSafetyLevel; 042 043 044 045/** 046 * This interface defines a set of methods that may be used to obtain 047 * information about a client connection that has been established to the 048 * server. 049 */ 050@NotExtensible() 051@ThreadSafety(level=ThreadSafetyLevel.INTERFACE_NOT_THREADSAFE) 052public interface ClientContext 053{ 054 /** 055 * Retrieves the identifier that has been assigned to the associated client 056 * connection. 057 * 058 * @return The identifier that has been assigned to the associated client 059 * connection. 060 */ 061 long getConnectionID(); 062 063 064 065 /** 066 * Returns a {@code List} containing the names of all the Connection 067 * Criteria that match this connection. These are the configuration names 068 * (e.g. the RDNs, not the full DNs) of the Connection Criteria. 069 * 070 * @return a list of connection criteria names. 071 */ 072 List<String> getMatchedConnectionCriteria(); 073 074 075 076 /** 077 * Determines whether this {@code ClientContext} matches the given Connection 078 * Criteria. 079 * 080 * @param criteriaName the name (not the DN) of the Connection Criteria to 081 * check against. 082 * @return true if this {@code ClientContext} matches the specified 083 * Connection Criteria, false otherwise. 084 */ 085 boolean matchesConnectionCriteria(final String criteriaName); 086 087 088 089 /** 090 * Indicates whether this represents an internal client connection. 091 * 092 * @return {@code true} if this represents an internal client connection, or 093 * {@code false} if it is from an external client. 094 */ 095 boolean isInternal(); 096 097 098 099 /** 100 * Retrieves an internal connection that is authenticated as a root user 101 * that is not subject to access control. It may optionally use the client 102 * connection policy from the associated client connection. 103 * 104 * @param usePolicyFromConnection If {@code true}, the internal connection 105 * will use the same client connection policy 106 * as the associated client connection. If 107 * {@code false}, the internal connection 108 * will use the server's default client 109 * connection policy for internal 110 * connections. 111 * 112 * @return An internal connection that is authenticated as a root user. 113 */ 114 InternalConnection getInternalRootConnection( 115 final boolean usePolicyFromConnection); 116 117 118 119 /** 120 * Retrieves an internal connection that is authenticated as the same user 121 * as the associated client connection. It may optionally use the client 122 * connection policy from the associated client connection. 123 * 124 * @param usePolicyFromConnection If {@code true}, the internal connection 125 * will use the same client connection policy 126 * as the associated client connection. If 127 * {@code false}, the internal connection 128 * will use the server's default client 129 * connection policy for internal 130 * connections. 131 * 132 * @return An internal connection that is authenticated as the same user as 133 * the associated client connection. 134 * 135 * @throws LDAPException If a problem occurs while attempting to obtain or 136 * authenticate the connection. 137 */ 138 InternalConnection getInternalUserConnection( 139 final boolean usePolicyFromConnection) 140 throws LDAPException; 141 142 143 144 /** 145 * Retrieves an internal connection that is authenticated as the specified 146 * user. Operations on the connection may be subject to access control based 147 * on the privileges associated with the specified user. It may optionally 148 * use the client connection policy from the associated client connection. 149 * 150 * @param dn The DN of the user as whom the connection 151 * should be authenticated. It may be 152 * {@code null} or empty if the connection 153 * should be unauthenticated. 154 * @param usePolicyFromConnection If {@code true}, the internal connection 155 * will use the same client connection policy 156 * as the associated client connection. If 157 * {@code false}, the internal connection 158 * will use the server's default client 159 * connection policy for internal 160 * connections. 161 * 162 * @return An internal connection that is authenticated as the specified 163 * user. 164 * 165 * @throws LDAPException If a problem occurs while attempting to 166 * authenticate as the specified user. 167 */ 168 InternalConnection getInternalConnection(final String dn, 169 final boolean usePolicyFromConnection) 170 throws LDAPException; 171 172 173 174 /** 175 * Indicates whether the client is communicating with the server in a secure 176 * manner. 177 * 178 * @return {@code true} if the client is communicating with the server in a 179 * secure manner, or {@code false} if not. 180 */ 181 boolean isSecure(); 182 183 184 185 /** 186 * Retrieves the name of the protocol that the client is using to communicate 187 * with the server. 188 * 189 * @return The name of the protocol that the client is using to communicate 190 * with the server. 191 */ 192 String getProtocol(); 193 194 195 196 /** 197 * Retrieves the time that the connection was established. The value returned 198 * will be an offset in milliseconds since 12:00 a.m. on January 1, 1970. 199 * 200 * @return The time that the connection was established. 201 */ 202 long getConnectTime(); 203 204 205 206 /** 207 * Retrieves an {@code InetAddress} representing the address of the client 208 * system, if available. 209 * 210 * @return An {@code InetAddress} representing the address of the client 211 * system, or {@code null} if that is not available or applicable for 212 * the associated client connection. 213 */ 214 InetAddress getClientInetAddress(); 215 216 217 218 /** 219 * Retrieves an {@code InetAddress} representing the address on the server to 220 * which the client established the connection, if available. 221 * 222 * @return The address on the server to which the client established the 223 * connection, or {@code null} if that is not available or 224 * applicable. 225 */ 226 InetAddress getServerInetAddress(); 227 228 229 230 /** 231 * Indicates whether the client has authenticated to the server. 232 * 233 * @return {@code true} if the client has authenticated to the server, or 234 * {@code false} if not. 235 */ 236 boolean isAuthenticated(); 237 238 239 240 /** 241 * Retrieves information about the authentication state of the client 242 * connection. 243 * 244 * @return Information about the authentication state of the client 245 * connection. 246 */ 247 AuthInfo getAuthInfo(); 248 249 250 251 /** 252 * Indicates whether the currently-authenticated user is a member of the 253 * specified group. This will consider both direct memberships (in which the 254 * user is explicitly named as a member of the target group) and indirect 255 * memberships (in which the user is a member of the group by virtue of 256 * matching dynamic group criteria or by membership in a nested group). 257 * 258 * @param groupDN The DN of the group for which to make the determination. 259 * It must not be {@code null}. 260 * @param operation The operation currently being processed. It may be 261 * {@code null} if no operation is available. 262 * 263 * @return {@code true} if the authenticated user is a member of the 264 * specified group, or {@code false} if not. 265 * 266 * @throws LDAPException If a problem is encountered while attempting to 267 * make the determination. 268 */ 269 boolean isMemberOf(final String groupDN, final OperationContext operation) 270 throws LDAPException; 271 272 273 274 /** 275 * Retrieves the groups in which the currently-authenticated user is a member, 276 * indexed by group DN. 277 * 278 * @param operation The operation currently being processed. It 279 * may be {@code null} if no operation is 280 * available. 281 * @param directMembershipOnly Indicates whether to only consider groups in 282 * which the user is directly named as a member. 283 * If this parameter is {@code true}, then only 284 * static groups that directly contain the 285 * authenticated user will be included. If this 286 * parameter is {@code false}, then the set of 287 * groups returned will also include dynamic 288 * groups in which the user's entry matches the 289 * membership criteria, as well as static groups 290 * in which the user is a nested member. 291 * 292 * @return The groups in which the currently-authenticated user is a member, 293 * or an empty map if the client connection is not authenticated or 294 * if the authenticated user is not a member of any groups. 295 * 296 * @throws LDAPException If a problem is encountered while attempting to 297 * determine the set of groups in which the 298 * authenticated user is a member. 299 */ 300 Map<DN,Group> getGroups(final OperationContext operation, 301 final boolean directMembershipOnly) 302 throws LDAPException; 303 304 305 306 /** 307 * Indicates whether the currently-authenticated user has the specified 308 * privilege. The set of defined privileges may be found in the 309 * privilege-list.html and privilege-list.csv files in the server docs 310 * directory. 311 * 312 * @param privilegeName The name of the privilege for which to make the 313 * determination. 314 * @param operation The operation currently being processed. It may be 315 * {@code null} if no operation is available. 316 * 317 * @return {@code true} if the currently-authenticated user has the specified 318 * privilege, or {@code false} if not (or if the client is not 319 * authenticated). 320 * 321 * @throws LDAPException If the specified privilege is not defined in the 322 * server, or if a problem is encountered while trying 323 * to make the determination. 324 */ 325 boolean hasPrivilege(final String privilegeName, 326 final OperationContext operation) 327 throws LDAPException; 328 329 330 331 /** 332 * Retrieves the names of the privileges held by the currently-authenticated 333 * user. The set of defined privileges may be found in the 334 * privilege-list.html and privilege-list.csv files in the server docs 335 * directory. 336 * 337 * @return The names of the privileges held by the currently-authenticated 338 * user, or an empty set if the authenticated user does not have any 339 * privileges (or if the client is not authenticated). 340 */ 341 Set<String> getPrivilegeNames(); 342 343 344 345 /** 346 * Attempts to send an unsolicited notification to the client with the 347 * provided information. 348 * 349 * @param oid The OID for the unsolicited notification. It must not 350 * be {@code null}. 351 * @param resultCode The result code to use for the unsolicited 352 * notification. It must not be {@code null}. 353 * @param message A message to include in the unsolicited notification. 354 * It may be {@code null} if no message is needed. 355 */ 356 void sendUnsolicitedNotification(final String oid, 357 final ResultCode resultCode, 358 final String message); 359 360 361 362 /** 363 * Terminates the connection to the client and interrupts any operations that 364 * may be in progress on that connection. 365 * 366 * @param reason A general reason that the connection was closed. 367 * @param notifyClient Indicates whether to attempt to send a notice of 368 * disconnection to the client. 369 * @param message A message with information about the reason for the 370 * disconnect. It may be {@code null} if none is 371 * available. It is generally recommended that a 372 * message be provided even if the client should not be 373 * notified, since the message may be used in other 374 * ways (e.g., in log messages). 375 */ 376 void disconnect(final DisconnectReason reason, final boolean notifyClient, 377 final String message); 378 379 380 381 /** 382 * Retrieves information about the server with which the client connection is 383 * associated. 384 * 385 * @return Information about the server with which the client connection is 386 * associated. 387 */ 388 ServerContext getServerContext(); 389 390 391 392 /** 393 * Retrieves an opaque object with information about the state of an active 394 * multi-stage SASL bind. The core server will not make any attempt to 395 * interpret this object, but it is expected that any SASL mechanism handler 396 * which makes use of SASL state information will know how to interact with 397 * this object. 398 * 399 * @return An opaque object with information about the state of an active 400 * multi-stage SASL bind, or {@code null} if no state information is 401 * available (e.g., because no multi-stage SASL bind is in progress, 402 * or because no state information is needed for the active bind 403 * operation). 404 */ 405 Object getSASLAuthStateInfo(); 406 407 408 409 /** 410 * Sets state information for an active multi-stage SASL bind. It is 411 * recommended that if any SASL state information is set in the connection, 412 * then that state should be cleared when it is no longer required (e.g., 413 * after the bind has completed or failed). 414 * 415 * @param saslAuthStateInfo An opaque object that may hold information about 416 * the state of an active multi-stage SASL bind. 417 * It may be {@code null} to clear any existing 418 * SASL authentication state. The core sever will 419 * not make any attempt to interpret this object, 420 * but it is expected that any SASL mechanism 421 * handler which makes use of SASL state 422 * information will know how to interact with this 423 * object. 424 */ 425 void setSASLAuthStateInfo(final Object saslAuthStateInfo); 426 427 428 429 /** 430 * Retrieves a named object that has been associated with this client 431 * connection. 432 * 433 * @param name The name of the attachment to retrieve. It will be treated 434 * in a case-sensitive manner. Note that attachment names must 435 * be carefully crafted to avoid inadvertent conflicts between 436 * extensions or the core server itself. It is strongly 437 * recommended that attachment names be made unique (e.g., 438 * by prefixing them with the fully-qualified class name of the 439 * extension with which they are associated) so that attachments 440 * used by one extension do not inadvertently interfere with 441 * those which may be used in another extension or elsewhere in 442 * the server. 443 * 444 * @return The object that has been associated with this client connection 445 * using the given name, or {@code null} if there is no such 446 * attachment. 447 */ 448 Object getAttachment(final String name); 449 450 451 452 /** 453 * Attaches an object to this client connection. 454 * 455 * @param name The name of the attachment to retrieve. It will be treated 456 * in a case-sensitive manner. Note that attachment names must 457 * be carefully crafted to avoid inadvertent conflicts between 458 * extensions or the core server itself. It is strongly 459 * recommended that attachment names be made unique (e.g., 460 * by prefixing them with the fully-qualified class name of the 461 * extension with which they are associated) so that 462 * attachments used by one extension do not inadvertently 463 * interfere with those which may be used in another extension 464 * or elsewhere in the server. 465 * @param value The attachment to set. It may be {@code null} if an 466 * existing attachment with the given name should be removed. 467 * 468 * @return The attachment value held before the new value was assigned, or 469 * {@code null} if the attachment did not previously have a value. 470 */ 471 Object setAttachment(final String name, final Object value); 472 473 474 475 /** 476 * Retrieves a string representation of the client connection. 477 * 478 * @return A string representation of the client connection. 479 */ 480 String toString(); 481}