axTLS
axTLSj.SSLCTX Class Reference

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

Public Member Functions

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

Protected Member Functions

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

Protected Attributes

int m_ctx
 

Detailed Description

A base object for SSLServer/SSLClient.

Constructor & Destructor Documentation

◆ SSLCTX()

axTLSj.SSLCTX.SSLCTX ( int  options,
int  num_sessions 
)
inlineprotected

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.

References axTLSj.SSLCTX.m_ctx.

Member Function Documentation

◆ dispose()

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

References axTLSj.SSLCTX.m_ctx.

◆ read()

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.

References axTLSj.SSL.m_ssl.

◆ write() [1/2]

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.

References axTLSj.SSL.m_ssl.

◆ write() [2/2]

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.

References axTLSj.SSL.m_ssl.

◆ find()

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.

References axTLSj.SSLCTX.m_ctx.

◆ verifyCert()

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.

References axTLSj.SSL.m_ssl.

◆ renegotiate()

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

References axTLSj.SSL.m_ssl.

◆ objLoad() [1/2]

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

References axTLSj.SSLCTX.m_ctx.

◆ objLoad() [2/2]

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

References axTLSj.SSLCTX.m_ctx.

Field Documentation

◆ m_ctx

int axTLSj.SSLCTX.m_ctx
protected

Copyright © 2007 Cameron Rich