SSL

Description:
Perform SSL (secure sockets layer) on a pi3 IO channel. An instance of this IO class would normally be inserted between a TCPIP transport IO object and a higher level logic component implementing a TCP service to make the service secure, e.g. (HTTP-->HTTPS).

However this IO filter can be used on any IO chain, both for other transports (shared memory, named pipes) and other uses, FastCGI connections, FTP connections etc.

Typically an instance of this object is inserted into the IO chain using code like the following.

Substitute:
... IOObject TheTransportIO ...

With:
... IOObject SSL IOObject="TheTransportIO" ...

This SSL pi3 component is implemented using the OpenSSL library ( formerly known as Eric Youngs SSLeay library, thus -

   "This product includes software developed by the OpenSSL Project
	for use in the OpenSSL Toolkit (http://www.openssl.org/)."

Options:

Overview

Option	Default	Values	Short Description	Example(s)
IOObject	+	<pi3objectname>	A Pi3 object	IOObject="TCPIPIO"
Type	Passive	Active\|Passive	Specify IO layer type	Type="Passive"
Version	23	2, 3, 23 or 10	Version of SSL/TLS to accept	Version=3
Verify	0	0, 1 or 2	Client certificate verification requirements	Verify=2
VerifyDepth	8	An integer value	Level to verify peer certificate	VerifyDepth=2
CACertificatePath	-	<pathname>	CA Path	CACertificatePath="./certs"
CACertificateFile	-	<filename>	CA Certificate file to use	CACertificateFile="./ca.pem"
PrivateKeyFile	+*	<filename>	A private key file	PrivateKeyFile="./key.pem"
CertificateFile	+*	<filename>	Certificate file	CertificateFile="./cert.pem"
Flag	-	"Bugs"	Flag	Flag="Bugs"
DebugFile	-	"STDOUT", "STDERR" or <filename>	Specific an SSL debug file	DebugFile="./ssl.dbg"
CipherList	-		List of acceptable ciphers	CipherList "!ADH:RC4+RSA:HIGH:MEDIUM:LOW:EXP:+SSLv2:+EXP" ("DEFAULT", "NULL-MD5" - Read the openssl documentation for details)

- in the default indicates no default
+ in the default indicates the field is mandatory
+* in the default indicates the field is mandatory for server connections only

Description of Options

IOObject

Lower level IO object which will be loaded to provide the transport for this layer.

Type

Type of the IO filter layer, active (client) or passive (server).

Version

Version of SSL to accept, 2=SSLv2 only; 3=SSLv3 only; 23=SSLv2 or SSLv3; 10=TLS1.0

Verify

Client certificate verification mode.

0: No certificate verification is performed.
1: Certificate is verified, but not mandatory.
2: Certificate must be present.

VerifyDepth

Depth to verify peer cetificate to before giving up.

CACertificatePath

CACertificate verification path.

CACertificateFile

CACertificate file.

PrivateKeyFile

Private keyfile.

CertificateFile

Certificate file.

Flag

Specify a flag which effects the behaviour of SSL. This directive can be repeated multiple times to add different flags.

Bugs: Turn on SSL bug compatibility.
Hacks: Turn on special SSLeay hacks.
Disable: Switch off SSL (Raw TCP connection).

DebugFile

Produce an SSL debug file. Since the debug file is global to all SSL IO object instances, the first SSL IO to specify a debug file will determine the debug file created. If the filename is 'STDOUT' or 'STDERR' the debugging will be output to the standard output and standard error streams respectively.

CipherList

List of acceptable ciphers.

Returns:
PIAPI_COMPLETED on success. PIAPI_ERROR and PIAPI_ABORT respectively for generic and severe error conditions.

Example:


	<Object>
		Name SSL
		Class SSLClass
		IOObject TCPIPIOObject
	</Object>