plug_gpg_verify does the work of verifing a public key by generating a random challenge, sending that challenge to the user and expecting the response, having the client sign the challenge and send it back, then verifying the signature.

This makes a couple of assumptions:

1. GPG is setup and working correctly on your system.
   • this uses gpgmex which requires the rust toolchain installed and working
2. The public key we are validating has already been imported

What this is NOT

1. This is NOT a way to authenticate. Authentication is left as an excersise to the user of the library
2. This does NOT in any way import PGP keys, or verify that the email associated with the public_key is valid.

example-usage

Example Usage

Put this plug somewhere in your router

scope "/verify" do
  pipe_through(:api)
  forward "/", PlugGPGVerify, adapter: MyProject.GPGVerificationPlug
end

Create a module that implements the PlugGPGVerify behaviour

defmodule MyProject.GPGVerificationPlug do
  use PlugGPGVerify

  @impl true
  def find_user_by_email(email) do
    case Repo.get_by(User, :email, email) do
      nil -> {:error, :not_found}
      user -> {:ok, %{id: user.id, email: user.email}}
    end
  end

  @impl true
  def challenge_created(user, challenge) do
    changeset = User.changeset(
      %User{id: user.id, email: user.email}, 
      %{
        challenge: plain_text_challenge,
        challenge_expiration: DateTime.add(DateTime.utc_now(), 1, :hour)
      }
    )
    Repo.update(changeset)
  end

  @impl true
  def find_user_by_id(id) do
    case Repo.get(User, id) do
      nil -> {:error, :not_found}
      user ->
        # verify expiration
        {:ok, %{id: user.id, email: user.email, challenge: challenge}}
    end
  end

  @impl true
  def gpg_verified(conn, user) do 
    # do whatever you want with the connection
    token = Phoenix.Token.sign(MyAppWeb.Endpoint, "user auth", user.id)
    conn
    |> put_status(200)
    |> Controller.json(%{token: token})
  end
end

Your application accepts two new requests at /verify (or whatever route you defined):

• GET /verify?email="user@email.com"
• POST /verify

get-verify

GET /verify

If a user is found (via the find_user_by_email/1 callback), AND they have a public_key configured on the system, a new challenge is generated and encrypted.

A 201 is sent back with a JSON response of:

{
  challenge: string,
  user_id: string
}

post-verify

POST /verify

This accepts a json body of:

{
  challenge_response: string,
  user_id: string
}

where challenge_response is the signed challenge

flow-diagram

Flow Diagram

sequenceDiagram
  Client->>Server: GET /verify?email=example@email.com
  Server->>Client: {user_id: 1234, challenge: "challenge string"}
  Client->>Server: POST /verify {user_id: 1234, challenge_response: "-----BEGIN PGP MESSAGE----- ..."}
  Server->>Client: 200