org.opends.server.extensions
Class TLSConnectionSecurityProvider

java.lang.Object
  extended by org.opends.server.api.ConnectionSecurityProvider
      extended by org.opends.server.extensions.TLSConnectionSecurityProvider

public class TLSConnectionSecurityProvider
extends ConnectionSecurityProvider

This class provides an implementation of a connection security provider that uses SSL/TLS to encrypt the communication to and from the client. It uses the javax.net.ssl.SSLEngine class to provide the actual SSL communication layer, and the Directory Server key and trust store providers to determine which key and trust stores to use.


Constructor Summary
TLSConnectionSecurityProvider()
          Creates a new instance of this connection security provider.
 
Method Summary
 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.
 void finalizeConnectionSecurityProvider()
          Performs any finalization that may be necessary for this connection security provider.
 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.
 java.security.cert.Certificate[] getClientCertificateChain()
          Retrieves the certificate chain that the client presented to the server during the handshake process.
 java.lang.String[] getEnabledCipherSuites()
          Retrieves the set of SSL cipher suites that will be allowed.
 java.lang.String[] getEnabledProtocols()
          Retrieves the set of SSL protocols that will be allowed.
 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.
 java.lang.String getSecurityMechanismName()
          Retrieves the name used to identify this security mechanism.
 SSLClientAuthPolicy getSSLClientAuthPolicy()
          Retrieves the policy that should be used for SSL client authentication.
 javax.net.ssl.SSLSession getSSLSession()
          Retrieves the SSL session associated with this client connection.
 void initializeConnectionSecurityProvider(ConfigEntry configEntry)
          Initializes this connection security provider using the information in the provided configuration entry.
 boolean isSecure()
          Indicates whether client connections using this connection security provider should be considered secure.
 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.
 boolean readData()
          Reads data from a client connection, performing any necessary negotiation in the process.
 void setEnabledCipherSuites(java.lang.String[] enabledCipherSuites)
          Specifies the set of SSL cipher suites that will be allowed.
 void setEnabledProtocols(java.lang.String[] enabledProtocols)
          Specifies the set of SSL protocols that will be allowed.
 void setSSLClientAuthPolicy(SSLClientAuthPolicy sslClientAuthPolicy)
          Specifies the policy that should be used for SSL client authentication.
 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

TLSConnectionSecurityProvider

public TLSConnectionSecurityProvider()
Creates a new instance of this connection security provider. Note that no initialization should be done here, since it should all be done in the initializeConnectionSecurityProvider method. Also note that this instance should only be used to create new instances that are associated with specific client connections. This instance itself should not be used to attempt secure communication with the client.

Method Detail

initializeConnectionSecurityProvider

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

Specified by:
initializeConnectionSecurityProvider in class ConnectionSecurityProvider
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 void finalizeConnectionSecurityProvider()
Performs any finalization that may be necessary for this connection security provider.

Specified by:
finalizeConnectionSecurityProvider in class ConnectionSecurityProvider

getSecurityMechanismName

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

Specified by:
getSecurityMechanismName in class ConnectionSecurityProvider
Returns:
The name used to identify this security mechanism.

isSecure

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

Specified by:
isSecure in class ConnectionSecurityProvider
Returns:
true if client connections using this connection security provider should be considered secure, or false if not.

newInstance

public 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.

Specified by:
newInstance in class ConnectionSecurityProvider
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 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.

Specified by:
disconnect in class ConnectionSecurityProvider
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 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.

Specified by:
getClearBufferSize in class ConnectionSecurityProvider
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 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.

Specified by:
getEncodedBufferSize in class ConnectionSecurityProvider
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 boolean readData()
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.

Specified by:
readData in class ConnectionSecurityProvider
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.

writeData

public 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.

Specified by:
writeData in class ConnectionSecurityProvider
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.

getEnabledProtocols

public java.lang.String[] getEnabledProtocols()
Retrieves the set of SSL protocols that will be allowed.

Returns:
The set of SSL protocols that will be allowed, or null if the default set will be used.

setEnabledProtocols

public void setEnabledProtocols(java.lang.String[] enabledProtocols)
Specifies the set of SSL protocols that will be allowed.

Parameters:
enabledProtocols - The set of SSL protocols that will be allowed, or null if the default set will be used.

getEnabledCipherSuites

public java.lang.String[] getEnabledCipherSuites()
Retrieves the set of SSL cipher suites that will be allowed.

Returns:
The set of SSL cipher suites that will be allowed.

setEnabledCipherSuites

public void setEnabledCipherSuites(java.lang.String[] enabledCipherSuites)
Specifies the set of SSL cipher suites that will be allowed.

Parameters:
enabledCipherSuites - The set of SSL cipher suites that will be allowed.

getSSLClientAuthPolicy

public SSLClientAuthPolicy getSSLClientAuthPolicy()
Retrieves the policy that should be used for SSL client authentication.

Returns:
The policy that should be used for SSL client authentication.

setSSLClientAuthPolicy

public void setSSLClientAuthPolicy(SSLClientAuthPolicy sslClientAuthPolicy)
Specifies the policy that should be used for SSL client authentication.

Parameters:
sslClientAuthPolicy - The policy that should be used for SSL client authentication.

getSSLSession

public javax.net.ssl.SSLSession getSSLSession()
Retrieves the SSL session associated with this client connection.

Returns:
The SSL session associated with this client connection.

getClientCertificateChain

public java.security.cert.Certificate[] getClientCertificateChain()
Retrieves the certificate chain that the client presented to the server during the handshake process. The client's certificate will be the first listed, followed by the certificates of any issuers in the chain.

Returns:
The certificate chain that the client presented to the server during the handshake process, or null if the client did not present a certificate.