NAME¶

UUID - Universally Unique Identifier library for Perl

SYNOPSIS¶

    # SIMPLE
    use UUID qw(uuid);    # see EXPORTS
    my $str = uuid();     # generate version 4 UUID string
    # SPECIFIC
    $str = uuid1();                   # new version 1 UUID string
    $str = uuid4();                   # new version 4 UUID string
    $str = uuid6();                   # new version 6 UUID string
    $str = uuid7();                   # new version 7 UUID string
    # NAMESPACE is 'dns', 'url', 'oid', or 'x500'; case-insensitive.
    $str = uuid3(dns => 'www.example.com');
    $str = uuid5(url => 'https://www.example.com/foo.html');
    UUID::generate_v1($bin);          # new version 1 binary UUID
    UUID::generate_v4($bin);          # new version 4 binary UUID
    UUID::generate_v6($bin);          # new version 6 binary UUID
    UUID::generate_v7($bin);          # new version 7 binary UUID
    UUID::generate_v3($bin, dns => 'www.example.com');
    UUID::generate_v5($bin, url => 'https://www.example.com/foo.txt');
    UUID::generate($bin);             # alias for generate_v1()
    UUID::generate_time($bin);        # alias for generate_v1()
    UUID::generate_random($bin);      # alias for generate_v4()
    UUID::unparse($bin, $str);        # stringify $bin; prefer lowercase
    UUID::unparse_lower($bin, $str);  # force lowercase stringify
    UUID::unparse_upper($bin, $str);  # force uppercase stringify
    UUID::parse($str, $bin);          # map string to binary UUID
    UUID::compare($bin1, $bin2);      # compare binary UUIDs
    UUID::copy($dst, $src);           # copy binary UUID from $src to $dst
    UUID::clear($bin);                # set binary UUID to NULL
    UUID::is_null($bin);              # compare binary UUID to NULL
    UUID::time($bin);                 # return UUID time
    UUID::type($bin);                 # return UUID type
    UUID::variant($bin);              # return UUID variant
    UUID::version($bin);              # return UUID version

DESCRIPTION¶

The UUID library is used to generate unique identifiers for objects that may be accessible beyond the local system. For instance, they could be used to generate unique HTTP cookies across multiple web servers without communication between the servers, and without fear of a name clash.

The generated UUIDs can be reasonably expected to be unique within a system, and unique across all systems, and are compatible with those created by the Open Software Foundation (OSF) Distributed Computing Environment (DCE).

All generated UUIDs are either version 1, 3, 4, 5, 6, or version 7. And all are variant 1, meaning compliant with the OSF DCE standard as described in RFC4122.

Versions 6 and 7 are not standardized. They are presented here as proposed in RFC4122bis, version 14, and may change in the future. RFC4122bis is noted to replace RFC4122, if approved.

FUNCTIONS¶

Most of the UUID functions expose the historically underlying libuuid C interface rather directly. That is, many return their values in their parameters and nothing else.

Not very Perlish, but it's been like that for a long time so not likely to change any time soon.

All take or return UUIDs in either binary or string format. The string format resembles the following:

    21b081a3-de83-4480-a14f-e89a1dcf8f0f

Or, in terms of printf(3) format:

    "%08x-%04x-%04x-%04x-%012x"

The binary form is simply a packed 16 byte binary value.

    0  NCS
    1  DCE
    2  Microsoft
    3  Other

    v1  date/time and node address
    v2  date/time and node address, security version
    v3  namespace based, MD5 hash
    v4  random
    v5  namespace based, SHA-1 hash
    v6  reverse date/time and node address
    v7  reverse unix date/time and random
    v8  custom

MAINTAINING STATE¶

Internal state is optionally maintained for timestamped UUIDs (versions 1, 6, and 7) via a file designated by the :persist export tag. See EXPORTS for details.

The file records various internal states at the time the last UUID is generated, preventing future instances from overlapping the prior UUID sequence. This allows the sequence to absolutely survive reboots and, more importantly, backwards resetting of system time.

If :persist is not used, time resets will still be detected while the module is loaded and handled by incrementing the UUID clock_seq field. The clock_seq field is randomly initialized in this case anyway, so the chance of overlap is low but still exists since clock_seq is only 14 bits wide. Using a random MAC will help (see :mac in EXPORTS), adding an additional 48 bits of randomness.

NOTE: Using :persist incurs a serious performance penalty, in excess of 95% on tested platforms. You can run "make compare" in the distribution directory to see how this might affect your application, but unless you need many thousands of UUIDs/sec it's probably a non-issue.

RANDOM NUMBERS¶

Versions 4 and 7 UUIDs are partially filled with random numbers, as well as versions 1 and 6 when used with the :mac option.

Prior to version 0.33, UUID obtained randomness from the system's /dev/random device, or similar interface. On some platforms it called getrandom() and on others it read directly from /dev/urandom. And of course, Win32 did something completely different.

Starting in 0.33, UUID generates random numbers itself using the ChaCha20 algorithm which is considered crypto-strength in most circles. This is the same algo used as the basis for many modern kernel RNGs, albeit without the same entropy gathering ability.

To compensate, UUID mixes the output from ChaCha with output from another RNG, Xoshiro. The idea is that by mixing the two, the true output from either is effectively hidden, making discovery of either's key much more unlikely than it already is. And without the keys, you can't predict the future.

Well, that's the theory anyway.

NAMESPACES¶

Versions 3 and 5 generate UUIDs within namespaces. What this really means is that the NAME value is concatenated with a dedicated NAMESPACE UUID before hashing.

Available namespaces and UUIDs:

    dns   6ba7b810-9dad-11d1-80b4-00c04fd430c8
    url   6ba7b811-9dad-11d1-80b4-00c04fd430c8
    oid   6ba7b812-9dad-11d1-80b4-00c04fd430c8
    x500  6ba7b814-9dad-11d1-80b4-00c04fd430c8

For example, if you need to create some UUIDs within your own "questions" and "answers" namespaces using SHA1:

    $ns_base = uuid5( dns => 'www.example.com' );
    $ns_questions = uuid5( $ns_base, 'questions' );
    $ns_answers   = uuid5( $ns_base, 'answers'   );
    for $topic ( next_qa_aref() ) {
        ($q, $a) = @$topic;
        $uuid_question = uuid5( $ns_questions, $q );
        $uuid_answer   = uuid5( $ns_answers,   $a );
        ...
    }

This way, you can deterministically convert existing (and likely colliding) namespaces over to one UUID namespace, which is often useful when merging datasets.

You also don't need to publish your base and namespace UUIDs. Anyone using the same logic can generate the same question and answer UUIDs.

EXPORTS¶

None by default. All functions may be imported in the usual manner, either individually or all at once using the :all tag.

Beware that importing :all clobbers Perl's time(), not to mention a few other commonly used subs, like copy() from File::Copy.

THREAD SAFETY¶

This module is believed to be thread safe.

UUID LIBRARY¶

Releases prior to UUID-0.32 required libuuid or similar be installed first. This is no longer the case. Version 0.33 bundled the e2fsprogs UUID code, and version 0.34 removed it altogether.

BENCHMARKS¶

There are a few benchmarks in the distribution ubin directory which can be run either standalone or through the Makefile.

COPYRIGHT AND LICENSE¶

This software is Copyright (c) 2014-2024 by Rick Myers.

This is free software, licensed under:

  The Artistic License 2.0 (GPL Compatible)

Details of this license can be found within the 'LICENSE' text file.

AUTHOR¶

Current maintainer:

  Rick Myers <jrm@cpan.org>.

Authors and/or previous maintainers:

  Lukas Zapletal <lzap@cpan.org>
  Joseph N. Hall <joseph.nathan.hall@gmail.com>
  Colin Faber <cfaber@clusterfs.com>
  Peter J. Braam <braam@mountainviewdata.com>

CONTRIBUTORS¶

David E. Wheeler

William Faulk

gregor herrmann

Slaven Rezic

twata

Christopher Rasch-Olsen Raa

Petr Pisar

SEE ALSO¶

RFC4122 - <https://www.rfc-editor.org/rfc/rfc4122>

RFC4122bis - <https://www.ietf.org/archive/id/draft-ietf-uuidrev-rfc4122bis-14.html>

perl(1).