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