1 //! Utilities for secure random number generation.
2 //!
3 //! # Examples
4 //!
5 //! To generate a buffer with cryptographically strong bytes:
6 //!
7 //! ```
8 //! use openssl::rand::rand_bytes;
9 //!
10 //! let mut buf = [0; 256];
11 //! rand_bytes(&mut buf).unwrap();
12 //! ```
13 use libc::c_int;
14 
15 use crate::error::ErrorStack;
16 use crate::{cvt, LenType};
17 use openssl_macros::corresponds;
18 
19 /// Fill buffer with cryptographically strong pseudo-random bytes.
20 ///
21 /// # Examples
22 ///
23 /// To generate a buffer with cryptographically strong random bytes:
24 ///
25 /// ```
26 /// use openssl::rand::rand_bytes;
27 ///
28 /// let mut buf = [0; 256];
29 /// rand_bytes(&mut buf).unwrap();
30 /// ```
31 #[corresponds(RAND_bytes)]
rand_bytes(buf: &mut [u8]) -> Result<(), ErrorStack>32 pub fn rand_bytes(buf: &mut [u8]) -> Result<(), ErrorStack> {
33     unsafe {
34         ffi::init();
35         assert!(buf.len() <= c_int::max_value() as usize);
36         cvt(ffi::RAND_bytes(buf.as_mut_ptr(), buf.len() as LenType)).map(|_| ())
37     }
38 }
39 
40 /// Fill buffer with cryptographically strong pseudo-random bytes. It is
41 /// intended to be used for generating values that should remain private.
42 ///
43 /// # Examples
44 ///
45 /// To generate a buffer with cryptographically strong random bytes:
46 ///
47 /// ```
48 /// use openssl::rand::rand_priv_bytes;
49 ///
50 /// let mut buf = [0; 256];
51 /// rand_priv_bytes(&mut buf).unwrap();
52 /// ```
53 ///
54 /// Requires OpenSSL 1.1.1 or newer.
55 #[corresponds(RAND_priv_bytes)]
56 #[cfg(ossl111)]
rand_priv_bytes(buf: &mut [u8]) -> Result<(), ErrorStack>57 pub fn rand_priv_bytes(buf: &mut [u8]) -> Result<(), ErrorStack> {
58     unsafe {
59         ffi::init();
60         assert!(buf.len() <= c_int::max_value() as usize);
61         cvt(ffi::RAND_priv_bytes(buf.as_mut_ptr(), buf.len() as LenType)).map(|_| ())
62     }
63 }
64 
65 /// Controls random device file descriptor behavior.
66 ///
67 /// Requires OpenSSL 1.1.1 or newer.
68 #[corresponds(RAND_keep_random_devices_open)]
69 #[cfg(ossl111)]
keep_random_devices_open(keep: bool)70 pub fn keep_random_devices_open(keep: bool) {
71     unsafe {
72         ffi::RAND_keep_random_devices_open(keep as LenType);
73     }
74 }
75 
76 #[cfg(test)]
77 mod tests {
78     #[test]
test_rand_bytes()79     fn test_rand_bytes() {
80         let mut buf = [0; 32];
81         super::rand_bytes(&mut buf).unwrap();
82     }
83 
84     #[test]
85     #[cfg(ossl111)]
test_rand_priv_bytes()86     fn test_rand_priv_bytes() {
87         let mut buf = [0; 32];
88         super::rand_priv_bytes(&mut buf).unwrap();
89     }
90 }
91