danielsz.certificaat

<div>
  <h1>danielsz.certificaat</h1>
  <p>
    <a href="https://github.com/danielsz/certificaat.git">https://github.com/danielsz/certificaat.git</a>
  </p>

  
    <code class="clone">
    git clone 'https://github.com/danielsz/certificaat.git'
      <br>
      <br>
(ql:quickload :danielsz.certificaat)
    </code>
  

  <div class="star-area">
    <span class="starlabel">&#9733;</span><span class="stars">73</span>
  </div>
  <hr>
  
    <ul>
<li>Certificaat
<em>* Definition
Certificaat is a general-purpose [[https://tools.ietf.org/html/draft-ietf-acme-acme-06][ACME]] client, fully compatible with the [[https://letsencrypt.org/][Let’s Encrypt]] CA.
*</em> Motivation
Certificaat’s aim is to help you retrieve a certificate for your domain, and subsequently help you set up a cron job and forget about it.</li>
</ul>

<p>/Note:/ If [[https://certbot.eff.org/][certbot]] does everything for everybody, Certificaat is narrower in scope, focusing on usability and automated renewals.<br/>
** Installation
[[https://github.com/danielsz/certificaat/releases/latest][Download]] the latest release, extract the archive and drop the self-contained binary in your ~PATH~.</p>

<p>/Note:/ Java is a system requirement.</p>

<p>** Usage
<em>*</em> Command line</p>

<p>To get a certificate for a domain, you need to initialize ~certificaat~ with said domain, then you ~run~ it repeatedly until your certificate has downloaded.</p>

<ol>
<li>~certificaat -m change.me init~</li>
<li>~certificaat -m change.me run~</li>
</ol>

<p>The certificate can be renewed in one pass with ~certificaat -m change.me cron~.</p>

<p>**** Init</p>

<h1>+BEGIN_SRC shell</h1>

<p>certificaat -m change.me init</p>

<h1>+END_SRC</h1>

<p>The ~-m~ option indicates the domain you want to authorize. It will feature in the Subject name of the final X.509 certificate.</p>

<h1>+BEGIN_SRC shell</h1>

<p>certificaat -m change.me -n www.change.me init</p>

<h1>+END_SRC</h1>

<p>The ~-n~ option is for additional domain name you want to
authorize. It will feature in the Subject Alternative Name a(SAN) of
the certificate. Repeat this option for all required names. Caution:
there is a hard limit imposed by the CA.</p>

<p>During this phase, certificaat will, if needed, register a user
account with the ACME CA, and write configuration files that you then
can edit and customize.</p>

<p>Certificaat follows the [[https://specifications.freedesktop.org/basedir-spec/latest/][XDG Base Directory Specification]]. The
configuration folder is determined by querying the value of
~XDG_CONFIG_HOME~ in the environment, and if not set, will default to
~$HOME/.config/certificaat~.</p>

<p>Configuration files are in [[https://github.com/edn-format/edn][edn]] format and can be edited in any text
editor. </p>

<p>The local configuration file is stored in the project directory,
~$HOME/.config/certificaat/change.me/config.edn~ , and looks like
this:</p>

<h1>+BEGIN_SRC clojure</h1>

<p>{:acme-uri &ldquo;acme://letsencrypt.org/staging&rdquo;,
 :challenges #{&ldquo;http-01&rdquo;},
 :contact &ldquo;mailto:admin@change.me&rdquo;,
 :domain &ldquo;change.me&rdquo;,
 :hooks [:before-challenge :after-request],
 :organisation &ldquo;ChangeMe corporation&rdquo;,
 :san #{&ldquo;www.change.me&rdquo;}}</p>

<h1>+END_SRC</h1>

<p>Hopefully, the options are self-explanatory. </p>

<ul>
<li>the email address used by the CA to send expiry reminders.</li>
<li>the challenge you want to complete. If you want to offer the CA multiple challenges, that is supported as well.</li>
<li>the URI to the ACME CA. By default, Certificaat will talk to Let’s Encrypt’s staging server. The resulting certificates will be fake. This is so you can practice until you are ready to issue a production certificate.</li>
</ul>

<p>| Staging URI                    | Production URI         |
| acme://letsencrypt.org/staging | acme://letsencrypt.org |</p>

<p>The global configuration is stored in the root directory,
~$HOME/.config/certificaat/change.me/config.edn~ and it looks like
this:</p>

<h1>+BEGIN_SRC clojure</h1>

<p>{:key-size 2048,
 :key-type :rsa,
 :keypair-filename &ldquo;account.key&rdquo;,
 :plugins {:diffie-hellman {:enabled false,
                            :filename &ldquo;dhparam.pem&rdquo;,
                            :group14 true,
                            :modulus 2048},
           :email {:enabled false,
                   :sendmail false,
                   :smtp {:host &ldquo;smtp.changeme.org&rdquo;,
                          :pass &ldquo;changeme&rdquo;,
                          :port 587,
                          :user &ldquo;changeme&rdquo;}},
           :webroot {:enabled false, :path &ldquo;/var/www/&rdquo;}}}</p>

<h1>+END_SRC</h1>

<p>**** Run</p>

<h1>+BEGIN_SRC shell</h1>

<p>certificaat -m change.me run </p>

<h1>+END_SRC</h1>

<p>~certificaat~ will display instructions pertaining to the challenge. This is the time to satisfy the requirements (for example, configuring DNS records or preparing your web server). When you are ready, simply repeat the operation and the challenges will be triggered and, if successfully completed, a certificate downloaded and saved to disk.</p>

<p>**** Hooks</p>

<p>Hooks are provided to perform additional functionality at key moments, namely before the challenges get triggered, and after a certificate has been acquired or renewed. The hooks are powered by plugins that need to be configured and enabled. </p>

<p>The plugin configuration resides in the root directory, ~XDG_CONFIG_HOME/.config/certificaat/config.edn~</p>

<p>***** Webroot
This enables authorizing and requesting the certificate in a single pass.
***** Email
An email will be sent to the contact registered with the certificate. 
***** Diffie-Helman parameters
This will save a Diffie-Helman parameters file along with the certificate, for further tuning the SSL setup.</p>

<p>**** Info</p>

<h1>+BEGIN_SRC shell</h1>

<p>certificaat -m example.com info</p>

<h1>+END_SRC</h1>

<p>Certificaat will display a summary of the certificate. </p>

<p>**** Renew</p>

<h1>+BEGIN_SRC shell</h1>

<p>certificaat -m example.com cron</p>

<h1>+END_SRC</h1>

<p>This command can be integrated in an automated workflow. For example, as a cron job.</p>

<h1>+BEGIN_SRC shell</h1>

<p>5 8 1 * * certificaat -m change.me cron &amp;&amp; /usr/sbin/service nginx reload</p>

<h1>+END_SRC</h1>

<p>** Challenges</p>

<p>Certificaat will honor all challenges defined in the ACME specification, but please note that Let’s Encrypt CA does not support the OOB challenge and that TLS-SNI comes in two flavors. </p>

<p>| Challenge                             | Option identifier       | Let’s Encrypt | Certificaat |
| HTTP                                  | http-01                 | ✓             | ✓           |
| DNS                                   | dns-01                  | ✓             | ✓           |
| TLS with Server Name Indication (SNI) | tls-sni-01 &amp; tls-sni-02 | ✓ &amp; ✕         | ✓           |
| Out-of-Band                           | oob-01                  | ✕             | ✓           |</p>

<p>** Clojure library
In addition to the command line, Certificaat is available on [[https://clojars.org/][Clojars]] as a regular Clojure library which you can require in your projects.</p>

<p>[[http://clojars.org/org.danielsz/certificaat/latest-version.svg]]</p>

<p>/Note/: a single namespace exposes a core API which is made available to all interfaces.</p>

<p>** Contributions
If you plan to submit enhancements beyond bug fixes, please coordinate with me beforehand in order to save everybody’s time and effort.
<em>* Credits
I wish to thank [[https://shredzone.org/maven/acme4j/][Richard Körber]] who wrote the Java client for the ACME protocol, [[https://github.com/shred/acme4j][acme4j]], which serves as the foundation for Certificaat. Not only is it well written, it is exquisitely [[https://shredzone.org/maven/acme4j/][documented]]. 
*</em> License
Licensing terms will be revealed shortly. In the meantime, do what you want with it.
Type ~certificaat -h~ to familiarize yourself with the input it
expects.
For as long as the authorizations remain valid, </p>

<p>/Note:/ With LetsEncrypt, cached authorizations last for 30 days from the time of validation.</p>

  
</div>