Ferramentas para desenvolvedores · Gerador UUID
UUIDs baseados em nomes (v3 e v5): IDs determinísticos de um namespace
· Fundo
uuid criptografia APIs do navegador
Quando o mesmo registro externo deve sempre obter o mesmo identificador, UUIDs aleatórios não funcionarão. Os UUIDs das versões 3 e 5 fazem hash de um namespace e um nome em um ID estável; esta postagem explica como e quando usá-los.
Reimportar o mesmo cliente duas vezes – o problema de duplicação que os IDs determinísticos resolvem
Um pipeline de importação de dados recebe registros de clientes de um sistema externo com IDs externos estáveis nesse sistema. Se você gerar um novo UUID aleatório para cada execução de importação, importar o mesmo cliente duas vezes produzirá dois identificadores diferentes e registros duplicados. Esta duplicação flui posteriormente para os sistemas de relatórios, cobrança e suporte. Se você derivar um UUID do ID externo do cliente e um namespace estável representando sua origem de importação, cada importação produzirá o mesmo UUID para o mesmo cliente, permitindo identificar e atualizar registros existentes. Este determinismo é a característica definidora dos UUIDs v3 e v5: eles não são gerados independentemente, mas derivados de entradas, e a mesma entrada sempre produz o UUID idêntico.
Namespace mais nome — como a entrada é concatenada e com hash e por que o namespace evita colisões entre diferentes fontes
Um v3 ou v5 UUID é derivado de três componentes: um namespace UUID (normalmente predefinido), um nome (qualquer sequência de bytes) e um algoritmo de hash (MD5 para v3, SHA-1 para v5). Concatene o 16 bytes do espaço para nome UUID com o UTF-8 bytes do nome, hash da concatenação, pegue o primeiro 16 bytes da saída hash e interprete esses bytes como um UUID com a versão nibble definida como 3 ou 5. O namespace particiona o espaço de ID: v5 UUIDs do DNS namespace nunca colide com UUIDs v5 do URL espaço para nome. RFC 9562 define quatro namespaces predefinidos: por DNS nome, por URL, por OIDe por X.500 nome distinto. As organizações podem criar seu próprio namespace gerando um v4 UUID.
MD5 na v3 e SHA-1 na v5 — por que um hash enfraquecido é aceitável aqui, já que o ID não é um controle de segurança
A versão 3 usa MD5 e a versão 5 usa SHA-1, escolhas que datam de suas datas de especificação e implementações disponíveis. Para UUIDs baseados em nomes, esta distinção é irrelevante porque a função hash não é um limite de segurança ou controle criptográfico. O UUID não está provando autenticidade ou integridade; é simplesmente converter uma string de comprimento variável em um valor fixo de 128 bits. O modelo de ataque é irrelevante porque os UUIDs são armazenados e comparados como valores opacos, não como provas ou controles de segurança. Novas implementações devem usar v5 (SHA-1) em vez de v3 (MD5), não por razões de segurança convincentes, mas porque v5 é o padrão moderno e amplamente disponível.
Os namespaces predefinidos — DNS, URL, OID e X.500, e quando criar o seu próprio
RFC 9562 especifica exatamente quatro UUIDs de namespace predefinidos com representações de bytes específicas: 6ba7b810-9dad-11d1-80b4-00c04fd430c8 para DNS, 6ba7b811-9dad-11d1-80b4-00c04fd430c8 para URLs, 6ba7b812-9dad-11d1-80b4-00c04fd430c8 para OIDs e 6ba7b814-9dad-11d1-80b4-00c04fd430c8 para X.500 nomes distintos. Um UUID v5 derivado do namespace DNS e o nome www.example.com sempre serão idênticos e nunca colidirão com um UUID v5 do namespace URL. O uso de um namespace predefinido garante a interoperabilidade: se várias equipes usarem v5 de forma independente com o namespace DNS, elas gerarão UUIDs idênticos para os mesmos nomes DNS. Escolher ou cunhar um namespace faz parte do design do esquema.
Exemplo resolvido - derivando um UUID v5 conceitualmente do namespace URL e um registro URL, passo a passo
Derive um v5 UUID conceitualmente do namespace URL e do nome https://example.com/api/users/42. O namespace UUID como 16 bytes é 6b a7 b8 11 9d ad 11 d1 80 b4 00 c0 4f d4 30 c8. O nome é a string UTF-8 https://example.com/api/users/42, que é 30 bytes. Concatene os bytes do namespace (16) e os bytes do nome (30) para obter o total de 46 bytes. Calcule o hash SHA-1, produzindo um hash de 20 bytes. Pegue o primeiro 16 bytes e interprete-os como um UUID com o nibble da versão definido como 5 e os bits variantes definidos como o padrão RFC. Computá-lo novamente com entradas idênticas produz o resultado idêntico. A maioria dos desenvolvedores usa sua biblioteca de linguagem UUID para calcular a v5.
Onde o padrão quebra — quando os nomes mudam, quando o namespace é inconsistente entre as equipes e quando as entradas são secretas
Os UUIDs baseados em nome assumem que o nome é estável e consistente em todos os sistemas e execuções de importação. Se o mesmo registro externo tiver nomes diferentes em sistemas diferentes, a geração de v5 a partir de cada nome produzirá UUIDs diferentes e não conseguirá identificar a mesma pessoa. Se um namespace não for acordado entre as equipes (cada equipe criando seu próprio namespace para o que na verdade é a mesma fonte), elas geram UUIDs diferentes e não conseguem corresponder aos registros. Se a entrada for dados confidenciais, gerar um UUID v5 significa que UUID é um valor público e determinístico que qualquer pessoa pode consultar se conhecer as entradas. O determinismo é interrompido quando as entradas mudam ou as definições de namespace são inconsistentes.
O que isso não cobre - o gerador ToolAcre extrai do CSPRNG, portanto, IDs baseados em nomes precisam da biblioteca UUID do seu idioma
ToolAcre gera apenas UUIDs v4, extraídos do gerador criptograficamente seguro do navegador para independência. A derivação UUID baseada em nome requer sua biblioteca UUID de linguagem ou uma implementação que calcule SHA-1 e formate o resultado corretamente. Esta postagem explica o conceito e os casos de uso; implementar a geração v5 é simples em qualquer linguagem com acesso a bibliotecas criptográficas padrão. A mecânica da derivação v5 é simples; o desafio é integrá-lo a um esquema de sistema onde o namespace seja estável, o nome seja consistente e a abordagem seja bem documentada para sua equipe. As equipes de desenvolvimento devem documentar as escolhas de namespace.
Conclusão: determinístico quando necessário, aleatório caso contrário - use v5 para mapeamentos estáveis e o gerador ToolAcre para tudo que deveria ser indescritível
Use v5 para mapeamentos estáveis entre identificadores externos e seus registros internos. O determinismo evita importações duplicadas e torna a correspondência de registros entre sistemas simples e confiável. Não use UUIDs baseados em nomes para identificadores que precisam ser indecifráveis ou para cenários que exijam forte confidencialidade e segredos. ToolAcre gera UUIDs v4 aleatórios para identificadores que devem ser independentes e distintos sem previsibilidade. Quando seus sistemas precisam de IDs determinísticos que mapeiam entradas para identificadores fixos, sua biblioteca de linguagem UUID pode calculá-los. O determinismo é um recurso poderoso quando você controla a entrada.