Documentation and fix function output def

Author: Carlgo11

src/com/carlgo11/tempfiles/EncryptedFile.php

@@ -1,16 +1,14 @@
 <?php
 
-
 namespace com\carlgo11\tempfiles;
 
-
 use Exception;
 
 class EncryptedFile {
 
 	protected string $_blob;
-	protected string $_iv;
-	protected string $_tag;
+	protected array $_iv;
+	protected array $_tag;
 	protected string $_metadata;
 	protected string $_id;
 
@@ -57,11 +55,11 @@ public function getEncryptedFileContent(): string {
 		return $this->_blob;
 	}
 
-	public function getIV(): string {
+	public function getIV(): array {
 		return $this->_iv;
 	}
 
-	public function getTag(): string {
+	public function getTag(): array {
 		return $this->_tag;
 	}
 }

src/com/carlgo11/tempfiles/Encryption.php

@@ -16,24 +16,23 @@ class Encryption {
 	 *
 	 * @param string $content Data to encrypt.
 	 * @param string $password Password used to encrypt data.
-	 * @return array|false Returns encoded and encrypted file content.
-	 * @throws Exception
+	 * @return array Returns encoded and encrypted file content.
+	 * @throws Exception Throws {@see Exception} if encryption failed.
 	 * @global array $conf Configuration variables.
-	 * @since 2.3 Added support for AEAD cipher modes.
 	 * @since 2.0
+	 * @since 2.3 Added support for AEAD cipher modes.
 	 */
-	public static function encryptFileContent(string $content, string $password) {
+	public static function encryptFileContent(string $content, string $password): ?array {
 		global $conf;
 		$cipher = $conf['Encryption-Method'];
-		$iv = self::getIV($cipher);
-
+		$iv = self::createIV($cipher);
 		$data = base64_encode(openssl_encrypt($content, $cipher, $password, OPENSSL_RAW_DATA, $iv, $tag));
 
 		// Test if encrypted data is able to be decrypted
 		if (Encryption::decrypt(base64_decode($data), $password, bin2hex($iv), bin2hex($tag), OPENSSL_RAW_DATA) != FALSE)
 			return ['data' => $data, 'iv' => bin2hex($iv), 'tag' => bin2hex($tag)];
-		else error_log("Content encryption failed.");
-		return FALSE;
+		if (is_bool($data)) throw new Exception(openssl_error_string());
+		return NULL;
 	}
 
 	/**
@@ -42,11 +41,12 @@ public static function encryptFileContent(string $content, string $password) {
 	 *
 	 * @param string $cipher Encryption method to use.
 	 * @return string Returns an IV string encoded with base64.
-	 * @throws Exception
-	 * @since 2.3 Added support for variable IV length.
+	 * @throws Exception Throws {@see Exception} if unable to create IV
 	 * @since 2.0
+	 * @since 2.3 Added support for variable IV length.
+	 * @since 3.0 Rename getIV with createIV
 	 */
-	public static function getIV(string $cipher) {
+	public static function createIV(string $cipher): string {
 		$ivLength = openssl_cipher_iv_length($cipher);
 		return random_bytes($ivLength);
 	}
@@ -59,19 +59,18 @@ public static function getIV(string $cipher) {
 	 * @param string $iv IV for decryption.
 	 * @param string|null $tag AEAD tag from the data encryption.
 	 * @param array|null $options OPENSSL options.
-	 * @return string|bool Returns decrypted data or FALSE on failure.
-	 * @throws Exception
+	 * @return string Returns decrypted data.
+	 * @throws Exception Throws {@see Exception} if decryption failed.
 	 * @global array $conf Configuration variables.
 	 * @since 2.0
 	 * @since 2.3 Added support for AEAD cipher modes.
 	 * @since 2.4 Added ability to specify OPENSSL options.
 	 * @global array $conf Configuration variables.
 	 */
-	public static function decrypt(string $input, string $password, string $iv, string $tag = NULL, $options = NULL) {
+	public static function decrypt(string $input, string $password, string $iv, string $tag = NULL, $options = NULL): string {
 		global $conf;
 		$data = openssl_decrypt($input, $conf['Encryption-Method'], $password, $options, hex2bin($iv), hex2bin($tag));
-		if (is_bool($data)) throw new \Exception(openssl_error_string());
-
+		if (is_bool($data)) throw new Exception(openssl_error_string());
 		return $data;
 	}
 
@@ -81,34 +80,30 @@ public static function decrypt(string $input, string $password, string $iv, stri
 	 * @param array $metadata the $_FILES[] array to use.
 	 * @param string $deletionPassword Deletion password to encrypt along with the metadata.
 	 * @param string $password Password used to encrypt the data.
-	 * @return array|false
-	 * @throws Exception
+	 * @return array Returns array of [0 => encrypted string, 1 => encryption IV, 2 => encryption tag]
+	 * @throws Exception Throws {@see Exception} if encryption failed.
 	 * @since 2.0
 	 * @since 2.2 Added $deletionPassword to the array of things to encrypt.
 	 * @since 2.3 Added support for AEAD cipher modes.
 	 * @global array $conf Configuration variables.
 	 */
-	public static function encryptFileDetails(array $metadata, string $deletionPassword, string $password) {
+	public static function encryptFileDetails(array $metadata, string $deletionPassword, string $password): array {
 		global $conf;
 		$cipher = $conf['Encryption-Method'];
-		$iv = self::getIV($cipher);
+		$iv = self::createIV($cipher);
 
-		$data_array = [
+		$data = [
 			base64_encode($metadata['name']),
 			base64_encode($metadata['size']),
 			base64_encode($metadata['type']),
 			base64_encode($deletionPassword),
 		];
 
-		$data_string = implode(" ", $data_array);
-
-		$data_enc = base64_encode(openssl_encrypt($data_string, $cipher, $password, OPENSSL_RAW_DATA, $iv, $tag));
+		$encrypted_string = base64_encode(openssl_encrypt(implode(' ', $data), $cipher, $password, OPENSSL_RAW_DATA, $iv, $tag));
 
 		// Test if encrypted data is able to be decrypted
-		if (Encryption::decrypt(base64_decode($data_enc), $password, bin2hex($iv), bin2hex($tag), OPENSSL_RAW_DATA) != FALSE)
-			return ['data' => $data_enc, 'iv' => bin2hex($iv), 'tag' => bin2hex($tag)];
-
-		error_log("Metadata encryption failed.");
-		return FALSE;
+		if (Encryption::decrypt(base64_decode($encrypted_string), $password, bin2hex($iv), bin2hex($tag), OPENSSL_RAW_DATA) != FALSE)
+			return ['data' => $encrypted_string, 'iv' => bin2hex($iv), 'tag' => bin2hex($tag)];
+		throw new Exception(openssl_error_string());
 	}
 }

src/com/carlgo11/tempfiles/api/Cleanup.php

@@ -3,7 +3,6 @@
 namespace com\carlgo11\tempfiles\api;
 
 use com\carlgo11\tempfiles\datastorage\DataStorage;
-use com\carlgo11\tempfiles\exception\BadMethod;
 use Exception;
 
 class Cleanup extends API {

src/com/carlgo11/tempfiles/datastorage/DataStorage.php

@@ -39,7 +39,8 @@ public static function getFile(string $id, string $password): File {
 
 		$content = Encryption::decrypt(base64_decode($storedContent), $password, $storedEncryptionData['iv'][0], $storedEncryptionData['tag'][0]);
 		$metadata = explode(' ', Encryption::decrypt($storedMetaData, $password, $storedEncryptionData['iv'][1], $storedEncryptionData['tag'][1]));
-		$metadata = ['name' => $metadata[0],
+		$metadata = [
+			'name' => $metadata[0],
 			'size' => $metadata[1],
 			'type' => $metadata[2],
 			'delpass' => $metadata[3],

tests/com/carlgo11/tempfiles/EncryptionTest.php

@@ -11,7 +11,7 @@ class EncryptionTest extends TestCase
 	public function testGetIV() {
 		global $conf;
 		try {
-			$this->assertIsString(Encryption::getIV($conf['Encryption-Method']));
+			$this->assertIsString(Encryption::createIV($conf['Encryption-Method']));
 		} catch (Exception $e) {
 			error_log($e);
 			return FALSE;

tests/com/carlgo11/tempfiles/FileTest.php

@@ -23,7 +23,7 @@ public function __construct($name = NULL, array $data = [], $dataName = '') {
 	public function testSetIV() {
 		global $conf;
 		try {
-			$iv = [Encryption::getIV($conf['Encryption-Method']), Encryption::getIV($conf['Encryption-Method'])];
+			$iv = [Encryption::createIV($conf['Encryption-Method']), Encryption::createIV($conf['Encryption-Method'])];
 		} catch (Exception $e) {
 			error_log($e);
 			return FALSE;