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-2016 ForgeRock AS.
016 */
017
018package org.forgerock.opendj.ldap;
019
020import java.net.InetSocketAddress;
021
022import javax.net.ssl.SSLEngine;
023import javax.net.ssl.SSLSession;
024import javax.security.sasl.SaslServer;
025
026import org.forgerock.opendj.ldap.responses.ExtendedResult;
027
028import com.forgerock.reactive.Completable;
029
030/**
031 * An LDAP client which has connected to a {@link ServerConnectionFactory}. An
032 * LDAP client context can be used to query information about the client's
033 * connection such as their network address, as well as managing the state of
034 * the connection.
035 */
036public interface LDAPClientContext {
037
038    /**
039     * Register a listener which will be notified when this {@link LDAPClientContext} changes state.
040     *
041     * @param listener The {@link LDAPClientContextEventListener} to register.
042     */
043    void addListener(LDAPClientContextEventListener listener);
044
045    /**
046     * Disconnects the client without sending a disconnect notification. Invoking this method causes
047     * {@link LDAPClientContextEventListener#handleConnectionDisconnected(LDAPClientContext, ResultCode, String)} to be
048     * called before this method returns.
049     */
050    void disconnect();
051
052    /**
053     * Disconnects the client and sends a disconnect notification, containing the provided result code and diagnostic
054     * message. Invoking this method causes
055     * {@link LDAPClientContextEventListener#handleConnectionDisconnected(LDAPClientContext, ResultCode, String)} to be
056     * called before this method returns.
057     *
058     * @param resultCode
059     *            The result code to include with the disconnect notification
060     * @param diagnosticMessage
061     *            The diagnostic message to include with the disconnect notification
062     */
063    void disconnect(ResultCode resultCode, String diagnosticMessage);
064
065    /**
066     * Returns the {@code InetSocketAddress} associated with the local system.
067     *
068     * @return The {@code InetSocketAddress} associated with the local system.
069     */
070    InetSocketAddress getLocalAddress();
071
072    /**
073     * Returns the {@code InetSocketAddress} associated with the remote system.
074     *
075     * @return The {@code InetSocketAddress} associated with the remote system.
076     */
077    InetSocketAddress getPeerAddress();
078
079    /**
080     * Returns the cipher strength, in bits, currently in use by the underlying
081     * connection. This value is analogous to the
082     * {@code jakarta.servlet.request.key_size} property defined in the Servlet
083     * specification (section 3.8 "SSL Attributes"). It provides no indication
084     * of the relative strength of different cipher algorithms, their known
085     * weaknesses, nor the strength of other cryptographic information used
086     * during SSL/TLS negotiation.
087     *
088     * @return The cipher strength, in bits, currently in use by the underlying
089     *         connection.
090     */
091    int getSecurityStrengthFactor();
092
093    /**
094     * Returns the SSL session currently in use by the underlying connection, or
095     * {@code null} if SSL/TLS is not enabled.
096     *
097     * @return The SSL session currently in use by the underlying connection, or
098     *         {@code null} if SSL/TLS is not enabled.
099     */
100    SSLSession getSSLSession();
101
102    /**
103     * Returns the {@link SaslServer} currently in use by the underlying connection, or
104     * {@code null} if SASL integrity and/or privacy protection is not enabled.
105     *
106     * @return The {@link SaslServer} currently in use by the underlying connection, or
107     *         {@code null} if SASL integrity and/or privacy protection is not enabled.
108     */
109    SaslServer getSASLServer();
110
111    /**
112     * Returns {@code true} if the underlying connection has been closed as a
113     * result of a client disconnect, a fatal connection error, or a server-side
114     * {@link #disconnect}.
115     * <p>
116     * This method provides a polling mechanism which can be used by synchronous
117     * request handler implementations to detect connection termination.
118     * <p>
119     * <b>Server connections:</b> this method will always return {@code true}
120     * when called from within {@link ServerConnection#handleConnectionClosed
121     * handleConnectionClosed},
122     * {@link ServerConnection#handleConnectionDisconnected
123     * handleConnectionDisconnected}, or
124     * {@link ServerConnection#handleConnectionError handleConnectionError}.
125     *
126     * @return {@code true} if the underlying connection has been closed.
127     */
128    boolean isClosed();
129
130    /**
131     * Sends an unsolicited notification to the client.
132     *
133     * @param notification
134     *            The notification to send.
135     * @return A {@link Completable} which will be completed once the notification has been sent.
136     */
137    Completable sendUnsolicitedNotification(ExtendedResult notification);
138
139    /**
140     * Installs the TLS/SSL security layer on the underlying connection. The TLS/SSL security layer will be installed
141     * beneath any existing connection security layers and can only be installed at most once.
142     *
143     * @param sslEngine
144     *            The {@code SSLEngine} which should be used to secure the connection.
145     * @param startTls
146     *            Must be {@code true} if the TLS filter has to be installed as a consequence of a StartTLS request
147     *            performed by a client. When {@code true} the TLS filter will be installed atomically after the first
148     *            message sent to prevent race-condition.
149     * @return {@code true} if the TLS filter has been enabled, {@code false} if it was already enabled.
150     * @throws NullPointerException
151     *             if sslEngine is null
152     */
153    boolean enableTLS(SSLEngine sslEngine, boolean startTls);
154
155    /**
156     * Installs the SASL security layer on the underlying connection.
157     *
158     * @param saslServer
159     *            The {@code SaslServer} which should be used to secure the connection.
160     * @return {@code true} if the SASL filter has been enabled, {@code false} if it was already enabled.
161     * @throws NullPointerException
162     *             if saslServer is null
163     */
164    boolean enableSASL(SaslServer saslServer);
165}