baarde/uuid-kit

Swift library for generating and working with UUIDs

UUIDKit

UUIDKit is a Swift library for generating and working with Universally Unique Identifiers (UUIDs) as specified in RFC 4122.

It extends the existing Foundation's UUID type.

Generating UUIDs

The default initializer for UUID returns a random (version 4) UUID. This library adds methods for creating version 1, version 3 and version 5 UUIDs.

Time-based UUIDs (UUID.v1)

UUID.v1 returns a time-based (version 1) UUID.

let uuidv1 = UUID.v1()

Instead of relying on the computer's Ethernet address to ensure global uniqueness of time-based UUIDs, this method generates a random node identifier that is used for the duration of the program's execution, as specified in RFC 4122 section 4.5. The reason is discussed in this issue.

Random UUIDs (UUID.v4)

UUID.v4 returns a random (version 4) UUID. You may pass a custom random number generator.

var generator = SystemRandomNumberGenerator()
let uuidv4 = UUID.v4(using: generator)

Name-based UUIDs (UUID.v3 and UUID.v5)

UUID.v3 and UUID.v5 return name-based UUIDs using either MD5 (version 3) or SHA-1 (version 5) hashing.

let uuidv3 = UUID.v3(name: "thats.an.example", namespace: .dns)
let uuidv5 = UUID.v5(name: "http://example.com/index.html", namespace: .url)

Name-based UUIDs are built by combining a unique name with a namespace identifier. UUIDKit contains a list of pre-defined namespaces (.dns, .url, .oid and .x500); but any UUID may be used as a namespace.

let customNamespace = UUID.Namespace(UUID(uuidString: "34cd6bf4-3f41-4717-95ea-131762f60af8")!)

License

This project is licensed for use under the MIT License (MIT). Please see the LICENSE file for more information.

uuid-kit's Issues

Removing Ethernet address from version 1 UUIDs

Using the Ethernet address in time-based (version 1) UUIDs has several caveats:

• Determining the Ethernet address is not portable. The current implementation requires to embed C code in the library and only supports Darwin and Linux.
• The Ethernet address is not always globally unique.
  • On a MacBook Pro with touch bar, the first network interface is always ac:de:48:00:11:22.
  • Docker assigns Ethernet addresses from the range 02:42:ac:11:00:00–02:42:ac:11:ff:ff.
  • And there are probably more example.
• Exposing the Ethernet address may leak private information.

We already use a random node identifier as a fallback when the Ethernet address cannot be determined, as specified in RFC 4122 section 4.5. I suggest we make using that random identifier the default choice for UUID.v1.

Evolution: UUID Version 6

There exists a proposal for "Version 6" UUIDs.

They are similar to RFC4122's time-based (version 1) UUIDs but the timestamp's bits are stored in standard byte order which make the UUIDs sortable using lexicographic order.

uuid v1: 9850ee54-fc18-11ea-adc1-0242ac120002
         zzzzzzzz yyyy 1xxx

uuid v6: 1eafc189-850e-6e54-adc1-0242ac120002
         xxxyyyyz zzzz 6zzz

Should we wait for the proposal to be accepted before implementing it?

Evolution: UUID Version 2

Does anyone need support for DCE Security (version 2) UUIDs? Probably not.

Evolution: Make UUIDv1 public

UUID.UUIDv1, UUID.Timestamp, UUID.ClockSequence and UUID.NodeID are currently implementation details of the UUID.v1() method (I originally intended .v1() to just be a wrapper around uuid_generate_time() but I wasn't satisfied with the implementation in swift-corelibs-foundation).

Some developers might want to inspect time-based (version 1) UUIDs or generate UUIDs with custom node IDs (or timestamps), which is why I plan to make these types public in a future release.

However I first need to make sure that the APIs are good enough that I won't have to change them and break existing code in the near future. Also I have to write the corresponding docs.

Feel free to comment if you see anything that should change before I do.