FreeBSD Manual Pages

home | help

ACMED.TOML(5) File Formats Manual ACMED.TOML(5)

NAME
acmed.toml -- ACMEd configuration file

DESCRIPTION
acmed.toml is the configuration file for acmed(8). It is written in
the TOML format. The allowed elements are described below.

account
Array of table representing an account on one or several end-
point.

contacts array
Array of tables describing describing the account
holder's contact information. Each table must have one
and only one key-value pair. Possible keys and their
associated values are:

mailto string
A mailto URI as defined by RFC 6068. This URI
cannot contains neither "hfields" nor more than
one "addr-spec" in the "to" component.

env table
Table of environment variables that will be accessible
from hooks.

external_account table
Table containing the information required to bind the
account to an external one. Possible fields and values
are:

identifier string
ASCII string identifying the key.

key string
Private key encoded in base64url without
padding.

signature_algorithm string
Name of the signature algorithm used to sign
the external account binding message sent to
the endpoint as defined in RFC 7518. Possible
values are:
- HS256 <default>
- HS384
- HS512

hooks array
Names of hooks that will be called during operations on
the account storage file. The hooks are guaranteed to
be called sequentially in the declaration order.

key_type string
Name of the asymmetric cryptography algorithm used to
generate the key pair. Possible values are:
- ed25519
- ed448
- ecdsa_p256 <default>
- ecdsa_p384
- ecdsa_p521
- rsa2048
- rsa4096

name string
The name the account is registered under. Must be
unique.

signature_algorithm string
Name of the signature algorithm used to sign the mes-
sages sent to the endpoint as defined in RFC 7518. The
default value is derived from the key type. Possible
values are:
- ES256
- ES384
- ES512
- RS256

certificate
Array of table representing a certificate that will be re-
quested to a CA.

Note that, by default, certificates are identified by the first
identifier in the list of identifiers. That means that if you
reorder the identifiers so that a different identifier is at
the first position, a new certificate with a new name will be
issued.

account string
Name of the account to use.

csr_digest string
Name of the certificate's signing request digest algo-
rithm. Possible values are:
- sha256 <default>
- sha384
- sha512

directory string
Path to the directory where certificates and their as-
sociated private keys are stored.

endpoint string
Name of the endpoint to use.

env table
Table of environment variables that will be accessible
from hooks.

file_name_format string
Template used to build the file's name. The template
syntax is TinyTemplate. See the "STANDARDS" section
for a link to the TinyTemplate specifications. If not
specified, the value defined in the endpoint element,
and then the global element, is used. Default is "{
name }_{ key_type }.{ file_type }.{ ext }". Possible
variables are:

ext string
File extension. Currently, only "pem" is sup-
ported.

file_type string
Contains "pk" for the private key file and
"crt" for the certificate file.

key_type string
The certificate's private key type.

name string
The certificate's name.

hooks array
Names of hooks that will be called when requesting a
new certificate. The hooks are guaranteed to be called
sequentially in the declaration order.

identifiers array
Array of tables listing the identifiers that should be
included in the certificate along with the challenge to
use for each one. The dns and ip fields are mutually
exclusive.

challenge string
The name of the challenge to use to prove the
identifier's ownership. Possible values are:
- dns-01
- http-01
- tls-alpn-01

dns string
The domain name.

env table
Table of environment variables that will be ac-
cessible from hooks.

ip string
The IP address.

key_type string
Name of the asymmetric cryptography algorithm used to
generate the certificate's key pair. Possible values
are:
- ed25519
- ed448
- ecdsa_p256
- ecdsa_p384
- ecdsa_p521
- rsa2048 <default>
- rsa4096

kp_reuse boolean
Set whether or not the private key should be reused
when renewing the certificate. Default is false.

name Name of the certificate. Must be unique unless the key
type is different. Will be used in logs and in the as-
sociated file's name. The `*', `:' and `/' characters
will be replaced by an underscore. Default is the first
identifier.

renew_delay string
Period of time between the certificate renewal and its
expiration date. The format is described in the "TIME
PERIODS" section. Default is the value defined in the
associated endpoint.

subject_attributes table
Table where the certificate's subject attributes are
specified. Possible keys, with their RFC 4519 and X.500
equivalents, are:

ACMEd key RFC
4519 X.500
country_name c countryName
generation_qualifier generationQualifier
given_name givenName
initials initials
locality_name l localityName
name name
organization_name o organizationName
organizational_unit_name ou organizationalUnitName
pkcs9_email_address
postal_address postalAddress
postal_code postalCode
state_or_province_name st stateOrProvinceName
street street streetAddress
surname sn surname
title title

endpoint
Array of table where each element defines a Certificate Author-
ity (CA) which may be used to request certificates.

file_name_format string
Template used to build the file's name. For detailed
documentation, see the file_name_format directive lo-
cated in the certificate element.

name string
The name the endpoint is registered under. Must be
unique.

rate_limits array
Array containing the names of the HTTPS rate limits to
apply.

renew_delay string
Period of time between the certificate renewal and its
expiration date. The format is described in the "TIME
PERIODS" section. Default is the value defined in the
global section.

root_certificates array
Array containing the path to root certificates that
should be added to the trust store.

tos_agreed boolean
Set whether or not the user agrees to the Terms Of Ser-
vice (TOS).

url string
The endpoint's directory URL.

global Table containing the global configuration options.

accounts_directory string
Specify the directory where the accounts private and
public keys are stored.

cert_file_group group_name|group_id string
Specify the group who will own newly-created certifi-
cates files. See chown(2) for more details.

cert_file_mode integer
Specify the permissions to use for newly-created cer-
tificates files. See chmod(2) for more details.

cert_file_user username|user_id string
Specify the user who will own newly-created certifi-
cates files. See chown(2) for more details.

certificates_directory string
Specify the directory where the certificates and their
associated private keys are stored.

env table
Table of environment variables that will be accessible
from hooks.

file_name_format string
Template used to build the file's name. For detailed
documentation, see the file_name_format directive lo-
cated in the certificate element.

pk_file_group group_name|group_id string
Specify the group who will own newly-created private-
key files. See chown(2) for more details.

pk_file_mode integer
Specify the permissions to use for newly-created pri-
vate-key files. See chmod(2) for more details.

pk_file_user username|user_id string
Specify the user who will own newly-created private-key
files. See chown(2) for more details.

renew_delay string
Period of time between the certificate renewal and its
expiration date. The format is described in the "TIME
PERIODS" section. Default is 3w.

root_certificates array
Array containing the path to root certificates that
should be added to the trust store.

group Array of table allowing to group several hooks as one. A group
is considered as new hook.

hooks array
Array containing the names of the hooks that are
grouped. The hooks are guaranteed to be called sequen-
tially in the declaration order.

name string
The name the group is registered under. This name is
considered as a hook name. Must be unique.

hook Array of table where each element defines a command that will
be launched at a defined point. See section "WRITING A HOOK"
for more details.

allow_failure boolean
Defines if an error return value for this hook is al-
lowed or not. If not allowed, a failure in this hook
will fail the whole certificate request process. De-
fault is false.

args array
Array of strings representing the command's arguments.

cmd string
The name of the command that will be launched.

name string
The name the hook is registered under. Must be unique.

stderr string
Path to the file where the command's standard error
output if written.

stdin string
Path to the file that will be written into the com-
mand's standard intput. Mutually exclusive with
stdin_str.

stdin_str string
String that will be written into the command's standard
input. Mutually exclusive with stdin.

stdout string
Path to the file where the command's standard output if
written.

type array
Array of strings. Possible types are:
- challenge-dns-01
- challenge-dns-01-clean
- challenge-http-01
- challenge-http-01-clean
- challenge-tls-alpn-01
- challenge-tls-alpn-01-clean
- file-post-create
- file-post-edit
- file-pre-create
- file-pre-edit
- post-operation

include
Array containing the path to configuration file to include. The
path can be either relative or absolute. If relative, it is
relative to the configuration file which included it.

In case or overlapping global option definition, the one of the
last included file will be used. For example, if a file A in-
cludes files B and C and all three defines the same global op-
tion, the final value will be the one defined in file C.

Unix style globing is supported.

rate-limit
Array of table where each element defines a HTTPS rate limit.

name string
The name the rate limit is registered under. Must be
unique.

number integer
Number of requests authorized withing the time period.

period string
Period of time during which a maximal number of re-
quests is authorized. The format is described in the
"TIME PERIODS" section.

WRITING A HOOK
When requesting a certificate from a CA using ACME, there are three
steps that are hard to automatize. The first one is solving challenges
in order to prove the ownership of every identifier to be included: it
requires to interact with the configuration of other services, hence
depends on how the infrastructure works. The second one is restarting
all the services that use a given certificate, for the same reason. The
last one is archiving: although several default methods can be imple-
mented, sometimes admins wants or are required to do it in a different
way.

In order to allow full automation of the three above steps without im-
posing arbitrary restrictions or methods, acmed(8) uses hooks. Funda-
mentally, a hook is a command line template that will be called at a
specific time of the process. Such an approach allows admins to use any
executable script or program located on the machine to customize the
process.

For a given certificate, hooks are guaranteed to be called sequentially
in the declaration order. It is therefore possible to have a hook that
depends on another one. Nevertheless, several certificates may be re-
newed at the same time. Hence, hooks shall not use globing or any other
action that may disrupt hooks called by a different certificate.

A hook has a type that will influence both the moment it is called and
the available template variables. It is possible to declare several
types. In such a case, the hook will be invoked whenever one of its
type request it. When called, the hook only have access to template
variable for the current type. If a hook uses a template variable that
does not exists for the current type it is invoked for, the variable is
empty.

When writing a hook, the values of args, stdin, stdin_str, stdout and
stderr are considered as template strings whereas cmd is not. The tem-
plate syntax is TinyTemplate. See the "STANDARDS" section for a link
to the TinyTemplate specifications.

The available types and the associated template variable are described
below.

challenge-dns-01
Invoked when the ownership of an identifier must be proved us-
ing the dns-01 challenge. The available template variables are:
challenge string
The name of the challenge type <dns-01>. Mostly used
in hooks with multiple types.
env array
Array containing all the environment variables.
identifier string
The identifier name whom ownership is currently being
validated.
is_clean_hook bool
False
proof string
The content of the proof that must be written to a
`TXT' entry of the DNS zone for the `_acme-challenge'
subdomain.

challenge-dns-01-clean
Invoked once an identifier ownership has been proven using the
dns-01 challenge. This hook is intended to remove the proof
since it is no longer required. The template variables are
strictly identical to those given in the corresponding
challenge-dns-01 hook, excepted is_clean_hook which is set to
true.

challenge-http-01
Invoked when the ownership of an identifier must be proved us-
ing the http-01 challenge. The available template variables
are:
challenge string
The name of the challenge type <http-01>. Mostly used
in hooks with multiple types.
env array
Array containing all the environment variables.
file_name string
Name of the file containing the proof. This is not a
full path and does not include the
`.well-known/acme-challenge/' prefix.
identifier string
The identifier name whom ownership is currently being
validated.
is_clean_hook bool
False
proof string
The content of the proof that must be written to
file_name.

challenge-http-01-clean
Invoked once an identifier ownership has been proven using the
http-01 challenge. This hook is intended to remove the proof
since it is no longer required. The template variables are
strictly identical to those given in the corresponding
challenge-http-01 hook, excepted is_clean_hook which is set to
true.

challenge-tls-alpn-01
Invoked when the ownership of an identifier must be proved us-
ing the tls-alpn-01 challenge. The available template variables
are:
challenge string
The name of the challenge type <tls-alpn-01>. Mostly
used in hooks with multiple types.
env array
Array containing all the environment variables.
identifier string
The identifier name whom ownership is currently being
validated.
identifier_tls_alpn string
The identifier name whom ownership is currently being
validated, in a form suitable for the TLS ALPN chal-
lenge.
is_clean_hook bool
False
proof string
Plain-text representation of the acmeIdentifier exten-
sion that should be used in the self-signed certificate
presented when a TLS connection is initiated with the
ALPN extension value. acmed(8) will not generate the
certificate itself since it can be done using tacd(8).

challenge-tls-alpn-01-clean
Invoked once an identifier ownership has been proven using the
tls-alpn-01 challenge. This hook is intended to remove the
proof since it is no longer required. The template variables
are strictly identical to those given in the corresponding
challenge-tls-alpn-01 hook, excepted is_clean_hook which is set
to true.

file-post-create
Invoked after a non-existent file created. The available tem-
plate variables are the same as those available for the
file-pre-create type.

file-post-edit
Invoked after an existent file modified. The available tem-
plate variables are the same as those available for the
file-pre-create type.

file-pre-create
Invoked before a non-existent file created. The available tem-
plate variables are:
env array
Array containing all the environment variables.
file_directory string
Name of the directory where the impacted file is lo-
cated.
file_name string
Name of the impacted file.
file_path string
Full path to the impacted file.

file-pre-edit
Invoked before an existent file modified. The available tem-
plate variables are the same as those available for the
file-pre-create type.

post-operation
Invoked at the end of the certificate request process. The
available template variables are:
env array
Array containing all the environment variables.
identifiers string
Array containing the identifiers included in the re-
quested certificate.
is_success boolean
True if the certificate request is successful.
key_type string
Name of the asymmetric cryptography algorithm used to
generate the certificate's key pair.
status string
Human-readable status. If the certificate request
failed, it contains the error description.

DEFAULT HOOKS
Because many people have the same needs, ACMEd comes with a set of
hooks that should serve most situations. Hook names being unique, the
following names and any other name starting by those is reserved and
should not be used.

git This hook uses git(1) to archive private keys, public keys and
certificates. It is possible to customize the commit username
and email by using respectively the GIT_USERNAME and GIT_EMAIL
environment variables.

http-01-echo
This hook is designed to solve the http-01 challenge. For this
purpose, it will write the proof into { env.HTTP_ROOT }/{
identifier }/.well-known/acme-challenge/{ file_name }.

The web server must be configured so the file http://{
identifier }/.well-known/acme-challenge/{ file_name } can be
accessed from the CA.

If HTTP_ROOT is not specified, it will be set to /var/www.

tls-alpn-01-tacd-tcp
This hook is designed to solve the tls-alpn-01 challenge using
tacd(8). It requires pkill(1) to support the -F option.

tacd(8) will listen on the host defined by the TACD_HOST envi-
ronment variable (default is the identifier to be validated)
and on the port defined by the TACD_PORT environment variable
(default is 5001).

tacd(8) will store its pid into { TACD_PID_ROOT }/tacd_{
identifier }.pid. If TACD_PID_ROOT is not specified, it will
be set to /run.

tls-alpn-01-tacd-unix
This hook is designed to solve the tls-alpn-01 challenge using
tacd(8). It requires pkill(1) to support the -F option.

tacd(8) will listen on the unix socket { env.TACD_SOCK_ROOT
}/tacd_{ identifier }.sock. If TACD_SOCK_ROOT is not speci-
fied, it will be set to /run.

tacd(8) will store its pid into { TACD_PID_ROOT }/tacd_{
identifier }.pid. If TACD_PID_ROOT is not specified, it will
be set to /run.

TIME PERIODS
ACMEd uses its own time period format, which is vaguely inspired by the
ISO 8601 one. Periods are formatted as PM[PM...] where M is case sensi-
tive character representing a length and P is an integer representing a
multiplayer for the following length. The authorized length are:
- s: second
- m: minute
- h: hour
- d: day
- w: week
The PM couples can be specified multiple times and in any order.

For example, "1d42s" and "40s20h4h2s" both represents a period of one
day and forty-two seconds.

TEMPLATE FORMATTERS
In addition the the formatters provided by default by TinyTemplate,
ACMEd provides the following formatters:

rev_labels
Reverts the labels of a domain name (eg: "mx1.example.org" be-
comes "org.example.mx1" ).

FILES
/var/lib/acmed/accounts
Default accounts private and public keys directory.

/etc/acmed/acmed.toml
Default acmed(8) configuration file.

/var/lib/acmed/certs
Default certificates and associated private keys directory.

EXAMPLES
The following example defines a typical endpoint, account and certifi-
cate for a domain, several subdomains and an IP address.

[[endpoint]]
name = "example name"
url = "https://acme.example.org/directory"
tos_agreed = true

[[account]]
name = "my test account"
contacts = [
{ mailto = "certs@exemple.net" }
]

[[certificate]]
endpoint = "example name"
account = "my test account"
identifiers = [
{ dns = "exemple.net", challenge = "http-01"},
{ dns = "1.exemple.net", challenge = "dns-01"},
{ dns = "2.exemple.net", challenge = "tls-alpn-01", env.TACD_PORT="5010"},
{ dns = "3.exemple.net", challenge = "tls-alpn-01", env.TACD_PORT="5011"},
{ ip = "203.0.113.1", challenge = "http-01"},
]
hooks = ["git", "http-01-echo", "tls-alpn-01-tacd-tcp", "some-dns-01-hook"]
env.HTTP_ROOT = "/srv/http"

It is possible to use echo(1) to solve the http-01 challenge and rm(1)
to clean it. mkdir(1) and chmod(1) are used to prevent issues related
to file access.

[[hook]]
name = "http-01-echo-mkdir"
type = ["challenge-http-01"]
cmd = "mkdir"
args = [
"-m", "0755",
"-p", "{{ if env.HTTP_ROOT }}{ env.HTTP_ROOT }{{ else }}/var/www{{ endif }}/{ identifier }/.well-known/acme-challenge"
]

[[hook]]
name = "http-01-echo-echo"
type = ["challenge-http-01"]
cmd = "echo"
args = ["{ proof }"]
stdout = "{{ if env.HTTP_ROOT }}{ env.HTTP_ROOT }{{ else }}/var/www{{ endif }}/{ identifier }/.well-known/acme-challenge/{ file_name }"

[[hook]]
name = "http-01-echo-chmod"
type = ["challenge-http-01-clean"]
cmd = "chmod"
args = [
"a+r",
"{{ if env.HTTP_ROOT }}{ env.HTTP_ROOT }{{ else }}/var/www{{ endif }}/{ identifier }/.well-known/acme-challenge/{ file_name }"
]

[[hook]]
name = "http-01-echo-clean"
type = ["challenge-http-01-clean"]
cmd = "rm"
args = [
"-f",
"{{ if env.HTTP_ROOT }}{ env.HTTP_ROOT }{{ else }}/var/www{{ endif }}/{ identifier }/.well-known/acme-challenge/{ file_name }"
]

The hooks from the previous example can be grouped in order to reduce
the number of hooks to define in the certificate.

[[group]]
name = "http-01-echo-var-www"
hooks = [
"http-01-echo-mkdir",
"http-01-echo-echo",
"http-01-echo-chmod",
"http-01-echo-clean"
]

[[certificate]]
# Some fields omitted
hooks = ["http-01-echo"]
env.HTTP_ROOT = "/srv/http"

It is also possible to use sendmail(8) in a hook in order to notify
someone when the certificate request process is done.

[[hook]]
name = "email-report"
type = ["post-operation"]
cmd = "sendmail"
args = [
"-f", "noreply.certs@example.net",
"contact@example.net"
]
stdin_str = """Subject: Certificate renewal {{ if is_success }}succeeded{{ else }}failed{{ endif }} for { identifiers.0 }

The following certificate has {{ if not is_success }}*not* {{ endif }}been renewed.
identifiers: {{ for ident in identifiers }}{{ if not @first }}, {{ endif }}{ ident }{{ endfor }}
key type: { key_type }
status: { status }"""

Header And Logo

Peripheral Links

Site Navigation

FreeBSD Manual Pages

Header And Logo

Peripheral Links

Search

Site Navigation

FreeBSD Manual Pages