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.

824 lines
25 KiB

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