Commit | Line | Data |
---|---|---|
920dae64 AT |
1 | # Copyright (C) 2002-2004 Python Software Foundation |
2 | # Author: Ben Gertzfield | |
3 | # Contact: email-sig@python.org | |
4 | ||
5 | """Base64 content transfer encoding per RFCs 2045-2047. | |
6 | ||
7 | This module handles the content transfer encoding method defined in RFC 2045 | |
8 | to encode arbitrary 8-bit data using the three 8-bit bytes in four 7-bit | |
9 | characters encoding known as Base64. | |
10 | ||
11 | It is used in the MIME standards for email to attach images, audio, and text | |
12 | using some 8-bit character sets to messages. | |
13 | ||
14 | This module provides an interface to encode and decode both headers and bodies | |
15 | with Base64 encoding. | |
16 | ||
17 | RFC 2045 defines a method for including character set information in an | |
18 | `encoded-word' in a header. This method is commonly used for 8-bit real names | |
19 | in To:, From:, Cc:, etc. fields, as well as Subject: lines. | |
20 | ||
21 | This module does not do the line wrapping or end-of-line character conversion | |
22 | necessary for proper internationalized headers; it only does dumb encoding and | |
23 | decoding. To deal with the various line wrapping issues, use the email.Header | |
24 | module. | |
25 | """ | |
26 | ||
27 | import re | |
28 | from binascii import b2a_base64, a2b_base64 | |
29 | from email.Utils import fix_eols | |
30 | ||
31 | CRLF = '\r\n' | |
32 | NL = '\n' | |
33 | EMPTYSTRING = '' | |
34 | ||
35 | # See also Charset.py | |
36 | MISC_LEN = 7 | |
37 | ||
38 | ||
39 | \f | |
40 | # Helpers | |
41 | def base64_len(s): | |
42 | """Return the length of s when it is encoded with base64.""" | |
43 | groups_of_3, leftover = divmod(len(s), 3) | |
44 | # 4 bytes out for each 3 bytes (or nonzero fraction thereof) in. | |
45 | # Thanks, Tim! | |
46 | n = groups_of_3 * 4 | |
47 | if leftover: | |
48 | n += 4 | |
49 | return n | |
50 | ||
51 | ||
52 | \f | |
53 | def header_encode(header, charset='iso-8859-1', keep_eols=False, | |
54 | maxlinelen=76, eol=NL): | |
55 | """Encode a single header line with Base64 encoding in a given charset. | |
56 | ||
57 | Defined in RFC 2045, this Base64 encoding is identical to normal Base64 | |
58 | encoding, except that each line must be intelligently wrapped (respecting | |
59 | the Base64 encoding), and subsequent lines must start with a space. | |
60 | ||
61 | charset names the character set to use to encode the header. It defaults | |
62 | to iso-8859-1. | |
63 | ||
64 | End-of-line characters (\\r, \\n, \\r\\n) will be automatically converted | |
65 | to the canonical email line separator \\r\\n unless the keep_eols | |
66 | parameter is True (the default is False). | |
67 | ||
68 | Each line of the header will be terminated in the value of eol, which | |
69 | defaults to "\\n". Set this to "\\r\\n" if you are using the result of | |
70 | this function directly in email. | |
71 | ||
72 | The resulting string will be in the form: | |
73 | ||
74 | "=?charset?b?WW/5ciBtYXp66XLrIHf8eiBhIGhhbXBzdGHuciBBIFlv+XIgbWF6euly?=\\n | |
75 | =?charset?b?6yB3/HogYSBoYW1wc3Rh7nIgQkMgWW/5ciBtYXp66XLrIHf8eiBhIGhh?=" | |
76 | ||
77 | with each line wrapped at, at most, maxlinelen characters (defaults to 76 | |
78 | characters). | |
79 | """ | |
80 | # Return empty headers unchanged | |
81 | if not header: | |
82 | return header | |
83 | ||
84 | if not keep_eols: | |
85 | header = fix_eols(header) | |
86 | ||
87 | # Base64 encode each line, in encoded chunks no greater than maxlinelen in | |
88 | # length, after the RFC chrome is added in. | |
89 | base64ed = [] | |
90 | max_encoded = maxlinelen - len(charset) - MISC_LEN | |
91 | max_unencoded = max_encoded * 3 // 4 | |
92 | ||
93 | for i in range(0, len(header), max_unencoded): | |
94 | base64ed.append(b2a_base64(header[i:i+max_unencoded])) | |
95 | ||
96 | # Now add the RFC chrome to each encoded chunk | |
97 | lines = [] | |
98 | for line in base64ed: | |
99 | # Ignore the last character of each line if it is a newline | |
100 | if line.endswith(NL): | |
101 | line = line[:-1] | |
102 | # Add the chrome | |
103 | lines.append('=?%s?b?%s?=' % (charset, line)) | |
104 | # Glue the lines together and return it. BAW: should we be able to | |
105 | # specify the leading whitespace in the joiner? | |
106 | joiner = eol + ' ' | |
107 | return joiner.join(lines) | |
108 | ||
109 | ||
110 | \f | |
111 | def encode(s, binary=True, maxlinelen=76, eol=NL): | |
112 | """Encode a string with base64. | |
113 | ||
114 | Each line will be wrapped at, at most, maxlinelen characters (defaults to | |
115 | 76 characters). | |
116 | ||
117 | If binary is False, end-of-line characters will be converted to the | |
118 | canonical email end-of-line sequence \\r\\n. Otherwise they will be left | |
119 | verbatim (this is the default). | |
120 | ||
121 | Each line of encoded text will end with eol, which defaults to "\\n". Set | |
122 | this to "\r\n" if you will be using the result of this function directly | |
123 | in an email. | |
124 | """ | |
125 | if not s: | |
126 | return s | |
127 | ||
128 | if not binary: | |
129 | s = fix_eols(s) | |
130 | ||
131 | encvec = [] | |
132 | max_unencoded = maxlinelen * 3 // 4 | |
133 | for i in range(0, len(s), max_unencoded): | |
134 | # BAW: should encode() inherit b2a_base64()'s dubious behavior in | |
135 | # adding a newline to the encoded string? | |
136 | enc = b2a_base64(s[i:i + max_unencoded]) | |
137 | if enc.endswith(NL) and eol <> NL: | |
138 | enc = enc[:-1] + eol | |
139 | encvec.append(enc) | |
140 | return EMPTYSTRING.join(encvec) | |
141 | ||
142 | ||
143 | # For convenience and backwards compatibility w/ standard base64 module | |
144 | body_encode = encode | |
145 | encodestring = encode | |
146 | ||
147 | ||
148 | \f | |
149 | def decode(s, convert_eols=None): | |
150 | """Decode a raw base64 string. | |
151 | ||
152 | If convert_eols is set to a string value, all canonical email linefeeds, | |
153 | e.g. "\\r\\n", in the decoded text will be converted to the value of | |
154 | convert_eols. os.linesep is a good choice for convert_eols if you are | |
155 | decoding a text attachment. | |
156 | ||
157 | This function does not parse a full MIME header value encoded with | |
158 | base64 (like =?iso-8895-1?b?bmloISBuaWgh?=) -- please use the high | |
159 | level email.Header class for that functionality. | |
160 | """ | |
161 | if not s: | |
162 | return s | |
163 | ||
164 | dec = a2b_base64(s) | |
165 | if convert_eols: | |
166 | return dec.replace(CRLF, convert_eols) | |
167 | return dec | |
168 | ||
169 | ||
170 | # For convenience and backwards compatibility w/ standard base64 module | |
171 | body_decode = decode | |
172 | decodestring = decode |