ExAwsSnsVerifier

Verify AWS SNS HTTPS message authenticity — RSA-SHA256 signature verification for Elixir applications.

ExAwsSnsVerifier validates Notification, SubscriptionConfirmation, and UnsubscribeConfirmation payloads sent via the AWS SNS HTTPS transport. It is the Elixir equivalent of Ruby's Aws::SNS::MessageVerifier.

No runtime dependencies — uses :public_key for RSA verification and :httpc for certificate fetching.

Features

• 🔐 RSA-SHA256 verification — validates SignatureVersion 2 signatures using the AWS signing certificate
• 📬 All message types — Notification, SubscriptionConfirmation, and UnsubscribeConfirmation
• 🛡️ Topic ARN allowlist — restrict which topics are accepted
• 🔒 URL hardening — enforces HTTPS, host whitelist (sns.<region>.amazonaws.com), no credentials in URL, .pem extension for certs
• ⏰ Replay protection — configurable timestamp window (default: 1 hour)
• 🗄️ Cert caching — :persistent_term-backed cache with 24-hour TTL
• 🔌 Pluggable HTTP client — swap in Tesla, Req, Finch, or any custom client
• 🧩 Plug integration — ExAwsSnsVerifier.Plug for Phoenix / Plug pipelines
• ⚡ Consistent error handling — verify/2 returns {:ok, payload} or {:error, reason}; verify!/2 raises
• 📦 Zero runtime dependencies — no Jason, no HTTPoison, no extra baggage
• 🧪 Fully tested — matrix across OTP 26–28 and Elixir 1.16–1.19

Installation

Add ex_aws_sns_verifier to your mix.exs:

def deps do
  [
    {:ex_aws_sns_verifier, "~> 0.2.0"}
  ]
end

Then run:

mix deps.get

Quick Start

1. One-shot verification

Pass the raw JSON body and a set of allowed topic ARNs:

raw_body = ~s({
  "Type": "Notification",
  "MessageId": "22b80b92-fdea-4c2c-8f9d-bdfb0c7bf324",
  "TopicArn": "arn:aws:sns:us-east-1:123456789012:MyTopic",
  "Message": "Hello from SNS!",
  "Timestamp": "2026-05-13T12:00:00.000Z",
  "SignatureVersion": "2",
  "Signature": "...",
  "SigningCertURL": "https://sns.us-east-1.amazonaws.com/...pem",
  ...
})

opts = [
  allowed_topic_arns: ["arn:aws:sns:us-east-1:123456789012:MyTopic"]
]

{:ok, payload} = ExAwsSnsVerifier.verify(raw_body, opts)

2. With a Verifier struct (reusable config)

verifier = ExAwsSnsVerifier.new(
  allowed_topic_arns: ["arn:aws:sns:us-east-1:123456789012:MyTopic"],
  timestamp_window_seconds: 300  # 5 minutes
)

{:ok, payload} = ExAwsSnsVerifier.verify(verifier, raw_body)

3. Raise on failure

payload = ExAwsSnsVerifier.verify!(raw_body, opts)
# Raises ExAwsSnsVerifier.VerificationError on failure

4. With a Plug pipeline

# In your router or endpoint
plug ExAwsSnsVerifier.Plug,
     allowed_topic_arns: ["arn:aws:sns:us-east-1:123456789012:MyTopic"]

The plug reads the raw body, verifies the SNS signature, and assigns {:ok, payload} or {:error, reason} to conn.assigns.sns_verification. On failure, the connection is halted with 403.

Configuration

Verifier options

Custom HTTP client

Swap in your own HTTP client (Tesla, Req, Finch, etc.):

defmodule MyApp.MyHttpClient do
  @behaviour ExAwsSnsVerifier.Cert.HttpClientBehaviour

  @impl true
  def get(url) do
    # Return {:ok, body} or {:error, reason}
    Req.get!(url).body
  end
end

verifier = ExAwsSnsVerifier.new(
  allowed_topic_arns: ["..."],
  http_client: MyApp.MyHttpClient
)

Custom cert cache

defmodule MyApp.MyCache do
  @behaviour ExAwsSnsVerifier.Cert.CacheBehaviour  # get/1, put/2

  @impl true
  def get(key), do: # ...
  @impl true
  def put(key, value), do: # ...
end

Error Reasons

verify/2 returns {:error, reason} with one of the following atoms:

How it works

1. Parse — decodes the JSON body
2. Validate type — confirms one of the three supported message types
3. Validate signature version — only SignatureVersion 2 (RSA-SHA256)
4. Validate timestamp — checks the message is within the replay window
5. Validate topic — confirms the TopicArn is in the allowlist
6. Build canonical string — constructs the signed payload per AWS spec
7. Fetch cert — downloads and caches the signing certificate from SigningCertURL
8. Verify signature — RSA-SHA256 verification using :public_key

Development

git clone https://github.com/GustavoZiaugra/ex_aws_sns_verifier.git
cd ex_aws_sns_verifier
mix deps.get
mix compile --warnings-as-errors

# Run tests
mix test

# Quality checks
mix format --check-formatted
mix credo --strict
mix dialyzer

# Generate docs
mix docs

Links

• AWS SNS Message Verification Docs
• Hex.pm
• HexDocs

License

MIT © Gustavo Ziaugra