<?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;
/**
* Minimal ACMEv2 (RFC 8555) client used to obtain and renew TLS
* certificates for a Yioop site's principal domain and a list of
* subdomains (for example www and mta-sts) on one multi-SAN
* certificate. It speaks the JWS-signed JSON the protocol uses and
* supports the HTTP-01 challenge, which a Yioop WebSite answers with
* a single route, and the ACME Renewal Information (ARI) endpoint so
* a renewal job can let the certificate authority pick the renewal
* window rather than guessing from a fixed age threshold.
*
* The account key signs every request and is the credential for the
* ACME account; it is generated and stored separately from the
* certificate keys. An RSA account key (RS256) is used so request
* signing is a single openssl_sign with no JOSE signature-format
* conversion. This class does its own small HTTP because the
* protocol needs response headers (Replay-Nonce, Location), must not
* follow redirects on those, and must read 4xx bodies (a bad-nonce
* 400 is a retry signal, not a hard error) -- the opposite of what
* the crawler fetcher does.
*
* @author Chris Pollett chris@pollett.org
*/
class AcmeClient
{
/**
* Directory URL of the ACME server (the one document from which
* every other endpoint is discovered).
* @var string
*/
private $directory_url;
/**
* PEM-encoded RSA account private key used to sign requests.
* @var string
*/
private $account_key_pem;
/**
* OpenSSL key resource for the account key, lazily created from
* the PEM.
* @var \OpenSSLAsymmetricKey|null
*/
private $account_key;
/**
* The account URL ("kid") returned by newAccount, sent in the
* protected header of every subsequent request.
* @var string|null
*/
private $account_url;
/**
* Endpoint URLs discovered from the directory document keyed by
* ACME resource name (newNonce, newAccount, newOrder, revokeCert,
* keyChange, and optionally renewalInfo).
* @var array
*/
private $directory;
/**
* Most recent Replay-Nonce. Each signed POST consumes one and
* the response supplies the next, so this is refreshed from
* every response.
* @var string|null
*/
private $nonce;
/**
* Seconds to allow each HTTP request before giving up.
* @var int
*/
private $timeout;
/**
* Public-key directory endpoint name for ARI in the directory
* document. ARI is optional; absent on servers that predate it.
*/
const RENEWAL_INFO = "renewalInfo";
/**
* @param string $directory_url ACME directory URL (use the
* staging directory while developing)
* @param string $account_key_pem PEM of the RSA account private
* key; generate one with generateAccountKey if starting
* fresh
* @param int $timeout per-request timeout in seconds
*/
public function __construct($directory_url, $account_key_pem,
$timeout = 30)
{
$this->directory_url = $directory_url;
$this->account_key_pem = $account_key_pem;
$this->account_key = null;
$this->account_url = null;
$this->directory = [];
$this->nonce = null;
$this->timeout = $timeout;
}
/**
* Generates a fresh RSA account private key and returns it as a
* PEM string. Stored once and reused for the lifetime of the
* ACME account.
*
* @param int $bits RSA modulus size
* @return string PEM-encoded private key
*/
public static function generateAccountKey($bits = 2048)
{
$key = openssl_pkey_new([
"private_key_bits" => $bits,
"private_key_type" => OPENSSL_KEYTYPE_RSA,
]);
$pem = "";
openssl_pkey_export($key, $pem);
return $pem;
}
/**
* URL-safe base64 with padding stripped, as JOSE and ACME use
* everywhere (tokens, JWS segments, thumbprints).
*
* @param string $data raw bytes
* @return string base64url text without '=' padding
*/
public static function base64url($data)
{
return rtrim(strtr(base64_encode($data), "+/", "-_"), "=");
}
/**
* Returns the account key as an OpenSSL key resource, parsing
* the stored PEM on first use.
*
* @return \OpenSSLAsymmetricKey the account private key
*/
private function accountKey()
{
if ($this->account_key === null) {
$this->account_key =
openssl_pkey_get_private($this->account_key_pem);
}
return $this->account_key;
}
/**
* Builds the public JWK for the RSA account key: the modulus and
* exponent as base64url big-endian integers, with members in the
* lexicographic order RFC 7638 requires for a stable thumbprint.
*
* @return array JWK with keys 'e', 'kty', 'n' in that order
*/
public function jwk()
{
$details = openssl_pkey_get_details($this->accountKey());
return [
"e" => self::base64url($details["rsa"]["e"]),
"kty" => "RSA",
"n" => self::base64url($details["rsa"]["n"]),
];
}
/**
* RFC 7638 JWK thumbprint: SHA-256 over the JWK serialized as
* compact JSON with members lexicographically ordered and no
* extra whitespace. Used to form the key authorization a
* challenge proves.
*
* @return string base64url of the SHA-256 thumbprint
*/
public function jwkThumbprint()
{
$jwk = $this->jwk();
$canonical = '{"e":"' . $jwk["e"] . '","kty":"' . $jwk["kty"]
. '","n":"' . $jwk["n"] . '"}';
return self::base64url(hash("sha256", $canonical, true));
}
/**
* Key authorization for a challenge token: the token, a dot, and
* the account key's JWK thumbprint. For HTTP-01 this exact
* string is what the .well-known/acme-challenge/<token> route
* must return.
*
* @param string $token challenge token from the authorization
* @return string the key authorization string
*/
public function keyAuthorization($token)
{
return $token . "." . $this->jwkThumbprint();
}
/**
* Signs a request payload as a JWS in the flattened JSON
* serialization ACME expects. The protected header carries the
* algorithm (RS256), the nonce, the request URL, and either the
* account URL (kid) once registered or the full JWK before
* then. A null payload serializes as the empty string, which
* ACME uses for POST-as-GET reads.
*
* @param string $url request URL, echoed in the protected header
* @param array|null $payload request body, or null for
* POST-as-GET
* @return string JSON-encoded JWS ready to POST
*/
private function signedRequest($url, $payload)
{
$protected = [
"alg" => "RS256",
"nonce" => $this->nonce,
"url" => $url,
];
if ($this->account_url !== null) {
$protected["kid"] = $this->account_url;
} else {
$protected["jwk"] = $this->jwk();
}
$protected64 = self::base64url(json_encode($protected));
/* A null payload is the POST-as-GET empty string. Any other
payload is a JSON object; an empty PHP array must still
encode as the object {} (json_encode would otherwise emit
the array []), so empty arrays are forced to an object. */
if ($payload === null) {
$payload64 = "";
} else {
if (is_array($payload) && empty($payload)) {
$payload = new \stdClass();
}
$payload64 = self::base64url(json_encode($payload));
}
$signing_input = $protected64 . "." . $payload64;
$signature = "";
openssl_sign($signing_input, $signature, $this->accountKey(),
OPENSSL_ALGO_SHA256);
return json_encode([
"protected" => $protected64,
"payload" => $payload64,
"signature" => self::base64url($signature),
]);
}
/**
* Performs one HTTP request and returns status, headers, and
* body. Unlike the crawler fetcher this reads response headers
* (needed for Replay-Nonce and Location), does not follow
* redirects (ACME's Location is data, not a redirect), does not
* fail on 4xx (a bad-nonce 400 is a retry signal), and verifies
* the peer certificate.
*
* @param string $url request URL
* @param string|null $body request body for POST, or null for a
* plain GET
* @param array $extra_headers extra request headers as
* "Name: value" strings
* @return array ['status' => int, 'headers' => array,
* 'body' => string]
*/
private function http($url, $body = null, $extra_headers = [])
{
$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, $url);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_HEADER, true);
curl_setopt($curl, CURLOPT_FOLLOWLOCATION, false);
curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, true);
curl_setopt($curl, CURLOPT_SSL_VERIFYHOST, 2);
curl_setopt($curl, CURLOPT_TIMEOUT, $this->timeout);
curl_setopt($curl, CURLOPT_CONNECTTIMEOUT, $this->timeout);
$headers = $extra_headers;
if ($body !== null) {
curl_setopt($curl, CURLOPT_POST, true);
curl_setopt($curl, CURLOPT_POSTFIELDS, $body);
$headers[] = "Content-Type: application/jose+json";
}
if (!empty($headers)) {
curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);
}
$response = curl_exec($curl);
$status = curl_getinfo($curl, CURLINFO_HTTP_CODE);
$header_size = curl_getinfo($curl, CURLINFO_HEADER_SIZE);
curl_close($curl);
$raw_headers = substr($response, 0, $header_size);
$body_text = substr($response, $header_size);
return [
"status" => $status,
"headers" => $this->parseHeaders($raw_headers),
"body" => $body_text,
];
}
/**
* Parses a raw HTTP response header block into a lowercased-key
* map. Repeated headers keep the last value, which is sufficient
* for the single-valued headers ACME uses (Replay-Nonce,
* Location, Content-Type, Retry-After).
*
* @param string $raw raw header block, possibly including the
* status line and earlier redirect blocks
* @return array map of lowercased header name to value
*/
private function parseHeaders($raw)
{
$headers = [];
$lines = preg_split('/\r\n|\n/', trim($raw));
foreach ($lines as $line) {
$colon = strpos($line, ":");
if ($colon === false) {
continue;
}
$name = strtolower(trim(substr($line, 0, $colon)));
$value = trim(substr($line, $colon + 1));
$headers[$name] = $value;
}
return $headers;
}
/**
* Fetches the directory document and caches the endpoint URLs.
* Also primes the first nonce.
*
* @return void
*/
public function fetchDirectory()
{
$response = $this->http($this->directory_url);
$this->directory = json_decode($response["body"], true) ?? [];
$this->refreshNonce();
}
/**
* Gets a fresh nonce from the newNonce endpoint and stores it.
*
* @return void
*/
public function refreshNonce()
{
$url = $this->directory["newNonce"] ?? null;
if ($url === null) {
return;
}
$response = $this->http($url);
if (isset($response["headers"]["replay-nonce"])) {
$this->nonce = $response["headers"]["replay-nonce"];
}
}
/**
* Sends a signed POST to $url with $payload (null for a
* POST-as-GET read), refreshing the stored nonce from the
* response. On a badNonce error it retries once with a fresh
* nonce, the recovery the protocol prescribes.
*
* @param string $url endpoint URL
* @param array|null $payload request body or null
* @return array the http() result
*/
private function post($url, $payload)
{
$response = $this->http($url, $this->signedRequest($url,
$payload));
if (isset($response["headers"]["replay-nonce"])) {
$this->nonce = $response["headers"]["replay-nonce"];
}
if ($response["status"] === 400 &&
strpos($response["body"], "badNonce") !== false) {
$response = $this->http($url, $this->signedRequest($url,
$payload));
if (isset($response["headers"]["replay-nonce"])) {
$this->nonce = $response["headers"]["replay-nonce"];
}
}
return $response;
}
/**
* Registers (or looks up) the ACME account for the stored key,
* agreeing to the terms of service, and remembers the account
* URL used as the kid on later requests.
*
* @param string $contact_email contact address for the account
* @return bool true if the account URL was obtained
*/
public function registerAccount($contact_email)
{
$url = $this->directory["newAccount"] ?? null;
if ($url === null) {
return false;
}
$payload = [
"termsOfServiceAgreed" => true,
"contact" => ["mailto:" . $contact_email],
];
$response = $this->post($url, $payload);
if (isset($response["headers"]["location"])) {
$this->account_url = $response["headers"]["location"];
return true;
}
return false;
}
/**
* Creates a new order for the given identifiers (the principal
* domain and any subdomains). Returns the decoded order object,
* with its URL added under the 'url' key from the Location
* header so later finalize and poll calls can reference it.
*
* @param array $domains DNS names to include on the certificate
* @return array|null the order, or null on failure
*/
public function newOrder($domains)
{
$url = $this->directory["newOrder"] ?? null;
if ($url === null) {
return null;
}
$identifiers = [];
foreach ($domains as $domain) {
$identifiers[] = ["type" => "dns", "value" => $domain];
}
$response = $this->post($url, ["identifiers" => $identifiers]);
$order = json_decode($response["body"], true);
if (!is_array($order)) {
return null;
}
if (isset($response["headers"]["location"])) {
$order["url"] = $response["headers"]["location"];
}
return $order;
}
/**
* Reads one authorization object (POST-as-GET).
*
* @param string $authz_url authorization URL from the order
* @return array|null decoded authorization, or null
*/
public function authorization($authz_url)
{
$response = $this->post($authz_url, null);
return json_decode($response["body"], true);
}
/**
* Extracts the HTTP-01 challenge from an authorization object.
*
* @param array $authorization decoded authorization
* @return array|null the http-01 challenge, or null if absent
*/
public function httpChallenge($authorization)
{
foreach ($authorization["challenges"] ?? [] as $challenge) {
if (($challenge["type"] ?? "") === "http-01") {
return $challenge;
}
}
return null;
}
/**
* Tells the server a challenge is ready to be validated by
* POSTing the empty object to the challenge URL. The payload
* must encode as the JSON object {}, so a stdClass is used: an
* empty PHP array would encode as the JSON array [], which the
* certificate authority rejects as a malformed request.
*
* @param array $challenge the challenge object
* @return array the http() result
*/
public function notifyChallengeReady($challenge)
{
return $this->post($challenge["url"], new \stdClass());
}
/**
* Polls a URL (order or authorization) until its status leaves
* the pending/processing state or the attempt budget runs out.
*
* @param string $url the resource URL to poll
* @param int $attempts maximum poll attempts
* @param int $delay seconds to wait between attempts
* @return array|null the final decoded resource, or null
*/
public function pollStatus($url, $attempts = 20, $delay = 3)
{
for ($i = 0; $i < $attempts; $i++) {
$response = $this->post($url, null);
$resource = json_decode($response["body"], true);
$status = $resource["status"] ?? "";
if ($status !== "pending" && $status !== "processing") {
return $resource;
}
sleep($delay);
}
return null;
}
/**
* Finalizes an order by submitting the DER-encoded CSR, which
* must cover exactly the order's identifiers.
*
* @param array $order the order (must have a 'finalize' URL)
* @param string $csr_der the CSR in DER form
* @return array decoded order after finalize
*/
public function finalizeOrder($order, $csr_der)
{
$response = $this->post($order["finalize"],
["csr" => self::base64url($csr_der)]);
return json_decode($response["body"], true);
}
/**
* Downloads the issued certificate chain (PEM) once an order is
* valid and carries a certificate URL.
*
* @param array $order the valid order with a 'certificate' URL
* @return string|null PEM certificate chain, or null
*/
public function downloadCertificate($order)
{
if (empty($order["certificate"])) {
return null;
}
$response = $this->post($order["certificate"], null);
return $response["body"];
}
/**
* Queries the ACME Renewal Information endpoint for a
* certificate and returns the suggested renewal window plus any
* Retry-After the server asked for, so a renewal job can renew
* when the certificate authority recommends rather than on a
* fixed age. Returns null if the server has no ARI endpoint or
* gives no window.
*
* @param string $ari_cert_id the ARI certificate identifier
* (base64url of the authority key id and serial, per the
* ARI specification)
* @return array|null ['start' => int, 'end' => int,
* 'retry_after' => int] as unix timestamps/seconds, or null
*/
public function renewalInfo($ari_cert_id)
{
$base = $this->directory[self::RENEWAL_INFO] ?? null;
if ($base === null) {
return null;
}
$response = $this->http($base . "/" . $ari_cert_id);
$info = json_decode($response["body"], true);
if (!isset($info["suggestedWindow"])) {
return null;
}
$retry_after = 0;
if (isset($response["headers"]["retry-after"])) {
$retry_after =
(int)$response["headers"]["retry-after"];
}
return [
"start" => strtotime($info["suggestedWindow"]["start"]),
"end" => strtotime($info["suggestedWindow"]["end"]),
"retry_after" => $retry_after,
];
}
}
(c) 2026 Seekquarry - Open Source Search Engine Software