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}