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