# 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 (30 days before expiration)

#### 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

{% hint style="info" %}
**Important:** smoxy cannot automatically renew manually uploaded certificates. You are responsible for uploading a new certificate before the current one expires.
{% endhint %}

***

### 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  →  your-org.acme.smoxy.eu
```

This CNAME record allows smoxy to complete the ACME DNS-01 challenge required by Let's Encrypt.

{% hint style="info" %}
**Important:** If you use Cloudflare, the Cloudflare proxy must be **disabled** for the `_acme-challenge` CNAME record. See Cloudflare Setup for details.
{% endhint %}

#### 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 begins the renewal process **30 days before expiry**. The renewal follows the same verification flow. If the DNS records are still in place, renewal 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.

#### SAN Status

Each SAN has two independent statuses:

| Status         | Values                    | Meaning                                                            |
| -------------- | ------------------------- | ------------------------------------------------------------------ |
| **DNS Status** | `Valid` / `Missing`       | Whether the `_acme-challenge` CNAME record is correctly configured |
| **SSL Status** | `Covered` / `Not covered` | Whether the current certificate actually includes this domain      |

smoxy regularly re-checks DNS records:

* Every **12 hours** for valid records (to detect removal)
* Every **1 hour** for missing records (to detect when you've added them)

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                                         |
| ----------------- | ----------------------------------------------------------------------- | ------------------------------------------------------- |
| **Active**        | Certificate is valid and working                                        | None                                                    |
| **Pending**       | Certificate generation has been initiated but not yet completed         | Wait for generation to complete                         |
| **DNS Missing**   | The `_acme-challenge` CNAME record does not exist                       | Add the required CNAME record at your DNS provider      |
| **DNS Wrong**     | The CNAME record exists but points to the wrong target                  | Update the CNAME to point to the correct smoxy target   |
| **DNS Duplicate** | A TXT record exists for `_acme-challenge` instead of the required CNAME | Remove the TXT record and create a CNAME record instead |

{% hint style="info" %}
**Note:** Multiple DNS issues can exist simultaneously (e.g., some SANs may have missing records while others have wrong targets).
{% endhint %}

***

### Certificate Generation Workflow

Behind the scenes, smoxy tracks certificate generation through a detailed workflow:

| Phase           | What happens                                  |
| --------------- | --------------------------------------------- |
| **Pending**     | Generation request is queued                  |
| **Starting**    | Worker picks up the request                   |
| **CNAME Check** | Verifying DNS records for all SANs            |
| **Ordering**    | Requesting certificate from Let's Encrypt     |
| **Validating**  | ACME challenge validation in progress         |
| **Completed**   | Certificate successfully issued and installed |

If an error occurs during generation, smoxy automatically retries with exponential backoff. Common errors include:

| Error                 | Cause                                                       | Resolution                                                |
| --------------------- | ----------------------------------------------------------- | --------------------------------------------------------- |
| **CNAME not found**   | DNS record missing for one or more SANs                     | Add the missing CNAME record(s)                           |
| **TXT record exists** | A TXT record for `_acme-challenge` conflicts with the CNAME | Remove the TXT record, keep only the CNAME                |
| **Rate limit**        | Too many certificate requests to Let's Encrypt              | Automatic — smoxy waits and retries after 1 hour          |
| **Validation failed** | ACME challenge could not be verified                        | Check DNS propagation; smoxy will retry automatically     |
| **Cloudflare error**  | Cloudflare proxy is interfering with DNS verification       | Disable Cloudflare proxy for the `_acme-challenge` record |

***

### Uploading a Self-managed Certificate

To upload your own SSL certificate:

1. Navigate to **Domains & DNS** and select your domain
2. Go to the **SSL** tab
3. Click **Upload Custom SSL Certificate**
4. Provide:
   * **Certificate** (PEM format): The full certificate chain, including intermediate certificates
   * **Private Key** (PEM format): The matching private key

#### 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 site, 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. Navigate to **Domains & DNS** and select your domain
2. Go to the **SSL** tab
3. Click the **Download** button for the certificate or key

**Required role:** Owner or Maintainer

***

### 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 sites:

* 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

{% hint style="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.
{% endhint %}

***

### 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 Missing" status

The `_acme-challenge` CNAME record is not found. Verify:

* The record exists at your DNS provider
* It points to the correct target (shown in smoxy)
* DNS has had time to propagate

#### "DNS Wrong" status

The CNAME record exists but points to an incorrect target. Update the record to point to the target shown in smoxy.

#### "DNS Duplicate" status

A TXT record for `_acme-challenge` exists alongside or instead of the required CNAME. Remove the TXT record and ensure only the CNAME record exists.

#### Certificate not renewing

* Auto-managed certificates renew automatically 30 days before expiration
* 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 in the SSL tab.