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