base64url_nopad 0.2.0

Fast, efficient, correct, and const base64url without padding encoding and decoding
Documentation

base64url_nopad

base64url_nopad is a library for fast, efficient, correct, and const encoding and decoding of base64url without padding data. All functions that can be const are const. Great care is made to ensure all arithmetic is free from "side effects" (e.g., overflow). panics are avoided at all costs unless explicitly documented including panics related to memory allocations.

base64url_nopad in action

use base64url_nopad::DecodeErr;
/// Length of our input to encode.
const INPUT_LEN: usize = 259;
/// The base64url-encoded value without padding of our input.
const ENCODED_VAL: &str = "AAECAwQFBgcICQoLDA0ODxAREhMUFRYXGBkaGxwdHh8gISIjJCUmJygpKissLS4vMDEyMzQ1Njc4OTo7PD0-P0BBQkNERUZHSElKS0xNTk9QUVJTVFVWV1hZWltcXV5fYGFiY2RlZmdoaWprbG1ub3BxcnN0dXZ3eHl6e3x9fn-AgYKDhIWGh4iJiouMjY6PkJGSk5SVlpeYmZqbnJ2en6ChoqOkpaanqKmqq6ytrq-wsbKztLW2t7i5uru8vb6_wMHCw8TFxsfIycrLzM3Oz9DR0tPU1dbX2Nna29zd3t_g4eLj5OXm5-jp6uvs7e7v8PHy8_T19vf4-fr7_P3-_1MH0Q";
fn main() -> Result<(), DecodeErr> {
    let mut input = [0; INPUT_LEN];
    for i in 0..=255 {
        input[usize::from(i)] = i;
    }
    input[256] = 83;
    input[257] = 7;
    input[258] = 209;
    let mut output = [0; base64url_nopad::encode_len(INPUT_LEN)];
    assert_eq!(base64url_nopad::encode_buffer(&input, &mut output), ENCODED_VAL);
    assert!(base64url_nopad::decode_len(output.len()).is_some_and(|len| len == INPUT_LEN));
    base64url_nopad::decode_buffer(ENCODED_VAL.as_bytes(), &mut output[..INPUT_LEN])?;
    assert_eq!(input, output[..INPUT_LEN]);
    Ok(())
}

Cargo "features"

alloc

Enables support for memory allocations via alloc.

Correctness of code

This library is written in a way that is free from any overflow, underflow, or other kinds of "arithmetic side effects". All functions that can panic are explicitly documented as such; and all possible panics are isolated to convenience functions that panic instead of error. Strict encoding and decoding is performed; thus if an input contains any invalid data, it is guaranteed to fail when decoding it (e.g., trailing non-zero bits).

Minimum Supported Rust Version (MSRV)

This will frequently be updated to be the same as stable. Specifically, any time stable is updated and that update has "useful" features or compilation no longer succeeds (e.g., due to new compiler lints), then MSRV will be updated.

MSRV changes will correspond to a SemVer patch version bump pre-1.0.0; otherwise a minor version bump.

SemVer Policy

  • All on-by-default features of this library are covered by SemVer
  • MSRV is considered exempt from SemVer as noted above

License

Licensed under either of

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.

Before any PR is sent, cargo clippy --all-targets, cargo test --all-targets -- --include-ignored, and cargo test --doc should be run for each possible combination of "features" using the stable and MSRV toolchains. One easy way to achieve this is by invoking ci-cargo as ci-cargo clippy --all-targets test --all-targets --include-ignored in the base64url_nopad directory.

Last, RUSTDOCFLAGS="--cfg docsrs" cargo +nightly doc --all-features should be run to ensure documentation can be built.

Status

The crate is only tested on the x86_64-unknown-linux-gnu, x86_64-unknown-openbsd, and aarch64-apple-darwin targets; but it should work on most platforms.