Debian Codegraph @

README

raw
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