Merge pull request #18964 from johanandren/wip-18857-document-credentials-hiding-secret-johanandren

=doc #18857 Add docs about comparing the secret when authenticating

akka-docs-dev/rst/scala/http/routing-dsl/directives/security-directives/authenticateBasic.rst

@@ -27,6 +27,8 @@ variant of this directive which allows it to run without blocking routing layer
 Standard HTTP-based authentication which uses the ``WWW-Authenticate`` header containing challenge data and
 ``Authorization`` header for receiving credentials is implemented in subclasses of ``HttpAuthenticator``.
 
+See :ref:`credentials-and-timing-attacks-scala` for details about verifying the secret.
+
 .. warning::
   Make sure to use basic authentication only over SSL/TLS because credentials are transferred in plaintext.
 

akka-docs-dev/rst/scala/http/routing-dsl/directives/security-directives/authenticateBasicAsync.rst

@@ -25,6 +25,8 @@ which by default is mapped to an ``401 Unauthorized`` response.
 Standard HTTP-based authentication which uses the ``WWW-Authenticate`` header containing challenge data and
 ``Authorization`` header for receiving credentials is implemented in subclasses of ``HttpAuthenticator``.
 
+See :ref:`credentials-and-timing-attacks-scala` for details about verifying the secret.
+
 .. warning::
   Make sure to use basic authentication only over SSL/TLS because credentials are transferred in plaintext.
 

akka-docs-dev/rst/scala/http/routing-dsl/directives/security-directives/authenticateBasicPF.rst

@@ -25,6 +25,8 @@ leaves the request to be rejected with a :class:`AuthenticationFailedRejection`
 Longer-running authentication tasks (like looking up credentials in a database) should use :ref:`-authenticateBasicAsync-`
 or :ref:`-authenticateBasicPFAsync-` if you prefer to use the ``PartialFunction`` syntax.
 
+See :ref:`credentials-and-timing-attacks-scala` for details about verifying the secret.
+
 .. warning::
   Make sure to use basic authentication only over SSL/TLS because credentials are transferred in plaintext.
 

akka-docs-dev/rst/scala/http/routing-dsl/directives/security-directives/authenticateBasicPFAsync.rst

@@ -22,6 +22,8 @@ Refer to :ref:`-authenticateBasic-` for a detailed description of this directive
 Its semantics are equivalent to ``authenticateBasicPF`` 's, where not handling a case in the Partial Function (PF)
 leaves the request to be rejected with a :class:`AuthenticationFailedRejection` rejection.
 
+See :ref:`credentials-and-timing-attacks-scala` for details about verifying the secret.
+
 .. warning::
   Make sure to use basic authentication only over SSL/TLS because credentials are transferred in plaintext.
 

akka-docs-dev/rst/scala/http/routing-dsl/directives/security-directives/authenticateOAuth2.rst

@@ -29,6 +29,8 @@ which by default is mapped to an ``401 Unauthorized`` response.
 Longer-running authentication tasks (like looking up credentials in a database) should use the :ref:`-authenticateOAuth2Async-`
 variant of this directive which allows it to run without blocking routing layer of Akka HTTP, freeing it for other requests.
 
+See :ref:`credentials-and-timing-attacks-scala` for details about verifying the secret.
+
 For more information on how OAuth2 works see `RFC 6750`_.
 
 .. _RFC 6750: https://tools.ietf.org/html/rfc6750

akka-docs-dev/rst/scala/http/routing-dsl/directives/security-directives/authenticateOAuth2Async.rst

@@ -28,6 +28,8 @@ which by default is mapped to an ``401 Unauthorized`` response.
 
 See also :ref:`-authenticateOAuth2-` if the authorization operation is rather quick, and does not have to execute asynchronously.
 
+See :ref:`credentials-and-timing-attacks-scala` for details about verifying the secret.
+
 For more information on how OAuth2 works see `RFC 6750`_.
 
 .. _RFC 6750: https://tools.ietf.org/html/rfc6750

akka-docs-dev/rst/scala/http/routing-dsl/directives/security-directives/authenticateOAuth2PF.rst

@@ -30,6 +30,8 @@ leaves the request to be rejected with a :class:`AuthenticationFailedRejection`
 Longer-running authentication tasks (like looking up credentials in a database) should use the :ref:`-authenticateOAuth2Async-`
 variant of this directive which allows it to run without blocking routing layer of Akka HTTP, freeing it for other requests.
 
+See :ref:`credentials-and-timing-attacks-scala` for details about verifying the secret.
+
 For more information on how OAuth2 works see `RFC 6750`_.
 
 .. _RFC 6750: https://tools.ietf.org/html/rfc6750

akka-docs-dev/rst/scala/http/routing-dsl/directives/security-directives/authenticateOAuth2PFAsync.rst

@@ -30,6 +30,8 @@ leaves the request to be rejected with a :class:`AuthenticationFailedRejection`
 
 See also :ref:`-authenticateOAuth2PF-` if the authorization operation is rather quick, and does not have to execute asynchronously.
 
+See :ref:`credentials-and-timing-attacks-scala` for details about verifying the secret.
+
 For more information on how OAuth2 works see `RFC 6750`_.
 
 .. _RFC 6750: https://tools.ietf.org/html/rfc6750

akka-docs-dev/rst/scala/http/routing-dsl/directives/security-directives/authenticateOrRejectWithChallenge.rst

@@ -17,7 +17,7 @@ Lifts an authenticator function into a directive.
 
 This directive allows implementing the low level challange-response type of authentication that some services may require.
 
-More details about challange-response authentication are available in the `RFC 2617`_, `RFC 7616`_ and `RFC 7617`_.
+More details about challenge-response authentication are available in the `RFC 2617`_, `RFC 7616`_ and `RFC 7617`_.
 
 .. _RFC 2617: http://tools.ietf.org/html/rfc2617
 .. _RFC 7616: http://tools.ietf.org/html/rfc7616

akka-docs-dev/rst/scala/http/routing-dsl/directives/security-directives/extractCredentials.rst

@@ -15,6 +15,8 @@ Description
 Extracts the potentially present ``HttpCredentials`` provided with the request's ``Authorization`` header,
 which can be then used to implement some custom authentication or authorization logic.
 
+See :ref:`credentials-and-timing-attacks-scala` for details about verifying the secret.
+
 Example
 -------
 

akka-docs-dev/rst/scala/http/routing-dsl/directives/security-directives/index.rst

@@ -64,3 +64,20 @@ they are only a means of extracting the so called ``Bearer Token`` from the ``Au
 as defined in `RFC 6750`_, and allow users to validate and complete the protocol.
 
 .. _RFC 6750: https://tools.ietf.org/html/rfc6750
+
+
+.. _credentials-and-timing-attacks-scala:
+
+Credentials and password timing attacks
+---------------------------------------
+
+When transforming request ``Credentials`` into an application specific user identifier the naive solution for
+checking the secret (password) would be a regular string comparison, but doing this would open up the application to
+timing attacks. See for example `Timing Attacks Explained`_ for an explanation of the problem.
+
+.. _Timing Attacks Explained: http://emerose.com/timing-attacks-explained
+
+To protect users of the library from that mistake the secret is not available through the API, instead the method
+``Credentials.Provided.verify(String)`` should be used. It does a constant time comparison rather than returning early
+upon finding the first non-equal character.
+