UUIDv47Sharp

English | Japanese

This library provides functionality to convert between UUIDv7—which includes timestamp information and supports sorting—and a cryptographically encrypted "facade" UUID that appears random.

This enables using efficient UUIDv7 internally in databases while publicly exposing IDs that cannot be inferred to include generation timestamps or other information, effectively balancing both privacy and performance.

This library is a port of stateless-me/uuidv47 to the C#/.NET ecosystem.

What's this?

This library provides a deterministic and reversible conversion method between UUIDv7 and IDs that appear random, such as UUIDv4.

The mechanism works by applying an XOR mask exclusively to the timestamp portion of UUIDv7 to obfuscate the timestamp information. This XOR mask is generated using a reversible cryptographic algorithm called SipHash-2-4 stream, which is tied to the random bit portion of the UUID itself. This approach ensures that while the converted IDs conceal the timestamp information, they maintain a one-to-one correspondence with the original UUIDv7, allowing them to be converted back and forth at any time.

Installation

You can install it into your project from NuGet.

> dotnet add package UUIDv47Sharp

Usage

using UUIDv47Sharp;

var key = new Key(0x0123456789abcdef, 0xfedcba9876543210);
// Or generate a random key:
// var key = Key.NewRandom();

// Parse a UUIDv7
// (e.g., from your database)
var v7 = Uuid.Parse("018f2d9f-9a2a-7def-8c3f-7b1a2c4d5e6f");
// Or can also be converted from a .NET GUID structure
// var v7 = guid.ToUuid();

// Encode to facade (v4-like) for external use
var facade = Uuid47Codec.Encode(v7, key);
Console.WriteLine($"ExternalID: {facade}");
// Output: External ID: 2463c780-7fca-4def-8c3f-7b1a2c4d5e6f

// Decode back to original v7 for internal use
var decoded = Uuid47Codec.Decode(facade, key);
Console.WriteLine($"InternalID: {decoded}");
// Output: Internal ID: 018f2d9f-9a2a-7def-8c3f-7b1a2c4d5e6f

Principles

Preservation of random bits: The 74-bit random component of UUIDv7 is completely retained and remains unchanged after the transformation.
Timestamp masking: The 48-bit timestamp portion is masked (encrypted) through XOR operation with the keystream generated by SipHash-2-4.
Key derivation: The key used for masking is deterministically derived from the random bit portion of the UUID itself.
RFC compliance: Both the ID before and after transformation maintain proper version and variant bits to comply with UUID specifications.

Through this approach, the transformation offers the following key advantages:

Deterministic: Given the same UUIDv7 input, the exact same facade will always be produced.
Reversible: The facade can be reverse-transformed back to the original UUIDv7 using a secret key.
Secure: The SipHash-2-4 algorithm provides cryptographic security against attempts to deduce the secret key or original timestamp from the facade.

Security Tips

Carefully safeguard the key used for modification. This key will be used when reversing the conversion to UUIDv7.
The generated UUIDv4-like output only encrypts the timestamp portion; the random bits remain unprotected.
For UUIDv7 generation, use a sufficiently secure algorithm and library.

Security

If you discover any security vulnerabilities in this software, please DO NOT create an issue or pull request. Instead, please report it using one of the following methods:

Submit a report to our Security Advisory page on GitHub
Contact us directly at taiseiue@wsnet.jp (you can obtain our PGP key from OpenPGP)

If an issue related to a security vulnerability is created, we will accept the report but subsequently delete the associated issue.

Credits & Supports

This is a C# implementation of the highly efficient UUID generation library stateless-me/uuidv47 developed by Stateless Limited. We also referenced the Go language implementation n2p5/uuid47 of uuidv47 for implementation guidance.

This project receives support from GMO FlattSecurity's “GMO Open Source Developer Support Program” and regularly conducts security assessments using “Takumi byGMO.”

I'd be grateful if you could support this project!

License

This software is released under the The MIT License.

taiseiue/UUIDv47Sharp