SourcePro C++ 12.0
SourcePro® C++ API Reference Guide
SourcePro C++
Documentation Home
SourcePro C++ 12.0 |
SourcePro® C++ API Reference Guide |
SourcePro C++ Documentation Home |
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>
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.
| RWSecureSocketContext::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.
| 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. |
| RWSecureSocketContext::RWSecureSocketContext | ( | const RWSecureSocketContext & | second | ) | [inline] |
Copy constructor.
| RWSecureSocketContext::~RWSecureSocketContext | ( | void | ) | [inline] |
Destructor.
| 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.
| 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.
| 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) .
| 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.
| RWSecureSocketUseCertificateError | Thrown if the certificate cannot be set. |
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.
| 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().
| 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:
RWSecureSocketContext context; context.setOptions( SSL_OP_ALL | SSL_OP_NO_SSLv2 );
// 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 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.
| RWSecureSocketUsePrivateKeyError | Thrown when the private key pkey could not be set on the context. |
| 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.
| 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.
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.
| 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. |
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.
| pass | 0 if the certificate failed internal verification procedures, otherwise it will be 1. | |
| ctxt | Represents the certificate data to be verified. |
1 if pass had the value 1 and the certificate passes the verification procedure. Otherwise, 0. © 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.