rfc:improve_hash_hkdf_pramater
Differences
This shows you the differences between two versions of the page.
Both sides previous revisionPrevious revisionNext revision | Previous revisionLast revisionBoth sides next revision | ||
rfc:improve_hash_hkdf_pramater [2017/02/05 03:03] – yohgaki | rfc:improve_hash_hkdf_pramater [2017/02/05 06:52] – Correct typo in page name (rename) yohgaki | ||
---|---|---|---|
Line 1: | Line 1: | ||
- | ====== PHP RFC: Improve hash_hkdf() parameter order and handling ====== | + | Page name had typo and renamed during draft. |
- | * Version: 0.9 | + | See [[rfc::improve_hash_hkdf_parameter]] |
- | * Create Date: 2017-02-05 | + | |
- | * Author: Yasuo Ohgaki < | + | |
- | * Status: Draft (or Under Discussion or Accepted or Declined) | + | |
- | * First Published at: http:// | + | |
- | + | ||
- | ===== Introduction ===== | + | |
- | + | ||
- | HKDF is informational internet standard defined by [[https:// | + | |
- | + | ||
- | hash_hkdf() is added to master without RFC already. It has following signature currently. | + | |
- | + | ||
- | < | + | |
- | string hash_hkdf(string algo, string ikm [, int length = 0 [, string info = '' | + | |
- | </ | + | |
- | + | ||
- | Issue is parameter order and handling. | + | |
- | + | ||
- | RFC 5869 notes for HKDF users. It states, | + | |
- | + | ||
- | < | + | |
- | + | ||
- | **HKDF is defined to operate with and without random salt. This is | + | |
- | done to accommodate applications where a salt value is not available. | + | |
- | **We stress, however, that the use of **salt adds significantly to the | + | |
- | strength of HKDF**, ensuring independence between different uses of the | + | |
- | hash function, supporting " | + | |
- | strengthening the analytical results that back the HKDF design. | + | |
- | + | ||
- | Random salt differs fundamentally from the initial keying material in | + | |
- | two ways: it is non-secret and can be re-used. | + | |
- | are available to many applications. | + | |
- | number generator (PRNG) that continuously produces outputs by | + | |
- | applying HKDF to renewable pools of entropy (e.g., sampled system | + | |
- | events) can fix a salt value and use it for multiple applications of | + | |
- | HKDF without having to protect the secrecy of the salt. In a | + | |
- | different application domain, a key agreement protocol deriving | + | |
- | cryptographic keys from a Diffie-Hellman exchange can derive a salt | + | |
- | value from public nonces exchanged and authenticated between | + | |
- | communicating parties as part of the key agreement (this is the | + | |
- | approach taken in [IKEv2]). | + | |
- | + | ||
- | Ideally, the salt value is a random (or pseudorandom) string of the | + | |
- | length HashLen. | + | |
- | size or with limited entropy) may still make a significant | + | |
- | contribution to the security of the output keying material; designers | + | |
- | of applications are therefore encouraged to provide salt values to | + | |
- | HKDF if such values can be obtained by the application. | + | |
- | + | ||
- | It is worth noting that, while not the typical case, some | + | |
- | applications may even have a secret salt value available for use; in | + | |
- | such a case, HKDF provides an even stronger security guarantee. | + | |
- | example of such application is IKEv1 in its " | + | |
- | mode", where the " | + | |
- | are secret; similarly, the pre-shared mode of IKEv1 uses a secret | + | |
- | salt derived from the pre-shared key. | + | |
- | </ | + | |
- | + | ||
- | < | + | |
- | 3.2. The ' | + | |
- | + | ||
- | While the ' | + | |
- | often of great importance in applications**. | + | |
- | bind the derived key material to application- and context-specific | + | |
- | information. | + | |
- | algorithm identifiers, | + | |
- | prevent the derivation of the same keying material for different | + | |
- | contexts (when the same input key material (IKM) is used in such | + | |
- | different contexts). | + | |
- | the key expansion part, if so desired (e.g., an application may want | + | |
- | to bind the key material to its length L, thus making L part of the | + | |
- | ' | + | |
- | should be independent of the input key material value IKM. | + | |
- | </ | + | |
- | + | ||
- | As you can see from the RFC, it states even weak " | + | |
- | + | ||
- | The RFC described " | + | |
- | + | ||
- | As the RFC 3.1 states "HKDF is defined to operate with and without random salt. This is done to accommodate applications where a salt value is not available." | + | |
- | + | ||
- | The RFC describes " | + | |
- | + | ||
- | + | ||
- | ==== hash_hkdf() applications ===== | + | |
- | + | ||
- | This RFC only describes 2 examples, but there are many HKDF application. e.g. Object Store, etc. Developers must consider salt use for better security rather than omitting salt without proper consideration. | + | |
- | + | ||
- | === Per user data encryption === | + | |
- | + | ||
- | - Get the password hash generated by hash_password() for the user | + | |
- | - Get application secret salt stored in secure place. i.g. $_ENV | + | |
- | - Generate HKDF hash value with 1 and 2 by hash_hkdf() | + | |
- | - Encrypt the user data with the key from 3 | + | |
- | + | ||
- | Although " | + | |
- | + | ||
- | Suppose your application had SQL injection vulnerability and your data is stolen including password hash and encrypted user data. Secret encrypted data can be decrypted by attackers if salt is NOT used. | + | |
- | + | ||
- | See also **Security Note** section blow. The same technique can be used for per user encryption key. | + | |
- | + | ||
- | === CSRF token === | + | |
- | + | ||
- | When session ID is used for CSRF token, there is risk that session ID can leak to others by saving & sending HTML page, by malware web browser plugins that read page content, etc. Therefore, session ID should not be used as CSRF token. HKDF can be used to generate CSRF token belong to specific session with salt. | + | |
- | + | ||
- | Setting up CSRF token | + | |
- | - Get expiration timestamp as salt | + | |
- | - Generate HKDF value with 1 and session ID | + | |
- | - Send key from 2 and timestamp from 1 to browser as CSRF token | + | |
- | + | ||
- | Verifying CSRF token | + | |
- | - Get HKDF key and timestamp(salt) value from request | + | |
- | - Check if timestamp is not expired | + | |
- | - Generate HKDF value session ID and timestamp(salt) | + | |
- | - Compare HKDF value sent by browser and server generated HKDF value if it matches | + | |
- | + | ||
- | Secure CSRF token expiration can be defined with this method regardless of session ID lifetime. i.e. You can set short CSRF token expiration securely. | + | |
- | + | ||
- | ==Security Note== | + | |
- | Users must regenerate session ID periodically regardless of SSL usage for security reasons. Current OWASP recommends to regenerate rather short period. (Absolute timeout discussion is described in next section.) | + | |
- | + | ||
- | < | + | |
- | https:// | + | |
- | + | ||
- | Therefore, use of session ID as CSRF token key source is not recommended. You are better to use separate key for CSRF token generation in $_SESSION. e.g. $_SESSION[' | + | |
- | + | ||
- | ==Use of info parameter== | + | |
- | + | ||
- | " | + | |
- | + | ||
- | ===== Proposal ===== | + | |
- | + | ||
- | Internet RFC clearly recommends " | + | |
- | + | ||
- | Change hash_hkdf() from | + | |
- | + | ||
- | < | + | |
- | string hash_hkdf(string algo, string ikm [, int length = 0 [, string info = '' | + | |
- | </ | + | |
- | + | ||
- | to | + | |
- | + | ||
- | < | + | |
- | string hash_hkdf(string algo, string ikm, string salt [, string info = '' | + | |
- | - Set NULL to use without salt, raise exception for empty string. | + | |
- | - Note: length is only used for internal execution optimization. It will set to proper value according to inputs. | + | |
- | </ | + | |
- | + | ||
- | From user perspective, | + | |
- | Unlike " | + | |
- | + | ||
- | Typical PHP applications that need HKDF can use (or should use) salt for security reasons as examples above. Users should consider if salt can be used or not. If use of salt is impossible, then it should set to be empty. They shouldn' | + | |
- | + | ||
- | ===== Discussions ===== | + | |
- | + | ||
- | Discussions will be added later. | + | |
- | + | ||
- | ===== Backward Incompatible Changes ===== | + | |
- | + | ||
- | None. hash_hkdf() is new function. | + | |
- | + | ||
- | ===== Proposed PHP Version(s) ===== | + | |
- | + | ||
- | Next PHP 7.x | + | |
- | + | ||
- | ===== RFC Impact ===== | + | |
- | + | ||
- | None. | + | |
- | + | ||
- | ===== Open Issues ===== | + | |
- | + | ||
- | Please comment if any. | + | |
- | + | ||
- | ===== Unaffected PHP Functionality ===== | + | |
- | + | ||
- | Nothing is affected. hash_hkdf() is new function does not affect any. | + | |
- | + | ||
- | ===== Future Scope ===== | + | |
- | + | ||
- | Please comment if any | + | |
- | + | ||
- | ===== Proposed Voting Choices ===== | + | |
- | State whether this project requires a 2/3 | + | |
- | + | ||
- | + | ||
- | + | ||
- | ===== Patches and Tests ===== | + | |
- | + | ||
- | TBD | + | |
- | + | ||
- | ===== Implementation ===== | + | |
- | After the project is implemented, | + | |
- | - the version(s) it was merged to | + | |
- | - a link to the git commit(s) | + | |
- | - a link to the PHP manual entry for the feature | + | |
- | - a link to the language specification section (if any) | + | |
- | + | ||
- | ===== References ===== | + | |
- | Links to external references, discussions or RFCs | + | |
- | + | ||
- | ===== Rejected Features ===== | + | |
- | Keep this updated with features that were discussed on the mail lists. | + |
rfc/improve_hash_hkdf_pramater.txt · Last modified: 2017/09/22 13:28 by 127.0.0.1