src/ssl/support.h

   1 /*
   2  * Copyright (C) 1996-2014 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 "CbDataList.h"
  15 #include "ssl/gadgets.h"
  16
  17 #if HAVE_OPENSSL_SSL_H
  18 #include <openssl/ssl.h>
  19 #endif
  20 #if HAVE_OPENSSL_X509V3_H
  21 #include <openssl/x509v3.h>
  22 #endif
  23 #if HAVE_OPENSSL_ERR_H
  24 #include <openssl/err.h>
  25 #endif
  26 #if HAVE_OPENSSL_ENGINE_H
  27 #include <openssl/engine.h>
  28 #endif
  29
  30 /**
  31  \defgroup ServerProtocolSSLAPI Server-Side SSL API
  32  \ingroup ServerProtocol
  33  */
  34
  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
  43
  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
  50 #endif
  51
  52 namespace AnyP
  53 {
  54 class PortCfg;
  55 };
  56
  57 namespace Ssl
  58 {
  59 /// Squid defined error code (<0),  an error code returned by SSL X509 api, or SSL_ERROR_NONE
  60 typedef int ssl_error_t;
  61
  62 typedef CbDataList<Ssl::ssl_error_t> Errors;
  63
  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);
  67
  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);
  71
  72 /// An SSL certificate-related error.
  73 /// Pairs an error code with the certificate experiencing the error.
  74 class CertError
  75 {
  76 public:
  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;
  84 };
  85
  86 /// Holds a list of certificate SSL errors
  87 typedef CbDataList<Ssl::CertError> CertErrors;
  88
  89 } //namespace Ssl
  90
  91 /// \ingroup ServerProtocolSSLAPI
  92 SSL_CTX *sslCreateServerContext(AnyP::PortCfg &port);
  93
  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);
  96
  97 /// \ingroup ServerProtocolSSLAPI
  98 int ssl_read_method(int, char *, int);
  99
 100 /// \ingroup ServerProtocolSSLAPI
 101 int ssl_write_method(int, const char *, int);
 102
 103 /// \ingroup ServerProtocolSSLAPI
 104 void ssl_shutdown_method(SSL *ssl);
 105
 106 /// \ingroup ServerProtocolSSLAPI
 107 const char *sslGetUserEmail(SSL *ssl);
 108
 109 /// \ingroup ServerProtocolSSLAPI
 110 const char *sslGetUserAttribute(SSL *ssl, const char *attribute_name);
 111
 112 /// \ingroup ServerProtocolSSLAPI
 113 const char *sslGetCAAttribute(SSL *ssl, const char *attribute_name);
 114
 115 /// \ingroup ServerProtocolSSLAPI
 116 const char *sslGetUserCertificatePEM(SSL *ssl);
 117
 118 /// \ingroup ServerProtocolSSLAPI
 119 const char *sslGetUserCertificateChainPEM(SSL *ssl);
 120
 121 namespace Ssl
 122 {
 123 /// \ingroup ServerProtocolSSLAPI
 124 typedef char const *GETX509ATTRIBUTE(X509 *, const char *);
 125
 126 /// \ingroup ServerProtocolSSLAPI
 127 GETX509ATTRIBUTE GetX509UserAttribute;
 128
 129 /// \ingroup ServerProtocolSSLAPI
 130 GETX509ATTRIBUTE GetX509CAAttribute;
 131
 132 /// \ingroup ServerProtocolSSLAPI
 133 GETX509ATTRIBUTE GetX509Fingerprint;
 134
 135 extern const EVP_MD *DefaultSignHash;
 136
 137 /**
 138   \ingroup ServerProtocolSSLAPI
 139  * Supported ssl-bump modes
 140  */
 141 enum BumpMode {bumpNone = 0, bumpClientFirst, bumpServerFirst, bumpPeek, bumpStare, bumpBump, bumpSplice, bumpTerminate, /*bumpErr,*/ bumpEnd};
 142
 143 enum BumpStep {bumpStep1, bumpStep2, bumpStep3};
 144
 145 /**
 146  \ingroup  ServerProtocolSSLAPI
 147  * Short names for ssl-bump modes
 148  */
 149 extern const char *BumpModeStr[];
 150
 151 /**
 152  \ingroup ServerProtocolSSLAPI
 153  * Return the short name of the ssl-bump mode "bm"
 154  */
 155 inline const char *bumpMode(int bm)
 156 {
 157     return (0 <= bm && bm < Ssl::bumpEnd) ? Ssl::BumpModeStr[bm] : NULL;
 158 }
 159
 160 /**
 161  \ingroup ServerProtocolSSLAPI
 162  * Parses the SSL flags.
 163  */
 164 long parse_flags(const char *flags);
 165
 166 /**
 167  \ingroup ServerProtocolSSLAPI
 168  * Parses the SSL options.
 169  */
 170 long parse_options(const char *options);
 171
 172 /**
 173  \ingroup ServerProtocolSSLAPI
 174  * Load a CRLs list stored in a file
 175  */
 176 STACK_OF(X509_CRL) *loadCrl(const char *CRLFile, long &flags);
 177
 178 /**
 179  \ingroup ServerProtocolSSLAPI
 180  * Load DH params from file
 181  */
 182 DH *readDHParams(const char *dhfile);
 183
 184 /**
 185  \ingroup ServerProtocolSSLAPI
 186  * Compute the Ssl::ContextMethod (SSL_METHOD) from SSL version
 187  */
 188 ContextMethod contextMethod(int version);
 189
 190 /**
 191   \ingroup ServerProtocolSSLAPI
 192   * Generate a certificate to be used as untrusted signing certificate, based on a trusted CA
 193 */
 194 bool generateUntrustedCert(X509_Pointer & untrustedCert, EVP_PKEY_Pointer & untrustedPkey, X509_Pointer const & cert, EVP_PKEY_Pointer const & pkey);
 195
 196 /**
 197   \ingroup ServerProtocolSSLAPI
 198   * Decide on the kind of certificate and generate a CA- or self-signed one
 199 */
 200 SSL_CTX * generateSslContext(CertificateProperties const &properties, AnyP::PortCfg &port);
 201
 202 /**
 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
 208  */
 209 bool verifySslCertificate(SSL_CTX * sslContext,  CertificateProperties const &properties);
 210
 211 /**
 212   \ingroup ServerProtocolSSLAPI
 213   * Read private key and certificate from memory and generate SSL context
 214   * using their.
 215  */
 216 SSL_CTX * generateSslContextUsingPkeyAndCertFromMemory(const char * data, AnyP::PortCfg &port);
 217
 218 /**
 219   \ingroup ServerProtocolSSLAPI
 220   * Create an SSL context using the provided certificate and key
 221  */
 222 SSL_CTX * createSSLContext(Ssl::X509_Pointer & x509, Ssl::EVP_PKEY_Pointer & pkey, AnyP::PortCfg &port);
 223
 224 /**
 225   \ingroup ServerProtocolSSLAPI
 226   * Generates a certificate and a private key using provided properies and set it
 227   * to SSL object.
 228  */
 229 bool configureSSL(SSL *ssl, CertificateProperties const &properties, AnyP::PortCfg &port);
 230
 231 /**
 232   \ingroup ServerProtocolSSLAPI
 233   * Read private key and certificate from memory and set it to SSL object
 234   * using their.
 235  */
 236 bool configureSSLUsingPkeyAndCertFromMemory(SSL *ssl, const char *data, AnyP::PortCfg &port);
 237
 238 /**
 239   \ingroup ServerProtocolSSLAPI
 240   * Adds the certificates in certList to the certificate chain of the SSL context
 241  */
 242 void addChainToSslContext(SSL_CTX *sslContext, STACK_OF(X509) *certList);
 243
 244 /**
 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.
 250  */
 251 void readCertChainAndPrivateKeyFromFiles(X509_Pointer & cert, EVP_PKEY_Pointer & pkey, X509_STACK_Pointer & chain, char const * certFilename, char const * keyFilename);
 252
 253 /**
 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.
 261  */
 262 int matchX509CommonNames(X509 *peer_cert, void *check_data, int (*check_func)(void *check_data,  ASN1_STRING *cn_data));
 263
 264 /**
 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.
 270  */
 271 bool checkX509ServerValidity(X509 *cert, const char *server);
 272
 273 /**
 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
 280  */
 281 int asn1timeToString(ASN1_TIME *tm, char *buf, int len);
 282
 283 /**
 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
 288 */
 289 bool setClientSNI(SSL *ssl, const char *fqdn);
 290
 291 int OpenSSLtoSquidSSLVersion(int sslVersion);
 292
 293 #if OPENSSL_VERSION_NUMBER < 0x00909000L
 294 SSL_METHOD *method(int version);
 295 #else
 296 const SSL_METHOD *method(int version);
 297 #endif
 298
 299 const SSL_METHOD *serverMethod(int version);
 300
 301 /**
 302    \ingroup ServerProtocolSSLAPI
 303    * Initializes the shared session cache if configured
 304 */
 305 void initialize_session_cache();
 306
 307 /**
 308    \ingroup ServerProtocolSSLAPI
 309    * Destroy the shared session cache if configured
 310 */
 311 void destruct_session_cache();
 312 } //namespace Ssl
 313
 314 #if _SQUID_WINDOWS_
 315
 316 #if defined(__cplusplus)
 317
 318 /** \cond AUTODOCS-IGNORE */
 319 namespace Squid
 320 {
 321 /** \endcond */
 322
 323 /// \ingroup ServerProtocolSSLAPI
 324 inline
 325 int SSL_set_fd(SSL *ssl, int fd)
 326 {
 327     return ::SSL_set_fd(ssl, _get_osfhandle(fd));
 328 }
 329
 330 /// \ingroup ServerProtocolSSLAPI
 331 #define SSL_set_fd(ssl,fd) Squid::SSL_set_fd(ssl,fd)
 332
 333 } /* namespace Squid */
 334
 335 #else
 336
 337 /// \ingroup ServerProtocolSSLAPI
 338 #define SSL_set_fd(s,f) (SSL_set_fd(s, _get_osfhandle(f)))
 339
 340 #endif /* __cplusplus */
 341
 342 #endif /* _SQUID_WINDOWS_ */
 343
 344 #endif /* SQUID_SSL_SUPPORT_H */