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–29 and Elixir 1.16–1.20

Installation

Add ex_aws_sns_verifier to your mix.exs:

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

Then run:

mix deps.get

Upgrading to plug_crypto 2.2.1

This release requires plug_crypto >= 2.2.1 to fix CVE-2026-105963.

If your application uses encrypted cookie sessions (Plug.Session with encryption_salt), Plug.Crypto 2.x encrypts new cookies with XChaCha20-Poly1305 and requires a 32-byte key:

• Set key_length: 32 (or omit it; 32 is the default). Values of 16 or 24 now raise when an encrypted session is written.

• Plug.Crypto 2.x can still decrypt old 1.x cookies when given the previous options. To keep old cookies readable during the transition, configure them under rotating_options and verify the result against your Plug version:

  plug Plug.Session,
    store: :cookie,
    key: "_my_app_session",
    signing_salt: "...",
    encryption_salt: "...",
    key_length: 32,
    rotating_options: [
      [key_length: 24, signing_salt: "...", encryption_salt: "..."]
    ]

  If rotating_options cannot read the old cookies in your deployment, force a fresh login instead.

• Do not run a mixed Plug.Crypto 1.x/2.x rollout: 1.x nodes cannot decrypt cookies written by 2.x. Upgrade all nodes together, or use a new cookie key/name for 2.x and let old sessions expire.

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