> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oximail.ch/llms.txt
> Use this file to discover all available pages before exploring further.

# TLS & ACME

> Les certificats pour HTTPS, SMTP et IMAP : l'ACME intégré (Let's Encrypt) en topologie directe, l'alternative proxy inverse, le rechargement à chaud sans redémarrage, et le couplage DANE au renouvellement.

Un seul certificat sert toutes les surfaces TLS de l'instance : HTTPS/JMAP (443), la soumission STARTTLS (587), SMTPS (465) et IMAPS (993). Qui l'obtient dépend de la topologie choisie au [premier démarrage](../first-boot).

## Topologie directe : ACME intégré

Quand OxiMail possède les ports 80/443, il provisionne et renouvelle lui-même son certificat auprès de Let's Encrypt :

```toml theme={null}
[tls]
acme_enabled = true
acme_email = "admin@example.com"

[server]
http_bind = "0.0.0.0:80"    # sert le défi HTTP-01 (et redirige vers HTTPS)
```

Le premier certificat est obtenu au premier démarrage (l'assistant l'attend jusqu'à 90 secondes) ; les renouvellements sont automatiques avant expiration. Le port 80 doit rester joignable depuis Internet pour le défi HTTP-01. L'assistant publie aussi un **enregistrement CAA** qui restreint l'émission à Let's Encrypt : un durcissement par défaut cohérent avec cette configuration.

**Un renouvellement ne redémarre jamais rien.** Le nouveau certificat est permuté atomiquement (`ArcSwap`, ADR-016) : les connexions en cours terminent sur l'ancien, les nouvelles poignées de main reçoivent le nouveau, sur tous les écouteurs à la fois, SMTP et IMAP compris.

## Topologie proxy inverse

Derrière Caddy ou Nginx, le proxy possède 80/443 et ses propres certificats, et `acme_enabled = false` (l'assistant l'écrit pour vous). Deux points restent importants :

* **SMTP (25/587/465) et IMAPS (993) ne passent pas par le proxy** : OxiMail y termine le TLS lui-même. Il lui faut un certificat pour eux : pointez `[tls]` vers les fichiers de certificat du proxy, ou copiez-les par un hook de déploiement, en sachant qu'OxiMail recharge les fichiers à chaud quand ils changent.
* Le proxy doit transmettre **tout** sauf le chemin de défi ACME, avec `X-Forwarded-For` depuis une adresse de `[server] trusted_proxies` : voir [premier démarrage](../first-boot) pour l'extrait généré et la règle CORS.

## Le couplage DANE

Si vous publiez des enregistrements DANE TLSA ([authentification du courrier](./email-auth-security)), un renouvellement de certificat **change la valeur épinglée** : des TLSA périmés cassent le courrier entrant de chaque expéditeur qui valide DANE. C'est pourquoi `dane_enabled = true` (le défaut) exige un fournisseur `[dns]` configuré : après chaque renouvellement, OxiMail republie lui-même les TLSA (API Cloudflare), ou journalise un rappel bruyant en mode `manual`. Un serveur avec DANE actif et sans fournisseur DNS **refuse de démarrer** plutôt que de vous préparer cette casse silencieuse.

## Échange de clés post-quantique

Chaque surface TLS qu'OxiMail termine lui-même (25, 465, 587, 993, et le 443 quand aucun frontal ne se trouve devant) propose en tête le groupe hybride **X25519MLKEM768**, avec le X25519 classique en repli. Rien n'est cassé au passage : un pair qui ne connaît pas le groupe hybride négocie X25519 exactement comme avant. Il n'y a pas de réglage pour l'activer, c'est la posture livrée.

La menace visée est « récolter maintenant, déchiffrer plus tard » : un adversaire enregistre le trafic d'aujourd'hui pour le déchiffrer quand la machine capable de le faire existera. Être en retard là-dessus ne se rattrape pas après coup, d'où un défaut plutôt qu'une option. Ce n'est pas théorique pour le courrier : Gmail propose déjà le groupe hybride sur 25, 465, 587 et 993, le courrier sortant vers lui négocie donc du post-quantique dès aujourd'hui.

**Vérifiez au lieu de supposer.** Cette propriété précise a été fausse en silence pendant des mois ici : la fonctionnalité était compilée alors que le fournisseur de cryptographie installé n'en avait aucune implémentation, si bien que chaque session retombait sur le X25519 classique pendant que la configuration se lisait comme le contraire. Un repli de ce genre est invisible : aucune erreur, aucune ligne de journal, rien qui échoue. Avec OpenSSL 3.5 ou plus récent :

```bash theme={null}
openssl s_client -connect mail.example.com:993 -groups X25519MLKEM768 </dev/null 2>&1 | grep -i 'group'
```

Lancez-le sur chaque port que vous servez. Un frontal placé devant le 443 répond pour lui-même, pas pour OxiMail : contrôlez les ports courrier séparément.

**Les connexions sortantes utilisent la même pile.** Le client HTTP qui sert les webhooks, le push et le déploiement des liens tourne sur la même implémentation TLS que le serveur : ces requêtes ont donc gagné le groupe hybride elles aussi. Il fait confiance au magasin de certificats **du système d'exploitation** et non à une liste de racines embarquée, et c'est délibéré : un point de terminaison dont le certificat remonte à une autorité privée installée sur la machine continue de fonctionner.

## Inspecter et dépanner

```bash theme={null}
oximail cert ...                      # inspecter le ou les certificats actifs
journalctl -u oximail | grep -i acme  # l'historique des défis et renouvellements
```

Échecs courants :

* **Port 80 injoignable** : le défi HTTP-01 ne peut pas aboutir. Ouvrez-le dans le pare-feu ou le groupe de sécurité ; il ne sert jamais que les défis et les redirections.
* **Limité par Let's Encrypt** : des tentatives d'émission échouées en boucle (généralement une erreur DNS) peuvent atteindre les limites par domaine de LE ; corrigez la cause avant de réessayer.
* **Des expéditeurs DANE rebondissent après un renouvellement** : les TLSA n'ont pas été mis à jour. Vérifiez la configuration du fournisseur `[dns]` et les journaux de renouvellement.

Les certificats et le matériel de compte ACME vivent sous `/etc/oximail/tls/`, qui fait partie de la [surface de sauvegarde](./operations) standard.