001/* 002 * The contents of this file are subject to the terms of the Common Development and 003 * Distribution License (the License). You may not use this file except in compliance with the 004 * License. 005 * 006 * You can obtain a copy of the License at legal/CDDLv1.0.txt. See the License for the 007 * specific language governing permission and limitations under the License. 008 * 009 * When distributing Covered Software, include this CDDL Header Notice in each file and include 010 * the License file at legal/CDDLv1.0.txt. If applicable, add the following below the CDDL 011 * Header, with the fields enclosed by brackets [] replaced by your own identifying 012 * information: "Portions Copyright [year] [name of copyright owner]". 013 * 014 * Copyright 2010 Sun Microsystems, Inc. 015 * Portions copyright 2012 ForgeRock AS. 016 */ 017 018package org.forgerock.opendj.ldap; 019 020import java.net.InetSocketAddress; 021 022import javax.net.ssl.SSLContext; 023import javax.net.ssl.SSLSession; 024 025import org.forgerock.opendj.ldap.responses.ExtendedResult; 026 027/** 028 * An LDAP client which has connected to a {@link ServerConnectionFactory}. An 029 * LDAP client context can be used to query information about the client's 030 * connection such as their network address, as well as managing the state of 031 * the connection. 032 */ 033public interface LDAPClientContext { 034 035 /** 036 * Disconnects the client without sending a disconnect notification. 037 * <p> 038 * <b>Server connections:</b> invoking this method causes 039 * {@link ServerConnection#handleConnectionDisconnected 040 * handleConnectionDisconnected} to be called before this method returns. 041 */ 042 void disconnect(); 043 044 /** 045 * Disconnects the client and sends a disconnect notification, if possible, 046 * containing the provided result code and diagnostic message. 047 * <p> 048 * <b>Server connections:</b> invoking this method causes 049 * {@link ServerConnection#handleConnectionDisconnected 050 * handleConnectionDisconnected} to be called before this method returns. 051 * 052 * @param resultCode 053 * The result code which should be included with the disconnect 054 * notification. 055 * @param message 056 * The diagnostic message, which may be empty or {@code null} 057 * indicating that none was provided. 058 */ 059 void disconnect(ResultCode resultCode, String message); 060 061 /** 062 * Returns the {@code InetSocketAddress} associated with the local system. 063 * 064 * @return The {@code InetSocketAddress} associated with the local system. 065 */ 066 InetSocketAddress getLocalAddress(); 067 068 /** 069 * Returns the {@code InetSocketAddress} associated with the remote system. 070 * 071 * @return The {@code InetSocketAddress} associated with the remote system. 072 */ 073 InetSocketAddress getPeerAddress(); 074 075 /** 076 * Returns the cipher strength, in bits, currently in use by the underlying 077 * connection. This value is analogous to the 078 * {@code javax.servlet.request.key_size} property defined in the Servlet 079 * specification (section 3.8 "SSL Attributes"). It provides no indication 080 * of the relative strength of different cipher algorithms, their known 081 * weaknesses, nor the strength of other cryptographic information used 082 * during SSL/TLS negotiation. 083 * 084 * @return The cipher strength, in bits, currently in use by the underlying 085 * connection. 086 */ 087 int getSecurityStrengthFactor(); 088 089 /** 090 * Returns the SSL session currently in use by the underlying connection, or 091 * {@code null} if SSL/TLS is not enabled. 092 * 093 * @return The SSL session currently in use by the underlying connection, or 094 * {@code null} if SSL/TLS is not enabled. 095 */ 096 SSLSession getSSLSession(); 097 098 /** 099 * Returns {@code true} if the underlying connection has been closed as a 100 * result of a client disconnect, a fatal connection error, or a server-side 101 * {@link #disconnect}. 102 * <p> 103 * This method provides a polling mechanism which can be used by synchronous 104 * request handler implementations to detect connection termination. 105 * <p> 106 * <b>Server connections:</b> this method will always return {@code true} 107 * when called from within {@link ServerConnection#handleConnectionClosed 108 * handleConnectionClosed}, 109 * {@link ServerConnection#handleConnectionDisconnected 110 * handleConnectionDisconnected}, or 111 * {@link ServerConnection#handleConnectionError handleConnectionError}. 112 * 113 * @return {@code true} if the underlying connection has been closed. 114 */ 115 boolean isClosed(); 116 117 /** 118 * Sends an unsolicited notification to the client. 119 * 120 * @param notification 121 * The notification to send. 122 */ 123 void sendUnsolicitedNotification(ExtendedResult notification); 124 125 /** 126 * Installs the provided connection security layer to the underlying 127 * connection. This may be used to add a SASL integrity and/or 128 * confidentiality protection layer after SASL authentication has completed, 129 * but could also be used to add other layers such as compression. Multiple 130 * layers may be installed. 131 * 132 * @param layer 133 * The negotiated bind context that can be used to encode and 134 * decode data on the connection. 135 */ 136 void enableConnectionSecurityLayer(ConnectionSecurityLayer layer); 137 138 /** 139 * Installs the TLS/SSL security layer on the underlying connection. The 140 * TLS/SSL security layer will be installed beneath any existing connection 141 * security layers and can only be installed at most once. 142 * 143 * @param sslContext 144 * The {@code SSLContext} which should be used to secure the 145 * @param protocols 146 * Names of all the protocols to enable or {@code null} to use 147 * the default protocols. 148 * @param suites 149 * Names of all the suites to enable or {@code null} to use the 150 * default cipher suites. 151 * @param wantClientAuth 152 * Set to {@code true} if client authentication is requested, or 153 * {@code false} if no client authentication is desired. 154 * @param needClientAuth 155 * Set to {@code true} if client authentication is required, or 156 * {@code false} if no client authentication is desired. 157 * @throws IllegalStateException 158 * If the TLS/SSL security layer has already been installed. 159 */ 160 void enableTLS(SSLContext sslContext, String[] protocols, String[] suites, 161 boolean wantClientAuth, boolean needClientAuth); 162}