SSL Context

Detailed Description

Context is the shared configuration for SSL/TLS connections. It is not a connection and it does not wrap a stream. Many IOStream and StreamBuffer objects can open with the same context and then run their own handshakes.

The context holds the protocol, the verification mode, how deep a peer certificate chain is checked, the identity presented to the peer, extra certificates that complete that identity's chain, and the trusted CA certificates used to verify the peer. A default-constructed context uses the highest available TLS protocol and TryVerify. setProtocol() selects an explicit version when the peer requires one. TLS is the highest available protocol; TLSv1, TLSv1_1 and TLSv1_2 pin a version.

setIdentity() sets the certificate presented to the peer. A server context must have an identity. A client context needs one only when the server asks for client authentication. Because a private key stays attached to its certificate in the store, setting the identity selects that key as well. addCertificate() adds a certificate to the chain presented together with the identity. addCACertificate() adds a trusted CA used to verify the peer; it does not change the identity.

setVerifyMode() chooses whether the peer must authenticate. NoVerify does not check a peer certificate. TryVerify checks a certificate when the peer presents one and continues if none is presented. AlwaysVerify requires a peer certificate and fails the handshake without one. setVerifyDepth() limits how many certificates in the peer chain are checked.

The context copies the certificate data it needs when identity, chain, or CA certificates are set, so the store does not have to remain after those calls. The Certificate argument of each call must still be valid for the call. Unusable certificate material throws InvalidCertificate.

Context is not copyable. assign() copies protocol, verify settings, and certificates into another context.

The example prepares a server context from certificates already in a store. Opening a stream with that context is the next chapter.

Pt::Ssl::Context ctx(Pt::Ssl::TLSv1_2);
ctx.setVerifyMode(Pt::Ssl::AlwaysVerify);
ctx.setIdentity(store.getCertificate("Example Server"));
ctx.addCACertificate(store.getCertificate("Example CA"));

Classes
class	Context
	Shared configuration for SSL connections. More...
class	InvalidCertificate
	Invalid SSL certificate or certificate chain. More...

Enumerations
enum	Protocol {   SSLv2 = 0,   SSLv3or2 = 1,   SSLv3 = 2,   TLS = SSLv3or2,   TLSv1 = 3,   TLSv1_1 = 4,   TLSv1_2 = 5 }
	SSL/TLS protocol version. More...
enum	VerifyMode {   NoVerify = 0,   TryVerify = 1,   AlwaysVerify = 2 }
	How the peer certificate is verified. More...

Enumeration Type Documentation

Protocol

enum Protocol

Enumerator
SSLv2	SSL version 2.
SSLv3or2	Highest available protocol version.
SSLv3	SSL version 3.
TLS	Highest available TLS protocol version.
TLSv1	TLS version 1.0.
TLSv1_1	TLS version 1.1.
TLSv1_2	TLS version 1.2.

VerifyMode

enum VerifyMode

Enumerator
NoVerify	Do not verify the peer.
TryVerify	Verify a certificate when the peer presents one.
AlwaysVerify	Require a peer certificate.