# SSLContext
# SSLContext
```cpp
#include
class SSLContext
```
[Defined in src/net/include/icy/net/sslcontext.h:44](https://github.com/auscaster/icey/blob/main/src/net/include/icy/net/sslcontext.h#L44)
OpenSSL SSL_CTX wrapper for client and server TLS configuration.
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.
## Public Methods
| Return | Name | Description |
|--------|------|-------------|
| | [`SSLContext`](#sslcontext-1) | Creates a Context. |
| | [`SSLContext`](#sslcontext-2) | Creates a Context. |
| | [`~SSLContext`](#sslcontext-3) `noexcept` | Destroys the Context. |
| `void` | [`useCertificate`](#usecertificate) | Sets the certificate to be used by the Context. |
| `void` | [`addChainCertificate`](#addchaincertificate) | Adds a certificate for certificate chain validation. |
| `void` | [`addVerificationCertificate`](#addverificationcertificate) | Sets the private key to be used by the Context. |
| `SSL_CTX *` | [`sslContext`](#sslcontext-4) `const` `inline` | Returns the underlying OpenSSL SSL Context object. |
| [`Usage`](#usage-1) | [`usage`](#usage) `const` `inline` | Returns whether the context is for use by a client or by a server and whether TLSv1 is required. |
| `bool` | [`isForServerUse`](#isforserveruse) `const` `inline` | Returns true if the context is for use by a server. |
| [`SSLContext::VerificationMode`](#verificationmode-1) | [`verificationMode`](#verificationmode) `const` `inline` | Returns the verification mode. |
| `void` | [`enableSessionCache`](#enablesessioncache) | 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. |
| `void` | [`enableSessionCache`](#enablesessioncache-1) | 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. |
| `bool` | [`sessionCacheEnabled`](#sessioncacheenabled) `const` | Returns true if the session cache is enabled. |
| `void` | [`setSessionCacheSize`](#setsessioncachesize) | 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. |
| `size_t` | [`getSessionCacheSize`](#getsessioncachesize) `const` | Returns the current maximum size of the server session cache. |
| `void` | [`setSessionTimeout`](#setsessiontimeout) | 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. |
| `long` | [`getSessionTimeout`](#getsessiontimeout) `const` | Returns the timeout (in seconds) of cached sessions on the server. |
| `void` | [`flushSessionCache`](#flushsessioncache) | Flushes the SSL session cache on the server. |
| `void` | [`disableStatelessSessionResumption`](#disablestatelesssessionresumption) | Newer versions of OpenSSL support RFC 4507 tickets for stateless session resumption. |
| `void` | [`setALPNProtocols`](#setalpnprotocols) | Set the ALPN protocols for negotiation. Protocols should be in preference order. Example: {"h2", "http/1.1"} |
| | [`SSLContext`](#sslcontext-5) | Deleted constructor. |
| [`SSLContext`](#sslcontext) & | [`operator=`](#operator-183) | Deleted assignment operator. |
| | [`SSLContext`](#sslcontext-6) | Deleted constructor. |
| [`SSLContext`](#sslcontext) & | [`operator=`](#operator-184) | Deleted assignment operator. |
---
### SSLContext
```cpp
SSLContext(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")
```
[Defined in src/net/include/icy/net/sslcontext.h:123](https://github.com/auscaster/icey/blob/main/src/net/include/icy/net/sslcontext.h#L123)
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](https://auscaster.com/icey/docs/api-reference/icy-net-SSLManager.md#sslmanager), or the [SSLManager](https://auscaster.com/icey/docs/api-reference/icy-net-SSLManager.md#sslmanager)'s PrivateKeyPassphraseRequired event must be handled.
---
### SSLContext
```cpp
SSLContext(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")
```
[Defined in src/net/include/icy/net/sslcontext.h:148](https://github.com/auscaster/icey/blob/main/src/net/include/icy/net/sslcontext.h#L148)
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.
---
### ~SSLContext
`noexcept`
```cpp
~SSLContext() noexcept
```
[Defined in src/net/include/icy/net/sslcontext.h:155](https://github.com/auscaster/icey/blob/main/src/net/include/icy/net/sslcontext.h#L155)
Destroys the Context.
---
### useCertificate
```cpp
void useCertificate(crypto::X509Certificate & certificate)
```
[Defined in src/net/include/icy/net/sslcontext.h:165](https://github.com/auscaster/icey/blob/main/src/net/include/icy/net/sslcontext.h#L165)
Sets the certificate to be used by the Context.
To set-up a complete certificate chain, it might be necessary to call [addChainCertificate()](#addchaincertificate) to specify additional certificates.
Note that [useCertificate()](#usecertificate) must always be called before usePrivateKey().
---
### addChainCertificate
```cpp
void addChainCertificate(crypto::X509Certificate & certificate)
```
[Defined in src/net/include/icy/net/sslcontext.h:168](https://github.com/auscaster/icey/blob/main/src/net/include/icy/net/sslcontext.h#L168)
Adds a certificate for certificate chain validation.
---
### addVerificationCertificate
```cpp
void addVerificationCertificate(crypto::X509Certificate & certificate)
```
[Defined in src/net/include/icy/net/sslcontext.h:184](https://github.com/auscaster/icey/blob/main/src/net/include/icy/net/sslcontext.h#L184)
Sets the private key to be used by the Context.
Note that [useCertificate()](#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](https://auscaster.com/icey/docs/api-reference/icy-net-SSLManager.md#sslmanager), or the [SSLManager](https://auscaster.com/icey/docs/api-reference/icy-net-SSLManager.md#sslmanager)'s PrivateKeyPassphraseRequired event must be handled. Adds the given certificate to the list of trusted certificates that will be used for verification.
---
### sslContext
`const` `inline`
```cpp
inline SSL_CTX * sslContext() const
```
[Defined in src/net/include/icy/net/sslcontext.h:187](https://github.com/auscaster/icey/blob/main/src/net/include/icy/net/sslcontext.h#L187)
Returns the underlying OpenSSL SSL Context object.
---
### usage
`const` `inline`
```cpp
inline Usage usage() const
```
[Defined in src/net/include/icy/net/sslcontext.h:191](https://github.com/auscaster/icey/blob/main/src/net/include/icy/net/sslcontext.h#L191)
Returns whether the context is for use by a client or by a server and whether TLSv1 is required.
---
### isForServerUse
`const` `inline`
```cpp
inline bool isForServerUse() const
```
[Defined in src/net/include/icy/net/sslcontext.h:194](https://github.com/auscaster/icey/blob/main/src/net/include/icy/net/sslcontext.h#L194)
Returns true if the context is for use by a server.
---
### verificationMode
`const` `inline`
```cpp
inline SSLContext::VerificationMode verificationMode() const
```
[Defined in src/net/include/icy/net/sslcontext.h:197](https://github.com/auscaster/icey/blob/main/src/net/include/icy/net/sslcontext.h#L197)
Returns the verification mode.
---
### enableSessionCache
```cpp
void enableSessionCache(bool flag = true)
```
[Defined in src/net/include/icy/net/sslcontext.h:208](https://github.com/auscaster/icey/blob/main/src/net/include/icy/net/sslcontext.h#L208)
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
```cpp
void enableSessionCache(bool flag, std::string_view sessionIdContext)
```
[Defined in src/net/include/icy/net/sslcontext.h:225](https://github.com/auscaster/icey/blob/main/src/net/include/icy/net/sslcontext.h#L225)
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.
---
### sessionCacheEnabled
`const`
```cpp
bool sessionCacheEnabled() const
```
[Defined in src/net/include/icy/net/sslcontext.h:228](https://github.com/auscaster/icey/blob/main/src/net/include/icy/net/sslcontext.h#L228)
Returns true if the session cache is enabled.
---
### setSessionCacheSize
```cpp
void setSessionCacheSize(size_t size)
```
[Defined in src/net/include/icy/net/sslcontext.h:238](https://github.com/auscaster/icey/blob/main/src/net/include/icy/net/sslcontext.h#L238)
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.
---
### getSessionCacheSize
`const`
```cpp
size_t getSessionCacheSize() const
```
[Defined in src/net/include/icy/net/sslcontext.h:243](https://github.com/auscaster/icey/blob/main/src/net/include/icy/net/sslcontext.h#L243)
Returns the current maximum size of the server session cache.
This method may only be called on SERVER_USE Context objects.
---
### setSessionTimeout
```cpp
void setSessionTimeout(long seconds)
```
[Defined in src/net/include/icy/net/sslcontext.h:250](https://github.com/auscaster/icey/blob/main/src/net/include/icy/net/sslcontext.h#L250)
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.
---
### getSessionTimeout
`const`
```cpp
long getSessionTimeout() const
```
[Defined in src/net/include/icy/net/sslcontext.h:255](https://github.com/auscaster/icey/blob/main/src/net/include/icy/net/sslcontext.h#L255)
Returns the timeout (in seconds) of cached sessions on the server.
This method may only be called on SERVER_USE Context objects.
---
### flushSessionCache
```cpp
void flushSessionCache()
```
[Defined in src/net/include/icy/net/sslcontext.h:260](https://github.com/auscaster/icey/blob/main/src/net/include/icy/net/sslcontext.h#L260)
Flushes the SSL session cache on the server.
This method may only be called on SERVER_USE Context objects.
---
### disableStatelessSessionResumption
```cpp
void disableStatelessSessionResumption()
```
[Defined in src/net/include/icy/net/sslcontext.h:266](https://github.com/auscaster/icey/blob/main/src/net/include/icy/net/sslcontext.h#L266)
Newer versions of OpenSSL support RFC 4507 tickets for stateless session resumption.
The feature can be disabled by calling this method.
---
### setALPNProtocols
```cpp
void setALPNProtocols(const std::vector< std::string > & protocols)
```
[Defined in src/net/include/icy/net/sslcontext.h:271](https://github.com/auscaster/icey/blob/main/src/net/include/icy/net/sslcontext.h#L271)
Set the ALPN protocols for negotiation. Protocols should be in preference order. Example: {"h2", "http/1.1"}
---
### SSLContext
```cpp
SSLContext(const SSLContext &) = delete
```
[Defined in src/net/include/icy/net/sslcontext.h:278](https://github.com/auscaster/icey/blob/main/src/net/include/icy/net/sslcontext.h#L278)
Deleted constructor.
---
### operator=
```cpp
SSLContext & operator=(const SSLContext &) = delete
```
[Defined in src/net/include/icy/net/sslcontext.h:279](https://github.com/auscaster/icey/blob/main/src/net/include/icy/net/sslcontext.h#L279)
Deleted assignment operator.
---
### SSLContext
```cpp
SSLContext(SSLContext &&) = delete
```
[Defined in src/net/include/icy/net/sslcontext.h:280](https://github.com/auscaster/icey/blob/main/src/net/include/icy/net/sslcontext.h#L280)
Deleted constructor.
---
### operator=
```cpp
SSLContext & operator=(SSLContext &&) = delete
```
[Defined in src/net/include/icy/net/sslcontext.h:281](https://github.com/auscaster/icey/blob/main/src/net/include/icy/net/sslcontext.h#L281)
Deleted assignment operator.
## Public Static Methods
| Return | Name | Description |
|--------|------|-------------|
| `void` | [`enableSNI`](#enablesni) `static` | Enable SNI (Server Name Indication) for a specific SSL connection. The hostname is sent during the TLS handshake to allow the server to select the appropriate certificate. |
---
### enableSNI
`static`
```cpp
static void enableSNI(SSL * ssl, const std::string & hostname)
```
[Defined in src/net/include/icy/net/sslcontext.h:276](https://github.com/auscaster/icey/blob/main/src/net/include/icy/net/sslcontext.h#L276)
Enable SNI (Server Name Indication) for a specific SSL connection. The hostname is sent during the TLS handshake to allow the server to select the appropriate certificate.
## Public Types
| Name | Description |
|------|-------------|
| [`Usage`](#usage-1) | |
| [`VerificationMode`](#verificationmode-1) | |
| [`Ptr`](#ptr-11) | |
---
### Usage
```cpp
enum Usage
```
[Defined in src/net/include/icy/net/sslcontext.h:49](https://github.com/auscaster/icey/blob/main/src/net/include/icy/net/sslcontext.h#L49)
| Value | Description |
|-------|-------------|
| `CLIENT_USE` | Context is used by a client. |
| `SERVER_USE` | Context is used by a server. |
| `TLSV1_CLIENT_USE` | Context is used by a client requiring TLSv1. |
| `TLSV1_SERVER_USE` | Context is used by a server requiring TLSv2. |
---
### VerificationMode
```cpp
enum VerificationMode
```
[Defined in src/net/include/icy/net/sslcontext.h:57](https://github.com/auscaster/icey/blob/main/src/net/include/icy/net/sslcontext.h#L57)
| Value | Description |
|-------|-------------|
| `VERIFY_NONE` | Server: The server will not send a client certificate request to the client, so the client will not send a certificate. |
| `VERIFY_RELAXED` | 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. |
| `VERIFY_STRICT` | Server: If the client did not return a certificate, the TLS/SSL handshake is immediately terminated with a handshake failure alert. |
| `VERIFY_ONCE` | 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. |
---
### Ptr
```cpp
using Ptr = std::shared_ptr< SSLContext >
```
Type: std::shared_ptr< [`SSLContext`](#sslcontext) >
[Defined in src/net/include/icy/net/sslcontext.h:47](https://github.com/auscaster/icey/blob/main/src/net/include/icy/net/sslcontext.h#L47)
## Private Attributes
| Return | Name | Description |
|--------|------|-------------|
| [`Usage`](#usage-1) | [`_usage`](#_usage) | |
| [`VerificationMode`](#verificationmode-1) | [`_mode`](#_mode) | |
| `SSL_CTX *` | [`_sslContext`](#_sslcontext) | |
| `std::vector< unsigned char >` | [`_alpnWire`](#_alpnwire) | Wire-format ALPN protocols for server selection. |
---
### _usage
```cpp
Usage _usage
```
Type: [`Usage`](#usage-1)
[Defined in src/net/include/icy/net/sslcontext.h:287](https://github.com/auscaster/icey/blob/main/src/net/include/icy/net/sslcontext.h#L287)
---
### _mode
```cpp
VerificationMode _mode
```
Type: [`VerificationMode`](#verificationmode-1)
[Defined in src/net/include/icy/net/sslcontext.h:288](https://github.com/auscaster/icey/blob/main/src/net/include/icy/net/sslcontext.h#L288)
---
### _sslContext
```cpp
SSL_CTX * _sslContext
```
[Defined in src/net/include/icy/net/sslcontext.h:289](https://github.com/auscaster/icey/blob/main/src/net/include/icy/net/sslcontext.h#L289)
---
### _alpnWire
```cpp
std::vector< unsigned char > _alpnWire
```
[Defined in src/net/include/icy/net/sslcontext.h:290](https://github.com/auscaster/icey/blob/main/src/net/include/icy/net/sslcontext.h#L290)
Wire-format ALPN protocols for server selection.
## Private Methods
| Return | Name | Description |
|--------|------|-------------|
| `void` | [`createSSLContext`](#createsslcontext) | Create a SSL_CTX object according to Context configuration. |
---
### createSSLContext
```cpp
void createSSLContext()
```
[Defined in src/net/include/icy/net/sslcontext.h:285](https://github.com/auscaster/icey/blob/main/src/net/include/icy/net/sslcontext.h#L285)
Create a SSL_CTX object according to Context configuration.