| 1 |
NAME |
| 2 |
|
| 3 |
Crypt::URandom - Provide non blocking randomness |
| 4 |
|
| 5 |
VERSION |
| 6 |
|
| 7 |
This document describes Crypt::URandom version 0.55 |
| 8 |
|
| 9 |
SYNOPSIS |
| 10 |
|
| 11 |
use Crypt::URandom(); |
| 12 |
|
| 13 |
my $random_string_50_bytes_long = Crypt::URandom::urandom(50); |
| 14 |
|
| 15 |
OR |
| 16 |
|
| 17 |
use Crypt::URandom qw( urandom ); |
| 18 |
|
| 19 |
my $random_string_50_bytes_long = urandom(50); |
| 20 |
|
| 21 |
DESCRIPTION |
| 22 |
|
| 23 |
This Module is intended to provide an interface to the strongest |
| 24 |
available source of non-blocking randomness on the current platform. |
| 25 |
Platforms currently supported are anything supporting getrandom(2), |
| 26 |
/dev/urandom and versions of Windows greater than or equal to Windows |
| 27 |
2000. |
| 28 |
|
| 29 |
SUBROUTINES/METHODS |
| 30 |
|
| 31 |
urandom |
| 32 |
|
| 33 |
This function accepts an integer and returns a string of the same |
| 34 |
size filled with random data. It will throw an exception if the |
| 35 |
requested amount of random data is not returned. The first call will |
| 36 |
initialize the native cryptographic libraries (if necessary) and load |
| 37 |
all the required Perl libraries. This call is a buffered read on non |
| 38 |
Win32 platforms that do not support getrandom(2) or equivalent. |
| 39 |
|
| 40 |
urandom_ub |
| 41 |
|
| 42 |
This function accepts an integer and returns a string of the same |
| 43 |
size filled with random data. It will throw an exception if the |
| 44 |
requested amount of random data is not returned. The first call will |
| 45 |
initialize the native cryptographic libraries (if necessary) and load |
| 46 |
all the required Perl libraries. This call is a unbuffered sysread on |
| 47 |
non Win32 platforms that do not support getrandom(2) or equivalent. |
| 48 |
|
| 49 |
getrandom |
| 50 |
|
| 51 |
This function accepts an integer and returns a string of the same |
| 52 |
size filled with random data on platforms that implement |
| 53 |
getrandom(2). It will throw an exception if the requested amount of |
| 54 |
random data is not returned. This is NOT portable across all |
| 55 |
operating systems, but is made available if high-speed generation of |
| 56 |
random numbers is required. |
| 57 |
|
| 58 |
DIAGNOSTICS |
| 59 |
|
| 60 |
No secure alternative for random number generation for Win32 versions |
| 61 |
older than W2K |
| 62 |
|
| 63 |
The module cannot run on versions of Windows earlier than Windows |
| 64 |
2000 as there is no cryptographic functions provided by the operating |
| 65 |
system. |
| 66 |
|
| 67 |
Could not import CryptAcquireContext |
| 68 |
|
| 69 |
The module was unable to load the CryptAcquireContextA function from |
| 70 |
the advapi32 dynamic library. The advapi32 library cannot probably be |
| 71 |
loaded. |
| 72 |
|
| 73 |
CryptAcquireContext failed |
| 74 |
|
| 75 |
The module was unable to call the CryptAcquireContextA function from |
| 76 |
the advapi32 dynamic library. |
| 77 |
|
| 78 |
Could not import CryptGenRandom |
| 79 |
|
| 80 |
The module was unable to load the CryptGenRandom function from the |
| 81 |
advapi32 dynamic library. |
| 82 |
|
| 83 |
Could not import SystemFunction036 |
| 84 |
|
| 85 |
The module was unable to load the SystemFunction036 function from the |
| 86 |
advapi32 dynamic library. |
| 87 |
|
| 88 |
The length argument must be supplied and must be an integer |
| 89 |
|
| 90 |
The get method must be called with an integer argument to describe |
| 91 |
how many random bytes are required. |
| 92 |
|
| 93 |
CryptGenRandom failed |
| 94 |
|
| 95 |
The Windows 2000 CryptGenRandom method call failed to generate the |
| 96 |
required amount of randomness |
| 97 |
|
| 98 |
RtlGenRand failed |
| 99 |
|
| 100 |
The post Windows 2000 RtlGenRand method call failed to generate the |
| 101 |
required amount of randomness |
| 102 |
|
| 103 |
Only read n bytes from path |
| 104 |
|
| 105 |
The /dev/urandom device did not return the desired amount of random |
| 106 |
bytes |
| 107 |
|
| 108 |
Failed to read from path |
| 109 |
|
| 110 |
The /dev/urandom device returned an error when being read from |
| 111 |
|
| 112 |
Failed to open path |
| 113 |
|
| 114 |
The /dev/urandom device returned an error when being opened |
| 115 |
|
| 116 |
CONFIGURATION AND ENVIRONMENT |
| 117 |
|
| 118 |
Crypt::URandom requires no configuration files or environment |
| 119 |
variables. |
| 120 |
|
| 121 |
If the environment variable CRYPT_URANDOM_BUILD_DEBUG is specified when |
| 122 |
running perl Makefile.PL or make test AND getrandom(2) or it's |
| 123 |
equivalents cannot be detected, extra debug will be shown to show the |
| 124 |
failures to detect these functions. |
| 125 |
|
| 126 |
DEPENDENCIES |
| 127 |
|
| 128 |
If the platform is Win32, the Win32::API module will be required. |
| 129 |
Otherwise no other modules other than those provided by perl will be |
| 130 |
required |
| 131 |
|
| 132 |
INCOMPATIBILITIES |
| 133 |
|
| 134 |
None reported. |
| 135 |
|
| 136 |
BUGS AND LIMITATIONS |
| 137 |
|
| 138 |
To report a bug, or view the current list of bugs, please visit |
| 139 |
https://github.com/david-dick/crypt-urandom/issues |
| 140 |
|
| 141 |
AUTHOR |
| 142 |
|
| 143 |
David Dick <[email protected]> |
| 144 |
|
| 145 |
ACKNOWLEDGEMENTS |
| 146 |
|
| 147 |
The Win32::API code for interacting with Microsoft's CryptoAPI |
| 148 |
<https://en.wikipedia.org/wiki/Microsoft_CryptoAPI> was copied with |
| 149 |
extreme gratitude from Crypt::Random::Source::Strong::Win32 by Max |
| 150 |
Kanat-Alexander <https://metacpan.org/author/MKANAT> |
| 151 |
|
| 152 |
LICENSE AND COPYRIGHT |
| 153 |
|
| 154 |
Copyright (c) 2025, David Dick <[email protected]>. All rights reserved. |
| 155 |
|
| 156 |
This module is free software; you can redistribute it and/or modify it |
| 157 |
under the same terms as Perl itself. |
| 158 |
|
| 159 |
DISCLAIMER OF WARRANTY |
| 160 |
|
| 161 |
BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY |
| 162 |
FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT |
| 163 |
WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER |
| 164 |
PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, |
| 165 |
EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED |
| 166 |
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE |
| 167 |
ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH |
| 168 |
YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL |
| 169 |
NECESSARY SERVICING, REPAIR, OR CORRECTION. |
| 170 |
|
| 171 |
IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING |
| 172 |
WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR |
| 173 |
REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE LIABLE |
| 174 |
TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR |
| 175 |
CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE |
| 176 |
SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING |
| 177 |
RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A |
| 178 |
FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF |
| 179 |
SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH |
| 180 |
DAMAGES. |
| 181 |
|