src/ssl/support.h

   1
   2 /*
   3  * AUTHOR: Benno Rice
   4  *
   5  * SQUID Internet Object Cache  http://squid.nlanr.net/Squid/
   6  * ----------------------------------------------------------
   7  *
   8  *  Squid is the result of efforts by numerous individuals from the
   9  *  Internet community.  Development is led by Duane Wessels of the
  10  *  National Laboratory for Applied Network Research and funded by the
  11  *  National Science Foundation.  Squid is Copyrighted (C) 1998 by
  12  *  Duane Wessels and the University of California San Diego.  Please
  13  *  see the COPYRIGHT file for full details.  Squid incorporates
  14  *  software developed and/or copyrighted by other sources.  Please see
  15  *  the CREDITS file for full details.
  16  *
  17  *  This program is free software; you can redistribute it and/or modify
  18  *  it under the terms of the GNU General Public License as published by
  19  *  the Free Software Foundation; either version 2 of the License, or
  20  *  (at your option) any later version.
  21  *
  22  *  This program is distributed in the hope that it will be useful,
  23  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
  24  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  25  *  GNU General Public License for more details.
  26  *
  27  *  You should have received a copy of the GNU General Public License
  28  *  along with this program; if not, write to the Free Software
  29  *  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, USA.
  30  *
  31  */
  32
  33 #ifndef SQUID_SSL_SUPPORT_H
  34 #define SQUID_SSL_SUPPORT_H
  35
  36 #include "CbDataList.h"
  37 #include "ssl/gadgets.h"
  38
  39 #if HAVE_OPENSSL_SSL_H
  40 #include <openssl/ssl.h>
  41 #endif
  42 #if HAVE_OPENSSL_X509V3_H
  43 #include <openssl/x509v3.h>
  44 #endif
  45 #if HAVE_OPENSSL_ERR_H
  46 #include <openssl/err.h>
  47 #endif
  48 #if HAVE_OPENSSL_ENGINE_H
  49 #include <openssl/engine.h>
  50 #endif
  51
  52 /**
  53  \defgroup ServerProtocolSSLAPI Server-Side SSL API
  54  \ingroup ServerProtocol
  55  */
  56
  57 // Custom SSL errors; assumes all official errors are positive
  58 #define SQUID_X509_V_ERR_INFINITE_VALIDATION -4
  59 #define SQUID_X509_V_ERR_CERT_CHANGE -3
  60 #define SQUID_ERR_SSL_HANDSHAKE -2
  61 #define SQUID_X509_V_ERR_DOMAIN_MISMATCH -1
  62 // All SSL errors range: from smallest (negative) custom to largest SSL error
  63 #define SQUID_SSL_ERROR_MIN SQUID_X509_V_ERR_CERT_CHANGE
  64 #define SQUID_SSL_ERROR_MAX INT_MAX
  65
  66 // Maximum certificate validation callbacks. OpenSSL versions exceeding this
  67 // limit are deemed stuck in an infinite validation loop (OpenSSL bug #3090)
  68 // and will trigger the SQUID_X509_V_ERR_INFINITE_VALIDATION error.
  69 // Can be set to a number up to UINT32_MAX
  70 #ifndef SQUID_CERT_VALIDATION_ITERATION_MAX
  71 #define SQUID_CERT_VALIDATION_ITERATION_MAX 16384
  72 #endif
  73
  74 namespace AnyP
  75 {
  76 class PortCfg;
  77 };
  78
  79 namespace Ssl
  80 {
  81 /// Squid defined error code (<0),  an error code returned by SSL X509 api, or SSL_ERROR_NONE
  82 typedef int ssl_error_t;
  83
  84 typedef CbDataList<Ssl::ssl_error_t> Errors;
  85
  86 /// Creates SSL Client connection structure and initializes SSL I/O (Comm and BIO).
  87 /// On errors, emits DBG_IMPORTANT with details and returns NULL.
  88 SSL *CreateClient(SSL_CTX *sslContext, const int fd, const char *squidCtx);
  89
  90 /// Creates SSL Server connection structure and initializes SSL I/O (Comm and BIO).
  91 /// On errors, emits DBG_IMPORTANT with details and returns NULL.
  92 SSL *CreateServer(SSL_CTX *sslContext, const int fd, const char *squidCtx);
  93
  94 /// An SSL certificate-related error.
  95 /// Pairs an error code with the certificate experiencing the error.
  96 class CertError
  97 {
  98 public:
  99     ssl_error_t code; ///< certificate error code
 100     X509_Pointer cert; ///< certificate with the above error code
 101     CertError(ssl_error_t anErr, X509 *aCert);
 102     CertError(CertError const &err);
 103     CertError & operator = (const CertError &old);
 104     bool operator == (const CertError &ce) const;
 105     bool operator != (const CertError &ce) const;
 106 };
 107
 108 /// Holds a list of certificate SSL errors
 109 typedef CbDataList<Ssl::CertError> CertErrors;
 110
 111 } //namespace Ssl
 112
 113 /// \ingroup ServerProtocolSSLAPI
 114 SSL_CTX *sslCreateServerContext(AnyP::PortCfg &port);
 115
 116 /// \ingroup ServerProtocolSSLAPI
 117 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);
 118
 119 /// \ingroup ServerProtocolSSLAPI
 120 int ssl_read_method(int, char *, int);
 121
 122 /// \ingroup ServerProtocolSSLAPI
 123 int ssl_write_method(int, const char *, int);
 124
 125 /// \ingroup ServerProtocolSSLAPI
 126 void ssl_shutdown_method(SSL *ssl);
 127
 128 /// \ingroup ServerProtocolSSLAPI
 129 const char *sslGetUserEmail(SSL *ssl);
 130
 131 /// \ingroup ServerProtocolSSLAPI
 132 const char *sslGetUserAttribute(SSL *ssl, const char *attribute_name);
 133
 134 /// \ingroup ServerProtocolSSLAPI
 135 const char *sslGetCAAttribute(SSL *ssl, const char *attribute_name);
 136
 137 /// \ingroup ServerProtocolSSLAPI
 138 const char *sslGetUserCertificatePEM(SSL *ssl);
 139
 140 /// \ingroup ServerProtocolSSLAPI
 141 const char *sslGetUserCertificateChainPEM(SSL *ssl);
 142
 143 namespace Ssl
 144 {
 145 /// \ingroup ServerProtocolSSLAPI
 146 typedef char const *GETX509ATTRIBUTE(X509 *, const char *);
 147
 148 /// \ingroup ServerProtocolSSLAPI
 149 GETX509ATTRIBUTE GetX509UserAttribute;
 150
 151 /// \ingroup ServerProtocolSSLAPI
 152 GETX509ATTRIBUTE GetX509CAAttribute;
 153
 154 /// \ingroup ServerProtocolSSLAPI
 155 GETX509ATTRIBUTE GetX509Fingerprint;
 156
 157 /**
 158   \ingroup ServerProtocolSSLAPI
 159  * Supported ssl-bump modes
 160  */
 161 enum BumpMode {bumpNone = 0, bumpClientFirst, bumpServerFirst, bumpPeek, bumpStare, bumpBump, bumpSplice, bumpTerminate, bumpErr, bumpEnd};
 162
 163 enum BumpStep {bumpStep1, bumpStep2, bumpStep3};
 164
 165 /**
 166  \ingroup  ServerProtocolSSLAPI
 167  * Short names for ssl-bump modes
 168  */
 169 extern const char *BumpModeStr[];
 170
 171 /**
 172  \ingroup ServerProtocolSSLAPI
 173  * Return the short name of the ssl-bump mode "bm"
 174  */
 175 inline const char *bumpMode(int bm)
 176 {
 177     return (0 <= bm && bm < Ssl::bumpEnd) ? Ssl::BumpModeStr[bm] : NULL;
 178 }
 179
 180 /**
 181  \ingroup ServerProtocolSSLAPI
 182  * Parses the SSL flags.
 183  */
 184 long parse_flags(const char *flags);
 185
 186 /**
 187  \ingroup ServerProtocolSSLAPI
 188  * Parses the SSL options.
 189  */
 190 long parse_options(const char *options);
 191
 192 /**
 193  \ingroup ServerProtocolSSLAPI
 194  * Load a CRLs list stored in a file
 195  */
 196 STACK_OF(X509_CRL) *loadCrl(const char *CRLFile, long &flags);
 197
 198 /**
 199  \ingroup ServerProtocolSSLAPI
 200  * Load DH params from file
 201  */
 202 DH *readDHParams(const char *dhfile);
 203
 204 /**
 205  \ingroup ServerProtocolSSLAPI
 206  * Compute the Ssl::ContextMethod (SSL_METHOD) from SSL version
 207  */
 208 ContextMethod contextMethod(int version);
 209
 210 /**
 211   \ingroup ServerProtocolSSLAPI
 212   * Generate a certificate to be used as untrusted signing certificate, based on a trusted CA
 213 */
 214 bool generateUntrustedCert(X509_Pointer & untrustedCert, EVP_PKEY_Pointer & untrustedPkey, X509_Pointer const & cert, EVP_PKEY_Pointer const & pkey);
 215
 216 /**
 217   \ingroup ServerProtocolSSLAPI
 218   * Decide on the kind of certificate and generate a CA- or self-signed one
 219 */
 220 SSL_CTX * generateSslContext(CertificateProperties const &properties, AnyP::PortCfg &port);
 221
 222 /**
 223   \ingroup ServerProtocolSSLAPI
 224   * Check if the certificate of the given context is still valid
 225   \param sslContext The context to check
 226   \param properties Check if the context certificate matches the given properties
 227   \return true if the contexts certificate is valid, false otherwise
 228  */
 229 bool verifySslCertificate(SSL_CTX * sslContext,  CertificateProperties const &properties);
 230
 231 /**
 232   \ingroup ServerProtocolSSLAPI
 233   * Read private key and certificate from memory and generate SSL context
 234   * using their.
 235  */
 236 SSL_CTX * generateSslContextUsingPkeyAndCertFromMemory(const char * data, AnyP::PortCfg &port);
 237
 238 /**
 239   \ingroup ServerProtocolSSLAPI
 240   * Create an SSL context using the provided certificate and key
 241  */
 242 SSL_CTX * createSSLContext(Ssl::X509_Pointer & x509, Ssl::EVP_PKEY_Pointer & pkey, AnyP::PortCfg &port);
 243
 244 /**
 245   \ingroup ServerProtocolSSLAPI
 246   * Generates a certificate and a private key using provided properies and set it
 247   * to SSL object.
 248  */
 249 bool configureSSL(SSL *ssl, CertificateProperties const &properties, AnyP::PortCfg &port);
 250
 251 /**
 252   \ingroup ServerProtocolSSLAPI
 253   * Read private key and certificate from memory and set it to SSL object
 254   * using their.
 255  */
 256 bool configureSSLUsingPkeyAndCertFromMemory(SSL *ssl, const char *data, AnyP::PortCfg &port);
 257
 258
 259 /**
 260   \ingroup ServerProtocolSSLAPI
 261   * Adds the certificates in certList to the certificate chain of the SSL context
 262  */
 263 void addChainToSslContext(SSL_CTX *sslContext, STACK_OF(X509) *certList);
 264
 265 /**
 266  \ingroup ServerProtocolSSLAPI
 267  *  Read certificate, private key and any certificates which must be chained from files.
 268  * See also: Ssl::readCertAndPrivateKeyFromFiles function,  defined in gadgets.h
 269  * \param certFilename name of file with certificate and certificates which must be chainned.
 270  * \param keyFilename name of file with private key.
 271  */
 272 void readCertChainAndPrivateKeyFromFiles(X509_Pointer & cert, EVP_PKEY_Pointer & pkey, X509_STACK_Pointer & chain, char const * certFilename, char const * keyFilename);
 273
 274 /**
 275    \ingroup ServerProtocolSSLAPI
 276    * Iterates over the X509 common and alternate names and to see if  matches with given data
 277    * using the check_func.
 278    \param peer_cert  The X509 cert to check
 279    \param check_data The data with which the X509 CNs compared
 280    \param check_func The function used to match X509 CNs. The CN data passed as ASN1_STRING data
 281    \return   1 if any of the certificate CN matches, 0 if none matches.
 282  */
 283 int matchX509CommonNames(X509 *peer_cert, void *check_data, int (*check_func)(void *check_data,  ASN1_STRING *cn_data));
 284
 285 /**
 286    \ingroup ServerProtocolSSLAPI
 287    * Check if the certificate is valid for a server
 288    \param cert  The X509 cert to check.
 289    \param server The server name.
 290    \return   true if the certificate is valid for the server or false otherwise.
 291  */
 292 bool checkX509ServerValidity(X509 *cert, const char *server);
 293
 294 /**
 295    \ingroup ServerProtocolSSLAPI
 296    * Convert a given ASN1_TIME to a string form.
 297    \param tm the time in ASN1_TIME form
 298    \param buf the buffer to write the output
 299    \param len write at most len bytes
 300    \return The number of bytes written
 301  */
 302 int asn1timeToString(ASN1_TIME *tm, char *buf, int len);
 303
 304 /**
 305    \ingroup ServerProtocolSSLAPI
 306    * Sets the hostname for the Server Name Indication (SNI) TLS extension
 307    * if supported by the used openssl toolkit.
 308    \return true if SNI set false otherwise
 309 */
 310 bool setClientSNI(SSL *ssl, const char *fqdn);
 311
 312 int OpenSSLtoSquidSSLVersion(int sslVersion);
 313
 314 #if OPENSSL_VERSION_NUMBER < 0x00909000L
 315 SSL_METHOD *method(int version);
 316 #else
 317 const SSL_METHOD *method(int version);
 318 #endif
 319
 320 const SSL_METHOD *serverMethod(int version);
 321
 322 /**
 323    \ingroup ServerProtocolSSLAPI
 324    * Initializes the shared session cache if configured
 325 */
 326 void initialize_session_cache();
 327
 328 /**
 329    \ingroup ServerProtocolSSLAPI
 330    * Destroy the shared session cache if configured
 331 */
 332 void destruct_session_cache();
 333 } //namespace Ssl
 334
 335 #if _SQUID_WINDOWS_
 336
 337 #if defined(__cplusplus)
 338
 339 /** \cond AUTODOCS-IGNORE */
 340 namespace Squid
 341 {
 342 /** \endcond */
 343
 344 /// \ingroup ServerProtocolSSLAPI
 345 inline
 346 int SSL_set_fd(SSL *ssl, int fd)
 347 {
 348     return ::SSL_set_fd(ssl, _get_osfhandle(fd));
 349 }
 350
 351 /// \ingroup ServerProtocolSSLAPI
 352 #define SSL_set_fd(ssl,fd) Squid::SSL_set_fd(ssl,fd)
 353
 354 } /* namespace Squid */
 355
 356 #else
 357
 358 /// \ingroup ServerProtocolSSLAPI
 359 #define SSL_set_fd(s,f) (SSL_set_fd(s, _get_osfhandle(f)))
 360
 361 #endif /* __cplusplus */
 362
 363 #endif /* _SQUID_WINDOWS_ */
 364
 365 #endif /* SQUID_SSL_SUPPORT_H */