Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/handnot2/sigaws
An Elixir library to sign and verify HTTP requests using AWS Signature V4
https://github.com/handnot2/sigaws
authentication aws-signature elixir-library
Last synced: 3 days ago
JSON representation
An Elixir library to sign and verify HTTP requests using AWS Signature V4
- Host: GitHub
- URL: https://github.com/handnot2/sigaws
- Owner: handnot2
- License: mit
- Created: 2017-04-07T06:20:06.000Z (over 7 years ago)
- Default Branch: master
- Last Pushed: 2021-06-28T14:52:43.000Z (over 3 years ago)
- Last Synced: 2024-05-02T08:19:14.727Z (6 months ago)
- Topics: authentication, aws-signature, elixir-library
- Language: Elixir
- Size: 38.1 KB
- Stars: 11
- Watchers: 1
- Forks: 17
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
- freaking_awesome_elixir - Elixir - AWS Signature V4 signing and verification library ([Doc](https://hexdocs.pm/sigaws/Sigaws.html)). (Authentication)
- fucking-awesome-elixir - sigaws - AWS Signature V4 signing and verification library ([Doc](https://hexdocs.pm/sigaws/Sigaws.html)). (Authentication)
- awesome-elixir - sigaws - AWS Signature V4 signing and verification library ([Doc](https://hexdocs.pm/sigaws/Sigaws.html)). (Authentication)
README
# Sigaws
An Elixir library to sign and verify HTTP requests using AWS Signature V4.
[](http://inch-ci.org/github/handnot2/sigaws)
## Installation
This package can be installed by adding `sigaws` to your list of dependencies
in `mix.exs`:
```elixir
def deps do
[{:sigaws, "~> 0.7"}]
end
```
## Documentation
+ [Blog](https://handnot2.github.io/blog/elixir/aws-signature-sigaws)
+ [Module Doc](https://hexdocs.pm/sigaws)
+ [Plug built using this](https://hexdocs.pm/plug_sigaws)
## Examples
### Signature to be passed as request headers
```elixir
url = "https://ec2.amazonaws.com/Action=DescribeRegions&Version=2013-10-15"
{:ok, %{} = sig_data, _} =
Sigaws.sign_req(url, region: "us-east-1", service: "ec2",
access_key: System.get_env("AWS_ACCESS_KEY_ID"),
secret: System.get_env("AWS_SECRET_ACCESS_KEY"))
{:ok, resp} = HTTPoison.get(url, sig_data)
```
> You can pass in request headers to be included in the signature. Make sure to merge the
> signature with the headers before sending the request.
The same example is shown here making use of the temporary credentials obtained using
**AWS STS Secure Token Service**. Assuming the temporary credentials and the session
token are made available in environment variables:
```elixir
url = "https://ec2.amazonaws.com/Action=DescribeRegions&Version=2013-10-15"
headers = %{"X-Amz-Secure-Token" => System.get_env("AWS_SESSION_TOKEN")}
{:ok, %{} = sig_data, _} =
Sigaws.sign_req(url, region: "us-east-1", service: "ec2", headers: headers,
access_key: System.get_env("AWS_ACCESS_KEY_ID"),
secret: System.get_env("AWS_SECRET_ACCESS_KEY"))
{:ok, resp} = HTTPoison.get(url, Map.merge(headers, sig_data))
```
> Make sure to merge `sig_data` with other headers before calling HTTPoison.
> If not done, the HTTP request will fail with signature verification error.
### Signature to be passed in query string ("presigned" URL)
```elixir
url = "https://iam.amazonaws.com/Action=CreateUser&UserName=NewUser&Version=2010-05-08"
{:ok, %{} = sig_data, _} =
Sigaws.sign_req(url, region: "us-east-1", service: "iam", body: :unsigned,
access_key: System.get_env("AWS_ACCESS_KEY_ID"),
secret: System.get_env("AWS_SECRET_ACCESS_KEY"))
presigned_url = Sigaws.Util.add_params_to_url(url, sig_data)
{:ok, resp} = HTTPoison.get(presigned_url)
```
> When creating pre-signed URL for AWS S3, make sure to pass in `body: :unsigned`
> option. It is also very importnt to merge the signature data with other query
> parameters before sending the request (`Sigaws.Util.add_params_to_url`).
> The request will fail if these are not taken care of.
### Signature Verification
The verification process relies on a provider module that implements
`Sigaws.Provider` behavior. The provider is expected to supply the signing
key based on the information present in the context (primarily the access key).
```elixir
{:ok, %Sigaws.Ctxt{} = ctxt} =
Sigaws.Verify(conn.request_path,
method: conn.method,
params: conn.query_params,
headers: conn.req_headers,
body: get_raw_body(conn),
provider: SigawsQuickStartProvider)
```
The above example is using the `sigaws_quickstart_provider` Hex package.
Check the blog listed earlier.
## Test Suite
Part of the tests in this package rely on AWS Signature Version 4 Test Suite.
This test suite should be downloaded and unpacked before running the tests.
```sh
mkdir -p test/testsuite
cd test/testsuite
wget https://docs.aws.amazon.com/general/latest/gr/samples/aws-sig-v4-test-suite.zip
unzip aws-sig-v4-test-suite.zip
```