Network/connection security abstraction layer.

Namespaces
	Io

Classes
class	Alert
	TLS Alert protocol frame from RFC 5246 Section 7.2. More...

class	BlindPeerConnector
	A PeerConnector for TLS cache_peers and origin servers. No SslBump capabilities. More...

class	CertError

class	CommunicationSecrets

class	EncryptorAnswer

class	ErrorDetail

class	Extension
	TLS Hello Extension from RFC 5246 Section 7.4.1.4. More...

class	FuturePeerContext
	A combination of PeerOptions and the corresponding Context. More...

class	Handshake
	TLS Handshake Protocol frame from RFC 5246 Section 7.4. More...

class	HandshakeParser
	Incremental TLS/SSL Handshake parser. More...

class	IoResult
	a summary a TLS I/O operation outcome More...

class	KeyData
	TLS certificate and private key details from squid.conf. More...

class	KeyLog
	a single tls_key_log directive configuration and logging handler More...

class	KeyLogger
	manages collecting and logging secrets of a TLS connection to tls_key_log More...

class	LockingPointer

class	NegotiationHistory

class	PeerConnector

class	PeerOptions
	TLS squid.conf settings for a remote server peer. More...

class	ServerOptions
	TLS squid.conf settings for a listening port. More...

class	Sslv2Record
	draft-hickman-netscape-ssl-00. Section 4.1. SSL Record Header Format More...

class	TlsDetails

class	TLSPlaintext
	TLS Record Layer's frame from RFC 5246 Section 6.2.1. More...

Typedefs
typedef std::shared_ptr< SSL_CTX >	ContextPointer

typedef std::map< ErrorCode, const char * >	ErrorCodeNames

typedef CbDataList< Security::CertError >	CertErrors
	Holds a list of X.509 certificate errors. More...

typedef X509	Certificate

typedef Security::LockingPointer< X509, X509_free_cpp, HardFun< int, X509 *, X509_up_ref > >	CertPointer

typedef Security::LockingPointer< X509_CRL, X509_CRL_free_cpp, HardFun< int, X509_CRL *, X509_CRL_up_ref > >	CrlPointer

typedef std::list< Security::CertPointer >	CertList

typedef std::list< Security::CrlPointer >	CertRevokeList

typedef Security::LockingPointer< DH, DH_free_cpp, HardFun< int, DH *, DH_up_ref > >	DhePointer

typedef int	ErrorCode
	Squid-defined error code (<0), an error code returned by X.509 API, or zero. More...

typedef unsigned long	LibErrorCode
	TLS library-reported non-validation error. More...

typedef std::unordered_set< Security::ErrorCode >	Errors

using	ParsedOptions = uint64_t

typedef long	ParsedPortFlags

typedef RefCount< ErrorDetail >	ErrorDetailPointer

typedef std::unordered_set< Extension::Type >	Extensions
	Extension types optimized for fast lookups. More...

typedef SessionPointer::element_type *	ConnectionPointer

typedef HardFun< bool, const void *, nilFunction >	NilFunctor

typedef RefCount< IoResult >	IoResultPointer

typedef SSL	Connection

using	Session = SSL_SESSION

typedef std::shared_ptr< SSL >	SessionPointer

typedef std::unique_ptr< SSL_SESSION, HardFun< void, SSL_SESSION *, &SSL_SESSION_free > >	SessionStatePointer

Enumerations
enum	ContentType { ctChangeCipherSpec = 20, ctAlert = 21, ctHandshake = 22, ctApplicationData = 23 }
	TLS Record Layer's content types from RFC 5246 Section 6.2.1. More...

enum	HandshakeType { hskClientHello = 1, hskServerHello = 2, hskCertificate = 11, hskServerHelloDone = 14 }
	TLS Handshake protocol's handshake types from RFC 5246 Section 7.4. More...

Functions
SBuf	SubjectName (Certificate &)
	The SubjectName field of the given certificate (if found) or an empty SBuf. More...

SBuf	IssuerName (Certificate &)
	The Issuer field of the given certificate (if found) or an empty SBuf. More...

bool	IssuedBy (Certificate &cert, Certificate &issuer)

bool	SelfSigned (Certificate &c)
	Whether the given certificate is self-signed. More...

std::ostream &	operator<< (std::ostream &, const EncryptorAnswer &)

ErrorCode	ErrorCodeFromName (const char *name)

const char *	ErrorNameFromCode (ErrorCode err, bool prefixRawCode=false)

std::ostream &	operator<< (std::ostream &os, const ErrorDetail::Pointer &p)
	dump the given ErrorDetail via a possibly nil pointer (for debugging) More...

	CtoCpp1 (X509_free, X509 *)

	CtoCpp1 (X509_CRL_free, X509_CRL *)

	CtoCpp1 (EVP_PKEY_free, EVP_PKEY *) using PrivateKeyPointer

	CtoCpp1 (DH_free, DH *)

const char *	ErrorString (const LibErrorCode code)
	converts numeric LibErrorCode into a human-friendlier string More...

std::ostream &	operator<< (std::ostream &, const KeyLog &)

void	OpenLogs ()
	opens logs enabled in the current configuration More...

void	RotateLogs ()
	rotates logs opened by OpenLogs() More...

void	CloseLogs ()
	closes logs opened by OpenLogs() More...

static Extensions	SupportedExtensions ()
	A helper function to create a set of all supported TLS extensions. More...

static AnyP::ProtocolVersion	ParseProtocolVersionBase (Parser::BinaryTokenizer &tk, const char *contextLabel, const bool beStrict)

static AnyP::ProtocolVersion	ParseProtocolVersion (Parser::BinaryTokenizer &tk)

static AnyP::ProtocolVersion	ParseOptionalProtocolVersion (Parser::BinaryTokenizer &tk, const char *contextLabel)

std::ostream &	operator<< (std::ostream &os, const TlsDetails &details)

bool	TlsFamilyProtocol (const AnyP::ProtocolVersion &version)
	whether the given protocol belongs to the TLS/SSL group of protocols More...

bool	TlsVersionEarlierThan (const AnyP::ProtocolVersion &a, const AnyP::ProtocolVersion &b)
	whether TLS/SSL protocol `a` precedes TLS/SSL protocol `b` More...

bool	Tls1p2orEarlier (const AnyP::ProtocolVersion &p)
	whether the given TLS/SSL protocol is TLS v1.2 or earlier, including SSL More...

bool	Tls1p3orLater (const AnyP::ProtocolVersion &p)
	whether the given TLS/SSL protocol is TLS v1.3 or later More...

template<typename Fun >
static IoResult	Handshake (Comm::Connection &, ErrorCode, Fun)

static void	PrepForIo ()

std::ostream &	operator<< (std::ostream &os, const IoResult &result)

IoResult	Accept (Comm::Connection &transport)
	accept a TLS connection over the specified to-Squid transport connection More...

IoResult	Connect (Comm::Connection &transport)
	establish a TLS connection over the specified from-Squid transport connection More...

void	ForgetErrors ()
	clear any errors that a TLS library has accumulated in its global storage More...

bool	nilFunction (const void *)

PeerOptions &	ProxyOutgoingConfig ()
	configuration options for DIRECT server access More...

bool	CreateClientSession (FuturePeerContext &, const Comm::ConnectionPointer &, const char *squidCtx)

bool	CreateServerSession (const Security::ContextPointer &, const Comm::ConnectionPointer &, Security::PeerOptions &, const char *squidCtx)

void	SessionSendGoodbye (const Security::SessionPointer &)
	send the shutdown/bye notice for an active TLS session. More...

bool	SessionIsResumed (const Security::SessionPointer &)
	whether the session is a resumed one More...

void	MaybeGetSessionResumeData (const Security::SessionPointer &, Security::SessionStatePointer &data)

void	SetSessionResumeData (const Security::SessionPointer &, const Security::SessionStatePointer &)

void	SetSessionCacheCallbacks (Security::ContextPointer &)
	Setup the given TLS context with callbacks used to manage the session cache. More...

Security::ContextPointer	GetFrom (Security::SessionPointer &s)
	Helper function to retrieve a (non-locked) ContextPointer from a SessionPointer. More...

Security::SessionPointer	NewSessionObject (const Security::ContextPointer &)

Variables
static const ErrorCodeNames	TheErrorCodeNames

static const uint64_t	HelloRandomSize = 32
	The size of the TLS Random structure from RFC 5246 Section 7.4.1.2. More...

Typedef Documentation

◆ CertErrors

typedef CbDataList<Security::CertError> Security::CertErrors

Definition at line 74 of file forward.h.

◆ Certificate

typedef X509 Security::Certificate

Definition at line 79 of file forward.h.

◆ CertList

typedef std::list<Security::CertPointer> Security::CertList

Definition at line 105 of file forward.h.

◆ CertPointer

typedef Security::LockingPointer<X509, X509_free_cpp, HardFun<int, X509 *, X509_up_ref> > Security::CertPointer

Definition at line 88 of file forward.h.

◆ CertRevokeList

typedef std::list<Security::CrlPointer> Security::CertRevokeList

Definition at line 107 of file forward.h.

◆ Connection

typedef SSL Security::Connection

Definition at line 49 of file Session.h.

◆ ConnectionPointer

typedef SessionPointer::element_type* Security::ConnectionPointer

Definition at line 23 of file Io.cc.

◆ ContextPointer

typedef std::shared_ptr<SSL_CTX> Security::ContextPointer

Definition at line 29 of file Context.h.

◆ CrlPointer

typedef Security::LockingPointer<X509_CRL, X509_CRL_free_cpp, HardFun<int, X509_CRL *, X509_CRL_up_ref> > Security::CrlPointer

Definition at line 97 of file forward.h.

◆ DhePointer

typedef Security::LockingPointer<DH, DH_free_cpp, HardFun<int, DH *, DH_up_ref> > Security::DhePointer

Definition at line 121 of file forward.h.

◆ ErrorCode

typedef int Security::ErrorCode

Definition at line 131 of file forward.h.

◆ ErrorCodeNames

typedef std::map<ErrorCode, const char *> Security::ErrorCodeNames

Definition at line 34 of file ErrorDetail.cc.

◆ ErrorDetailPointer

typedef RefCount<ErrorDetail> Security::ErrorDetailPointer

Definition at line 214 of file forward.h.

◆ Errors

typedef std::unordered_set<Security::ErrorCode> Security::Errors

set of Squid defined TLS error codes

Note: using std::unordered_set ensures values are unique, with fast lookup

Definition at line 165 of file forward.h.

◆ Extensions

typedef std::unordered_set<Extension::Type> Security::Extensions

Definition at line 106 of file Handshake.cc.

◆ IoResultPointer

typedef RefCount<IoResult> Security::IoResultPointer

Definition at line 37 of file PeerConnector.h.

◆ LibErrorCode

typedef unsigned long Security::LibErrorCode

the result of the first ERR_get_error(3SSL) call after a library call; openssl errstr expands these numbers into human-friendlier strings like error:1408F09C:SSL routines:ssl3_get_record:http request

Definition at line 141 of file forward.h.

◆ NilFunctor

typedef HardFun<bool, const void *, nilFunction> Security::NilFunctor

Definition at line 37 of file LockingPointer.h.

◆ ParsedOptions

using Security::ParsedOptions = typedef uint64_t

Definition at line 194 of file forward.h.

◆ ParsedPortFlags

typedef long Security::ParsedPortFlags

bitmask representing configured http(s)_port sslflags as well tls_outgoing_options flags, cache_peer sslflags, and icap_service tls-flags

Definition at line 204 of file forward.h.

◆ Session

using Security::Session = typedef SSL_SESSION

Definition at line 51 of file Session.h.

◆ SessionPointer

typedef std::shared_ptr<SSL> Security::SessionPointer

Definition at line 53 of file Session.h.

◆ SessionStatePointer

typedef std::unique_ptr<SSL_SESSION, HardFun<void, SSL_SESSION*, &SSL_SESSION_free> > Security::SessionStatePointer

Definition at line 55 of file Session.h.

Enumeration Type Documentation

◆ ContentType

enum Security::ContentType

Enumerator
ctChangeCipherSpec
ctAlert
ctHandshake
ctApplicationData

Definition at line 30 of file Handshake.cc.

◆ HandshakeType

enum Security::HandshakeType

Enumerator
hskClientHello
hskServerHello
hskCertificate
hskServerHelloDone

Definition at line 58 of file Handshake.cc.

Function Documentation

◆ Accept()

Security::IoResult Security::Accept ( Comm::Connection & transport )

Definition at line 211 of file Io.cc.

References Handshake(), and SQUID_TLS_ERR_ACCEPT.

Referenced by ConnStateData::acceptTls().

◆ CloseLogs()

void Security::CloseLogs ( )

Definition at line 85 of file KeyLog.cc.

References FormattedLog::close(), Config, SquidConfig::Log, and SquidConfig::tlsKeys.

Referenced by mainReconfigureStart().

◆ Connect()

Security::IoResult Security::Connect ( Comm::Connection & transport )

Definition at line 226 of file Io.cc.

References Handshake(), and SQUID_TLS_ERR_CONNECT.

Referenced by Security::PeerConnector::negotiate().

◆ CreateClientSession()

bool Security::CreateClientSession	(	FuturePeerContext &	ctx,
		const Comm::ConnectionPointer &	c,
		const char *	squidCtx
	)

Creates TLS Client connection structure (aka 'session' state) and initializes TLS/SSL I/O (Comm and BIO). On errors, emits DBG_IMPORTANT with details and returns false.

Definition at line 183 of file Session.cc.

References Security::Io::BIO_TO_SERVER, CreateSession(), Security::FuturePeerContext::options, and Security::FuturePeerContext::raw.

Referenced by Security::PeerConnector::initialize().

◆ CreateServerSession()

bool Security::CreateServerSession	(	const Security::ContextPointer &	ctx,
		const Comm::ConnectionPointer &	c,
		Security::PeerOptions &	o,
		const char *	squidCtx
	)

Creates TLS Server connection structure (aka 'session' state) and initializes TLS/SSL I/O (Comm and BIO). On errors, emits DBG_IMPORTANT with details and returns false.

Definition at line 194 of file Session.cc.

References Security::Io::BIO_TO_CLIENT, and CreateSession().

Referenced by httpsCreate().

◆ CtoCpp1() [1/4]

Security::CtoCpp1	(	DH_free	,
		DH *
	)

◆ CtoCpp1() [2/4]

Security::CtoCpp1	(	EVP_PKEY_free	,
		EVP_PKEY *
	)

◆ CtoCpp1() [3/4]

Security::CtoCpp1	(	X509_CRL_free	,
		X509_CRL *
	)

◆ CtoCpp1() [4/4]

Security::CtoCpp1	(	X509_free	,
		X509 *
	)

◆ ErrorCodeFromName()

Security::ErrorCode Security::ErrorCodeFromName ( const char * name )

Returns: ErrorCode with a given name (or zero)

Definition at line 410 of file ErrorDetail.cc.

References SQUID_TLS_ERR_CONNECT, and TheErrorCodeNames.

Referenced by Ssl::GetErrorCode().

◆ ErrorNameFromCode()

const char * Security::ErrorNameFromCode	(	ErrorCode	err,
		bool	prefixRawCode = `false`
	)

Returns: string representation of ErrorCode, including raw X.509 error codes

Parameters

prefixRawCode whether to prefix raw codes with "SSL_ERR="

Definition at line 430 of file ErrorDetail.cc.

References TheErrorCodeNames.

Referenced by Ssl::GetErrorName(), and Security::ErrorDetail::printErrorCode().

◆ ErrorString()

const char* Security::ErrorString ( const LibErrorCode code )

inline

Definition at line 152 of file forward.h.

References code.

Referenced by Ssl::chainCertificatesToSSLContext(), Security::PeerOptions::createBlankContext(), Security::ServerOptions::createBlankContext(), CreateSession(), Security::ServerOptions::createStaticServerContext(), findIssuerInCaDb(), Ssl::InitClientContext(), Ssl::Initialize(), IssuerName(), Security::KeyData::loadCertificates(), loadSystemTrustedCa(), MaybeGetSessionResumeData(), Security::PeerOptions::parseOptions(), Security::ErrorDetail::printErrorLibError(), Ssl::setClientSNI(), SetSessionResumeData(), SubjectName(), Security::PeerOptions::updateContextCa(), Security::ServerOptions::updateContextClientCa(), Security::ServerOptions::updateContextConfig(), Security::ServerOptions::updateContextEecdh(), Security::PeerOptions::updateContextTrust(), and Security::PeerOptions::updateSessionOptions().

◆ ForgetErrors()

void Security::ForgetErrors ( )

Definition at line 71 of file Io.cc.

References Ssl::ForgetErrors().

Referenced by Security::ErrorDetail::ErrorDetail(), PrepForIo(), and Ssl::ReadOnlyBioTiedTo().

◆ GetFrom()

Security::ContextPointer Security::GetFrom ( Security::SessionPointer & s )

inline

Definition at line 109 of file Session.h.

Referenced by ConnStateData::getSslContextStart(), and ConnStateData::sslCrtdHandleReply().

◆ Handshake()

template<typename Fun >

static IoResult Security::Handshake	(	Comm::Connection &	,
		ErrorCode	,
		Fun
	)

static

Referenced by Accept(), and Connect().

◆ IssuedBy()

bool Security::IssuedBy	(	Certificate &	cert,
		Certificate &	issuer
	)

Whether cert was (correctly) issued by the given issuer. Due to complexity of the underlying checks, it is impossible to clearly distinguish pure negative answers (e.g., two independent certificates) from errors (e.g., the issuer certificate lacks the right CA extension).

Definition at line 108 of file Certificate.cc.

References DBG_PARSE_NOTE, debugs, Debug::Extra(), Ssl::ForgetErrors(), MissingLibraryError(), and Ssl::ReportAndForgetErrors().

Referenced by findCertIssuerFast(), SelfSigned(), and sk_x509_findIssuer().

◆ IssuerName()

SBuf Security::IssuerName ( Certificate & cert )

Definition at line 28 of file Certificate.cc.

References SBuf::append(), DBG_PARSE_NOTE, debugs, ErrorString(), Ssl::ForgetErrors(), MissingLibraryError(), Ssl::OneLineSummary(), and Ssl::ReportAndForgetErrors().

Referenced by Format::Format::assemble(), clientNegotiateSSL(), findCertIssuerFast(), and Security::ErrorDetail::printCaName().

◆ MaybeGetSessionResumeData()

void Security::MaybeGetSessionResumeData	(	const Security::SessionPointer &	s,
		Security::SessionStatePointer &	data
	)

When the session is not a resumed session, retrieve the details needed to resume a later connection and store them in 'data'. This may result in 'data' becoming a nil Pointer if no details exist or an error occurs.

When the session is already a resumed session, do nothing and leave 'data' unhanged. XXX: is this latter behaviour always correct?

Definition at line 226 of file Session.cc.

References debugs, ErrorString(), and SessionIsResumed().

Referenced by Security::BlindPeerConnector::noteNegotiationDone(), and Ssl::IcapPeerConnector::noteNegotiationDone().

◆ NewSessionObject()

Security::SessionPointer Security::NewSessionObject ( const Security::ContextPointer & ctx )

Deprecated:: use the PeerOptions/ServerOptions API methods instead. Wraps SessionPointer value creation to reduce risk of a nasty hack in ssl/support.cc.

Definition at line 90 of file Session.cc.

References debugs.

Referenced by CreateSession(), and Ssl::verifySslCertificate().

◆ nilFunction()

bool Security::nilFunction ( const void * )

inline

Definition at line 36 of file LockingPointer.h.

◆ OpenLogs()

void Security::OpenLogs ( )

Definition at line 71 of file KeyLog.cc.

References Config, SquidConfig::Log, FormattedLog::open(), and SquidConfig::tlsKeys.

Referenced by mainInitialize(), and mainReconfigureFinish().

◆ operator<<() [1/5]

std::ostream & Security::operator<<	(	std::ostream &	os,
		const EncryptorAnswer &	answer
	)

Definition at line 20 of file EncryptorAnswer.cc.

References Security::EncryptorAnswer::conn, and Security::EncryptorAnswer::error.

Referenced by operator<<().

◆ operator<<() [2/5]

std::ostream& Security::operator<<	(	std::ostream &	,
		const KeyLog &
	)

◆ operator<<() [3/5]

std::ostream& Security::operator<<	(	std::ostream &	os,
		const ErrorDetail::Pointer &	p
	)

inline

Dump the given Security::ErrorDetail via a possibly nil pointer (for debugging). Unfortunately, without this, compilers pick generic RefCount<T> operator "<<" overload (with T=Security::ErrorDetail) instead of the overload provided by the parent ErrorDetail class (that we call here).

Definition at line 138 of file ErrorDetail.h.

References operator<<().