| Alex Gaynor | 2a70f91 | 2014-02-06 09:47:07 -0800 | [diff] [blame] | 1 | Random number generation |
| 2 | ======================== |
| 3 | |
| 4 | When generating random data for use in cryptographic operations, such as an |
| 5 | initialization vector for encryption in |
| 6 | :class:`~cryptography.hazmat.primitives.ciphers.modes.CBC` mode, you do not |
| 7 | want to use the standard :mod:`random` module APIs. This is because they do not |
| Alex Gaynor | cb15716 | 2014-02-06 10:27:48 -0800 | [diff] [blame] | 8 | provide a cryptographically secure random number generator, which can result in |
| 9 | major security issues depending on the algorithms in use. |
| Alex Gaynor | 2a70f91 | 2014-02-06 09:47:07 -0800 | [diff] [blame] | 10 | |
| Alex Gaynor | 3e4729a | 2014-02-25 14:12:35 -0800 | [diff] [blame] | 11 | Therefore, it is our recommendation to `always use your operating system's |
| 12 | provided random number generator`_, which is available as ``os.urandom()``. For |
| Alex Gaynor | 2a70f91 | 2014-02-06 09:47:07 -0800 | [diff] [blame] | 13 | example, if you need 16 bytes of random data for an initialization vector, you |
| 14 | can obtain them with: |
| 15 | |
| Alex Stapleton | faf305b | 2014-07-12 12:27:37 +0100 | [diff] [blame] | 16 | .. doctest:: |
| Alex Gaynor | 2a70f91 | 2014-02-06 09:47:07 -0800 | [diff] [blame] | 17 | |
| 18 | >>> import os |
| Alex Gaynor | 6e1fa9b | 2014-07-12 09:52:59 -0700 | [diff] [blame] | 19 | >>> iv = os.urandom(16) |
| Alex Gaynor | 3e4729a | 2014-02-25 14:12:35 -0800 | [diff] [blame] | 20 | |
| Alex Gaynor | 2d6bb0b | 2014-12-18 21:31:28 -0800 | [diff] [blame^] | 21 | This will use ``/dev/urandom`` on UNIX platforms, and ``CryptGenRandom`` on |
| 22 | Windows. |
| 23 | |
| Alex Gaynor | 3e4729a | 2014-02-25 14:12:35 -0800 | [diff] [blame] | 24 | .. _`always use your operating system's provided random number generator`: http://sockpuppet.org/blog/2014/02/25/safely-generate-random-numbers/ |