# Sigaws
An Elixir library to sign and verify HTTP requests using AWS Signature V4.
[![Inline docs](http://inch-ci.org/github/handnot2/sigaws.svg)](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.6"}]
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))
```
### 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)
```
### 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
```