1 <?php
2 /**
3 * @package FrameworkOnFramework
4 * @subpackage utils
5 * @copyright Copyright (C) 2010-2016 Nicholas K. Dionysopoulos / Akeeba Ltd. All rights reserved.
6 * @license GNU General Public License version 2 or later; see LICENSE.txt
7 */
8
9 // Protect from unauthorized access
10 defined('FOF_INCLUDED') or die;
11
12 /**
13 * Interface for AES encryption adapters
14 */
15 interface FOFEncryptAesInterface
16 {
17 /**
18 * Sets the AES encryption mode.
19 *
20 * WARNING: The strength is deprecated as it has a different effect in MCrypt and OpenSSL. MCrypt was abandoned in
21 * 2003 before the Rijndael-128 algorithm was officially the Advanced Encryption Standard (AES). MCrypt also offered
22 * Rijndael-192 and Rijndael-256 algorithms with different block sizes. These are NOT used in AES. OpenSSL, however,
23 * implements AES correctly. It always uses a 128-bit (16 byte) block. The 192 and 256 bit strengths refer to the
24 * key size, not the block size. Therefore using different strengths in MCrypt and OpenSSL will result in different
25 * and incompatible ciphertexts.
26 *
27 * TL;DR: Always use $strength = 128!
28 *
29 * @param string $mode Choose between CBC (recommended) or ECB
30 * @param int $strength Bit strength of the key (128, 192 or 256 bits). DEPRECATED. READ NOTES ABOVE.
31 *
32 * @return mixed
33 */
34 public function setEncryptionMode($mode = 'cbc', $strength = 128);
35
36 /**
37 * Encrypts a string. Returns the raw binary ciphertext.
38 *
39 * WARNING: The plaintext is zero-padded to the algorithm's block size. You are advised to store the size of the
40 * plaintext and trim the string to that length upon decryption.
41 *
42 * @param string $plainText The plaintext to encrypt
43 * @param string $key The raw binary key (will be zero-padded or chopped if its size is different than the block size)
44 * @param null|string $iv The initialization vector (for CBC mode algorithms)
45 *
46 * @return string The raw encrypted binary string.
47 */
48 public function encrypt($plainText, $key, $iv = null);
49
50 /**
51 * Decrypts a string. Returns the raw binary plaintext.
52 *
53 * $ciphertext MUST start with the IV followed by the ciphertext, even for EBC data (the first block of data is
54 * dropped in EBC mode since there is no concept of IV in EBC).
55 *
56 * WARNING: The returned plaintext is zero-padded to the algorithm's block size during encryption. You are advised
57 * to trim the string to the original plaintext's length upon decryption. While rtrim($decrypted, "\0") sounds
58 * appealing it's NOT the correct approach for binary data (zero bytes may actually be part of your plaintext, not
59 * just padding!).
60 *
61 * @param string $cipherText The ciphertext to encrypt
62 * @param string $key The raw binary key (will be zero-padded or chopped if its size is different than the block size)
63 *
64 * @return string The raw unencrypted binary string.
65 */
66 public function decrypt($cipherText, $key);
67
68 /**
69 * Returns the encryption block size in bytes
70 *
71 * @return int
72 */
73 public function getBlockSize();
74
75 /**
76 * Is this adapter supported?
77 *
78 * @param FOFUtilsPhpfunc $phpfunc
79 *
80 * @return bool
81 */
82 public function isSupported(FOFUtilsPhpfunc $phpfunc = null);
83 }