#include <Context.h>

Inheritance diagram for Poco::Net::Context:

Collaboration diagram for Poco::Net::Context:

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 &params)

	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 &params)

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.

Detailed Description

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:

TLS_AES_256_GCM_SHA384
TLS_CHACHA20_POLY1305_SHA256
TLS_AES_128_GCM_SHA256
TLS_AES_128_CCM_8_SHA256
TLS_AES_128_CCM_SHA256

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

Definition at line 38 of file Context.h.

Member Typedef Documentation

◆ InvalidCertificateHandlerPtr

using Poco::Net::Context::InvalidCertificateHandlerPtr = Poco::SharedPtr<InvalidCertificateHandler>

Definition at line 198 of file Context.h.

◆ Ptr

using Poco::Net::Context::Ptr = Poco::AutoPtr<Context>

Definition at line 64 of file Context.h.

Member Enumeration Documentation

◆ Protocols

enum Poco::Net::Context::Protocols

Enumerator
PROTO_SSLV2
PROTO_SSLV3
PROTO_TLSV1
PROTO_TLSV1_1
PROTO_TLSV1_2
PROTO_TLSV1_3

Definition at line 119 of file Context.h.

◆ Usage

enum Poco::Net::Context::Usage

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

Definition at line 66 of file Context.h.

◆ VerificationMode

enum Poco::Net::Context::VerificationMode

Enumerator
VERIFY_NONE
VERIFY_RELAXED	Server: The server will not send a client certificate request to the client, so the client will not send a certificate. Client: If not using an anonymous cipher (by default disabled), the server will send a certificate which will be checked, but the result of the check will be ignored.
VERIFY_STRICT	Server: The server sends a client certificate request to the client. The certificate returned (if any) is checked. If the verification process fails, the TLS/SSL handshake is immediately terminated with an alert message containing the reason for the verification failure. Client: The server certificate is verified, if one is provided. If the verification process fails, the TLS/SSL handshake is immediately terminated with an alert message containing the reason for the verification failure.
VERIFY_ONCE	Server: If the client did not return a certificate, the TLS/SSL handshake is immediately terminated with a handshake failure alert. Client: Same as VERIFY_RELAXED.

Definition at line 82 of file Context.h.

Constructor & Destructor Documentation

◆ Context() [1/3]

Poco::Net::Context::Context	(	Usage	usage,
		const Params &	params )

◆ Context() [2/3]

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.

usage specifies whether the context is used by a client or server.
params specifies the context parameters.

◆ Context() [3/3]

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.

usage specifies whether the context is used by a client or server.
privateKeyFile contains the path to the private key file used for encryption. Can be empty if no private key file is used.
certificateFile contains the path to the certificate file (in PEM format). If the private key and the certificate are stored in the same file, this can be empty if privateKeyFile is given.
caLocation contains the path to the file or directory containing the CA/root certificates. Can be empty if the OpenSSL builtin CA certificates are used (see loadDefaultCAs).
verificationMode specifies whether and how peer certificates are validated.
verificationDepth sets the upper limit for verification chain sizes. Verification will fail if a certificate chain larger than this is encountered.
loadDefaultCAs specifies whether the builtin CA certificates from OpenSSL are used.
cipherList specifies the supported ciphers in OpenSSL notation.

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.

◆ ~Context()

Poco::Net::Context::~Context ( )

Creates a Context.

usage specifies whether the context is used by a client or server.
caLocation contains the path to the file or directory containing the CA/root certificates. Can be empty if the OpenSSL builtin CA certificates are used (see loadDefaultCAs).
verificationMode specifies whether and how peer certificates are validated.
verificationDepth sets the upper limit for verification chain sizes. Verification will fail if a certificate chain larger than this is encountered.
loadDefaultCAs specifies whether the builtin CA certificates from OpenSSL are used.
cipherList specifies the supported ciphers in OpenSSL notation.

Note that a private key and/or certificate must be specified with usePrivateKey()/useCertificate() before the Context can be used.

Member Function Documentation

◆ addCertificateAuthority()

void Poco::Net::Context::addCertificateAuthority ( const Poco::Crypto::X509Certificate & certificate )

Adds a certificate for certificate chain validation.

◆ addChainCertificate()

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().

◆ createSSLContext()

void Poco::Net::Context::createSSLContext ( )

private

Initializes the Context with Elliptic-Curve Diffie-Hellman key exchange curve parameters.

◆ disableProtocols()

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.

◆ disableStatelessSessionResumption()

void Poco::Net::Context::disableStatelessSessionResumption ( )

Returns true iff automatic extended certificate verification is enabled.

◆ enableExtendedCertificateVerification()

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.

◆ enableSessionCache() [1/2]

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.

◆ enableSessionCache() [2/2]

void Poco::Net::Context::enableSessionCache ( bool flag = true )

Returns the verification mode.

◆ extendedCertificateVerificationEnabled()

bool Poco::Net::Context::extendedCertificateVerificationEnabled ( ) const

inline

Enable or disable the automatic post-connection extended certificate verification.

See X509Certificate::verify() for more information.

Definition at line 478 of file Context.h.

◆ flushSessionCache()

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.

◆ getInvalidCertificateHandler()

Context::InvalidCertificateHandlerPtr Poco::Net::Context::getInvalidCertificateHandler ( ) const

inline

Sets a Context-specific InvalidCertificateHandler.

If specified, this InvalidCertificateHandler will be used instead of the one globally set in the SSLManager.

Definition at line 490 of file Context.h.

◆ getSessionCacheSize()

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.

◆ getSessionTimeout()

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.

◆ init()

void Poco::Net::Context::init ( const Params & params )

private

Returns the InvalidCertificateHandler set for this Context, or a null pointer if none has been set.

◆ initDH()

void Poco::Net::Context::initDH	(	bool	use2048Bits,
		const std::string &	dhFile )

private

Initializes the Context with the given parameters.

◆ initECDH()

void Poco::Net::Context::initECDH ( const std::string & curve )

private

Initializes the Context with Diffie-Hellman parameters.

◆ isForServerUse()

bool Poco::Net::Context::isForServerUse ( ) const

inline

Returns whether the context is for use by a client or by a server and whether TLSv1 is required.

Definition at line 455 of file Context.h.

◆ ocspStaplingResponseVerificationEnabled()

bool Poco::Net::Context::ocspStaplingResponseVerificationEnabled ( ) const

inline

When choosing a cipher, use the server's preferences instead of the client preferences. When not called, the SSL server will always follow the clients preferences. When called, the SSL/TLS server will choose following its own preferences.

Definition at line 484 of file Context.h.

◆ preferServerCiphers()

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);

◆ requireMinimumProtocol()

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);

◆ sessionCacheEnabled()

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.

◆ setInvalidCertificateHandler()

void Poco::Net::Context::setInvalidCertificateHandler ( InvalidCertificateHandlerPtr pInvalidCertificageHandler )

Returns true if automatic OCSP response reception and verification is enabled for client connections

◆ setSessionCacheSize()

void Poco::Net::Context::setSessionCacheSize ( std::size_t size )

Returns true iff the session cache is enabled.

◆ setSessionTimeout()

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.

◆ sslContext()

SSL_CTX * Poco::Net::Context::sslContext ( ) const

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.

Definition at line 472 of file Context.h.

◆ usage()

Context::Usage Poco::Net::Context::usage ( ) const

inline

Returns the underlying OpenSSL SSL Context object.

Definition at line 449 of file Context.h.

◆ useCertificate()

void Poco::Net::Context::useCertificate ( const Poco::Crypto::X509Certificate & certificate )

Destroys the Context.

◆ usePrivateKey() [1/2]

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.

◆ usePrivateKey() [2/2]

void Poco::Net::Context::usePrivateKey ( const Poco::Crypto::RSAKey & key )

Add one trusted certification authority to be used by the Context.

◆ verificationMode()

Context::VerificationMode Poco::Net::Context::verificationMode ( ) const

inline

Returns true iff the context is for use by a server.

Definition at line 466 of file Context.h.

Member Data Documentation

◆ _extendedCertificateVerification

bool Poco::Net::Context::_extendedCertificateVerification

private

Definition at line 440 of file Context.h.

◆ _mode

VerificationMode Poco::Net::Context::_mode

private

Definition at line 438 of file Context.h.

◆ _ocspStaplingResponseVerification

bool Poco::Net::Context::_ocspStaplingResponseVerification

private

Definition at line 441 of file Context.h.

◆ _pInvalidCertificateHandler

InvalidCertificateHandlerPtr Poco::Net::Context::_pInvalidCertificateHandler

private

Definition at line 442 of file Context.h.

◆ _pSSLContext

SSL_CTX* Poco::Net::Context::_pSSLContext

private

Definition at line 439 of file Context.h.

◆ _usage

Usage Poco::Net::Context::_usage

private

Create a SSL_CTX object according to Context configuration.

Definition at line 437 of file Context.h.

The documentation for this class was generated from the following file:

C:/Users/lachl/Downloads/ArkServerAPI_NEW/ASE/AseApi-main/include/Poco/Poco/Net/Context.h

Classes

Public Types

Public Member Functions

Private Member Functions

Private Attributes

Additional Inherited Members

Detailed Description

Member Typedef Documentation

◆ InvalidCertificateHandlerPtr

◆ Ptr

Member Enumeration Documentation

◆ Protocols

◆ Usage

◆ VerificationMode

Constructor & Destructor Documentation

◆ Context() [1/3]

◆ Context() [2/3]

◆ Context() [3/3]

◆ ~Context()

Member Function Documentation

◆ addCertificateAuthority()

◆ addChainCertificate()

◆ createSSLContext()

◆ disableProtocols()

◆ disableStatelessSessionResumption()

◆ enableExtendedCertificateVerification()

◆ enableSessionCache() [1/2]

◆ enableSessionCache() [2/2]

◆ extendedCertificateVerificationEnabled()

◆ flushSessionCache()

◆ getInvalidCertificateHandler()

◆ getSessionCacheSize()

◆ getSessionTimeout()

◆ init()

◆ initDH()

◆ initECDH()

◆ isForServerUse()

◆ ocspStaplingResponseVerificationEnabled()

◆ preferServerCiphers()

◆ requireMinimumProtocol()

◆ sessionCacheEnabled()

◆ setInvalidCertificateHandler()

◆ setSessionCacheSize()

◆ setSessionTimeout()

◆ sslContext()

◆ usage()

◆ useCertificate()

◆ usePrivateKey() [1/2]

◆ usePrivateKey() [2/2]

◆ verificationMode()

Member Data Documentation

◆ _extendedCertificateVerification

◆ _mode

◆ _ocspStaplingResponseVerification

◆ _pInvalidCertificateHandler

◆ _pSSLContext

◆ _usage