--- url: 'https://docs.smoxy.eu/ssl-and-certificates/how-ssl-works.md' --- # How SSL Works in smoxy SSL/TLS certificates are essential for securing traffic between your visitors and smoxy, as well as between smoxy and your origin servers. smoxy provides a fully integrated certificate lifecycle - from automatic generation via Let's Encrypt to manual certificate uploads. This guide explains how SSL works in smoxy, the different certificate types available, and how smoxy manages certificates on your behalf. *** ### SSL Certificate Types smoxy supports two types of SSL certificates: | Type | Generated by | Renewed by | Best for | | ------------------------------ | ----------------------- | ----------------- | ------------------------------------------------------------ | | **Auto-managed (Recommended)** | smoxy via Let's Encrypt | smoxy (automatic) | Most users - zero maintenance | | **Self-managed** | You | You (manual) | Enterprise certs, EV certificates, specific compliance needs | #### Auto-managed Certificates (Recommended) When you add a domain to smoxy, a **wildcard SSL certificate** is automatically created. This certificate covers: * `yourdomain.com` * `*.yourdomain.com` (all subdomains) The certificate is issued via **Let's Encrypt** using DNS-based validation (ACME protocol). smoxy handles the entire lifecycle: 1. Certificate request 2. DNS challenge verification 3. Certificate issuance 4. Automatic renewal (timed by the CA's recommended renewal window) #### Self-managed Certificates If you need to use your own certificate (e.g., Extended Validation, organization-specific requirements), you can upload it manually. **Requirements:** * Certificate file in **PEM format** * Private key file in **PEM format** * The private key must match the certificate * The certificate must not be expired * The certificate must cover the domain(s) you intend to use ::: info **Important:** smoxy cannot automatically renew manually uploaded certificates. You are responsible for uploading a new certificate before the current one expires. ::: *** ### How Certificate Generation Works #### Step 1: DNS Verification For each Subject Alternative Name (SAN) on the certificate, smoxy requires a **CNAME record** pointing to smoxy's ACME verification infrastructure: ``` _acme-challenge.yourdomain.com → yourdomain.com.acme.smoxy.eu. ``` This CNAME record allows smoxy to complete the ACME DNS-01 challenge required by Let's Encrypt. The target is the SAN's own domain followed by `.acme.smoxy.eu.` (including the trailing dot). The exact value for each SAN is shown in the certificate's **SANs** tab - copy it from there. ::: info **Important:** If you use Cloudflare, the Cloudflare proxy must be **disabled** for the `_acme-challenge` CNAME record. See [Cloudflare Setup](/developer-guide/cloudflare-setup) for details. ::: #### Step 2: Certificate Issuance Once all DNS records are verified, smoxy automatically: 1. Requests a certificate from Let's Encrypt 2. Completes the ACME challenge 3. Downloads and installs the certificate 4. Activates the certificate for your hostnames #### Step 3: Automatic Renewal smoxy monitors certificate expiration and renews automatically. Renewal timing follows the CA's recommended renewal window (ACME Renewal Information, ARI); if no window is available, smoxy falls back to renewing roughly two weeks before expiry. The renewal follows the same verification flow - if the DNS records are still in place, it happens completely automatically. *** ### Subject Alternative Names (SANs) A Subject Alternative Name (SAN) is an individual domain name covered by an SSL certificate. When you create a new domain in smoxy, two default SANs are added: * `yourdomain.com` - the root domain * `*.yourdomain.com` - wildcard for all subdomains #### Adding Additional SANs If you need to cover additional specific subdomains (e.g., `specific.sub.yourdomain.com` that isn't covered by the wildcard), smoxy can add additional SANs to your certificate. Each SAN requires its own `_acme-challenge` CNAME record for DNS verification. When you add such a hostname to a zone and the domain's DNS is managed by smoxy, this can happen automatically: smoxy offers to add the missing SAN, create its validation record, and trigger the certificate renewal in one step. See [Automatic DNS Setup](/zones/hostnames#automatic-dns-setup). #### SAN Status Each SAN has two independent statuses: | Status | Values | Meaning | | -------------- | ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **DNS Status** | `Unknown` / `Valid` / `Missing` | Whether the `_acme-challenge` CNAME record is correctly configured. `Unknown` means it hasn't been checked yet; `Missing` covers every case where the expected record isn't found - including a CNAME pointing at the wrong target or a conflicting TXT record | | **SSL Status** | `Covered` / `Not covered` | Whether the current certificate actually includes this domain | smoxy regularly re-checks DNS records: * Every **24 hours** for valid records (to detect removal) * Every **1 hour** for missing records (to detect when you've added them) You can also trigger a manual **Recheck DNS** on the SANs tab. After a manual recheck, smoxy schedules the next automatic check in 24 hours for a still-valid record, or in 5 minutes for a still-missing one. When new SANs are added and their DNS is verified, smoxy automatically triggers a certificate regeneration to include the new domains. *** ### Certificate Statuses Your SSL certificate in smoxy can be in one of the following states: | Status | Meaning | Action Required | | ------------ | --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | | **Pending** | Certificate generation has been initiated but not yet completed | Wait for generation to complete | | **Active** | Certificate is valid and working | None | | **Renewing** | A renewal is in progress | None - smoxy handles this automatically | | **Expired** | The certificate has passed its expiry date | Auto-managed: check the `_acme-challenge` records so renewal can complete. Self-managed: upload a new certificate | | **Failed** | Certificate generation or renewal failed | Check each SAN's DNS status and the latest attempt for the specific error | ::: info **Note:** DNS problems don't appear as certificate statuses. They surface per SAN as a **DNS Status** of `Missing` on the SANs tab. Common causes are a missing `_acme-challenge` CNAME record, a CNAME pointing at the wrong target, or a conflicting TXT record for `_acme-challenge`. See [SSL Troubleshooting](/ssl-and-certificates/ssl-troubleshooting) for how to fix each. ::: *** ### Certificate Generation Workflow Behind the scenes, smoxy tracks certificate generation through a detailed workflow: Each generation or renewal is tracked as an **attempt**, which is **Processing**, **Succeeded**, or **Failed**. An attempt runs through the following steps in order: | Step | What happens | | ------------------------- | ------------------------------------------------------- | | **Initialize** | The attempt is set up | | **Verify CNAME Record** | Checks the `_acme-challenge` CNAME records for all SANs | | **Create ACME Order** | Requests a certificate order from Let's Encrypt | | **Provision DNS Record** | Creates the DNS-01 challenge record | | **Await DNS Propagation** | Waits until the challenge record resolves | | **Authorize** | Lets the CA validate the challenge | | **Poll Order Status** | Waits for the order to become ready | | **Download Certificate** | Downloads the issued certificate | | **Save Certificate** | Stores and activates the certificate | If a transient error occurs during generation, smoxy automatically retries with exponential backoff. The errors you may see fall into two groups - problems with the ACME/DNS flow for auto-managed certificates, and validation failures when uploading a custom certificate: | Error | Cause | Resolution | | --------------------------- | ------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | | **Rate limit** | Too many certificate requests to Let's Encrypt | Automatic - smoxy waits and retries later | | **CNAME record missing** | The `_acme-challenge` CNAME record is missing for one or more SANs | Add the missing CNAME record(s). On Cloudflare, disable the proxy for the challenge record (see [Cloudflare Setup](/developer-guide/cloudflare-setup)) | | **CNAME record invalid** | The CNAME record exists but points to the wrong target | Update the CNAME to the exact target shown on the SANs tab | | **DNS provisioning failed** | smoxy could not create the DNS-01 challenge record | Temporary - smoxy retries automatically | | **ACME error** | The certificate authority reported an error | Check DNS propagation; smoxy retries automatically | | **Invalid PEM** | An uploaded certificate or key is not valid PEM data | Re-export the file in PEM format and upload again | | **Key mismatch** | The uploaded private key does not match the certificate | Upload the private key that belongs to the certificate | | **Certificate expired** | The uploaded certificate has already expired | Obtain and upload a current certificate | | **SAN mismatch** | The uploaded certificate does not cover all configured SANs | Use a certificate that covers your domains | | **Invalid chain** | The uploaded chain / intermediate certificate is not valid PEM data | Provide a valid intermediate chain in the Chain PEM field | | **Internal error** | An unexpected error occurred | Retry; contact support if it persists | *** ### Uploading a Self-managed Certificate To upload your own SSL certificate: 1. Open **SSL Certificates** in the smoxy sidebar 2. Click **New Certificate** to open the **New SSL Certificate** dialog 3. Set **Type** to **Custom** 4. Provide: * **Certificate PEM**: Your server certificate in PEM format * **Private Key PEM**: The matching private key * **Chain PEM (optional)**: Any intermediate certificates, in this separate field #### Validation When uploading, smoxy validates: * The certificate is parseable and in valid PEM format * The private key matches the certificate * The certificate has not expired * The SANs in the certificate cover your domain If the SANs in the new certificate differ from the current ones, smoxy will show you the differences and ask for confirmation before proceeding. #### After Upload * The previous certificate is archived for audit purposes * The new certificate is immediately activated * Since self-managed certificates are not auto-renewed, **you must upload a replacement before expiration** *** ### Wildcard Certificates smoxy creates **wildcard certificates** by default. A wildcard certificate for `*.yourdomain.com` covers: * `www.yourdomain.com` * `shop.yourdomain.com` * `api.yourdomain.com` * Any other single-level subdomain **What wildcards do NOT cover:** * The root domain itself (`yourdomain.com`) - this is added as a separate SAN * Multi-level subdomains (`sub.sub.yourdomain.com`) - these need additional SANs When you add a hostname like `shop.yourdomain.com` to a smoxy **Zone** (the delivery and security configuration for a hostname - distinct from a DNS zone), smoxy checks if the existing wildcard certificate already covers it. If yes, no additional certificate work is needed. *** ### Downloading Certificates You can download your SSL certificate and private key for use in external tools: 1. Open **SSL Certificates** in the smoxy sidebar and select the certificate 2. Use the **Download** buttons for the certificate, chain, or private key **Required role:** Owner or Manager *** ### Subdomain Reuse When you create the main domain (e.g., `yourdomain.com`) and a wildcard certificate is generated, all subdomains can reuse this certificate. When adding subdomains as hostnames to zones: * No additional DNS verification is needed for the subdomain * The existing wildcard certificate automatically covers the subdomain * This significantly speeds up the setup of additional hostnames ::: info **Recommendation:** Always create your main domain first, then add subdomains. This ensures the wildcard certificate is in place and subdomains can be configured without additional SSL steps. ::: *** ### Troubleshooting #### Certificate stuck in "Pending" * Check that all required `_acme-challenge` CNAME records are set at your DNS provider * DNS propagation can take up to 48 hours (though usually much faster) * If using Cloudflare, ensure the proxy is disabled for challenge records #### DNS Status shows "Missing": record not found The `_acme-challenge` CNAME record is not found. Verify: * The record exists at your DNS provider * It points to the correct target (shown on the certificate's SANs tab) * DNS has had time to propagate #### DNS Status shows "Missing": CNAME points to the wrong target The CNAME record exists but points to an incorrect target, so it still counts as `Missing`. Update the record to the exact target shown on the certificate's SANs tab. #### DNS Status shows "Missing": conflicting TXT record A TXT record for `_acme-challenge` exists alongside or instead of the required CNAME, which also results in a `Missing` status. Remove the TXT record and ensure only the CNAME record exists. #### Certificate not renewing * Auto-managed certificates renew automatically within the CA's recommended renewal window (roughly two weeks before expiry as a fallback) * Ensure the `_acme-challenge` CNAME records are still in place * Self-managed certificates are **never** auto-renewed - you must upload a replacement #### SAN changes not reflected After adding new SANs, smoxy needs to regenerate the certificate. This happens automatically once the DNS verification for the new SAN passes. Check the SAN's DNS status on the certificate's SANs tab.