aboutsummaryrefslogtreecommitdiffstats
path: root/lib/public/Security
diff options
context:
space:
mode:
Diffstat (limited to 'lib/public/Security')
-rw-r--r--lib/public/Security/Events/GenerateSecurePasswordEvent.php34
-rw-r--r--lib/public/Security/Events/ValidatePasswordPolicyEvent.php23
-rw-r--r--lib/public/Security/IContentSecurityPolicyManager.php2
-rw-r--r--lib/public/Security/ICrypto.php4
-rw-r--r--lib/public/Security/IHasher.php11
-rw-r--r--lib/public/Security/ISecureRandom.php4
-rw-r--r--lib/public/Security/Ip/IAddress.php35
-rw-r--r--lib/public/Security/Ip/IFactory.php30
-rw-r--r--lib/public/Security/Ip/IRange.php37
-rw-r--r--lib/public/Security/Ip/IRemoteAddress.php22
-rw-r--r--lib/public/Security/PasswordContext.php29
-rw-r--r--lib/public/Security/RateLimiting/ILimiter.php10
12 files changed, 223 insertions, 18 deletions
diff --git a/lib/public/Security/Events/GenerateSecurePasswordEvent.php b/lib/public/Security/Events/GenerateSecurePasswordEvent.php
index 8adddd529b0..419e7b40ee4 100644
--- a/lib/public/Security/Events/GenerateSecurePasswordEvent.php
+++ b/lib/public/Security/Events/GenerateSecurePasswordEvent.php
@@ -9,15 +9,34 @@ declare(strict_types=1);
namespace OCP\Security\Events;
use OCP\EventDispatcher\Event;
+use OCP\Security\PasswordContext;
/**
+ * Event to request a secure password to be generated
* @since 18.0.0
*/
class GenerateSecurePasswordEvent extends Event {
- /** @var null|string */
- private $password;
+ private ?string $password;
/**
+ * Request a secure password to be generated.
+ *
+ * By default passwords are generated for the user account context,
+ * this can be adjusted by passing another `PasswordContext`.
+ * @since 31.0.0
+ */
+ public function __construct(
+ private PasswordContext $context = PasswordContext::ACCOUNT,
+ ) {
+ parent::__construct();
+ $this->password = null;
+ }
+
+ /**
+ * Get the generated password.
+ *
+ * If a password generator is registered and successfully generated a password
+ * that password can get read back. Otherwise `null` is returned.
* @since 18.0.0
*/
public function getPassword(): ?string {
@@ -25,9 +44,20 @@ class GenerateSecurePasswordEvent extends Event {
}
/**
+ * Set the generated password.
+ *
+ * This is used by password generators to set the generated password.
* @since 18.0.0
*/
public function setPassword(string $password): void {
$this->password = $password;
}
+
+ /**
+ * Get the context this password should generated for.
+ * @since 31.0.0
+ */
+ public function getContext(): PasswordContext {
+ return $this->context;
+ }
}
diff --git a/lib/public/Security/Events/ValidatePasswordPolicyEvent.php b/lib/public/Security/Events/ValidatePasswordPolicyEvent.php
index 0aa8b516f70..d7ac9442392 100644
--- a/lib/public/Security/Events/ValidatePasswordPolicyEvent.php
+++ b/lib/public/Security/Events/ValidatePasswordPolicyEvent.php
@@ -9,26 +9,41 @@ declare(strict_types=1);
namespace OCP\Security\Events;
use OCP\EventDispatcher\Event;
+use OCP\Security\PasswordContext;
/**
+ * This event can be emitted to request a validation of a password.
+ *
+ * If a password policy app is installed and the password
+ * is invalid, an `\OCP\HintException` will be thrown.
* @since 18.0.0
*/
class ValidatePasswordPolicyEvent extends Event {
- /** @var string */
- private $password;
/**
* @since 18.0.0
+ * @since 31.0.0 - $context parameter added
*/
- public function __construct(string $password) {
+ public function __construct(
+ private string $password,
+ private PasswordContext $context = PasswordContext::ACCOUNT,
+ ) {
parent::__construct();
- $this->password = $password;
}
/**
+ * Get the password that should be validated.
* @since 18.0.0
*/
public function getPassword(): string {
return $this->password;
}
+
+ /**
+ * Get the context this password should validated for.
+ * @since 31.0.0
+ */
+ public function getContext(): PasswordContext {
+ return $this->context;
+ }
}
diff --git a/lib/public/Security/IContentSecurityPolicyManager.php b/lib/public/Security/IContentSecurityPolicyManager.php
index 3df0da465b2..00cdcc2c454 100644
--- a/lib/public/Security/IContentSecurityPolicyManager.php
+++ b/lib/public/Security/IContentSecurityPolicyManager.php
@@ -24,7 +24,7 @@ interface IContentSecurityPolicyManager {
* 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)`,
+ * To use this from your `app.php` use `\OCP\Server::get(IContentSecurityPolicyManager::class)->addDefaultPolicy($policy)`,
* $policy has to be of type `\OCP\AppFramework\Http\ContentSecurityPolicy`.
*
* WARNING: Using this API incorrectly may make the instance more insecure.
diff --git a/lib/public/Security/ICrypto.php b/lib/public/Security/ICrypto.php
index c2ba4cc9c97..78b0fc14d6d 100644
--- a/lib/public/Security/ICrypto.php
+++ b/lib/public/Security/ICrypto.php
@@ -13,8 +13,8 @@ namespace OCP\Security;
* 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');
+ * $encryptWithDefaultPassword = \OCP\Server::get(ICrypto::class)->encrypt('EncryptedText');
+ * $encryptWithCustomPassword = \OCP\Server::get(ICrypto::class)->encrypt('EncryptedText', 'password');
*
* @since 8.0.0
*/
diff --git a/lib/public/Security/IHasher.php b/lib/public/Security/IHasher.php
index 378c2cf3f51..d0d6e4e9028 100644
--- a/lib/public/Security/IHasher.php
+++ b/lib/public/Security/IHasher.php
@@ -19,10 +19,10 @@ namespace OCP\Security;
*
* Usage:
* // Hashing a message
- * $hash = \OC::$server->get(\OCP\Security\IHasher::class)->hash('MessageToHash');
+ * $hash = \OCP\Server::get(\OCP\Security\IHasher::class)->hash('MessageToHash');
* // Verifying a message - $newHash will contain the newly calculated hash
* $newHash = null;
- * var_dump(\OC::$server->get(\OCP\Security\IHasher::class)->verify('a', '86f7e437faa5a7fce15d1ddcb9eaeaea377667b8', $newHash));
+ * var_dump(\OCP\Server::get(\OCP\Security\IHasher::class)->verify('a', '86f7e437faa5a7fce15d1ddcb9eaeaea377667b8', $newHash));
* var_dump($newHash);
*
* @since 8.0.0
@@ -47,4 +47,11 @@ interface IHasher {
* @since 8.0.0
*/
public function verify(string $message, string $hash, &$newHash = null): bool ;
+
+ /**
+ * Check if the prefixed hash is valid
+ *
+ * @since 30.0.0
+ */
+ public function validate(string $prefixedHash): bool;
}
diff --git a/lib/public/Security/ISecureRandom.php b/lib/public/Security/ISecureRandom.php
index 188236dd3f9..0f4a79e08e0 100644
--- a/lib/public/Security/ISecureRandom.php
+++ b/lib/public/Security/ISecureRandom.php
@@ -14,7 +14,7 @@ namespace OCP\Security;
* use a fallback.
*
* Usage:
- * \OC::$server->get(ISecureRandom::class)->generate(10);
+ * \OCP\Server::get(ISecureRandom::class)->generate(10);
*
* @since 8.0.0
*/
@@ -58,7 +58,7 @@ interface ISecureRandom {
* 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.
+ * specified all valid base64 characters are used.
* @return string
* @since 8.0.0
*/
diff --git a/lib/public/Security/Ip/IAddress.php b/lib/public/Security/Ip/IAddress.php
new file mode 100644
index 00000000000..bff7744ddce
--- /dev/null
+++ b/lib/public/Security/Ip/IAddress.php
@@ -0,0 +1,35 @@
+<?php
+
+declare(strict_types=1);
+/**
+ * SPDX-FileCopyrightText: 2024 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace OCP\Security\Ip;
+
+/**
+ * @since 30.0.0
+ */
+interface IAddress {
+ /**
+ * Check if a given IP address is valid
+ *
+ * @since 30.0.0
+ */
+ public static function isValid(string $ip): bool;
+
+ /**
+ * Check if current address is contained by given ranges
+ *
+ * @since 30.0.0
+ */
+ public function matches(IRange ... $ranges): bool;
+
+ /**
+ * Normalized IP address
+ *
+ * @since 30.0.0
+ */
+ public function __toString(): string;
+}
diff --git a/lib/public/Security/Ip/IFactory.php b/lib/public/Security/Ip/IFactory.php
new file mode 100644
index 00000000000..3b88aa8c756
--- /dev/null
+++ b/lib/public/Security/Ip/IFactory.php
@@ -0,0 +1,30 @@
+<?php
+
+declare(strict_types=1);
+/**
+ * SPDX-FileCopyrightText: 2024 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace OCP\Security\Ip;
+
+/**
+ * @since 30.0.0
+ */
+interface IFactory {
+ /**
+ * Creates a range from string
+ *
+ * @since 30.0.0
+ * @throws \InvalidArgumentException on invalid range
+ */
+ public function rangeFromString(string $range): IRange;
+
+ /**
+ * Creates a address from string
+ *
+ * @since 30.0.0
+ * @throws \InvalidArgumentException on invalid IP
+ */
+ public function addressFromString(string $ip): IAddress;
+}
diff --git a/lib/public/Security/Ip/IRange.php b/lib/public/Security/Ip/IRange.php
new file mode 100644
index 00000000000..70e1815c75e
--- /dev/null
+++ b/lib/public/Security/Ip/IRange.php
@@ -0,0 +1,37 @@
+<?php
+
+declare(strict_types=1);
+/**
+ * SPDX-FileCopyrightText: 2024 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace OCP\Security\Ip;
+
+/**
+ * IP Range (IPv4 or IPv6)
+ *
+ * @since 30.0.0
+ */
+interface IRange {
+ /**
+ * Check if a given range is valid
+ *
+ * @since 30.0.0
+ */
+ public static function isValid(string $range): bool;
+
+ /**
+ * Check if an address is in the current range
+ *
+ * @since 30.0.0
+ */
+ public function contains(IAddress $address): bool;
+
+ /**
+ * Normalized IP range
+ *
+ * @since 30.0.0
+ */
+ public function __toString(): string;
+}
diff --git a/lib/public/Security/Ip/IRemoteAddress.php b/lib/public/Security/Ip/IRemoteAddress.php
new file mode 100644
index 00000000000..19a1dab9734
--- /dev/null
+++ b/lib/public/Security/Ip/IRemoteAddress.php
@@ -0,0 +1,22 @@
+<?php
+
+declare(strict_types=1);
+/**
+ * SPDX-FileCopyrightText: 2024 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace OCP\Security\Ip;
+
+/**
+ * IP address of the connected client
+ *
+ * @since 30.0.0
+ */
+interface IRemoteAddress {
+ /**
+ * Check if the current remote address is allowed to perform admin actions
+ * @since 30.0.0
+ */
+ public function allowsAdminActions(): bool;
+}
diff --git a/lib/public/Security/PasswordContext.php b/lib/public/Security/PasswordContext.php
new file mode 100644
index 00000000000..909070c09ff
--- /dev/null
+++ b/lib/public/Security/PasswordContext.php
@@ -0,0 +1,29 @@
+<?php
+
+declare(strict_types=1);
+/**
+ * SPDX-FileCopyrightText: 2024 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+namespace OCP\Security;
+
+/**
+ * Define the context in which a password is used.
+ * This allows setting a context for password validation and password generation.
+ *
+ * @package OCP\Security
+ * @since 31.0.0
+ */
+enum PasswordContext {
+ /**
+ * Password used for an user account
+ * @since 31.0.0
+ */
+ case ACCOUNT;
+
+ /**
+ * Password used for (public) shares
+ * @since 31.0.0
+ */
+ case SHARING;
+}
diff --git a/lib/public/Security/RateLimiting/ILimiter.php b/lib/public/Security/RateLimiting/ILimiter.php
index 50e2e9008ea..22a07f3d430 100644
--- a/lib/public/Security/RateLimiting/ILimiter.php
+++ b/lib/public/Security/RateLimiting/ILimiter.php
@@ -34,8 +34,8 @@ interface ILimiter {
*
*/
public function registerAnonRequest(string $identifier,
- int $anonLimit,
- int $anonPeriod,
+ int $anonLimit,
+ int $anonPeriod,
string $ip): void;
/**
@@ -50,7 +50,7 @@ interface ILimiter {
*
*/
public function registerUserRequest(string $identifier,
- int $userLimit,
- int $userPeriod,
- IUser $user): void;
+ int $userLimit,
+ int $userPeriod,
+ IUser $user): void;
}
generated by cgit v1.2.3 (git 2.39.1) at 2025-08-15 05:39:40 +0000