Class Poco::Net::Context
Author: Applied Informatics Software Engineering GmbH and Contributors
Date: 2009-11-24

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

## Inheritance

Direct Base Classes: Poco::RefCountedObject

All Base Classes: Poco::RefCountedObject

## Member Summary

Member Functions: enableSessionCache, sessionCacheEnabled, sslContext, usage, verificationMode

Inherited Functions: duplicate, referenceCount, release

## Types

### Ptr

typedef Poco::AutoPtr < Context > Ptr;

## Enumerations

### Usage

CLIENT_USE

Context is used by a client.

SERVER_USE

Context is used by a server.

### 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 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 wheter the builtin CA certificates from OpenSSL are used.
- cipherList specifies the supported ciphers in OpenSSL notation.

## Destructor

### ~Context

~Context();

Destroys the Context.

## Member Functions

### enableSessionCache

void enableSessionCache(
bool flag = true
);

Enable or disable the SSL/TLS session cache for a server.

The default is a disabled session cache.

### sessionCacheEnabled

bool sessionCacheEnabled() const;

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

### sslContext

SSL_CTX * sslContext() const;

Returns the underlying OpenSSL SSL Context object.

### usage

Usage usage() const;

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

### verificationMode

Context::VerificationMode verificationMode() const;

Returns the verification mode.