IThrottler.php 4.0 KB

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