# Certbot
[![Build Status](]( [![Hex pm](]( [![Hex Docs](]( [![License](](

Provide certificates for your Phoenix or Plug app using Letsencrypt.

This package should for now be considered a POC. Not everything is implemented
at the moment, most notably, certificate renewal.

You can also set your own Certificate Provider for your own functionality, or
to provide different certificates for different hostnames.

## Installation

The package can be installed
by adding `certbot` to your list of dependencies in `mix.exs`:

def deps do
    {:certbot, "~> 0.5.0"}

### Setting up Letsencrypt with Phoenix
From then on there are a few steps, we need to setup a certbot client, a store
for the certificates and a store for Acme challenges. Furthermore we need to setup
`Certbot.Acme.Plug` to verify Acme challenges over http.

### Certbot client
First, a certbot client is needed. We use a self generated private key to build 
into a JWK. If you have a Phoenix project, this can be generated with 
`mix phx.gen.cert`

Furthermore, we set an AcmeCertificateProvider
defmodule Myapp.CertbotClient do
  @jwk "priv/cert/selfsigned_key.pem"
       |> JOSE.JWK.from_pem()
       |> JOSE.JWK.to_map()

  use Certbot,
    certificate_provider: Myapp.AcmeCertificateProvider,
    jwk: @jwk,
    email: "

defmodule Myapp.AcmeCertificateProvider do
  use Certbot.Provider.Acme,
    challenge_store: Certbot.Acme.ChallengeStore.Default,
    certificate_store: Certbot.CertificateStore.Default,
    acme_client: Myapp.CertbotClient

The `Myapp.CertbotClient` doubles as an Acme client, and therefore needs to be added 
to the supervision tree of your application. We use, the default challenge/certificate 
stores of the package, they also need to be added your application supervision 
tree. Note, there are downsides to the stores, see their docs for more info.

Your supervision tree will look something like this in a Phoenix project
# application.ex

children = [
  # Start the Ecto repository
  # Start the endpoint when the application starts

In your `endpoint.ex` you should add `Certbot.Acme.Plug`, with the same challenge
store and `jwk`.

It should be added before the router, and before Plug.SSL if force SSL redirects 
are turned on.

# endpoint.ex
@jwk "priv/cert/selfsigned_key.pem" |>!() |> JOSE.JWK.from_pem() |> JOSE.JWK.to_map()

plug Certbot.Acme.Plug, challenge_store: Certbot.Acme.ChallengeStore.Default, jwk: @jwk
plug MyappWeb.Router

As a last step we need configure the https endpoint to dynamically return certificates.

config :myapp, MyappWeb.Endpoint,
  http: [port: 6000],
  https: [
    cipher_suite: :strong,
    port: 6001,
    sni_fun: &Myapp.CertbotClient.sni_fun/1 #Set the sni_fun

This tells cowboy to call `sni_fun/1` with the hostname of the request. This
function will ask the certificate provider for a certificate. The certificate provider
will return one, or first request one from Letsencrypt and then return it.

## FAQ
Is this tested in production?
 - No, be careful

Can I test this against a non-production acme server
 - Yes, you need to set the `:server` to ``

Does it do certificate renewal?
 - Not yet, should not be really hard to do. Every now and then a sweep of the 
 certificate store to check for certificates that are about to expire, and renew
 a certificate for them.

How can I test this locally?
 - You need to make sure port 80 is available for the Acme server to request with
 the token verification call. You'll need to map port 80 to the https port you
 configured your endpoint to.

Are multiple account keys supported?
 - No, not yet. But willing to accept PR's.

How are multiple concurrent requests handled with certification requests?
 - Nothing is done, ideally some kind of lock is placed so requests after the first
 one will wait till a certificate is retrieved and then use this certificate. Nothing of the kind is done.

What happens if I request too many certificates?
 - You'll be ratelimited by Letsencrypt

I am debugging but don't see errors appearing?
 - Because everything happens as a result of calling the `sni_fun/1` callback,
 this is at such a level that many errors don't seem to appear.

What version of the Acme protocol is used?
 - Acme V1 is used, many thanks to this package:

Are alternative challenge methods (`dns-01`, `tls-sni-01`,`tls-alpn-01`)?
 - No, `tls-alpn-01` is currently not supported by the Acme client but would be interesting
 as it would make it unnecessary te expose port 80. `tls-sni-01` is not secure and
 `dns-01` is out of scope as of now. 

### Errors
```[error] %Certbot.Error{detail: "JWS has invalid anti-replay nonce twT0up7DWSrbe163DiRuKnPwd4ZpyXVER0p-COl1vAA", status: 400, type: "urn:acme:error:badNonce"}```
 - This is not handled yet, the nonce should be refreshed and then the request repeated.

```[error] Certbot.Acme.Client Certbot.Acme.Client received unexpected message in handle_info/2: {:ssl_closed, {:sslsocket, {:gen_tcp, #Port<0.76>, :tls_connection, :undefined}, [#PID<0.851.0>, #PID<0.850.0>]}}```
 - Don't know why this happens...

## Documentation
Documentation can be generated with [ExDoc](
and published on [HexDocs]( Once published, the docs can
be found at [](