1: package MIME::Base64;
2: 
3: use strict;
4: use warnings;
5: 
6: require Exporter;
7: our @ISA = qw(Exporter);
8: our @EXPORT = qw(encode_base64 decode_base64);
9: our @EXPORT_OK = qw(encode_base64url decode_base64url encoded_base64_length decoded_base64_length);
10: 
11: our $VERSION = '3.16';
12: 
13: require XSLoader;
14: XSLoader::load('MIME::Base64', $VERSION);
15: 
16: *encode = \&encode_base64;
17: *decode = \&decode_base64;
18: 
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: 
33: 1;
34: 
35: __END__
36: 
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: 
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
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: 
57: The following primary functions are provided:
58: 
59: =over 4
60: 
61: =item encode_base64( $bytes )
62: 
63: =item encode_base64( $bytes, $eol );
64: 
65: Encode data by calling the encode_base64() function.  The first
66: argument is the byte string to encode.  The second argument is the
67: line-ending sequence to use.  It is optional and defaults to "\n".  The
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
71: to be broken into lines.
72: 
73: The function will croak with "Wide character in subroutine entry" if $bytes
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: 
78: =item decode_base64( $str )
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: 
84: Any character not part of the 65-character base64 subset is
85: silently ignored.  Characters occurring after a '=' padding character
86: are never decoded.
87: 
88: =back
89: 
90: If you prefer not to import these routines into your namespace, you can
91: call them as:
92: 
93:     use MIME::Base64 ();
94:     $encoded = MIME::Base64::encode($decoded);
95:     $decoded = MIME::Base64::decode($encoded);
96: 
97: Additional functions not exported by default:
98: 
99: =over 4
100: 
101: =item encode_base64url( $bytes )
102: 
103: =item decode_base64url( $str )
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: 
110: =item encoded_base64_length( $bytes )
111: 
112: =item encoded_base64_length( $bytes, $eol )
113: 
114: Returns the length that the encoded string would have without actually
115: encoding it.  This will return the same value as C<< length(encode_base64($bytes)) >>,
116: but should be more efficient.
117: 
118: =item decoded_base64_length( $str )
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: 
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: 
150: Decoding does not need slurp mode if every line contains a multiple
151: of four base64 chars:
152: 
153:    perl -MMIME::Base64 -ne 'print decode_base64($_)' <file
154: 
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: 
167: =head1 COPYRIGHT
168: 
169: Copyright 1995-1999, 2001-2004, 2010 Gisle Aas.
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: 
179: The XS implementation uses code from metamail.  Copyright 1991 Bell
180: Communications Research, Inc. (Bellcore)
181: 
182: =head1 SEE ALSO
183: 
184: L<MIME::QuotedPrint>
185: 
186: [1] L<http://en.wikipedia.org/wiki/Base64#URL_applications>
187: 
188: =cut