Poco::Net

class Context

Library: NetSSL_OpenSSL
Package: SSLCore
Header: Poco/Net/Context.h

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

Inheritance

Direct Base Classes: Poco::RefCountedObject

All Base Classes: Poco::RefCountedObject

Member Summary

Member Functions: addCertificateAuthority, addChainCertificate, disableProtocols, disableStatelessSessionResumption, enableExtendedCertificateVerification, enableSessionCache, extendedCertificateVerificationEnabled, flushSessionCache, getInvalidCertificateHandler, getSessionCacheSize, getSessionTimeout, ignoreUnexpectedEof, isForServerUse, ocspStaplingResponseVerificationEnabled, preferServerCiphers, requireMinimumProtocol, sessionCacheEnabled, setInvalidCertificateHandler, setQuietShutdown, setSecurityLevel, setSessionCacheSize, setSessionTimeout, sslContext, usage, useCertificate, usePrivateKey, verificationMode

Inherited Functions: duplicate, referenceCount, release

Nested Classes

struct Params

 more...

Types Aliases

InvalidCertificateHandlerPtr

using InvalidCertificateHandlerPtr = Poco::SharedPtr < InvalidCertificateHandler >;

Ptr

using Ptr = Poco::AutoPtr < Context >;

Enumerations

Protocols

PROTO_SSLV2 = 0x01

PROTO_SSLV3 = 0x02

PROTO_TLSV1 = 0x04

PROTO_TLSV1_1 = 0x08

PROTO_TLSV1_2 = 0x10

PROTO_TLSV1_3 = 0x20

SecurityLevel

SECURITY_LEVEL_NONE = 0

SECURITY_LEVEL_80_BITS = 1

SECURITY_LEVEL_112_BITS = 2

SECURITY_LEVEL_128_BITS = 3

SECURITY_LEVEL_192_BITS = 4

SECURITY_LEVEL_256_BITS = 5

Usage

TLS_CLIENT_USE

Context is used by a client for TLSv1 or higher. Use requireMinimumProtocol() or disableProtocols() to disable undesired older versions.

TLS_SERVER_USE

Context is used by a client for TLSv1 or higher. Use requireMinimumProtocol() or disableProtocols() to disable undesired older versions.

CLIENT_USE

DEPRECATED. Context is used by a client.

SERVER_USE

DEPRECATED. Context is used by a server.

TLSV1_CLIENT_USE

DEPRECATED. Context is used by a client requiring TLSv1.

TLSV1_SERVER_USE

DEPRECATED. Context is used by a server requiring TLSv1.

TLSV1_1_CLIENT_USE

DEPRECATED. Context is used by a client requiring TLSv1.1 (OpenSSL 1.0.0 or newer).

TLSV1_1_SERVER_USE

DEPRECATED. Context is used by a server requiring TLSv1.1 (OpenSSL 1.0.0 or newer).

TLSV1_2_CLIENT_USE

DEPRECATED. Context is used by a client requiring TLSv1.2 (OpenSSL 1.0.1 or newer).

TLSV1_2_SERVER_USE

DEPRECATED. Context is used by a server requiring TLSv1.2 (OpenSSL 1.0.1 or newer).

TLSV1_3_CLIENT_USE

DEPRECATED. Context is used by a client requiring TLSv1.3 (OpenSSL 1.1.1 or newer).

TLSV1_3_SERVER_USE

DEPRECATED. Context is used by a server requiring TLSv1.3 (OpenSSL 1.1.1 or newer).

VerificationMode

VERIFY_NONE = 0x00

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_RELAXED = 0x01

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_STRICT = 0x01 | 0x02

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.

VERIFY_ONCE = 0x01 | 0x04

Server: Only request a client certificate on the initial TLS/SSL handshake. Do not ask for a client certificate again in case of a renegotiation.

Client: Same as VERIFY_RELAXED.

Constructors

Context

Context(
    Usage usage,
    const Params & params
);

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

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

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.

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

Destructor

~Context virtual

~Context();

Destroys the Context.

Member Functions

addCertificateAuthority

void addCertificateAuthority(
    const Poco::Crypto::X509Certificate & certificate
);

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

addChainCertificate

void addChainCertificate(
    const Poco::Crypto::X509Certificate & certificate
);

Adds a certificate for certificate chain validation.

disableProtocols

void disableProtocols(
    int protocols
);

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

disableStatelessSessionResumption

void disableStatelessSessionResumption();

Newer versions of OpenSSL support RFC 4507 tickets for stateless session resumption.

The feature can be disabled by calling this method.

enableExtendedCertificateVerification

void enableExtendedCertificateVerification(
    bool flag = true
);

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

See X509Certificate::verify() for more information.

enableSessionCache

void enableSessionCache(
    bool flag = true
);

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

void enableSessionCache(
    bool flag,
    const std::string & sessionIdContext
);

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.

extendedCertificateVerificationEnabled inline

bool extendedCertificateVerificationEnabled() const;

Returns true if and only if automatic extended certificate verification is enabled.

flushSessionCache

void flushSessionCache();

Flushes the SSL session cache on the server.

This method may only be called on SERVER_USE Context objects.

getInvalidCertificateHandler inline

InvalidCertificateHandlerPtr getInvalidCertificateHandler() const;

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

getSessionCacheSize

std::size_t getSessionCacheSize() const;

Returns the current maximum size of the server session cache.

This method may only be called on SERVER_USE Context objects.

getSessionTimeout

long getSessionTimeout() const;

Returns the timeout (in seconds) of cached sessions on the server.

This method may only be called on SERVER_USE Context objects.

ignoreUnexpectedEof

void ignoreUnexpectedEof(
    bool flag = true
);

Enable or disable SSL/TLS SSL_OP_IGNORE_UNEXPECTED_EOF

Some TLS implementations do not send the mandatory close_notify alert on shutdown. If the application tries to wait for the close_notify alert but the peer closes the connection without sending it, an error is generated. When this option is enabled the peer does not need to send the close_notify alert and a closed connection will be treated as if the close_notify alert was received.

isForServerUse inline

bool isForServerUse() const;

Returns true if and only if the context is for use by a server.

ocspStaplingResponseVerificationEnabled inline

bool ocspStaplingResponseVerificationEnabled() const;

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

preferServerCiphers

void preferServerCiphers();

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.

requireMinimumProtocol

void requireMinimumProtocol(
    Protocols protocol
);

Disables all protocol version lower than the given one. To require at least TLS 1.2 or later:

context.requireMinimumProtocol(PROTO_TLSV1_2);

sessionCacheEnabled

bool sessionCacheEnabled() const;

Returns true if and only if the session cache is enabled.

setInvalidCertificateHandler

void setInvalidCertificateHandler(
    InvalidCertificateHandlerPtr pInvalidCertificageHandler
);

Sets a Context-specific InvalidCertificateHandler.

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

setQuietShutdown

void setQuietShutdown(
    bool flag = true
);

Normally, when an SSL connection is finished, the parties must send out close_notify alert messages for a clean shutdown. When setting the "quiet shutdown" flag to true, the SecureSocketImpl::shutdown() will set the SSL shutdown flags, but no close_notify alert is sent to the peer. This behaviour violates the TLS standard. The default is a normal shutdown behaviour as described by the TLS standard.

setSecurityLevel

void setSecurityLevel(
    SecurityLevel level
);

Sets the security level.

setSessionCacheSize

void setSessionCacheSize(
    std::size_t size
);

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.

setSessionTimeout

void setSessionTimeout(
    long seconds
);

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.

sslContext inline

SSL_CTX * sslContext() const;

Returns the underlying OpenSSL SSL Context object.

usage inline

Usage usage() const;

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

useCertificate

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

usePrivateKey

void usePrivateKey(
    const Poco::Crypto::RSAKey & key
);

Deprecated. This function is deprecated and should no longer be used.

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

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

verificationMode inline

Context::VerificationMode verificationMode() const;

Returns the verification mode.