RWSecureSocketContext Class Reference

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 RWSecureSocketContext &second)
	RWSecureSocketContext (const RWSecureSocketMethod &method)
	RWSecureSocketContext (RWSecureSocketProtocolVersion minVersion, RWSecureSocketProtocolVersion maxVersion, RWSecureSocketSide side=RW_CLIENT_OR_SERVER)
	~RWSecureSocketContext (void)
bool	checkPrivateKey (void) const
RWVerifyCallback	getCertificateVerifyCallback (void) const
int	getCertificateVerifyMode (void) const
RWClientCertificateCallback	getClientCertificateCallback (void) const
RWSecureSocketContextRep	getRep (void) const
int	getSecurityLevel () 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 (unspecified_integer_type op)
void	setPrivateKey (const RWPrivateKey &pkey)
void	setSecurityLevel (int level)
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

Related Symbols
(Note that these are not member symbols.)
#define	RW_NO_OPENSSL_SECURITY_LEVEL
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 (const RWHandleBase &second)
	RWHandleBase (RWBodyBase *body)
	RWHandleBase (RWStaticCtor)
	RWHandleBase (void)
	~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() [1/4]

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() [2/4]

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() [3/4]

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.

Condition:

This constructor is available only if building with OpenSSL 1.0.1 and later.

RWSecureSocketContext() [4/4]

RWSecureSocketContext::RWSecureSocketContext ( const RWSecureSocketContext & second )

inline

Copy constructor.

~RWSecureSocketContext()

RWSecureSocketContext::~RWSecureSocketContext ( void )

inline

Destructor.

Member Function Documentation

checkPrivateKey()

bool RWSecureSocketContext::checkPrivateKey ( void ) const

inline

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

getCertificateVerifyCallback()

RWVerifyCallback RWSecureSocketContext::getCertificateVerifyCallback ( void ) const

inline

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

getCertificateVerifyMode()

int RWSecureSocketContext::getCertificateVerifyMode ( void ) const

inline

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

getClientCertificateCallback()

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.

getRep()

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.

getSecurityLevel()

int RWSecureSocketContext::getSecurityLevel

(

)

const

Gets the security level previously set by setSecurityLevel() or the library default value.

Exceptions

RWSecureSocketError

Thrown if the cryptographic library does not provide the required method.

Note

This function is available only if building with OpenSSL 1.1.0 and later.

getShutdownMode()

RWSSLShutdownMode RWSecureSocketContext::getShutdownMode ( void ) const

inline

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

loadVerifyLocations()

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.

operator=()

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

inline

Assignment operator.

prepareToAuthenticate()

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.

setCertificate()

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.

setCertificateVerifyCallback()

void RWSecureSocketContext::setCertificateVerifyCallback ( RWVerifyCallback fun )

inline

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

setCertificateVerifyMode()

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)

setCipherList()

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.

setClientCertificateCallback()

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.

setIdentity()

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.

setOptions()

void RWSecureSocketContext::setOptions ( unspecified_integer_type 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.

Note

unspecified_integer_type is a type compatible with the underlying OpenSSL SSL_CTX_set_options() function, and may vary based on the OpenSSL version.

setPrivateKey()

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.

setSecurityLevel()

void RWSecureSocketContext::setSecurityLevel

(

int

level

)

Sets the security level on the cryptographic library's representation of the context to level.

See the function SSL_CTX_set_security_level() in the OpenSSL documentation for details on the available values and their definitions.

Exceptions

RWSecureSocketError

Thrown if the cryptographic library does not provide the required method.

Condition:

This function is available only if building with OpenSSL 1.1.0 and later.

setSessionId()

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.

setShutdownMode()

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.

setVerify()

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 Symbol Documentation

RW_NO_OPENSSL_SECURITY_LEVEL

#define RW_NO_OPENSSL_SECURITY_LEVEL

related

RW_NO_OPENSSL_SECURITY_LEVEL is defined when the underlying OpenSSL library does not provide support for setting a security level. The functions RWSecureSocketContext::setSecurityLevel() and RWSecureSocketContext::getSecurityLevel() are not declared if this is the case.

RWClientCertificateCallback

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

related

A typedef for a callback function that is invoked when the server requests a client certificate. It is useful when a client must choose which certificate to send back to the server.

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.

RWSecureSocketContextRep

typedef SSL_CTX* RWSecureSocketContextRep

related

This is the internal secure socket context representation.

RWVerifyCallback

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

related

A typedef for a callback function that is invoked for every certificate in the certificate chain that is passed to the client during the SSL/TLS handshake.

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.