http-message-signatures


Namehttp-message-signatures JSON
Version 0.5.0 PyPI version JSON
download
home_pagehttps://github.com/pyauth/http-message-signatures
SummaryAn implementation of the IETF HTTP Message Signatures draft standard
upload_time2024-02-22 03:58:13
maintainer
docs_urlNone
authorAndrey Kislyuk
requires_python
licenseApache Software License
keywords
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            http-message-signatures: An implementation of RFC 9421, the IETF HTTP Message Signatures standard
=================================================================================================

*http-message-signatures* is an implementation of the IETF
`RFC 9421 HTTP Message Signatures <https://datatracker.ietf.org/doc/rfc9421/>`_ draft standard in
Python.

Installation
------------
::

    pip3 install http-message-signatures

Synopsis
--------

.. code-block:: python

    from http_message_signatures import HTTPMessageSigner, HTTPMessageVerifier, HTTPSignatureKeyResolver, algorithms
    import requests, base64, hashlib, http_sfv

    class MyHTTPSignatureKeyResolver(HTTPSignatureKeyResolver):
        keys = {"my-key": b"top-secret-key"}

        def resolve_public_key(self, key_id: str):
            return self.keys[key_id]

        def resolve_private_key(self, key_id: str):
            return self.keys[key_id]

    request = requests.Request('POST', 'https://example.com/foo?param=Value&Pet=dog', json={"hello": "world"})
    request = request.prepare()
    request.headers["Content-Digest"] = str(http_sfv.Dictionary({"sha-256": hashlib.sha256(request.body).digest()}))

    signer = HTTPMessageSigner(signature_algorithm=algorithms.HMAC_SHA256, key_resolver=MyHTTPSignatureKeyResolver())
    signer.sign(request, key_id="my-key", covered_component_ids=("@method", "@authority", "@target-uri", "content-digest"))

    verifier = HTTPMessageVerifier(signature_algorithm=algorithms.HMAC_SHA256, key_resolver=MyHTTPSignatureKeyResolver())
    verifier.verify(request)

Note that verifying the body content-digest is outside the scope of this package's functionality, so it remains the
caller's responsibility. The `requests-http-signature <https://github.com/pyauth/requests-http-signature>`_ library
builds upon this package to provide integrated signing and validation of the request body.

.. admonition:: See what is signed

 It is important to understand and follow the best practice rule of "See what is signed" when verifying HTTP message
 signatures. The gist of this rule is: if your application neglects to verify that the information it trusts is
 what was actually signed, the attacker can supply a valid signature but point you to malicious data that wasn't signed
 by that signature. Failure to follow this rule can lead to vulnerability against signature wrapping and substitution
 attacks.

 In http-message-signatures, you can ensure that the information signed is what you expect to be signed by only trusting the
 data returned by the ``verify()`` method::

   verify_results = verifier.verify(request)

 This returns a list of ``VerifyResult`` s, which are ``namedtuple`` s with the following attributes:

 * label (str): The label for the signature
 * algorithm: (same as signature_algorithm above)
 * covered_components: A mapping of component names to their values, as covered by the signature
 * parameters: A mapping of signature parameters to their values, as covered by the signature
 * body: Always ``None`` (the `requests-http-signature <https://github.com/pyauth/requests-http-signature>`_ package
   implements returning the body upon successful digest validation).

Given an HTTP request can potentially have multiple signatures the ``verify()`` method returns a list of ``VerifyResult`` s.
However, the implementation currently supports just one signature, so the returned list currently contains just one element.
If more signatures are found in the request then ``InvalidSignature`` is raised.

Additionally, the ``verify()`` method raises ``HTTPMessageSignaturesException`` or an exception derived from this class in
case an error occurs (unable to load PEM key, unsupported algorithm specified in signature input, signature doesn't match
digest etc.)

Authors
-------
* Andrey Kislyuk

Links
-----
* `Project home page (GitHub) <https://github.com/pyauth/http-message-signatures>`_
* `Documentation <https://FIXME>`_
* `Package distribution (PyPI) <https://pypi.python.org/pypi/http-message-signatures>`_
* `Change log <https://github.com/pyauth/http-message-signatures/blob/master/Changes.rst>`_
* `IETF HTTP Message Signatures standard tracker <https://datatracker.ietf.org/doc/rfc9421/>`_
* `OWASP Top Ten <https://owasp.org/www-project-top-ten/>`_

Bugs
~~~~
Please report bugs, issues, feature requests, etc. on `GitHub <https://github.com/pyauth/http-message-signatures/issues>`_.

License
-------
Licensed under the terms of the `Apache License, Version 2.0 <http://www.apache.org/licenses/LICENSE-2.0>`_.

            

Raw data

            {
    "_id": null,
    "home_page": "https://github.com/pyauth/http-message-signatures",
    "name": "http-message-signatures",
    "maintainer": "",
    "docs_url": null,
    "requires_python": "",
    "maintainer_email": "",
    "keywords": "",
    "author": "Andrey Kislyuk",
    "author_email": "kislyuk@gmail.com",
    "download_url": "https://files.pythonhosted.org/packages/dc/c9/9396cc932aaf2e79d9cbced8826138751de89e4c65c5b04a431e7f5e5032/http-message-signatures-0.5.0.tar.gz",
    "platform": "MacOS X",
    "description": "http-message-signatures: An implementation of RFC 9421, the IETF HTTP Message Signatures standard\n=================================================================================================\n\n*http-message-signatures* is an implementation of the IETF\n`RFC 9421 HTTP Message Signatures <https://datatracker.ietf.org/doc/rfc9421/>`_ draft standard in\nPython.\n\nInstallation\n------------\n::\n\n    pip3 install http-message-signatures\n\nSynopsis\n--------\n\n.. code-block:: python\n\n    from http_message_signatures import HTTPMessageSigner, HTTPMessageVerifier, HTTPSignatureKeyResolver, algorithms\n    import requests, base64, hashlib, http_sfv\n\n    class MyHTTPSignatureKeyResolver(HTTPSignatureKeyResolver):\n        keys = {\"my-key\": b\"top-secret-key\"}\n\n        def resolve_public_key(self, key_id: str):\n            return self.keys[key_id]\n\n        def resolve_private_key(self, key_id: str):\n            return self.keys[key_id]\n\n    request = requests.Request('POST', 'https://example.com/foo?param=Value&Pet=dog', json={\"hello\": \"world\"})\n    request = request.prepare()\n    request.headers[\"Content-Digest\"] = str(http_sfv.Dictionary({\"sha-256\": hashlib.sha256(request.body).digest()}))\n\n    signer = HTTPMessageSigner(signature_algorithm=algorithms.HMAC_SHA256, key_resolver=MyHTTPSignatureKeyResolver())\n    signer.sign(request, key_id=\"my-key\", covered_component_ids=(\"@method\", \"@authority\", \"@target-uri\", \"content-digest\"))\n\n    verifier = HTTPMessageVerifier(signature_algorithm=algorithms.HMAC_SHA256, key_resolver=MyHTTPSignatureKeyResolver())\n    verifier.verify(request)\n\nNote that verifying the body content-digest is outside the scope of this package's functionality, so it remains the\ncaller's responsibility. The `requests-http-signature <https://github.com/pyauth/requests-http-signature>`_ library\nbuilds upon this package to provide integrated signing and validation of the request body.\n\n.. admonition:: See what is signed\n\n It is important to understand and follow the best practice rule of \"See what is signed\" when verifying HTTP message\n signatures. The gist of this rule is: if your application neglects to verify that the information it trusts is\n what was actually signed, the attacker can supply a valid signature but point you to malicious data that wasn't signed\n by that signature. Failure to follow this rule can lead to vulnerability against signature wrapping and substitution\n attacks.\n\n In http-message-signatures, you can ensure that the information signed is what you expect to be signed by only trusting the\n data returned by the ``verify()`` method::\n\n   verify_results = verifier.verify(request)\n\n This returns a list of ``VerifyResult`` s, which are ``namedtuple`` s with the following attributes:\n\n * label (str): The label for the signature\n * algorithm: (same as signature_algorithm above)\n * covered_components: A mapping of component names to their values, as covered by the signature\n * parameters: A mapping of signature parameters to their values, as covered by the signature\n * body: Always ``None`` (the `requests-http-signature <https://github.com/pyauth/requests-http-signature>`_ package\n   implements returning the body upon successful digest validation).\n\nGiven an HTTP request can potentially have multiple signatures the ``verify()`` method returns a list of ``VerifyResult`` s.\nHowever, the implementation currently supports just one signature, so the returned list currently contains just one element.\nIf more signatures are found in the request then ``InvalidSignature`` is raised.\n\nAdditionally, the ``verify()`` method raises ``HTTPMessageSignaturesException`` or an exception derived from this class in\ncase an error occurs (unable to load PEM key, unsupported algorithm specified in signature input, signature doesn't match\ndigest etc.)\n\nAuthors\n-------\n* Andrey Kislyuk\n\nLinks\n-----\n* `Project home page (GitHub) <https://github.com/pyauth/http-message-signatures>`_\n* `Documentation <https://FIXME>`_\n* `Package distribution (PyPI) <https://pypi.python.org/pypi/http-message-signatures>`_\n* `Change log <https://github.com/pyauth/http-message-signatures/blob/master/Changes.rst>`_\n* `IETF HTTP Message Signatures standard tracker <https://datatracker.ietf.org/doc/rfc9421/>`_\n* `OWASP Top Ten <https://owasp.org/www-project-top-ten/>`_\n\nBugs\n~~~~\nPlease report bugs, issues, feature requests, etc. on `GitHub <https://github.com/pyauth/http-message-signatures/issues>`_.\n\nLicense\n-------\nLicensed under the terms of the `Apache License, Version 2.0 <http://www.apache.org/licenses/LICENSE-2.0>`_.\n",
    "bugtrack_url": null,
    "license": "Apache Software License",
    "summary": "An implementation of the IETF HTTP Message Signatures draft standard",
    "version": "0.5.0",
    "project_urls": {
        "Homepage": "https://github.com/pyauth/http-message-signatures"
    },
    "split_keywords": [],
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "21db353399e056ec284c64ed6c3baa818bcd248f81029f98cc5dcdb0a7f12fa9",
                "md5": "8e65eeab79ef4f134a196b246051abd6",
                "sha256": "719933cba48943b5e148fe7bbbf520927573f72c6ca00855cb2c79fdecee2cb2"
            },
            "downloads": -1,
            "filename": "http_message_signatures-0.5.0-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "8e65eeab79ef4f134a196b246051abd6",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": null,
            "size": 14784,
            "upload_time": "2024-02-22T03:58:11",
            "upload_time_iso_8601": "2024-02-22T03:58:11.513537Z",
            "url": "https://files.pythonhosted.org/packages/21/db/353399e056ec284c64ed6c3baa818bcd248f81029f98cc5dcdb0a7f12fa9/http_message_signatures-0.5.0-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "dcc99396cc932aaf2e79d9cbced8826138751de89e4c65c5b04a431e7f5e5032",
                "md5": "a7be4ec54c31c3b9b4fcc3bf12661947",
                "sha256": "5a59de19b90dce0eaf62021ee776d6562e5a166c96e4107db36f9c01f25552a3"
            },
            "downloads": -1,
            "filename": "http-message-signatures-0.5.0.tar.gz",
            "has_sig": false,
            "md5_digest": "a7be4ec54c31c3b9b4fcc3bf12661947",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": null,
            "size": 24800,
            "upload_time": "2024-02-22T03:58:13",
            "upload_time_iso_8601": "2024-02-22T03:58:13.343306Z",
            "url": "https://files.pythonhosted.org/packages/dc/c9/9396cc932aaf2e79d9cbced8826138751de89e4c65c5b04a431e7f5e5032/http-message-signatures-0.5.0.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2024-02-22 03:58:13",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "pyauth",
    "github_project": "http-message-signatures",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": true,
    "lcname": "http-message-signatures"
}
        
Elapsed time: 0.21259s