Module zuuid

RFC-4122 UUID generator and manipulator.

See also: zuuid:config/1, zuuid:start/0.

Description

RFC-4122 UUID generator and manipulator.

This is the interface module and application file for zUUID. To generate version 1 or 2 UUIDs the uuid application must be started by calling zuuid:start/0 first. After the application is started zuuid:config/1 can be used to set arbitrary state values on the state manager like the node/MAC address, POSIX IDs, and so on.

Data Types

clock_seq()

clock_seq() = non_neg_integer()

Becomes <<_:14>>.

ieee802mac()

ieee802mac() = <<_:48>>

local_id()

local_id() = non_neg_integer()

Becomes <<_:8>>.

namespace()

namespace() = nil | url | dns | oid | x500

posix_id()

posix_id() = non_neg_integer()

Becomes <<_:32>>.

uuid()

uuid() = {uuid, <<_:128>>}

Function Index

binary/1Equivalent to zuuid:binary(UUID, standard).
binary/2 Accept an internal UUID representation, and return a canonical binary string representation in one of three formats, or raw bits as an Erlang term.
config/1 Allows zuuid application to be configured after startup with any desired values that would affect generation of version 1 or 2 UUIDs (versions 3, 4 and 5 do not use system state information to generate their result).
nil/0 Generate an RFC 4122 nil UUID.
randomize/1 A convenience function to compliment config/1 that randomizes any attribute of the uuid_man processes (the state manager for version 1 and 2 UUID generators).
read_mac/1 Takes a serialized representation of an IEEE 802 MAC address in a variety of formats and returns an internalized representation (currently a 48-bit binary) or the atom 'bad_mac' in the case of malformed input.
read_uuid/1 Takes serialized representation of a UUID/GUID in a variety of formats and returns an internalized representation or the atom 'bad_uuid' in the case of malformed input.
start/0 Starts the zuuid application, spawning a supervisor and a worker to manage state generation details for version 1 and 2 UUIDs and ensure duplicates will not occur even at high call frequencies (as suggested in RFC 4122, 4.2.1).
stop/0 Stops the zuuid application.
string/1Equivalent to zuuid:string(UUID, standard).
string/2 Accept an internal UUID representation and return a canonical string representation in one of three formats, or a string of 0's and 1's representing each bit of the 128-bit value.
v1/0 Generate an RFC 4122 version 1 UUID.
v2/0 Generate an RFC 4122 version 2 (DEC Security) UUID with current ID values.
v2/2 Generate an RFC 4122 version 2 (DEC Security) UUID with custom ID values.
v3/1Equivalent to v3(nil, Name).
v3/2 Generate an RFC 4122 version 3 UUID (md5 hash).
v3rand/1Equivalent to zuuid:v3(crypto:strong_rand_bytes(16), Name).
v4/0 Generate an RFC 4122 version 4 UUID (strongly random UUID).
v5/1Equivalent to v5(nil, Name).
v5/2 Generate an RFC 4122 version 5 UUID (truncated sha1 hash).
v5rand/1 Generate an RFC 4122 version 5 UUID (truncated sha1 hash) with a random namespace.
version/1 Determine the variant and version of a UUID.

Function Details

binary/1

binary(UUID::uuid()) -> binary()

Equivalent to zuuid:binary(UUID, standard).

binary/2

binary(UUID, Format) -> Serialized

Accept an internal UUID representation, and return a canonical binary string representation in one of three formats, or raw bits as an Erlang term.

For example:
  1> zuuid:binary(zuuid:read_uuid("6BA7B810-9DAD-11D1-80B4-00C04FD430C8"), standard).
  <<"6BA7B810-9DAD-11D1-80B4-00C04FD430C8">>
  2> zuuid:binary(zuuid:read_uuid("6BA7B810-9DAD-11D1-80B4-00C04FD430C8"), brackets).
  <<"{6BA7B810-9DAD-11D1-80B4-00C04FD430C8}">>
  3> zuuid:binary(zuuid:read_uuid("6BA7B810-9DAD-11D1-80B4-00C04FD430C8"), no_break).
  <<"6BA7B8109DAD11D180B400C04FD430C8">>
  4> zuuid:binary(zuuid:read_uuid("6BA7B810-9DAD-11D1-80B4-00C04FD430C8"), raw_bits).
  <<107,167,184,16,157,173,17,209,128,180,0,192,79,212,48,200>>

config/1

config(Value) -> Result

Allows zuuid application to be configured after startup with any desired values that would affect generation of version 1 or 2 UUIDs (versions 3, 4 and 5 do not use system state information to generate their result).

Accepts a value of {node, bad_mac} to permit compositions of the following form without crashing the state management process on bad input:
  zuuid:config({node, zuuid:read_mac(SomeString)})

See also: zuuid:read_mac/1.

nil/0

nil() -> uuid()

Generate an RFC 4122 nil UUID.

randomize/1

randomize(Attribute) -> ok

A convenience function to compliment config/1 that randomizes any attribute of the uuid_man processes (the state manager for version 1 and 2 UUID generators).

read_mac/1

read_mac(Input) -> Result

Takes a serialized representation of an IEEE 802 MAC address in a variety of formats and returns an internalized representation (currently a 48-bit binary) or the atom 'bad_mac' in the case of malformed input.

Given a MAC "12:34:56:78:90:AB", acceptable input representations are:
  "12:34:56:78:90:AB"
  "12-34-56-78-90-ab"
  "12.34.56.78.90.ab"
  "1234567890AB"
  <<"12:34:56:78:90:ab">>
  <<"12-34-56-78-90-AB">>
  <<"12.34.56.78.90.ab">>
  <<"1234567890ab">>

64-bit hardware addresses (EUI-64 addresses) are also accepted, but are adjusted to 48-bit length before being returned as a MAC. In the case of MAC-48 or EUI-48 to EUI-64 address conversion, the original MAC-48/EUI-48 address is returned. In the case of assembled EUI-64 or native EUI-64 bit addresses, the last two bytes are truncated.

MAC-48/EUI-48 "12-34-56-78-90-AB" to EUI-64:
  "12-34-56-FF-FE-78-90-AB"
  "123456fffe7890ab"
  <<18,52,86,255,254,120,144,171>>

Returns: <<18,52,86,120,144,171>>

Native EUI-64:
  "12-34-56-78-90-AB-CD-EF"
  "1234567890abcdef"
  <<18,52,86,120,144,171,205,239>>

Returns: <<18,52,86,120,144,171>>

Hexadecimal "letter" values are not case sensitive.

read_uuid/1

read_uuid(Input) -> Result

Takes serialized representation of a UUID/GUID in a variety of formats and returns an internalized representation or the atom 'bad_uuid' in the case of malformed input.

Given a UUID "6ba7b810-9dad-11d1-80b4-00c04fd430c8", acceptable input representations are:
  "{6ba7b810-9dad-11d1-80b4-00c04fd430c8}"
  "6ba7b810-9dad-11d1-80b4-00c04fd430c8"
  "{6BA7B8109DAD11D180B400C04FD430C8}"
  "6ba7b8109dad11d180b400c04fd430c8"
  <<"{6ba7b810-9dad-11d1-80b4-00c04fd430c8}">>
  <<"6BA7B810-9DAD-11D1-80B4-00C04FD430C8">>
  <<"{6BA7B8109DAD11D180B400C04FD430C8}">>
  <<"6ba7b8109dad11d180b400c04fd430c8">>
  {uuid,<<107,167,184,16,157,173,17,209,128,180,0,192,79,212,48,200>>}
  <<107,167,184,16,157,173,17,209,128,180,0,192,79,212,48,200>>
Hexadecimal "letter" values are not case sensitive.

start/0

start() -> ok

Starts the zuuid application, spawning a supervisor and a worker to manage state generation details for version 1 and 2 UUIDs and ensure duplicates will not occur even at high call frequencies (as suggested in RFC 4122, 4.2.1).

It is not necessary to start the application for UUID versions 3, 4 or 5 (versions 3 and 5 are actually pure functions, while 4 has only the side effect of calling crypto:strong_rand_bytes/1).

stop/0

stop() -> ok

Stops the zuuid application.

string/1

string(UUID::uuid()) -> string()

Equivalent to zuuid:string(UUID, standard).

string/2

string(UUID, Format) -> Serialized

Accept an internal UUID representation and return a canonical string representation in one of three formats, or a string of 0's and 1's representing each bit of the 128-bit value.

For example:
  1> zuuid:string(zuuid:read_uuid(<<"6BA7B810-9DAD-11D1-80B4-00C04FD430C8">>), standard).
  "6BA7B810-9DAD-11D1-80B4-00C04FD430C8"
  2> zuuid:string(zuuid:read_uuid(<<"6BA7B810-9DAD-11D1-80B4-00C04FD430C8">>), brackets).
  "{6BA7B810-9DAD-11D1-80B4-00C04FD430C8}"
  3> zuuid:string(zuuid:read_uuid(<<"6BA7B810-9DAD-11D1-80B4-00C04FD430C8">>), no_break).
  "6BA7B8109DAD11D180B400C04FD430C8"
  4> zuuid:string(zuuid:read_uuid(<<"6BA7B810-9DAD-11D1-80B4-00C04FD430C8">>), raw_bits).
  "01101011101001111011100000010000100111011010110100010001110100011000000010110100000000001100000001001111110101000011000011001000"

v1/0

v1() -> uuid()

Generate an RFC 4122 version 1 UUID.

This function requires that the zuuid application be started before being called. The process zuuid_man maintains a record of UUID generation and implements measures to ensure that generation on very fast systems will not produce duplicate clock-based UUIDs by mistake.

The UUIDs generated by this function are based on the state of the generator process at the time it is called. The state (MAC address, clock sequence, etc.) can be updated by calling config/1.

v2/0

v2() -> uuid()

Generate an RFC 4122 version 2 (DEC Security) UUID with current ID values.

This function requires that the zuuid application be started before being called. The process zuuid_man maintains a record of UUID generation and implements measures to ensure that generation on very fast systems will not produce duplicate clock-based UUIDs by mistake.

DEC Security UUID generation is not explicitly referenced in RFC 4122, but the process is similiar to version 1 UUIDs with the exception that some clock and clock sequence bits are replaced with Posix user and local/group ID data. The UUIDs generated by this function are based on the state of the generator process at the time it is called. The state (MAC address, Posix user and local/group IDs, clock sequence, etc.) can be updated by calling config/1.

v2/2

v2(PosixID::posix_id(), LocalID::local_id()) -> uuid()

Generate an RFC 4122 version 2 (DEC Security) UUID with custom ID values.

This function requires that the zuuid application be started before being called.

This function is like v2/0, but allows supplying the Posix ID values without reconfiguring the UUID generator process.

v3/1

v3(Name::iodata()) -> uuid()

Equivalent to v3(nil, Name).

v3/2

v3(Prefix, Name) -> uuid()

Generate an RFC 4122 version 3 UUID (md5 hash).

This function provides atom values for RFC 4122 appendix C namespaces, a nil namespace (direct hash over single argument), and any arbitrary namespace.

Calling v3(Name) is the same as calling v3(nil, Name).

v3rand/1

v3rand(Name::iodata()) -> uuid()

Equivalent to zuuid:v3(crypto:strong_rand_bytes(16), Name).

v4/0

v4() -> uuid()

Generate an RFC 4122 version 4 UUID (strongly random UUID).

This function calls crypto:strong_rand_bytes/1. There is a very small chance the call could fail with an exception low_entropy if your program calls it at very high speed and your systems random device cannot keep up. So far in testing on Linux and BSD this has not been a problem, even generating hundreds of thousands of UUIDs to populate a database, but it could happen. If this call fails the caller will crash if it does not catch the exception.

v5/1

v5(Name::iodata()) -> uuid()

Equivalent to v5(nil, Name).

v5/2

v5(Prefix, Name) -> uuid()

Generate an RFC 4122 version 5 UUID (truncated sha1 hash).

This function provides atom values for RFC 4122 appendix C namespaces, a nil namespace (direct hash over single argument), and any arbitrary namespace.

v5rand/1

v5rand(Name::iodata()) -> uuid()

Equivalent to zuuid:v5(crypto:strong_rand_bytes(16), Name).

Generate an RFC 4122 version 5 UUID (truncated sha1 hash) with a random namespace.

version/1

version(UUID) -> VarVer

Determine the variant and version of a UUID.

Currently detects only RFC-4122 defined variant/versions. Some homespun or wildly non-compliant 128-bit identifier values can incidentally appear to comply with RFC-4122, so not all arguments are guaranteed to return an accurate result.

(Noncompliant values can be used by the rest of this module, though).

Returns the atom 'bad_uuid' on non-UUID values, so composition with read_uuid/1 will return sane values on bad external input.


Generated by EDoc