Generator UUID v3

Czym jest UUID v3?

UUID v3 to wersja UUID oparta na nazwach zdefiniowana w RFC 4122. Zamiast losowych danych lub znacznika czasu, wyprowadza UUID deterministycznie z dwóch danych wejściowych: UUID przestrzeni nazw i ciągu nazwy. Para przestrzeń nazw + nazwa jest hashowana przy użyciu MD5, a wynikowy skrót jest formatowany jako UUID.

Kluczową właściwością UUID v3 jest determinizm: ta sama przestrzeń nazw i nazwa zawsze wyprodukuje identyczny UUID, na dowolnej maszynie, w dowolnym czasie. To czyni go odpowiednim do adresowania treści — generowania stabilnych identyfikatorów dla zasobów identyfikowanych przez znaczącą nazwę.

UUID v3 używa MD5 jako funkcji skrótu. MD5 jest uważany za kryptograficznie zepsuty dla celów bezpieczeństwa, dlatego UUID v5 (który używa SHA-1) jest generalnie preferowany dla nowego rozwoju. Ani v3, ani v5 nie zapewnia żadnej losowości — są czysto deterministyczne.

Standardowe przestrzenie nazw

RFC 4122 definiuje cztery wstępnie przypisane UUID przestrzeni nazw. Używanie standardowej przestrzeni nazw zapewnia interoperacyjność — dwie niezależne implementacje wyprodukują ten sam UUID v3 dla tej samej nazwy w tej samej przestrzeni nazw:

Możesz również użyć dowolnego UUID jako niestandardowej przestrzeni nazw — na przykład UUID v4, który generujesz raz i osadzasz w swojej aplikacji jako stałą. Pozwala to tworzyć prywatną przestrzeń nazw dla własnych mapowań nazwa-do-UUID.

UUID v3 a UUID v5

UUID v3 i UUID v5 są strukturalnie identyczne — oba są deterministycznymi, opartymi na nazwach UUID. Jedyna różnica to funkcja skrótu:

Preferuj UUID v5 nad UUID v3 dla całego nowego rozwoju. Skrót SHA-1 jest silniejszy niż MD5, a różnica wydajności jest pomijalnie mała. Używaj UUID v3 tylko wtedy, gdy musisz odtworzyć UUID z systemu, który już go używa.

Kiedy używać UUID v3

UUID v3 (i v5) są odpowiednie, gdy potrzebujesz stabilnego, odtwarzalnego identyfikatora wywodzącego się ze znaczącej nazwy — zamiast losowego identyfikatora, który musi być przechowywany i wyszukiwany:

Zrozumienie determinizmu

Determinizm UUID v3 jest zarówno jego największą siłą, jak i najważniejszym ograniczeniem. Dla dowolnego UUID przestrzeni nazw i dowolnego ciągu nazwy wyjściowy UUID jest całkowicie stały — nie jest zaangażowana żadna losowość. Oznacza to:

Zawsze produkuje: 9073926b-929f-31c2-abc9-fad77ae3e8eb

Jeśli atakujący zna przestrzeń nazw i może odgadnąć nazwę, może z góry obliczyć UUID. Wartości UUID v3 nigdy nie powinny być używane jako nieprzewidywalne tokeny, identyfikatory sesji ani sekrety. Użyj UUID v4 dla każdego identyfikatora wrażliwego na bezpieczeństwo.

Przykłady kodu

UUID v3 wymaga UUID przestrzeni nazw i ciągu nazwy. Użyj standardowego pakietu 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)
}

Często zadawane pytania