ya-rand 2.0.2

A crate for simple and fast random number generation
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91

/*!
Provides the [`Encoder`] trait, as well as concrete implementations of the
[RFC 4648] encodings and alphanumeric encoding.

[RFC 4648]: https://datatracker.ietf.org/doc/html/rfc4648
*/

use crate::rng::ALPHANUMERIC;

/// Specifies parameters for encoding random data into a valid UTF-8 `String`.
///
/// All provided implementations list their minimum secure length
/// in the documentation of their unit struct, and it is highly recommended
/// that custom implementations all do the same.
///
/// # Safety
///
/// The `CHARSET` field must only contain valid ascii characters,
/// meaning that all u8 values must be in the interval [0, 128).
/// Failure to uphold this condition will result in generation of
/// invalid `String` values.
///
/// The `MIN_LEN` field must be at least ceil(log<sub>`base`</sub>(2<sup>128</sup>)),
/// where `base` is the length of the `CHARSET` field. Failure to uphold
/// this condition will result in poor security of generated `String` values.
pub unsafe trait Encoder {
    /// The character set of the encoder implementation.
    ///
    /// See trait-level docs for safety comments.
    const CHARSET: &[u8];

    /// Shortest length `String` that will contain at least 128 bits
    /// of randomness.
    ///
    /// See trait-level docs for safety comments.
    const MIN_LEN: usize;
}

/// Base64 encoding, as specified by RFC 4648.
///
/// Minimum secure length is 22.
pub struct Base64;
unsafe impl Encoder for Base64 {
    const CHARSET: &[u8] = b"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
    const MIN_LEN: usize = 22;
}

/// Base64 (URLs and filenames) encoding, as specified by RFC 4648.
///
/// Minimum secure length is 22.
pub struct Base64Url;
unsafe impl Encoder for Base64Url {
    const CHARSET: &[u8] = b"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";
    const MIN_LEN: usize = 22;
}

/// Base62 (alphanumeric) encoding.
///
/// Minimum secure length is 22.
pub struct Base62;
unsafe impl Encoder for Base62 {
    const CHARSET: &[u8] = ALPHANUMERIC;
    const MIN_LEN: usize = 22;
}

/// Base32 encoding, as specified by RFC 4648.
///
/// Minimum secure length is 26.
pub struct Base32;
unsafe impl Encoder for Base32 {
    const CHARSET: &[u8] = b"ABCDEFGHIJKLMNOPQRSTUVWXYZ234567";
    const MIN_LEN: usize = 26;
}

/// Base32 (extended hexidecimal) encoding, as specified by RFC 4648.
///
/// Minimum secure length is 26.
pub struct Base32Hex;
unsafe impl Encoder for Base32Hex {
    const CHARSET: &[u8] = b"0123456789ABCDEFGHIJKLMNOPQRSTUV";
    const MIN_LEN: usize = 26;
}

/// Base16 (hexidecimal) encoding, as specified by RFC 4648.
///
/// Minimum secure length is 32.
pub struct Base16;
unsafe impl Encoder for Base16 {
    const CHARSET: &[u8] = b"0123456789ABCDEF";
    const MIN_LEN: usize = 32;
}