Skip to content

docs: add Let's Encrypt as recommended SSL provider for evonodes #567

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
ktechmidas wants to merge 1 commit into
base: 23.0.0
Choose a base branch
from
+28 −11
Open

docs: add Let's Encrypt as recommended SSL provider for evonodes #567

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
39 changes: 28 additions & 11 deletions docs/user/masternodes/setup-evonode.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -597,22 +597,38 @@ Prerequisites
- 9999/tcp
- 443/tcp
- 26656/tcp
- 80/tcp (if you are going to use ZeroSSL)
- 80/tcp (required for Let's Encrypt or ZeroSSL certificate validation)
- Backup of any existing Dash Core and dashmate configuration data, including private keys
- `ZeroSSL API access key <https://app.zerossl.com/developer>`_ or SSL certificate for the public
IPv4 address (not DNS name)
- An email address for Let's Encrypt certificate registration, or a `ZeroSSL API access key
<https://app.zerossl.com/developer>`_, or an SSL certificate for the public IPv4 address (not DNS
name)
Comment on lines +602 to +604
Copy link
Contributor

@coderabbitai coderabbitai bot Feb 24, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

"certificate registration" conflicts with the "no account registration" claim in the body.

The prerequisite uses "Let's Encrypt certificate registration," but lines 615–616 explicitly state "no account registration required" and clarify the email is for "certificate expiry notifications." The two phrases are contradictory from a reader's perspective.

✏️ Proposed fix 
-- An email address for Let's Encrypt certificate registration, or a `ZeroSSL API access key
+- An email address for Let's Encrypt certificate expiry notifications, or a `ZeroSSL API access key
🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@docs/user/masternodes/setup-evonode.rst` around lines 602 - 604, The
prerequisite line currently says "Let's Encrypt certificate registration" which
conflicts with the later claim "no account registration required"; change the
prerequisite text to clarify purpose and remove the word "registration" — e.g.
state "an email address for Let's Encrypt certificate expiry notifications, or a
ZeroSSL API access key, or an SSL certificate for the public IPv4 address" so it
matches the later "no account registration required" wording and removes
ambiguity between registration and notification; update the phrase containing
"Let's Encrypt certificate registration" to this clearer wording wherever it
appears.

Copy link
Contributor

@thepastaclaw thepastaclaw Feb 25, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Valid catch. The wording "certificate registration" in the prerequisite conflicts with "no account registration required" in the body. The suggested fix is correct — changing to "certificate expiry notifications" makes the prerequisite consistent with the description below.

@ktechmidas this is a quick one-liner fix if you want to update it.

Copy link
Contributor

@coderabbitai coderabbitai bot Feb 25, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Seems like the humans are having a chat. I'll hop back into my burrow for now. If you need me again, just tag @coderabbitai in a new comment, and I'll come hopping out!


.. _evonode-ssl-cert:

SSL certificates
----------------

There are two ways to get SSL certificates:
An SSL certificate is required for your evonode to communicate securely with the Dash Platform
network. There are three ways to get SSL certificates:

1. Register for the ZeroSSL service and set your API key. Since ZeroSSL provides an API, dashmate
can update your certificates automatically. The free plan only provides 3 free certificates (or 3
renewals of 1 certificate). Other plans require paying with a credit card. You can get an API key
for dashmate by completing the following steps:
1. **Let's Encrypt (recommended)**. Let's Encrypt is a free, automated certificate authority that
provides SSL certificates at no cost and with no account registration required. Dashmate has
built-in support for obtaining and automatically renewing Let's Encrypt certificates. All you need
is an email address for certificate expiry notifications.

During ``dashmate setup``, select **Let's Encrypt** as the SSL provider and enter your email
address when prompted. Dashmate will handle the rest, including automatic renewal before
certificates expire.

.. note::

Let's Encrypt requires port 80/tcp to be open for the ACME HTTP-01 challenge used to validate
your server's IP address during certificate issuance and renewal.

Comment on lines +614 to +627
Copy link
Contributor

@coderabbitai coderabbitai bot Feb 24, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Search for ACME profile, shortlived, or letsEncrypt-related terms in dashmate source
rg -i --type=js -n -C3 "shortlived\|acme.*profile\|letsEncrypt\|lets.encrypt" \
  -g '!node_modules' -g '!dist'

Repository: dashpay/docs

Length of output: 38

🏁 Script executed:

# Also check for certificate-related configurations
rg -i --type=js -n "certificate\|cert\|acme" -g '!node_modules' -g '!dist' | head -100

Repository: dashpay/docs

Length of output: 38

🏁 Script executed:

# Look for dashmate configuration and package info
fd -type f -name "package.json" -o -name "*acme*" -o -name "*certificate*" | head -20

Repository: dashpay/docs

Length of output: 226

🏁 Script executed:

# Search for any dashmate documentation or configuration in this docs repo
rg -i "dashmate" -n -A 5 -B 5 | head -150

Repository: dashpay/docs

Length of output: 11283

🏁 Script executed:

# Look for any setup or configuration files mentioning ACME
rg -i "acme\|shortlived" -n

Repository: dashpay/docs

Length of output: 38

🌐 Web query:

Let's Encrypt IP address certificate validity period shortlived profile ACME

💡 Result:

  • Validity period (Let’s Encrypt “shortlived” profile): 160 hours (just over 6 days). [1]
  • IP address certificates: Must be issued under the shortlived ACME profile (i.e., they’re also 160-hour certs). [2]
  • How to request (ACME): Your ACME client must support ACME Profiles and you must explicitly select/request the shortlived profile; otherwise you’ll get the default (classic) profile behavior. [1][3]
  • Challenges allowed for IP identifiers: HTTP-01 or TLS-ALPN-01 only (not DNS-01). [2]
  • Availability: Let’s Encrypt states short-lived and IP address certificates are generally available as of January 15, 2026. [1]

Sources:
[1] Let’s Encrypt — “6-day and IP Address Certificates are Generally Available” (Jan 15, 2026)
[2] Let’s Encrypt — “We’ve Issued Our First IP Address Certificate” (Jul 1, 2025)
[3] Let’s Encrypt docs — “Profiles”

Clarify the certificate validity period and renewal requirements for Let's Encrypt IP-address certificates.

The documentation at lines 614-627 describes automatic certificate renewal without disclosing that Let's Encrypt IP-address certificates are valid for only ~160 hours (approximately 6 days), compared to the standard 90-day validity for domain-name certificates. These short-lived certificates require the ACME client to explicitly request the shortlived ACME profile during issuance and renewal.

Since the snippet confirms these are IP-address certificates (mentioning "your server's IP address" validation), users need to understand that continuous automated renewal is not optional—it's operationally critical. This is a significant operational difference from standard Let's Encrypt usage that should be clearly disclosed to node operators.

Please confirm whether dashmate's bundled ACME client supports and requests the shortlived ACME profile. If it does, add a note explaining the 6-day validity window and the need for continuous renewal. If not yet implemented, document the current limitations.

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@docs/user/masternodes/setup-evonode.rst` around lines 614 - 627, Update the
Let's Encrypt section describing IP-address certificates to explicitly state
that ACME-issued IP certificates use the shortlived profile and are valid for
roughly 160 hours (~6 days), so automated continuous renewal is operationally
required; while editing the text that references "dashmate setup" and the ACME
HTTP-01 challenge, add a note indicating the short-lived validity and renewal
necessity and then verify whether Dashmate's bundled ACME client requests the
`shortlived` profile—if it does, state that Dashmate handles short-lived renewal
automatically, otherwise document the current limitation and recommend users
ensure an ACME client or external process requests the `shortlived` profile and
performs renewals at least every 5 days.

Copy link
Contributor

@thepastaclaw thepastaclaw Feb 25, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good research on the short-lived certificate validity. I checked dashmate's implementation and can confirm:

Dashmate already handles this correctly. In obtainLetsEncryptCertificateTaskFactory.js, the lego ACME client is invoked with --profile shortlived specifically for IP address certificates. Dashmate also has automatic renewal scheduling via scheduleRenewLetsEncryptCertificateFactory.js with a 2-day expiration threshold (EXPIRATION_LIMIT_DAYS = 2).

That said, adding a brief note about the ~6-day validity for IP-address certificates would be helpful for node operators who want to understand why renewal happens so frequently. Something like:

Note: Let's Encrypt IP-address certificates use the short-lived profile and are valid for approximately 6 days. Dashmate handles renewal automatically — no manual intervention is required.

This is informational rather than a blocker — the current text ("Dashmate will handle the rest, including automatic renewal") is technically accurate.

2. **ZeroSSL**. ZeroSSL provides an API that allows dashmate to obtain and update your certificates
automatically. The free plan provides 3 free certificates (or 3 renewals of 1 certificate). Other
plans require paying with a credit card. You can get an API key for dashmate by completing the
following steps:

- Register on `https://zerossl.com/ <https://zerossl.com/>`_. *We recommend not using your
personal email address.*
Expand All @@ -624,14 +640,15 @@ There are two ways to get SSL certificates:

ZeroSSL Developer tab showing the API key

2. Obtain SSL certificates for your IP address using any available provider and upload the
certificate files to your server. `SSL Dragon <https://www.ssldragon.com/>`_ and `SuperbitHost
3. **Manual certificate upload**. Obtain SSL certificates for your IP address using any available
provider and upload the certificate files to your server. `SSL Dragon
<https://www.ssldragon.com/>`_ and `SuperbitHost
<https://www.superbithost.com/ssl-certificates/>`_ are two options that accept cryptocurrency.

Please make sure that the certificate chain file contains your server certificate at the top and
intermediate/root certificates if present. If a bundle file is present, you need to concatenate it
with the certificate file::

cat certificate.crt bundle.crt > bundle.crt
Comment on lines 648 to 652
Copy link
Contributor

@coderabbitai coderabbitai bot Feb 24, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

Pre-existing data-corruption bug in the cat concatenation command.

cat certificate.crt bundle.crt > bundle.crt

The shell opens bundle.crt for writing (truncating it to zero bytes) before cat reads it. The result is that bundle.crt ends up containing only the contents of certificate.crt — the original bundle data is silently discarded. Users following this step will upload an incomplete certificate chain without realising it.

Although this line was not introduced by this PR, it falls within the restructured option-3 section that was touched here, making this a good moment to fix it.

🐛 Proposed fix 
-   cat certificate.crt bundle.crt > bundle.crt
+   cat certificate.crt bundle.crt > chain.crt

Then reference chain.crt as the certificate chain file in the upload step. Alternatively, use a temporary file and rename:

-   cat certificate.crt bundle.crt > bundle.crt
+   cat certificate.crt bundle.crt > bundle.crt.tmp && mv bundle.crt.tmp bundle.crt
🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@docs/user/masternodes/setup-evonode.rst` around lines 648 - 652, The current
concat command overwrites bundle.crt before reading it; replace the line that
reads "cat certificate.crt bundle.crt > bundle.crt" by writing the combined
output to a new file (e.g., "chain.crt") or to a temporary file and then
renaming it, and update the subsequent upload instruction to reference the new
certificate chain filename (reference symbols: certificate.crt, bundle.crt,
chain.crt and the upload step that currently points to bundle.crt).

Copy link
Contributor

@thepastaclaw thepastaclaw Feb 25, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Valid bug — cat certificate.crt bundle.crt > bundle.crt will indeed truncate bundle.crt before cat reads it, silently discarding the bundle data.

However, this is a pre-existing issue not introduced by this PR (the line existed before in the original option 2 section). While it's worth fixing, it should ideally be addressed in a separate commit or PR to keep the scope clean.

The suggested fix of writing to a temp file and renaming is the safest approach:

cat certificate.crt bundle.crt > bundle.crt.tmp && mv bundle.crt.tmp bundle.crt

Copy link
Contributor

@coderabbitai coderabbitai bot Feb 25, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@thepastaclaw Agreed — keeping the scope of this PR focused on the Let's Encrypt additions makes sense, and addressing pre-existing issues separately is good practice.

Would you like me to open a GitHub issue to track this bug as a follow-up? I can document the problem and the recommended fix (bundle.crt.tmp + mv) so it doesn't get lost.


Verify the validity of the private key and certificate chain by running these commands::
Expand Down