Generatore UUID v3

Cos'è UUID v3?

UUID v3 è una versione UUID basata su nome definita in RFC 4122. Invece di dati casuali o un timestamp, deriva l'UUID deterministicamente da due input: un UUID namespace e una stringa nome. La coppia namespace + nome è hashata con MD5, e l'hash risultante è formattato come UUID.

La proprietà chiave di UUID v3 è il determinismo: lo stesso namespace e nome produrranno sempre l'UUID identico, su qualsiasi macchina, in qualsiasi momento. Questo lo rende adatto al content-addressing — generare identificatori stabili per risorse identificate da un nome significativo.

UUID v3 usa MD5 come funzione hash. MD5 è considerato crittograficamente compromesso per scopi di sicurezza, motivo per cui UUID v5 (che usa SHA-1) è generalmente preferito per il nuovo sviluppo. Né v3 né v5 forniscono casualità — sono puramente deterministici.

Namespace standard

RFC 4122 definisce quattro UUID di namespace pre-assegnati. Usare un namespace standard garantisce l'interoperabilità — due implementazioni indipendenti produrranno lo stesso UUID v3 per lo stesso nome nello stesso namespace:

È possibile usare anche qualsiasi UUID arbitrario come namespace personalizzato — per esempio, un UUID v4 generato una volta e incorporato nell'applicazione come costante. Questo permette di creare un namespace privato per i propri mapping nome-verso-UUID.

UUID v3 vs UUID v5

UUID v3 e UUID v5 sono strutturalmente identici — entrambi sono UUID deterministici basati su nome. L'unica differenza è la funzione hash:

Preferire UUID v5 a UUID v3 per tutto il nuovo sviluppo. L'hash SHA-1 è più forte di MD5 e la differenza di prestazioni è trascurabile. Usare UUID v3 solo quando si devono riprodurre UUID da un sistema che lo usa già.

Quando usare UUID v3

UUID v3 (e v5) sono appropriati quando si ha bisogno di un identificatore stabile e riproducibile derivato da un nome significativo — piuttosto che un ID casuale che deve essere memorizzato e cercato:

Capire il determinismo

Il determinismo di UUID v3 è sia il suo punto di forza maggiore che il suo vincolo più importante. Dato qualsiasi UUID namespace e qualsiasi stringa nome, l'UUID di output è completamente fisso — non è coinvolta nessuna casualità. Ciò significa:

Produce sempre: 9073926b-929f-31c2-abc9-fad77ae3e8eb

Se un attaccante conosce il namespace e può indovinare il nome, può calcolare l'UUID in anticipo. I valori UUID v3 non dovrebbero mai essere usati come token imprevedibili, ID di sessione o segreti. Usare UUID v4 per qualsiasi identificatore sensibile alla sicurezza.

Esempi di codice

UUID v3 richiede un UUID namespace e una stringa nome. Usare il pacchetto standard 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)
}

Domande Frequenti