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 endpoint. 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 can- not 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 ac- count 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 end- point 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 gen- erate 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 messages 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 requested to a CA. Note that, by default, certificates are identified by the first identifier in the list of identifiers. That means that if you re- order 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 algorithm. Possible values are: - sha256 <default> - sha384 - sha512 directory string Path to the directory where certificates and their associ- ated 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 supported. 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 sequen- tially in the declaration order. identifiers array Array of tables listing the identifiers that should be in- cluded 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 iden- tifier'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 acces- sible from hooks. ip string The IP address. key_type string Name of the asymmetric cryptography algorithm used to gen- erate 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 associated file's name. The `*', `:' and `/' characters will be re- placed by an underscore. Default is the first identifier. renew_delay string Period of time between the certificate renewal and its ex- piration date. The format is described in the "TIME PERIODS" section. Default is the value defined in the asso- ciated endpoint. subject_attributes table Table where the certificate's subject attributes are speci- fied. Possible keys, with their RFC 4519 and X.500 equiva- lents, 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 Authority (CA) which may be used to request certificates. file_name_format string Template used to build the file's name. For detailed docu- mentation, see the file_name_format directive located 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 ap- ply. renew_delay string Period of time between the certificate renewal and its ex- piration 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 Service (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 certificates files. See chown(2) for more details. cert_file_mode integer Specify the permissions to use for newly-created certifi- cates files. See chmod(2) for more details. cert_file_user username|user_id string Specify the user who will own newly-created certificates files. See chown(2) for more details. certificates_directory string Specify the directory where the certificates and their as- sociated 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 docu- mentation, see the file_name_format directive located 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 private- 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 ex- piration 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 sequentially in the declaration order. name string The name the group is registered under. This name is con- sidered 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 allowed or not. If not allowed, a failure in this hook will fail the whole certificate request process. Default 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 command's standard intput. Mutually exclusive with stdin_str. stdin_str string String that will be written into the command's standard in- put. 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 rela- tive 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 includes files B and C and all three defines the same global option, the fi- nal 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 requests 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 implemented, 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 imposing arbitrary restrictions or methods, acmed(8) uses hooks. Fundamentally, 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 renewed 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 cur- rent 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 template syntax is TinyTemplate. See the "STANDARDS" section for a link to the TinyTemplate specifications. The available types and the associated template variable are described be- low. challenge-dns-01 Invoked when the ownership of an identifier must be proved using 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 vali- dated. 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 iden- tical 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 using 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 vali- dated. 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 iden- tical 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 using 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 vali- dated. identifier_tls_alpn string The identifier name whom ownership is currently being vali- dated, in a form suitable for the TLS ALPN challenge. is_clean_hook bool False proof string Plain-text representation of the acmeIdentifier extension that should be used in the self-signed certificate pre- sented when a TLS connection is initiated with the ALPN ex- tension 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 template variables are the same as those available for the file-pre-create type. file-post-edit Invoked after an existent file modified. The available template 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 template variables are: env array Array containing all the environment variables. file_directory string Name of the directory where the impacted file is located. 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 template 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 avail- able template variables are: env array Array containing all the environment variables. identifiers string Array containing the identifiers included in the requested certificate. is_success boolean True if the certificate request is successful. key_type string Name of the asymmetric cryptography algorithm used to gen- erate 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 cer- tificates. It is possible to customize the commit username and email by using respectively the GIT_USERNAME and GIT_EMAIL environ- ment variables. http-01-echo This hook is designed to solve the http-01 challenge. For this pur- pose, 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 environ- ment 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 specified, 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 sensitive character representing a length and P is an integer representing a multi- player 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" becomes "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 certificate 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 }""" SEE ALSO acmed(8), tacd(8) STANDARDS - Tom Preston-Werner, TOML v0.5.0, https://toml.io/en/v0.5.0, July 2018. - Brook Heisler, TinyTemplate, https://docs.rs/tinytemplate/lat- est/tinytemplate/syntax/index.html. - M. Jones, JSON Web Algorithms (JWA), RFC 7518, May 2015. AUTHORS Rodolphe BrA(C)ard <rodolphe@breard.tf> FreeBSD ports 15.quarterly Dec 19, 2022 ACMED.TOML(5)
NAME | DESCRIPTION | WRITING A HOOK | DEFAULT HOOKS | TIME PERIODS | TEMPLATE FORMATTERS | FILES | EXAMPLES | SEE ALSO | STANDARDS | AUTHORS
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=acmed.toml&sektion=5&manpath=FreeBSD+Ports+15.1.quarterly>