rfc:openssl_aead
Differences
This shows you the differences between two versions of the page.
Next revision | Previous revision | ||
rfc:openssl_aead [2016/01/02 16:50] – Create initial version bukka | rfc:openssl_aead [2017/09/22 13:28] (current) – external edit 127.0.0.1 | ||
---|---|---|---|
Line 1: | Line 1: | ||
- | ====== PHP RFC: Your Title Here ====== | + | ====== PHP RFC: OpenSSL AEAD support |
- | * Version: 0.1 | + | * Version: 0.2 |
* Date: 2016-01-02 | * Date: 2016-01-02 | ||
* Author: Jakub Zelenka, bukka@php.net | * Author: Jakub Zelenka, bukka@php.net | ||
- | * Status: | + | * Status: |
===== Introduction ===== | ===== Introduction ===== | ||
- | The PHP OpenSSL extension | + | The PHP OpenSSL extension |
+ | |||
+ | There are two AEAD modes supported by OpenSSL (up to version 1.0.2) - GCM (Galois Counter Mode) and CCM (Counter with CBC-MAC). Both of these modes currently fails on decryption as there is no way how to supply an authentication tag and internal OpenSSL API doesn' | ||
===== Proposal ===== | ===== Proposal ===== | ||
- | This RFC proposes adding extra parameters to openssl_encrypt | + | This RFC proposes adding extra parameters to the openssl_encrypt |
+ | |||
+ | The parameters differs for each function. | ||
+ | |||
+ | === Encryption === | ||
+ | |||
+ | The new prototype for openssl_encrypt is following: | ||
+ | |||
+ | <code php> | ||
+ | string openssl_encrypt ( string $data , string $method , string $password | ||
+ | [, int $options = 0 [, string $iv = "" | ||
+ | </ | ||
+ | |||
+ | == New parameters description == | ||
+ | |||
+ | * $tag - The authentication tag will be saved to the variable passed as a reference on successful encryption. If the encryption fails, then the variable is unchanged. The resulted tag length is the same as the length supplied in the $tag_length parameter which default to 16. | ||
+ | * $aad - Additional authentication data. | ||
+ | * $tag_length - The tag length can be set before the encryption and can be between 4 and 16 for GCM mode where it is the same like trimming the tag. On the other side the CCM has no such limits and also the resulted tag is different for each length. | ||
+ | |||
+ | === Decryption === | ||
+ | |||
+ | The new prototype for openssl_decrypt is following: | ||
+ | |||
+ | <code php> | ||
+ | string openssl_decrypt ( string $data , string $method , string $password | ||
+ | [, int $options = 0 [, string $iv = "" | ||
+ | </ | ||
+ | |||
+ | |||
+ | == New parameters description == | ||
+ | * $tag - The authentication tag that will be authenticated. If it's incorrect, then the authentication fails and the function returns FALSE. | ||
+ | * $aad - Additional authentication data. | ||
===== Backward Incompatible Changes ===== | ===== Backward Incompatible Changes ===== | ||
Line 35: | Line 68: | ||
===== Open Issues ===== | ===== Open Issues ===== | ||
- | Default tag length and parameters order. | + | Tag length and parameters order. |
===== Unaffected PHP Functionality ===== | ===== Unaffected PHP Functionality ===== | ||
Line 45: | Line 78: | ||
Adding support for OCB mode once the extension supports OpenSSL 1.1 | Adding support for OCB mode once the extension supports OpenSSL 1.1 | ||
- | ===== Proposed | + | ===== Voting ===== |
- | 50%+1 majority | + | Required |
+ | |||
+ | <doodle title=" | ||
+ | * Yes | ||
+ | * No | ||
+ | </ | ||
+ | |||
+ | Voting started on January 20th at 17:00 UTC and ended on January 27th at 17:00 UTC. | ||
===== Patches and Tests ===== | ===== Patches and Tests ===== | ||
- | https:// | + | https:// |
===== Implementation ===== | ===== Implementation ===== | ||
- | After the project is implemented, | + | |
- | - the version(s) it was merged to | + | OpenSSL AEAD support has been implemented in PHP 7.1 with [[http:// |
- | | + | |
- | - a link to the PHP manual entry for the feature | + | The PHP language specification is not affected by this RFC. |
===== References ===== | ===== References ===== | ||
- | Links to external references, discussions or RFCs | + | * https:// |
===== Rejected Features ===== | ===== Rejected Features ===== | ||
- | Keep this updated with features | + | |
+ | There has been discussion about introducing an object | ||
+ | |||
+ | It's been suggested that new functions openssl_ecrypt_aead and openss_decrytp_aead should be introduced instead of adding new parameters to prevent confusion for users that tries to use a tag with non AEAD modes. That has been rejected in favour of adding warning when tag supplied for non AEAD modes. |
rfc/openssl_aead.txt · Last modified: 2017/09/22 13:28 by 127.0.0.1