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