#include <tls.h>

Inherits securitycontext.

Public Member Functions
	tlscontext ()

virtual	~tlscontext ()

void	setProtocolVersion (const char *version)

const char *	getProtocolVersion ()

void	setCertificateChainFile (const char *filename)

const char *	getCertificateChainFile ()

void	setPrivateKeyFile (const char *filename)

const char *	getPrivateKeyFile ()

void	setPrivateKeyPassword (const char *password)

const char *	getPrivateKeyPassword ()

void	setCiphers (const char *ciphers)

const char *	getCiphers ()

void	setValidatePeer (bool validatepeer)

bool	getValidatePeer ()

void	setValidationDepth (uint16_t depth)

uint16_t	getValidationDepth ()

void	setCertificateAuthority (const char *ca)

const char *	getCertificateAuthority ()

void	setFileDescriptor (filedescriptor *fd)

filedescriptor *	getFileDescriptor ()

bool	connect ()

bool	accept ()

tlscertificate *	getPeerCertificate ()

ssize_t	read (void *buf, size_t size)

ssize_t	write (const void *buf, size_t size)

size_t	getPendingSize ()

bool	close ()

size_t	getSizeMax ()

int32_t	getError ()

const char *	getErrorString ()

Public Member Functions inherited from object
virtual	~object ()

Detailed Description

The tlscontext class implements the securitycontext interface for TLS/SSL.

Constructor & Destructor Documentation

◆ tlscontext()

tlscontext::tlscontext ( )

Creates a new instance of the tlscontext class.

◆ ~tlscontext()

virtual tlscontext::~tlscontext ( )

virtual

Deletes this instance of the tlscontext class.

Member Function Documentation

◆ accept()

bool tlscontext::accept ( )

Accepts a security context from the client with whom a connection is already established across the filedescriptor previously set using setFileDescriptor().

Note that if this instance is set as the current GSS context of a child of the socketserver class, then this method is called implicitly during a successful call to accept().

Returns true on success and false on failure.

◆ close()

bool tlscontext::close ( )

Releases any security context established during the previous call to connect() or accept().

◆ connect()

bool tlscontext::connect ( )

Initiates a security context with the server with whom a connection is already established across the filedescriptor previously set using setFileDescriptor().

Note that if this instance is set as the current security context of a child of the socketclient class, then this method is called implicitly during a successful call to connect().

Returns true on success and false on failure.

◆ getCertificateAuthority()

const char * tlscontext::getCertificateAuthority ( )

Returns the location of the certificate authority that will be used when validating the peer's certificate during the next call to connect() or accept().

◆ getCertificateChainFile()

const char * tlscontext::getCertificateChainFile ( )

Returns the location of the certificate chain file that will be used during the next call to connect() or accept().

◆ getCiphers()

const char * tlscontext::getCiphers ( )

Returns the list of ciphers that will be allowed during the next call to connect() or accept().

◆ getError()

int32_t tlscontext::getError ( )

Returns the error code of the most recently failed call.

◆ getErrorString()

const char * tlscontext::getErrorString ( )

Returns the error string of the most recently failed call.

◆ getFileDescriptor()

filedescriptor * tlscontext::getFileDescriptor ( )

virtual

Returns the file descrptor that will be used to communicate with the peer during the next call to connect() or accept().

Implements socketlayer.

◆ getPeerCertificate()

tlscertificate * tlscontext::getPeerCertificate ( )

Returns the certificate sent by the peer during the most recent call to connect() or accept() or NULL if the peer didn't send a certificate. Note that this method allocates an instance of tlscertificate internally and returns it. The calling program must delete this instance.

◆ getPendingSize()

size_t tlscontext::getPendingSize ( )

Returns the number of bytes that are buffered and available for immediate read.

◆ getPrivateKeyFile()

const char * tlscontext::getPrivateKeyFile ( )

Returns the location of the private key file that (on non-Windows platforms) will be used during the next call to connect() or accept().

◆ getPrivateKeyPassword()

const char * tlscontext::getPrivateKeyPassword ( )

Returns the password that will be used to access the private key in the certificate chain file during the next call to connect() or accept().

Note: password-protected private keys are currently not supported on Windows platforms.

◆ getProtocolVersion()

const char * tlscontext::getProtocolVersion ( )

Returns the protocol version that will be used during the next call to connect() or accept().

◆ getSizeMax()

size_t tlscontext::getSizeMax ( )

Returns the maximum number of bytes that can be written or read in a single call to write() or read().

◆ getValidatePeer()

bool tlscontext::getValidatePeer ( )

Returns whether or not the peer's certificate was explicitly configured to be validated during the next call to connect() or accept().

◆ getValidationDepth()

uint16_t tlscontext::getValidationDepth ( )

Returns the validation depth that will be used when validating the peer's certificate during the next call to connect() or accept().

◆ read()

ssize_t tlscontext::read	(	void *	buf,
		size_t	size )

Reads from the file descriptor previously configured by setFileDescriptor() into "buf" until "size" bytes have been read. Returns the number of bytes that were written to "buf" or RESULT_ERROR if an error occurred.

◆ setCertificateAuthority()

void tlscontext::setCertificateAuthority ( const char * ca )

Sets the location of the certificate store that contains the certificate of the certificate authority (CA cert) to use when validating the peer's certificate during the next call to connect() or accept().

If "ca" is NULL or empty then no validation of the peer certificate will occur during the next call to connect() or accept().

Otherwise...

On non-Windows systems, "ca" can be either a file name or directory name. If it a file name, then only that file will be used, though the file may contain multiple CA certs. If it is a directory name, then all certificate store files found in that directory will be used.

On Windows platforms, "ca" may refer to a file or to a Windows Certificate Store. If it a file name, then only that file will be used, though the file may contain multiple CA certs. If it is a Windows Certificate Store, then all certificates in the store will be used.

Note that the supported file formats may vary between platforms. A variety of formats are generally supported on Linux and Unix platforms (.pem, .pfx, etc.) but only .pfx files are currently supported on Windows.

To specify a Windows Certificate Store, "ca" must be specified in one of the following formats: location:store store

The "location" parameter identifies the certificate store location, and must be one of the following: CURRENT_USER LOCAL_MACHINE CURRENT_SERVICE SERVICES USERS CURRENT_USER_GROUP_POLICY LOCAL_MACHINE_GROUP_POLICY LOCAL_MACHINE_ENTERPRISE If "location" is omitted then it defaults to CURRENT_USER.

The "store" parameter identifies the certificate store, and must be one of the following: MY Root Trust CA If "store" is omitted then it defaults to MY.

◆ setCertificateChainFile()

void tlscontext::setCertificateChainFile ( const char * filename )

Sets the location of the certificate chain file to use during the next call to connect() or accept().

If "filename" is NULL or empty then no certificate will be sent to the peer.

Otherwise...

On non-Windows platforms, "filename" must refer to an actual file. On Windows platforms, it may refer to an actual file or to a certificate found in a Windows Certificate Store.

Actual files must contain the client's certificate and the chain of signing certificates, terminating in a certificate for a root certificate authority. On Windows platforms, the file must also contain the client's private key. On non-Windows platforms, the private key may be stored in a separate file, specified by setPrivateKeyFile().

Note that the supported file formats may vary between platforms. A variety of formats are generally supported on Linux and Unix platforms (.pem, .pfx, etc.) but only .pfx files are currently supported on Windows.

Certificates in a Windows Certificate Store must have an associated private key and associated chain of signing certificates, terminating in a certificate for a root certificate authority.

To specify an entry in a Windows Certificate Store, "filename" must be specified in one of the following formats: location:store:subject store:subject subject

The "location" parameter identifies the certificate store location, and must be one of the following: CURRENT_USER LOCAL_MACHINE CURRENT_SERVICE SERVICES USERS CURRENT_USER_GROUP_POLICY LOCAL_MACHINE_GROUP_POLICY LOCAL_MACHINE_ENTERPRISE If "location" is omitted then it defaults to CURRENT_USER.

The "store" parameter identifies the certificate store, and must be one of the following: MY Root Trust CA If "store" is omitted then it defaults to MY.

The "subject" parameter identifies the certificate. The first certificate in the specified location/store who's Subject contains "subject" (case-insensitive) will be used. Note that the order of the certificates in the store is not guaranteed, so "subject" should contain enough information to uniquely identify a certificate.

◆ setCiphers()

void tlscontext::setCiphers ( const char * ciphers )

Sets the list of ciphers to allow during the next call to connect() or accept(). Ciphers may be separated by spaces, commas, or colons. If "ciphers" is NULL or empty then a default set of ciphers will be used.

For a list of valid ciphers on Linux and Unix platforms, see: man ciphers

For a list of valid ciphers on Windows platforms, see: https://msdn.microsoft.com/en-us/library/windows/desktop/aa375549%28v=vs.85%29.aspx On Windows platforms, the ciphers (alg_id's) should omit CALG_ and may be given with underscores or dashes. For example: 3DES_112

◆ setFileDescriptor()

void tlscontext::setFileDescriptor ( filedescriptor * fd )

virtual

Sets the file descriptor that will be used to communicate with the peer during the next call to connect() or accept().

Implements socketlayer.

◆ setPrivateKeyFile()

void tlscontext::setPrivateKeyFile ( const char * filename )

Ignored on Windows platforms.

On non-Windows platforms:

Sets the location of the private key file to use during the next call to connect() or accept().

If no private key file is specified via this call, either because the call is omitted, or because "filename" is NULL or empty, then the certificate chain file will be searched for the private key.

Note that the supported file formats may vary between platforms. A variety of formats are generally supported on Linux and Unix platforms (.pem, .pfx, etc.) but only the .pfx format is currently supported on Windows.

◆ setPrivateKeyPassword()

void tlscontext::setPrivateKeyPassword ( const char * password )

Sets the password to use when accessing the private key in the certificate chain file during the next call to connect() or accept().

Note: password-protected private keys are currently not supported on Windows platforms.

◆ setProtocolVersion()

void tlscontext::setProtocolVersion ( const char * version )

Sets the protocol version to use during the next call to connect() or accept().

Valid values include SSL2, SSL3, TLS1, TLS1.1, TLS1.2 or any more recent version of TLS, as supported by and enabled in the underlying TLS/SSL library. If left blank or empty then the highest supported version will be negotiated.

◆ setValidatePeer()

void tlscontext::setValidatePeer ( bool validatepeer )

Instructs the next call to connect() or accept() whether or not to validate the peer's certificate. Defaults to true for connect() and false for accept().

◆ setValidationDepth()

void tlscontext::setValidationDepth ( uint16_t depth )

Sets the validation depth to use when validating the peer's certificate during the next call to connect() or accept().

There could be any number of intermediate signing authorities between the peer's certificate and a top-level certificate authority.

For example, the certificate chain could consist of:

peer's certificate (signed by A)
A's certificate (signed by B)
B's certificate (signed by C)
...
Y's certificate (signed by a top-level authority)
top-level authority's certificate

Setting the validation depth instructs the context to only allow "depth" certificates between the peer certificate and a top-level authority.

The default, and maximum depth is 9. Setting a depth greater than 9 has the same effect as setting it to 9. Setting the depth to 0 also has the same effect as setting it to 9.

◆ write()

ssize_t tlscontext::write	(	const void *	buf,
		size_t	size )

Writes "size" bytes from "buf" to the file descriptor previously configured by setFileDescriptor(). Returns the number of bytes that were written or RESULT_ERROR if an error occurred.

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ tlscontext()

◆ ~tlscontext()

Member Function Documentation

◆ accept()

◆ close()

◆ connect()

◆ getCertificateAuthority()

◆ getCertificateChainFile()

◆ getCiphers()

◆ getError()

◆ getErrorString()

◆ getFileDescriptor()

◆ getPeerCertificate()

◆ getPendingSize()

◆ getPrivateKeyFile()

◆ getPrivateKeyPassword()

◆ getProtocolVersion()

◆ getSizeMax()

◆ getValidatePeer()

◆ getValidationDepth()

◆ read()

◆ setCertificateAuthority()

◆ setCertificateChainFile()

◆ setCiphers()

◆ setFileDescriptor()

◆ setPrivateKeyFile()

◆ setPrivateKeyPassword()

◆ setProtocolVersion()

◆ setValidatePeer()

◆ setValidationDepth()

◆ write()