• Uses acme4j internally for strong RFC compliance.
• Exclusively uses the DNS-01 ACME challenge type for ease of integration with infrastructure without having to set up insecure web servers.
• A small, easily auditable codebase with a heavy use of modularity for correctness.
• Exposes a service provider API for integrating with new DNS APIs.
• Exposes a service provider API for implementing new types of certificate outputs.
• Supports Hetzner DNS.
• Supports Vultr DNS.
• Supports Gandi LiveDNS.
• Supports writing certificates to looseleaf servers.
• Heavily instrumented with OpenTelemetry for reliable service monitoring.
• An extensive automated test suite with high coverage.
• A small footprint; the client is designed to run in tiny 16-32mb JVM heap configurations.
• Platform independence. No platform-dependent code is included in any form, and installations can largely be carried between platforms without changes.
• OSGi-ready
• JPMS-ready
• ISC license

• Maven Central
• Quay.io

$ gpg --verify com.io7m.certusine.cmdline-3.2.0-distribution.zip.asc
gpg: assuming signed data in 'com.io7m.certusine.cmdline-3.2.0-distribution.zip.asc'
gpg: Signature made Tue 28 Jun 2022 15:01:56 GMT
gpg:                using RSA key 3CCE59428B30462D10459909C5607DA146E128B8
gpg:                issuer "contact@io7m.com"
gpg: using pgp trust model
gpg: Good signature from "io7m.com (2022 maven-rsa-key) <contact@io7m.com>" [unknown]

$ unzip com.io7m.certusine.cmdline-3.2.0-distribution.zip
$ export CERTUSINE_HOME=$(realpath certusine)
$ ./certusine/bin/certusine
info: Usage: certusine [options] [command] [command options]
...

$ podman pull quay.io/io7mcom/certusine:3.2.0
$ podman run quay.io/io7mcom/certusine:3.2.0
certusine: usage: certusine [command] [arguments ...]
...

• Options
• Accounts
• Outputs
• DNSConfigurators
• Domains
• OpenTelemetry

<Options DNSWaitTime="PT5M"
         CertificateStore="store.db"
         CertificateExpirationThreshold="PT72H"/>

<Accounts>
  <Account Name="main"
           PublicKeyPath="example.pub"
           PrivateKeyPath="example.pri"
           AcmeURI="https://acme-staging-v02.api.letsencrypt.org/directory"/>
</Accounts>

<Outputs>
  <Output Type="directory"
          Name="main-output">
    <Parameters>
      <Parameter Name="path" Value="/tmp"/>
    </Parameters>
  </Output>
</Outputs>

<DNSConfigurators>
  <DNSConfigurator Type="vultr" Name="vultr-dns">
    <Parameters>
      <Parameter Name="api-key" Value="25DDk6MT+2JI5KBABMysYLPFEOge+MZE3/GiBgrR+CU="/>
      <Parameter Name="domain" Value="example.com"/>
    </Parameters>
  </DNSConfigurator>
</DNSConfigurators>

<Domain Name="example.com"
        Account="main"
        DNSConfigurator="vultr-dns">
  <Certificates>
    <Certificate Name="www"
                 PublicKeyPath="fake.pub"
                 PrivateKeyPath="fake.pri">
      <Hosts>
        <Host Name="www0"/>
        <Host Name="www1"/>
        <Host Name="www2"/>
      </Hosts>
    </Certificate>
    <Certificate Name="mail"
                 PublicKeyPath="fake.pub"
                 PrivateKeyPath="fake.pri">
      <Hosts>
        <Host Name="mail0"/>
        <Host Name="mail1"/>
      </Hosts>
    </Certificate>
    <Certificate Name="wildcard"
                 PublicKeyPath="fake.pub"
                 PrivateKeyPath="fake.pri">
      <Hosts>
        <Host Name="*"/>
      </Hosts>
    </Certificate>
  </Certificates>
  <OutputReferences>
    <OutputReference Name="main-output"/>
  </OutputReferences>
</Domain>

<OpenTelemetry LogicalServiceName="certusine">
  <Logs Endpoint="http://logs.example.com:4317"
        Protocol="GRPC"/>
  <Metrics Endpoint="http://metrics.example.com:4317"
           Protocol="GRPC"/>
  <Traces Endpoint="http://traces.example.com:4317"
          Protocol="GRPC"/>
</OpenTelemetry>

<?xml version="1.0" encoding="UTF-8" ?>

<Configuration xmlns="urn:com.io7m.certusine:configuration:1">

  <Options CertificateStore="store.db"
           DNSWaitTime="PT5M"
           CertificateExpirationThreshold="PT72H"/>

  <Accounts>
    <Account Name="main"
             PublicKeyPath="fake.pub"
             PrivateKeyPath="fake.pri"
             AcmeURI="https://acme-staging-v02.api.letsencrypt.org/directory"/>
  </Accounts>

  <Outputs>
    <Output Type="directory"
            Name="main-output">
      <Parameters>
        <Parameter Name="path"
                   Value="/tmp"/>
      </Parameters>
    </Output>
  </Outputs>

  <DNSConfigurators>
    <DNSConfigurator Type="vultr"
                     Name="vultr-dns">
      <Parameters>
        <Parameter Name="api-key"
                   Value="NOTANAPIKEY"/>
        <Parameter Name="domain"
                   Value="example.com"/>
      </Parameters>
    </DNSConfigurator>
  </DNSConfigurators>

  <Domains>
    <Domain Name="example.com"
            Account="main"
            DNSConfigurator="vultr-dns">
      <Certificates>
        <Certificate Name="www"
                     PublicKeyPath="fake.pub"
                     PrivateKeyPath="fake.pri">
          <Hosts>
            <Host Name="www0"/>
            <Host Name="www1"/>
            <Host Name="www2"/>
          </Hosts>
        </Certificate>
        <Certificate Name="mail"
                     PublicKeyPath="fake.pub"
                     PrivateKeyPath="fake.pri">
          <Hosts>
            <Host Name="mail0"/>
            <Host Name="mail1"/>
          </Hosts>
        </Certificate>
        <Certificate Name="wildcard"
                     PublicKeyPath="fake.pub"
                     PrivateKeyPath="fake.pri">
          <Hosts>
            <Host Name="*"/>
          </Hosts>
        </Certificate>
      </Certificates>
      <OutputReferences>
        <OutputReference Name="main-output"/>
      </OutputReferences>
    </Domain>
  </Domains>

</Configuration>

<?xml version="1.0" encoding="UTF-8" ?>

<schema xmlns="http://www.w3.org/2001/XMLSchema"
        xmlns:c="urn:com.io7m.certusine:configuration:1"
        targetNamespace="urn:com.io7m.certusine:configuration:1">

  <element name="Options">
    <complexType>
      <attribute name="DNSWaitTime"
                 type="duration"
                 use="optional">
        <annotation>
          <documentation>
            Specifies the amount of time that the client will wait between creating DNS records, and then notifying the
            ACME servers that the records have been created. This wait time is necessary because DNS records sometimes
            take time to propagate, and if the client instructs the ACME server to check the records before they have
            had time to propagate, then the certificate authorization check will fail.
          </documentation>
        </annotation>
      </attribute>

      <attribute name="CertificateStore"
                 type="string"
                 use="required">
        <annotation>
          <documentation>
            Specifies the file that the client will use for its internal database of certificates. Relative paths are
            resolved relative to the configuration file.
          </documentation>
        </annotation>
      </attribute>

      <attribute name="CertificateExpirationThreshold"
                 type="duration"
                 use="optional">
        <annotation>
          <documentation>
            Specifies the maximum amount of time before expiration that the client will allow before it attempts to
            renew a certificate. For example, a value of PT72H means that the client will start attempting to renew a
            certificate when the certificate becomes due to expire in less than 72 hours.
          </documentation>
        </annotation>
      </attribute>
    </complexType>
  </element>

  <element name="FaultInjection">
    <annotation>
      <documentation>
        Configuration for fault injection. The purpose of fault injection is to make the program fail in various ways at
        runtime in order to verify that metrics and alerting are working correctly.
      </documentation>
    </annotation>

    <complexType>
      <attribute name="FailTasks"
                 use="optional"
                 type="boolean">
        <annotation>
          <documentation>
            Specifies that failing tasks should be injected into the execution of tasks for each domain renewal.
          </documentation>
        </annotation>
      </attribute>

      <attribute name="FailDNSChallenge"
                 use="optional"
                 type="boolean">
        <annotation>
          <documentation>
            Specifies that DNS challenges should be purposefully failed.
          </documentation>
        </annotation>
      </attribute>

      <attribute name="FailSigningCertificates"
                 use="optional"
                 type="boolean">
        <annotation>
          <documentation>
            Specifies that certificate signing should be purposefully failed.
          </documentation>
        </annotation>
      </attribute>

      <attribute name="CrashTasks"
                 use="optional"
                 type="boolean">
        <annotation>
          <documentation>
            Specifies that crashing tasks should be injected into the execution of tasks for each domain renewal.
          </documentation>
        </annotation>
      </attribute>

      <attribute name="CrashDNSChallenge"
                 use="optional"
                 type="boolean">
        <annotation>
          <documentation>
            Specifies that DNS challenges should be purposefully crashed.
          </documentation>
        </annotation>
      </attribute>

      <attribute name="CrashSigningCertificates"
                 use="optional"
                 type="boolean">
        <annotation>
          <documentation>
            Specifies that certificate signing should be purposefully crashed.
          </documentation>
        </annotation>
      </attribute>
    </complexType>
  </element>

  <element name="Account">
    <complexType>
      <attribute name="Name"
                 type="string"
                 use="required">
        <annotation>
          <documentation>
            Specifies the name of that account. Names can be anything, but must be unique with respect to other
            accounts. The names are purely used for organizational purposes internally.
          </documentation>
        </annotation>
      </attribute>

      <attribute name="PublicKeyPath"
                 type="string"
                 use="required">
        <annotation>
          <documentation>
            Specifies the location of the account's public key. Relative paths are resolved relative to the
            configuration file.
          </documentation>
        </annotation>
      </attribute>

      <attribute name="PrivateKeyPath"
                 type="string"
                 use="required">
        <annotation>
          <documentation>
            Specifies the location of the account's private key. Relative paths are resolved relative to the
            configuration file.
          </documentation>
        </annotation>
      </attribute>

      <attribute name="AcmeURI"
                 type="anyURI"
                 use="required">
        <annotation>
          <documentation>
            Specifies the base URI that will be used for ACME operations.
          </documentation>
        </annotation>
      </attribute>
    </complexType>
  </element>

  <element name="Accounts">
    <complexType>
      <sequence minOccurs="0"
                maxOccurs="unbounded">
        <element ref="c:Account"/>
      </sequence>
    </complexType>

    <key name="AccountKey">
      <selector xpath="c:Account"/>
      <field xpath="@Name"/>
    </key>
  </element>

  <element name="Parameter">
    <complexType>
      <attribute name="Name"
                 use="required"
                 type="string"/>
      <attribute name="Value"
                 use="required"
                 type="string"/>
    </complexType>
  </element>

  <element name="Parameters">
    <complexType>
      <sequence minOccurs="0"
                maxOccurs="unbounded">
        <element ref="c:Parameter"/>
      </sequence>
    </complexType>

    <key name="ParameterKey">
      <selector xpath="c:Parameter"/>
      <field xpath="@Name"/>
    </key>
  </element>

  <element name="Output">
    <annotation>
      <documentation>
        An output destination for signed certificates.
      </documentation>
    </annotation>

    <complexType>
      <sequence minOccurs="1"
                maxOccurs="1">
        <element ref="c:Parameters"/>
      </sequence>
      <attribute name="Type"
                 type="string"
                 use="required">
        <annotation>
          <documentation>
            The type of the output. Must be one of the supported output types.
          </documentation>
        </annotation>
      </attribute>
      <attribute name="Name"
                 type="string"
                 use="required">
        <annotation>
          <documentation>
            The (unique) name of the output.
          </documentation>
        </annotation>
      </attribute>
    </complexType>
  </element>

  <element name="Outputs">
    <annotation>
      <documentation>
        A set of output destinations for signed certificates.
      </documentation>
    </annotation>

    <complexType>
      <sequence minOccurs="0"
                maxOccurs="unbounded">
        <element ref="c:Output"/>
      </sequence>
    </complexType>

    <key name="OutputKey">
      <selector xpath="c:Output"/>
      <field xpath="@Name"/>
    </key>
  </element>

  <element name="DNSConfigurator">
    <annotation>
      <documentation>
        A DNS configurator used to create and delete DNS records in response to ACME challenges.
      </documentation>
    </annotation>

    <complexType>
      <sequence minOccurs="1"
                maxOccurs="1">
        <element ref="c:Parameters"/>
      </sequence>
      <attribute name="Type"
                 type="string"
                 use="required"/>
      <attribute name="Name"
                 type="string"
                 use="required"/>
    </complexType>
  </element>

  <element name="DNSConfigurators">
    <annotation>
      <documentation>
        A set of DNS configurators.
      </documentation>
    </annotation>

    <complexType>
      <sequence minOccurs="0"
                maxOccurs="unbounded">
        <element ref="c:DNSConfigurator"/>
      </sequence>
    </complexType>

    <key name="DNSConfiguratorKey">
      <selector xpath="c:DNSConfigurator"/>
      <field xpath="@Name"/>
    </key>
  </element>

  <element name="Host">
    <annotation>
      <documentation>
        A hostname. Note that this is not a fully-qualified domain name.
      </documentation>
    </annotation>

    <complexType>
      <attribute name="Name"
                 use="required"
                 type="string"/>
    </complexType>
  </element>

  <element name="Hosts">
    <annotation>
      <documentation>
        A set of hostnames.
      </documentation>
    </annotation>

    <complexType>
      <sequence minOccurs="0"
                maxOccurs="unbounded">
        <element ref="c:Host"/>
      </sequence>
    </complexType>

    <unique name="HostsUnique">
      <selector xpath="c:Host"/>
      <field xpath="@Name"/>
    </unique>
  </element>

  <element name="Certificate">
    <annotation>
      <documentation>
        A set of definitions that describe a certificate that will be created and signed.
      </documentation>
    </annotation>

    <complexType>
      <sequence>
        <element ref="c:Hosts"/>
      </sequence>

      <attribute name="Name"
                 use="required"
                 type="string">
        <annotation>
          <documentation>
            The certificate name.
          </documentation>
        </annotation>
      </attribute>

      <attribute name="PublicKeyPath"
                 type="string"
                 use="required">
        <annotation>
          <documentation>
            Specifies the location of the certificate's public key. Relative paths are resolved relative to the
            configuration file.
          </documentation>
        </annotation>
      </attribute>

      <attribute name="PrivateKeyPath"
                 type="string"
                 use="required">
        <annotation>
          <documentation>
            Specifies the location of the certificate's private key. Relative paths are resolved relative to the
            configuration file.
          </documentation>
        </annotation>
      </attribute>
    </complexType>
  </element>

  <element name="Certificates">
    <annotation>
      <documentation>
        A set of certificate definitions.
      </documentation>
    </annotation>

    <complexType>
      <sequence minOccurs="0"
                maxOccurs="unbounded">
        <element ref="c:Certificate"/>
      </sequence>
    </complexType>

    <key name="CertificateKey">
      <selector xpath="c:Certificate"/>
      <field xpath="@Name"/>
    </key>
  </element>

  <element name="OutputReference">
    <annotation>
      <documentation>
        A reference to an output definition.
      </documentation>
    </annotation>

    <complexType>
      <attribute name="Name"
                 use="required"
                 type="string"/>
    </complexType>
  </element>

  <element name="OutputReferences">
    <annotation>
      <documentation>
        A set of references to output definitions.
      </documentation>
    </annotation>

    <complexType>
      <sequence minOccurs="1"
                maxOccurs="unbounded">
        <element ref="c:OutputReference"/>
      </sequence>
    </complexType>

    <unique name="OutputReferencesUnique">
      <selector xpath="c:OutputReference"/>
      <field xpath="@Name"/>
    </unique>
  </element>

  <element name="Domain">
    <annotation>
      <documentation>
        A set of definitions that define a domain.
      </documentation>
    </annotation>

    <complexType>
      <sequence>
        <element ref="c:Certificates"/>
        <element ref="c:OutputReferences"/>
      </sequence>

      <attribute name="Name"
                 use="required"
                 type="string">
        <annotation>
          <documentation>
            The fully qualified domain name.
          </documentation>
        </annotation>
      </attribute>

      <attribute name="Account"
                 use="required"
                 type="string">
        <annotation>
          <documentation>
            The account to which this domain belongs.
          </documentation>
        </annotation>
      </attribute>

      <attribute name="DNSConfigurator"
                 use="required"
                 type="string">
        <annotation>
          <documentation>
            The DNS configurator that will be used for this domain.
          </documentation>
        </annotation>
      </attribute>
    </complexType>
  </element>

  <element name="Domains">
    <annotation>
      <documentation>
        A set of domain definitions.
      </documentation>
    </annotation>

    <complexType>
      <sequence minOccurs="0"
                maxOccurs="unbounded">
        <element ref="c:Domain"/>
      </sequence>
    </complexType>

    <key name="DomainKey">
      <selector xpath="c:Domain"/>
      <field xpath="@Name"/>
    </key>
  </element>

  <simpleType name="OpenTelemetryProtocol">
    <annotation>
      <documentation>
        The protocol used to deliver OpenTelemetry data.
      </documentation>
    </annotation>

    <restriction base="string">
      <enumeration value="GRPC">
        <annotation>
          <documentation>
            The data will be sent using gRPC.
          </documentation>
        </annotation>
      </enumeration>
      <enumeration value="HTTP">
        <annotation>
          <documentation>
            The data will be sent using HTTP(s).
          </documentation>
        </annotation>
      </enumeration>
    </restriction>
  </simpleType>

  <element name="Metrics">
    <annotation>
      <documentation>
        Configuration information for OpenTelemetry metrics.
      </documentation>
    </annotation>

    <complexType>
      <attribute name="Endpoint"
                 use="required"
                 type="anyURI">
        <annotation>
          <documentation>
            The endpoint to which OTLP metrics data will be sent.
          </documentation>
        </annotation>
      </attribute>

      <attribute name="Protocol"
                 use="required"
                 type="c:OpenTelemetryProtocol">
        <annotation>
          <documentation>
            The protocol used to send metrics data.
          </documentation>
        </annotation>
      </attribute>
    </complexType>
  </element>

  <element name="Traces">
    <annotation>
      <documentation>
        Configuration information for OpenTelemetry traces.
      </documentation>
    </annotation>

    <complexType>
      <attribute name="Endpoint"
                 use="required"
                 type="anyURI">
        <annotation>
          <documentation>
            The endpoint to which OTLP trace data will be sent.
          </documentation>
        </annotation>
      </attribute>

      <attribute name="Protocol"
                 use="required"
                 type="c:OpenTelemetryProtocol">
        <annotation>
          <documentation>
            The protocol used to send trace data.
          </documentation>
        </annotation>
      </attribute>
    </complexType>
  </element>

  <element name="Logs">
    <annotation>
      <documentation>
        Configuration information for OpenTelemetry logs/events.
      </documentation>
    </annotation>

    <complexType>
      <attribute name="Endpoint"
                 use="required"
                 type="anyURI">
        <annotation>
          <documentation>
            The endpoint to which OTLP log data will be sent.
          </documentation>
        </annotation>
      </attribute>

      <attribute name="Protocol"
                 use="required"
                 type="c:OpenTelemetryProtocol">
        <annotation>
          <documentation>
            The protocol used to send log data.
          </documentation>
        </annotation>
      </attribute>
    </complexType>
  </element>

  <element name="OpenTelemetry">
    <annotation>
      <documentation>
        Configuration information for OpenTelemetry.
      </documentation>
    </annotation>

    <complexType>
      <sequence>
        <element ref="c:Logs"
                 minOccurs="0"
                 maxOccurs="1"/>
        <element ref="c:Metrics"
                 minOccurs="0"
                 maxOccurs="1"/>
        <element ref="c:Traces"
                 minOccurs="0"
                 maxOccurs="1"/>
      </sequence>

      <attribute name="LogicalServiceName"
                 use="required"
                 type="string">
        <annotation>
          <documentation>
            The logical name of the service as it will appear in OpenTelemetry.
          </documentation>
        </annotation>
      </attribute>
    </complexType>
  </element>

  <element name="Configuration">
    <annotation>
      <documentation>
        The configuration information for the certusine client.
      </documentation>
    </annotation>

    <complexType>
      <sequence>
        <element ref="c:Options"/>
        <element ref="c:Accounts"/>
        <element ref="c:Outputs"/>
        <element ref="c:DNSConfigurators"/>
        <element ref="c:Domains"/>
        <element ref="c:OpenTelemetry"
                 minOccurs="0"
                 maxOccurs="1"/>
        <element ref="c:FaultInjection"
                 minOccurs="0"
                 maxOccurs="1"/>
      </sequence>
    </complexType>

    <keyref name="DomainAccountsExist"
            refer="c:AccountKey">
      <selector xpath="c:Domains/c:Domain"/>
      <field xpath="@Account"/>
    </keyref>

    <keyref name="DomainDNSConfiguratorsExist"
            refer="c:DNSConfiguratorKey">
      <selector xpath="c:Domains/c:Domain"/>
      <field xpath="@DNSConfigurator"/>
    </keyref>

    <keyref name="OutputReferencesExist"
            refer="c:OutputKey">
      <selector xpath="c:Domains/c:Domain/c:OutputReferences/c:OutputReference"/>
      <field xpath="@Name"/>
    </keyref>
  </element>

</schema>

rate(certusine_renewal_failures_total[30m]) > bool 0

certusine_certificate_time_remaining{} < 252000

max(certusine_certificate_time_remaining{}) < bool max(certusine_certificate_expiration_threshold{})

count(rate({level="ERROR"} | json | attributes_certusine_type=`CSEventCertificateRenewalFailed`[30m])) > bool 0

<Output Type="Directory" Name="an-example-output">
  <Parameters>
    <Parameter Name="path" Value="/tmp"/>
  </Parameters>
</Output>

<Output Type="Looseleaf" Name="an-example-looseleaf-output">
  <Parameters>
    <Parameter Name="endpoint" Value="http://looseleaf.example.com:20000/"/>
    <Parameter Name="username" Value="grouch"/>
    <Parameter Name="password" Value="12345678"/>
  </Parameters>
</Output>

certusine: usage: certusine [command] [arguments ...]

  The certusine ACME client.

  Use the "help" command to examine specific commands:

    $ certusine help help.

  Command-line arguments can be placed one per line into a file, and
  the file can be referenced using the @ symbol:

    $ echo help > file.txt
    $ echo help >> file.txt
    $ certusine @file.txt

  Commands:
    check-configuration         Check configuration file.
    generate-keypair            Generate keypairs.
    help                        Show usage information for a command.
    looseleaf-download          Download certificates from looseleaf databases.
    renew                       Renew certificates.
    show-certificate-outputs    Show supported certificate outputs.
    show-dns-configurators      Show supported DNS configurators.
    version                     Show the application version.

  Documentation:
    https://www.io7m.com/software/certusine/

$ certusine check-configuration --file config.xml

$ (cat <<EOF
check-configuration
--file
config.xml
EOF
) > args.txt

$ certusine @args.txt