rfc:openssl_aead
Differences
This shows you the differences between two versions of the page.
Both sides previous revisionPrevious revision | Next revisionBoth sides next revision | ||
rfc:openssl_aead [2016/01/06 14:51] – Change status bukka | rfc:openssl_aead [2016/01/10 17:08] – Clarify and add info about warning for supplying tag when mode is not AEAD. bukka | ||
---|---|---|---|
Line 1: | Line 1: | ||
====== PHP RFC: OpenSSL AEAD support ====== | ====== 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 | ||
Line 7: | Line 7: | ||
===== 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 and there are some internal OpenSSL API that doesn' | + | 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 for each function. | + | 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' |
+ | |||
+ | The parameters differs for each function. | ||
=== Encryption === | === Encryption === | ||
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 === | ||
Line 42: | Line 44: | ||
== 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 94: | Line 96: | ||
There has been discussion about introducing an object that would wrap the context and offered functions for setting tag, AAD, key, IV and making partials updates. However such functionality is already implemented in crypto extension and requires much more code (about extra 1000 lines) to address all possible exceptions. The main thing is that this is not contradicting to this proposal as it could easily co-exist as we will still have to keep openssl_ecrypt and openssl_decrypt working. This proposal is just about extending these two function for AEAD mode support. | There has been discussion about introducing an object that would wrap the context and offered functions for setting tag, AAD, key, IV and making partials updates. However such functionality is already implemented in crypto extension and requires much more code (about extra 1000 lines) to address all possible exceptions. The main thing is that this is not contradicting to this proposal as it could easily co-exist as we will still have to keep openssl_ecrypt and openssl_decrypt working. This proposal is just about extending these two function for AEAD mode support. | ||
+ | |||
+ | 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