Gerador UUID v3

O que é UUID v3?

UUID v3 é uma versão UUID baseada em nome definida no RFC 4122. Em vez de dados aleatórios ou um timestamp, ela deriva o UUID deterministicamente a partir de duas entradas: um UUID de namespace e uma string de nome. O par namespace + nome é hasheado usando MD5, e o hash resultante é formatado como UUID.

A propriedade chave do UUID v3 é o determinismo: o mesmo namespace e nome sempre produzirão o UUID idêntico, em qualquer máquina, a qualquer momento. Isso o torna adequado para endereçamento de conteúdo — gerando identificadores estáveis para recursos que são identificados por um nome significativo.

UUID v3 usa MD5 como função hash. MD5 é considerado criptograficamente quebrado para fins de segurança, razão pela qual UUID v5 (que usa SHA-1) é geralmente preferido para novo desenvolvimento. Nem v3 nem v5 fornecem aleatoriedade — eles são puramente determinísticos.

Namespaces Padrão

RFC 4122 define quatro UUIDs de namespace pré-atribuídos. Usar um namespace padrão garante interoperabilidade — duas implementações independentes produzirão o mesmo UUID v3 para o mesmo nome dentro do mesmo namespace:

Você também pode usar qualquer UUID arbitrário como namespace personalizado — por exemplo, um UUID v4 que você gera uma vez e incorpora em sua aplicação como constante. Isso permite criar um namespace privado para seus próprios mapeamentos de nome para UUID.

UUID v3 vs UUID v5

UUID v3 e UUID v5 são estruturalmente idênticos — ambos são UUIDs determinísticos baseados em nome. A única diferença é a função hash:

Prefira UUID v5 a UUID v3 para todo novo desenvolvimento. O hash SHA-1 é mais forte que MD5, e a diferença de desempenho é insignificante. Use UUID v3 apenas quando precisar reproduzir UUIDs de um sistema que já o usa.

Quando Usar UUID v3

UUID v3 (e v5) são apropriados quando você precisa de um identificador estável e reproduzível derivado de um nome significativo — em vez de um ID aleatório que deve ser armazenado e consultado:

Entendendo o Determinismo

O determinismo do UUID v3 é tanto seu maior ponto forte quanto sua restrição mais importante. Dado qualquer UUID de namespace e qualquer string de nome, o UUID de saída é completamente fixo — nenhuma aleatoriedade está envolvida. Isso significa:

Sempre produz: 9073926b-929f-31c2-abc9-fad77ae3e8eb

Se um atacante conhece o namespace e pode adivinhar o nome, ele pode calcular o UUID antecipadamente. Valores UUID v3 nunca devem ser usados como tokens imprevisíveis, IDs de sessão ou segredos. Use UUID v4 para qualquer identificador sensível à segurança.

Exemplos de Código

UUID v3 requer um UUID de namespace e uma string de nome. Use o pacote padrão uuid:

// Browser / Node.js — UUID v3 without dependencies
function uuidV3(namespace, name) {
  // namespace must be a UUID string like '6ba7b810-9dad-11d1-80b4-00c04fd430c8'
  const nsBytes = namespace.replace(/-/g, '').match(/../g).map(h => parseInt(h, 16))
  const nameBytes = [...new TextEncoder().encode(name)]
  const combined = new Uint8Array([...nsBytes, ...nameBytes])

  // md5(combined) — use your preferred MD5 library or the inline implementation
  const hash = md5(combined) // returns Uint8Array(16)
  hash[6] = (hash[6] & 0x0f) | 0x30 // version 3
  hash[8] = (hash[8] & 0x3f) | 0x80 // variant

  const h = [...hash].map(b => b.toString(16).padStart(2, '0')).join('')
  return `${h.slice(0,8)}-${h.slice(8,12)}-${h.slice(12,16)}-${h.slice(16,20)}-${h.slice(20)}`
}

// Using the 'uuid' npm package
import { v3 as uuidv3 } from 'uuid'
const DNS = '6ba7b810-9dad-11d1-80b4-00c04fd430c8'
console.log(uuidv3('example.com', uuidv3.DNS))
// → '9073926b-929f-31c2-abc9-fad77ae3e8eb' (always the same)

import uuid

# Using the standard library
dns_uuid = uuid.uuid3(uuid.NAMESPACE_DNS, 'example.com')
print(dns_uuid)
# → 9073926b-929f-31c2-abc9-fad77ae3e8eb

url_uuid = uuid.uuid3(uuid.NAMESPACE_URL, 'https://example.com/page')
print(url_uuid)

# Custom namespace
MY_NS = uuid.UUID('a1b2c3d4-e5f6-7890-abcd-ef1234567890')
custom = uuid.uuid3(MY_NS, 'my-entity-name')
print(custom)

package main

import (
    "fmt"
    "github.com/google/uuid"
)

func main() {
    // Standard DNS namespace
    ns := uuid.MustParse("6ba7b810-9dad-11d1-80b4-00c04fd430c8")
    id := uuid.NewMD5(ns, []byte("example.com"))
    fmt.Println(id)
    // → 9073926b-929f-31c2-abc9-fad77ae3e8eb

    // URL namespace
    urlNS := uuid.MustParse("6ba7b811-9dad-11d1-80b4-00c04fd430c8")
    idURL := uuid.NewMD5(urlNS, []byte("https://example.com/page"))
    fmt.Println(idURL)
}

Perguntas Frequentes