org.opends.server.api
Class ConnectionSecurityProvider

java.lang.Object
  extended by org.opends.server.api.ConnectionSecurityProvider
Direct Known Subclasses:
NullConnectionSecurityProvider, TLSConnectionSecurityProvider

@PublicAPI(stability=VOLATILE,
           mayInstantiate=true,
           mayExtend=true,
           mayInvoke=true)
public abstract class ConnectionSecurityProvider
extends java.lang.Object

This class defines an API that may be used to encode and decode data for communication with clients over a secure channel (e.g., SSL/TLS, Kerberos confidentiality, etc.).


Constructor Summary
ConnectionSecurityProvider()
           
 
Method Summary
abstract  void disconnect(boolean connectionValid)
          Indicates that the associated client connection is being closed and that this security provider should perform any necessary processing to deal with that.
abstract  void finalizeConnectionSecurityProvider()
          Performs any finalization that may be necessary for this connection security provider.
abstract  int getClearBufferSize()
          Retrieves the size in bytes that the client should use for the byte buffer meant to hold clear-text data read from or to be written to the client.
abstract  int getEncodedBufferSize()
          Retrieves the size in bytes that the client should use for the byte buffer meant to hold encoded data read from or to be written to the client.
abstract  java.lang.String getSecurityMechanismName()
          Retrieves the name used to identify this security mechanism.
abstract  void initializeConnectionSecurityProvider(ConfigEntry configEntry)
          Initializes this connection security provider using the information in the provided configuration entry.
abstract  boolean isSecure()
          Indicates whether client connections using this connection security provider should be considered secure.
abstract  ConnectionSecurityProvider newInstance(ClientConnection clientConnection, java.nio.channels.SocketChannel socketChannel)
          Creates a new instance of this connection security provider that will be used to encode and decode all communication on the provided client connection.
abstract  boolean readData()
          Reads data from a client connection, performing any necessary negotiation in the process.
abstract  boolean writeData(java.nio.ByteBuffer clearData)
          Writes the data contained in the provided clear-text buffer to the client, performing any necessary encoding in the process.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

ConnectionSecurityProvider

public ConnectionSecurityProvider()
Method Detail

initializeConnectionSecurityProvider

public abstract void initializeConnectionSecurityProvider(ConfigEntry configEntry)
                                                   throws ConfigException,
                                                          InitializationException
Initializes this connection security provider using the information in the provided configuration entry.

Parameters:
configEntry - The entry that contains the configuration for this connection security provider.
Throws:
ConfigException - If the provided entry does not contain an acceptable configuration for this security provider.
InitializationException - If a problem occurs during initialization that is not related to the provided configuration.

finalizeConnectionSecurityProvider

public abstract void finalizeConnectionSecurityProvider()
Performs any finalization that may be necessary for this connection security provider.


getSecurityMechanismName

public abstract java.lang.String getSecurityMechanismName()
Retrieves the name used to identify this security mechanism.

Returns:
The name used to identify this security mechanism.

isSecure

public abstract boolean isSecure()
Indicates whether client connections using this connection security provider should be considered secure.

Returns:
true if client connections using this connection security provider should be considered secure, or false if not.

newInstance

public abstract ConnectionSecurityProvider newInstance(ClientConnection clientConnection,
                                                       java.nio.channels.SocketChannel socketChannel)
                                                throws DirectoryException
Creates a new instance of this connection security provider that will be used to encode and decode all communication on the provided client connection.

Parameters:
clientConnection - The client connection with which this security provider will be associated.
socketChannel - The socket channel that may be used to communicate with the client.
Returns:
The created connection security provider instance.
Throws:
DirectoryException - If a problem occurs while creating a new instance of this security provider for the given client connection.

disconnect

public abstract void disconnect(boolean connectionValid)
Indicates that the associated client connection is being closed and that this security provider should perform any necessary processing to deal with that. If it is indicated that the connection is still valid, then the security provider may attempt to communicate with the client to perform a graceful shutdown.

Parameters:
connectionValid - Indicates whether the Directory Server believes that the client connection is still valid and may be used for communication with the client. Note that this may be inaccurate, or that the state of the connection may change during the course of this method, so the security provider must be able to handle failures if they arise.

getClearBufferSize

public abstract int getClearBufferSize()
Retrieves the size in bytes that the client should use for the byte buffer meant to hold clear-text data read from or to be written to the client.

Returns:
The size in bytes that the client should use for the byte buffer meant to hold clear-text data read from or to be written to the client.

getEncodedBufferSize

public abstract int getEncodedBufferSize()
Retrieves the size in bytes that the client should use for the byte buffer meant to hold encoded data read from or to be written to the client.

Returns:
The size in bytes that the client should use for the byte buffer meant to hold encoded data read from or to be written to the client.

readData

public abstract boolean readData()
                          throws DirectoryException
Reads data from a client connection, performing any necessary negotiation in the process. Whenever any clear-text data has been obtained, then the connection security provider should make that available to the client by calling the ClientConnection.processDataRead method.

Returns:
true if all the data in the provided buffer was processed and the client connection can remain established, or false if a decoding error occurred and requests from this client should no longer be processed. Note that if this method does return false, then it must have already disconnected the client.
Throws:
DirectoryException - If a problem occurs while reading data from the client.

writeData

public abstract boolean writeData(java.nio.ByteBuffer clearData)
Writes the data contained in the provided clear-text buffer to the client, performing any necessary encoding in the process. It must be capable of dealing with input buffers that are larger than the value returned by the getClearBufferSize method. When this method returns, the provided buffer should be in its original state with regard to the position and limit.

Parameters:
clearData - The buffer containing the clear-text data to write to the client.
Returns:
true if all the data in the provided buffer was written to the client and the connection may remain established, or false if a problem occurred and the client connection is no longer valid. Note that if this method does return false, then it must have already disconnected the client.