Description:
------------
---
From manual page: http://www.php.net/function.hash-pbkdf2#refsect1-function.hash-pbkdf2-parameters
---

The units that the length parameter is in is not documented. It's nibbles if $raw_output is true, and bytes otherwise. That needs to be documented in the length parameter section AND in one of those red warning things. I've already seen someone pass the byte count they wanted with raw_output set to false, making their application use 64-bit keys instead of 128-bit keys. That is a huge security problem and I expect many more people will screw it up. It NEEDS to be documented CLEARLY.

This definition of the length parameter actually violates the PBKDF2 specification, since the RFC formally defines the length parameter to be the number of bytes, not bits or nibbles.

Test script:
---------------
<?php
  // http://www.ietf.org/rfc/rfc6070.txt
  // this should output: 
  // DK = ea 6c 01 4d c7 2d 6f 8c
  //        cd 1e d9 2a ce 1d 41 f0
  //        d8 de 89 57             (20 octets)

  echo hash_pbkdf2("sha1", "password", "salt", 2, 20, false);
  // actual: ea6c014dc72d6f8ccd1e
?>

Expected result:
----------------
The documentation should make it very clear that the length parameter is either bytes or nibbles depending on the raw_output parameter.