2 * Copyright (C) 1996-2015 The Squid Software Foundation and contributors
4 * Squid software is distributed under GPLv2+ license and includes
5 * contributions from numerous individuals and organizations.
6 * Please see the COPYING and CONTRIBUTORS files for details.
9 /* DEBUG: section 83 SSL accelerator support */
11 #ifndef SQUID_SSL_SUPPORT_H
12 #define SQUID_SSL_SUPPORT_H
14 #include "base/CbDataList.h"
15 #include "ssl/gadgets.h"
17 #if HAVE_OPENSSL_SSL_H
18 #include <openssl/ssl.h>
20 #if HAVE_OPENSSL_X509V3_H
21 #include <openssl/x509v3.h>
23 #if HAVE_OPENSSL_ERR_H
24 #include <openssl/err.h>
26 #if HAVE_OPENSSL_ENGINE_H
27 #include <openssl/engine.h>
31 \defgroup ServerProtocolSSLAPI Server-Side SSL API
32 \ingroup ServerProtocol
35 // Custom SSL errors; assumes all official errors are positive
36 #define SQUID_X509_V_ERR_INFINITE_VALIDATION -4
37 #define SQUID_X509_V_ERR_CERT_CHANGE -3
38 #define SQUID_ERR_SSL_HANDSHAKE -2
39 #define SQUID_X509_V_ERR_DOMAIN_MISMATCH -1
40 // All SSL errors range: from smallest (negative) custom to largest SSL error
41 #define SQUID_SSL_ERROR_MIN SQUID_X509_V_ERR_CERT_CHANGE
42 #define SQUID_SSL_ERROR_MAX INT_MAX
44 // Maximum certificate validation callbacks. OpenSSL versions exceeding this
45 // limit are deemed stuck in an infinite validation loop (OpenSSL bug #3090)
46 // and will trigger the SQUID_X509_V_ERR_INFINITE_VALIDATION error.
47 // Can be set to a number up to UINT32_MAX
48 #ifndef SQUID_CERT_VALIDATION_ITERATION_MAX
49 #define SQUID_CERT_VALIDATION_ITERATION_MAX 16384
59 /// Squid defined error code (<0), an error code returned by SSL X509 api, or SSL_ERROR_NONE
60 typedef int ssl_error_t
;
62 typedef CbDataList
<Ssl::ssl_error_t
> Errors
;
64 /// Creates SSL Client connection structure and initializes SSL I/O (Comm and BIO).
65 /// On errors, emits DBG_IMPORTANT with details and returns NULL.
66 SSL
*CreateClient(SSL_CTX
*sslContext
, const int fd
, const char *squidCtx
);
68 /// Creates SSL Server connection structure and initializes SSL I/O (Comm and BIO).
69 /// On errors, emits DBG_IMPORTANT with details and returns NULL.
70 SSL
*CreateServer(SSL_CTX
*sslContext
, const int fd
, const char *squidCtx
);
72 /// An SSL certificate-related error.
73 /// Pairs an error code with the certificate experiencing the error.
77 ssl_error_t code
; ///< certificate error code
78 X509_Pointer cert
; ///< certificate with the above error code
79 CertError(ssl_error_t anErr
, X509
*aCert
);
80 CertError(CertError
const &err
);
81 CertError
& operator = (const CertError
&old
);
82 bool operator == (const CertError
&ce
) const;
83 bool operator != (const CertError
&ce
) const;
86 /// Holds a list of certificate SSL errors
87 typedef CbDataList
<Ssl::CertError
> CertErrors
;
91 /// \ingroup ServerProtocolSSLAPI
92 SSL_CTX
*sslCreateServerContext(AnyP::PortCfg
&port
);
94 /// \ingroup ServerProtocolSSLAPI
95 SSL_CTX
*sslCreateClientContext(const char *certfile
, const char *keyfile
, int version
, const char *cipher
, const char *options
, const char *flags
, const char *CAfile
, const char *CApath
, const char *CRLfile
);
97 /// \ingroup ServerProtocolSSLAPI
98 int ssl_read_method(int, char *, int);
100 /// \ingroup ServerProtocolSSLAPI
101 int ssl_write_method(int, const char *, int);
103 /// \ingroup ServerProtocolSSLAPI
104 void ssl_shutdown_method(SSL
*ssl
);
106 /// \ingroup ServerProtocolSSLAPI
107 const char *sslGetUserEmail(SSL
*ssl
);
109 /// \ingroup ServerProtocolSSLAPI
110 const char *sslGetUserAttribute(SSL
*ssl
, const char *attribute_name
);
112 /// \ingroup ServerProtocolSSLAPI
113 const char *sslGetCAAttribute(SSL
*ssl
, const char *attribute_name
);
115 /// \ingroup ServerProtocolSSLAPI
116 const char *sslGetUserCertificatePEM(SSL
*ssl
);
118 /// \ingroup ServerProtocolSSLAPI
119 const char *sslGetUserCertificateChainPEM(SSL
*ssl
);
123 /// \ingroup ServerProtocolSSLAPI
124 typedef char const *GETX509ATTRIBUTE(X509
*, const char *);
126 /// \ingroup ServerProtocolSSLAPI
127 GETX509ATTRIBUTE GetX509UserAttribute
;
129 /// \ingroup ServerProtocolSSLAPI
130 GETX509ATTRIBUTE GetX509CAAttribute
;
132 /// \ingroup ServerProtocolSSLAPI
133 GETX509ATTRIBUTE GetX509Fingerprint
;
135 extern const EVP_MD
*DefaultSignHash
;
138 \ingroup ServerProtocolSSLAPI
139 * Supported ssl-bump modes
141 enum BumpMode
{bumpNone
= 0, bumpClientFirst
, bumpServerFirst
, bumpPeek
, bumpStare
, bumpBump
, bumpSplice
, bumpTerminate
, /*bumpErr,*/ bumpEnd
};
143 enum BumpStep
{bumpStep1
, bumpStep2
, bumpStep3
};
146 \ingroup ServerProtocolSSLAPI
147 * Short names for ssl-bump modes
149 extern const char *BumpModeStr
[];
152 \ingroup ServerProtocolSSLAPI
153 * Return the short name of the ssl-bump mode "bm"
155 inline const char *bumpMode(int bm
)
157 return (0 <= bm
&& bm
< Ssl::bumpEnd
) ? Ssl::BumpModeStr
[bm
] : NULL
;
161 \ingroup ServerProtocolSSLAPI
162 * Parses the SSL flags.
164 long parse_flags(const char *flags
);
167 \ingroup ServerProtocolSSLAPI
168 * Parses the SSL options.
170 long parse_options(const char *options
);
173 \ingroup ServerProtocolSSLAPI
174 * Load a CRLs list stored in a file
176 STACK_OF(X509_CRL
) *loadCrl(const char *CRLFile
, long &flags
);
179 \ingroup ServerProtocolSSLAPI
180 * Load DH params from file
182 DH
*readDHParams(const char *dhfile
);
185 \ingroup ServerProtocolSSLAPI
186 * Compute the Ssl::ContextMethod (SSL_METHOD) from SSL version
188 ContextMethod
contextMethod(int version
);
191 \ingroup ServerProtocolSSLAPI
192 * Generate a certificate to be used as untrusted signing certificate, based on a trusted CA
194 bool generateUntrustedCert(X509_Pointer
& untrustedCert
, EVP_PKEY_Pointer
& untrustedPkey
, X509_Pointer
const & cert
, EVP_PKEY_Pointer
const & pkey
);
197 \ingroup ServerProtocolSSLAPI
198 * Decide on the kind of certificate and generate a CA- or self-signed one
200 SSL_CTX
* generateSslContext(CertificateProperties
const &properties
, AnyP::PortCfg
&port
);
203 \ingroup ServerProtocolSSLAPI
204 * Check if the certificate of the given context is still valid
205 \param sslContext The context to check
206 \param properties Check if the context certificate matches the given properties
207 \return true if the contexts certificate is valid, false otherwise
209 bool verifySslCertificate(SSL_CTX
* sslContext
, CertificateProperties
const &properties
);
212 \ingroup ServerProtocolSSLAPI
213 * Read private key and certificate from memory and generate SSL context
216 SSL_CTX
* generateSslContextUsingPkeyAndCertFromMemory(const char * data
, AnyP::PortCfg
&port
);
219 \ingroup ServerProtocolSSLAPI
220 * Create an SSL context using the provided certificate and key
222 SSL_CTX
* createSSLContext(Ssl::X509_Pointer
& x509
, Ssl::EVP_PKEY_Pointer
& pkey
, AnyP::PortCfg
&port
);
225 \ingroup ServerProtocolSSLAPI
226 * Generates a certificate and a private key using provided properies and set it
229 bool configureSSL(SSL
*ssl
, CertificateProperties
const &properties
, AnyP::PortCfg
&port
);
232 \ingroup ServerProtocolSSLAPI
233 * Read private key and certificate from memory and set it to SSL object
236 bool configureSSLUsingPkeyAndCertFromMemory(SSL
*ssl
, const char *data
, AnyP::PortCfg
&port
);
239 \ingroup ServerProtocolSSLAPI
240 * Adds the certificates in certList to the certificate chain of the SSL context
242 void addChainToSslContext(SSL_CTX
*sslContext
, STACK_OF(X509
) *certList
);
245 \ingroup ServerProtocolSSLAPI
246 * Read certificate, private key and any certificates which must be chained from files.
247 * See also: Ssl::readCertAndPrivateKeyFromFiles function, defined in gadgets.h
248 * \param certFilename name of file with certificate and certificates which must be chainned.
249 * \param keyFilename name of file with private key.
251 void readCertChainAndPrivateKeyFromFiles(X509_Pointer
& cert
, EVP_PKEY_Pointer
& pkey
, X509_STACK_Pointer
& chain
, char const * certFilename
, char const * keyFilename
);
254 \ingroup ServerProtocolSSLAPI
255 * Iterates over the X509 common and alternate names and to see if matches with given data
256 * using the check_func.
257 \param peer_cert The X509 cert to check
258 \param check_data The data with which the X509 CNs compared
259 \param check_func The function used to match X509 CNs. The CN data passed as ASN1_STRING data
260 \return 1 if any of the certificate CN matches, 0 if none matches.
262 int matchX509CommonNames(X509
*peer_cert
, void *check_data
, int (*check_func
)(void *check_data
, ASN1_STRING
*cn_data
));
265 \ingroup ServerProtocolSSLAPI
266 * Check if the certificate is valid for a server
267 \param cert The X509 cert to check.
268 \param server The server name.
269 \return true if the certificate is valid for the server or false otherwise.
271 bool checkX509ServerValidity(X509
*cert
, const char *server
);
274 \ingroup ServerProtocolSSLAPI
275 * Convert a given ASN1_TIME to a string form.
276 \param tm the time in ASN1_TIME form
277 \param buf the buffer to write the output
278 \param len write at most len bytes
279 \return The number of bytes written
281 int asn1timeToString(ASN1_TIME
*tm
, char *buf
, int len
);
284 \ingroup ServerProtocolSSLAPI
285 * Sets the hostname for the Server Name Indication (SNI) TLS extension
286 * if supported by the used openssl toolkit.
287 \return true if SNI set false otherwise
289 bool setClientSNI(SSL
*ssl
, const char *fqdn
);
291 int OpenSSLtoSquidSSLVersion(int sslVersion
);
293 #if OPENSSL_VERSION_NUMBER < 0x00909000L
294 SSL_METHOD
*method(int version
);
296 const SSL_METHOD
*method(int version
);
299 const SSL_METHOD
*serverMethod(int version
);
302 \ingroup ServerProtocolSSLAPI
303 * Initializes the shared session cache if configured
305 void initialize_session_cache();
308 \ingroup ServerProtocolSSLAPI
309 * Destroy the shared session cache if configured
311 void destruct_session_cache();
316 #if defined(__cplusplus)
318 /** \cond AUTODOCS-IGNORE */
323 /// \ingroup ServerProtocolSSLAPI
325 int SSL_set_fd(SSL
*ssl
, int fd
)
327 return ::SSL_set_fd(ssl
, _get_osfhandle(fd
));
330 /// \ingroup ServerProtocolSSLAPI
331 #define SSL_set_fd(ssl,fd) Squid::SSL_set_fd(ssl,fd)
333 } /* namespace Squid */
337 /// \ingroup ServerProtocolSSLAPI
338 #define SSL_set_fd(s,f) (SSL_set_fd(s, _get_osfhandle(f)))
340 #endif /* __cplusplus */
342 #endif /* _SQUID_WINDOWS_ */
344 #endif /* SQUID_SSL_SUPPORT_H */