<?php
/**
* SeekQuarry/Yioop --
* Open Source Pure PHP Search Engine, Crawler, and Indexer
*
* Copyright (C) 2009 - 2026 Chris Pollett chris@pollett.org
*
* LICENSE:
*
* This program is free software: you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation, either version 3 of the License, or
* (at your option) any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program. If not, see
* <https://www.gnu.org/licenses/>.
*
* END LICENSE
*
* @author Chris Pollett chris@pollett.org
* @license https://www.gnu.org/licenses/ GPL3
* @link https://www.seekquarry.com/
* @copyright 2009 - 2026
* @filesource
*/
namespace seekquarry\yioop\library;
use seekquarry\yioop\configs as C;
/**
* Orchestrates obtaining a TLS certificate over ACME for a list of
* domains, sequencing the pieces that each handle one concern:
* AcmeClient speaks the protocol, AcmeKeyStore holds the account
* key, AcmeChallengeStore publishes HTTP-01 tokens for the port-80
* route to serve, CsrBuilder makes the multi-SAN request, and
* CertInstaller writes the result and reloads the running server.
*
* The single entry point obtainCertificate runs the whole flow:
* load or create the account key, fetch the directory, register the
* account, open an order for the domains, answer each domain's
* HTTP-01 challenge by publishing its key authorization and telling
* the certificate authority to validate, wait for the order to be
* ready, finalize it with a freshly generated key and CSR, download
* the issued chain, and install it. Each published token is removed
* once the order leaves the pending state, whether issuance
* succeeded or failed, so stale tokens are not left served.
*
* It does not decide WHEN to renew; that is the renewal job's role,
* which uses ariCertId (computed here from an installed certificate)
* to ask the certificate authority for a renewal window.
*
* @author Chris Pollett chris@pollett.org
*/
class AcmeManager
{
/**
* ACME directory URL (the staging directory while testing, the
* production directory once trusted certificates are wanted).
* @var string
*/
private $directory_url;
/**
* Contact email registered with the ACME account.
* @var string
*/
private $contact_email;
/**
* Account key store.
* @var AcmeKeyStore
*/
private $key_store;
/**
* HTTP-01 challenge token store the port-80 route reads.
* @var AcmeChallengeStore
*/
private $challenge_store;
/**
* Certificate installer.
* @var CertInstaller
*/
private $cert_installer;
/**
* Running WebSite to reload after install, or null when
* issuance runs separately from the server.
* @var object|null
*/
private $web_site;
/**
* Published challenge tokens awaiting cleanup after an order
* leaves the pending state.
* @var array
*/
private $published_tokens = [];
/**
* @param string $directory_url ACME directory URL
* @param string $contact_email contact address for the account
* @param AcmeKeyStore $key_store account key store, or null for
* the default location
* @param AcmeChallengeStore $challenge_store challenge token
* store, or null for the default location
* @param CertInstaller $cert_installer installer, or null for
* the default certificate paths
* @param object $web_site running WebSite to reload, or null
*/
public function __construct($directory_url, $contact_email,
$key_store = null, $challenge_store = null,
$cert_installer = null, $web_site = null)
{
$this->directory_url = $directory_url;
$this->contact_email = $contact_email;
$this->key_store = ($key_store === null)
? new AcmeKeyStore() : $key_store;
$this->challenge_store = ($challenge_store === null)
? new AcmeChallengeStore() : $challenge_store;
$this->cert_installer = ($cert_installer === null)
? new CertInstaller() : $cert_installer;
$this->web_site = $web_site;
}
/**
* Obtains and installs a certificate covering $domains. Returns
* true when a certificate was issued and installed, false at the
* first step that fails. Logs progress and the failing step so a
* run can be followed in the server log.
*
* @param array $domains DNS names for the certificate; the first
* is the principal domain
* @return bool true on a fully successful issue and install
*/
public function obtainCertificate($domains)
{
if (empty($domains)) {
crawlLog("AcmeManager: no domains given; nothing to do.");
return false;
}
$account_key = $this->key_store->accountKey();
if ($account_key === null) {
crawlLog("AcmeManager: could not load or create the " .
"account key.");
return false;
}
$client = $this->makeClient($account_key);
$client->fetchDirectory();
if (!$client->registerAccount($this->contact_email)) {
crawlLog("AcmeManager: account registration failed.");
return false;
}
$order = $client->newOrder($domains);
if ($order === null || empty($order["authorizations"])) {
crawlLog("AcmeManager: could not create an order for " .
implode(", ", $domains) . ".");
return false;
}
$published = $this->publishChallenges($client, $order);
if ($published === null) {
$this->clearTokens();
return false;
}
$ready = $client->pollStatus($order["url"]);
$authorized = $ready !== null &&
($ready["status"] ?? "") === "ready";
$this->clearTokens();
if (!$authorized) {
$this->logAuthorizationFailures($client, $order);
crawlLog("AcmeManager: authorizations did not all " .
"validate; order not ready.");
return false;
}
return $this->finalizeAndInstall($client, $order, $domains);
}
/**
* Creates the protocol client for an issuance run. Isolated so
* the client construction has one home and so a test can supply
* a stand-in client without reaching the network.
*
* @param string $account_key the account key PEM
* @return AcmeClient the protocol client
*/
protected function makeClient($account_key)
{
return new AcmeClient($this->directory_url, $account_key);
}
/**
* For each authorization in the order, finds the HTTP-01
* challenge, publishes its key authorization to the challenge
* store, and tells the certificate authority it is ready.
* Returns the published token list, or null if any authorization
* lacked an HTTP-01 challenge.
*
* @param AcmeClient $client the protocol client
* @param array $order the order with authorization URLs
* @return array|null published tokens, or null on a missing
* challenge
*/
private function publishChallenges($client, $order)
{
$tokens = [];
foreach ($order["authorizations"] as $authz_url) {
$authorization = $client->authorization($authz_url);
$domain = $authorization["identifier"]["value"] ?? "?";
$challenge = $client->httpChallenge($authorization);
if ($challenge === null ||
empty($challenge["token"])) {
crawlLog("AcmeManager: authorization for " . $domain .
" had no http-01 challenge.");
return null;
}
$token = $challenge["token"];
$key_authorization = $client->keyAuthorization($token);
if (!$this->challenge_store->put($token,
$key_authorization)) {
crawlLog("AcmeManager: could not publish challenge " .
"token for " . $domain . ".");
return null;
}
$tokens[] = $token;
crawlLog("AcmeManager: published challenge for " .
$domain . " (token " . $token . "); the certificate " .
"authority will fetch /.well-known/acme-challenge/" .
$token . " over port 80.");
$notify = $client->notifyChallengeReady($challenge);
$notify_status = $notify["status"] ?? 0;
if ($notify_status < 200 || $notify_status >= 300) {
crawlLog("AcmeManager: the ready signal for " .
$domain . " was rejected by the certificate " .
"authority (HTTP " . $notify_status . "): " .
trim((string)($notify["body"] ?? "")) . " -- the " .
"authority will not validate this domain.");
}
}
$this->published_tokens = $tokens;
return $tokens;
}
/**
* Removes every published challenge token from the store.
*
* @return void
*/
private function clearTokens()
{
foreach ($this->published_tokens as $token) {
$this->challenge_store->clear($token);
}
$this->published_tokens = [];
}
/**
* Re-fetches each authorization after the order failed to reach
* ready and logs its status together with any error the
* certificate authority recorded against the http-01 challenge.
* This turns a generic "not ready" into a per-domain reason --
* for example a still-pending authorization (the authority never
* fetched the token) versus an invalid one (the authority
* fetched and rejected the response, with a connection or dns
* detail). Best-effort: a failure to fetch a status is itself
* logged and skipped.
*
* @param AcmeClient $client the protocol client
* @param array $order the order whose authorizations to inspect
* @return void
*/
private function logAuthorizationFailures($client, $order)
{
foreach ($order["authorizations"] as $authz_url) {
$authorization = $client->authorization($authz_url);
if (!is_array($authorization)) {
crawlLog("AcmeManager: could not read an " .
"authorization status from " . $authz_url . ".");
continue;
}
$domain = $authorization["identifier"]["value"] ?? "?";
$status = $authorization["status"] ?? "?";
$detail = "";
foreach ($authorization["challenges"] ?? [] as $one) {
if (($one["type"] ?? "") === "http-01" &&
!empty($one["error"])) {
$error = $one["error"];
$detail = " (" . ($error["type"] ?? "") . ": " .
($error["detail"] ?? "") . ")";
}
}
crawlLog("AcmeManager: authorization for " . $domain .
" is " . $status . $detail . ".");
}
}
/**
* Generates a key and CSR for the domains, finalizes the order,
* waits for issuance, downloads the chain, and installs it.
*
* @param AcmeClient $client the protocol client
* @param array $order the ready order
* @param array $domains the certificate domains
* @return bool true on a successful finalize, download, and
* install
*/
private function finalizeAndInstall($client, $order, $domains)
{
$csr = CsrBuilder::build($domains);
if ($csr === null) {
crawlLog("AcmeManager: could not build the CSR.");
return false;
}
$client->finalizeOrder($order, $csr["csr_der"]);
$issued = $client->pollStatus($order["url"]);
if ($issued === null ||
($issued["status"] ?? "") !== "valid") {
crawlLog("AcmeManager: order did not reach valid after " .
"finalize.");
return false;
}
if (isset($order["url"])) {
$issued["url"] = $order["url"];
}
$chain = $client->downloadCertificate($issued);
if ($chain === null || $chain === "") {
crawlLog("AcmeManager: certificate download returned " .
"nothing.");
return false;
}
if (!$this->cert_installer->install($chain, $csr["key_pem"],
$this->web_site)) {
crawlLog("AcmeManager: certificate install failed.");
return false;
}
crawlLog("AcmeManager: installed a certificate for " .
implode(", ", $domains) . ".");
return true;
}
/**
* Computes the ARI certificate identifier for an installed
* certificate so the renewal job can ask the certificate
* authority when to renew. A thin pass-through to CsrBuilder
* kept here so callers have one ACME entry point.
*
* @param string $cert_pem the installed certificate in PEM form
* @return string|null the ARI cert id, or null
*/
public function ariCertId($cert_pem)
{
return CsrBuilder::ariCertId($cert_pem);
}
/**
* Asks the certificate authority's ACME Renewal Information
* endpoint when an installed certificate should be renewed,
* returning the suggested window together with any Retry-After
* the authority asked the caller to wait before querying again.
* Lets the renewal job renew when the authority recommends
* rather than at a fixed age, and back off between polls as the
* authority asks. Returns null when the certificate identifier
* cannot be computed, the account key is unavailable, or the
* authority publishes no renewal information.
*
* @param string $cert_pem the installed certificate in PEM form
* @return array|null ['start' => int, 'end' => int,
* 'retry_after' => int] as unix timestamps and seconds, or
* null when no window is available
*/
public function renewalWindow($cert_pem)
{
$ari_cert_id = $this->ariCertId($cert_pem);
if ($ari_cert_id === null) {
return null;
}
$account_key = $this->key_store->accountKey();
if ($account_key === null) {
return null;
}
$client = $this->makeClient($account_key);
$client->fetchDirectory();
return $client->renewalInfo($ari_cert_id);
}
}
(c) 2026 Seekquarry - Open Source Search Engine Software