axTLSj::SSLCTX Class Reference
[Java API.]

A base object for SSLServer/SSLClient. More...

Public Member Functions

void dispose ()
 Remove a client/server context.
int read (SSL ssl, SSLReadHolder rh)
 Read the SSL data stream.
int write (SSL ssl, byte[] out_data)
 Write to the SSL data stream.
int write (SSL ssl, byte[] out_data, int out_len)
 Write to the SSL data stream.
SSL find (Socket s)
 Find an ssl object based on a Socket reference.
int verifyCert (SSL ssl)
 Authenticate a received certificate.
int renegotiate (SSL ssl)
 Force the client to perform its handshake again.
int objLoad (int obj_type, String filename, String password)
 Load a file into memory that is in binary DER or ASCII PEM format.
int objLoad (int obj_type, byte[] data, int len, String password)
 Transfer binary data into the object loader.

Protected Member Functions

 SSLCTX (int options, int num_sessions)
 Establish a new client/server context.

Protected Attributes

int m_ctx

Detailed Description

A base object for SSLServer/SSLClient.


Constructor & Destructor Documentation

axTLSj::SSLCTX::SSLCTX ( int  options,
int  num_sessions 
) [inline, protected]

Establish a new client/server context.

This function is called before any client/server SSL connections are made. If multiple threads are used, then each thread will have its own SSLCTX context. Any number of connections may be made with a single context.

Each new connection will use the this context's private key and certificate chain. If a different certificate chain is required, then a different context needs to be be used.

Parameters:
options [in] Any particular options. At present the options supported are:

  • SSL_SERVER_VERIFY_LATER (client only): Don't stop a handshake if the server authentication fails. The certificate can be authenticated later with a call to verifyCert().
  • SSL_CLIENT_AUTHENTICATION (server only): Enforce client authentication i.e. each handshake will include a "certificate request" message from the server.
  • SSL_DISPLAY_BYTES (full mode build only): Display the byte sequences during the handshake.
  • SSL_DISPLAY_STATES (full mode build only): Display the state changes during the handshake.
  • SSL_DISPLAY_CERTS (full mode build only): Display the certificates that are passed during a handshake.
  • SSL_DISPLAY_RSA (full mode build only): Display the RSA key details that are passed during a handshake.
num_sessions [in] The number of sessions to be used for session caching. If this value is 0, then there is no session caching.

If this option is null, then the default internal private key/ certificate pair is used (if CONFIG_SSL_USE_DEFAULT_KEY is set).

The resources used by this object are automatically freed.

Returns:
A client/server context.

Member Function Documentation

void axTLSj::SSLCTX::dispose (  )  [inline]

Remove a client/server context.

Frees any used resources used by this context. Each connection will be sent a "Close Notify" alert (if possible).

int axTLSj::SSLCTX::read ( SSL  ssl,
SSLReadHolder  rh 
) [inline]

Read the SSL data stream.

Parameters:
ssl [in] An SSL object reference.
rh [out] After a successful read, the decrypted data can be retrieved with rh.getData(). It will be null otherwise.
Returns:
The number of decrypted bytes:
  • if > 0, then the handshaking is complete and we are returning the number of decrypted bytes.
  • SSL_OK if the handshaking stage is successful (but not yet complete).
  • < 0 if an error.
See also:
ssl.h for the error code list.
Note:
Use rh before doing any successive ssl calls.
int axTLSj::SSLCTX::write ( SSL  ssl,
byte[]  out_data 
) [inline]

Write to the SSL data stream.

Parameters:
ssl [in] An SSL obect reference.
out_data [in] The data to be written
Returns:
The number of bytes sent, or if < 0 if an error.
See also:
ssl.h for the error code list.
int axTLSj::SSLCTX::write ( SSL  ssl,
byte[]  out_data,
int  out_len 
) [inline]

Write to the SSL data stream.

Parameters:
ssl [in] An SSL obect reference.
out_data [in] The data to be written
out_len [in] The number of bytes to be written
Returns:
The number of bytes sent, or if < 0 if an error.
See also:
ssl.h for the error code list.
SSL axTLSj::SSLCTX::find ( Socket  s  )  [inline]

Find an ssl object based on a Socket reference.

Goes through the list of SSL objects maintained in a client/server context to look for a socket match.

Parameters:
s [in] A reference to a Socket object.
Returns:
A reference to the SSL object. Returns null if the object could not be found.
int axTLSj::SSLCTX::verifyCert ( SSL  ssl  )  [inline]

Authenticate a received certificate.

This call is usually made by a client after a handshake is complete and the context is in SSL_SERVER_VERIFY_LATER mode.

Parameters:
ssl [in] An SSL object reference.
Returns:
SSL_OK if the certificate is verified.
int axTLSj::SSLCTX::renegotiate ( SSL  ssl  )  [inline]

Force the client to perform its handshake again.

For a client this involves sending another "client hello" message. For the server is means sending a "hello request" message.

This is a blocking call on the client (until the handshake completes).

Parameters:
ssl [in] An SSL object reference.
Returns:
SSL_OK if renegotiation instantiation was ok
int axTLSj::SSLCTX::objLoad ( int  obj_type,
String  filename,
String  password 
) [inline]

Load a file into memory that is in binary DER or ASCII PEM format.

These are temporary objects that are used to load private keys, certificates etc into memory.

Parameters:
obj_type [in] The format of the file. Can be one of:

  • SSL_OBJ_X509_CERT (no password required)
  • SSL_OBJ_X509_CACERT (no password required)
  • SSL_OBJ_RSA_KEY (AES128/AES256 PEM encryption supported)
  • SSL_OBJ_P8 (RC4-128 encrypted data supported)
  • SSL_OBJ_P12 (RC4-128 encrypted data supported)

PEM files are automatically detected (if supported).

Parameters:
filename [in] The location of a file in DER/PEM format.
password [in] The password used. Can be null if not required.
Returns:
SSL_OK if all ok
int axTLSj::SSLCTX::objLoad ( int  obj_type,
byte[]  data,
int  len,
String  password 
) [inline]

Transfer binary data into the object loader.

These are temporary objects that are used to load private keys, certificates etc into memory.

Parameters:
obj_type [in] The format of the memory data.
data [in] The binary data to be loaded.
len [in] The amount of data to be loaded.
password [in] The password used. Can be null if not required.
Returns:
SSL_OK if all ok

Field Documentation

int axTLSj::SSLCTX::m_ctx [protected]

A reference to the real client/server context.

Copyright 2007 Cameron Rich