src/ssl/support.h

   1 /*
   2  * Copyright (C) 1996-2015 The Squid Software Foundation and contributors
   3  *
   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.
   7  */
   8
   9 /* DEBUG: section 83    SSL accelerator support */
  10
  11 #ifndef SQUID_SSL_SUPPORT_H
  12 #define SQUID_SSL_SUPPORT_H
  13
  14 #include "base/CbDataList.h"
  15 #include "security/forward.h"
  16 #include "ssl/gadgets.h"
  17
  18 #if HAVE_OPENSSL_X509V3_H
  19 #include <openssl/x509v3.h>
  20 #endif
  21 #if HAVE_OPENSSL_ERR_H
  22 #include <openssl/err.h>
  23 #endif
  24 #if HAVE_OPENSSL_ENGINE_H
  25 #include <openssl/engine.h>
  26 #endif
  27
  28 /**
  29  \defgroup ServerProtocolSSLAPI Server-Side SSL API
  30  \ingroup ServerProtocol
  31  */
  32
  33 // Custom SSL errors; assumes all official errors are positive
  34 #define SQUID_X509_V_ERR_INFINITE_VALIDATION -4
  35 #define SQUID_X509_V_ERR_CERT_CHANGE -3
  36 #define SQUID_ERR_SSL_HANDSHAKE -2
  37 #define SQUID_X509_V_ERR_DOMAIN_MISMATCH -1
  38 // All SSL errors range: from smallest (negative) custom to largest SSL error
  39 #define SQUID_SSL_ERROR_MIN SQUID_X509_V_ERR_CERT_CHANGE
  40 #define SQUID_SSL_ERROR_MAX INT_MAX
  41
  42 // Maximum certificate validation callbacks. OpenSSL versions exceeding this
  43 // limit are deemed stuck in an infinite validation loop (OpenSSL bug #3090)
  44 // and will trigger the SQUID_X509_V_ERR_INFINITE_VALIDATION error.
  45 // Can be set to a number up to UINT32_MAX
  46 #ifndef SQUID_CERT_VALIDATION_ITERATION_MAX
  47 #define SQUID_CERT_VALIDATION_ITERATION_MAX 16384
  48 #endif
  49
  50 namespace AnyP
  51 {
  52 class PortCfg;
  53 };
  54
  55 namespace Ssl
  56 {
  57 /// Squid defined error code (<0),  an error code returned by SSL X509 api, or SSL_ERROR_NONE
  58 typedef int ssl_error_t;
  59
  60 typedef CbDataList<Ssl::ssl_error_t> Errors;
  61
  62 /// Creates SSL Client connection structure and initializes SSL I/O (Comm and BIO).
  63 /// On errors, emits DBG_IMPORTANT with details and returns NULL.
  64 SSL *CreateClient(SSL_CTX *sslContext, const int fd, const char *squidCtx);
  65
  66 /// Creates SSL Server connection structure and initializes SSL I/O (Comm and BIO).
  67 /// On errors, emits DBG_IMPORTANT with details and returns NULL.
  68 SSL *CreateServer(SSL_CTX *sslContext, const int fd, const char *squidCtx);
  69
  70 /// An SSL certificate-related error.
  71 /// Pairs an error code with the certificate experiencing the error.
  72 class CertError
  73 {
  74 public:
  75     ssl_error_t code; ///< certificate error code
  76     Security::CertPointer cert; ///< certificate with the above error code
  77     CertError(ssl_error_t anErr, X509 *aCert);
  78     CertError(CertError const &err);
  79     CertError & operator = (const CertError &old);
  80     bool operator == (const CertError &ce) const;
  81     bool operator != (const CertError &ce) const;
  82 };
  83
  84 /// Holds a list of certificate SSL errors
  85 typedef CbDataList<Ssl::CertError> CertErrors;
  86
  87 } //namespace Ssl
  88
  89 /// \ingroup ServerProtocolSSLAPI
  90 SSL_CTX *sslCreateServerContext(AnyP::PortCfg &port);
  91
  92 /// \ingroup ServerProtocolSSLAPI
  93 SSL_CTX *sslCreateClientContext(const char *certfile, const char *keyfile, const char *cipher, long options, long flags);
  94
  95 /// \ingroup ServerProtocolSSLAPI
  96 int ssl_read_method(int, char *, int);
  97
  98 /// \ingroup ServerProtocolSSLAPI
  99 int ssl_write_method(int, const char *, int);
 100
 101 /// \ingroup ServerProtocolSSLAPI
 102 void ssl_shutdown_method(SSL *ssl);
 103
 104 /// \ingroup ServerProtocolSSLAPI
 105 const char *sslGetUserEmail(SSL *ssl);
 106
 107 /// \ingroup ServerProtocolSSLAPI
 108 const char *sslGetUserAttribute(SSL *ssl, const char *attribute_name);
 109
 110 /// \ingroup ServerProtocolSSLAPI
 111 const char *sslGetCAAttribute(SSL *ssl, const char *attribute_name);
 112
 113 /// \ingroup ServerProtocolSSLAPI
 114 const char *sslGetUserCertificatePEM(SSL *ssl);
 115
 116 /// \ingroup ServerProtocolSSLAPI
 117 const char *sslGetUserCertificateChainPEM(SSL *ssl);
 118
 119 namespace Ssl
 120 {
 121 /// \ingroup ServerProtocolSSLAPI
 122 typedef char const *GETX509ATTRIBUTE(X509 *, const char *);
 123
 124 /// \ingroup ServerProtocolSSLAPI
 125 GETX509ATTRIBUTE GetX509UserAttribute;
 126
 127 /// \ingroup ServerProtocolSSLAPI
 128 GETX509ATTRIBUTE GetX509CAAttribute;
 129
 130 /// \ingroup ServerProtocolSSLAPI
 131 GETX509ATTRIBUTE GetX509Fingerprint;
 132
 133 extern const EVP_MD *DefaultSignHash;
 134
 135 /**
 136   \ingroup ServerProtocolSSLAPI
 137  * Supported ssl-bump modes
 138  */
 139 enum BumpMode {bumpNone = 0, bumpClientFirst, bumpServerFirst, bumpPeek, bumpStare, bumpBump, bumpSplice, bumpTerminate, /*bumpErr,*/ bumpEnd};
 140
 141 enum BumpStep {bumpStep1, bumpStep2, bumpStep3};
 142
 143 /**
 144  \ingroup  ServerProtocolSSLAPI
 145  * Short names for ssl-bump modes
 146  */
 147 extern const char *BumpModeStr[];
 148
 149 /**
 150  \ingroup ServerProtocolSSLAPI
 151  * Return the short name of the ssl-bump mode "bm"
 152  */
 153 inline const char *bumpMode(int bm)
 154 {
 155     return (0 <= bm && bm < Ssl::bumpEnd) ? Ssl::BumpModeStr[bm] : NULL;
 156 }
 157
 158 /**
 159   \ingroup ServerProtocolSSLAPI
 160   * Generate a certificate to be used as untrusted signing certificate, based on a trusted CA
 161 */
 162 bool generateUntrustedCert(Security::CertPointer & untrustedCert, EVP_PKEY_Pointer & untrustedPkey, Security::CertPointer const & cert, EVP_PKEY_Pointer const & pkey);
 163
 164 /**
 165   \ingroup ServerProtocolSSLAPI
 166   * Decide on the kind of certificate and generate a CA- or self-signed one
 167 */
 168 SSL_CTX * generateSslContext(CertificateProperties const &properties, AnyP::PortCfg &port);
 169
 170 /**
 171   \ingroup ServerProtocolSSLAPI
 172   * Check if the certificate of the given context is still valid
 173   \param sslContext The context to check
 174   \param properties Check if the context certificate matches the given properties
 175   \return true if the contexts certificate is valid, false otherwise
 176  */
 177 bool verifySslCertificate(SSL_CTX * sslContext,  CertificateProperties const &properties);
 178
 179 /**
 180   \ingroup ServerProtocolSSLAPI
 181   * Read private key and certificate from memory and generate SSL context
 182   * using their.
 183  */
 184 SSL_CTX * generateSslContextUsingPkeyAndCertFromMemory(const char * data, AnyP::PortCfg &port);
 185
 186 /**
 187   \ingroup ServerProtocolSSLAPI
 188   * Create an SSL context using the provided certificate and key
 189  */
 190 SSL_CTX * createSSLContext(Security::CertPointer & x509, Ssl::EVP_PKEY_Pointer & pkey, AnyP::PortCfg &port);
 191
 192 /**
 193   \ingroup ServerProtocolSSLAPI
 194   * Generates a certificate and a private key using provided properies and set it
 195   * to SSL object.
 196  */
 197 bool configureSSL(SSL *ssl, CertificateProperties const &properties, AnyP::PortCfg &port);
 198
 199 /**
 200   \ingroup ServerProtocolSSLAPI
 201   * Read private key and certificate from memory and set it to SSL object
 202   * using their.
 203  */
 204 bool configureSSLUsingPkeyAndCertFromMemory(SSL *ssl, const char *data, AnyP::PortCfg &port);
 205
 206 /**
 207   \ingroup ServerProtocolSSLAPI
 208   * Adds the certificates in certList to the certificate chain of the SSL context
 209  */
 210 void addChainToSslContext(SSL_CTX *sslContext, STACK_OF(X509) *certList);
 211
 212 /**
 213  \ingroup ServerProtocolSSLAPI
 214  *  Read certificate, private key and any certificates which must be chained from files.
 215  * See also: Ssl::readCertAndPrivateKeyFromFiles function,  defined in gadgets.h
 216  * \param certFilename name of file with certificate and certificates which must be chainned.
 217  * \param keyFilename name of file with private key.
 218  */
 219 void readCertChainAndPrivateKeyFromFiles(Security::CertPointer & cert, EVP_PKEY_Pointer & pkey, X509_STACK_Pointer & chain, char const * certFilename, char const * keyFilename);
 220
 221 /**
 222    \ingroup ServerProtocolSSLAPI
 223    * Iterates over the X509 common and alternate names and to see if  matches with given data
 224    * using the check_func.
 225    \param peer_cert  The X509 cert to check
 226    \param check_data The data with which the X509 CNs compared
 227    \param check_func The function used to match X509 CNs. The CN data passed as ASN1_STRING data
 228    \return   1 if any of the certificate CN matches, 0 if none matches.
 229  */
 230 int matchX509CommonNames(X509 *peer_cert, void *check_data, int (*check_func)(void *check_data,  ASN1_STRING *cn_data));
 231
 232 /**
 233    \ingroup ServerProtocolSSLAPI
 234    * Check if the certificate is valid for a server
 235    \param cert  The X509 cert to check.
 236    \param server The server name.
 237    \return   true if the certificate is valid for the server or false otherwise.
 238  */
 239 bool checkX509ServerValidity(X509 *cert, const char *server);
 240
 241 /**
 242    \ingroup ServerProtocolSSLAPI
 243    * Convert a given ASN1_TIME to a string form.
 244    \param tm the time in ASN1_TIME form
 245    \param buf the buffer to write the output
 246    \param len write at most len bytes
 247    \return The number of bytes written
 248  */
 249 int asn1timeToString(ASN1_TIME *tm, char *buf, int len);
 250
 251 /**
 252    \ingroup ServerProtocolSSLAPI
 253    * Sets the hostname for the Server Name Indication (SNI) TLS extension
 254    * if supported by the used openssl toolkit.
 255    \return true if SNI set false otherwise
 256 */
 257 bool setClientSNI(SSL *ssl, const char *fqdn);
 258
 259 /**
 260    \ingroup ServerProtocolSSLAPI
 261    * Initializes the shared session cache if configured
 262 */
 263 void initialize_session_cache();
 264
 265 /**
 266    \ingroup ServerProtocolSSLAPI
 267    * Destroy the shared session cache if configured
 268 */
 269 void destruct_session_cache();
 270 } //namespace Ssl
 271
 272 #if _SQUID_WINDOWS_
 273
 274 #if defined(__cplusplus)
 275
 276 /** \cond AUTODOCS-IGNORE */
 277 namespace Squid
 278 {
 279 /** \endcond */
 280
 281 /// \ingroup ServerProtocolSSLAPI
 282 inline
 283 int SSL_set_fd(SSL *ssl, int fd)
 284 {
 285     return ::SSL_set_fd(ssl, _get_osfhandle(fd));
 286 }
 287
 288 /// \ingroup ServerProtocolSSLAPI
 289 #define SSL_set_fd(ssl,fd) Squid::SSL_set_fd(ssl,fd)
 290
 291 } /* namespace Squid */
 292
 293 #else
 294
 295 /// \ingroup ServerProtocolSSLAPI
 296 #define SSL_set_fd(s,f) (SSL_set_fd(s, _get_osfhandle(f)))
 297
 298 #endif /* __cplusplus */
 299
 300 #endif /* _SQUID_WINDOWS_ */
 301
 302 #endif /* SQUID_SSL_SUPPORT_H */
 303