Struct Profile

Source

pub struct Profile<A, const PAD: bool> { /* private fields */ }

Expand description

A named Base64 profile with an engine and optional strict line wrapping.

Profiles are convenience values for protocol-shaped Base64. They keep the same strict alphabet, padding, canonical-bit, and output-buffer rules as Engine, while carrying the wrapping policy for MIME/PEM-like formats.

Implementations§

Source §

impl<A, const PAD: bool> Profile<A, PAD>
where A: Alphabet,

Source

pub const fn new(engine: Engine<A, PAD>, wrap: Option<LineWrap>) -> Self

Creates a profile from an engine and optional strict line wrapping.

Source

pub const fn checked_new( engine: Engine<A, PAD>, wrap: Option<LineWrap>, ) -> Option<Self>

Creates a profile, returning None when the wrapping policy is invalid.

This is useful when a profile is assembled from configuration or other untrusted metadata. Use Self::new for compile-time constants where the wrapping policy is known to be valid.

Source

pub const fn is_valid(&self) -> bool

Returns whether this profile can be used by encoders and decoders.

Source

pub const fn engine(&self) -> Engine<A, PAD>

Returns the underlying engine.

Source

pub const fn is_padded(&self) -> bool

Returns whether this profile uses padded Base64.

Source

pub const fn is_wrapped(&self) -> bool

Returns whether this profile carries a strict line-wrapping policy.

Source

pub const fn line_wrap(&self) -> Option<LineWrap>

Returns the strict wrapping policy carried by this profile, if any.

Source

pub const fn line_len(&self) -> Option<usize>

Returns the encoded line length for wrapped profiles.

Source

pub const fn line_ending(&self) -> Option<LineEnding>

Returns the line ending for wrapped profiles.

Source

pub const fn encoded_len(&self, input_len: usize) -> Result<usize, EncodeError>

Returns the encoded length for this profile.

Source

pub const fn checked_encoded_len(&self, input_len: usize) -> Option<usize>

Returns the encoded length for this profile, or None on overflow or invalid line wrapping.

Source

pub fn decoded_len(&self, input: &[u8]) -> Result<usize, DecodeError>

Returns the exact decoded length for this profile.

Source

pub fn validate_result(&self, input: &[u8]) -> Result<(), DecodeError>

Validates input according to this profile without writing decoded bytes.

Source

pub fn validate(&self, input: &[u8]) -> bool

Returns whether input is valid for this profile.

Source

pub fn encode_slice( &self, input: &[u8], output: &mut [u8], ) -> Result<usize, EncodeError>

Encodes input into output according to this profile.

Source

pub fn encode_slice_clear_tail( &self, input: &[u8], output: &mut [u8], ) -> Result<usize, EncodeError>

Encodes input into output and clears all bytes after the encoded prefix.

Source

pub fn encode_buffer<const CAP: usize>( &self, input: &[u8], ) -> Result<EncodedBuffer<CAP>, EncodeError>

Encodes input into a stack-backed buffer.

This is useful for short values where heap allocation is unnecessary. If encoding fails, the internal backing array is cleared before the error is returned.

Source

pub fn decode_slice( &self, input: &[u8], output: &mut [u8], ) -> Result<usize, DecodeError>

Decodes input into output according to this profile.

§Security

Profile decoders use the normal strict decode path. They may branch or return early based on malformed input, padding position, wrapping, and output capacity in order to return precise DecodeError diagnostics, including exact invalid-byte values and positions. Do not use this method for token comparison, key-material decoding, or secret-bearing validation where malformed-input timing matters. Use crate::ct with a matching unwrapped engine for constant-time-oriented secret decoding.

Source

pub fn decode_slice_clear_tail( &self, input: &[u8], output: &mut [u8], ) -> Result<usize, DecodeError>

Decodes input into output and clears all bytes after the decoded prefix.

Source

pub fn decode_buffer<const CAP: usize>( &self, input: &[u8], ) -> Result<DecodedBuffer<CAP>, DecodeError>

Decodes input into a stack-backed buffer according to this profile.

This is useful for short decoded values where heap allocation is unnecessary. If decoding fails, the internal backing array is cleared before the error is returned.

Source

pub fn decode_in_place<'a>( &self, buffer: &'a mut [u8], ) -> Result<&'a mut [u8], DecodeError>

Decodes buffer in place according to this profile.

For wrapped profiles, configured line endings are compacted out before decoding. If validation fails, the buffer contents are unspecified. On success, bytes after the returned decoded prefix may retain compacted encoded input. Use Self::decode_in_place_clear_tail when the buffer may be reused or freed without a caller-managed wipe.

§Security

Profile in-place decoders use the normal strict decode path. They may branch or return early based on malformed input, padding position, wrapping, and output capacity in order to return precise DecodeError diagnostics. Do not use this method for token comparison, key-material decoding, or secret-bearing validation where malformed-input timing matters.

§Examples

use base64_ng::{LineEnding, LineWrap, Profile, STANDARD};

let profile = Profile::new(STANDARD, Some(LineWrap::new(4, LineEnding::Lf)));
let mut buffer = *b"aGVs\nbG8=";
let decoded = profile.decode_in_place(&mut buffer).unwrap();

assert_eq!(decoded, b"hello");

Source

pub fn decode_in_place_clear_tail<'a>( &self, buffer: &'a mut [u8], ) -> Result<&'a mut [u8], DecodeError>

Decodes buffer in place according to this profile and clears all bytes after the decoded prefix.

If validation or decoding fails, the entire buffer is cleared before the error is returned.

§Examples

use base64_ng::{LineEnding, LineWrap, Profile, STANDARD};

let profile = Profile::new(STANDARD, Some(LineWrap::new(4, LineEnding::Lf)));
let mut buffer = *b"aGVs\nbG8=";
let len = profile.decode_in_place_clear_tail(&mut buffer).unwrap().len();

assert_eq!(&buffer[..len], b"hello");
assert!(buffer[len..].iter().all(|byte| *byte == 0));

Source

pub fn encode_vec(&self, input: &[u8]) -> Result<Vec<u8>, EncodeError>

Encodes input into a newly allocated byte vector.

Source

pub fn encode_secret(&self, input: &[u8]) -> Result<SecretBuffer, EncodeError>

Encodes input into a redacted owned secret buffer.

Source

pub fn encode_string(&self, input: &[u8]) -> Result<String, EncodeError>

Encodes input into a newly allocated UTF-8 string.

Source

pub fn decode_vec(&self, input: &[u8]) -> Result<Vec<u8>, DecodeError>

Decodes input into a newly allocated byte vector.

Source

pub fn decode_secret(&self, input: &[u8]) -> Result<SecretBuffer, DecodeError>

Decodes input into a redacted owned secret buffer.

§Security

This uses the profile’s normal strict decoder, not the constant-time-oriented crate::ct module. It may branch or return early on malformed input and reports localized decode errors. For secret-bearing payloads where malformed-input timing matters, use the matching crate::ct::CtEngine explicitly and wrap successful output in SecretBuffer.