diff options
Diffstat (limited to 'README')
| -rw-r--r-- | README | 46 |
1 files changed, 35 insertions, 11 deletions
@@ -196,17 +196,41 @@ packages for qpdf enable this option, for example. Random Number Generation ======================== -When the qpdf detects either the Windows cryptography API or the -existence of /dev/urandom, /dev/arandom, or /dev/random, it uses them -to generate cryptography secure random numbers. If none of these -conditions are true, the build will fail with an error. It is -possible to configure qpdf with the --enable-insecure-random option, -in which case it will generate random numbers with stdlib's random() -or rand() calls instead. These random numbers are not cryptography -secure, but the qpdf library is fully functional using them. Using -non-secure random numbers means that it's easier in some cases to -guess encryption keys. If you're not generating encrypted files, -there's no advantage to using secure random numbers. +By default, when the qpdf detects either the Windows cryptography API +or the existence of /dev/urandom, /dev/arandom, or /dev/random, it +uses them to generate cryptography secure random numbers. If none of +these conditions are true, the build will fail with an error. This +behavior can be modified in several ways: + + * If you configure with --disable-os-secure-random or define + SKIP_OS_SECURE_RANDOM, qpdf will not attempt to use Windows + cryptography or the random device. You must either supply your own + random data provider or allow use of insecure random numbers. + + * If you configure qpdf with the --enable-insecure-random option or + define USE_INSECURE_RANDOM, qpdf will try insecure random numbers + if OS-provided secure random numbers are disabled. This is not a + fallback. In order for insecure random numbers to be used, you + must also disable OS secure random numbers since, otherwise, + failure to find OS secure random numbers is a compile error. The + insecure random number source is stdlib's random() or rand() calls. + These random numbers are not cryptography secure, but the qpdf + library is fully functional using them. Using non-secure random + numbers means that it's easier in some cases to guess encryption + keys. If you're not generating encrypted files, there's no + advantage to using secure random numbers. + + * In all cases, you may supply your own random data provider. To do + this, derive a class from qpdf/RandomDataProvider (since 5.1.0) and + call QUtil::setRandomDataProvider before you create any QPDF + objects. If you supply your own random data provider, it will + always be used even if support for one of the other random data + providers is compiled in. If you wish to avoid any possibility of + your build of qpdf from using anything but a user-supplied random + data provider, you can define SKIP_OS_SECURE_RANDOM and not + USE_INSECURE_RANDOM. In this case, qpdf will throw a runtime error + if any attempt is made to generate random numbers and no random + data provider has been supplied. If you are building qpdf on a platform that qpdf doesn't know how to generate secure random numbers on, a patch would be welcome. |