Merge pull request #31 from weierophinney/feature/deprecate-digest

Deprecate Digest adapter

docs/book/adapter/digest.md

@@ -20,6 +20,16 @@ which the password is "somePassword"):
 someUser:Some Realm:fde17b91c3a510ecbaf7dbd37f59d4f8
 ```
 
+> CAUTION: **Digest Authentication Security Issues**
+>
+> Digest authentication utilizes `md5()` for hash creation and hash comparisons by default.
+> While the [HTDigest specification](https://datatracker.ietf.org/doc/html/rfc7616) has been expanded to allow SHA-256 and SHA-512 hashing algorithms, they require a different tool for the digest password file, as well as for the server-side to emit a header indicating what algorithm is in use.
+> We plan to add new adapters to support SHA-256 and/or SHA-512 in version 3, but continue to provide the original Digest implementation here to ensure compatibility with existing tooling.
+>
+> However, we **strongly urge** users to use our Basic authentication, LDAP, DB table, or custom authentication adapters (preferably utilizing `password_hash()`/`password_verify()`) to prevent attack vectors common to the Digest algorithm.
+>
+> This adapter is deprecated as of version 2.10.0, and will be removed in version 3.0.0.
+
 ## Specifics
 
 The digest authentication adapter, `Laminas\Authentication\Adapter\Digest`,

src/Adapter/Digest.php

@@ -12,6 +12,13 @@
 use Laminas\Crypt\Utils as CryptUtils;
 use Laminas\Stdlib\ErrorHandler;
 
+/**
+ * @deprecated Since 2.10.0; to be removed in 3.0.0. Digest authentication has
+*     known security issues due to the usage of MD5 for hash comparisons.
+*     We recommend usage of HTTP Basic, LDAP, DbTable, or a custom adapter that
+*     makes usage of strong hashing algorithms, preferably via usage of
+*     password_hash and password_verify.
+*/
 class Digest extends AbstractAdapter
 {
     /**