Ark Server API (ASE) - Wiki
|
#include <Context.h>
Classes | |
struct | Params |
Public Types | |
enum | Usage { TLS_CLIENT_USE , TLS_SERVER_USE , CLIENT_USE , SERVER_USE , TLSV1_CLIENT_USE , TLSV1_SERVER_USE , TLSV1_1_CLIENT_USE , TLSV1_1_SERVER_USE , TLSV1_2_CLIENT_USE , TLSV1_2_SERVER_USE , TLSV1_3_CLIENT_USE , TLSV1_3_SERVER_USE } |
enum | VerificationMode { VERIFY_NONE = SSL_VERIFY_NONE , VERIFY_RELAXED = SSL_VERIFY_PEER , VERIFY_STRICT = SSL_VERIFY_PEER | SSL_VERIFY_FAIL_IF_NO_PEER_CERT , VERIFY_ONCE = SSL_VERIFY_PEER | SSL_VERIFY_CLIENT_ONCE } |
enum | Protocols { PROTO_SSLV2 = 0x01 , PROTO_SSLV3 = 0x02 , PROTO_TLSV1 = 0x04 , PROTO_TLSV1_1 = 0x08 , PROTO_TLSV1_2 = 0x10 , PROTO_TLSV1_3 = 0x20 } |
using | Ptr = Poco::AutoPtr<Context> |
using | InvalidCertificateHandlerPtr = Poco::SharedPtr<InvalidCertificateHandler> |
Public Member Functions | |
Context (Usage usage, const Params ¶ms) | |
Context (Usage usage, const std::string &privateKeyFile, const std::string &certificateFile, const std::string &caLocation, VerificationMode verificationMode=VERIFY_RELAXED, int verificationDepth=9, bool loadDefaultCAs=false, const std::string &cipherList="ALL:!ADH:!LOW:!EXP:!MD5:@STRENGTH") | |
Context (Usage usage, const std::string &caLocation, VerificationMode verificationMode=VERIFY_RELAXED, int verificationDepth=9, bool loadDefaultCAs=false, const std::string &cipherList="ALL:!ADH:!LOW:!EXP:!MD5:@STRENGTH") | |
~Context () | |
void | useCertificate (const Poco::Crypto::X509Certificate &certificate) |
Destroys the Context. | |
void | addChainCertificate (const Poco::Crypto::X509Certificate &certificate) |
void | addCertificateAuthority (const Poco::Crypto::X509Certificate &certificate) |
Adds a certificate for certificate chain validation. | |
void | usePrivateKey (const Poco::Crypto::RSAKey &key) |
Add one trusted certification authority to be used by the Context. | |
void | usePrivateKey (const Poco::Crypto::EVPPKey &pkey) |
SSL_CTX * | sslContext () const |
Usage | usage () const |
Returns the underlying OpenSSL SSL Context object. | |
bool | isForServerUse () const |
Context::VerificationMode | verificationMode () const |
Returns true iff the context is for use by a server. | |
void | enableSessionCache (bool flag=true) |
Returns the verification mode. | |
void | enableSessionCache (bool flag, const std::string &sessionIdContext) |
bool | sessionCacheEnabled () const |
void | setSessionCacheSize (std::size_t size) |
Returns true iff the session cache is enabled. | |
std::size_t | getSessionCacheSize () const |
void | setSessionTimeout (long seconds) |
long | getSessionTimeout () const |
void | flushSessionCache () |
void | enableExtendedCertificateVerification (bool flag=true) |
bool | extendedCertificateVerificationEnabled () const |
void | disableStatelessSessionResumption () |
void | disableProtocols (int protocols) |
void | requireMinimumProtocol (Protocols protocol) |
void | preferServerCiphers () |
bool | ocspStaplingResponseVerificationEnabled () const |
void | setInvalidCertificateHandler (InvalidCertificateHandlerPtr pInvalidCertificageHandler) |
InvalidCertificateHandlerPtr | getInvalidCertificateHandler () const |
Public Member Functions inherited from Poco::RefCountedObject | |
RefCountedObject () | |
void | duplicate () const |
void | release () const noexcept |
Increments the object's reference count. | |
int | referenceCount () const |
Private Member Functions | |
void | init (const Params ¶ms) |
void | initDH (bool use2048Bits, const std::string &dhFile) |
Initializes the Context with the given parameters. | |
void | initECDH (const std::string &curve) |
Initializes the Context with Diffie-Hellman parameters. | |
void | createSSLContext () |
Private Attributes | |
Usage | _usage |
Create a SSL_CTX object according to Context configuration. | |
VerificationMode | _mode |
SSL_CTX * | _pSSLContext |
bool | _extendedCertificateVerification |
bool | _ocspStaplingResponseVerification |
InvalidCertificateHandlerPtr | _pInvalidCertificateHandler |
Additional Inherited Members | |
Protected Member Functions inherited from Poco::RefCountedObject | |
virtual | ~RefCountedObject () |
Returns the reference count. | |
This class encapsulates context information for an SSL server or client, such as the certificate verification mode and the location of certificates and private key files, as well as the list of supported ciphers.
The Context class is also used to control SSL session caching on the server and client side.
A Note Regarding TLSv1.3 Support:
TLSv1.3 support requires at least OpenSSL version 1.1.1. Make sure that the TLSv1.3 cipher suites are enabled:
The first three of the above cipher suites should be enabled by default in OpenSSL if you do not provide an explicit cipher configuration (cipherList).
using Poco::Net::Context::Ptr = Poco::AutoPtr<Context> |
Enumerator | |
---|---|
TLS_CLIENT_USE | |
TLS_SERVER_USE | Context is used by a client for TLSv1 or higher. Use requireMinimumProtocol() or disableProtocols() to disable undesired older versions. |
CLIENT_USE | Context is used by a client for TLSv1 or higher. Use requireMinimumProtocol() or disableProtocols() to disable undesired older versions. |
SERVER_USE | DEPRECATED. Context is used by a client. |
TLSV1_CLIENT_USE | DEPRECATED. Context is used by a server. |
TLSV1_SERVER_USE | DEPRECATED. Context is used by a client requiring TLSv1. |
TLSV1_1_CLIENT_USE | DEPRECATED. Context is used by a server requiring TLSv1. |
TLSV1_1_SERVER_USE | DEPRECATED. Context is used by a client requiring TLSv1.1 (OpenSSL 1.0.0 or newer). |
TLSV1_2_CLIENT_USE | DEPRECATED. Context is used by a server requiring TLSv1.1 (OpenSSL 1.0.0 or newer). |
TLSV1_2_SERVER_USE | DEPRECATED. Context is used by a client requiring TLSv1.2 (OpenSSL 1.0.1 or newer). |
TLSV1_3_CLIENT_USE | DEPRECATED. Context is used by a server requiring TLSv1.2 (OpenSSL 1.0.1 or newer). |
TLSV1_3_SERVER_USE | DEPRECATED. Context is used by a client requiring TLSv1.3 (OpenSSL 1.1.1 or newer). DEPRECATED. Context is used by a server requiring TLSv1.3 (OpenSSL 1.1.1 or newer). |
Poco::Net::Context::Context | ( | Usage | usage, |
const std::string & | privateKeyFile, | ||
const std::string & | certificateFile, | ||
const std::string & | caLocation, | ||
VerificationMode | verificationMode = VERIFY_RELAXED, | ||
int | verificationDepth = 9, | ||
bool | loadDefaultCAs = false, | ||
const std::string & | cipherList = "ALL:!ADH:!LOW:!EXP:!MD5:@STRENGTH" ) |
Creates a Context using the given parameters.
Poco::Net::Context::Context | ( | Usage | usage, |
const std::string & | caLocation, | ||
VerificationMode | verificationMode = VERIFY_RELAXED, | ||
int | verificationDepth = 9, | ||
bool | loadDefaultCAs = false, | ||
const std::string & | cipherList = "ALL:!ADH:!LOW:!EXP:!MD5:@STRENGTH" ) |
Creates a Context.
Note: If the private key is protected by a passphrase, a PrivateKeyPassphraseHandler must have been setup with the SSLManager, or the SSLManager's PrivateKeyPassphraseRequired event must be handled.
Poco::Net::Context::~Context | ( | ) |
Creates a Context.
Note that a private key and/or certificate must be specified with usePrivateKey()/useCertificate() before the Context can be used.
void Poco::Net::Context::addCertificateAuthority | ( | const Poco::Crypto::X509Certificate & | certificate | ) |
Adds a certificate for certificate chain validation.
void Poco::Net::Context::addChainCertificate | ( | const Poco::Crypto::X509Certificate & | certificate | ) |
Sets the certificate to be used by the Context.
To set-up a complete certificate chain, it might be necessary to call addChainCertificate() to specify additional certificates.
Note that useCertificate() must always be called before usePrivateKey().
|
private |
Initializes the Context with Elliptic-Curve Diffie-Hellman key exchange curve parameters.
void Poco::Net::Context::disableProtocols | ( | int | protocols | ) |
Newer versions of OpenSSL support RFC 4507 tickets for stateless session resumption.
The feature can be disabled by calling this method.
void Poco::Net::Context::disableStatelessSessionResumption | ( | ) |
Returns true iff automatic extended certificate verification is enabled.
void Poco::Net::Context::enableExtendedCertificateVerification | ( | bool | flag = true | ) |
Flushes the SSL session cache on the server.
This method may only be called on SERVER_USE Context objects.
void Poco::Net::Context::enableSessionCache | ( | bool | flag, |
const std::string & | sessionIdContext ) |
Enable or disable SSL/TLS session caching. For session caching to work, it must be enabled on the server, as well as on the client side.
The default is disabled session caching.
To enable session caching on the server side, use the two-argument version of this method to specify a session ID context.
void Poco::Net::Context::enableSessionCache | ( | bool | flag = true | ) |
Returns the verification mode.
|
inline |
Enable or disable the automatic post-connection extended certificate verification.
See X509Certificate::verify() for more information.
void Poco::Net::Context::flushSessionCache | ( | ) |
Returns the timeout (in seconds) of cached sessions on the server.
This method may only be called on SERVER_USE Context objects.
|
inline |
Sets a Context-specific InvalidCertificateHandler.
If specified, this InvalidCertificateHandler will be used instead of the one globally set in the SSLManager.
std::size_t Poco::Net::Context::getSessionCacheSize | ( | ) | const |
Sets the maximum size of the server session cache, in number of sessions. The default size (according to OpenSSL documentation) is 1024*20, which may be too large for many applications, especially on embedded platforms with limited memory.
Specifying a size of 0 will set an unlimited cache size.
This method may only be called on SERVER_USE Context objects.
long Poco::Net::Context::getSessionTimeout | ( | ) | const |
Sets the timeout (in seconds) of cached sessions on the server. A cached session will be removed from the cache if it has not been used for the given number of seconds.
This method may only be called on SERVER_USE Context objects.
|
private |
Returns the InvalidCertificateHandler set for this Context, or a null pointer if none has been set.
|
private |
Initializes the Context with the given parameters.
|
private |
Initializes the Context with Diffie-Hellman parameters.
|
inline |
|
inline |
void Poco::Net::Context::preferServerCiphers | ( | ) |
Disables all protocol version lower than the given one. To require at least TLS 1.2 or later:
context.requireMinimumProtocol(PROTO_TLSV1_2);
void Poco::Net::Context::requireMinimumProtocol | ( | Protocols | protocol | ) |
Disables the given protocols.
The protocols to be disabled are specified by OR-ing values from the Protocols enumeration, e.g.:
context.disableProtocols(PROTO_SSLV2 | PROTO_SSLV3);
bool Poco::Net::Context::sessionCacheEnabled | ( | ) | const |
Enables or disables SSL/TLS session caching on the server. For session caching to work, it must be enabled on the server, as well as on the client side.
SessionIdContext contains the application's unique session ID context, which becomes part of each session identifier generated by the server within this context. SessionIdContext can be an arbitrary sequence of bytes with a maximum length of SSL_MAX_SSL_SESSION_ID_LENGTH.
A non-empty sessionIdContext should be specified even if session caching is disabled to avoid problems with clients requesting to reuse a session (e.g. Firefox 3.6).
This method may only be called on SERVER_USE Context objects.
void Poco::Net::Context::setInvalidCertificateHandler | ( | InvalidCertificateHandlerPtr | pInvalidCertificageHandler | ) |
Returns true if automatic OCSP response reception and verification is enabled for client connections
void Poco::Net::Context::setSessionCacheSize | ( | std::size_t | size | ) |
Returns true iff the session cache is enabled.
void Poco::Net::Context::setSessionTimeout | ( | long | seconds | ) |
Returns the current maximum size of the server session cache.
This method may only be called on SERVER_USE Context objects.
|
inline |
Sets the private key to be used by the Context.
Note that useCertificate() must always be called before usePrivateKey().
Note: If the private key is protected by a passphrase, a PrivateKeyPassphraseHandler must have been setup with the SSLManager, or the SSLManager's PrivateKeyPassphraseRequired event must be handled.
|
inline |
void Poco::Net::Context::useCertificate | ( | const Poco::Crypto::X509Certificate & | certificate | ) |
Destroys the Context.
void Poco::Net::Context::usePrivateKey | ( | const Poco::Crypto::EVPPKey & | pkey | ) |
Sets the private key to be used by the Context.
Note that useCertificate() must always be called before usePrivateKey().
Note: If the private key is protected by a passphrase, a PrivateKeyPassphraseHandler must have been setup with the SSLManager, or the SSLManager's PrivateKeyPassphraseRequired event must be handled.
void Poco::Net::Context::usePrivateKey | ( | const Poco::Crypto::RSAKey & | key | ) |
Add one trusted certification authority to be used by the Context.
|
inline |
|
private |
|
private |
|
private |
|
private |
|
private |