Acmex

This project is no longer maintained.

Acmex is an Elixir Client for the Lets Encrypt ACMEv2 protocol.

Status

Acmex is not used in production and have a very incomplete support to ACMEv2 protocol.
It does not have a good flexibility, because it uses a GenServer to keep the account state and application config to get the directory URL.

Installation

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

def deps do
  [
    {:acmex, "~> 0.2.0"}
  ]
end

Configure

Set the directory_url in your config.exs:

config :acmex,
  directory_url: "https://acme-v02.api.letsencrypt.org/directory"

If you need a staging version of Lets Encrypt ACMEv2 set the directory_url as https://acme-staging-v02.api.letsencrypt.org/directory.

Usage

Client

Starting the client

Acmex.start_link(key: account_rsa_key)

To use on your supervisor:

children = [
  {Acmex, [[key: "-----BEGIN RSA PRIVATE KEY-----..."]]}
]

Account

Creating a new account

The second parameter is about the agreement of the terms of service.

Acmex.new_account(["mailto:info@example.com"], true)

Fetch existing account

Acmex.get_account()

Order

Creating a new order

Acmex.new_order(["example.com"])

Fetch an existing order

Acmex.get_order(order.url)

Challenge

Receive a challenge

authorization = List.first(order.authorizations)
challenge = Acmex.Resource.Authorization.http(authorization)

Return a challenge response

Acmex.get_challenge_response(challenge)

Validate the challenge

{:ok, challenge} = Acmex.validate_challenge(challenge)

Fetch an existing challenge

Acmex.get_challenge(challenge.url)

Certificate

Finalize an order

order_key = Acmex.OpenSSL.generate_key(:rsa)
{:ok, csr} = Acmex.OpenSSL.generate_csr(order_key, ["example.com"])
{:ok, order} = Acmex.finalize_order(order, csr)

Get the certificate

Acmex.get_certificate(order)

Revoke a certificate

{:ok, certificate} = Acmex.get_certificate(order)
Acmex.revoke_certificate(certificate, 0)

Timeout

All the Acmex functions accept an optional parameter to set the process timeout. The default value is 5000ms.

Documentation

The full documentation can be found at https://hexdocs.pm/acmex.

Contributing

To run the tests you need an ACME Test Server. You can use Pebble. For this reason, there is a docker-compose.yml file with pebble defined as a service.

To use pebble and run the tests:

$ docker-compose up
$ mix test

License

MIT License

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.