OAuth 1.0a signature methods: RSA-SHA256, RSA-SHA512 and HMAC-SHA512 (#723)

* Adding support for RSA-SHA256.

* Added support for HMAC-SHA512, RSA-SHA256 and RSA-SHA512 signature methods.

* Made version dependencies consistent.

* Updated OAuth1 signature tests.

* Fixed parsing of netloc/host. Deprecated old functions.

* Refactored and expanded tests to include signature validate.

* Update docs for HMAC-SHA512, RSA-SHA256 and RSA-SHA512 signature methods.

* Updated code comments in oauth1 signatures module.

* Updated changelog.

* Update docs/feature_matrix.rst

Co-Authored-By: Omer Katz <omer.drow@gmail.com>

* Used parenthesis instead of backslash to break lines.

* Fixed typo

Co-authored-by: Omer Katz <omer.drow@gmail.com>

Co-authored-by: Omer Katz <omer.drow@gmail.com>

4 files changed, 166 insertions, 59 deletions

diff --git a/docs/faq.rst b/docs/faq.rst
index d9cd5c6..4814dcd 100644
--- a/docs/faq.rst
+++ b/docs/faq.rst
@@ -12,7 +12,7 @@ What parts of OAuth 1 & 2 are supported?
     See :doc:`feature_matrix`.
 
 OAuth 1 with RSA-SHA1 signatures says "could not import cryptography". What should I do?
-----------------------------------------------------------------------------------
+----------------------------------------------------------------------------------------
 
     Install oauthlib with rsa flag or install cryptography manually via pip.
 
diff --git a/docs/feature_matrix.rst b/docs/feature_matrix.rst
index df8cb0e..56d0cf3 100644
--- a/docs/feature_matrix.rst
+++ b/docs/feature_matrix.rst
@@ -1,33 +1,56 @@
 Supported features and platforms
 ================================
 
-OAuth 1 is fully supported per the RFC for both clients and providers.
-Extensions and variations that are outside the spec are not supported.
+Features
+--------
 
-- HMAC-SHA1, RSA-SHA1 and plaintext signatures.
-- Signature placement in header, url or body.
+OAuth 1.0a
+..........
+
+OAuth 1.0a is fully supported for both clients and providers.
+
+All standard *signature methods* defined in `RFC 5849`_ *The OAuth 1.0
+Protocol* are supported:
+
+- HMAC-SHA1
+- RSA-SHA1
+- PLAINTEXT
+
+Non-standard *signature methods* that replaces SHA-1 with stronger
+digest algorithms are also supported:
+
+- HMAC-SHA256
+- HMAC-SHA512
+- RSA-SHA256
+- RSA-SHA512
+
+The OAuth 1.0a signature can be placed in the header, URL or body of
+the request.
+
+OAuth 2.0
+.........
 
 OAuth 2.0 client and provider support for:
 
-- `RFC6749#section-4.1`_: Authorization Code Grant
-- `RFC6749#section-4.2`_: Implicit Grant
-- `RFC6749#section-4.3`_: Resource Owner Password Credentials Grant
-- `RFC6749#section-4.4`_: Client Credentials Grant
-- `RFC6749#section-6`_: Refresh Tokens
-- `RFC6750`_: Bearer Tokens
-- `RFC7009`_: Token Revocation
-- `RFC Draft MAC tokens`_
+- `RFC 6749 section-4.1`_: Authorization Code Grant
+- `RFC 6749 section-4.2`_: Implicit Grant
+- `RFC 6749 section-4.3`_: Resource Owner Password Credentials Grant
+- `RFC 6749 section-4.4`_: Client Credentials Grant
+- `RFC 6749 section-6`_: Refresh Tokens
+- `RFC 6750`_: Bearer Tokens
+- `RFC 7009`_: Token Revocation
+- `RFC Draft`_ Message Authentication Code (MAC) Tokens
 - OAuth2.0 Provider: `OpenID Connect Core`_
-- OAuth2.0 Provider: `RFC7636`_: Proof Key for Code Exchange by OAuth Public Clients (PKCE)
-- OAuth2.0 Provider: `RFC7662`_: Token Introspection
-- OAuth2.0 Provider: `RFC8414`_: Authorization Server Metadata
+- OAuth2.0 Provider: `RFC 7636`_: Proof Key for Code Exchange by OAuth Public Clients (PKCE)
+- OAuth2.0 Provider: `RFC 7662`_: Token Introspection
+- OAuth2.0 Provider: `RFC 8414`_: Authorization Server Metadata
 
 Features to be implemented (any help/PR are welcomed):
 
 - OAuth2.0 **Client**: `OpenID Connect Core`_
-- OAuth2.0 **Client**: `RFC7636`_: Proof Key for Code Exchange by OAuth Public Clients (PKCE)
-- OAuth2.0 **Client**: `RFC7662`_: Token Introspection
-- OAuth2.0 **Client**: `RFC8414`_: Authorization Server Metadata
+- OAuth2.0 **Client**: `RFC 7636`_: Proof Key for Code Exchange by OAuth Public Clients (PKCE)
+- OAuth2.0 **Client**: `RFC 7662`_: Token Introspection
+- OAuth2.0 **Client**: `RFC 8414`_: Authorization Server Metadata
 - SAML2
 - Bearer JWT as Client Authentication
 - Dynamic client registration
@@ -35,24 +58,32 @@ Features to be implemented (any help/PR are welcomed):
 - OpenID Session Management
 - ...and more
 
-Supported platforms
--------------------
+Platforms
+---------
+
+OAuthLib is mainly developed and tested on 64-bit Linux. It works on
+Unix and Unix-like operating systems (including macOS), as well as
+Microsoft Windows.
+
+It should work on any platform that supports Python, if features
+requiring RSA public-key cryptography is not used.
 
-OAuthLib is mainly developed/tested on 64 bit Linux but works on Unix (incl. OS
-X) and Windows as well. Unless you are using the RSA features of OAuth 1 you
-should be able to use OAuthLib on any platform that supports Python. If you use
-RSA you are limited to the platforms supported by `cryptography`_.
+If features requiring RSA public-key cryptography is used (e.g
+RSA-SHA1 and RS256), it should work on any platform supported by
+PyCA's `cryptography`_ package. RSA features require installing
+additional packages: see the installation instructions for details.
 
 .. _`cryptography`: https://cryptography.io/en/latest/installation/
-.. _`RFC6749#section-4.1`: https://tools.ietf.org/html/rfc6749#section-4.1
-.. _`RFC6749#section-4.2`: https://tools.ietf.org/html/rfc6749#section-4.2
-.. _`RFC6749#section-4.3`: https://tools.ietf.org/html/rfc6749#section-4.3
-.. _`RFC6749#section-4.4`: https://tools.ietf.org/html/rfc6749#section-4.4
-.. _`RFC6749#section-6`: https://tools.ietf.org/html/rfc6749#section-6
-.. _`RFC6750`: https://tools.ietf.org/html/rfc6750
-.. _`RFC Draft MAC tokens`: https://tools.ietf.org/id/draft-ietf-oauth-v2-http-mac-02.html
-.. _`RFC7009`: https://tools.ietf.org/html/rfc7009
-.. _`RFC7662`: https://tools.ietf.org/html/rfc7662
-.. _`RFC7636`: https://tools.ietf.org/html/rfc7636
+.. _`RFC 5849`: https://tools.ietf.org/html/rfc5849
+.. _`RFC 6749 section-4.1`: https://tools.ietf.org/html/rfc6749#section-4.1
+.. _`RFC 6749 section-4.2`: https://tools.ietf.org/html/rfc6749#section-4.2
+.. _`RFC 6749 section-4.3`: https://tools.ietf.org/html/rfc6749#section-4.3
+.. _`RFC 6749 section-4.4`: https://tools.ietf.org/html/rfc6749#section-4.4
+.. _`RFC 6749 section-6`: https://tools.ietf.org/html/rfc6749#section-6
+.. _`RFC 6750`: https://tools.ietf.org/html/rfc6750
+.. _`RFC Draft`: https://tools.ietf.org/id/draft-ietf-oauth-v2-http-mac-02.html
+.. _`RFC 7009`: https://tools.ietf.org/html/rfc7009
+.. _`RFC 7662`: https://tools.ietf.org/html/rfc7662
+.. _`RFC 7636`: https://tools.ietf.org/html/rfc7636
 .. _`OpenID Connect Core`: https://openid.net/specs/openid-connect-core-1_0.html
-.. _`RFC8414`: https://tools.ietf.org/html/rfc8414
+.. _`RFC 8414`: https://tools.ietf.org/html/rfc8414
diff --git a/docs/installation.rst b/docs/installation.rst
index 72d7b08..0e00e39 100644
--- a/docs/installation.rst
+++ b/docs/installation.rst
@@ -1,71 +1,147 @@
 Installing OAuthLib
 ===================
 
-The recommended way to install OAuthLib is from PyPI but if you are running
-into a bug or want to try out recently implemented features you will want to
-try installing directly from the GitHub master branch.
 
-For various reasons you may wish to install using your OS packaging system and
-install instructions for a few are shown below. Please send a PR to add a
-missing one.
+Install from PyPI
+-----------------
+
+The recommended way to install OAuthLib is from PyPI using the *pip*
+program. Either just the *standard install* by itself or *with extras
+for RSA*.
 
-Latest release on PyPI
-----------------------
+Standard install
+^^^^^^^^^^^^^^^^
 
+A standard installation contains the core features of OAuthLib. It can
+be installed by running:
 
 .. code-block:: bash
 
     pip install oauthlib
 
-Bleeding edge from GitHub master
---------------------------------
+To reduce its requirements, the Python packages needed for RSA
+public-key cryptography are not included in the standard installation.
+
+
+With extras for RSA
+^^^^^^^^^^^^^^^^^^^
+
+To support features that use RSA public-key cryptography, PyCA's
+`cryptography`_ package and the `PyJWT`_ package must also be
+installed. This can be done by installing the core features of
+OAuthLib along with the "signedtoken" extras.
 
 .. code-block:: bash
 
-    pip install -e git+https://github.com/oauthlib/oauthlib.git#egg=oauthlib
+    pip install 'oauthlib[signedtoken]'
+
+Note: the quotes may be required, since shells can interpret the
+square brackets as special characters.
+
+Alternatively, those two Python packages can be installed manually by
+running ``pip install cryptography`` and ``pip install pyjwt``, either
+before or after installing the standard installation of OAuthLib.
+PyJWT depends on cryptography, so just installing *pyjwt* should
+automatically also install *cryptography*. But *cryptography* has
+dependencies that can cause its installation to fail, so it can be
+better to get it installed before installing PyJWT.
+
+Install from operating system distribution
+------------------------------------------
+
+Alternatively, install it from the operating system distribution's
+packaging system, if OAuthLib is available as a distribution package.
+Install instructions for some distributions are shown below.
+
+The distribution packages usually only contain the standard install of
+OAuthLib. To enable support for RSA, the *cryptography* and *pyjwt*
+Python packages also need to be installed: either from the
+distribution packages (if available) or from PyPI.
 
 Debian and derivatives like Ubuntu, Mint, etc.
----------------------------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 .. code-block:: bash
 
-    apt-get install python-oauthlib
     apt-get install python3-oauthlib
 
-Redhat and Fedora
------------------
+The Python2 package is called "python-oauthlib".
+
+RHEL, CentOS and Fedora
+^^^^^^^^^^^^^^^^^^^^^^^
 
 .. code-block:: bash
 
-    yum install python-oauthlib
     yum install python3-oauthlib
 
+The Python2 package is called "python2-oauthlib", and is available on
+some distributions (e.g.Fedora 31 and CentOS 7) but not available on
+others (e.g. CentOS 8).
+
+For CentOS, the Python3 package is only available on CentOS 8 and
+higher.
+
 openSUSE
---------
+^^^^^^^^
 
 .. code-block:: bash
 
-    zypper in python-oauthlib
     zypper in python3-oauthlib
 
+The Python2 package is called "python-oauthlib".
+
 Gentoo
-------
+^^^^^^
 
 .. code-block:: bash
 
     emerge oauthlib
 
 Arch
-----
+^^^^
 
 .. code-block:: bash
 
     pacman -S python-oauthlib
-    pacman -S python2-oauthlib
+
+The Python2 package is called "python2-oauthlib".
 
 FreeBSD
--------
+^^^^^^^
 
 .. code-block:: bash
 
     pkg_add -r security/py-oauthlib/
+
+
+Install from GitHub
+-------------------
+
+Alternatively, install it directly from the source repository on
+GitHub.  This is the "bleading edge" version, but it may be useful for
+accessing bug fixes and/or new features that have not been released.
+
+Standard install
+^^^^^^^^^^^^^^^^
+
+The standard installation contains the core features of OAuthLib.
+
+.. code-block:: bash
+
+    pip install -e git+https://github.com/oauthlib/oauthlib.git#egg=oauthlib
+
+With extras for RSA
+^^^^^^^^^^^^^^^^^^^
+
+To support features that use RSA public-key cryptography, install the
+core features of OAuthLib along with the "signedtoken" extras.
+
+.. code-block:: bash
+
+    pip install -e 'git+https://github.com/oauthlib/oauthlib.git#egg=oauthlib[signedtoken]'
+
+Note: the quotes may be required, since shells can interpret the
+square brackets as special characters.
+
+.. _`cryptography`: https://cryptography.io/
+.. _`PyJWT`: https://pyjwt.readthedocs.io/
diff --git a/docs/oauth2/endpoints/metadata.rst b/docs/oauth2/endpoints/metadata.rst
index d44e8b7..a879765 100644
--- a/docs/oauth2/endpoints/metadata.rst
+++ b/docs/oauth2/endpoints/metadata.rst
@@ -2,7 +2,7 @@
 Metadata endpoint
 ===================
 
-OAuth2.0 Authorization Server Metadata (`RFC8414`_) endpoint provide the metadata of your authorization server. Since the metadata results can be a combination of OAuthlib's Endpoint (see :doc:`preconfigured_servers`), the MetadataEndpoint's class takes a list of Endpoints in parameter, and aggregate the metadata in the response.
+OAuth2.0 Authorization Server Metadata (`RFC8414`_) endpoint provide the metadata of your authorization server. Since the metadata results can be a combination of OAuthlib's Endpoint (see :doc:`/oauth2/preconfigured_servers`), the MetadataEndpoint's class takes a list of Endpoints in parameter, and aggregate the metadata in the response.
 
 See below an example of usage with `bottle-oauthlib`_ when using a `LegacyApplicationServer` (password grant) endpoint: