Initial commit

.formatter.exs

@@ -0,0 +1,5 @@
+# Used by "mix format"
+[
+  inputs: ["{mix,.formatter}.exs", "{config,lib,test}/**/*.{ex,exs}"],
+  import_deps: [:plug]
+]

.gitignore

@@ -0,0 +1,26 @@
+# The directory Mix will write compiled artifacts to.
+/_build/
+
+# If you run "mix test --cover", coverage assets end up here.
+/cover/
+
+# The directory Mix downloads your dependencies sources to.
+/deps/
+
+# Where third-party dependencies like ExDoc output generated docs.
+/doc/
+
+# Ignore .fetch files in case you like to edit your project deps locally.
+/.fetch
+
+# If the VM crashes, it generates a dump, let's ignore it too.
+erl_crash.dump
+
+# Also ignore archive artifacts (built via "mix archive.build").
+*.ez
+
+# Ignore package tarball (built via "mix hex.build").
+plug_signature-*.tar
+
+plug_signature_example/_build/
+plug_signature_example/deps/

.travis.yml

@@ -0,0 +1,15 @@
+language: elixir
+sudo: false
+script: mix test
+matrix:
+  include:
+  - elixir: '1.9.4'
+    otp_release: '22.2'
+  - elixir: '1.9.0'
+    otp_release: '22.0'
+  - elixir: '1.8.2'
+    otp_release: '21.3'
+  - elixir: '1.7.3'
+    otp_release: '21.1'
+  - elixir: '1.6.6'
+    otp_release: '21.0'

LICENSE

@@ -0,0 +1,27 @@
+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.

README.md

@@ -0,0 +1,168 @@
+# PlugSignature
+
+Plug for verifying request signatures according to the IETF HTTP signatures
+[draft specification](https://tools.ietf.org/html/draft-cavage-http-signatures-12).
+
+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](https://bluecode.com/).
+
+The HTTP Date header parsing module was vendored from
+[cowlib](https://github.com/ninenines/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:
+
+```elixir
+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](https://hex.pm/packages/plug_body_digest)
+package, e.g. to the application's Phoenix Endpoint:
+
+```elixir
+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:
+
+```elixir
+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:
+
+```elixir
+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):
+
+```elixir
+def deps do
+  [
+    {:plug_body_digest, "~> 0.5.0"},
+    {:plug_signature, "~> 0.5.0"}
+  ]
+end
+```
+
+Documentation can be found at [https://hexdocs.pm/plug_signature](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.