Skip to content

Commit

Permalink
Make the RATIONALE a little more useful.
Browse files Browse the repository at this point in the history
  • Loading branch information
paragonie-security committed Nov 7, 2016
1 parent 7ff464d commit 79122b8
Showing 1 changed file with 9 additions and 7 deletions.
16 changes: 9 additions & 7 deletions RATIONALE.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
## Errata (Design Decisions)
## Rationale (Design Decisions)

### Reasoning Behind the Order of Preferred Random Data Sources

Expand All @@ -14,18 +14,20 @@ method on all OSes, but libsodium is not very widely installed, so other
fallbacks are available.

Next, we read `/dev/urandom` (if it exists). This is the preferred file to read
for random data for cryptographic purposes for BSD and Linux.
for random data for cryptographic purposes for BSD and Linux. This step
is skipped on Windows, because someone could create a `C:\dev\urandom`
file and PHP would helpfully (but insecurely) return bytes from it.

Despite [strongly urging people not to use mcrypt in their projects](https://paragonie.com/blog/2015/05/if-you-re-typing-word-mcrypt-into-your-code-you-re-doing-it-wrong),
because libmcrypt is abandonware and the API puts too much responsibility on the
implementor, we prioritize `mcrypt_create_iv()` with `MCRYPT_DEV_URANDOM` above
Despite [strongly urging people not to use mcrypt in their projects](https://paragonie.com/blog/2015/05/if-you-re-typing-word-mcrypt-into-your-code-you-re-doing-it-wrong)
(because libmcrypt is abandonware and the API puts too much responsibility on the
implementor) we prioritize `mcrypt_create_iv()` with `MCRYPT_DEV_URANDOM` above
the remaining implementations.

The reason is simple: `mcrypt_create_iv()` is part of PHP's `ext/mcrypt` code,
and is not part `libmcrypt`. It actually does the right thing:

* On Unix-based operating systems, it reads from `/dev/urandom`, which unlike `/dev/random`
is the sane and correct thing to do.
* On Unix-based operating systems, it reads from `/dev/urandom` which
(unlike `/dev/random`) is the sane and correct thing to do.
* On Windows, it reads from `CryptGenRandom`, which is an exclusively Windows
way to get random bytes.

Expand Down

0 comments on commit 79122b8

Please sign in to comment.