Represents an SSL/TLS context and is an adapter for the underlying cryptographic library's representation of a secure socket context. More...

#include <rw/secsock/RWSecureSocketContext.h>

Inheritance diagram for RWSecureSocketContext:

Public Member Functions
	RWSecureSocketContext ()

	RWSecureSocketContext (const RWSecureSocketMethod &method)

	RWSecureSocketContext (RWSecureSocketProtocolVersion minVersion, RWSecureSocketProtocolVersion maxVersion, RWSecureSocketSide side=RW_CLIENT_OR_SERVER)

	RWSecureSocketContext (const RWSecureSocketContext &second)

	~RWSecureSocketContext (void)

bool	checkPrivateKey (void) const

RWVerifyCallback	getCertificateVerifyCallback (void) const

int	getCertificateVerifyMode (void) const

RWClientCertificateCallback	getClientCertificateCallback (void) const

RWSecureSocketContextRep	getRep (void) const

RWSSLShutdownMode	getShutdownMode (void) const

void	loadVerifyLocations (const RWCString &file)

RWSecureSocketContext &	operator= (const RWSecureSocketContext &second)

void	prepareToAuthenticate (const RWCString &trustedCertFile)

void	setCertificate (const RWX509Certificate &cert)

void	setCertificateVerifyCallback (RWVerifyCallback fun)

void	setCertificateVerifyMode (int mode)

void	setCipherList (const RWCString &list)

void	setClientCertificateCallback (RWClientCertificateCallback fun)

void	setIdentity (const RWX509Certificate &cert, const RWPrivateKey &key)

void	setOptions (long op)

void	setPrivateKey (const RWPrivateKey &pkey)

void	setSessionId (const RWCString &id)

void	setShutdownMode (RWSSLShutdownMode mode)

void	setVerify (int mode, RWVerifyCallback fun)

Public Member Functions inherited from RWHandleBase
bool	isValid (void) const

bool	operator!= (const RWHandleBase &second) const

bool	operator< (const RWHandleBase &second) const

bool	operator== (const RWHandleBase &second) const

Related Functions
(Note that these are not member functions.)
typedef int(*	RWClientCertificateCallback) (SSL conn, X509 cert, EVP_PKEY *pkey)

typedef SSL_CTX *	RWSecureSocketContextRep

typedef int(*	RWVerifyCallback) (int pass, X509_STORE_CTX *ctxt)

Additional Inherited Members
Protected Member Functions inherited from RWHandleBase
	RWHandleBase (void)

	RWHandleBase (RWStaticCtor)

	RWHandleBase (RWBodyBase *body)

	RWHandleBase (const RWHandleBase &second)

	~RWHandleBase (void)

RWBodyBase &	body (void) const

RWHandleBase &	operator= (const RWHandleBase &second)

Detailed Description

RWSecureSocketContext represents an SSL/TLS context. It is an adapter for the underlying cryptographic library's representation of a secure socket context. The context contains the default settings for all secure sockets created by using this class. RWSecureSocketContext also maintains the session cache. The defaults set with this class may be overridden on a per-connection basis.

Every application using the Secure Sockets package must create at least one instance of RWSecureSocketContext and then initialize it with setIdentity() and/or prepareToAuthenticate(). In general, server programs use setIdentity(), and clients use prepareToAuthenticate(). If an application requires both client and server authentication, both the client and the server call both functions. For more information, see the Secure Communication Module User's Guide.

The constructor for RWSecureSocketContext throws an RWSecureSocketRNGNotSeededError exception unless one of the Secure Sockets package random number generator seeding functions or constructors was used before the construction of the RWSecureSocketContext.

RWSecureSocketContext uses the handle-body idiom handle memory management for the cryptographic library. This implementation also ensures that the body and the associated memory are not destroyed until all handles to that body are destroyed.

Note: For a full discussion of the handle-body idiom, see Section 7.3.1, "Understanding the Handle-Body Idiom," in the Threads Module User's Guide.

Constructor & Destructor Documentation

RWSecureSocketContext::RWSecureSocketContext ( )

Constructs a secure socket context. The resulting context will support all versions of SSL/TLS available, and will fall back as necessary. This should be sufficient for most needs.

Exceptions

RWSecureSocketPackageNotInitializedError	Thrown if the Secure Sockets package has not been initialized. See RWSecureSocketPackageInit for more information.
RWSecureSocketUnderlyingAllocationError	Thrown if the cryptographic library is unsuccessful in allocating memory.

Note: Calls setOptions(SSL_OP_ALL) to enable all known compatibility flags. See the description of the setOptions() function for more information.

RWSecureSocketContext::RWSecureSocketContext ( const RWSecureSocketMethod & method )

Deprecated:: Deprecated as of SourcePro 2016.3. Use another constructor.

Deprecated. Constructs a secure socket context. The method parameter specifies which versions of SSL/TLS the application will support.

Exceptions

RWSecureSocketPackageNotInitializedError	Thrown if the Secure Sockets package has not been initialized. See RWSecureSocketPackageInit for more information.
RWSecureSocketUnderlyingAllocationError	Thrown if the cryptographic library is unsuccessful in allocating memory.
RWSecureSocketInvalidMethodError	Thrown if the OpenSSL library is not built with support for the version of SSL/TLS specified by the `method` parameter.

Note: Calls setOptions(SSL_OP_ALL) to enable all known compatibility flags. See the description of the setOptions() function for more information.

RWSecureSocketContext::RWSecureSocketContext	(	RWSecureSocketProtocolVersion	minVersion,
		RWSecureSocketProtocolVersion	maxVersion,
		RWSecureSocketSide	side = `RW_CLIENT_OR_SERVER`
	)

Constructs a secure socket context.

The minVersion and maxVersion parameters indicate the minimum and maximum SSL/TLS protocol version the context will support.

The side parameter indicates the side of the protocol that this context will implement.

Exceptions

RWSecureSocketPackageNotInitializedError	Thrown if the Secure Sockets package has not been initialized. See RWSecureSocketPackageInit for more information.
RWSecureSocketUnderlyingAllocationError	Thrown if the cryptographic library is unsuccessful in allocating memory.
RWSecureSocketVersionError	Thrown if the library is unable to satisfy the request for the given protocol versions.

Note: Calls setOptions(SSL_OP_ALL) to enable all known compatibility flags. See the description of the setOptions() function for more information.; This constructor is available only if building with OpenSSL 1.0.1 and later.

RWSecureSocketContext::RWSecureSocketContext ( const RWSecureSocketContext & second )

inline

Copy constructor.

RWSecureSocketContext::~RWSecureSocketContext ( void )

inline

Destructor.

Member Function Documentation

bool RWSecureSocketContext::checkPrivateKey ( void ) const

inline

Returns true if the previously specified private key matches the previously specified certificate, returns false otherwise.

RWVerifyCallback RWSecureSocketContext::getCertificateVerifyCallback ( void ) const

inline

Gets the certificate verification callback previously set by setVerify() or setCertificateVerifyCallback().

int RWSecureSocketContext::getCertificateVerifyMode ( void ) const

inline

Gets the certificate verify mode previously set by setVerify() or setCertificateVerifyMode(). See setCertificateVerifyMode() for more information.

RWClientCertificateCallback RWSecureSocketContext::getClientCertificateCallback ( void ) const

inline

Gets the client certificate callback. This callback is invoked by the client when a server requests a certificate from the client. See the Secure Communication Module User's Guide for more information.

RWSecureSocketContextRep RWSecureSocketContext::getRep ( void ) const

inline

Returns a pointer to the cryptographic library's representation of the context.

Note: The memory that this pointer references is owned by the body class, so users should not attempt to delete it. The memory is released when all handles referring to that body are destroyed.

RWSSLShutdownMode RWSecureSocketContext::getShutdownMode ( void ) const

inline

Gets the current default shutdown mode for all sockets and portals created with this RWSecureSocketContext.

void RWSecureSocketContext::loadVerifyLocations ( const RWCString & file )

inline

Specifies a pathname for the file containing the trusted certificates, which are stored sequentially in PEM format. In most applications, the client uses this function to authenticate the server. If client authentication is desired, the server also calls this function to authenticate the client.

Multiple certificates may be stored in file.

Exceptions

RWSecureSocketInvalidFileError	Thrown if the file does not exist.
RWSSLContextLoadVerifyLocationsError	Thrown if the call to SSL_CTX_load_verify_locations() in the underlying library fails. The RWCString must be encoded as UTF-8.

RWSecureSocketContext & RWSecureSocketContext::operator= ( const RWSecureSocketContext & second )

inline

Assignment operator.

void RWSecureSocketContext::prepareToAuthenticate ( const RWCString & trustedCertFile )

inline

A convenience function that should be used by the side of the SSL/TLS protocol that is performing the authentication. Normally this function is called by the client. If client authentication is also desired, this function is also called by the server. Calling prepareToAuthenticate() is equivalent to calling loadVerifyLocations(trustedCertsFile) followed by setCertificateVerifyMode(SSL_VERIFY_PEER).

Exceptions

RWSecureSocketInvalidFileError	Thrown if the file supplied does not exist or is otherwise invalid. The parameter trustedCertFile must be encoded as UTF-8.
RWSSLContextLoadVerifyLocationsError	Thrown if the call to SSL_CTX_load_verify_locations() in the underlying library fails.

void RWSecureSocketContext::setCertificate ( const RWX509Certificate & cert )

inline

Sets the certificate for the entity (client or server) being authenticated. In most cases, the server is the entity being authenticated, so the server calls this function. If client authentication is desired, the client should also call this function.

Exceptions

RWSecureSocketUseCertificateError Thrown if the certificate cannot be set.

Note: If the setCertificate() function is called before setPrivateKey(), the cryptographic library automatically compares the key and the certificate. If the key does not match the certificate, setPrivateKey() throws RWSecureSocketUsePrivateKeyError. This exception is not thrown if setPrivateKey() is called before setCertificate(), even if the key does not match the certificate. In any case, if the key does not match the certificate, checkPrivateKey() will return false.

void RWSecureSocketContext::setCertificateVerifyCallback ( RWVerifyCallback fun )

inline

Sets the certificate verification callback. See the Secure Communication Module User's Guide for more information.

void RWSecureSocketContext::setCertificateVerifyMode ( int mode )

inline

Sets the certificate verify mode. Options may be combined with the bitwise-OR operator. Allowable values for the mode parameter are shown in the following Table.

Value	Description
`SSL_VERIFY_NONE`	Ignores results of certificate verification (Not Recommended)
`SSL_VERIFY_PEER`	Verifies the other end of the connection
`SSL_VERIFY_CLIENT_ONCE`	Ensures that when attempting to perform session-id reuse, no client certificate will be re-requested if one has previously been sent to the server.
`SSL_VERIFY_FAIL_IF_NO_PEER_CERT`	Ensures that verification fails if the peer does not provide a certificate. (This option is most often used by servers requesting client verification)

void RWSecureSocketContext::setCipherList ( const RWCString & list )

inline

Sets the kind and order of ciphers used by the TLS/SSL protocol. The cipher list is passed as a string whose construction is beyond the scope of this manual. See the section "Cipher List Formatting Rules" in the RSA B-Safe SSL-C User's Guide and the documentation for the function SSL_CTX_set_cipher_list() in the RSA and OpenSSL documentation.

Exceptions

RWSSLContextUnableToSetCipherListError Thrown if the underlying library is unable to set the cipher list.

void RWSecureSocketContext::setClientCertificateCallback ( RWClientCertificateCallback fun )

inline

Sets the client certificate callback. This callback is invoked by the client when a server requests a certificate from the client. See the Secure Communication Module User's Guide for more information.

void RWSecureSocketContext::setIdentity	(	const RWX509Certificate &	cert,
		const RWPrivateKey &	key
	)

inline

Convenience function that should be used by the side of the SSL/TLS protocol being authenticated. Normally this function is called by the server. If client authentication is also desired, this function is also called by the client to establish its own identity. Calling setIdentity() is equivalent to calling setPrivateKey(pkey), setCertificate(cert), and checkPrivateKey().

Exceptions

RWCertificateKeyMismatchError Thrown if checkPrivateKey() returns false.

void RWSecureSocketContext::setOptions ( long op )

inline

Sets various options related to the SSL/TLS implementation. Any of the values below may be bitwise-ORed together and passed in to the function. The RWSecureSocketContext constructor calls setOptions(SSL_OP_ALL) to enable all known compatibility flags in the underlying SSL library, which improves compatibility with all browsers and SSL implementations. See the following table for a list of options.

Option	Description
`SSL_OP_ALL`	Enables all compatibility options. See the RSA B-Safe or OpenSSL documentation for more information about compatibility with other SSL/TLS implementations.
`SSL_OP_NO_TLSv1` `SSL_OP_NO_SSLv3` `SSL_OP_NO_SSLv2`	Specifies which protocols are used. These options only work when the context has been constructed with one of the "With Fallback" methods (the default).

The following examples show how to set options:

You want the protocol to fall back only as far as SSL version 3, and you want to enable all bug fixes:
RWSecureSocketContext context;

context.setOptions( SSL_OP_ALL | SSL_OP_NO_SSLv2 );
You want to use only TLS version 1, and you want to enable all bug fixes:
RWSecureSocketContext context;

context.setOptions(SSL_OP_ALL | SSL_OP_NO_SSLv2 |

SSL_OP_NO_SSLv3 );

Other options may be available. See the documentation of the function SSL_CTX_set_options() in the RSA or OpenSSL documentation.

void RWSecureSocketContext::setPrivateKey ( const RWPrivateKey & pkey )

inline

Sets the private key for the entity (client or server) being authenticated. In most cases, the server is the entity being authenticated, so the server calls this function. If client authentication is desired, the client also calls this function.

Exceptions

RWSecureSocketUsePrivateKeyError Thrown when the private key pkey could not be set on the context.

Note: If the setCertificate() function is called before setPrivateKey(), the cryptographic library automatically compares the key and the certificate. If the key does not match the certificate, setPrivateKey() throws RWSecureSocketUsePrivateKeyError. This exception is not thrown if setPrivateKey() is called before setCertificate(), even if the key does not match the certificate. In any case, if the key does not match the certificate, checkPrivateKey() returns FALSE.

void RWSecureSocketContext::setSessionId ( const RWCString & id )

inline

Sets the session id of the context.

Exceptions

RWSecureSocketInvalidSessionId Thrown when a session ID that exceeds the maximum allowable length is set.

void RWSecureSocketContext::setShutdownMode ( RWSSLShutdownMode mode )

inline

Sets the shutdown mode. When an SSL/TLS connection is about to be shut down and the shutdown mode is normal (the default), the side of the protocol initiating the shutdown sends a CloseVerify message to its peer and waits for the peer to respond with a CloseVerify message.

Some SSL/TLS libraries incorrectly implement the shutdown protocol. To enable interoperability with these libraries, set the shutdown mode to quiet. This mode instructs the libraries to ignore the CloseVerify portion of the protocol.

The shutdown mode set with this function applies to all sockets and portals created with this RWSecureSocketContext.

Note: Security issues related to this function are described in the Security Issues section of the Secure Communication Module User's Guide.

void RWSecureSocketContext::setVerify	(	int	mode,
		RWVerifyCallback	fun
	)

inline

Sets the verification mode and verification callback function simultaneously. We recommend that applications avoid this function and instead invoke setCertificateVerifyMode() and setCertificateVerifyCallback() separately. This function is provided as a convenience to current users of RSA B-Safe SSL-C and OpenSSL. See setCertificateVerifyMode() and setCertificateVerifyCallback() for more information.

Friends And Related Function Documentation

typedef int(* RWClientCertificateCallback) (SSL *conn, X509 **cert, EVP_PKEY **pkey)

Parameters

conn	The secure socket connection for which the certificate and private key are being requested.
cert	Output parameter used to return the certificate.
pkey	Output parameter used to return the private key.

Returns: 1 to send the certificate and private key to the server, otherwise 0.

typedef SSL_CTX* RWSecureSocketContextRep

typedef int(* RWVerifyCallback) (int pass, X509_STORE_CTX *ctxt)

Parameters

pass	`0` if the certificate failed internal verification procedures, otherwise it will be `1`.
ctxt	Represents the certificate data to be verified.

Returns: 1 if pass had the value 1 and the certificate passes the verification procedure. Otherwise, 0.

SourcePro® API Reference Guide

Public Member Functions

Related Functions

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation