Crate base64ct 

RustCrypto: Constant-Time Base64

Pure Rust implementation of Base64 (RFC 4648).

Implements multiple Base64 alphabets without data-dependent branches or lookup tables, thereby providing portable “best effort” constant-time operation.

Supports no_std environments and avoids heap allocations in the core API (but also provides optional alloc support for convenience).

Documentation

About

This crate implements several Base64 alphabets in constant-time for sidechannel resistance, aimed at purposes like encoding/decoding the “PEM” format used to store things like cryptographic private keys (i.e. in the pem-rfc7468 crate).

The paper Util::Lookup: Exploiting key decoding in cryptographic libraries demonstrates how the leakage from non-constant-time Base64 parsers can be used to practically extract RSA private keys from SGX enclaves.

The padded variants require (=) padding. Unpadded variants expressly reject such padding.

Whitespace is expressly disallowed, with the exception of the Decoder::new_wrapped and Encoder::new_wrapped modes which provide fixed-width line wrapping.

Supported Base64 variants

• Standard Base64: [A-Z], [a-z], [0-9], +, /
• URL-safe Base64: [A-Z], [a-z], [0-9], -, _
• bcrypt Base64: ., /, [A-Z], [a-z], [0-9]
• crypt(3) Base64: ., -, [0-9], [A-Z], [a-z]

Minimum Supported Rust Version (MSRV) Policy

MSRV increases are not considered breaking changes and can happen in patch releases.

The crate MSRV accounts for all supported targets and crate feature combinations, excluding explicitly unstable features.

License

Licensed under either of:

• Apache License, Version 2.0
• MIT license

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

Usage

Allocating (enable alloc crate feature)

use base64ct::{Base64, Encoding};

let bytes = b"example bytestring!";
let encoded = Base64::encode_string(bytes);
assert_eq!(encoded, "ZXhhbXBsZSBieXRlc3RyaW5nIQ==");

let decoded = Base64::decode_vec(&encoded).unwrap();
assert_eq!(decoded, bytes);

Heapless no_std usage

use base64ct::{Base64, Encoding};

const BUF_SIZE: usize = 128;

let bytes = b"example bytestring!";
assert!(Base64::encoded_len(bytes) <= BUF_SIZE);

let mut enc_buf = [0u8; BUF_SIZE];
let encoded = Base64::encode(bytes, &mut enc_buf).unwrap();
assert_eq!(encoded, "ZXhhbXBsZSBieXRlc3RyaW5nIQ==");

let mut dec_buf = [0u8; BUF_SIZE];
let decoded = Base64::decode(encoded, &mut dec_buf).unwrap();
assert_eq!(decoded, bytes);

Implementation

Implemented using integer arithmetic alone without any lookup tables or data-dependent branches, thereby providing portable “best effort” constant-time operation.

Not constant-time with respect to message length (only data).

Adapted from the following constant-time C++ implementation of Base64:

https://github.com/Sc00bz/ConstTimeEncoding/blob/master/base64.cpp

Copyright (c) 2014 Steve “Sc00bz” Thomas (steve at tobtu dot com). Derived code is dual licensed MIT + Apache 2 (with permission from Sc00bz).

Structs

Base64

Standard Base64 encoding with = padding.

Base64Bcrypt

bcrypt Base64 encoding.

Base64Crypt

crypt(3) Base64 encoding.

Base64ShaCrypt

Little endian variant of the crypt(3) Base64 encoding.

Base64Unpadded

Standard Base64 encoding without padding.

Base64Url

URL-safe Base64 encoding with = padding.

Base64UrlUnpadded

URL-safe Base64 encoding without padding.

Decoder

Stateful Base64 decoder with support for buffered, incremental decoding.

Encoder

Stateful Base64 encoder with support for buffered, incremental encoding.

InvalidEncodingError

Invalid encoding of provided Base64 string.

InvalidLengthError

Insufficient output buffer length.

Enums

Error

Generic error, union of InvalidLengthError and InvalidEncodingError.

LineEnding

Line endings: variants of newline characters that can be used with Base64.

Traits

Encoding

Base64 encoding trait.