src/http/one/Parser.h

   1 /*
   2  * Copyright (C) 1996-2023 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 #ifndef SQUID_SRC_HTTP_ONE_PARSER_H
  10 #define SQUID_SRC_HTTP_ONE_PARSER_H
  11
  12 #include "anyp/ProtocolVersion.h"
  13 #include "http/one/forward.h"
  14 #include "http/StatusCode.h"
  15 #include "parser/forward.h"
  16 #include "sbuf/SBuf.h"
  17
  18 namespace Http {
  19 namespace One {
  20
  21 // Parser states
  22 enum ParseState {
  23     HTTP_PARSE_NONE,      ///< initialized, but nothing usefully parsed yet
  24     HTTP_PARSE_FIRST,     ///< HTTP/1 message first-line
  25     HTTP_PARSE_CHUNK_SZ,  ///< HTTP/1.1 chunked encoding chunk-size
  26     HTTP_PARSE_CHUNK_EXT, ///< HTTP/1.1 chunked encoding chunk-ext
  27     HTTP_PARSE_CHUNK,     ///< HTTP/1.1 chunked encoding chunk-data
  28     HTTP_PARSE_MIME,      ///< HTTP/1 mime-header block
  29     HTTP_PARSE_DONE       ///< parsed a message header, or reached a terminal syntax error
  30 };
  31
  32 /** HTTP/1.x protocol parser
  33  *
  34  * Works on a raw character I/O buffer and tokenizes the content into
  35  * the major CRLF delimited segments of an HTTP/1 procotol message:
  36  *
  37  * \li first-line (request-line / simple-request / status-line)
  38  * \li mime-header 0*( header-name ':' SP field-value CRLF)
  39  */
  40 class Parser : public RefCountable
  41 {
  42 public:
  43     typedef SBuf::size_type size_type;
  44     typedef ::Parser::Tokenizer Tokenizer;
  45
  46     Parser() = default;
  47     Parser(const Parser &) = default;
  48     Parser &operator =(const Parser &) = default;
  49     Parser(Parser &&) = default;
  50     Parser &operator =(Parser &&) = default;
  51     ~Parser() override {}
  52
  53     /// Set this parser back to a default state.
  54     /// Will DROP any reference to a buffer (does not free).
  55     virtual void clear() = 0;
  56
  57     /// attempt to parse a message from the buffer
  58     /// \retval true if a full message was found and parsed
  59     /// \retval false if incomplete, invalid or no message was found
  60     virtual bool parse(const SBuf &aBuf) = 0;
  61
  62     /** Whether the parser is waiting on more data to complete parsing a message.
  63      * Use to distinguish between incomplete data and error results
  64      * when parse() returns false.
  65      */
  66     bool needsMoreData() const {return parsingStage_!=HTTP_PARSE_DONE;}
  67
  68     /// size in bytes of the first line including CRLF terminator
  69     virtual size_type firstLineSize() const = 0;
  70
  71     /// size in bytes of the message headers including CRLF terminator(s)
  72     /// but excluding first-line bytes
  73     size_type headerBlockSize() const {return mimeHeaderBlock_.length();}
  74
  75     /// size in bytes of HTTP message block, includes first-line and mime headers
  76     /// excludes any body/entity/payload bytes
  77     /// excludes any garbage prefix before the first-line
  78     size_type messageHeaderSize() const {return firstLineSize() + headerBlockSize();}
  79
  80     /// buffer containing HTTP mime headers, excluding message first-line.
  81     SBuf mimeHeader() const {return mimeHeaderBlock_;}
  82
  83     /// the protocol label for this message
  84     const AnyP::ProtocolVersion & messageProtocol() const {return msgProtocol_;}
  85
  86     /**
  87      * Scan the mime header block (badly) for a Host header.
  88      *
  89      * BUG: omits lines when searching for headers with obs-fold or multiple entries.
  90      *
  91      * BUG: limits output to just 1KB when Squid accepts up to 64KB line length.
  92      *
  93      * \return A pointer to a field-value of the first matching field-name, or NULL.
  94      */
  95     char *getHostHeaderField();
  96
  97     /// the remaining unprocessed section of buffer
  98     const SBuf &remaining() const {return buf_;}
  99
 100     /**
 101      * HTTP status code resulting from the parse process.
 102      * to be used on the invalid message handling.
 103      *
 104      * Http::scNone indicates incomplete parse,
 105      * Http::scOkay indicates no error,
 106      * other codes represent a parse error.
 107      */
 108     Http::StatusCode parseStatusCode = Http::scNone;
 109
 110     /// Whitespace between regular protocol elements.
 111     /// Seen in RFCs as OWS, RWS, BWS, SP/HTAB but may be "relaxed" by us.
 112     /// See also: DelimiterCharacters().
 113     static const CharacterSet &WhitespaceCharacters();
 114
 115     /// Whitespace between protocol elements in restricted contexts like
 116     /// request line, status line, asctime-date, and credentials
 117     /// Seen in RFCs as SP but may be "relaxed" by us.
 118     /// See also: WhitespaceCharacters().
 119     /// XXX: Misnamed and overused.
 120     static const CharacterSet &DelimiterCharacters();
 121
 122 protected:
 123     /**
 124      * detect and skip the CRLF or (if tolerant) LF line terminator
 125      * consume from the tokenizer.
 126      *
 127      * \throws exception on bad or InsufficientInput
 128      */
 129     void skipLineTerminator(Tokenizer &) const;
 130
 131     /**
 132      * Scan to find the mime headers block for current message.
 133      *
 134      * \retval true   If mime block (or a blocks non-existence) has been
 135      *                identified accurately within limit characters.
 136      *                mimeHeaderBlock_ has been updated and buf_ consumed.
 137      *
 138      * \retval false  An error occurred, or no mime terminator found within limit.
 139      */
 140     bool grabMimeBlock(const char *which, const size_t limit);
 141
 142     /// RFC 7230 section 2.6 - 7 magic octets
 143     static const SBuf Http1magic;
 144
 145     /// bytes remaining to be parsed
 146     SBuf buf_;
 147
 148     /// what stage the parser is currently up to
 149     ParseState parsingStage_ = HTTP_PARSE_NONE;
 150
 151     /// what protocol label has been found in the first line (if any)
 152     AnyP::ProtocolVersion msgProtocol_;
 153
 154     /// buffer holding the mime headers (if any)
 155     SBuf mimeHeaderBlock_;
 156
 157     /// Whether the invalid HTTP as HTTP/0.9 hack expects a mime header block
 158     bool hackExpectsMime_ = false;
 159
 160 private:
 161     void cleanMimePrefix();
 162     void unfoldMime();
 163 };
 164
 165 /// skips and, if needed, warns about RFC 7230 BWS ("bad" whitespace)
 166 /// \throws InsufficientInput when the end of BWS cannot be confirmed
 167 void ParseBws(Parser::Tokenizer &);
 168
 169 /// the right debugs() level for logging HTTP violation messages
 170 int ErrorLevel();
 171
 172 } // namespace One
 173 } // namespace Http
 174
 175 #endif /* SQUID_SRC_HTTP_ONE_PARSER_H */
 176