IHasher.php 1.9 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657
  1. <?php
  2. declare(strict_types=1);
  3. /**
  4. * SPDX-FileCopyrightText: 2016-2024 Nextcloud GmbH and Nextcloud contributors
  5. * SPDX-FileCopyrightText: 2016 ownCloud, Inc.
  6. * SPDX-License-Identifier: AGPL-3.0-only
  7. */
  8. namespace OCP\Security;
  9. /**
  10. * Class Hasher provides some basic hashing functions. Furthermore, it supports legacy hashes
  11. * used by previous versions of ownCloud and helps migrating those hashes to newer ones.
  12. *
  13. * The hashes generated by this class are prefixed (version|hash) with a version parameter to allow possible
  14. * updates in the future.
  15. * Possible versions:
  16. * - 1 (Initial version)
  17. *
  18. * Usage:
  19. * // Hashing a message
  20. * $hash = \OC::$server->get(\OCP\Security\IHasher::class)->hash('MessageToHash');
  21. * // Verifying a message - $newHash will contain the newly calculated hash
  22. * $newHash = null;
  23. * var_dump(\OC::$server->get(\OCP\Security\IHasher::class)->verify('a', '86f7e437faa5a7fce15d1ddcb9eaeaea377667b8', $newHash));
  24. * var_dump($newHash);
  25. *
  26. * @since 8.0.0
  27. */
  28. interface IHasher {
  29. /**
  30. * Hashes a message using PHP's `password_hash` functionality.
  31. * Please note that the size of the returned string is not guaranteed
  32. * and can be up to 255 characters.
  33. *
  34. * @param string $message Message to generate hash from
  35. * @return string Hash of the message with appended version parameter
  36. * @since 8.0.0
  37. */
  38. public function hash(string $message): string;
  39. /**
  40. * @param string $message Message to verify
  41. * @param string $hash Assumed hash of the message
  42. * @param null|string &$newHash Reference will contain the updated hash if necessary. Update the existing hash with this one.
  43. * @return bool Whether $hash is a valid hash of $message
  44. * @since 8.0.0
  45. */
  46. public function verify(string $message, string $hash, &$newHash = null): bool ;
  47. /**
  48. * Check if the prefixed hash is valid
  49. *
  50. * @since 30.0.0
  51. */
  52. public function validate(string $prefixedHash): bool;
  53. }