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 * trunk/opends/resource/legal-notices/OpenDS.LICENSE
011 * or https://OpenDS.dev.java.net/OpenDS.LICENSE.
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 * trunk/opends/resource/legal-notices/OpenDS.LICENSE. 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 2006-2008 Sun Microsystems, Inc.
026 */
027 package org.opends.server.api;
028
029
030
031 import java.nio.ByteBuffer;
032 import java.nio.channels.SocketChannel;
033 import org.opends.server.config.ConfigEntry;
034 import org.opends.server.config.ConfigException;
035 import org.opends.server.types.DirectoryException;
036 import org.opends.server.types.InitializationException;
037
038
039
040 /**
041 * This class defines an API that may be used to encode and decode
042 * data for communication with clients over a secure channel (e.g.,
043 * SSL/TLS, Kerberos confidentiality, etc.).
044 */
045 @org.opends.server.types.PublicAPI(
046 stability=org.opends.server.types.StabilityLevel.VOLATILE,
047 mayInstantiate=true,
048 mayExtend=true,
049 mayInvoke=true)
050 public abstract class ConnectionSecurityProvider
051 {
052 /**
053 * Initializes this connection security provider using the
054 * information in the provided configuration entry.
055 *
056 * @param configEntry The entry that contains the configuration
057 * for this connection security provider.
058 *
059 * @throws ConfigException If the provided entry does not contain
060 * an acceptable configuration for this
061 * security provider.
062 *
063 * @throws InitializationException If a problem occurs during
064 * initialization that is not
065 * related to the provided
066 * configuration.
067 */
068 public abstract void initializeConnectionSecurityProvider(
069 ConfigEntry configEntry)
070 throws ConfigException, InitializationException;
071
072
073
074 /**
075 * Performs any finalization that may be necessary for this
076 * connection security provider.
077 */
078 public abstract void finalizeConnectionSecurityProvider();
079
080
081
082 /**
083 * Retrieves the name used to identify this security mechanism.
084 *
085 * @return The name used to identify this security mechanism.
086 */
087 public abstract String getSecurityMechanismName();
088
089
090
091 /**
092 * Indicates whether client connections using this connection
093 * security provider should be considered secure.
094 *
095 * @return {@code true} if client connections using this connection
096 * security provider should be considered secure, or
097 * {@code false} if not.
098 */
099 public abstract boolean isSecure();
100
101
102
103 /**
104 * Creates a new instance of this connection security provider that
105 * will be used to encode and decode all communication on the
106 * provided client connection.
107 *
108 * @param clientConnection The client connection with which this
109 * security provider will be associated.
110 * @param socketChannel The socket channel that may be used to
111 * communicate with the client.
112 *
113 * @return The created connection security provider instance.
114 *
115 * @throws DirectoryException If a problem occurs while creating a
116 * new instance of this security
117 * provider for the given client
118 * connection.
119 */
120 public abstract ConnectionSecurityProvider
121 newInstance(ClientConnection clientConnection,
122 SocketChannel socketChannel)
123 throws DirectoryException;
124
125
126
127 /**
128 * Indicates that the associated client connection is being closed
129 * and that this security provider should perform any necessary
130 * processing to deal with that. If it is indicated that the
131 * connection is still valid, then the security provider may attempt
132 * to communicate with the client to perform a graceful shutdown.
133 *
134 * @param connectionValid Indicates whether the Directory Server
135 * believes that the client connection is
136 * still valid and may be used for
137 * communication with the client. Note
138 * that this may be inaccurate, or that the
139 * state of the connection may change
140 * during the course of this method, so the
141 * security provider must be able to handle
142 * failures if they arise.
143 */
144 public abstract void disconnect(boolean connectionValid);
145
146
147
148 /**
149 * Retrieves the size in bytes that the client should use for the
150 * byte buffer meant to hold clear-text data read from or to be
151 * written to the client.
152 *
153 * @return The size in bytes that the client should use for the
154 * byte buffer meant to hold clear-text data read from or
155 * to be written to the client.
156 */
157 public abstract int getClearBufferSize();
158
159
160
161 /**
162 * Retrieves the size in bytes that the client should use for the
163 * byte buffer meant to hold encoded data read from or to be written
164 * to the client.
165 *
166 * @return The size in bytes that the client should use for the
167 * byte buffer meant to hold encoded data read from or to
168 * be written to the client.
169 */
170 public abstract int getEncodedBufferSize();
171
172
173
174 /**
175 * Reads data from a client connection, performing any necessary
176 * negotiation in the process. Whenever any clear-text data has
177 * been obtained, then the connection security provider should make
178 * that available to the client by calling the
179 * {@code ClientConnection.processDataRead} method.
180 *
181 * @return {@code true} if all the data in the provided buffer was
182 * processed and the client connection can remain
183 * established, or {@code false} if a decoding error
184 * occurred and requests from this client should no longer
185 * be processed. Note that if this method does return
186 * {@code false}, then it must have already disconnected
187 * the client.
188 *
189 * @throws DirectoryException If a problem occurs while reading
190 * data from the client.
191 */
192 public abstract boolean readData()
193 throws DirectoryException;
194
195
196
197 /**
198 * Writes the data contained in the provided clear-text buffer to
199 * the client, performing any necessary encoding in the process. It
200 * must be capable of dealing with input buffers that are larger
201 * than the value returned by the {@code getClearBufferSize} method.
202 * When this method returns, the provided buffer should be in its
203 * original state with regard to the position and limit.
204 *
205 * @param clearData The buffer containing the clear-text data to
206 * write to the client.
207 *
208 * @return {@code true} if all the data in the provided buffer was
209 * written to the client and the connection may remain
210 * established, or {@code false} if a problem occurred and
211 * the client connection is no longer valid. Note that if
212 * this method does return {@code false}, then it must have
213 * already disconnected the client.
214 */
215 public abstract boolean writeData(ByteBuffer clearData);
216 }
217