RWSecureSocketContext
Module: Secure Communication Module Package: Secure Sockets
RWSecureSocketContextRWHandleBase
- Local Index
- Header File
- Description
- Enum
- Typedefs
- Public Constructor
- Destructor
- Public Operator
- Public Member Functions
- Protected Member Function
Local Index
Members
Header File
#include <rw/secsock/RWSecureSocketContext.h>
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.
Enum
enum RWSSLShutdownMode { RW_SSL_SHUTDOWN_NORMAL,
RW_SSL_SHUTDOWN_QUIET };
Determines whether SSL/TLS connections send and wait for or ignore the CloseVerify message when shutting down.
Typedefs
typedef SSL_CTX* RWSecureSocketContextRep;
extern "C" typedef int(*RWPasswordCallback)(char*, int, int);
extern "C" typedef int (*RWClientCertificateCallback)
(SSL*, X509**, EVP_PKEY **);
extern "C" typedef int (*RWVerifyCallback)(int,
X509_STORE_CTX*);
Public Constructor
RWSecureSocketContext(const RWSecureSocketContext& second);
Copy constructor.
RWSecureSocketContext(const RWSecureSocketMethod&
method = RWSecureSocketMethod::TLSv1WithFallback);
Constructs a secure socket context. The method parameter specifies which versions of SSL/TLS the application will support. The default parameter ensures that the application first attempts a TLS v1.0 handshake, falling back to SSL v3.0 and SSL v2.0 handshake protocols in that order. This default parameter should be sufficient for most needs. See RWSecureSocketMethod for more information.
Throws RWSecureSocketPackageNotInitalizedError if the Secure Sockets package has not been initialized. See RWSecureSocketPackageInit for more information. Throws RWSecureSocketUnderlyingAllocationError 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.
Destructor
~RWSecureSocketContext();
Destructor.
Public Operator
RWSecureSocketContext& operator=(RWSecureSocketContext& second);
Assignment operator.
Public Member Functions
bool checkPrivateKey() const;
Returns true if the previously specified private key matches the previously specified certificate, returns false otherwise.
RWClientCertificateCallback getClientCertificateCallback() const;
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.
RWVerifyCallback getCertificateVerifyCallback() const;
Gets the certificate verification callback previously set by setVerify() or setCertificateVerifyCallback().
int getCertificateVerifyMode() const;
Gets the certificate verify mode previously set by setVerify() or setCertificateVerifyMode(). See setCertificateVerifyMode() for more information.
RWSecureSocketContextRep getRep() const;
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, RWSecureSocketContextImp, so users should not attempt to delete it. RWSecureSocketContextImp deletes the memory when all handles referring to that body are destroyed.
RWSSLShutdownMode getShutdownMode() const;
Gets the current default shutdown mode for all sockets and portals created with this RWSecureSocketContext.
void loadVerifyLocations(const RWCString& file);
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. Throws RWSecureSocketInvalidFileError if the file does not exist. Throws RWSSLContextLoadVerifyLocationsError if the call to SSL_CTX_load_verify_locations() in the underlying library fails. The RWCString must be encoded as UTF-8.
void prepareToAuthenticate(const RWCString& trustedCertsFile );
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). Throws RWSecureSocketInvalidFileError if the file supplied does not exist or is otherwise invalid. Throws RWSSLContextLoadVerifyLocationsError if the call to SSL_CTX_load_verify_locations() in the underlying library fails. The RWCString must be encoded as UTF-8.
void setCertificate(const RWX509Certificate& cert);
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. Throws RWSecureSocketUseCertificateError 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 setCertificateVerifyCallback(RWVerifyCallback fun);
Sets the certificate verification callback. See the Secure Communication Module User's Guide for more information.
void setCertificateVerifyMode(int mode);
Sets the certificate verify mode. Options may be combined with the bitwise-OR operator. Allowable values for the mode parameter are shown inTable 3.
Table 3: SSL/TLS Certificate Verify Modes
| 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 setCipherList(const RWCString& list);
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. Throws RWSSLContextUnableToSetCipherListError if the underlying library is unable to set the cipher list.
void setClientCertificateCallback(RWClientCertificateCallback fun);
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
setIdentity(const RWX509Certificate& cert,
const RWPrivateKey& pkey);
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(). Throws RWCertificateKeyMismatchError if checkPrivateKey() returns false.
void setOptions(long op);
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 Table 4 for a list of options.
Table 4: SSL/TLS 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:
// Falls back to SSLv3 and SSLv2 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 setPrivateKey(const RWPrivateKey& pkey );
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. Throws RWSSLContextUsePrivateKeyError.
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 setShutdownMode(RWSSLShutdownMode mode);
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(int mode, RWVerifyCallback fun);
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 setCertficateVerifyCallback() for more information.
Protected Member Function
RWSecureSocketContextImp& body() const;
Returns a reference to the connected body. Redefined from RWHandleBase.
© Copyright Rogue Wave Software, Inc. All Rights Reserved.
Rogue Wave and SourcePro are registered trademarks of Rogue Wave Software, Inc. in the United States and other countries. All other trademarks are the property of their respective owners.
Contact Rogue Wave about documentation or support issues.