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