SourcePro® API Reference Guide

 
List of all members | Public Member Functions | Related Functions
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:
RWHandleBase

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
 
int getSecurityLevel () const
 
RWSSLShutdownMode getShutdownMode (void) const
 
void loadVerifyLocations (const RWCString &file)
 
RWSecureSocketContextoperator= (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
 
bool operator== (const RWHandleBase &second) const
 

Related Functions

(Note that these are not member functions.)

#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 (void)
 
 RWHandleBase (RWStaticCtor)
 
 RWHandleBase (RWBodyBase *body)
 
 RWHandleBase (const RWHandleBase &second)
 
 ~RWHandleBase (void)
 
RWBodyBasebody (void) const
 
RWHandleBaseoperator= (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
RWSecureSocketPackageNotInitializedErrorThrown if the Secure Sockets package has not been initialized. See RWSecureSocketPackageInit for more information.
RWSecureSocketUnderlyingAllocationErrorThrown 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
RWSecureSocketPackageNotInitializedErrorThrown if the Secure Sockets package has not been initialized. See RWSecureSocketPackageInit for more information.
RWSecureSocketUnderlyingAllocationErrorThrown if the cryptographic library is unsuccessful in allocating memory.
RWSecureSocketInvalidMethodErrorThrown 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
RWSecureSocketPackageNotInitializedErrorThrown if the Secure Sockets package has not been initialized. See RWSecureSocketPackageInit for more information.
RWSecureSocketUnderlyingAllocationErrorThrown if the cryptographic library is unsuccessful in allocating memory.
RWSecureSocketVersionErrorThrown 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::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.
int RWSecureSocketContext::getSecurityLevel ( ) const

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

Exceptions
RWSecureSocketErrorThrown 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.
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
RWSecureSocketInvalidFileErrorThrown if the file does not exist.
RWSSLContextLoadVerifyLocationsErrorThrown 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
RWSecureSocketInvalidFileErrorThrown if the file supplied does not exist or is otherwise invalid. The parameter trustedCertFile must be encoded as UTF-8.
RWSSLContextLoadVerifyLocationsErrorThrown 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
RWSecureSocketUseCertificateErrorThrown 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
RWSSLContextUnableToSetCipherListErrorThrown 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
RWCertificateKeyMismatchErrorThrown if checkPrivateKey() returns false.
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:
    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:
    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.
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
RWSecureSocketUsePrivateKeyErrorThrown 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::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
RWSecureSocketErrorThrown 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.
void RWSecureSocketContext::setSessionId ( const RWCString id)
inline

Sets the session id of the context.

Exceptions
RWSecureSocketInvalidSessionIdThrown 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

#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.

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
connThe secure socket connection for which the certificate and private key are being requested.
certOutput parameter used to return the certificate.
pkeyOutput 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
related

This is the internal secure socket context representation.

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
pass0 if the certificate failed internal verification procedures, otherwise it will be 1.
ctxtRepresents the certificate data to be verified.
Returns
1 if pass had the value 1 and the certificate passes the verification procedure. Otherwise, 0.

Copyright © 2023 Rogue Wave Software, Inc., a Perforce company. All Rights Reserved.