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

• Blog
• Module Doc
• Plug built using this

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