src/clients/FtpClient.h

   1 /*
   2  * Copyright (C) 1996-2025 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 09    File Transfer Protocol (FTP) */
  10
  11 #ifndef SQUID_SRC_CLIENTS_FTPCLIENT_H
  12 #define SQUID_SRC_CLIENTS_FTPCLIENT_H
  13
  14 #include "clients/Client.h"
  15 #include "error/Detail.h"
  16
  17 class String;
  18 namespace Ftp
  19 {
  20
  21 extern const char *const crlf;
  22
  23 /// Holds FTP server reply error code
  24 /// Squid needs to interpret internally FTP reply codes and respond with
  25 /// custom error (eg in the case of Ftp::Gateway), however still we need
  26 /// to log the exact FTP server error reply code as the reason of error.
  27 class ErrorDetail: public ::ErrorDetail {
  28     MEMPROXY_CLASS(Ftp::ErrorDetail);
  29
  30 public:
  31     explicit ErrorDetail(const int code): completionCode(code) {}
  32
  33     /* ErrorDetail API */
  34     SBuf brief() const override;
  35     SBuf verbose(const HttpRequestPointer &) const override;
  36
  37 private:
  38     int completionCode; ///< FTP reply completion code
  39 };
  40
  41 /// Common code for FTP server control and data channels.
  42 /// Does not own the channel descriptor, which is managed by Ftp::Client.
  43 class Channel
  44 {
  45 public:
  46     /// called after the socket is opened, sets up close handler
  47     void opened(const Comm::ConnectionPointer &conn, const AsyncCall::Pointer &aCloser);
  48
  49     /** Handles all operations needed to properly close the active channel FD.
  50      * clearing the close handler, clearing the listen socket properly, and calling comm_close
  51      */
  52     void close();
  53
  54     void forget(); /// remove the close handler, leave connection open
  55
  56     void clear(); ///< just drops conn and close handler. does not close active connections.
  57
  58     Comm::ConnectionPointer conn; ///< channel descriptor
  59
  60     /** A temporary handle to the connection being listened on.
  61      * Closing this will also close the waiting Data channel acceptor.
  62      * If a data connection has already been accepted but is still waiting in the event queue
  63      * the callback will still happen and needs to be handled (usually dropped).
  64      */
  65     Comm::ConnectionPointer listenConn;
  66
  67 private:
  68     AsyncCall::Pointer closer; ///< Comm close handler callback
  69 };
  70
  71 /// FTP channel for control commands.
  72 /// This channel is opened once per transaction.
  73 class CtrlChannel: public Ftp::Channel
  74 {
  75 public:
  76     CtrlChannel();
  77     ~CtrlChannel();
  78
  79     char *buf;
  80     size_t size;
  81     size_t offset;
  82     wordlist *message;
  83     char *last_command;
  84     char *last_reply;
  85     int replycode;
  86
  87 private:
  88     CtrlChannel(const CtrlChannel &); // not implemented
  89     CtrlChannel &operator =(const CtrlChannel &); // not implemented
  90 };
  91
  92 /// FTP channel for data exchanges.
  93 /// This channel may be opened/closed a few times.
  94 class DataChannel: public Ftp::Channel
  95 {
  96 public:
  97     DataChannel();
  98     ~DataChannel();
  99
 100     void addr(const Ip::Address &addr); ///< import host and port
 101
 102 public:
 103     MemBuf *readBuf;
 104     char *host;
 105     unsigned short port;
 106     bool read_pending;
 107 };
 108
 109 /// FTP client functionality shared among FTP Gateway and Relay clients.
 110 class Client: public ::Client
 111 {
 112     CBDATA_INTERMEDIATE();
 113
 114 public:
 115     explicit Client(FwdState *fwdState);
 116     ~Client() override;
 117
 118     /// handle a fatal transaction error, closing the control connection
 119     virtual void failed(err_type error = ERR_NONE, int xerrno = 0,
 120                         ErrorState *ftperr = nullptr);
 121
 122     /// read timeout handler
 123     virtual void timeout(const CommTimeoutCbParams &io);
 124
 125     /* Client API */
 126     void maybeReadVirginBody() override;
 127
 128     void writeCommand(const char *buf);
 129
 130     /// extracts remoteAddr from PASV response, validates it,
 131     /// sets data address details, and returns true on success
 132     bool handlePasvReply(Ip::Address &remoteAddr);
 133     bool handleEpsvReply(Ip::Address &remoteAddr);
 134
 135     bool sendEprt();
 136     bool sendPort();
 137     bool sendPassive();
 138     void connectDataChannel();
 139     bool openListenSocket();
 140     void switchTimeoutToDataChannel();
 141
 142     CtrlChannel ctrl; ///< FTP control channel state
 143     DataChannel data; ///< FTP data channel state
 144
 145     enum {
 146         BEGIN,
 147         SENT_USER,
 148         SENT_PASS,
 149         SENT_TYPE,
 150         SENT_MDTM,
 151         SENT_SIZE,
 152         SENT_EPRT,
 153         SENT_PORT,
 154         SENT_EPSV_ALL,
 155         SENT_EPSV_1,
 156         SENT_EPSV_2,
 157         SENT_PASV,
 158         SENT_CWD,
 159         SENT_LIST,
 160         SENT_NLST,
 161         SENT_REST,
 162         SENT_RETR,
 163         SENT_STOR,
 164         SENT_QUIT,
 165         READING_DATA,
 166         WRITING_DATA,
 167         SENT_MKDIR,
 168         SENT_FEAT,
 169         SENT_PWD,
 170         SENT_CDUP,
 171         SENT_DATA_REQUEST, // LIST, NLST or RETR requests..
 172         SENT_COMMAND, // General command
 173         END
 174     } ftp_state_t;
 175
 176     int state;
 177     char *old_request;
 178     char *old_reply;
 179
 180 protected:
 181     /* AsyncJob API */
 182     void start() override;
 183
 184     /* Client API */
 185     void closeServer() override;
 186     bool doneWithServer() const override;
 187     const Comm::ConnectionPointer & dataConnection() const override;
 188     void abortAll(const char *reason) override;
 189     void noteDelayAwareReadChance() override;
 190
 191     virtual Http::StatusCode failedHttpStatus(err_type &error);
 192     void ctrlClosed(const CommCloseCbParams &io);
 193     void scheduleReadControlReply(int buffered_ok);
 194     void readControlReply(const CommIoCbParams &io);
 195     virtual void handleControlReply();
 196     void writeCommandCallback(const CommIoCbParams &io);
 197     virtual void dataChannelConnected(const CommConnectCbParams &io) = 0;
 198     void dataRead(const CommIoCbParams &io);
 199     void dataComplete();
 200     AsyncCall::Pointer dataCloser();
 201     virtual void dataClosed(const CommCloseCbParams &io);
 202     void initReadBuf();
 203
 204     // sending of the request body to the server
 205     void sentRequestBody(const CommIoCbParams &io) override;
 206     void doneSendingRequestBody() override;
 207
 208     /// Waits for an FTP data connection to the server to be established/opened.
 209     /// This wait only happens in FTP passive mode (via PASV or EPSV).
 210     JobWait<Comm::ConnOpener> dataConnWait;
 211
 212 private:
 213     bool parseControlReply(size_t &bytesUsed);
 214
 215     /// XXX: An old hack for FTP servers like ftp.netscape.com that may not
 216     /// respond to PASV. Use faster connect timeout instead of read timeout.
 217     bool shortenReadTimeout;
 218 };
 219
 220 } // namespace Ftp
 221
 222 #endif /* SQUID_SRC_CLIENTS_FTPCLIENT_H */
 223