Move \OCP\Security to PSR-4

6 files changed, 380 insertions, 0 deletions

diff --git a/lib/public/Security/IContentSecurityPolicyManager.php b/lib/public/Security/IContentSecurityPolicyManager.php
new file mode 100644
index 00000000000..10f1efe995f
--- /dev/null
+++ b/lib/public/Security/IContentSecurityPolicyManager.php
@@ -0,0 +1,50 @@
+<?php
+/**
+ * @author Lukas Reschke <lukas@owncloud.com>
+ *
+ * @copyright Copyright (c) 2016, ownCloud, Inc.
+ * @license AGPL-3.0
+ *
+ * This code is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License, version 3,
+ * as published by the Free Software Foundation.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License, version 3,
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>
+ *
+ */
+
+namespace OCP\Security;
+use OCP\AppFramework\Http\EmptyContentSecurityPolicy;
+
+/**
+ * Used for Content Security Policy manipulations
+ *
+ * @package OCP\Security
+ * @since 9.0.0
+ */
+interface IContentSecurityPolicyManager {
+	/**
+	 * Allows to inject something into the default content policy. This is for
+	 * example useful when you're injecting Javascript code into a view belonging
+	 * to another controller and cannot modify its Content-Security-Policy itself.
+	 * Note that the adjustment is only applied to applications that use AppFramework
+	 * controllers.
+	 *
+	 * To use this from your `app.php` use `\OC::$server->getContentSecurityPolicyManager()->addDefaultPolicy($policy)`,
+	 * $policy has to be of type `\OCP\AppFramework\Http\ContentSecurityPolicy`.
+	 *
+	 * WARNING: Using this API incorrectly may make the instance more insecure.
+	 * Do think twice before adding whitelisting resources. Please do also note
+	 * that it is not possible to use the `disallowXYZ` functions.
+	 *
+	 * @param EmptyContentSecurityPolicy $policy
+	 * @since 9.0.0
+	 */
+	public function addDefaultPolicy(EmptyContentSecurityPolicy $policy);
+}
diff --git a/lib/public/Security/ICredentialsManager.php b/lib/public/Security/ICredentialsManager.php
new file mode 100644
index 00000000000..d576bbcfbd8
--- /dev/null
+++ b/lib/public/Security/ICredentialsManager.php
@@ -0,0 +1,71 @@
+<?php
+/**
+ * @author Robin McCorkell <robin@mccorkell.me.uk>
+ *
+ * @copyright Copyright (c) 2016, ownCloud, Inc.
+ * @license AGPL-3.0
+ *
+ * This code is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License, version 3,
+ * as published by the Free Software Foundation.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License, version 3,
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>
+ *
+ */
+
+namespace OCP\Security;
+
+/**
+ * Store and retrieve credentials for external services
+ *
+ * @package OCP\Security
+ * @since 8.2.0
+ */
+interface ICredentialsManager {
+
+	/**
+	 * Store a set of credentials
+	 *
+	 * @param string|null $userId Null for system-wide credentials
+	 * @param string $identifier
+	 * @param mixed $credentials
+	 * @since 8.2.0
+	 */
+	public function store($userId, $identifier, $credentials);
+
+	/**
+	 * Retrieve a set of credentials
+	 *
+	 * @param string|null $userId Null for system-wide credentials
+	 * @param string $identifier
+	 * @return mixed
+	 * @since 8.2.0
+	 */
+	public function retrieve($userId, $identifier);
+
+	/**
+	 * Delete a set of credentials
+	 *
+	 * @param string|null $userId Null for system-wide credentials
+	 * @param string $identifier
+	 * @return int rows removed
+	 * @since 8.2.0
+	 */
+	public function delete($userId, $identifier);
+
+	/**
+	 * Erase all credentials stored for a user
+	 *
+	 * @param string $userId
+	 * @return int rows removed
+	 * @since 8.2.0
+	 */
+	public function erase($userId);
+
+}
diff --git a/lib/public/Security/ICrypto.php b/lib/public/Security/ICrypto.php
new file mode 100644
index 00000000000..62f27017ab7
--- /dev/null
+++ b/lib/public/Security/ICrypto.php
@@ -0,0 +1,64 @@
+<?php
+/**
+ * @author Lukas Reschke <lukas@owncloud.com>
+ * @author Morris Jobke <hey@morrisjobke.de>
+ *
+ * @copyright Copyright (c) 2016, ownCloud, Inc.
+ * @license AGPL-3.0
+ *
+ * This code is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License, version 3,
+ * as published by the Free Software Foundation.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License, version 3,
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>
+ *
+ */
+
+namespace OCP\Security;
+
+/**
+ * Class Crypto provides a high-level encryption layer using AES-CBC. If no key has been provided
+ * it will use the secret defined in config.php as key. Additionally the message will be HMAC'd.
+ *
+ * Usage:
+ * $encryptWithDefaultPassword = \OC::$server->getCrypto()->encrypt('EncryptedText');
+ * $encryptWithCustomPassword = \OC::$server->getCrypto()->encrypt('EncryptedText', 'password');
+ *
+ * @package OCP\Security
+ * @since 8.0.0
+ */
+interface ICrypto {
+
+	/**
+	 * @param string $message The message to authenticate
+	 * @param string $password Password to use (defaults to `secret` in config.php)
+	 * @return string Calculated HMAC
+	 * @since 8.0.0
+	 */
+	public function calculateHMAC($message, $password = '');
+
+	/**
+	 * Encrypts a value and adds an HMAC (Encrypt-Then-MAC)
+	 * @param string $plaintext
+	 * @param string $password Password to encrypt, if not specified the secret from config.php will be taken
+	 * @return string Authenticated ciphertext
+	 * @since 8.0.0
+	 */
+	public function encrypt($plaintext, $password = '');
+
+	/**
+	 * Decrypts a value and verifies the HMAC (Encrypt-Then-Mac)
+	 * @param string $authenticatedCiphertext
+	 * @param string $password Password to encrypt, if not specified the secret from config.php will be taken
+	 * @return string plaintext
+	 * @throws \Exception If the HMAC does not match
+	 * @since 8.0.0
+	 */
+	public function decrypt($authenticatedCiphertext, $password = '');
+}
diff --git a/lib/public/Security/IHasher.php b/lib/public/Security/IHasher.php
new file mode 100644
index 00000000000..39ba5094b12
--- /dev/null
+++ b/lib/public/Security/IHasher.php
@@ -0,0 +1,65 @@
+<?php
+/**
+ * @author Lukas Reschke <lukas@owncloud.com>
+ * @author Morris Jobke <hey@morrisjobke.de>
+ *
+ * @copyright Copyright (c) 2016, ownCloud, Inc.
+ * @license AGPL-3.0
+ *
+ * This code is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License, version 3,
+ * as published by the Free Software Foundation.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License, version 3,
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>
+ *
+ */
+
+namespace OCP\Security;
+
+/**
+ * Class Hasher provides some basic hashing functions. Furthermore, it supports legacy hashes
+ * used by previous versions of ownCloud and helps migrating those hashes to newer ones.
+ *
+ * The hashes generated by this class are prefixed (version|hash) with a version parameter to allow possible
+ * updates in the future.
+ * Possible versions:
+ * 	- 1 (Initial version)
+ *
+ * Usage:
+ * // Hashing a message
+ * $hash = \OC::$server->getHasher()->hash('MessageToHash');
+ * // Verifying a message - $newHash will contain the newly calculated hash
+ * $newHash = null;
+ * var_dump(\OC::$server->getHasher()->verify('a', '86f7e437faa5a7fce15d1ddcb9eaeaea377667b8', $newHash));
+ * var_dump($newHash);
+ *
+ * @package OCP\Security
+ * @since 8.0.0
+ */
+interface IHasher {
+	/**
+	 * Hashes a message using PHP's `password_hash` functionality.
+	 * Please note that the size of the returned string is not guaranteed
+	 * and can be up to 255 characters.
+	 *
+	 * @param string $message Message to generate hash from
+	 * @return string Hash of the message with appended version parameter
+	 * @since 8.0.0
+	 */
+	public function hash($message);
+
+	/**
+	 * @param string $message Message to verify
+	 * @param string $hash Assumed hash of the message
+	 * @param null|string &$newHash Reference will contain the updated hash if necessary. Update the existing hash with this one.
+	 * @return bool Whether $hash is a valid hash of $message
+	 * @since 8.0.0
+	 */
+	public function verify($message, $hash, &$newHash = null);
+}
diff --git a/lib/public/Security/ISecureRandom.php b/lib/public/Security/ISecureRandom.php
new file mode 100644
index 00000000000..9b346afe680
--- /dev/null
+++ b/lib/public/Security/ISecureRandom.php
@@ -0,0 +1,83 @@
+<?php
+/**
+ * @author Lukas Reschke <lukas@owncloud.com>
+ * @author Morris Jobke <hey@morrisjobke.de>
+ *
+ * @copyright Copyright (c) 2016, ownCloud, Inc.
+ * @license AGPL-3.0
+ *
+ * This code is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License, version 3,
+ * as published by the Free Software Foundation.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License, version 3,
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>
+ *
+ */
+
+namespace OCP\Security;
+
+/**
+ * Class SecureRandom provides a wrapper around the random_int function to generate
+ * secure random strings. For PHP 7 the native CSPRNG is used, older versions do
+ * use a fallback.
+ *
+ * Usage:
+ * \OC::$server->getSecureRandom()->generate(10);
+ *
+ * @package OCP\Security
+ * @since 8.0.0
+ */
+interface ISecureRandom {
+
+	/**
+	 * Flags for characters that can be used for <code>generate($length, $characters)</code>
+	 */
+	const CHAR_UPPER = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ';
+	const CHAR_LOWER = 'abcdefghijklmnopqrstuvwxyz';
+	const CHAR_DIGITS = '0123456789';
+	const CHAR_SYMBOLS = '!\"#$%&\\\'()* +,-./:;<=>?@[\]^_`{|}~';
+
+	/**
+	 * Convenience method to get a low strength random number generator.
+	 *
+	 * Low Strength should be used anywhere that random strings are needed
+	 * in a non-cryptographical setting. They are not strong enough to be
+	 * used as keys or salts. They are however useful for one-time use tokens.
+	 *
+	 * @return $this
+	 * @since 8.0.0
+	 * @deprecated 9.0.0 Use \OC\Security\SecureRandom::generate directly or random_bytes() / random_int()
+	 */
+	public function getLowStrengthGenerator();
+
+	/**
+	 * Convenience method to get a medium strength random number generator.
+	 *
+	 * Medium Strength should be used for most needs of a cryptographic nature.
+	 * They are strong enough to be used as keys and salts. However, they do
+	 * take some time and resources to generate, so they should not be over-used
+	 *
+	 * @return $this
+	 * @since 8.0.0
+	 * @deprecated 9.0.0 Use \OC\Security\SecureRandom::generate directly or random_bytes() / random_int()
+	 */
+	public function getMediumStrengthGenerator();
+
+	/**
+	 * Generate a random string of specified length.
+	 * @param int $length The length of the generated string
+	 * @param string $characters An optional list of characters to use if no character list is
+	 * 							specified all valid base64 characters are used.
+	 * @return string
+	 * @since 8.0.0
+	 */
+	public function generate($length,
+							 $characters = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/');
+
+}
diff --git a/lib/public/Security/StringUtils.php b/lib/public/Security/StringUtils.php
new file mode 100644
index 00000000000..ff1e290315a
--- /dev/null
+++ b/lib/public/Security/StringUtils.php
@@ -0,0 +1,47 @@
+<?php
+/**
+ * @author Lukas Reschke <lukas@owncloud.com>
+ * @author Morris Jobke <hey@morrisjobke.de>
+ *
+ * @copyright Copyright (c) 2016, ownCloud, Inc.
+ * @license AGPL-3.0
+ *
+ * This code is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License, version 3,
+ * as published by the Free Software Foundation.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License, version 3,
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>
+ *
+ */
+
+
+namespace OCP\Security;
+
+/**
+ * Class StringUtils
+ *
+ * @package OCP\Security
+ * @since 8.0.0
+ */
+class StringUtils {
+	/**
+	 * Compares whether two strings are equal. To prevent guessing of the string
+	 * length this is done by comparing two hashes against each other and afterwards
+	 * a comparison of the real string to prevent against the unlikely chance of
+	 * collisions.
+	 * @param string $expected The expected value
+	 * @param string $input The input to compare against
+	 * @return bool True if the two strings are equal, otherwise false.
+	 * @since 8.0.0
+	 * @deprecated 9.0.0 Use hash_equals
+	 */
+	public static function equals($expected, $input) {
+		return hash_equals($expected, $input);
+	}
+}