Acme4ZeroSSL

Contents

Development Purpose

Limitation

Usage

Configuration file

{
 "Telegram_BOTs":{
 "Token": "",
 "ChatID": ""
 },
 "CloudflareAPI":{
 "Token": "",
 "Mail": ""
 },
 "CloudflareRecords":{
 "ZoneID": "",
 "CNAMERecordsID": ["", ""]
 },
 "ZeroSSLAPI":{
 "AccessKey": "",
 "Cache": ""
 },
 "Certificate":{
 "Domains": ["www.example.com", "example.com"],
 "ValidityDays": 90,
 "Country": "",
 "StateOrProvince": "",
 "Locality": "",
 "Organization": "",
 "OrganizationalUnit": "",
 "Config": "",
 "CSR": "",
 "PendingPK": "",
 "PK": "",
 "CA": "",
 "CAB": ""
 },
 "FileChallenge":{
 "HTMLFilePath": ""
 },
 "Cpanel":{
 "ServerUAPI": "",
 "Username": "",
 "Token": ""
 }
}

"CNAMERecordsID": ["XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX","XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"]

"CNAMERecordsID": ["XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"]

"AccessKey": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
"Cache": "/Documents/script/cache.domain.json"

"Domains": ["www.example.com", "example.com"],

"Domains": ["www.example.com"],

"ValidityDays": 90,

"Country": "JP",
"StateOrProvince": "Tokyo Metropolis",
"Locality": "Shimokitazawa",
"Organization": "STARRY",
"OrganizationalUnit": "Kessoku Bando",

"Config": "/Documents/script/domain.csr.conf",
"CSR": "/Documents/script/domain.csr",

"PendingPK": "/Documents/script/cache.domain.key",
"PK": "/var/certificate/private.key",
"CA": "/var/certificate/certificate.crt",
"CAB": "/var/certificate/ca_bundle.crt"

"HTMLFilePath": "/var/www/html"

Cloudflare API

ZeroSSL REST API

Telegram BOTs

2025年05月14日 19:19:00 | Telegram ChatID is empty, notifications will not be sent.

import acme4zerossl
ConfigFile = "/documents/script/acme4zerossl.config.json"
Tg = acme4zerossl.Telegram(ConfigFile)
Tg.GetChatID()

2025年05月14日 19:19:18 | You ChatID is: XXXXXXXXX

Webpage Server Reload or Restart

# Function
Rt.Install(CertificateContent, ServerCommand)
# Default is None
ServerCommand = None
# Apache2, using systemd
ServerCommand = ['systemctl','reload','apache2.service']
# Nginx, using systemd
ServerCommand = ['systemctl','reload','nginx']
# Nginx, using init
ServerCommand = ['/etc/init.d/nginx','reload']

cPanel Install SSL Certificate

import acme4zerossl as acme
ConfigFile = "/Documents/script/acme4zerossl.config.json"
Cp = acme.Cpanel(ConfigFile)
# UAPI token verification
Cp.Verify()
# Certificate upload
Cp.UploadCertificate()
# Private key and upload
Cp.UploadPrivateKey()
# Upload CA bundle and installing
Cp.Install()
# Expires date check
Cp.CertificateCheck()

Schedule

[Unit]
Description=ACME script
# Wait till network available
After=network-online.target
Wants=network-online.target
[Service]
# Run once every call
Type=oneshot
# Root
User=root
# Script folder absolute path
WorkingDirectory=/var/acme
# Python environment (interpreter) and script located
ExecStart=/usr/bin/python3 script_cname.py
# Log output
StandardOutput=journal
StandardError=journal

[Unit]
Description=Run ACME script everyday
[Timer]
OnCalendar=*-*-* 05:00:00
# Avoid skip cause by poweroff 
Persistent=true
# Service name
Unit=acme.service
# Adding randomized delay
RandomizedDelaySec=10m
# Avoid inaccuracy
AccuracySec=1m
[Install]
WantedBy=timers.target

# Enable and start the timer
systemctl enable acme.timer
systemctl start acme.timer
# Reload systemd
systemctl daemon-reload

Import module

# Import as module
import acme4zerossl
# Alternative
import acme4zerossl as acme

Function

Verify Cloudflare API Token

import acme4zerossl as acme
ConfigFile = "/Documents/script/acme4zerossl.config.json"
Cf = acme.Cloudflare(ConfigFile)
Cf.Verify()

Cf.Verify(DisplayVerifyResult=True)

Asking CNAME Records ID hosing on Cloudflare

import acme4zerossl as acme
ConfigFile = "/Documents/script/acme4zerossl.config.json"
Cf = acme.Cloudflare(ConfigFile)
Cf.GetDNSRecords()

FileOutput = "/Documents/script/records.cloudflare.json"
Cf.GetDNSRecords(FileOutput)

Verify with CNAME challenge

# -*- coding: utf-8 -*-
import acme4zerossl as acme
import logging
from time import sleep
from sys import exit
# Config load, dictionary or filepath
ConfigFile = "/Documents/script/acme4zerossl.config.json"
# Server reload or restart command
ServerCommand = None
# Error handling
FORMAT = "%(asctime)s |%(levelname)s |%(message)s"
logging.basicConfig(level=logging.WARNING,filename="acme4zerossl.log",filemode="a",format=FORMAT)
# Script
def main(VerifyRetry,Interval):
 # Load object
 Rt = acme.Runtime(ConfigFile)
 Cf = acme.Cloudflare(ConfigFile)
 Zs = acme.ZeroSSL(ConfigFile)
 # Create certificates signing request
 CSRCreateCheck = Rt.CreateCSR()
 if not isinstance(CSRCreateCheck,list):
 raise RuntimeError("Error occurred during Create CSR and Private key.")
 Rt.Message("Successful create CSR and Private key.")
 # Sending CSR to ZeroSSL
 CertCreate = Zs.Create()
 if not isinstance(CertCreate,dict):
 raise RuntimeError("Error occurred during request new certificate.")
 # Parsing ZeroSSL verify
 VerifyData = Zs.PhrasingVerifyJSON(CertCreate,ValidationMethod="CNAME_CSR_HASH")
 if not isinstance(VerifyData,dict):
 raise RuntimeError("Error occurred during parsing ZeroSSL verify data.")
 # Check pending certificate ID
 CertID = VerifyData.get("id",None)
 if CertID is None:
 raise RuntimeError("Certificate hash is empty.")
 Rt.Message(f"Request success, pending certificate hash: {CertID}")
 # Check CNAME domain and payload
 UpdatePayloads = [VerifyData['common_name']]
 AdditionalDomains = VerifyData.get('additional_domains')
 if AdditionalDomains:
 UpdatePayloads.append(AdditionalDomains)
 # Update CNAME via Cloudflare API
 for UpdatePayload in UpdatePayloads:
 CNAMEUpdateCheck = Cf.UpdateCNAME(UpdatePayload)
 # Check CNAME update result
 if not isinstance(CNAMEUpdateCheck,dict):
 raise RuntimeError("Error occurred during connect to Cloudflare API update CNAME.")
 else:
 Rt.Message("Successful update CNAME from Cloudflare.")
 sleep(5)
 # Wait DNS records update and active
 sleep(60)
 # Verify CNAME challenge
 CertVerifyCheck = Zs.Verification(CertID,ValidationMethod="CNAME_CSR_HASH")
 if not isinstance(CertVerifyCheck,str):
 raise RuntimeError("Error occurred during verification.")
 # Check verify status
 if CertVerifyCheck == "draft":
 raise RuntimeError("Not verified yet.")
 # Verify passed (Under CNAME and file validation, pending_validation means verify successful)
 elif CertVerifyCheck in ("pending_validation","issued"):
 Rt.Message(f"Verify successful, now downloading certificate.")
 sleep(30)
 # Download certificates, adding retry and interval in case backlog certificate issuance
 for _ in range(VerifyRetry):
 CertContent = Zs.Download(CertID)
 # Successful download certificates
 if isinstance(CertContent,dict):
 Rt.Message("Certificate has been downloaded.")
 break
 sleep(Interval)
 else:
 raise RuntimeError(f"Unable download certificate.")
 # Undefined error
 else:
 raise RuntimeError(f"Unable to check verification status, currently verification status: {CertVerifyCheck}")
 # Install certificate to server folder
 InstallCheck = Rt.Install(CertContent,ServerCommand)
 if InstallCheck is False:
 raise RuntimeError("Error occurred during certificate install. You may need to download and install manually.")
 # Get certificate expires date
 CertExpiresDate = CertCreate.get("expires","Unknown")
 if isinstance(InstallCheck,int):
 Rt.Message(f"Certificate been renewed, will expires in {CertExpiresDate}. You may need to restart server manually.")
 return
 elif isinstance(InstallCheck,list):
 Rt.Message(f"Certificate been renewed and installed, will expires in {CertExpiresDate}.")
 return
# Runtime, including check validity date of certificate
if __name__ == "__main__":
 try:
 Rt = acme.Runtime(ConfigFile)
 # Default minimum is 14 days
 CertExpiresDays = Rt.ExpiresCheck()
 # Renew determination
 if CertExpiresDays is None:
 main(5,60)
 logging.info("Certificate has been renewed.")
 exit(0)
 # No need to renew
 else:
 Rt.Message(f"Certificate's validity date has {CertExpiresDays} days left.")
 logging.info(f"Certificate check complete |{CertExpiresDays} days left.")
 exit(0)
 except KeyboardInterrupt:
 logging.warning("Manually interrupt.")
 exit(0)
 except Exception as RenewedError:
 logging.exception(f"Script error |{RenewedError}")
 # Notify
 RenewedErrorMessage = str(RenewedError)
 Rt.Message(RenewedErrorMessage)
 exit(1)

Verify with HTTPS file challenge

# -*- coding: utf-8 -*-
import acme4zerossl as acme
import logging
from time import sleep
from sys import exit
# Config load, dictionary or filepath
ConfigFile = "/Documents/script/acme4zerossl.config.json"
# Server reload or restart command
ServerCommand = None
# Error handling
FORMAT = "%(asctime)s |%(levelname)s |%(message)s"
logging.basicConfig(level=logging.WARNING,filename="acme4zerossl.log",filemode="a",format=FORMAT)
# Script
def main(VerifyRetry,Interval):
 Rt = acme.Runtime(ConfigFile)
 Zs = acme.ZeroSSL(ConfigFile)
 # Create certificates signing request
 CSRCreateCheck = Rt.CreateCSR()
 if not isinstance(CSRCreateCheck,list):
 raise RuntimeError("Error occurred during Create CSR and Private key.")
 Rt.Message("Successful create CSR and Private key.")
 # Sending CSR to ZeroSSL
 CertCreate = Zs.Create()
 if not isinstance(CertCreate,dict):
 raise RuntimeError("Error occurred during request new certificate.")
 # Parsing ZeroSSL verify
 VerifyData = Zs.PhrasingVerifyJSON(CertCreate,ValidationMethod="HTTPS_CSR_HASH")
 if not isinstance(VerifyData,dict):
 raise RuntimeError("Error occurred during parsing ZeroSSL verify data.")
 # Check pending certificate ID
 CertID = VerifyData.get("id",None)
 if CertID is None:
 raise RuntimeError("Certificate hash is empty")
 Rt.Message(f"Request success, pending certificate hash: {CertID}")
 # Validation file path and content
 ValidationFiles = [VerifyData['common_name']]
 AdditionalDomains = VerifyData.get("additional_domains")
 if AdditionalDomains:
 ValidationFiles.append(AdditionalDomains)
 # Create validation file
 for ValidationFile in ValidationFiles:
 CreateValidationFileStatus = Rt.CreateValidationFile(ValidationFile)
 if CreateValidationFileStatus is not True:
 raise RuntimeError("Error occurred during create validation file.")
 # Wait server cache
 sleep(60)
 # Verify file challenge
 CertVerifyCheck = Zs.Verification(CertID,ValidationMethod="HTTPS_CSR_HASH")
 if not isinstance(CertVerifyCheck,str):
 raise RuntimeError("Error occurred during file verification.")
 # Check verify status
 if CertVerifyCheck == "draft":
 raise RuntimeError("Not verified yet.")
 # Verify passed (Under CNAME and file validation, pending_validation means verify successful)
 elif CertVerifyCheck in ("pending_validation","issued"):
 Rt.Message(f"Verify successful, now downloading certificate.")
 sleep(30)
 # Download certificates, adding retry and interval in case backlog certificate issuance
 for _ in range(VerifyRetry):
 CertContent = Zs.Download(CertID)
 # Successful download certificates
 if isinstance(CertContent,dict):
 Rt.Message("Certificate has been downloaded.")
 break
 sleep(Interval)
 else:
 raise RuntimeError(f"Unable download certificate.")
 # Undefined error
 else:
 raise RuntimeError(f"Unable to check verification status, undefined status: {CertVerifyCheck}")
 # Delete validation file
 for ValidationFile in ValidationFiles:
 Rt.DeleteValidationFile(ValidationFile)
 # Install certificate to server folder
 InstallCheck = Rt.Install(CertContent,ServerCommand)
 if InstallCheck is False:
 raise RuntimeError("Error occurred during certificate install. You may need to download and install manually.")
 # Get certificate expires date
 CertExpiresDate = CertCreate.get("expires","Unknown")
 if isinstance(InstallCheck,int):
 Rt.Message(f"Certificate been renewed, will expires in {CertExpiresDate}. You may need to restart server manually.")
 return
 elif isinstance(InstallCheck,list):
 Rt.Message(f"Certificate been renewed and installed, will expires in {CertExpiresDate}.")
 return
# Runtime, including check validity date of certificate
if __name__ == "__main__":
 try:
 Rt = acme.Runtime(ConfigFile)
 # Default minimum is 14 days
 CertExpiresDays = Rt.ExpiresCheck()
 # Renew determination
 if CertExpiresDays is None:
 main(5,60)
 logging.info("Certificate has been renewed.")
 exit(0)
 # No need to renew
 else:
 Rt.Message(f"Certificate's validity date has {CertExpiresDays} days left.")
 logging.info(f"Certificate check complete |{CertExpiresDays} days left.")
 exit(0)
 except KeyboardInterrupt:
 logging.warning("Manually interrupt.")
 exit(0)
 except Exception as RenewedError:
 logging.exception(f"Script error |{RenewedError}")
 # Notify
 RenewedErrorMessage = str(RenewedError)
 Rt.Message(RenewedErrorMessage)
 exit(1)

Download certificate

# -*- coding: utf-8 -*-
import acme4zerossl as acme
from sys import exit
# Config
ConfigFile = "/documents/script/acme4zerossl.config.json"
# Script
def DownloadScript(CertificateID):
 Rt = acme.Runtime(ConfigFile)
 Zs = acme.ZeroSSL(ConfigFile)
 # Download certificate payload
 CertificateContent = Zs.Download(CertificateID or None)
 # Check
 if not isinstance(CertificateContent, dict):
 raise RuntimeError("Unable download certificate")
 # Download certificate and save to folder
 elif isinstance(CertificateContent, dict) and ("certificate.crt") in CertificateContent:
 pass
 ResultCheck = Rt.Install(CertificateContent)
 if ResultCheck is False:
 raise RuntimeError("Error occurred during certificate install")
 elif isinstance(ResultCheck, int):
 Rt.Message("Certificate been downloaded to folder. You may need to restart server manually.")
 elif isinstance(ResultCheck, (list,str)):
 Rt.Message(f"Certificate been downloaded and server has reload or restart.")
# Runtime
try:
 # Input certificate hash manually
 CertificateID = input("Please input certificate ID (hash), or press ENTER using cache file: ")
 DownloadScript(CertificateID)
 exit(0)
except Exception:
 exit(1)

Cancel certificate

# -*- coding: utf-8 -*-
import acme4zerossl as acme
from sys import exit
# Config
ConfigFile = "/documents/script/acme4zerossl.config.json"
# Script
def CancelScript(CertificateID):
 Rt = acme.Runtime(ConfigFile)
 Zs = acme.ZeroSSL(ConfigFile)
 # Cancel certificate
 CancelStatus = Zs.Cancel(CertificateID)
 # Status check, Error
 if not isinstance(CancelStatus,dict):
 raise RuntimeError("Error occurred during cancel certificate")
 # Standard response, check status code
 elif isinstance(CancelStatus,dict):
 CancelResult = CancelStatus.get("success")
 if CancelResult == 1:
 Rt.Message(f"Certificate ID: {CertificateID} has been cancelled.")
 else:
 raise RuntimeError("Unable cancel certificate")
 else:
 raise RuntimeError("Error occurred during cancel certificate")
# Runtime
try:
 # Input certificate hash manually
 CertificateID = input("Please input certificate ID (hash): ")
 CancelScript(CertificateID)
 exit(0)
except Exception as ScriptError:
 print(ScriptError)
 exit(1)

Revoke certificate

# -*- coding: utf-8 -*-
import acme4zerossl as acme
from sys import exit
# Config
ConfigFile = "/documents/script/acme4zerossl.config.json"
# Script
def RevokeScript(CertificateID):
 Rt = acme.Runtime(ConfigFile)
 Zs = acme.ZeroSSL(ConfigFile)
 # Revoke certificate
 RevokeStatus = Zs.Revoke(CertificateID)
 # Status check
 if not isinstance(RevokeStatus,dict):
 raise Exception()
 elif isinstance(RevokeStatus,dict):
 RevokeResult = RevokeStatus.get("success")
 if RevokeResult == 1:
 Rt.Message(f"Certificate ID: {CertificateID} has been revoked.")
 else:
 raise RuntimeError("Unable revoke certificate")
 else:
 raise RuntimeError("Error occurred during revoke certificate")
# Runtime
try:
 # Input certificate hash manually
 CertificateID = input("Please input certificate ID (hash): ")
 RevokeScript(CertificateID)
 exit(0)
except Exception as ScriptError:
 print(ScriptError)
 exit(1)

Self-signed certificate

# Backup IP address, if you really want
self.Address4Backup = ""
self.Address6Backup = None
# CSR config
self.Days = 365
self.Country = "JP"
self.State = "Tokyo Metropolis"
self.Locality = "Toshima"
self.Organization = "Tsukinomori Girl's Academy"
self.Unit = "Concert Band Club"
# Certificate folder path, None as default path
self.CertFolder = None
# Certificate and private key name
self.Certificate = "selfsigned_certificate.crt"
self.PrivateKey = "selfsigned_certificate.key"
# Server command
self.WebServer = None

Dependencies

Python version

Python module

License

Resources

ZeroSSL API

Reference repository