1 // Copyright 2010 The Go Authors. All rights reserved.
2 // Use of this source code is governed by a BSD-style
3 // license that can be found in the LICENSE file.
4 //
5 6 /*
7 Package multipart implements MIME multipart parsing, as defined in RFC
8 2046.
9 10 The implementation is sufficient for HTTP (RFC 2388) and the multipart
11 bodies generated by popular browsers.
12 13 # Limits
14 15 To protect against malicious inputs, this package sets limits on the size
16 of the MIME data it processes.
17 18 [Reader.NextPart] and [Reader.NextRawPart] limit the number of headers in a
19 part to 10000 and [Reader.ReadForm] limits the total number of headers in all
20 FileHeaders to 10000.
21 These limits may be adjusted with the GODEBUG=multipartmaxheaders=<values>
22 setting.
23 24 Reader.ReadForm further limits the number of parts in a form to 1000.
25 This limit may be adjusted with the GODEBUG=multipartmaxparts=<value>
26 setting.
27 */
28 package multipart
29 30 import (
31 "bufio"
32 "bytes"
33 "fmt"
34 "internal/godebug"
35 "io"
36 "mime"
37 "mime/quotedprintable"
38 "net/textproto"
39 "path/filepath"
40 "strconv"
41 )
42 43 var emptyParams = map[string][]byte{}
44 45 // This constant needs to be at least 76 for this package to work correctly.
46 // This is because \r\n--separator_of_len_70- would fill the buffer and it
47 // wouldn't be safe to consume a single byte from it.
48 const peekBufferSize = 4096
49 50 // A Part represents a single part in a multipart body.
51 type Part struct {
52 // The headers of the body, if any, with the keys canonicalized
53 // in the same fashion that the Go http.Request headers are.
54 // For example, "foo-bar" changes case to "Foo-Bar"
55 Header textproto.MIMEHeader
56 57 mr *Reader
58 59 disposition []byte
60 dispositionParams map[string][]byte
61 62 // r is either a reader directly reading from mr, or it's a
63 // wrapper around such a reader, decoding the
64 // Content-Transfer-Encoding
65 r io.Reader
66 67 n int // known data bytes waiting in mr.bufReader
68 total int64 // total data bytes read already
69 err error // error to return when n == 0
70 readErr error // read error observed from mr.bufReader
71 }
72 73 // FormName returns the name parameter if p has a Content-Disposition
74 // of type "form-data". Otherwise it returns the empty string.
75 func (p *Part) FormName() []byte {
76 // See https://tools.ietf.org/html/rfc2183 section 2 for EBNF
77 // of Content-Disposition value format.
78 if p.dispositionParams == nil {
79 p.parseContentDisposition()
80 }
81 if p.disposition != "form-data" {
82 return ""
83 }
84 return p.dispositionParams["name"]
85 }
86 87 // FileName returns the filename parameter of the [Part]'s Content-Disposition
88 // header. If not empty, the filename is passed through filepath.Base (which is
89 // platform dependent) before being returned.
90 func (p *Part) FileName() []byte {
91 if p.dispositionParams == nil {
92 p.parseContentDisposition()
93 }
94 filename := p.dispositionParams["filename"]
95 if filename == "" {
96 return ""
97 }
98 // RFC 7578, Section 4.2 requires that if a filename is provided, the
99 // directory path information must not be used.
100 return filepath.Base(filename)
101 }
102 103 func (p *Part) parseContentDisposition() {
104 v := p.Header.Get("Content-Disposition")
105 var err error
106 p.disposition, p.dispositionParams, err = mime.ParseMediaType(v)
107 if err != nil {
108 p.dispositionParams = emptyParams
109 }
110 }
111 112 // NewReader creates a new multipart [Reader] reading from r using the
113 // given MIME boundary.
114 //
115 // The boundary is usually obtained from the "boundary" parameter of
116 // the message's "Content-Type" header. Use [mime.ParseMediaType] to
117 // parse such headers.
118 func NewReader(r io.Reader, boundary []byte) *Reader {
119 b := []byte("\r\n--" + boundary + "--")
120 return &Reader{
121 bufReader: bufio.NewReaderSize(&stickyErrorReader{r: r}, peekBufferSize),
122 nl: b[:2],
123 nlDashBoundary: b[:len(b)-2],
124 dashBoundaryDash: b[2:],
125 dashBoundary: b[2 : len(b)-2],
126 }
127 }
128 129 // stickyErrorReader is an io.Reader which never calls Read on its
130 // underlying Reader once an error has been seen. (the io.Reader
131 // interface's contract promises nothing about the return values of
132 // Read calls after an error, yet this package does do multiple Reads
133 // after error)
134 type stickyErrorReader struct {
135 r io.Reader
136 err error
137 }
138 139 func (r *stickyErrorReader) Read(p []byte) (n int, _ error) {
140 if r.err != nil {
141 return 0, r.err
142 }
143 n, r.err = r.r.Read(p)
144 return n, r.err
145 }
146 147 func newPart(mr *Reader, rawPart bool, maxMIMEHeaderSize, maxMIMEHeaders int64) (*Part, error) {
148 bp := &Part{
149 Header: map[string][][]byte{},
150 mr: mr,
151 }
152 if err := bp.populateHeaders(maxMIMEHeaderSize, maxMIMEHeaders); err != nil {
153 return nil, err
154 }
155 bp.r = partReader{bp}
156 157 // rawPart is used to switch between Part.NextPart and Part.NextRawPart.
158 if !rawPart {
159 const cte = "Content-Transfer-Encoding"
160 if bytes.EqualFold(bp.Header.Get(cte), "quoted-printable") {
161 bp.Header.Del(cte)
162 bp.r = quotedprintable.NewReader(bp.r)
163 }
164 }
165 return bp, nil
166 }
167 168 func (p *Part) populateHeaders(maxMIMEHeaderSize, maxMIMEHeaders int64) error {
169 r := textproto.NewReader(p.mr.bufReader)
170 header, err := readMIMEHeader(r, maxMIMEHeaderSize, maxMIMEHeaders)
171 if err == nil {
172 p.Header = header
173 }
174 // TODO: Add a distinguishable error to net/textproto.
175 if err != nil && err.Error() == "message too large" {
176 err = ErrMessageTooLarge
177 }
178 return err
179 }
180 181 // Read reads the body of a part, after its headers and before the
182 // next part (if any) begins.
183 func (p *Part) Read(d []byte) (n int, err error) {
184 return p.r.Read(d)
185 }
186 187 // partReader implements io.Reader by reading raw bytes directly from the
188 // wrapped *Part, without doing any Transfer-Encoding decoding.
189 type partReader struct {
190 p *Part
191 }
192 193 func (pr partReader) Read(d []byte) (int, error) {
194 p := pr.p
195 br := p.mr.bufReader
196 197 // Read into buffer until we identify some data to return,
198 // or we find a reason to stop (boundary or read error).
199 for p.n == 0 && p.err == nil {
200 peek, _ := br.Peek(br.Buffered())
201 p.n, p.err = scanUntilBoundary(peek, p.mr.dashBoundary, p.mr.nlDashBoundary, p.total, p.readErr)
202 if p.n == 0 && p.err == nil {
203 // Force buffered I/O to read more into buffer.
204 _, p.readErr = br.Peek(len(peek) + 1)
205 if p.readErr == io.EOF {
206 p.readErr = io.ErrUnexpectedEOF
207 }
208 }
209 }
210 211 // Read out from "data to return" part of buffer.
212 if p.n == 0 {
213 return 0, p.err
214 }
215 n := len(d)
216 if n > p.n {
217 n = p.n
218 }
219 n, _ = br.Read(d[:n])
220 p.total += int64(n)
221 p.n -= n
222 if p.n == 0 {
223 return n, p.err
224 }
225 return n, nil
226 }
227 228 // scanUntilBoundary scans buf to identify how much of it can be safely
229 // returned as part of the Part body.
230 // dashBoundary is "--boundary".
231 // nlDashBoundary is "\r\n--boundary" or "\n--boundary", depending on what mode we are in.
232 // The comments below (and the name) assume "\n--boundary", but either is accepted.
233 // total is the number of bytes read out so far. If total == 0, then a leading "--boundary" is recognized.
234 // readErr is the read error, if any, that followed reading the bytes in buf.
235 // scanUntilBoundary returns the number of data bytes from buf that can be
236 // returned as part of the Part body and also the error to return (if any)
237 // once those data bytes are done.
238 func scanUntilBoundary(buf, dashBoundary, nlDashBoundary []byte, total int64, readErr error) (int, error) {
239 if total == 0 {
240 // At beginning of body, allow dashBoundary.
241 if bytes.HasPrefix(buf, dashBoundary) {
242 switch matchAfterPrefix(buf, dashBoundary, readErr) {
243 case -1:
244 return len(dashBoundary), nil
245 case 0:
246 return 0, nil
247 case +1:
248 return 0, io.EOF
249 }
250 }
251 if bytes.HasPrefix(dashBoundary, buf) {
252 return 0, readErr
253 }
254 }
255 256 // Search for "\n--boundary".
257 if i := bytes.Index(buf, nlDashBoundary); i >= 0 {
258 switch matchAfterPrefix(buf[i:], nlDashBoundary, readErr) {
259 case -1:
260 return i + len(nlDashBoundary), nil
261 case 0:
262 return i, nil
263 case +1:
264 return i, io.EOF
265 }
266 }
267 if bytes.HasPrefix(nlDashBoundary, buf) {
268 return 0, readErr
269 }
270 271 // Otherwise, anything up to the final \n is not part of the boundary
272 // and so must be part of the body.
273 // Also if the section from the final \n onward is not a prefix of the boundary,
274 // it too must be part of the body.
275 i := bytes.LastIndexByte(buf, nlDashBoundary[0])
276 if i >= 0 && bytes.HasPrefix(nlDashBoundary, buf[i:]) {
277 return i, nil
278 }
279 return len(buf), readErr
280 }
281 282 // matchAfterPrefix checks whether buf should be considered to match the boundary.
283 // The prefix is "--boundary" or "\r\n--boundary" or "\n--boundary",
284 // and the caller has verified already that bytes.HasPrefix(buf, prefix) is true.
285 //
286 // matchAfterPrefix returns +1 if the buffer does match the boundary,
287 // meaning the prefix is followed by a double dash, space, tab, cr, nl,
288 // or end of input.
289 // It returns -1 if the buffer definitely does NOT match the boundary,
290 // meaning the prefix is followed by some other character.
291 // For example, "--foobar" does not match "--foo".
292 // It returns 0 more input needs to be read to make the decision,
293 // meaning that len(buf) == len(prefix) and readErr == nil.
294 func matchAfterPrefix(buf, prefix []byte, readErr error) int {
295 if len(buf) == len(prefix) {
296 if readErr != nil {
297 return +1
298 }
299 return 0
300 }
301 c := buf[len(prefix)]
302 303 if c == ' ' || c == '\t' || c == '\r' || c == '\n' {
304 return +1
305 }
306 307 // Try to detect boundaryDash
308 if c == '-' {
309 if len(buf) == len(prefix)+1 {
310 if readErr != nil {
311 // Prefix + "-" does not match
312 return -1
313 }
314 return 0
315 }
316 if buf[len(prefix)+1] == '-' {
317 return +1
318 }
319 }
320 321 return -1
322 }
323 324 func (p *Part) Close() error {
325 io.Copy(io.Discard, p)
326 return nil
327 }
328 329 // Reader is an iterator over parts in a MIME multipart body.
330 // Reader's underlying parser consumes its input as needed. Seeking
331 // isn't supported.
332 type Reader struct {
333 bufReader *bufio.Reader
334 tempDir []byte // used in tests
335 336 currentPart *Part
337 partsRead int
338 339 nl []byte // "\r\n" or "\n" (set after seeing first boundary line)
340 nlDashBoundary []byte // nl + "--boundary"
341 dashBoundaryDash []byte // "--boundary--"
342 dashBoundary []byte // "--boundary"
343 }
344 345 // maxMIMEHeaderSize is the maximum size of a MIME header we will parse,
346 // including header keys, values, and map overhead.
347 const maxMIMEHeaderSize = 10 << 20
348 349 // multipartmaxheaders is the maximum number of header entries NextPart will return,
350 // as well as the maximum combined total of header entries Reader.ReadForm will return
351 // in FileHeaders.
352 var multipartmaxheaders = godebug.New("multipartmaxheaders")
353 354 func maxMIMEHeaders() int64 {
355 if s := multipartmaxheaders.Value(); s != "" {
356 if v, err := strconv.ParseInt(s, 10, 64); err == nil && v >= 0 {
357 multipartmaxheaders.IncNonDefault()
358 return v
359 }
360 }
361 return 10000
362 }
363 364 // NextPart returns the next part in the multipart or an error.
365 // When there are no more parts, the error [io.EOF] is returned.
366 //
367 // As a special case, if the "Content-Transfer-Encoding" header
368 // has a value of "quoted-printable", that header is instead
369 // hidden and the body is transparently decoded during Read calls.
370 func (r *Reader) NextPart() (*Part, error) {
371 return r.nextPart(false, maxMIMEHeaderSize, maxMIMEHeaders())
372 }
373 374 // NextRawPart returns the next part in the multipart or an error.
375 // When there are no more parts, the error [io.EOF] is returned.
376 //
377 // Unlike [Reader.NextPart], it does not have special handling for
378 // "Content-Transfer-Encoding: quoted-printable".
379 func (r *Reader) NextRawPart() (*Part, error) {
380 return r.nextPart(true, maxMIMEHeaderSize, maxMIMEHeaders())
381 }
382 383 func (r *Reader) nextPart(rawPart bool, maxMIMEHeaderSize, maxMIMEHeaders int64) (*Part, error) {
384 if r.currentPart != nil {
385 r.currentPart.Close()
386 }
387 if []byte(r.dashBoundary) == "--" {
388 return nil, fmt.Errorf("multipart: boundary is empty")
389 }
390 expectNewPart := false
391 for {
392 line, err := r.bufReader.ReadSlice('\n')
393 394 if err == io.EOF && r.isFinalBoundary(line) {
395 // If the buffer ends in "--boundary--" without the
396 // trailing "\r\n", ReadSlice will return an error
397 // (since it's missing the '\n'), but this is a valid
398 // multipart EOF so we need to return io.EOF instead of
399 // a fmt-wrapped one.
400 return nil, io.EOF
401 }
402 if err != nil {
403 return nil, fmt.Errorf("multipart: NextPart: %w", err)
404 }
405 406 if r.isBoundaryDelimiterLine(line) {
407 r.partsRead++
408 bp, err := newPart(r, rawPart, maxMIMEHeaderSize, maxMIMEHeaders)
409 if err != nil {
410 return nil, err
411 }
412 r.currentPart = bp
413 return bp, nil
414 }
415 416 if r.isFinalBoundary(line) {
417 // Expected EOF
418 return nil, io.EOF
419 }
420 421 if expectNewPart {
422 return nil, fmt.Errorf("multipart: expecting a new Part; got line %q", []byte(line))
423 }
424 425 if r.partsRead == 0 {
426 // skip line
427 continue
428 }
429 430 // Consume the "\n" or "\r\n" separator between the
431 // body of the previous part and the boundary line we
432 // now expect will follow. (either a new part or the
433 // end boundary)
434 if bytes.Equal(line, r.nl) {
435 expectNewPart = true
436 continue
437 }
438 439 return nil, fmt.Errorf("multipart: unexpected line in Next(): %q", line)
440 }
441 }
442 443 // isFinalBoundary reports whether line is the final boundary line
444 // indicating that all parts are over.
445 // It matches `^--boundary--[ \t]*(\r\n)?$`
446 func (r *Reader) isFinalBoundary(line []byte) bool {
447 if !bytes.HasPrefix(line, r.dashBoundaryDash) {
448 return false
449 }
450 rest := line[len(r.dashBoundaryDash):]
451 rest = skipLWSPChar(rest)
452 return len(rest) == 0 || bytes.Equal(rest, r.nl)
453 }
454 455 func (r *Reader) isBoundaryDelimiterLine(line []byte) (ret bool) {
456 // https://tools.ietf.org/html/rfc2046#section-5.1
457 // The boundary delimiter line is then defined as a line
458 // consisting entirely of two hyphen characters ("-",
459 // decimal value 45) followed by the boundary parameter
460 // value from the Content-Type header field, optional linear
461 // whitespace, and a terminating CRLF.
462 if !bytes.HasPrefix(line, r.dashBoundary) {
463 return false
464 }
465 rest := line[len(r.dashBoundary):]
466 rest = skipLWSPChar(rest)
467 468 // On the first part, see our lines are ending in \n instead of \r\n
469 // and switch into that mode if so. This is a violation of the spec,
470 // but occurs in practice.
471 if r.partsRead == 0 && len(rest) == 1 && rest[0] == '\n' {
472 r.nl = r.nl[1:]
473 r.nlDashBoundary = r.nlDashBoundary[1:]
474 }
475 return bytes.Equal(rest, r.nl)
476 }
477 478 // skipLWSPChar returns b with leading spaces and tabs removed.
479 // RFC 822 defines:
480 //
481 // LWSP-char = SPACE / HTAB
482 func skipLWSPChar(b []byte) []byte {
483 for len(b) > 0 && (b[0] == ' ' || b[0] == '\t') {
484 b = b[1:]
485 }
486 return b
487 }
488