From 63806bdbe0f81df8b60f65c23328aa3c72adb928 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Johan=20Andre=CC=81n?= Date: Thu, 19 Nov 2015 11:08:37 +0100 Subject: [PATCH] =doc #18857 Add docs about comparing the secret when authenticating --- .../security-directives/authenticateBasic.rst | 2 ++ .../authenticateBasicAsync.rst | 2 ++ .../security-directives/authenticateBasicPF.rst | 2 ++ .../authenticateBasicPFAsync.rst | 2 ++ .../security-directives/authenticateOAuth2.rst | 2 ++ .../authenticateOAuth2Async.rst | 2 ++ .../authenticateOAuth2PF.rst | 2 ++ .../authenticateOAuth2PFAsync.rst | 2 ++ .../authenticateOrRejectWithChallenge.rst | 2 +- .../security-directives/extractCredentials.rst | 2 ++ .../directives/security-directives/index.rst | 17 +++++++++++++++++ 11 files changed, 36 insertions(+), 1 deletion(-) diff --git a/akka-docs-dev/rst/scala/http/routing-dsl/directives/security-directives/authenticateBasic.rst b/akka-docs-dev/rst/scala/http/routing-dsl/directives/security-directives/authenticateBasic.rst index 5aab3bf0ce..52f97b4cdf 100644 --- a/akka-docs-dev/rst/scala/http/routing-dsl/directives/security-directives/authenticateBasic.rst +++ b/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. diff --git a/akka-docs-dev/rst/scala/http/routing-dsl/directives/security-directives/authenticateBasicAsync.rst b/akka-docs-dev/rst/scala/http/routing-dsl/directives/security-directives/authenticateBasicAsync.rst index 60c30531e8..1f7b42afef 100644 --- a/akka-docs-dev/rst/scala/http/routing-dsl/directives/security-directives/authenticateBasicAsync.rst +++ b/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. diff --git a/akka-docs-dev/rst/scala/http/routing-dsl/directives/security-directives/authenticateBasicPF.rst b/akka-docs-dev/rst/scala/http/routing-dsl/directives/security-directives/authenticateBasicPF.rst index eaed96fd01..0643ecbc5d 100644 --- a/akka-docs-dev/rst/scala/http/routing-dsl/directives/security-directives/authenticateBasicPF.rst +++ b/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. diff --git a/akka-docs-dev/rst/scala/http/routing-dsl/directives/security-directives/authenticateBasicPFAsync.rst b/akka-docs-dev/rst/scala/http/routing-dsl/directives/security-directives/authenticateBasicPFAsync.rst index d01d244267..dce48aee22 100644 --- a/akka-docs-dev/rst/scala/http/routing-dsl/directives/security-directives/authenticateBasicPFAsync.rst +++ b/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. diff --git a/akka-docs-dev/rst/scala/http/routing-dsl/directives/security-directives/authenticateOAuth2.rst b/akka-docs-dev/rst/scala/http/routing-dsl/directives/security-directives/authenticateOAuth2.rst index 898ef0e421..f37fb275b3 100644 --- a/akka-docs-dev/rst/scala/http/routing-dsl/directives/security-directives/authenticateOAuth2.rst +++ b/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 diff --git a/akka-docs-dev/rst/scala/http/routing-dsl/directives/security-directives/authenticateOAuth2Async.rst b/akka-docs-dev/rst/scala/http/routing-dsl/directives/security-directives/authenticateOAuth2Async.rst index ff69316180..c224cc11cd 100644 --- a/akka-docs-dev/rst/scala/http/routing-dsl/directives/security-directives/authenticateOAuth2Async.rst +++ b/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 diff --git a/akka-docs-dev/rst/scala/http/routing-dsl/directives/security-directives/authenticateOAuth2PF.rst b/akka-docs-dev/rst/scala/http/routing-dsl/directives/security-directives/authenticateOAuth2PF.rst index bc6ff6ad44..cf3e65f000 100644 --- a/akka-docs-dev/rst/scala/http/routing-dsl/directives/security-directives/authenticateOAuth2PF.rst +++ b/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 diff --git a/akka-docs-dev/rst/scala/http/routing-dsl/directives/security-directives/authenticateOAuth2PFAsync.rst b/akka-docs-dev/rst/scala/http/routing-dsl/directives/security-directives/authenticateOAuth2PFAsync.rst index 8c54e1b245..44d0284225 100644 --- a/akka-docs-dev/rst/scala/http/routing-dsl/directives/security-directives/authenticateOAuth2PFAsync.rst +++ b/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 diff --git a/akka-docs-dev/rst/scala/http/routing-dsl/directives/security-directives/authenticateOrRejectWithChallenge.rst b/akka-docs-dev/rst/scala/http/routing-dsl/directives/security-directives/authenticateOrRejectWithChallenge.rst index 5a46654737..2f099b5572 100644 --- a/akka-docs-dev/rst/scala/http/routing-dsl/directives/security-directives/authenticateOrRejectWithChallenge.rst +++ b/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 diff --git a/akka-docs-dev/rst/scala/http/routing-dsl/directives/security-directives/extractCredentials.rst b/akka-docs-dev/rst/scala/http/routing-dsl/directives/security-directives/extractCredentials.rst index 9cf60006a8..682d510a28 100644 --- a/akka-docs-dev/rst/scala/http/routing-dsl/directives/security-directives/extractCredentials.rst +++ b/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 ------- diff --git a/akka-docs-dev/rst/scala/http/routing-dsl/directives/security-directives/index.rst b/akka-docs-dev/rst/scala/http/routing-dsl/directives/security-directives/index.rst index 8bc3a3a7c6..375c174a92 100644 --- a/akka-docs-dev/rst/scala/http/routing-dsl/directives/security-directives/index.rst +++ b/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. +