src/libserialize/base64.rs

   1 // Copyright 2012-2013 The Rust Project Developers. See the COPYRIGHT
   2 // file at the top-level directory of this distribution and at
   3 // http://rust-lang.org/COPYRIGHT.
   4 //
   5 // Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
   6 // http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
   7 // <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
   8 // option. This file may not be copied, modified, or distributed
   9 // except according to those terms.
  10
  11 //! Base64 binary-to-text encoding
  12 use std::str;
  13
  14 /// Available encoding character sets
  15 pub enum CharacterSet {
  16     /// The standard character set (uses `+` and `/`)
  17     Standard,
  18     /// The URL safe character set (uses `-` and `_`)
  19     UrlSafe
  20 }
  21
  22 /// Contains configuration parameters for `to_base64`.
  23 pub struct Config {
  24     /// Character set to use
  25     char_set: CharacterSet,
  26     /// True to pad output with `=` characters
  27     pad: bool,
  28     /// `Some(len)` to wrap lines at `len`, `None` to disable line wrapping
  29     line_length: Option<uint>
  30 }
  31
  32 /// Configuration for RFC 4648 standard base64 encoding
  33 pub static STANDARD: Config =
  34     Config {char_set: Standard, pad: true, line_length: None};
  35
  36 /// Configuration for RFC 4648 base64url encoding
  37 pub static URL_SAFE: Config =
  38     Config {char_set: UrlSafe, pad: false, line_length: None};
  39
  40 /// Configuration for RFC 2045 MIME base64 encoding
  41 pub static MIME: Config =
  42     Config {char_set: Standard, pad: true, line_length: Some(76)};
  43
  44 static STANDARD_CHARS: &'static[u8] = bytes!("ABCDEFGHIJKLMNOPQRSTUVWXYZ",
  45                                              "abcdefghijklmnopqrstuvwxyz",
  46                                              "0123456789+/");
  47
  48 static URLSAFE_CHARS: &'static[u8] = bytes!("ABCDEFGHIJKLMNOPQRSTUVWXYZ",
  49                                             "abcdefghijklmnopqrstuvwxyz",
  50                                             "0123456789-_");
  51
  52 /// A trait for converting a value to base64 encoding.
  53 pub trait ToBase64 {
  54     /// Converts the value of `self` to a base64 value following the specified
  55     /// format configuration, returning the owned string.
  56     fn to_base64(&self, config: Config) -> ~str;
  57 }
  58
  59 impl<'a> ToBase64 for &'a [u8] {
  60     /**
  61      * Turn a vector of `u8` bytes into a base64 string.
  62      *
  63      * # Example
  64      *
  65      * ```rust
  66      * extern crate serialize;
  67      * use serialize::base64::{ToBase64, STANDARD};
  68      *
  69      * fn main () {
  70      *     let str = [52,32].to_base64(STANDARD);
  71      *     println!("base 64 output: {}", str);
  72      * }
  73      * ```
  74      */
  75     fn to_base64(&self, config: Config) -> ~str {
  76         let bytes = match config.char_set {
  77             Standard => STANDARD_CHARS,
  78             UrlSafe => URLSAFE_CHARS
  79         };
  80
  81         let mut v: ~[u8] = ~[];
  82         let mut i = 0;
  83         let mut cur_length = 0;
  84         let len = self.len();
  85         while i < len - (len % 3) {
  86             match config.line_length {
  87                 Some(line_length) =>
  88                     if cur_length >= line_length {
  89                         v.push('\r' as u8);
  90                         v.push('\n' as u8);
  91                         cur_length = 0;
  92                     },
  93                 None => ()
  94             }
  95
  96             let n = (self[i] as u32) << 16 |
  97                     (self[i + 1] as u32) << 8 |
  98                     (self[i + 2] as u32);
  99
 100             // This 24-bit number gets separated into four 6-bit numbers.
 101             v.push(bytes[(n >> 18) & 63]);
 102             v.push(bytes[(n >> 12) & 63]);
 103             v.push(bytes[(n >> 6 ) & 63]);
 104             v.push(bytes[n & 63]);
 105
 106             cur_length += 4;
 107             i += 3;
 108         }
 109
 110         if len % 3 != 0 {
 111             match config.line_length {
 112                 Some(line_length) =>
 113                     if cur_length >= line_length {
 114                         v.push('\r' as u8);
 115                         v.push('\n' as u8);
 116                     },
 117                 None => ()
 118             }
 119         }
 120
 121         // Heh, would be cool if we knew this was exhaustive
 122         // (the dream of bounded integer types)
 123         match len % 3 {
 124             0 => (),
 125             1 => {
 126                 let n = (self[i] as u32) << 16;
 127                 v.push(bytes[(n >> 18) & 63]);
 128                 v.push(bytes[(n >> 12) & 63]);
 129                 if config.pad {
 130                     v.push('=' as u8);
 131                     v.push('=' as u8);
 132                 }
 133             }
 134             2 => {
 135                 let n = (self[i] as u32) << 16 |
 136                     (self[i + 1u] as u32) << 8;
 137                 v.push(bytes[(n >> 18) & 63]);
 138                 v.push(bytes[(n >> 12) & 63]);
 139                 v.push(bytes[(n >> 6 ) & 63]);
 140                 if config.pad {
 141                     v.push('=' as u8);
 142                 }
 143             }
 144             _ => fail!("Algebra is broken, please alert the math police")
 145         }
 146
 147         unsafe {
 148             str::raw::from_utf8_owned(v)
 149         }
 150     }
 151 }
 152
 153 /// A trait for converting from base64 encoded values.
 154 pub trait FromBase64 {
 155     /// Converts the value of `self`, interpreted as base64 encoded data, into
 156     /// an owned vector of bytes, returning the vector.
 157     fn from_base64(&self) -> Result<~[u8], FromBase64Error>;
 158 }
 159
 160 /// Errors that can occur when decoding a base64 encoded string
 161 pub enum FromBase64Error {
 162     /// The input contained a character not part of the base64 format
 163     InvalidBase64Character(char, uint),
 164     /// The input had an invalid length
 165     InvalidBase64Length,
 166 }
 167
 168 impl ToStr for FromBase64Error {
 169     fn to_str(&self) -> ~str {
 170         match *self {
 171             InvalidBase64Character(ch, idx) =>
 172                 format!("Invalid character '{}' at position {}", ch, idx),
 173             InvalidBase64Length => ~"Invalid length",
 174         }
 175     }
 176 }
 177
 178 impl<'a> FromBase64 for &'a str {
 179     /**
 180      * Convert any base64 encoded string (literal, `@`, `&`, or `~`)
 181      * to the byte values it encodes.
 182      *
 183      * You can use the `from_utf8_owned` function in `std::str`
 184      * to turn a `[u8]` into a string with characters corresponding to those
 185      * values.
 186      *
 187      * # Example
 188      *
 189      * This converts a string literal to base64 and back.
 190      *
 191      * ```rust
 192      * extern crate serialize;
 193      * use serialize::base64::{ToBase64, FromBase64, STANDARD};
 194      * use std::str;
 195      *
 196      * fn main () {
 197      *     let hello_str = bytes!("Hello, World").to_base64(STANDARD);
 198      *     println!("base64 output: {}", hello_str);
 199      *     let res = hello_str.from_base64();
 200      *     if res.is_ok() {
 201      *       let optBytes = str::from_utf8_owned(res.unwrap());
 202      *       if optBytes.is_some() {
 203      *         println!("decoded from base64: {}", optBytes.unwrap());
 204      *       }
 205      *     }
 206      * }
 207      * ```
 208      */
 209     fn from_base64(&self) -> Result<~[u8], FromBase64Error> {
 210         let mut r = ~[];
 211         let mut buf: u32 = 0;
 212         let mut modulus = 0;
 213
 214         let mut it = self.bytes().enumerate();
 215         for (idx, byte) in it {
 216             let val = byte as u32;
 217
 218             match byte as char {
 219                 'A'..'Z' => buf |= val - 0x41,
 220                 'a'..'z' => buf |= val - 0x47,
 221                 '0'..'9' => buf |= val + 0x04,
 222                 '+'|'-' => buf |= 0x3E,
 223                 '/'|'_' => buf |= 0x3F,
 224                 '\r'|'\n' => continue,
 225                 '=' => break,
 226                 _ => return Err(InvalidBase64Character(self.char_at(idx), idx)),
 227             }
 228
 229             buf <<= 6;
 230             modulus += 1;
 231             if modulus == 4 {
 232                 modulus = 0;
 233                 r.push((buf >> 22) as u8);
 234                 r.push((buf >> 14) as u8);
 235                 r.push((buf >> 6 ) as u8);
 236             }
 237         }
 238
 239         for (idx, byte) in it {
 240             match byte as char {
 241                 '='|'\r'|'\n' => continue,
 242                 _ => return Err(InvalidBase64Character(self.char_at(idx), idx)),
 243             }
 244         }
 245
 246         match modulus {
 247             2 => {
 248                 r.push((buf >> 10) as u8);
 249             }
 250             3 => {
 251                 r.push((buf >> 16) as u8);
 252                 r.push((buf >> 8 ) as u8);
 253             }
 254             0 => (),
 255             _ => return Err(InvalidBase64Length),
 256         }
 257
 258         Ok(r)
 259     }
 260 }
 261
 262 #[cfg(test)]
 263 mod tests {
 264     extern crate test;
 265     use self::test::BenchHarness;
 266     use base64::{Config, FromBase64, ToBase64, STANDARD, URL_SAFE};
 267
 268     #[test]
 269     fn test_to_base64_basic() {
 270         assert_eq!("".as_bytes().to_base64(STANDARD), ~"");
 271         assert_eq!("f".as_bytes().to_base64(STANDARD), ~"Zg==");
 272         assert_eq!("fo".as_bytes().to_base64(STANDARD), ~"Zm8=");
 273         assert_eq!("foo".as_bytes().to_base64(STANDARD), ~"Zm9v");
 274         assert_eq!("foob".as_bytes().to_base64(STANDARD), ~"Zm9vYg==");
 275         assert_eq!("fooba".as_bytes().to_base64(STANDARD), ~"Zm9vYmE=");
 276         assert_eq!("foobar".as_bytes().to_base64(STANDARD), ~"Zm9vYmFy");
 277     }
 278
 279     #[test]
 280     fn test_to_base64_line_break() {
 281         assert!(![0u8, ..1000].to_base64(Config {line_length: None, ..STANDARD})
 282                 .contains("\r\n"));
 283         assert_eq!("foobar".as_bytes().to_base64(Config {line_length: Some(4),
 284                                                          ..STANDARD}),
 285                    ~"Zm9v\r\nYmFy");
 286     }
 287
 288     #[test]
 289     fn test_to_base64_padding() {
 290         assert_eq!("f".as_bytes().to_base64(Config {pad: false, ..STANDARD}), ~"Zg");
 291         assert_eq!("fo".as_bytes().to_base64(Config {pad: false, ..STANDARD}), ~"Zm8");
 292     }
 293
 294     #[test]
 295     fn test_to_base64_url_safe() {
 296         assert_eq!([251, 255].to_base64(URL_SAFE), ~"-_8");
 297         assert_eq!([251, 255].to_base64(STANDARD), ~"+/8=");
 298     }
 299
 300     #[test]
 301     fn test_from_base64_basic() {
 302         assert_eq!("".from_base64().unwrap(), "".as_bytes().to_owned());
 303         assert_eq!("Zg==".from_base64().unwrap(), "f".as_bytes().to_owned());
 304         assert_eq!("Zm8=".from_base64().unwrap(), "fo".as_bytes().to_owned());
 305         assert_eq!("Zm9v".from_base64().unwrap(), "foo".as_bytes().to_owned());
 306         assert_eq!("Zm9vYg==".from_base64().unwrap(), "foob".as_bytes().to_owned());
 307         assert_eq!("Zm9vYmE=".from_base64().unwrap(), "fooba".as_bytes().to_owned());
 308         assert_eq!("Zm9vYmFy".from_base64().unwrap(), "foobar".as_bytes().to_owned());
 309     }
 310
 311     #[test]
 312     fn test_from_base64_newlines() {
 313         assert_eq!("Zm9v\r\nYmFy".from_base64().unwrap(),
 314                    "foobar".as_bytes().to_owned());
 315         assert_eq!("Zm9vYg==\r\n".from_base64().unwrap(),
 316                    "foob".as_bytes().to_owned());
 317     }
 318
 319     #[test]
 320     fn test_from_base64_urlsafe() {
 321         assert_eq!("-_8".from_base64().unwrap(), "+/8=".from_base64().unwrap());
 322     }
 323
 324     #[test]
 325     fn test_from_base64_invalid_char() {
 326         assert!("Zm$=".from_base64().is_err())
 327         assert!("Zg==$".from_base64().is_err());
 328     }
 329
 330     #[test]
 331     fn test_from_base64_invalid_padding() {
 332         assert!("Z===".from_base64().is_err());
 333     }
 334
 335     #[test]
 336     fn test_base64_random() {
 337         use std::rand::{task_rng, random, Rng};
 338         use std::vec;
 339
 340         for _ in range(0, 1000) {
 341             let times = task_rng().gen_range(1u, 100);
 342             let v = vec::from_fn(times, |_| random::<u8>());
 343             assert_eq!(v.to_base64(STANDARD).from_base64().unwrap(), v);
 344         }
 345     }
 346
 347     #[bench]
 348     pub fn bench_to_base64(bh: & mut BenchHarness) {
 349         let s = "イロハニホヘト チリヌルヲ ワカヨタレソ ツネナラム \
 350                  ウヰノオクヤマ ケフコエテ アサキユメミシ ヱヒモセスン";
 351         bh.iter(|| {
 352             s.as_bytes().to_base64(STANDARD);
 353         });
 354         bh.bytes = s.len() as u64;
 355     }
 356
 357     #[bench]
 358     pub fn bench_from_base64(bh: & mut BenchHarness) {
 359         let s = "イロハニホヘト チリヌルヲ ワカヨタレソ ツネナラム \
 360                  ウヰノオクヤマ ケフコエテ アサキユメミシ ヱヒモセスン";
 361         let b = s.as_bytes().to_base64(STANDARD);
 362         bh.iter(|| {
 363             b.from_base64().unwrap();
 364         });
 365         bh.bytes = b.len() as u64;
 366     }
 367
 368 }