Commit | Line | Data |
---|---|---|
6fba102d JH |
1 | package MIME::Base64; |
2 | ||
0a362e9d | 3 | use strict; |
46787c0e | 4 | use vars qw(@ISA @EXPORT @EXPORT_OK $VERSION); |
0a362e9d RGS |
5 | |
6 | require Exporter; | |
e1839706 | 7 | @ISA = qw(Exporter); |
0a362e9d | 8 | @EXPORT = qw(encode_base64 decode_base64); |
2456140e | 9 | @EXPORT_OK = qw(encode_base64url decode_base64url encoded_base64_length decoded_base64_length); |
0a362e9d | 10 | |
43f93048 | 11 | $VERSION = '3.14'; |
0a362e9d | 12 | |
e1839706 SP |
13 | require XSLoader; |
14 | XSLoader::load('MIME::Base64', $VERSION); | |
0a362e9d RGS |
15 | |
16 | *encode = \&encode_base64; | |
17 | *decode = \&decode_base64; | |
18 | ||
2456140e CBW |
19 | sub encode_base64url { |
20 | my $e = encode_base64(shift, ""); | |
21 | $e =~ s/=+\z//; | |
22 | $e =~ tr[+/][-_]; | |
23 | return $e; | |
24 | } | |
25 | ||
26 | sub decode_base64url { | |
27 | my $s = shift; | |
28 | $s =~ tr[-_][+/]; | |
29 | $s .= '=' while length($s) % 4; | |
30 | return decode_base64($s); | |
31 | } | |
32 | ||
0a362e9d RGS |
33 | 1; |
34 | ||
35 | __END__ | |
36 | ||
6fba102d JH |
37 | =head1 NAME |
38 | ||
39 | MIME::Base64 - Encoding and decoding of base64 strings | |
40 | ||
41 | =head1 SYNOPSIS | |
42 | ||
43 | use MIME::Base64; | |
44 | ||
45 | $encoded = encode_base64('Aladdin:open sesame'); | |
46 | $decoded = decode_base64($encoded); | |
47 | ||
48 | =head1 DESCRIPTION | |
49 | ||
691d66bd RGS |
50 | This module provides functions to encode and decode strings into and from the |
51 | base64 encoding specified in RFC 2045 - I<MIME (Multipurpose Internet | |
52 | Mail Extensions)>. The base64 encoding is designed to represent | |
6fba102d JH |
53 | arbitrary sequences of octets in a form that need not be humanly |
54 | readable. A 65-character subset ([A-Za-z0-9+/=]) of US-ASCII is used, | |
55 | enabling 6 bits to be represented per printable character. | |
56 | ||
46787c0e | 57 | The following primary functions are provided: |
6fba102d JH |
58 | |
59 | =over 4 | |
60 | ||
719245bd | 61 | =item encode_base64( $bytes ) |
6a63fb82 | 62 | |
719245bd | 63 | =item encode_base64( $bytes, $eol ); |
6fba102d JH |
64 | |
65 | Encode data by calling the encode_base64() function. The first | |
719245bd | 66 | argument is the byte string to encode. The second argument is the |
691d66bd | 67 | line-ending sequence to use. It is optional and defaults to "\n". The |
6fba102d JH |
68 | returned encoded string is broken into lines of no more than 76 |
69 | characters each and it will end with $eol unless it is empty. Pass an | |
70 | empty string as second argument if you do not want the encoded string | |
691d66bd | 71 | to be broken into lines. |
6fba102d | 72 | |
719245bd | 73 | The function will croak with "Wide character in subroutine entry" if $bytes |
2456140e CBW |
74 | contains characters with code above 255. The base64 encoding is only defined |
75 | for single-byte characters. Use the Encode module to select the byte encoding | |
76 | you want. | |
77 | ||
719245bd | 78 | =item decode_base64( $str ) |
6fba102d JH |
79 | |
80 | Decode a base64 string by calling the decode_base64() function. This | |
81 | function takes a single argument which is the string to decode and | |
82 | returns the decoded data. | |
83 | ||
691d66bd RGS |
84 | Any character not part of the 65-character base64 subset is |
85 | silently ignored. Characters occurring after a '=' padding character | |
6fba102d JH |
86 | are never decoded. |
87 | ||
6fba102d JH |
88 | =back |
89 | ||
691d66bd | 90 | If you prefer not to import these routines into your namespace, you can |
6fba102d JH |
91 | call them as: |
92 | ||
93 | use MIME::Base64 (); | |
94 | $encoded = MIME::Base64::encode($decoded); | |
95 | $decoded = MIME::Base64::decode($encoded); | |
96 | ||
46787c0e CBW |
97 | Additional functions not exported by default: |
98 | ||
99 | =over 4 | |
100 | ||
719245bd | 101 | =item encode_base64url( $bytes ) |
2456140e | 102 | |
719245bd | 103 | =item decode_base64url( $str ) |
2456140e CBW |
104 | |
105 | Encode and decode according to the base64 scheme for "URL applications" [1]. | |
106 | This is a variant of the base64 encoding which does not use padding, does not | |
107 | break the string into multiple lines and use the characters "-" and "_" instead | |
108 | of "+" and "/" to avoid using reserved URL characters. | |
109 | ||
719245bd | 110 | =item encoded_base64_length( $bytes ) |
46787c0e | 111 | |
719245bd | 112 | =item encoded_base64_length( $bytes, $eol ) |
46787c0e CBW |
113 | |
114 | Returns the length that the encoded string would have without actually | |
719245bd | 115 | encoding it. This will return the same value as C<< length(encode_base64($bytes)) >>, |
46787c0e CBW |
116 | but should be more efficient. |
117 | ||
719245bd | 118 | =item decoded_base64_length( $str ) |
46787c0e CBW |
119 | |
120 | Returns the length that the decoded string would have without actually | |
121 | decoding it. This will return the same value as C<< length(decode_base64($str)) >>, | |
122 | but should be more efficient. | |
123 | ||
124 | =back | |
125 | ||
6fba102d JH |
126 | =head1 EXAMPLES |
127 | ||
128 | If you want to encode a large file, you should encode it in chunks | |
129 | that are a multiple of 57 bytes. This ensures that the base64 lines | |
130 | line up and that you do not end up with padding in the middle. 57 | |
131 | bytes of data fills one complete base64 line (76 == 57*4/3): | |
132 | ||
133 | use MIME::Base64 qw(encode_base64); | |
134 | ||
135 | open(FILE, "/var/log/wtmp") or die "$!"; | |
136 | while (read(FILE, $buf, 60*57)) { | |
137 | print encode_base64($buf); | |
138 | } | |
139 | ||
140 | or if you know you have enough memory | |
141 | ||
142 | use MIME::Base64 qw(encode_base64); | |
143 | local($/) = undef; # slurp | |
144 | print encode_base64(<STDIN>); | |
145 | ||
146 | The same approach as a command line: | |
147 | ||
148 | perl -MMIME::Base64 -0777 -ne 'print encode_base64($_)' <file | |
149 | ||
691d66bd RGS |
150 | Decoding does not need slurp mode if every line contains a multiple |
151 | of four base64 chars: | |
6fba102d JH |
152 | |
153 | perl -MMIME::Base64 -ne 'print decode_base64($_)' <file | |
154 | ||
e1839706 SP |
155 | Perl v5.8 and better allow extended Unicode characters in strings. |
156 | Such strings cannot be encoded directly, as the base64 | |
157 | encoding is only defined for single-byte characters. The solution is | |
158 | to use the Encode module to select the byte encoding you want. For | |
159 | example: | |
160 | ||
161 | use MIME::Base64 qw(encode_base64); | |
162 | use Encode qw(encode); | |
163 | ||
164 | $encoded = encode_base64(encode("UTF-8", "\x{FFFF}\n")); | |
165 | print $encoded; | |
166 | ||
6fba102d JH |
167 | =head1 COPYRIGHT |
168 | ||
719245bd | 169 | Copyright 1995-1999, 2001-2004, 2010 Gisle Aas. |
6fba102d JH |
170 | |
171 | This library is free software; you can redistribute it and/or | |
172 | modify it under the same terms as Perl itself. | |
173 | ||
174 | Distantly based on LWP::Base64 written by Martijn Koster | |
175 | <m.koster@nexor.co.uk> and Joerg Reichelt <j.reichelt@nexor.co.uk> and | |
176 | code posted to comp.lang.perl <3pd2lp$6gf@wsinti07.win.tue.nl> by Hans | |
177 | Mulder <hansm@wsinti07.win.tue.nl> | |
178 | ||
691d66bd | 179 | The XS implementation uses code from metamail. Copyright 1991 Bell |
6fba102d JH |
180 | Communications Research, Inc. (Bellcore) |
181 | ||
8be5f608 RGS |
182 | =head1 SEE ALSO |
183 | ||
184 | L<MIME::QuotedPrint> | |
185 | ||
2456140e CBW |
186 | [1] L<http://en.wikipedia.org/wiki/Base64#URL_applications> |
187 | ||
6fba102d | 188 | =cut |