README.md

IntToUuid: Integer ID To RFC 9562 UUID Converter

Bidirectionally encodes a non-negative 64-bit unsigned "id" integer and optional 32-bit "namespace" integer into a valid RFC 9562 Version 8 UUID. The id and namespace integers are encoded to obscure their value and produce non-sequential UUIDs, while guaranteeing uniqueness and reproducibility.

This could be used to present an auto-incrementing integer "database id" as a UUID (proxy ID) in a public context, where you would not want to expose an enumerable, sequential value directly tied to your database structure/data. Since the encoded UUID can be converted back into integer namespace and id values at runtime, the UUID does not need to be persisted in the database or otherwise indexed to the ID it represents.

Note: The integer ID and namespace values are only encoded in the UUID, not encrypted, and the value can be recovered by a third party with effort. This library is intended to support on-demand conversion between an integer and a UUID, while mitigating basic "user enumeration attacks". Securely encrypting a 64-bit integer in the 122 bits available in a UUID is currently outside the scope of this library.

Installation

cargo add int-to-uuid

Usage

Encode ID with Default Namespace (0) to UUID

use int_to_uuid::{encode, IntegerId};

let id = IntegerId::with_default_namespace(12).unwrap();
let uuid = encode(&id);
println!("{uuid}"); // c81f423b-2ca0-8963-aefa-f067a191123f

Encode ID with Namespace to UUID

use int_to_uuid::{encode, IntegerId};

let id = IntegerId::new(42, 12).unwrap();
let uuid = encode(&id);
println!("{uuid}"); // dee5e9d2-c3e4-8273-b0d5-b3b5307bf749

Decode UUID to ID and Namespace

use int_to_uuid::{decode, IntegerId};

let id: IntegerId = "dee5e9d2-c3e4-8273-b0d5-b3b5307bf749".parse().unwrap();
println!("id: {}", id.id());         // 42
println!("namespace: {}", id.namespace()); // 12

Or using the decode function directly:

use uuid::Uuid;
use int_to_uuid::decode;

let uuid = Uuid::parse_str("dee5e9d2-c3e4-8273-b0d5-b3b5307bf749").unwrap();
let id = decode(&uuid).unwrap();
println!("id: {}, namespace: {}", id.id(), id.namespace()); // id: 42, namespace: 12

Specification

The encoding algorithm is defined in the IntToUuid Specification.

License

This project is licensed under the MIT License. See LICENSE.md for details.