rfc:openssl_aead
Differences
This shows you the differences between two versions of the page.
Both sides previous revisionPrevious revisionNext revision | Previous revision | ||
rfc:openssl_aead [2016/01/04 13:41] – Add parameters description 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 provides functions for data encryption (openssl_encrypt) and decryption (openssl_decrypt). These function works fine for all cipher algorithms (cipher + mode) except | + | The PHP OpenSSL extension provides functions for data encryption (openssl_encrypt) and decryption (openssl_decrypt). These function works fine for all cipher algorithms (cipher + mode) except AEAD (Authenticated Encrypt with Associated Data) modes. These modes requires special handling in OpenSSL and a need for supplying resp. retrieving of the authenticated tag and optionally AAD (associated application data). |
- | 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. | + | 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 resp. openssl_decrypt for retrieving resp. supplying an authenticated tag and AAD. These parameters are optional and are used only for supported AEAD modes (GCM and CCM). The parameters differs | + | This RFC proposes adding extra parameters to the openssl_encrypt resp. openssl_decrypt for retrieving resp. supplying an authenticated tag and AAD. These parameters are optional and are used only for supported AEAD modes (GCM and CCM). If a tag is used for any modes that doesn' |
- | ==== Encryption | + | The parameters differs for each function. |
+ | |||
+ | === Encryption === | ||
The new prototype for openssl_encrypt is following: | The new prototype for openssl_encrypt is following: | ||
Line 21: | Line 23: | ||
<code php> | <code php> | ||
string openssl_encrypt ( string $data , string $method , string $password | string openssl_encrypt ( string $data , string $method , string $password | ||
- | [, int $options = 0 [, string $iv = "" | + | [, int $options = 0 [, string $iv = "" |
</ | </ | ||
- | == New parameters description | + | == 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 as supplied in the $tag_length parameter. | + | * $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 |
* $aad - Additional authentication data. | * $aad - Additional authentication data. | ||
- | * $tag_length - The tag length can be set before the encryption. The tag length | + | * $tag_length - The tag length can be set before the encryption |
- | ==== Decryption | + | === Decryption === |
The new prototype for openssl_decrypt is following: | The new prototype for openssl_decrypt is following: | ||
Line 40: | Line 42: | ||
- | == New parameters description | + | == New parameters description |
- | * $tag - The authentication tag that will be authenticated. If it's incorrect, then the function returns FALSE. | + | * $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. | * $aad - Additional authentication data. | ||
Line 76: | 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.1451914897.txt.gz · Last modified: 2017/09/22 13:28 (external edit)