Aller au contenu
local-cert
Parcourir la documentation

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 scope cert: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 :

ChangeBatch
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.com

Visible 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) :

zone
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.

shell
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 :

GET /api/v1/dns/records
{ "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 TXTCommentaire
A/AAAA/CNAME/TXT persistantsouioui
_acme-challenge.*non — durée de vie ~2 min, supprimé en fin d'ordreoui
Noms wildcardnon — Route53 n'accepte * qu'en label le plus à gauche, _local-cert.*.x est invalideoui

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 CLI
aws route53 change-tags-for-resource --resource-type hostedzone \
  --resource-id Z0123456ABCDEFGHIJK \
  --add-tags Key=managed-with,Value=local-cert

IAM 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 :

iam-policy.json
{
  "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 :

shell
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.

aws:check
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 :

incorrect
"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.