PlugSignature

Plug for verifying request signatures according to the IETF HTTP signatures draft specification.

Supports the following algorithms:

• "hs2019", using ECDSA, RSASSA-PSS or HMAC
• "rsa-sha256", using RSASSA-PKCS1-v1_5
• "ecdsa-sha256"
• "hmac-sha256"
• "rsa-sha1", using RSASSA-PKCS1-v1_5

Development and public release of this package were made possible by Bluecode.

The HTTP Date header parsing module was vendored from cowlib, due to build issues that prevented use of the package as a dependency. Cowlib is copyright (c) 2013-2018, Loïc Hoguin

Usage

Use PlugSignature in a Phoenix (or other Plug-based) application.

Requests with a valid signature are allowed to proceed while all others are rejected. Both the success and the failure behaviour can be customized.

PlugSignature requires a callback module that implements the PlugSignature.Callback behaviour. In a Phoenix application this would typically live in a 'context' module, and it might look something like this:

defmodule MyApp.Auth do
  import Ecto.Query, only: [from: 2]

  alias MyApp.Repo
  alias MyApp.Auth.AccessKey

  @behaviour PlugSignature.Callback

  @impl true
  def client_lookup(key_id, "hs2019", _conn) do
    query = from a in AccessKey,
      where: a.key_id == ^key_id,
      preload: :client

    case Repo.one(query) do
      nil ->
        {:error, "Invalid access key ID: #{key_id}"}

      {:ok, %AccessKey{revoked: true}} ->
        {:error, "Access key revoked: #{key_id}"}

      {:ok, %AccessKey{public_key: pem, client: client}} ->
        public_key = X509.PublicKey.from_pem!(pem)
        {:ok, client, public_key}
    end
  end
end

To enable verification of the request body, through the HTTP Digest header, add PlugBodyDigest from the plug_body_digest package, e.g. to the application's Phoenix Endpoint:

defmodule MyAppWeb.Endpoint do
  # ...

  plug Plug.Parsers,
    parsers: [:urlencoded, :multipart, :json],
    pass: ["*/*"],
    json_decoder: Phoenix.json_library(),
    body_reader: {PlugBodyDigest, :digest_body_reader, []}

  plug PlugBodyDigest
end

Finally, add PlugSignature, for instance to a Phoenix Router pipeline:

defmodule MyAppWeb.Router do
  # ...

  pipeline :api do
    plug :accepts, ["json"]
    plug PlugSignature,
      callback_module: MyApp.Auth,
      headers: "(request-target) (created) host digest",
      on_success: {PlugSignature, :assign_client, [:client]}
  end

  # ...
end

Alternatively it may be used inside a controller's pipeline, possibly with guards:

defmodule MyAppWeb.SomeController do
  use MyAppWeb, :controller

  plug PlugSignature, [
    callback_module: MyApp.Auth,
    headers: "(request-target) (created) host digest"
  ] when not action in [:show, :index]

  # ...
end

The directory plug_signature_example in the package source repository contains a minimal functional sample application, implemented as a simple Plug server that echos back the request parameters after signature authentication.

Client implementation

The sample application includes clients written in Elixir, using Tesla middleware, and as a shell script, using OpenSSL and cURL.

Installation

Add plug_signature to your list of dependencies in mix.exs (and consider adding plug_body_digest as well):

def deps do
  [
    {:plug_body_digest, "~> 0.5.0"},
    {:plug_signature, "~> 0.6.0"}
  ]
end

Documentation can be found at https://hexdocs.pm/plug_signature.

License

Copyright (c) 2019, Bram Verburg All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

• Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

• Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

• Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.