diff --git a/README.md b/README.md new file mode 100644 index 0000000..d009f8e --- /dev/null +++ b/README.md @@ -0,0 +1,111 @@ +# urllib3 SigV4 + +Extension to [urllib3](https://github.com/urllib3/urllib3) adding support for +signing the requests with AWS Signature Version 4. It uses the +[Boto3](https://github.com/boto/boto3) library for handling the AWS credentials +and the actual signing process. + +## Installation + +Use `pip` to install the package: + +```bash +pip install urllib3_sigv4 +``` + +## Usage + +This library provides a drop-in replacement for two main components of urllib3, +the [`PoolManager`](https://urllib3.readthedocs.io/en/stable/reference/urllib3.poolmanager.html) +class and the top-level [`request`](https://urllib3.readthedocs.io/en/stable/reference/urllib3.request.html) +method. It adds a new optional parameter which determines if and how the +requests should be signed. + +### Creating a Signer + +First, create an instance of the `SigV4RequestSigner` class which defines the +parameters for request signing: + +```python +from urllib3_sigv4 import SigV4RequestSigner + +signer = SigV4RequestSigner( + "lambda", + region="eu-central-1", + access_key="AKIAIOSFODNN7EXAMPLE", + secret_key="wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY" +) +``` + +The first parameter is mandatory and identifies the AWS service we want to make +requests to (AWS Lambda in this case). The `region`, `access_key` and +`secret_key` parameters are optional and will be inferred from the environment +if not passed (via the default Boto3 session, see +[here](https://boto3.amazonaws.com/v1/documentation/api/latest/guide/session.html) +and [here](https://boto3.amazonaws.com/v1/documentation/api/latest/guide/credentials.html) +for more details). + +### Making Requests + +To make signed requests to an AWS service, pass the signer instance via the +`signer` parameter when creating the `PoolManager`: + +```python +from urllib3_sigv4 import PoolManager, SigV4RequestSigner + +signer = SigV4RequestSigner("lambda") +http = PoolManager(signer=signer) + +response = http.request( + "POST", + "https://my-lambda-url-id.lambda-url.eu-central-1.on.aws", + json={"name": "John Doe", "age": 30} +) +print(response.json()) +``` + +You can also provide the signer in individual `request` method calls to +override the default behavior: + +```python +from urllib3_sigv4 import PoolManager, SigV4RequestSigner + +signer = SigV4RequestSigner("lambda") +http = PoolManager() + +# The same as when using urllib3's PoolManager. +response = http.request("GET", "https://httpbin.org/get") +print(response.json()) + +# This request will be signed. +response = http.request( + "POST", + "https://my-lambda-url-id.lambda-url.eu-central-1.on.aws", + json={"name": "John Doe", "age": 30}, + signer=signer +) +print(response.json()) +``` + +You can also use a convenience top-level `request` method which uses a +module-global `PoolManager` instance: + +```python +from urllib3_sigv4 import SigV4RequestSigner, request + +signer = SigV4RequestSigner("lambda") + +response = request( + "POST", + "https://my-lambda-url-id.lambda-url.eu-central-1.on.aws", + json={"name": "John Doe", "age": 30}, + signer=signer +) +print(response.json()) +``` + +## Reference + +- https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_aws-signing.html +- https://github.com/aws-samples/sigv4-signing-examples +- https://github.com/awslabs/aws-sdk-python-signers