axTLS::SSLCTX Class Reference
[C# API.]

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

Public Member Functions

void Dispose ()
 Remove a client/server context.
int Read (SSL ssl, out byte[] in_data)
 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 (uint options, int num_sessions)
 Establish a new client/server context.

Protected Attributes

IntPtr m_ctx
 A reference to the real client/server context.

Detailed Description

A base object for SSLServer/SSLClient.


Constructor & Destructor Documentation

axTLS::SSLCTX::SSLCTX ( uint  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.
Returns:
A client/server context.

Member Function Documentation

void axTLS::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 axTLS::SSLCTX::Read ( SSL  ssl,
out byte[]  in_data 
) [inline]

Read the SSL data stream.

Parameters:
ssl [in] An SSL object reference.
in_data [out] After a successful read, the decrypted data will be here. 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 in_data before doing any successive ssl calls.
int axTLS::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 axTLS::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 axTLS::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 axTLS::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 axTLS::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 axTLS::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 axTLS::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

Copyright 2007 Cameron Rich