Home/Book/xacme Reference
20 functions · checked against lib/xacme · RFC 8555

xacme Function Reference

Compiled in by build.bat xacme. An ACME (RFC 8555) certificate client: account, order, dns-01 challenge and certificate fetch in one API, with disk storage and renewal checks.

Account & configuration

xrtAcmeAccountConfigInit config

Zero-initialize the account config; assign the CA preset constants XACME_DIRECTORY_LE / LE_STAGING / ZEROSSL / GOOGLE / BUYPASS straight into sDirectoryUrl.

void xrtAcmeAccountConfigInit(xacmeaccountconfig* pConfig);

Issuance flow (5 entry points)

xacmeClientInit / Unit / AccountPem lifecycle

Build the client: parse the directory, register or reuse the account (kid comes from the Location header); AccountPem exports the account key for persistence. Failures set the thread error (domain "xrt.acme.flow").

bool xacmeClientInit(xacmeclient* pClient, struct xnetengine* pBorrowedEngine, cstr sCaPem, cstr sDirectoryUrl, cstr sAccountKeyPem);

xacmeClientIssue issue

One dns-01 issuance: domains may carry wildcards; returns the certificate chain PEM (free with xrtFree). The provider's Add runs before the challenge, Remove best-effort afterwards.

str xacmeClientIssue(xacmeclient* pClient, const xstrview* pDomains, size_t iDomainCount, const struct xacmednsprovider* pDns);

xacmeClientIssueStored one-stop renewal

Composed with the store: at ≥ iRenewalDays remaining, return the existing chain as-is (*pbRenewed=false); otherwise issue, persist (fullchain + CA provenance) and return the new chain.

str xacmeClientIssueStored(xacmeclient* pClient, const xstrview* pDomains, size_t iDomainCount, const struct xacmednsprovider* pDns, cstr sStoreRoot, int iRenewalDays, bool* pbRenewed);

DNS providers

xrtAcmeDnsProviderValidate / Count / Id interface

Provider struct validation and built-in registry enumeration (currently "ali" only); custom vendors plug in by filling the struct (id/Add/Remove/optional Propagate).

xrtAcmeDnsAliConfigInit / xrtAcmeDnsAli / ProviderUnit aliyun

Aliyun alidns provider construction (ACS3-HMAC-SHA256 V3 signing) and teardown; keys go through env/Custom.

bool xrtAcmeDnsAli(const xacmednaliconfig* pConfig, xacmednsprovider* pProvider);

The library carries its own TXT propagation probe (UDP to the authoritative NS) and only notifies the CA once the record is visible.

Storage & renewal

xrtAcmeStoreSaveAccount / LoadAccount account

Persist/reload the account key (PKCS#8 PEM) — pass it to Init for reuse, skipping re-registration.

xrtAcmeStoreSaveCert / LoadCert / LoadCertCa certificates

Store and read the full chain and CA provenance separately, written atomically.

xrtAcmeStoreNeedRenew renewal check

Decide by remaining days whether renewal is due (x509 parsing, no external process).

bool xrtAcmeStoreNeedRenew(cstr sStoreRoot, cstr sDomain, int iRenewalDays, bool* pbNeed);
All 20 symbols (13 public + 5 flow entry points + 2 increments) are imported into scripts and nested TCC; the VFS exposes the flow headers under the xacme/ subtree. Tutorial in chapter 38; hooks into ch. 42 deployment and ch. 47 hot certificate swaps.