Skip to content

Latest commit

 

History

History
86 lines (65 loc) · 3.87 KB

uuid.adoc

File metadata and controls

86 lines (65 loc) · 3.87 KB

UUID

Table of Contents

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in IETF BCP14 (RFC2119 & RFC8174)

Copyright (c) 2023 General Motors GTO LLC

Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements.  See the NOTICE file
distributed with this work for additional information
regarding copyright ownership.  The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License.  You may obtain a copy of the License at

  http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied.  See the License for the
specific language governing permissions and limitations
under the License.

SPDX-FileType: DOCUMENTATION
SPDX-FileCopyrightText: 2023 General Motors GTO LLC
SPDX-License-Identifier: Apache-2.0

1. Overview

Universal Unique Identifier (UUID) are used to uniquely identify a "thing". UUIDs shall be used in uProtocol the UUID shall be used to uniquely identify messages (events) sent between uEs and between devices.

UUIDv1 through 4 are defined in RFC4122 and have been deployed throughout the Internet and in applications for many years. A new RFC draft draft-ietf-uuidrev-rfc4122bis proposes three new types of RFCs, UUIDv6, v7, and v8.

uProtocol shall define its own format of UUID (using UUIDv8 specification) so that:

  • ID is sortable

  • Timestamp is based on the reliable (and widely used) Unix Epoch

  • Large random number to ensure the UUIDs retain the required level of unguessability through underlying entropy

  • Support for <1ms precision

  • ID generation is efficient

2. Specification

The following will elaborate on the uProtocol UUIDv8 bit allocations:

 0                   1                   2                   3
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                         unix_ts_ms                            |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|           unix_ts_ms          |  ver  |         counter       |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|var|                          rand_b                           |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                           rand_b                              |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
Table 1. UUIDv8 Field Description
Field RFC2119

unix_ts_ms

ver

counter

  • MUST be a 12 bit counter, reset at each unix_ts_ms tick

  • MUST be incremented for each UUID generated within unix_ts_ms tick

  • MUST be frozen when counter reaches maximum value 4095

var

rand_b

  • MUST be a 62 bits pseudo-random number generated per uE

  • MUST NOT change during the lifecycle of the uE