Outils de développement · Générateur UUID
UUID basés sur le nom (v3 et v5) : ID déterministes à partir d'un espace de noms
· Contexte
uuid cryptographie API du navigateur
Lorsque le même enregistrement externe doit toujours obtenir le même identifiant, les UUID aléatoires ne suffiront pas. Les UUID des versions 3 et 5 hachent un espace de noms et un nom dans un identifiant stable ; cet article explique comment et quand les utiliser.
Réimporter deux fois le même client : le problème de duplication que les identifiants déterministes résolvent
Un pipeline d'importation de données reçoit les enregistrements client d'un système externe avec des ID externes stables au sein de ce système. Si vous générez un nouveau UUID aléatoire pour chaque exécution d'importation, importer deux fois le même client produit deux identifiants différents et des enregistrements en double. Cette duplication se répercute en aval dans les systèmes de reporting, de facturation et de support. Si vous dérivez un UUID à partir de l'ID externe du client et d'un espace de noms stable représentant votre source d'importation, chaque importation produit le même UUID pour le même client, vous permettant d'identifier et de mettre à jour les enregistrements existants. Ce déterminisme est la caractéristique déterminante des UUID v3 et v5 : ils ne sont pas générés indépendamment mais dérivés d'entrées, et la même entrée produit toujours le même UUID.
Espace de noms plus nom : comment l'entrée est concaténée et hachée, et pourquoi l'espace de noms empêche les collisions entre différentes sources
Un UUID v3 ou v5 est dérivé de trois composants : un espace de noms UUID (généralement prédéfini), un nom (n'importe quelle chaîne d'octets) et un algorithme de hachage (MD5 pour v3, SHA-1 pour v5). Concaténez les 16 octets de l'espace de noms UUID avec les UTF-8 octets du nom, hachez la concaténation, prenez les 16 premiers octets de la sortie de hachage et interprétez ces octets comme un UUID avec le quartet de version défini sur 3 ou 5. L'espace de noms partitionne l'espace d'identification : les UUID v5 de l'espace de noms DNS n'entrent jamais en collision avec les UUID v5 de l'espace de noms URL. La RFC 9562 définit quatre espaces de noms prédéfinis : par nom DNS, par URL, par OID et par nom distinctif X.500. Les organisations peuvent créer leur propre espace de noms en générant un UUID v4.
MD5 en v3 et SHA-1 en v5 — pourquoi un hachage affaibli est acceptable ici, puisque l'ID n'est pas un contrôle de sécurité
La version 3 utilise MD5 et la version 5 utilise SHA-1, des choix datant de leurs dates de spécification et de leurs implémentations disponibles. Pour les UUID basés sur le nom, cette distinction est sans importance car la fonction de hachage ne constitue pas une limite de sécurité ou un contrôle cryptographique. Le UUID ne prouve pas l'authenticité ou l'intégrité ; il s'agit simplement de convertir une chaîne de longueur variable en une valeur fixe 128 bits. Le modèle d'attaque n'est pas pertinent car les UUID sont stockés et comparés comme des valeurs opaques, et non comme des preuves ou des contrôles de sécurité. Les nouvelles implémentations devraient utiliser la v5 (SHA-1) plutôt que la v3 (MD5), non pas pour des raisons de sécurité impérieuses mais parce que la v5 est la norme moderne et largement disponible.
Les espaces de noms prédéfinis : DNS, URL, OID et X.500, et quand créer le vôtre
RFC 9562 spécifie exactement quatre UUID d'espace de noms prédéfinis avec des représentations d'octets spécifiques : 6ba7b810-9dad-11d1-80b4-00c04fd430c8 pour DNS, 6ba7b811-9dad-11d1-80b4-00c04fd430c8 pour les URL, 6ba7b812-9dad-11d1-80b4-00c04fd430c8 pour les OID et 6ba7b814-9dad-11d1-80b4-00c04fd430c8 pour les noms distinctifs X.500. Un UUID v5 dérivé de l'espace de noms DNS et le nom www.example.com seront toujours identiques et n'entreront jamais en collision avec un UUID v5 de l'espace de noms URL. L'utilisation d'un espace de noms prédéfini garantit l'interopérabilité : si plusieurs équipes utilisent indépendamment la v5 avec l'espace de noms DNS, elles génèrent des UUID identiques pour les mêmes noms DNS. Choisir ou créer un espace de noms fait partie de la conception du schéma.
Exemple concret : dériver conceptuellement un UUID v5 à partir de l'espace de noms d'URL et d'une URL d'enregistrement, étape par étape
Dérivez conceptuellement un UUID v5 à partir de l'espace de noms de l'URL et du nom https://example.com/api/users/42. L'espace de noms UUID sous forme de 16 octets est 6b a7 b8 11 9d ad 11 d1 80 b4 00 c0 4f d4 30 c8. Le nom est la chaîne UTF-8 https://example.com/api/users/42, qui fait 30 octets. Concaténez les octets de l'espace de noms (16) et les octets de nom (30) pour obtenir un total de 46 octets. Calculez le hachage SHA-1, produisant un hachage 20-byte. Prenez les premiers 16 octets et interprétez-les comme un UUID avec le quartet de version défini sur 5 et les bits de variante définis sur la norme RFC. Le recalculer avec des entrées identiques produit le résultat identique. La plupart des développeurs utilisent leur bibliothèque de langage UUID pour calculer la v5.
Là où le modèle se brise : lorsque les noms changent, lorsque l'espace de noms est incohérent entre les équipes et lorsque les entrées sont secrètes
Les UUID basés sur le nom supposent que le nom est stable et cohérent entre les systèmes et les exécutions d'importation. Si le même enregistrement externe porte des noms différents dans différents systèmes, la génération de v5 à partir de chaque nom produit des UUID différents et ne parvient pas à identifier la même personne. Si un espace de noms n'est pas convenu entre les équipes (chaque équipe créant son propre espace de noms pour ce qui est en réalité la même source), elles génèrent des UUID différents et ne parviennent pas à faire correspondre les enregistrements. Si l'entrée est une donnée sensible, générer un UUID v5 signifie que UUID est une valeur publique et déterministe que n'importe qui peut rechercher s'il connaît les entrées. Le déterminisme s'interrompt lorsque les entrées changent ou que les définitions de l'espace de noms sont incohérentes.
Ce que ceci ne couvre pas : le générateur ToolAcre s'appuie sur CSPRNG, donc les identifiants basés sur le nom ont besoin de la bibliothèque UUID de votre langue.
ToolAcre génère uniquement des UUID v4, tirés du générateur cryptographiquement sécurisé du navigateur pour plus d'indépendance. La dérivation UUID basée sur le nom nécessite la bibliothèque UUID de votre langage ou une implémentation qui calcule SHA-1 et formate correctement le résultat. Cet article explique le concept et les cas d'utilisation ; la mise en œuvre de la génération v5 est simple dans n'importe quel langage avec accès aux bibliothèques cryptographiques standard. Les mécanismes de dérivation de la v5 sont simples ; le défi consiste à l'intégrer dans un schéma système où l'espace de noms est stable, le nom est cohérent et l'approche est bien documentée pour votre équipe. Les équipes de développement doivent documenter les choix d’espace de noms.
À retenir : déterministe lorsque vous en avez besoin, aléatoire sinon – utilisez la v5 pour les mappages stables et le générateur ToolAcre pour tout ce qui devrait être indevinable
Utilisez la version 5 pour des mappages stables entre les identifiants externes et vos enregistrements internes. Le déterminisme empêche les importations en double et rend les enregistrements correspondants entre les systèmes simples et fiables. N'utilisez pas d'UUID basés sur le nom pour des identifiants qui doivent être impossibles à deviner ou pour des scénarios nécessitant une confidentialité et des secrets élevés. ToolAcre génère des UUID v4 aléatoires pour les identifiants qui doivent être indépendants et distincts sans prévisibilité. Lorsque vos systèmes ont besoin d'identifiants déterministes qui mappent les entrées à des identifiants fixes, votre bibliothèque de langage UUID peut les calculer. Le déterminisme est une fonctionnalité puissante lorsque vous contrôlez l'entrée.