Sécurité
Comment local-cert protège les secrets qu'il détient, comment il marque ce qu'il écrit dans vos zones, et les droits Route53 au plus juste avec lesquels il fonctionne.
Secrets et accès
- Mots de passe hachés en argon2id (19 MiB, t=2, p=1), paramètres portés par la chaîne PHC — les relever plus tard garde les anciens hashs vérifiables.
- Clés privées chiffrées en AES-256-GCM (
MASTER_KEY) avant insertion en base. Elles ne transitent en clair que sur/bundle, avec le scopecert:export, et chaque export est tracé dans le journal d'audit. - Toutes les mutations passent par
audit_log(acteur, action, cible, IP). - Webhooks signés HMAC-SHA256 (
X-Signature: sha256=…, cléWEBHOOK_SECRET). - Cookie de session
httpOnly+SameSite=lax: pas de CSRF sur les endpoints mutants, le cookie n'étant jamais joint à un POST cross-site. - La clé d'API de votre propre compte ne peut pas être supprimée depuis la console (la révoquer est possible, c'est réversible). Rotation via
scripts/reset-admin.ts. - Aucun secret n'est écrit sur disque : ni token, ni mot de passe, ni fichier d'amorçage.
Marquage des ressources
Tout ce que local-cert crée est estampillé managed-with-local-cert.
Contrainte AWS : Route53 n'expose aucun tag sur les resource record sets. ChangeTagsForResource n'accepte que hostedzone et healthcheck. Les vrais tags AWS sont donc hors de portée pour des enregistrements DNS. La provenance est inscrite par les deux seuls canaux qu'un record set autorise.
1. Le commentaire du ChangeBatch
Sur chaque écriture, sans exception :
Comment: managed-with-local-cert | UPSERT A nas.home.example.com
Comment: managed-with-local-cert | UPSERT TXT _acme-challenge.nas.home.example.com
Comment: managed-with-local-cert | DELETE A nas.home.example.comVisible dans l'historique des changements Route53 et dans l'événement CloudTrail correspondant. Utile pour l'audit, mais non interrogeable.
2. Un enregistrement TXT compagnon
_local-cert.<nom>, valeur managed-with-local-cert, écrit dans le même ChangeBatch que l'enregistrement lui-même (atomique : jamais de marqueur orphelin après une écriture partielle, et zéro appel API supplémentaire) :
nas.home.example.com. A 60 192.168.1.50
_local-cert.nas.home.example.com. TXT 60 "managed-with-local-cert"C'est ce qui rend la propriété interrogeable : un simple dig suffit, et ça survit à une base qui aurait perdu la trace d'un enregistrement.
dig +short TXT _local-cert.nas.home.example.com
# "managed-with-local-cert"GET /api/v1/dns/records résout la propriété à partir des marqueurs présents dans la zone et annote chaque ligne :
{ "name": "nas.home.example.com", "type": "A", "managed": true, "marker": false }
{ "name": "_local-cert.nas.home.example.com", "type": "TXT", "managed": false, "marker": true }
{ "name": "legacy.home.example.com", "type": "A", "managed": false, "marker": false }Ce qui n'est pas marqué, et pourquoi
| Marqueur TXT | Commentaire | |
|---|---|---|
| A/AAAA/CNAME/TXT persistants | oui | oui |
_acme-challenge.* | non — durée de vie ~2 min, supprimé en fin d'ordre | oui |
| Noms wildcard | non — Route53 n'accepte * qu'en label le plus à gauche, _local-cert.*.x est invalide | oui |
TAG_RECORDS=0 désactive les marqueurs TXT ; les commentaires restent.
Hosted zones : local-cert n'en crée jamais, il consomme des zones existantes. Elles ne sont donc pas taguées — ce serait modifier une ressource qui ne lui appartient pas. Si vous voulez ce tag, posez-le vous-même :
aws route53 change-tags-for-resource --resource-type hostedzone \
--resource-id Z0123456ABCDEFGHIJK \
--add-tags Key=managed-with,Value=local-certIAM Route53
La console génère la politique du provider pour vous, avec vos identifiants réels : voir le guide Provider AWS pour le modèle utilisateur / rôle et la mise en place pas à pas. Cette section sert de référence pour écrire ou auditer une politique à la main.
Politique au plus juste — l'application n'a besoin d'écrire que des TXT _acme-challenge, plus les A/AAAA que vous lui demandez explicitement :
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "route53:ChangeResourceRecordSets",
"Resource": "arn:aws:route53:::hostedzone/Z0123456ABCDEFGHIJK",
"Condition": {
"ForAllValues:StringEquals": {
"route53:ChangeResourceRecordSetsRecordTypes": ["TXT", "A", "AAAA"]
},
"ForAllValues:StringLike": {
"route53:ChangeResourceRecordSetsNormalizedRecordNames": [
"*.home.example.com"
]
}
}
},
{
"Effect": "Allow",
"Action": [
"route53:GetChange",
"route53:GetHostedZone",
"route53:ListResourceRecordSets"
],
"Resource": "*"
}
]
}Les TXT couvrent à la fois les challenges _acme-challenge et les marqueurs de provenance _local-cert. La copie prête à l'emploi est dans docs/iam-policy.json du dépôt (remplacez l'id de zone).
Préflight
Les permissions sont sondées à l'ajout d'un domaine : si un appel nécessaire manque, le domaine n'est pas créé et la console affiche exactement lequel et pourquoi. ?force=true (bouton Enregistrer quand même) permet de l'enregistrer malgré tout et de corriger l'IAM ensuite.
Le nom de base déclaré est aussi vérifié contre l'apex réel de la zone : entrer home.example.com avec une zone qui sert apps.exemple.co est refusé tout de suite.
Les mêmes contrôles en ligne de commande :
npm run aws:check -- Z0123456ABCDEFGHIJK # provider PROVIDER_AWS_DEFAULT_*
npm run aws:check -- Z0123456ABCDEFGHIJK PROD # un autre provider déclaréLa commande sonde les cinq appels que le code effectue réellement et dit lesquels manquent. L'écriture est testée par un DELETE d'un enregistrement qui ne peut pas exister : Route53 évalue IAM avant de valider le batch, donc un principal autorisé reçoit InvalidChangeBatch et un principal refusé reçoit AccessDenied — dans les deux cas la zone n'est pas modifiée.
Sonder bat la lecture de la politique : le document IAM est en général illisible depuis une clé scopée, et une condition qui ne matche pas produit exactement le même message qu'une instruction absente.
zone Z0123456ABCDEFGHIJK (us-east-1) — home.example.com
OK ListResourceRecordSets
DENIED GetHostedZone REQUIRED — used to read the delegation set…
OK GetChange
DENIED ChangeResourceRecordSets (TXT) REQUIRED — DNS-01 is built on TXT records…
OK ChangeResourceRecordSets (A)Trois pièges qui produisent le même AccessDenied
Le message « because no identity-based policy allows the … action » ne veut pas dire qu'il n'y a aucune politique : c'est aussi ce qu'AWS renvoie quand une politique existe mais qu'une condition ne matche pas.
1. TXT absent de ChangeResourceRecordSetsRecordTypes. DNS-01 repose entièrement sur des enregistrements TXT — sans ce type, rien ne peut être émis. Une politique qui n'autorise que A laisse passer la publication de l'enregistrement d'hôte et refuse tout le reste.
2. Deux blocs Condition avec le même opérateur. Le JSON ne garde que le dernier, silencieusement :
"Condition": {
"ForAllValues:StringEquals": { "route53:ChangeResourceRecordSetsRecordTypes": ["TXT","A"] },
"ForAllValues:StringEquals": { "route53:ChangeResourceRecordSetsActions": ["UPSERT","DELETE"] }
}La contrainte sur les types disparaît. Fusionnez les clés dans un seul bloc par opérateur.
3. GetHostedZone oublié. Souvent absent des politiques « minimales » trouvées en ligne, parce que la plupart des clients ACME ne s'en servent pas. local-cert en a besoin pour lire le delegation set et interroger les NS autoritatifs — sans lui, l'émission échoue à l'étape de propagation, après avoir écrit le TXT de challenge.
Les credentials viennent de la chaîne AWS standard (env, ~/.aws/credentials, IRSA, rôle d'instance) quand le provider ne porte pas de paire de clés. Un aws_role_arn par domaine permet d'assumer un rôle dédié par zone — utile en multi-comptes.