1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
|
<?php
declare(strict_types=1);
/**
* @copyright Copyright (c) 2022 Joas Schilling <coding@schilljs.com>
*
* @license GNU AGPL version 3 or any later version
*
* This program is free software: you can redistribute it and/or modify
* it under the terms of the GNU Affero General Public License as
* published by the Free Software Foundation, either version 3 of the
* License, or (at your option) any later version.
*
* 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
* along with this program. If not, see <http://www.gnu.org/licenses/>.
*
*/
namespace OCP\Security\Bruteforce;
/**
* Class Throttler implements the bruteforce protection for security actions in
* Nextcloud.
*
* It is working by logging invalid login attempts to the database and slowing
* down all login attempts from the same subnet. The max delay is 30 seconds and
* the starting delay are 200 milliseconds. (after the first failed login)
*
* This is based on Paragonie's AirBrake for Airship CMS. You can find the original
* code at https://github.com/paragonie/airship/blob/7e5bad7e3c0fbbf324c11f963fd1f80e59762606/src/Engine/Security/AirBrake.php
*
* @package OC\Security\Bruteforce
* @since 25.0.0
*/
interface IThrottler {
/**
* @since 25.0.0
* @deprecated 28.0.0
*/
public const MAX_DELAY = 25;
/**
* @since 25.0.0
* @deprecated 28.0.0
*/
public const MAX_DELAY_MS = 25000; // in milliseconds
/**
* @since 25.0.0
* @deprecated 28.0.0
*/
public const MAX_ATTEMPTS = 10;
/**
* Register a failed attempt to bruteforce a security control
*
* @param string $action
* @param string $ip
* @param array $metadata Optional metadata logged with the attempt
* @since 25.0.0
*/
public function registerAttempt(string $action, string $ip, array $metadata = []): void;
/**
* Get the throttling delay (in milliseconds)
*
* @param string $ip
* @param string $action optionally filter by action
* @param float $maxAgeHours
* @return int
* @since 25.0.0
* @deprecated 28.0.0 This method is considered internal as of Nextcloud 28. Use {@see showBruteforceWarning()} to decide whether a warning should be shown.
*/
public function getAttempts(string $ip, string $action = '', float $maxAgeHours = 12): int;
/**
* Whether a warning should be shown about the throttle
*
* @param string $ip
* @param string $action optionally filter by action
* @return bool
* @since 28.0.0
*/
public function showBruteforceWarning(string $ip, string $action = ''): bool;
/**
* Get the throttling delay (in milliseconds)
*
* @param string $ip
* @param string $action optionally filter by action
* @return int
* @since 25.0.0
* @deprecated 28.0.0 This method is considered internal as of Nextcloud 28. Use {@see showBruteforceWarning()} to decide whether a warning should be shown.
*/
public function getDelay(string $ip, string $action = ''): int;
/**
* Reset the throttling delay for an IP address, action and metadata
*
* @param string $ip
* @param string $action
* @param array $metadata
* @since 25.0.0
*/
public function resetDelay(string $ip, string $action, array $metadata): void;
/**
* Reset the throttling delay for an IP address
*
* @param string $ip
* @since 25.0.0
* @deprecated 28.0.0 This method is considered internal as of Nextcloud 28. Use {@see resetDelay()} and only reset the entries of your action and metadata
*/
public function resetDelayForIP(string $ip): void;
/**
* Will sleep for the defined amount of time
*
* @param string $ip
* @param string $action optionally filter by action
* @return int the time spent sleeping
* @since 25.0.0
* @deprecated 28.0.0 Use {@see sleepDelayOrThrowOnMax()} instead and abort handling the request when it throws
*/
public function sleepDelay(string $ip, string $action = ''): int;
/**
* Will sleep for the defined amount of time unless maximum was reached in the last 30 minutes
* In this case a "429 Too Many Request" exception is thrown
*
* @param string $ip
* @param string $action optionally filter by action
* @return int the time spent sleeping
* @throws MaxDelayReached when reached the maximum
* @since 25.0.0
*/
public function sleepDelayOrThrowOnMax(string $ip, string $action = ''): int;
}
|
