You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

840 lines
25 KiB

5 years ago
2 years ago
  1. .\" Copyright (c) 2019-2020 Rodolphe Bréard <rodolphe@breard.tf>
  2. .\"
  3. .\" Copying and distribution of this file, with or without modification,
  4. .\" are permitted in any medium without royalty provided the copyright
  5. .\" notice and this notice are preserved. This file is offered as-is,
  6. .\" without any warranty.
  7. .Dd Dec 19, 2022
  8. .Dt ACMED.TOML 5
  9. .Os
  10. .Sh NAME
  11. .Nm acmed.toml
  12. .Nd ACMEd configuration file
  13. .Sh DESCRIPTION
  14. .Nm
  15. is the configuration file for
  16. .Xr acmed 8 .
  17. It is written in the
  18. .Em TOML
  19. format. The allowed elements are described below.
  20. .Bl -tag
  21. .It Ic account
  22. Array of table representing an account on one or several endpoint.
  23. .Bl -tag
  24. .It Ic contacts Ar array
  25. 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:
  26. .Bl -tag
  27. .It Ic mailto Ar string
  28. A mailto URI as defined by
  29. .Em RFC 6068 .
  30. This URI cannot contains neither
  31. .Dq hfields
  32. nor more than one
  33. .Dq addr-spec
  34. in the
  35. .Dq to
  36. component.
  37. .El
  38. .It Ic env Ar table
  39. Table of environment variables that will be accessible from hooks.
  40. .It Ic external_account Ar table
  41. Table containing the information required to bind the account to an external one. Possible fields and values are:
  42. .Bl -tag
  43. .It Ic identifier Ar string
  44. ASCII string identifying the key.
  45. .It Ic key Ar string
  46. Private key encoded in base64url without padding.
  47. .It Ic signature_algorithm Ar string
  48. Name of the signature algorithm used to sign the external account binding message sent to the endpoint as defined in
  49. .Em RFC 7518 .
  50. Possible values are:
  51. .Bl -dash -compact
  52. .It
  53. HS256
  54. .Aq default
  55. .It
  56. HS384
  57. .It
  58. HS512
  59. .El
  60. .El
  61. .It Ic hooks Ar array
  62. 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.
  63. .It Cm key_type Ar string
  64. Name of the asymmetric cryptography algorithm used to generate the key pair. Possible values are:
  65. .Bl -dash -compact
  66. .It
  67. ed25519
  68. .It
  69. ed448
  70. .It
  71. ecdsa_p256
  72. .Aq default
  73. .It
  74. ecdsa_p384
  75. .It
  76. ecdsa_p521
  77. .It
  78. rsa2048
  79. .It
  80. rsa4096
  81. .El
  82. .It Ic name Ar string
  83. The name the account is registered under. Must be unique.
  84. .It Cm signature_algorithm Ar string
  85. Name of the signature algorithm used to sign the messages sent to the endpoint as defined in
  86. .Em RFC 7518 .
  87. The default value is derived from the key type. Possible values are:
  88. .Bl -dash -compact
  89. .It
  90. ES256
  91. .It
  92. ES384
  93. .It
  94. ES512
  95. .It
  96. RS256
  97. .El
  98. .El
  99. .It Ic certificate
  100. Array of table representing a certificate that will be requested to a CA.
  101. .Pp
  102. 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.
  103. .Bl -tag
  104. .It Ic account Ar string
  105. Name of the account to use.
  106. .It Ic csr_digest Ar string
  107. Name of the certificate's signing request digest algorithm. Possible values are:
  108. .Bl -dash -compact
  109. .It
  110. sha256
  111. .Aq default
  112. .It
  113. sha384
  114. .It
  115. sha512
  116. .El
  117. .It Ic directory Ar string
  118. Path to the directory where certificates and their associated private keys are stored.
  119. .It Ic endpoint Ar string
  120. Name of the endpoint to use.
  121. .It Ic env Ar table
  122. Table of environment variables that will be accessible from hooks.
  123. .It Ic file_name_format Ar string
  124. Template used to build the file's name. The template syntax is
  125. .Em TinyTemplate .
  126. See the
  127. .Sx STANDARDS
  128. section for a link to the
  129. .Em TinyTemplate
  130. specifications. If not specified, the value defined in the
  131. .Em endpoint
  132. element, and then the
  133. .Em global
  134. element, is used. Default is
  135. .Dq { name }_{ key_type }.{ file_type }.{ ext } .
  136. Possible variables are:
  137. .Bl -tag
  138. .It Ic ext Ar string
  139. File extension. Currently, only
  140. .Dq pem
  141. is supported.
  142. .It Ic file_type Ar string
  143. Contains
  144. .Dq pk
  145. for the private key file and
  146. .Dq crt
  147. for the certificate file.
  148. .It Ic key_type Ar string
  149. The certificate's private key type.
  150. .It Ic name Ar string
  151. The certificate's name.
  152. .El
  153. .It Ic hooks Ar array
  154. Names of hooks that will be called when requesting a new certificate. The hooks are guaranteed to be called sequentially in the declaration order.
  155. .It Ic identifiers Ar array
  156. Array of tables listing the identifiers that should be included in the certificate along with the challenge to use for each one. The
  157. .Em dns
  158. and
  159. .Em ip
  160. fields are mutually exclusive.
  161. .Bl -tag
  162. .It Ic challenge Ar string
  163. The name of the challenge to use to prove the identifier's ownership. Possible values are:
  164. .Bl -dash -compact
  165. .It
  166. dns-01
  167. .It
  168. http-01
  169. .It
  170. tls-alpn-01
  171. .El
  172. .It Ic dns Ar string
  173. The domain name.
  174. .It Ic env Ar table
  175. Table of environment variables that will be accessible from hooks.
  176. .It Ic ip Ar string
  177. The IP address.
  178. .El
  179. .It Ic key_type Ar string
  180. Name of the asymmetric cryptography algorithm used to generate the certificate's key pair. Possible values are:
  181. .Bl -dash -compact
  182. .It
  183. ed25519
  184. .It
  185. ed448
  186. .It
  187. ecdsa_p256
  188. .It
  189. ecdsa_p384
  190. .It
  191. ecdsa_p521
  192. .It
  193. rsa2048
  194. .Aq default
  195. .It
  196. rsa4096
  197. .El
  198. .It Ic kp_reuse Ar boolean
  199. Set whether or not the private key should be reused when renewing the certificate. Default is false.
  200. .It Ic name
  201. 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
  202. .Sq * ,
  203. .So
  204. :
  205. .Sc
  206. and
  207. .Sq /
  208. characters will be replaced by an underscore. Default is the first identifier.
  209. .It Cm renew_delay Ar string
  210. Period of time between the certificate renewal and its expiration date. The format is described in the
  211. .Sx TIME PERIODS
  212. section. Default is the value defined in the associated endpoint.
  213. .It Ic subject_attributes Ar table
  214. Table where the certificate's subject attributes are specified. Possible keys, with their RFC 4519 and X.500 equivalents, are:
  215. .Bl -column -offset indent ".Sy organizational_unit_name" ".Sy generationQualifier" ".Sy organizationalUnitName"
  216. .It Sy ACMEd key Ta Sy RFC 4519 Ta Sy X.500
  217. .It Li country_name Ta c Ta countryName
  218. .It Li generation_qualifier Ta generationQualifier Ta
  219. .It Li given_name Ta givenName Ta
  220. .It Li initials Ta initials Ta
  221. .It Li locality_name Ta l Ta localityName
  222. .It Li name Ta name Ta
  223. .It Li organization_name Ta o Ta organizationName
  224. .It Li organizational_unit_name Ta ou Ta organizationalUnitName
  225. .It Li pkcs9_email_address Ta Ta
  226. .It Li postal_address Ta postalAddress Ta
  227. .It Li postal_code Ta postalCode Ta
  228. .It Li state_or_province_name Ta st Ta stateOrProvinceName
  229. .It Li street Ta street Ta streetAddress
  230. .It Li surname Ta sn Ta surname
  231. .It Li title Ta title Ta
  232. .El
  233. .El
  234. .It Ic endpoint
  235. Array of table where each element defines a Certificate Authority
  236. .Pq CA
  237. which may be used to request certificates.
  238. .Bl -tag
  239. .It Cm file_name_format Ar string
  240. Template used to build the file's name. For detailed documentation, see the
  241. .Em file_name_format
  242. directive located in the
  243. .Em certificate
  244. element.
  245. .It Cm name Ar string
  246. The name the endpoint is registered under. Must be unique.
  247. .It Cm rate_limits Ar array
  248. Array containing the names of the HTTPS rate limits to apply.
  249. .It Cm renew_delay Ar string
  250. Period of time between the certificate renewal and its expiration date. The format is described in the
  251. .Sx TIME PERIODS
  252. section. Default is the value defined in the global section.
  253. .It Cm root_certificates Ar array
  254. Array containing the path to root certificates that should be added to the trust store.
  255. .It Cm tos_agreed Ar boolean
  256. Set whether or not the user agrees to the Terms Of Service
  257. .Pq TOS .
  258. .It Cm url Ar string
  259. The endpoint's directory URL.
  260. .El
  261. .It Ic global
  262. Table containing the global configuration options.
  263. .Bl -tag
  264. .It Cm accounts_directory Ar string
  265. Specify the directory where the accounts private and public keys are stored.
  266. .It Cm cert_file_group Ar group_name|group_id Ft string
  267. Specify the group who will own newly-created certificates files. See
  268. .Xr chown 2
  269. for more details.
  270. .It Cm cert_file_mode Ar integer
  271. Specify the permissions to use for newly-created certificates files. See
  272. .Xr chmod 2
  273. for more details.
  274. .It Cm cert_file_user Ar username|user_id Ft string
  275. Specify the user who will own newly-created certificates files. See
  276. .Xr chown 2
  277. for more details.
  278. .It Cm certificates_directory Ar string
  279. Specify the directory where the certificates and their associated private keys are stored.
  280. .It Ic env Ar table
  281. Table of environment variables that will be accessible from hooks.
  282. .It Ic file_name_format Ar string
  283. Template used to build the file's name. For detailed documentation, see the
  284. .Em file_name_format
  285. directive located in the
  286. .Em certificate
  287. element.
  288. .It Cm pk_file_group Ar group_name|group_id Ft string
  289. Specify the group who will own newly-created private-key files. See
  290. .Xr chown 2
  291. for more details.
  292. .It Cm pk_file_mode Ar integer
  293. Specify the permissions to use for newly-created private-key files. See
  294. .Xr chmod 2
  295. for more details.
  296. .It Cm pk_file_user Ar username|user_id Ft string
  297. Specify the user who will own newly-created private-key files. See
  298. .Xr chown 2
  299. for more details.
  300. .It Cm renew_delay Ar string
  301. Period of time between the certificate renewal and its expiration date. The format is described in the
  302. .Sx TIME PERIODS
  303. section. Default is 3w.
  304. .It Cm root_certificates Ar array
  305. Array containing the path to root certificates that should be added to the trust store.
  306. .El
  307. .It Ic group
  308. Array of table allowing to group several hooks as one. A group is considered as new hook.
  309. .Bl -tag
  310. .It Cm hooks Ar array
  311. Array containing the names of the hooks that are grouped. The hooks are guaranteed to be called sequentially in the declaration order.
  312. .It Cm name Ar string
  313. The name the group is registered under. This name is considered as a hook name. Must be unique.
  314. .El
  315. .It Ic hook
  316. Array of table where each element defines a command that will be launched at a defined point. See section
  317. .Sx WRITING A HOOK
  318. for more details.
  319. .Bl -tag
  320. .It Cm allow_failure Ar boolean
  321. 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.
  322. .It Ic args Ar array
  323. Array of strings representing the command's arguments.
  324. .It Ic cmd Ar string
  325. The name of the command that will be launched.
  326. .It Cm name Ar string
  327. The name the hook is registered under. Must be unique.
  328. .It Ic stderr Ar string
  329. Path to the file where the command's standard error output if written.
  330. .It Ic stdin Ar string
  331. Path to the file that will be written into the command's standard intput. Mutually exclusive with
  332. .Em stdin_str .
  333. .It Ic stdin_str Ar string
  334. String that will be written into the command's standard input. Mutually exclusive with
  335. .Em stdin .
  336. .It Ic stdout Ar string
  337. Path to the file where the command's standard output if written.
  338. .It Cm type Ar array
  339. Array of strings. Possible types are:
  340. .Bl -dash -compact
  341. .It
  342. challenge-dns-01
  343. .It
  344. challenge-dns-01-clean
  345. .It
  346. challenge-http-01
  347. .It
  348. challenge-http-01-clean
  349. .It
  350. challenge-tls-alpn-01
  351. .It
  352. challenge-tls-alpn-01-clean
  353. .It
  354. file-post-create
  355. .It
  356. file-post-edit
  357. .It
  358. file-pre-create
  359. .It
  360. file-pre-edit
  361. .It
  362. post-operation
  363. .El
  364. .El
  365. .It Ic include
  366. 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.
  367. .Pp
  368. In case or overlapping global option definition, the one of the last included file will be used. For example, if a file
  369. .Em A
  370. includes files
  371. .Em B
  372. and
  373. .Em C
  374. and all three defines the same global option, the final value will be the one defined in file
  375. .Em C .
  376. .Pp
  377. Unix style globing is supported.
  378. .It Ic rate-limit
  379. Array of table where each element defines a HTTPS rate limit.
  380. .Bl -tag
  381. .It Cm name Ar string
  382. The name the rate limit is registered under. Must be unique.
  383. .It Cm number Ar integer
  384. Number of requests authorized withing the time period.
  385. .It Cm period Ar string
  386. Period of time during which a maximal number of requests is authorized. The format is described in the
  387. .Sx TIME PERIODS
  388. section.
  389. .El
  390. .El
  391. .Sh WRITING A HOOK
  392. 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.
  393. .Pp
  394. In order to allow full automation of the three above steps without imposing arbitrary restrictions or methods,
  395. .Xr acmed 8
  396. 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.
  397. .Pp
  398. 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.
  399. .Pp
  400. 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.
  401. .Pp
  402. When writing a hook, the values of
  403. .Em args ,
  404. .Em stdin ,
  405. .Em stdin_str ,
  406. .Em stdout
  407. and
  408. .Em stderr
  409. are considered as template strings whereas
  410. .Em cmd
  411. is not. The template syntax is
  412. .Em TinyTemplate .
  413. See the
  414. .Sx STANDARDS
  415. section for a link to the
  416. .Em TinyTemplate
  417. specifications.
  418. .Pp
  419. The available types and the associated template variable are described below.
  420. .Bl -tag
  421. .It Ic challenge-dns-01
  422. Invoked when the ownership of an identifier must be proved using the
  423. .Em dns-01
  424. challenge. The available template variables are:
  425. .Bl -tag -compact
  426. .It Cm challenge Ar string
  427. The name of the challenge type
  428. .Aq dns-01 .
  429. Mostly used in hooks with multiple types.
  430. .It Cm env Ar array
  431. Array containing all the environment variables.
  432. .It Cm identifier Ar string
  433. The identifier name whom ownership is currently being validated.
  434. .It Cm is_clean_hook Ar bool
  435. False
  436. .It Cm proof Ar string
  437. The content of the proof that must be written to a
  438. .Ql TXT
  439. entry of the DNS zone for the
  440. .Ql _acme-challenge
  441. subdomain.
  442. .El
  443. .It Ic challenge-dns-01-clean
  444. Invoked once an identifier ownership has been proven using the
  445. .Em dns-01
  446. 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
  447. .Em challenge-dns-01
  448. hook, excepted
  449. .Em is_clean_hook
  450. which is set to
  451. .Em true .
  452. .It Ic challenge-http-01
  453. Invoked when the ownership of an identifier must be proved using the
  454. .Em http-01
  455. challenge. The available template variables are:
  456. .Bl -tag -compact
  457. .It Cm challenge Ar string
  458. The name of the challenge type
  459. .Aq http-01 .
  460. Mostly used in hooks with multiple types.
  461. .It Cm env Ar array
  462. Array containing all the environment variables.
  463. .It Cm file_name Ar string
  464. Name of the file containing the proof. This is not a full path and does not include the
  465. .Ql .well-known/acme-challenge/
  466. prefix.
  467. .It Cm identifier Ar string
  468. The identifier name whom ownership is currently being validated.
  469. .It Cm is_clean_hook Ar bool
  470. False
  471. .It Cm proof Ar string
  472. The content of the proof that must be written to
  473. .Em file_name .
  474. .El
  475. .It Ic challenge-http-01-clean
  476. Invoked once an identifier ownership has been proven using the
  477. .Em http-01
  478. 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
  479. .Em challenge-http-01
  480. hook, excepted
  481. .Em is_clean_hook
  482. which is set to
  483. .Em true .
  484. .It Ic challenge-tls-alpn-01
  485. Invoked when the ownership of an identifier must be proved using the
  486. .Em tls-alpn-01
  487. challenge. The available template variables are:
  488. .Bl -tag -compact
  489. .It Cm challenge Ar string
  490. The name of the challenge type
  491. .Aq tls-alpn-01 .
  492. Mostly used in hooks with multiple types.
  493. .It Cm env Ar array
  494. Array containing all the environment variables.
  495. .It Cm identifier Ar string
  496. The identifier name whom ownership is currently being validated.
  497. .It Cm identifier_tls_alpn Ar string
  498. The identifier name whom ownership is currently being validated, in a form suitable for the TLS ALPN challenge.
  499. .It Cm is_clean_hook Ar bool
  500. False
  501. .It Cm proof Ar string
  502. Plain-text representation of the
  503. .Em acmeIdentifier
  504. extension that should be used in the self-signed certificate presented when a TLS connection is initiated with the
  505. .Qd acme-tls/1
  506. ALPN extension value.
  507. .Xr acmed 8
  508. will not generate the certificate itself since it can be done using
  509. .Xr tacd 8 .
  510. .El
  511. .It Ic challenge-tls-alpn-01-clean
  512. Invoked once an identifier ownership has been proven using the
  513. .Em tls-alpn-01
  514. 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
  515. .Em challenge-tls-alpn-01
  516. hook, excepted
  517. .Em is_clean_hook
  518. which is set to
  519. .Em true .
  520. .It Ic file-post-create
  521. Invoked
  522. .Em after
  523. a non-existent file
  524. .Em created .
  525. The available template variables are the same as those available for the
  526. .Em file-pre-create
  527. type.
  528. .It Ic file-post-edit
  529. Invoked
  530. .Em after
  531. an existent file
  532. .Em modified .
  533. The available template variables are the same as those available for the
  534. .Em file-pre-create
  535. type.
  536. .It Ic file-pre-create
  537. Invoked
  538. .Em before
  539. a non-existent file
  540. .Em created .
  541. The available template variables are:
  542. .Bl -tag -compact
  543. .It Cm env Ar array
  544. Array containing all the environment variables.
  545. .It Cm file_directory Ar string
  546. Name of the directory where the impacted file is located.
  547. .It Cm file_name Ar string
  548. Name of the impacted file.
  549. .It Cm file_path Ar string
  550. Full path to the impacted file.
  551. .El
  552. .It Ic file-pre-edit
  553. Invoked
  554. .Em before
  555. an existent file
  556. .Em modified .
  557. The available template variables are the same as those available for the
  558. .Em file-pre-create
  559. type.
  560. .It Ic post-operation
  561. Invoked at the end of the certificate request process. The available template variables are:
  562. .Bl -tag -compact
  563. .It Cm env Ar array
  564. Array containing all the environment variables.
  565. .It Cm identifiers Ar string
  566. Array containing the identifiers included in the requested certificate.
  567. .It Cm is_success Ar boolean
  568. True if the certificate request is successful.
  569. .It Cm key_type Ar string
  570. Name of the asymmetric cryptography algorithm used to generate the certificate's key pair.
  571. .It Cm status Ar string
  572. Human-readable status. If the certificate request failed, it contains the error description.
  573. .El
  574. .El
  575. .Sh DEFAULT HOOKS
  576. 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.
  577. .Bl -tag
  578. .It Pa git
  579. This hook uses
  580. .Xr git 1
  581. to archive private keys, public keys and certificates. It is possible to customize the commit username and email by using respectively the
  582. .Ev GIT_USERNAME
  583. and
  584. .Ev GIT_EMAIL
  585. environment variables.
  586. .It Pa http-01-echo
  587. This hook is designed to solve the http-01 challenge. For this purpose, it will write the proof into
  588. .Pa { env.HTTP_ROOT }/{ identifier }/.well-known/acme-challenge/{ file_name } .
  589. .Pp
  590. The web server must be configured so the file
  591. .Pa http://{ identifier }/.well-known/acme-challenge/{ file_name }
  592. can be accessed from the CA.
  593. .Pp
  594. If
  595. .Ev HTTP_ROOT
  596. is not specified, it will be set to
  597. .Pa /var/www .
  598. .It Pa tls-alpn-01-tacd-tcp
  599. This hook is designed to solve the tls-alpn-01 challenge using
  600. .Xr tacd 8 .
  601. It requires
  602. .Xr pkill 1
  603. to support the
  604. .Em -F
  605. option.
  606. .Pp
  607. .Xr tacd 8
  608. will listen on the host defined by the
  609. .Ev TACD_HOST
  610. environment variable (default is the identifier to be validated) and on the port defined by the
  611. .Ev TACD_PORT
  612. environment variable (default is 5001).
  613. .Pp
  614. .Xr tacd 8
  615. will store its pid into
  616. .Pa { TACD_PID_ROOT }/tacd_{ identifier }.pid .
  617. If
  618. .Ev TACD_PID_ROOT
  619. is not specified, it will be set to
  620. .Pa /run .
  621. .It Pa tls-alpn-01-tacd-unix
  622. This hook is designed to solve the tls-alpn-01 challenge using
  623. .Xr tacd 8 .
  624. It requires
  625. .Xr pkill 1
  626. to support the
  627. .Em -F
  628. option.
  629. .Pp
  630. .Xr tacd 8
  631. will listen on the unix socket
  632. .Pa { env.TACD_SOCK_ROOT }/tacd_{ identifier }.sock .
  633. If
  634. .Ev TACD_SOCK_ROOT
  635. is not specified, it will be set to
  636. .Pa /run .
  637. .Pp
  638. .Xr tacd 8
  639. will store its pid into
  640. .Pa { TACD_PID_ROOT }/tacd_{ identifier }.pid .
  641. If
  642. .Ev TACD_PID_ROOT
  643. is not specified, it will be set to
  644. .Pa /run .
  645. .El
  646. .Sh TIME PERIODS
  647. ACMEd uses its own time period format, which is vaguely inspired by the ISO 8601 one. Periods are formatted as
  648. .Ar PM[PM...]
  649. where
  650. .Ar M
  651. is case sensitive character representing a length and
  652. .Ar P
  653. is an integer representing a multiplayer for the following length. The authorized length are:
  654. .Bl -dash -compact
  655. .It
  656. .Ar s :
  657. second
  658. .It
  659. .Ar m :
  660. minute
  661. .It
  662. .Ar h :
  663. hour
  664. .It
  665. .Ar d :
  666. day
  667. .It
  668. .Ar w :
  669. week
  670. .El
  671. The
  672. .Ar PM
  673. couples can be specified multiple times and in any order.
  674. .Pp
  675. For example,
  676. .Dq 1d42s
  677. and
  678. .Dq 40s20h4h2s
  679. both represents a period of one day and forty-two seconds.
  680. .Sh TEMPLATE FORMATTERS
  681. In addition the the formatters provided by default by TinyTemplate, ACMEd provides the following formatters:
  682. .Bl -tag
  683. .It Pa rev_labels
  684. Reverts the labels of a domain name (eg:
  685. .Dq mx1.example.org
  686. becomes
  687. .Dq org.example.mx1
  688. ).
  689. .El
  690. .Sh FILES
  691. .Bl -tag
  692. .It Pa /var/lib/acmed/accounts
  693. Default accounts private and public keys directory.
  694. .It Pa /etc/acmed/acmed.toml
  695. Default
  696. .Xr acmed 8
  697. configuration file.
  698. .It Pa /var/lib/acmed/certs
  699. Default certificates and associated private keys directory.
  700. .El
  701. .Sh EXAMPLES
  702. The following example defines a typical endpoint, account and certificate for a domain, several subdomains and an IP address.
  703. .Bd -literal -offset indent
  704. [[endpoint]]
  705. name = "example name"
  706. url = "https://acme.example.org/directory"
  707. tos_agreed = true
  708. [[account]]
  709. name = "my test account"
  710. contacts = [
  711. { mailto = "certs@exemple.net" }
  712. ]
  713. [[certificate]]
  714. endpoint = "example name"
  715. account = "my test account"
  716. identifiers = [
  717. { dns = "exemple.net", challenge = "http-01"},
  718. { dns = "1.exemple.net", challenge = "dns-01"},
  719. { dns = "2.exemple.net", challenge = "tls-alpn-01", env.TACD_PORT="5010"},
  720. { dns = "3.exemple.net", challenge = "tls-alpn-01", env.TACD_PORT="5011"},
  721. { ip = "203.0.113.1", challenge = "http-01"},
  722. ]
  723. hooks = ["git", "http-01-echo", "tls-alpn-01-tacd-tcp", "some-dns-01-hook"]
  724. env.HTTP_ROOT = "/srv/http"
  725. .Ed
  726. .Pp
  727. It is possible to use
  728. .Xr echo 1
  729. to solve the
  730. .Em http-01
  731. challenge and
  732. .Xr rm 1
  733. to clean it.
  734. .Xr mkdir 1
  735. and
  736. .Xr chmod 1
  737. are used to prevent issues related to file access.
  738. .Bd -literal -offset indent
  739. [[hook]]
  740. name = "http-01-echo-mkdir"
  741. type = ["challenge-http-01"]
  742. cmd = "mkdir"
  743. args = [
  744. "-m", "0755",
  745. "-p", "{{ if env.HTTP_ROOT }}{ env.HTTP_ROOT }{{ else }}/var/www{{ endif }}/{ identifier }/.well-known/acme-challenge"
  746. ]
  747. [[hook]]
  748. name = "http-01-echo-echo"
  749. type = ["challenge-http-01"]
  750. cmd = "echo"
  751. args = ["{ proof }"]
  752. stdout = "{{ if env.HTTP_ROOT }}{ env.HTTP_ROOT }{{ else }}/var/www{{ endif }}/{ identifier }/.well-known/acme-challenge/{ file_name }"
  753. [[hook]]
  754. name = "http-01-echo-chmod"
  755. type = ["challenge-http-01-clean"]
  756. cmd = "chmod"
  757. args = [
  758. "a+r",
  759. "{{ if env.HTTP_ROOT }}{ env.HTTP_ROOT }{{ else }}/var/www{{ endif }}/{ identifier }/.well-known/acme-challenge/{ file_name }"
  760. ]
  761. [[hook]]
  762. name = "http-01-echo-clean"
  763. type = ["challenge-http-01-clean"]
  764. cmd = "rm"
  765. args = [
  766. "-f",
  767. "{{ if env.HTTP_ROOT }}{ env.HTTP_ROOT }{{ else }}/var/www{{ endif }}/{ identifier }/.well-known/acme-challenge/{ file_name }"
  768. ]
  769. .Ed
  770. .Pp
  771. The hooks from the previous example can be grouped in order to reduce the number of hooks to define in the certificate.
  772. .Bd -literal -offset indent
  773. [[group]]
  774. name = "http-01-echo-var-www"
  775. hooks = [
  776. "http-01-echo-mkdir",
  777. "http-01-echo-echo",
  778. "http-01-echo-chmod",
  779. "http-01-echo-clean"
  780. ]
  781. [[certificate]]
  782. # Some fields omitted
  783. hooks = ["http-01-echo"]
  784. env.HTTP_ROOT = "/srv/http"
  785. .Ed
  786. .Pp
  787. It is also possible to use
  788. .Xr sendmail 8
  789. in a hook in order to notify someone when the certificate request process is done.
  790. .Bd -literal -offset indent
  791. [[hook]]
  792. name = "email-report"
  793. type = ["post-operation"]
  794. cmd = "sendmail"
  795. args = [
  796. "-f", "noreply.certs@example.net",
  797. "contact@example.net"
  798. ]
  799. stdin_str = """Subject: Certificate renewal {{ if is_success }}succeeded{{ else }}failed{{ endif }} for { identifiers.0 }
  800. The following certificate has {{ if not is_success }}*not* {{ endif }}been renewed.
  801. identifiers: {{ for ident in identifiers }}{{ if not @first }}, {{ endif }}{ ident }{{ endfor }}
  802. key type: { key_type }
  803. status: { status }"""
  804. .Ed
  805. .Sh SEE ALSO
  806. .Xr acmed 8 ,
  807. .Xr tacd 8
  808. .Sh STANDARDS
  809. .Bl -hyphen
  810. .It
  811. .Rs
  812. .%A Tom Preston-Werner
  813. .%D July 2018
  814. .%T TOML v0.5.0
  815. .%U https://toml.io/en/v0.5.0
  816. .Re
  817. .It
  818. .Rs
  819. .%A Brook Heisler
  820. .%T TinyTemplate
  821. .%U https://docs.rs/tinytemplate/latest/tinytemplate/syntax/index.html
  822. .Re
  823. .It
  824. .Rs
  825. .%A M. Jones
  826. .%D May 2015
  827. .%R RFC 7518
  828. .%T JSON Web Algorithms (JWA)
  829. .Re
  830. .El
  831. .Sh AUTHORS
  832. .An Rodolphe Bréard
  833. .Aq rodolphe@breard.tf