1.0.1

libcuid2 1.0.1 - Initial Public Release

We're excited to announce the first stable release of libcuid2, a high-performance C++ implementation of the Cuid2 specification for generating collision-resistant, sortable unique identifiers.

What is libcuid2?

libcuid2 generates cryptographically strong unique identifiers that are:

• Collision-Resistant: Uses NIST FIPS-202 SHA3-512 hashing with cryptographic random number generation
• Sortable: Contains timestamp components for chronological ordering
• URL-Safe: Base-36 encoded (lowercase alphanumeric)
• Configurable: Lengths from 4-32 characters (default: 24)
• Thread-Safe: Production-ready with comprehensive concurrent access testing

Example IDs:

c9k2l3m4n5o6p7q8r9s0t1u2  (default 24 chars)
a1b2c3d4e5f6g7h8          (custom 16 chars)

Key Features

Production-Ready Implementation

• ✅ Thread-Safe: Atomic counter with 37 test cases covering concurrent access from 10-20 threads
• ✅ Cross-Platform: Windows (MSVC/MinGW), Linux, macOS, FreeBSD, OpenBSD, NetBSD
• ✅ Security-Hardened: Stack protection, fortify source, control flow integrity
• ✅ Standards-Compliant: C++20, NIST FIPS-202, POSIX

Two Ways to Use

1. Command-Line Tool (cuid2gen)

   $ cuid2gen
   c9k2l3m4n5o6p7q8r9s0t1u2
   
   $ cuid2gen -l 16
   a1b2c3d4e5f6g7h8

2. C++ Library

   #include <cuid2/cuid2.hpp>
   
   std::string id = cuid2::generate_cuid2();      // Default 24 chars
   std::string short_id = cuid2::generate_cuid2(16); // Custom length

Comprehensive Documentation

• 📖 Unix Manual Pages: Complete reference documentation (sections 1, 3, 7)
• 📖 Doxygen API Docs: Full inline documentation for all public APIs
• 🌍 Internationalization: Infrastructure ready for 12 languages

Enterprise-Grade Cryptography

• NIST FIPS-202 SHA3-512 via OpenSSL 3.x (FIPS 140-3 validated)
• CSPRNG using OpenSSL RAND_bytes()
• Cross-platform endianness handling with Boost.Endian

Installation

Ubuntu/Debian (PPA - Recommended)

sudo add-apt-repository ppa:xaevik/libcuid2
sudo apt-get update
sudo apt-get install libcuid2-0 libcuid2-dev cuid2gen

Available packages:

• libcuid2-0 - Runtime shared library
• libcuid2-dev - Development headers and CMake config
• cuid2gen - Command-line tool

PPA: https://launchpad.net/~xaevik/+archive/ubuntu/libcuid2

Build from Source

Prerequisites:

# macOS
brew install cmake openssl@3 boost fmt

# Ubuntu/Debian
sudo apt-get install cmake libssl-dev libboost-all-dev libfmt-dev

# Fedora/RHEL
sudo dnf install cmake openssl-devel boost-devel fmt-devel

Build:

# Configure
cmake --preset linux-x64-release

# Build
cmake --build --preset linux-x64-release

# Install
sudo cmake --install build-linux-x64-release

See the README for Windows, BSD, and other platforms.

Platform Support

Platform	Architectures	Status
Linux	x86_64, ARM64	✅ Tested
macOS	x86_64, ARM64 (Apple Silicon)	✅ Tested
Windows	x86_64, ARM64 (MSVC/MinGW)	✅ Tested
FreeBSD	x86_64, ARM64	✅ Supported
OpenBSD	x86_64, ARM64	✅ Supported
NetBSD	x86_64, ARM64	✅ Supported

Usage Examples

CLI Tool

# Generate IDs
cuid2gen
cuid2gen -l 16

# Shell scripts
USER_ID=$(cuid2gen)
echo "Created user: $USER_ID"

C++ Library

#include <cuid2/cuid2.hpp>
#include <iostream>

int main() {
    // Basic usage
    std::string id = cuid2::generate_cuid2();
    std::cout << id << std::endl;

    // Error handling
    try {
        std::string invalid = cuid2::generate_cuid2(64); // Out of range
    } catch (const std::invalid_argument& e) {
        std::cerr << "Error: " << e.what() << std::endl;
    }

    return 0;
}

CMake Integration

find_package(cuid2 REQUIRED)

add_executable(myapp main.cpp)
target_link_libraries(myapp PRIVATE cuid2::cuid2)

Technical Highlights

Algorithm

Cuid2 combines five entropy sources:

1. Random Prefix (a-z) - Ensures valid identifiers
2. Timestamp (Unix epoch) - Enables sortability
3. Atomic Counter - Prevents collisions in rapid generation
4. System Fingerprint - Hostname + PID + environment (hashed)
5. Cryptographic Random - 32 bytes from OpenSSL CSPRNG

All components are hashed with SHA3-512 and encoded as base-36.

Testing

• 37 test cases across 5 test suites
• Thread safety validation (10-20 concurrent threads)
• Uniqueness guarantees (tested up to 50,000 IDs)
• Format validation, boundary testing, edge cases
• Platform abstraction layer tests

Dependencies

All MIT-compatible licenses:

• OpenSSL 3.x (Apache 2.0) - Cryptography
• Boost (BSL 1.0) - Endian, Multiprecision, Nowide, Test
• fmt (MIT) - String formatting

Requirements

• Compiler: C++20 (GCC 10+, Clang 11+, MSVC 2019+)
• CMake: 3.22 or later
• vcpkg: For dependency management (automatic on Windows)

Documentation

• Manual Pages: man cuid2gen, man 3 libcuid2, man 7 libcuid2
• README: Complete documentation
• API Reference: Doxygen comments in all headers
• Packaging: Debian/Ubuntu guide

Contributing

We welcome contributions! See our contributing guidelines and Code of Conduct.

License

MIT License - see LICENSE for details.

Links

• Repository: https://github.com/visus-io/libcuid2
• PPA: https://launchpad.net/~xaevik/+archive/ubuntu/libcuid2
• Issues: https://github.com/visus-io/libcuid2/issues
• Cuid2 Specification: https://github.com/paralleldrive/cuid2

---

Full Changelog: https://github.com/visus-io/libcuid2/commits/1.0.1