Sigaws

An Elixir library to sign and verify HTTP requests using AWS Signature V4.

Installation

This package can be installed by adding sigaws to your list of dependencies
in mix.exs:

def deps do
  [{:sigaws, "~> 0.7"}]
end

Documentation

Examples

Signature to be passed as request headers

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:

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)

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).

{: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.

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