pyramid-signed-params 1.0.0
Cryptographically signed query parameters for pyramid
License: BSD
Keywords: web pyramid cryptography query_string

#####################################################
Cryptographically Signed Query Parameters for Pyramid
#####################################################

|version| |py_versions| |license| |build status|

***********
Description
***********

This package provides a method for pyramid_ applications to sign parameters
which are passed in query strings (or POST bodies).

The initial motivation for this was to be able to pass a ``return_url``
to a views without turning the app into open redirector.

Other use cases include being able to generate URLs (e.g. to be included in
emails) which can be used to bypass the normal authentication/authorization
mechanisms.

.. _pyramid: https://trypyramid.com/

************
Installation
************

``Pyramid-signed-params`` can be installed from PyPI_ using ``pip`` or
``easy_install`` (or ``buildout``.)  You should probably be installing it in a virtual
environment.

.. _PyPI: https://pypi.python.org/pypi/pyramid-signed-params

*************
Configuration
*************

You must configure at least one signing secret in your app settings.
The secret should be a random, unguessable string.  E.g. in your app’s
``.ini`` file::

  pyramid_signed_params.secret = RGWO7nZ6W6AiPIUcXQN2iahJIThwH9BbpyZ7Lc1XfaOkPGt1GY

.. hint::

  You can specify multiple signing keys (one per line.)  If
  you do, the first key will be used for signing, while all keys will
  be tried when verifying signatures.  This can be useful when rolling
  out a new signing key.

Activate the package by including it in your pyramid application.

.. code-block:: python

  config.include('pyramid-signed-params')

This will add two new attributes to pyramid’s ``request``.

- ``request.sign_query(query, max_age=None, kid=None)``

  Used to sign query arguments, e.g.

  .. code-block:: python

    # Pass the current URL as a signed *return_url* parameter to another view
    query = {'return_url': request.url}
    other_url = request.route_url('other', _query=request.sign_query(query))

  The ``max_age`` parameter can be used to generate signatures which expire after a certain
  amount of time.

  Passing ``kid="csrf"`` will create signatures which will be
  invalidated whenever the session’s CSRF token is changed.

- ``request.signed_params``

  This *reified* property will contain a multidict populated with all
  parameters passed to the request which were signed with a valid
  signature.

*******************
Basic Usage Example
*******************

Construct a URL which could be e-mailed out to allow changing the
password of a given user::

    # Construct a URL with some signed parameters
    params = {'userid': 'fred', 'action': 'change-pw'}
    signed_params = request.sign_query(params, max_age=3600)
    url = request.route_url('change-pw', _query=signed_params)

Then, in the change-pw view::

    if request.signed_params['action'] != 'change-pw':
        raise HTTPForbidden()
    userid = request.signed_params['userid']

    # Do whatever needs to be done to change the given users password

Note that because we passed ``max_age=3600`` to ``sign_query``, the
URL will only work for an hour.

*******
Caution
*******

This package provides no inherent protection against replay attacks.
If an attacker has access to a set of signed parameters, he may pass
those signed parameters, unmodified, to any URL within the app (or
other apps sharing the same signing secret.)

*******
Authors
*******

`Jeff Dairiki`_

.. _Jeff Dairiki: mailto:dairiki@dairiki.org


.. ==== Badges ====

.. |build status| image::
    https://github.com/dairiki/pyramid_signed_params/actions/workflows/tests.yml/badge.svg?branch=master
    :target: https://github.com/dairiki/pyramid_signed_params/actions/workflows/tests.yml

.. |downloads| image::
    https://img.shields.io/pypi/dm/pyramid_signed_params.svg
    :target: https://pypi.python.org/pypi/pyramid_signed_params/
    :alt: Downloads
.. |version| image::
    https://img.shields.io/pypi/v/pyramid_signed_params.svg
    :target: https://pypi.python.org/pypi/pyramid_signed_params/
    :alt: Latest Version
.. |py_versions| image::
    https://img.shields.io/pypi/pyversions/pyramid_signed_params.svg
    :target: https://pypi.python.org/pypi/pyramid_signed_params/
    :alt: Supported Python versions
.. |py_implementation| image::
    https://img.shields.io/pypi/implementation/pyramid_signed_params.svg
    :target: https://pypi.python.org/pypi/pyramid_signed_params/
    :alt: Supported Python versions
.. |license| image::
    https://img.shields.io/pypi/l/pyramid_signed_params.svg
    :target: https://github.com/dairiki/pyramid_signed_params/blob/master/LICENSE.txt
    :alt: License
.. |dev_status| image::
    https://img.shields.io/pypi/status/pyramid_signed_params.svg
    :target: https://pypi.python.org/pypi/pyramid_signed_params/
    :alt: Development Status

*******
Changes
*******

Release 1.0.0 (2021-12-21)
==========================

- Add support for Pyramid 2.0.
- Mark this as a stable release.

Tests
-----

- Fix test for ``PyJWT>=2``
- Test under pythons 3.7 – 3.10. Stop testing under 3.4 and 3.5.
- Test under PyJWT 1 (as well as latest PyJWT).  Stop testing under PyJWT 1.5.


Release 0.1b5 (2018-03-08)
==========================

- Use the new in ``PyJWT`` 1.6 more specific ``InvalidSignatureError``
  in favor of the generic ``DecodeError`` to detect invalid signatures
  (when available.)

Tests
-----

- Test under both ``PyJWT`` 1.6 and 1.5.3.

- Fix for changes in default log level in ``pytest`` 3.4.

- As of ``pytest`` 3.3, ``pytest-catchlog`` has been rolled into the pytest core.


Release 0.1b4 (2017-12-18)
==========================

Packaging
---------

- Drop CPython 3.3 classifier

Release 0.1b3 (2017-12-18)
==========================

Compatibility
-------------

- Drop support for python 3.3.

Packaging
---------

- Include LICENSE.txt and pytest.ini in sdist.

Release 0.1b2 (2017-11-16)
==========================

- Change the ``signed_params`` reified request method so that it
  catches ``UnicodeDecodeError``\s when accessing ``request.params``,
  and returns an empty dict.  (If the parameters are not properly
  encoded, there are no valid signed parameters.)

Release 0.1b1 (2017-11-16)
==========================

- Drop support for python 2.6.  Test under python 3.6.

Security
--------

- Explicitly specify allowed algorithms when decoding JWTs.

Release 0.1a5 (2016-11-13)
==========================

- Remove the (broken) config-time warning issued if no service is
  registered for ``ISignedParamsService``.  (When ``autocommit`` was
  off, this warning was always being issued.)

Release 0.1a4 (2016-11-02)
==========================

- The setting for configuring the JWT signing secret(s) has been
  renamed to ``pyramid_signed_param.secret`` from
  ``pyramid_signed_param.secrets``.  Basic usage involve only a single
  secret. (Two allow for rotation of secrets, any configured secrets are
  accepted when verifying signatures, but only the first is used for
  creating new signatures.)

- ``Pyramid_signed_params.include`` now issues a warning if the
  ``ISignedParamsService`` is not configured.

- ``JWTSecretProviderFactory`` now raises a ``ConfigurationError``
  if no secrets are found in the app ``settings``.


Release 0.1a3 (2016-11-02)
==========================

Initial release.