src/ssl/PeerConnector.h

   1 /*
   2  * SQUID Web Proxy Cache          http://www.squid-cache.org/
   3  * ----------------------------------------------------------
   4  *
   5  *  Squid is the result of efforts by numerous individuals from
   6  *  the Internet community; see the CONTRIBUTORS file for full
   7  *  details.   Many organizations have provided support for Squid's
   8  *  development; see the SPONSORS file for full details.  Squid is
   9  *  Copyrighted (C) 2001 by the Regents of the University of
  10  *  California; see the COPYRIGHT file for full details.  Squid
  11  *  incorporates software developed and/or copyrighted by other
  12  *  sources; see the CREDITS file for full details.
  13  *
  14  *  This program is free software; you can redistribute it and/or modify
  15  *  it under the terms of the GNU General Public License as published by
  16  *  the Free Software Foundation; either version 2 of the License, or
  17  *  (at your option) any later version.
  18  *
  19  *  This program is distributed in the hope that it will be useful,
  20  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
  21  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  22  *  GNU General Public License for more details.
  23  *
  24  *  You should have received a copy of the GNU General Public License
  25  *  along with this program; if not, write to the Free Software
  26  *  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, USA.
  27  *
  28  */
  29 #ifndef SQUID_SSL_PEER_CONNECTOR_H
  30 #define SQUID_SSL_PEER_CONNECTOR_H
  31
  32 #include "base/AsyncJob.h"
  33 #include "base/AsyncCbdataCalls.h"
  34 #include "ssl/support.h"
  35 #include <iosfwd>
  36
  37 class HttpRequest;
  38 class ErrorState;
  39
  40 namespace Ssl {
  41
  42 class ErrorDetail;
  43 class CertValidationResponse;
  44
  45 /// PeerConnector results (supplied via a callback).
  46 /// The connection to peer was secured if and only if the error member is nil.
  47 class PeerConnectorAnswer {
  48 public:
  49     ~PeerConnectorAnswer(); ///< deletes error if it is still set
  50     Comm::ConnectionPointer conn; ///< peer connection (secured on success)
  51
  52     /// answer recepients must clear the error member in order to keep its info
  53     /// XXX: We should refcount ErrorState instead of cbdata-protecting it.
  54     CbcPointer<ErrorState> error; ///< problem details (nil on success)
  55 };
  56
  57 /**
  58  \par
  59  * Connects Squid client-side to an SSL peer (cache_peer ... ssl).
  60  * Handles peer certificate validation.
  61  * Used by TunnelStateData, FwdState, and PeerPoolMgr to start talking to an
  62  * SSL peer.
  63  \par
  64  * The caller receives a call back with PeerConnectorAnswer. If answer.error
  65  * is not nil, then there was an error and the SSL connection to the SSL peer
  66  * was not fully established. The error object is suitable for error response
  67  * generation.
  68  \par
  69  * The caller must monitor the connection for closure because this
  70  * job will not inform the caller about such events.
  71  \par
  72  * The caller must monitor the overall connection establishment timeout and
  73  * close the connection on timeouts. This is probably better than having
  74  * dedicated (or none at all!) timeouts for peer selection, DNS lookup,
  75  * TCP handshake, SSL handshake, etc. Some steps may have their own timeout,
  76  * but not all steps should be forced to have theirs. XXX: Neither tunnel.cc
  77  * nor forward.cc have a "overall connection establishment" timeout. We need
  78  * to change their code so that they start monitoring earlier and close on
  79  * timeouts. This change may need to be discussed on squid-dev.
  80  \par
  81  * This job never closes the connection, even on errors. If a 3rd-party
  82  * closes the connection, this job simply quits without informing the caller.
  83 */
  84 class PeerConnector: virtual public AsyncJob
  85 {
  86 public:
  87     /// Callback dialier API to allow PeerConnector to set the answer.
  88     class CbDialer {
  89     public:
  90         virtual ~CbDialer() {}
  91         /// gives PeerConnector access to the in-dialer answer
  92         virtual PeerConnectorAnswer &answer() = 0;
  93     };
  94
  95     typedef RefCount<HttpRequest> HttpRequestPointer;
  96
  97 public:
  98     PeerConnector(HttpRequestPointer &aRequest,
  99                   const Comm::ConnectionPointer &aServerConn,
 100                   AsyncCall::Pointer &aCallback);
 101     virtual ~PeerConnector();
 102
 103 protected:
 104     // AsyncJob API
 105     virtual void start();
 106     virtual bool doneAll() const;
 107     virtual void swanSong();
 108     virtual const char *status() const;
 109
 110     /// The comm_close callback handler.
 111     void commCloseHandler(const CommCloseCbParams &params);
 112
 113     /// Inform us that the connection is closed. Does the required clean-up.
 114     void connectionClosed(const char *reason);
 115
 116     /// Sets up TCP socket-related notification callbacks if things go wrong.
 117     /// If socket already closed return false, else install the comm_close
 118     /// handler to monitor the socket.
 119     bool prepareSocket();
 120
 121     void initializeSsl(); ///< Initializes SSL state
 122
 123     /// Performs a single secure connection negotiation step.
 124     /// It is called multiple times untill the negotiation finish or aborted.
 125     void negotiateSsl();
 126
 127     void checkForPeekAndSplice();
 128
 129     /// Called when the SSL negotiation step aborted because data needs to
 130     /// be transferred to/from SSL server or on error. In the first case
 131     /// setups the appropriate Comm::SetSelect handler. In second case
 132     /// fill an error and report to the PeerConnector caller.
 133     void handleNegotiateError(const int result);
 134
 135 private:
 136     PeerConnector(const PeerConnector &); // not implemented
 137     PeerConnector &operator =(const PeerConnector &); // not implemented
 138
 139     /// mimics FwdState to minimize changes to FwdState::initiate/negotiateSsl
 140     Comm::ConnectionPointer const &serverConnection() const { return serverConn; }
 141
 142     void bail(ErrorState *error); ///< Return an error to the PeerConnector caller
 143
 144     /// Callback the caller class, and pass the ready to communicate secure
 145     /// connection or an error if PeerConnector failed.
 146     void callBack();
 147
 148     /// Process response from cert validator helper
 149     void sslCrtvdHandleReply(Ssl::CertValidationResponse const &);
 150
 151     /// Check SSL errors returned from cert validator against sslproxy_cert_error access list
 152     Ssl::CertErrors *sslCrtvdCheckForErrors(Ssl::CertValidationResponse const &, Ssl::ErrorDetail *&);
 153
 154     /// Callback function called when squid receive message from cert validator helper
 155     static void sslCrtvdHandleReplyWrapper(void *data, Ssl::CertValidationResponse const &);
 156
 157     /// A wrapper function for negotiateSsl for use with Comm::SetSelect
 158     static void NegotiateSsl(int fd, void *data);
 159
 160     HttpRequestPointer request; ///< peer connection trigger or cause
 161     Comm::ConnectionPointer serverConn; ///< TCP connection to the peer
 162     AsyncCall::Pointer callback; ///< we call this with the results
 163     AsyncCall::Pointer closeHandler; ///< we call this when the connection closed
 164
 165     CBDATA_CLASS2(PeerConnector);
 166 };
 167
 168 } // namespace Ssl
 169
 170 std::ostream &operator <<(std::ostream &os, const Ssl::PeerConnectorAnswer &a);
 171
 172 #endif /* SQUID_PEER_CONNECTOR_H */