AHdark Blog

SSL certificates, as something that has been in use in the market for over a decade, are unlikely to be unknown to anyone involved in web-related technologies.

Common SSL certificates used by individual webmasters in China are basically Let's Encrypt, TrustAsia, CloudFlare SSL, etc., all of which provide free DV SSL domain certificates. The main application scenario discussed in this article is the automated certificate issuance based on the ACME protocol and its implementation, acme.sh.

About SSL#

If you don't even know what SSL is in the web world, you might as well be reborn...

SSL: something that makes you spend money while feeling extreme joy, even though the money you spend is usually of little use.

Secure Sockets Layer, or SSL, translates to 安全套接层 in Chinese. What we currently use, referred to as SSL encryption, is not the original SSL but rather the newer and more secure TLS (Transport Layer Security, 传输层安全性协议) encryption.

This is a security protocol aimed at providing security and data integrity for internet communications. Netscape introduced the first version of its web browser, Netscape Navigator, in 1994, along with the HTTPS protocol, which uses SSL for encryption; this is the origin of SSL.

The IETF standardized SSL and published the TLS 1.0 standard document in 1999 (RFC 2246). Subsequently, TLS 1.1 (RFC 4346, 2006), TLS 1.2 (RFC 5246, 2008), and TLS 1.3 (RFC 8446, 2018) were published.

SSL includes a Record Layer and a Transport Layer, with the Record Layer protocol determining the encapsulation format of the Transport Layer data. The transport layer security protocol uses X.509 authentication, followed by asymmetric encryption calculations for identity authentication of the communicating parties, and then exchanges symmetric keys as session keys.
This session key is used to encrypt the data exchanged between the two communicating parties, ensuring the confidentiality and reliability of communication between client and server applications, preventing eavesdropping by attackers.

In web applications, we often use TLS in conjunction with the HTTP protocol (they are loosely coupled), that is, HTTP Over TLS.

ACME Protocol#

The Automatic Certificate Management Environment (ACME) is a communication protocol for automated interaction between certificate authorities and their users' web servers, allowing for low-cost automated deployment of public key infrastructure.

This protocol was designed by the Internet Security Research Group (ISRG) for the Let's Encrypt service.

Yes, it's the magical non-profit organization that first offered free SSL.

acme.sh#

Repo: acmesh-official/acme.sh

acme.sh is an implementation of the ACME protocol using bash, which can generate certificates by calling the ACME Endpoint.

Installation#

We will not provide tutorials for the Windows environment.

# Install dependencies (Debian, Ubuntu)
apt install curl socat

# Call the script to install
curl https://get.acme.sh  sh -s email=my@example.com

# Add alias command
alias acme.sh=~/.acme.sh/acme.sh

For a more advanced and detailed installation process, please refer to: https://github.com/acmesh-official/acme.sh/wiki/How-to-install

CA Selection#

The acme.sh wiki provides a list of available CAs:

From https://github.com/acmesh-official/acme.sh/wiki/CA

Note regarding GTS certificates

To apply for a GTS certificate, you need to obtain the corresponding token from Google Cloud. Please refer to: Automate Public Certificates Lifecycle Management via RFC 8555 (ACME) & Google Public CA

You can specify the CA using --server <acme_endpoint>, for example:

acme.sh --issue \
        -d example.com \
        --server https://acme.hi.cn/directory

Issuing Certificates#

File Verification#

# File verification to issue a certificate
acme.sh --issue \
        -d example.com \
        -d www.example.com \
        --webroot /data/wwwroot/example.com/

# e.q.
acme.sh --issue \
        -d ssl-test.ah-dark.tech \
        -d ssl-test2.ah-dark.tech \
        --webroot /data/wwwroot/ssl-test.ah-dark.tech/

# Using built-in HTTP server
acme.sh --issue \
        -d example.com \
        --standalone

• Use --issue to specify that the operation to be executed is to issue a certificate.
• Use -d <domain> to specify the domain names to include; multiple domain names can be included here, and an error will be prompted if unsupported domain names are included.
• Use --webroot <path> to specify the root path of the web server; you can also choose not to use this option and instead use --standalone to let acme.sh create an HTTP server listening on port 80.

After specifying --webroot, the script will access <path>/.well-known/ to create verification files; please ensure that the user permissions and web server permissions are configured correctly.

You can then find your certificate files and other information in the following locations (of course, you can also use automatic certificate installation later):

• ~/.acme.sh/<domain>/fullchain.cer Full chain certificate public key (use this for deployment)
• ~/.acme.sh/<domain>/<domain>.csr Single domain public key
• ~/.acme.sh/<domain>/ca.cer CA certificate public key
• ~/.acme.sh/<domain>/<domain>.key Certificate private key (use this for deployment)

DNS Verification#

First, acme.sh will request pki to obtain the corresponding TXT record that needs to be added for the domain name:

acme.sh --issue --dns \
        -d example.com \
        --yes-I-know-dns-manual-mode-enough-go-ahead-please

# e.q.
acme.sh --issue --dns \
        -d ssl-test.ah-dark.tech \
        --yes-I-know-dns-manual-mode-enough-go-ahead-please

First step operation feedback

Then, you need to wait for the TXT record to be added and resolved before proceeding to the next step:

# Note that this is renew
acme.sh --renew \
        -d example.com \
        --yes-I-know-dns-manual-mode-enough-go-ahead-please

# e.q.
acme.sh --renew \
        -d ssl-test.ah-dark.tech \
        --yes-I-know-dns-manual-mode-enough-go-ahead-please

Second step operation feedback

You can then find your certificate files and other information in the following locations (of course, you can also use automatic certificate installation later):

• ~/.acme.sh/<domain>/fullchain.cer Full chain certificate public key (use this for deployment)
• ~/.acme.sh/<domain>/<domain>.csr Single domain public key
• ~/.acme.sh/<domain>/ca.cer CA certificate public key
• ~/.acme.sh/<domain>/<domain>.key Certificate private key (use this for deployment)

It is important to note that the real power of the DNS method lies in the ability to automatically add TXT records for verification using the API provided by the domain name resolver.

Currently, acme.sh supports automatic integration with dozens of resolvers, including Cloudflare, DNSPod, CloudXNS, GoDaddy, and OVH. For specifics, please refer to https://github.com/acmesh-official/acme.sh/blob/master/dnsapi/README.md

Installing Certificates#

After generating the certificate, you need to copy the certificate to the actual location where it will be used.

The certificates generated by default are placed in the installation directory: ~/.acme.sh/. Please do not directly use the files in this directory, for example: do not directly let Nginx/Apache configuration files use the files below. The files here are for internal use, and the directory structure may change.

The correct method is to use the --install-cert command and specify the target location, after which the certificate files will be copied to the corresponding location.

Nginx#

acme.sh --install-cert -d ssl-test.ah-dark.tech \
        --key-file       /path/to/keyfile/in/nginx/key.pem  \
        --fullchain-file /path/to/fullchain/nginx/cert.pem \
        --reloadcmd     "service nginx force-reload"

# e.q.
acme.sh --install-cert -d ssl-test.ah-dark.tech \
        --key-file       /usr/local/nginx/conf/ssl/ssl-test.ah-dark.tech.key  \
        --fullchain-file /usr/local/nginx/conf/ssl/ssl-test.ah-dark.tech.pem \
        --reloadcmd     "service nginx force-reload"

Here, service nginx force-reload is used instead of service nginx reload. Tests have shown that reload does not reload the certificate, so force-reload is used.

Nginx's configuration ssl_certificate should use /etc/nginx/ssl/fullchain.cer, not /etc/nginx/ssl/<domain>.cer, otherwise the test from SSL Labs will report Chain issues Incomplete errors.

The --install-cert command can carry many parameters to specify target files. You can also specify --reloadcmd, which is the command executed after the certificate is updated.

For detailed parameters, please refer to: https://github.com/Neilpang/acme.sh#3-install-the-issued-cert-to-apachenginx-etc

It is worth noting that all parameters specified here will be automatically recorded and called again after the certificate is automatically updated in the future.

Apache#

acme.sh --install-cert -d example.com \
        --cert-file      /path/to/certfile/in/apache/cert.pem  \
        --key-file       /path/to/keyfile/in/apache/key.pem  \
        --fullchain-file /path/to/fullchain/certfile/apache/fullchain.pem \
        --reloadcmd     "service apache2 force-reload"

Querying Certificate Information#

For issued certificates, you can query their information using the following command:

acme.sh --info -d example.com

# e.q.
acme.sh --info -d ssl-test.ah-dark.tech

Automation#

The acme.sh installed using the above installation method will automatically add crontab entries.

You can also add it yourself:

15 0 * * * "/root/.acme.sh"/acme.sh --cron --home "/root/.acme.sh" > /dev/null

IP Certificates#

Currently, the only CA that acme.sh supports for IP SSL ACME issuance is HiCA.

Please note that IP SSL can only be issued using PTR reverse query records and file verification. I am not sure if acme.sh supports PTR verification, so it is recommended to use file verification.