org.kde.koala
Class KSSL

java.lang.Object
  extended by org.kde.koala.KSSL
All Implemented Interfaces:
org.kde.qt.QtSupport

public class KSSL
extends java.lang.Object
implements org.kde.qt.QtSupport

KDE SSL Wrapper Class This class implements KDE's SSL support by wrapping OpenSSL.

Author:
George Staikos
See Also:
KExtendedSocket, TCPSlaveBase

Constructor Summary
  KSSL()
           
  KSSL(boolean init)
          Construct a KSSL object
protected KSSL(java.lang.Class dummy)
           
 
Method Summary
 int accept(int sock)
          Connect the SSL session to the remote host using the provided socket descriptor.
 void close()
          Close the SSL session.
 int connect(int sock)
          Connect the SSL session to the remote host using the provided socket descriptor.
 KSSLConnectionInfo connectionInfo()
          Obtain a reference to the connection information.
 void dispose()
          Delete the wrapped C++ instance ahead of finalize()
static boolean doesSSLWork()
          Determine if SSL is available and works.
protected  void finalize()
          Deletes the wrapped C++ instance
 boolean initialize()
          Initialize OpenSSL.
 boolean isDisposed()
          Has the wrapped C++ instance been deleted?
 KSSLPeerInfo peerInfo()
          Obtain a reference to the information about the peer.
 int pending()
          Determine if data is waiting to be read.
 boolean reconfig()
          Trigger a reread of KSSL configuration and reInitialize() KSSL.
 boolean reInitialize()
          Reinitialize OpenSSL.
 boolean reusingSession()
          Determine if we are currently reusing an SSL session ID.
 int seedWithEGD()
          This will reseed the pseudo-random number generator with the EGD (entropy gathering daemon) if the EGD is configured and enabled.
 KSSLSession session()
          Obtain a pointer to the session information.
 void setAutoReconfig(boolean ar)
          Enable or disable automatic reconfiguration on initialize().
 boolean setClientCertificate(KSSLPKCS12 pkcs)
          Use this to set the certificate to send to the server.
 void setPeerHost()
           
 void setPeerHost(java.lang.String realHost)
          Set the peer hostname to be used for certificate verification.
 boolean setSession(KSSLSession session)
          Set an SSL session to use.
 boolean setSettings(KSSLSettings settings)
          Set a new KSSLSettings instance as the settings.
 KSSLSettings settings()
          One is built by the constructor, so this will only return a NULL pointer if you set one with setSettings().
 boolean TLSInit()
          This is used for applicationss which do STARTTLS or something similar.
 
Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

KSSL

protected KSSL(java.lang.Class dummy)

KSSL

public KSSL(boolean init)
Construct a KSSL object

Parameters:
init - Set this to false if you do not want this class to immediately initialize OpenSSL.

KSSL

public KSSL()
Method Detail

initialize

public boolean initialize()
Initialize OpenSSL. This will do nothing if it is already initialized.

Returns:
true on success
See Also:
reInitialize()

TLSInit

public boolean TLSInit()
This is used for applicationss which do STARTTLS or something similar. It creates a TLS method regardless of the user's settings.

Returns:
true if TLS is successfully initialized

setSession

public boolean setSession(KSSLSession session)
Set an SSL session to use. This deep copies the session so it doesn't have to remain valid. You need to call it after calling initialize or reInitialize. The ID is cleared in close().

Parameters:
session - A valid session to reuse. If null, it will clear the session ID in memory.
Returns:
true on success

close

public void close()
Close the SSL session.


reInitialize

public boolean reInitialize()
Reinitialize OpenSSL. This is not generally needed unless you are reusing the KSSL object for a new session.

Returns:
true on success
See Also:
initialize()

reconfig

public boolean reconfig()
Trigger a reread of KSSL configuration and reInitialize() KSSL. If you setAutoReconfig() to false, then this will simply reInitialize() and not read in the new configuration.

Returns:
true on successful reinitalizations
See Also:
setAutoReconfig(boolean)

setAutoReconfig

public void setAutoReconfig(boolean ar)
Enable or disable automatic reconfiguration on initialize().

Parameters:
ar - Set to false in order to disable auto-reloading of the KSSL configuration during initialize(). By default, KSSL will read its configuration on initialize(). You might want to disable this for performance reasons.

seedWithEGD

public int seedWithEGD()
This will reseed the pseudo-random number generator with the EGD (entropy gathering daemon) if the EGD is configured and enabled. You don't need to call this yourself normally.

Returns:
0 on success

setSettings

public boolean setSettings(KSSLSettings settings)
Set a new KSSLSettings instance as the settings. This deletes the current instance of KSSLSettings.

Parameters:
settings - A new, valid settings object.
Returns:
true on success

settings

public KSSLSettings settings()
One is built by the constructor, so this will only return a NULL pointer if you set one with setSettings().

Returns:
the current settings instance

setClientCertificate

public boolean setClientCertificate(KSSLPKCS12 pkcs)
Use this to set the certificate to send to the server. Do NOT delete the KSSLPKCS12 object until you are done with the session. It is not defined when KSSL will be done with this.

Parameters:
pkcs - the valid PKCS#12 object to send.
Returns:
true if the certificate was properly set to the session.

setPeerHost

public void setPeerHost(java.lang.String realHost)
Set the peer hostname to be used for certificate verification.

Parameters:
realHost - the remote hostname as the user believes to be connecting to

setPeerHost

public void setPeerHost()

connect

public int connect(int sock)
Connect the SSL session to the remote host using the provided socket descriptor.

Parameters:
sock - the socket descriptor to connect with. This must be an already connected socket.
Returns:
1 on success, 0 on error setting the file descriptor, -1 on other error.

accept

public int accept(int sock)
Connect the SSL session to the remote host using the provided socket descriptor. This is for use with an SSL server application.

Parameters:
sock - the socket descriptor to connect with. This must be an already connected socket.
Returns:
1 on success, 0 on error setting the file descriptor, -1 on other error.

pending

public int pending()
Determine if data is waiting to be read.

Returns:
-1 on error, 0 if no data is waiting, > 0 if data is waiting.

connectionInfo

public KSSLConnectionInfo connectionInfo()
Obtain a reference to the connection information.

Returns:
a reference to the connection information, valid after connected
See Also:
KSSLConnectionInfo

peerInfo

public KSSLPeerInfo peerInfo()
Obtain a reference to the information about the peer.

Returns:
a reference to the peer information, valid after connected
See Also:
KSSLPeerInfo

session

public KSSLSession session()
Obtain a pointer to the session information.

Returns:
a pointer to the session information. This is valid after connected, while connected. It is deleted by the KSSL object which returns it. May return 0L if no valid session exists.
See Also:
KSSLSession

reusingSession

public boolean reusingSession()
Determine if we are currently reusing an SSL session ID.

Returns:
true if we are reusing a session ID.

doesSSLWork

public static boolean doesSSLWork()
Determine if SSL is available and works.

Returns:
true is SSL is available and usable

finalize

protected void finalize()
                 throws java.lang.InternalError
Deletes the wrapped C++ instance

Overrides:
finalize in class java.lang.Object
Throws:
java.lang.InternalError

dispose

public void dispose()
Delete the wrapped C++ instance ahead of finalize()


isDisposed

public boolean isDisposed()
Has the wrapped C++ instance been deleted?