Source file src/pkg/encoding/base64/base64.go

     1	// Copyright 2009 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	// Package base64 implements base64 encoding as specified by RFC 4648.
     6	package base64
     7	
     8	import (
     9		"io"
    10		"strconv"
    11	)
    12	
    13	/*
    14	 * Encodings
    15	 */
    16	
    17	// An Encoding is a radix 64 encoding/decoding scheme, defined by a
    18	// 64-character alphabet.  The most common encoding is the "base64"
    19	// encoding defined in RFC 4648 and used in MIME (RFC 2045) and PEM
    20	// (RFC 1421).  RFC 4648 also defines an alternate encoding, which is
    21	// the standard encoding with - and _ substituted for + and /.
    22	type Encoding struct {
    23		encode    string
    24		decodeMap [256]byte
    25	}
    26	
    27	const encodeStd = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/"
    28	const encodeURL = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_"
    29	
    30	// NewEncoding returns a new Encoding defined by the given alphabet,
    31	// which must be a 64-byte string.
    32	func NewEncoding(encoder string) *Encoding {
    33		e := new(Encoding)
    34		e.encode = encoder
    35		for i := 0; i < len(e.decodeMap); i++ {
    36			e.decodeMap[i] = 0xFF
    37		}
    38		for i := 0; i < len(encoder); i++ {
    39			e.decodeMap[encoder[i]] = byte(i)
    40		}
    41		return e
    42	}
    43	
    44	// StdEncoding is the standard base64 encoding, as defined in
    45	// RFC 4648.
    46	var StdEncoding = NewEncoding(encodeStd)
    47	
    48	// URLEncoding is the alternate base64 encoding defined in RFC 4648.
    49	// It is typically used in URLs and file names.
    50	var URLEncoding = NewEncoding(encodeURL)
    51	
    52	/*
    53	 * Encoder
    54	 */
    55	
    56	// Encode encodes src using the encoding enc, writing
    57	// EncodedLen(len(src)) bytes to dst.
    58	//
    59	// The encoding pads the output to a multiple of 4 bytes,
    60	// so Encode is not appropriate for use on individual blocks
    61	// of a large data stream.  Use NewEncoder() instead.
    62	func (enc *Encoding) Encode(dst, src []byte) {
    63		if len(src) == 0 {
    64			return
    65		}
    66	
    67		for len(src) > 0 {
    68			dst[0] = 0
    69			dst[1] = 0
    70			dst[2] = 0
    71			dst[3] = 0
    72	
    73			// Unpack 4x 6-bit source blocks into a 4 byte
    74			// destination quantum
    75			switch len(src) {
    76			default:
    77				dst[3] |= src[2] & 0x3F
    78				dst[2] |= src[2] >> 6
    79				fallthrough
    80			case 2:
    81				dst[2] |= (src[1] << 2) & 0x3F
    82				dst[1] |= src[1] >> 4
    83				fallthrough
    84			case 1:
    85				dst[1] |= (src[0] << 4) & 0x3F
    86				dst[0] |= src[0] >> 2
    87			}
    88	
    89			// Encode 6-bit blocks using the base64 alphabet
    90			for j := 0; j < 4; j++ {
    91				dst[j] = enc.encode[dst[j]]
    92			}
    93	
    94			// Pad the final quantum
    95			if len(src) < 3 {
    96				dst[3] = '='
    97				if len(src) < 2 {
    98					dst[2] = '='
    99				}
   100				break
   101			}
   102	
   103			src = src[3:]
   104			dst = dst[4:]
   105		}
   106	}
   107	
   108	// EncodeToString returns the base64 encoding of src.
   109	func (enc *Encoding) EncodeToString(src []byte) string {
   110		buf := make([]byte, enc.EncodedLen(len(src)))
   111		enc.Encode(buf, src)
   112		return string(buf)
   113	}
   114	
   115	type encoder struct {
   116		err  error
   117		enc  *Encoding
   118		w    io.Writer
   119		buf  [3]byte    // buffered data waiting to be encoded
   120		nbuf int        // number of bytes in buf
   121		out  [1024]byte // output buffer
   122	}
   123	
   124	func (e *encoder) Write(p []byte) (n int, err error) {
   125		if e.err != nil {
   126			return 0, e.err
   127		}
   128	
   129		// Leading fringe.
   130		if e.nbuf > 0 {
   131			var i int
   132			for i = 0; i < len(p) && e.nbuf < 3; i++ {
   133				e.buf[e.nbuf] = p[i]
   134				e.nbuf++
   135			}
   136			n += i
   137			p = p[i:]
   138			if e.nbuf < 3 {
   139				return
   140			}
   141			e.enc.Encode(e.out[0:], e.buf[0:])
   142			if _, e.err = e.w.Write(e.out[0:4]); e.err != nil {
   143				return n, e.err
   144			}
   145			e.nbuf = 0
   146		}
   147	
   148		// Large interior chunks.
   149		for len(p) >= 3 {
   150			nn := len(e.out) / 4 * 3
   151			if nn > len(p) {
   152				nn = len(p)
   153			}
   154			nn -= nn % 3
   155			if nn > 0 {
   156				e.enc.Encode(e.out[0:], p[0:nn])
   157				if _, e.err = e.w.Write(e.out[0 : nn/3*4]); e.err != nil {
   158					return n, e.err
   159				}
   160			}
   161			n += nn
   162			p = p[nn:]
   163		}
   164	
   165		// Trailing fringe.
   166		for i := 0; i < len(p); i++ {
   167			e.buf[i] = p[i]
   168		}
   169		e.nbuf = len(p)
   170		n += len(p)
   171		return
   172	}
   173	
   174	// Close flushes any pending output from the encoder.
   175	// It is an error to call Write after calling Close.
   176	func (e *encoder) Close() error {
   177		// If there's anything left in the buffer, flush it out
   178		if e.err == nil && e.nbuf > 0 {
   179			e.enc.Encode(e.out[0:], e.buf[0:e.nbuf])
   180			e.nbuf = 0
   181			_, e.err = e.w.Write(e.out[0:4])
   182		}
   183		return e.err
   184	}
   185	
   186	// NewEncoder returns a new base64 stream encoder.  Data written to
   187	// the returned writer will be encoded using enc and then written to w.
   188	// Base64 encodings operate in 4-byte blocks; when finished
   189	// writing, the caller must Close the returned encoder to flush any
   190	// partially written blocks.
   191	func NewEncoder(enc *Encoding, w io.Writer) io.WriteCloser {
   192		return &encoder{enc: enc, w: w}
   193	}
   194	
   195	// EncodedLen returns the length in bytes of the base64 encoding
   196	// of an input buffer of length n.
   197	func (enc *Encoding) EncodedLen(n int) int { return (n + 2) / 3 * 4 }
   198	
   199	/*
   200	 * Decoder
   201	 */
   202	
   203	type CorruptInputError int64
   204	
   205	func (e CorruptInputError) Error() string {
   206		return "illegal base64 data at input byte " + strconv.FormatInt(int64(e), 10)
   207	}
   208	
   209	// decode is like Decode but returns an additional 'end' value, which
   210	// indicates if end-of-message padding was encountered and thus any
   211	// additional data is an error.
   212	func (enc *Encoding) decode(dst, src []byte) (n int, end bool, err error) {
   213		osrc := src
   214		for len(src) > 0 && !end {
   215			// Decode quantum using the base64 alphabet
   216			var dbuf [4]byte
   217			dlen := 4
   218	
   219		dbufloop:
   220			for j := 0; j < 4; {
   221				if len(src) == 0 {
   222					return n, false, CorruptInputError(len(osrc) - len(src) - j)
   223				}
   224				in := src[0]
   225				src = src[1:]
   226				if in == '\r' || in == '\n' {
   227					// Ignore this character.
   228					continue
   229				}
   230				if in == '=' && j >= 2 && len(src) < 4 {
   231					// We've reached the end and there's
   232					// padding
   233					if len(src) == 0 && j == 2 {
   234						// not enough padding
   235						return n, false, CorruptInputError(len(osrc))
   236					}
   237					if len(src) > 0 && src[0] != '=' {
   238						// incorrect padding
   239						return n, false, CorruptInputError(len(osrc) - len(src) - 1)
   240					}
   241					dlen = j
   242					end = true
   243					break dbufloop
   244				}
   245				dbuf[j] = enc.decodeMap[in]
   246				if dbuf[j] == 0xFF {
   247					return n, false, CorruptInputError(len(osrc) - len(src) - 1)
   248				}
   249				j++
   250			}
   251	
   252			// Pack 4x 6-bit source blocks into 3 byte destination
   253			// quantum
   254			switch dlen {
   255			case 4:
   256				dst[2] = dbuf[2]<<6 | dbuf[3]
   257				fallthrough
   258			case 3:
   259				dst[1] = dbuf[1]<<4 | dbuf[2]>>2
   260				fallthrough
   261			case 2:
   262				dst[0] = dbuf[0]<<2 | dbuf[1]>>4
   263			}
   264			dst = dst[3:]
   265			n += dlen - 1
   266		}
   267	
   268		return n, end, nil
   269	}
   270	
   271	// Decode decodes src using the encoding enc.  It writes at most
   272	// DecodedLen(len(src)) bytes to dst and returns the number of bytes
   273	// written.  If src contains invalid base64 data, it will return the
   274	// number of bytes successfully written and CorruptInputError.
   275	// New line characters (\r and \n) are ignored.
   276	func (enc *Encoding) Decode(dst, src []byte) (n int, err error) {
   277		n, _, err = enc.decode(dst, src)
   278		return
   279	}
   280	
   281	// DecodeString returns the bytes represented by the base64 string s.
   282	func (enc *Encoding) DecodeString(s string) ([]byte, error) {
   283		dbuf := make([]byte, enc.DecodedLen(len(s)))
   284		n, err := enc.Decode(dbuf, []byte(s))
   285		return dbuf[:n], err
   286	}
   287	
   288	type decoder struct {
   289		err    error
   290		enc    *Encoding
   291		r      io.Reader
   292		end    bool       // saw end of message
   293		buf    [1024]byte // leftover input
   294		nbuf   int
   295		out    []byte // leftover decoded output
   296		outbuf [1024 / 4 * 3]byte
   297	}
   298	
   299	func (d *decoder) Read(p []byte) (n int, err error) {
   300		if d.err != nil {
   301			return 0, d.err
   302		}
   303	
   304		// Use leftover decoded output from last read.
   305		if len(d.out) > 0 {
   306			n = copy(p, d.out)
   307			d.out = d.out[n:]
   308			return n, nil
   309		}
   310	
   311		// Read a chunk.
   312		nn := len(p) / 3 * 4
   313		if nn < 4 {
   314			nn = 4
   315		}
   316		if nn > len(d.buf) {
   317			nn = len(d.buf)
   318		}
   319		nn, d.err = io.ReadAtLeast(d.r, d.buf[d.nbuf:nn], 4-d.nbuf)
   320		d.nbuf += nn
   321		if d.nbuf < 4 {
   322			return 0, d.err
   323		}
   324	
   325		// Decode chunk into p, or d.out and then p if p is too small.
   326		nr := d.nbuf / 4 * 4
   327		nw := d.nbuf / 4 * 3
   328		if nw > len(p) {
   329			nw, d.end, d.err = d.enc.decode(d.outbuf[0:], d.buf[0:nr])
   330			d.out = d.outbuf[0:nw]
   331			n = copy(p, d.out)
   332			d.out = d.out[n:]
   333		} else {
   334			n, d.end, d.err = d.enc.decode(p, d.buf[0:nr])
   335		}
   336		d.nbuf -= nr
   337		for i := 0; i < d.nbuf; i++ {
   338			d.buf[i] = d.buf[i+nr]
   339		}
   340	
   341		if d.err == nil {
   342			d.err = err
   343		}
   344		return n, d.err
   345	}
   346	
   347	// NewDecoder constructs a new base64 stream decoder.
   348	func NewDecoder(enc *Encoding, r io.Reader) io.Reader {
   349		return &decoder{enc: enc, r: r}
   350	}
   351	
   352	// DecodedLen returns the maximum length in bytes of the decoded data
   353	// corresponding to n bytes of base64-encoded data.
   354	func (enc *Encoding) DecodedLen(n int) int { return n / 4 * 3 }