cpan/MIME-Base64/Base64.pm

   1 package MIME::Base64;
   2
   3 use strict;
   4 use vars qw(@ISA @EXPORT @EXPORT_OK $VERSION);
   5
   6 require Exporter;
   7 @ISA = qw(Exporter);
   8 @EXPORT = qw(encode_base64 decode_base64);
   9 @EXPORT_OK = qw(encode_base64url decode_base64url encoded_base64_length decoded_base64_length);
  10
  11 $VERSION = '3.15';
  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