uuid (UUIDs)

Overview

Type and helper functions for a Universally Unique Identifier (UUID).

UUIDs (per RFC 4122) are used in several libraries supported by EtcPal. This module contains a type for a UUID and functions to generate, inspect and manipulate them.

#include "etcpal/uuid.h"

The basic UUID type is quite simple - an array of 16 data bytes. Functions are provided to generate every current UUID type except Version 2, which is very rarely used. Additionally, etcpal_generate_os_preferred_uuid() generates the UUID type preferred by the underlying OS, and etcpal_generate_device_uuid() generates a special type of V5 UUID which can be used to identify embedded devices.

Generation of V1 and V4 UUIDs require EtcPal to be compiled with OS abstraction support (the default in most situations).

The basic form of UUID generation is:

EtcPalUuid uuid;
if (etcpal_generate_v1_uuid(&uuid) == kEtcPalErrOk)
{
  // uuid now contains a valid Version 1 UUID.
}

Note: Not all UUID types are available on all systems. V3, V5 and Device UUIDs are guaranteed to be available in all ports of EtcPal, but V1, V4 and os_preferred UUIDs are generally not available on embedded systems:

EtcPal Platform	V1	V3	V4	V5	os_preferred	device
FreeRTOS	No	Yes	No	Yes	No	Yes
Linux	Yes	Yes	Yes	Yes	Yes	Yes
macOS	Yes	Yes	Yes	Yes	Yes	Yes
MQX	No	Yes	No	Yes	No	Yes
Windows	Yes	Yes	Yes	Yes	Yes	Yes

You can also convert UUIDs to and from strings:

EtcPalUuid uuid;
etcpal_string_to_uuid("39713ce1-2320-46aa-b602-4977be36e155", &uuid);
 
char str_buf[ETCPAL_UUID_STRING_BYTES];
etcpal_uuid_to_string(&uuid, str_buf);

Data Structures
struct	EtcPalUuid
	The UUID type. More...

Macros
#define	ETCPAL_UUID_BYTES   16u
	The number of bytes that make up a UUID.
#define	ETCPAL_UUID_CMP(uuid1ptr, uuid2ptr)   memcmp((uuid1ptr)->data, (uuid2ptr)->data, ETCPAL_UUID_BYTES)
	Compare two UUIDs. More...
#define	ETCPAL_UUID_IS_NULL(uuidptr)   (memcmp((uuidptr)->data, kEtcPalNullUuid.data, ETCPAL_UUID_BYTES) == 0)
	Determine if a UUID is null. More...
#define	ETCPAL_UUID_STRING_BYTES   37
	The maximum number of bytes required to hold an ASCII string representation of a UUID.
#define	ETCPAL_UUID_DEV_STR_MAX_LEN   32
	The maximum length of a device string used as an input to etcpal_generate_device_uuid().

Typedefs
typedef struct EtcPalUuid	EtcPalUuid
	The UUID type.

Functions
bool	etcpal_uuid_to_string (const EtcPalUuid *uuid, char *buf)
	Create a string representation of a UUID. More...
bool	etcpal_string_to_uuid (const char *str, EtcPalUuid *uuid)
	Create a UUID from a string representation. More...
etcpal_error_t	etcpal_generate_v1_uuid (EtcPalUuid *uuid)
	Generate a Version 1 UUID. More...
etcpal_error_t	etcpal_generate_v3_uuid (const EtcPalUuid *ns, const void *name, size_t name_len, EtcPalUuid *uuid)
	Generate a Version 3 UUID. More...
etcpal_error_t	etcpal_generate_v4_uuid (EtcPalUuid *uuid)
	Generate a Version 4 UUID. More...
etcpal_error_t	etcpal_generate_v5_uuid (const EtcPalUuid *ns, const void *name, size_t name_len, EtcPalUuid *uuid)
	Generate a Version 5 UUID. More...
etcpal_error_t	etcpal_generate_os_preferred_uuid (EtcPalUuid *uuid)
	Generate the preferred UUID version of the underlying OS. More...
etcpal_error_t	etcpal_generate_device_uuid (const char *dev_str, const uint8_t *mac_addr, uint32_t uuid_num, EtcPalUuid *uuid)
	Generate a UUID from a combination of a custom string and MAC address. More...

Variables
const EtcPalUuid	kEtcPalNullUuid
	A null (all 0's) UUID, used by ETCPAL_UUID_IS_NULL() for comparison.

Macro Definition Documentation

ETCPAL_UUID_CMP

#define ETCPAL_UUID_CMP	(		uuid1ptr,
			uuid2ptr
	)		memcmp((uuid1ptr)->data, (uuid2ptr)->data, ETCPAL_UUID_BYTES)

Compare two UUIDs.

Parameters

uuid1ptr	Pointer to first EtcPalUuid to compare.
uuid2ptr	Pointer to second EtcPalUuid to compare.

Returns

< 0: uuid1ptr is less than uuid2ptr

0: uuid1ptr is equal to uuid2ptr

> 0: uuid1ptr is greater than uuid2ptr

ETCPAL_UUID_IS_NULL

#define ETCPAL_UUID_IS_NULL

(

uuidptr

)

(memcmp((uuidptr)->data, kEtcPalNullUuid.data, ETCPAL_UUID_BYTES) == 0)

Determine if a UUID is null.

A UUID is said to be 'null' when it is made up of all 0's.

Parameters

uuidptr

Pointer to UUID to null-check.

Returns

true (UUID is null) or false (UUID is not null).

Function Documentation

etcpal_generate_device_uuid()

etcpal_error_t etcpal_generate_device_uuid	(	const char *	dev_str,
		const uint8_t *	mac_addr,
		uint32_t	uuid_num,
		EtcPalUuid *	uuid
	)

Generate a UUID from a combination of a custom string and MAC address.

This function is for use by embedded devices that want to create UUIDs representing themselves, and create the same UUIDs each time. It creates a Version 5 UUID (defined in RFC 4122) within a constant, hardcoded namespace. The UUID output is deterministic for each combination of dev_str, mac_addr and uuid_num inputs.

The namespace UUID used is: 57323103-db01-44b3-bafa-abdee3f37c1a

Parameters

[in]	dev_str	The device-specific string, such as the model name. This should never change on the device. It also allows different programs running on the device to generate different UUID sets.
[in]	mac_addr	The device's MAC address; must be an array of 6 bytes.
[in]	uuid_num	Component number. By changing this number, multiple unique UUIDs can be generated for the same device string-MAC address combination.
[out]	uuid	UUID to fill in with the generation result.

Returns

kEtcPalErrOk: UUID generated successfully.

kEtcPalErrInvalid: Invalid argument provided.

etcpal_generate_os_preferred_uuid()

etcpal_error_t etcpal_generate_os_preferred_uuid

(

EtcPalUuid *

uuid

)

Generate the preferred UUID version of the underlying OS.

This function uses the underlying OS API to create a UUID of the recommended type per the underlying OS API. In practice, this is often a V4 UUID, although this is not guaranteed.

This function may return kEtcPalErrNotImpl on platforms that do not have this functionality available (this is mostly a concern for RTOS-level embedded platforms).

Parameters

[out]

uuid

UUID to fill in with the generation result.

Returns

kEtcPalErrOk: UUID generated successfully.

kEtcPalErrInvalid: Invalid argument provided.

kEtcPalErrNotImpl: This UUID generation method is not available on this platform.

kEtcPalErrSys: An internal library of system call error occurred.

etcpal_generate_v1_uuid()

etcpal_error_t etcpal_generate_v1_uuid

(

EtcPalUuid *

uuid

)

Generate a Version 1 UUID.

This function uses the underlying OS API to create a UUID that is based on a combination of a local MAC address and the current system time. This method guarantees UUID uniqueness across space and time. Some OSes have deprecated this method because it creates a UUID that is traceable to the MAC address of the machine on which it was generated. If this type of security is a concern, etcpal_generate_v4_uuid() should be preferred. If you want to generate UUIDs that are deterministic for a combination of inputs you provide, see etcpal_generate_v3_uuid(), etcpal_generate_v5_uuid() or etcpal_generate_device_uuid().

This function may return kEtcPalErrNotImpl on platforms that do not have this functionality available (this is mostly a concern for RTOS-level embedded platforms).

Parameters

[out]

uuid

UUID to fill in with the generation result.

Returns

kEtcPalErrOk: UUID generated successfully.

kEtcPalErrInvalid: Invalid argument provided.

kEtcPalErrNotImpl: This UUID generation method is not available on this platform.

kEtcPalErrSys: An internal library of system call error occurred.

etcpal_generate_v3_uuid()

etcpal_error_t etcpal_generate_v3_uuid	(	const EtcPalUuid *	ns,
		const void *	name,
		size_t	name_len,
		EtcPalUuid *	uuid
	)

Generate a Version 3 UUID.

Version 3 UUIDs are "name-based"; they deterministically convert a combination of a "namespace" and "name" to a UUID. A namespace is another UUID of any type which represents a space within which UUIDs generated from different names are unique. A name is opaque data of any length. The same combination of namespace and name will always produce the same Version 3 UUID.

Version 3 UUIDs use the MD5 hashing algorithm to convert their inputs into a UUID. Prefer using etcpal_generate_v5_uuid(), which uses the SHA-1 algorithm instead, if backward compatibility is not an issue.

Parameters

[in]	ns	UUID to use as a namespace.
[in]	name	The name to convert into a UUID - opaque data.
[in]	name_len	The length in bytes of name.
[out]	uuid	UUID to fill in with the generation result.

Returns

kEtcPalErrOk: UUID generated successfully.

kEtcPalErrInvalid: Invalid argument provided.

etcpal_generate_v4_uuid()

etcpal_error_t etcpal_generate_v4_uuid

(

EtcPalUuid *

uuid

)

Generate a Version 4 UUID.

This function uses the underlying OS API to create a UUID that is based on random data. The quality of the random data used may differ across platforms. If you want to generate UUIDs that are deterministic for a combination of inputs you provide, see etcpal_generate_v3_uuid().

This function may return kEtcPalErrNotImpl on platforms that do not have this functionality available (this is mostly a concern for RTOS-level embedded platforms).

Parameters

[out]

uuid

UUID to fill in with the generation result.

Returns

kEtcPalErrOk: UUID generated successfully.

kEtcPalErrInvalid: Invalid argument provided.

kEtcPalErrNotImpl: This UUID generation method is not available on this platform.

kEtcPalErrSys: An internal library of system call error occurred.

etcpal_generate_v5_uuid()

etcpal_error_t etcpal_generate_v5_uuid	(	const EtcPalUuid *	ns,
		const void *	name,
		size_t	name_len,
		EtcPalUuid *	uuid
	)

Generate a Version 5 UUID.

Version 5 UUIDs are "name-based"; they deterministically convert a combination of a "namespace" and "name" to a UUID. A namespace is another UUID of any type which represents a space within which UUIDs generated from different names are unique. A name is opaque data of any length. The same combination of namespace and name will always produce the same Version 5 UUID.

Version 5 UUIDs use the SHA-1 hashing algorithm to convert their inputs into a UUID.

etcpal_generate_device_uuid() provides a specialized form of this function which embedded devices can use to create UUIDs representing themselves.

Parameters

[in]	ns	UUID to use as a namespace.
[in]	name	The name to convert into a UUID - opaque data.
[in]	name_len	The length in bytes of name.
[out]	uuid	UUID to fill in with the generation result.

Returns

kEtcPalErrOk: UUID generated successfully.

kEtcPalErrInvalid: Invalid argument provided.

etcpal_string_to_uuid()

bool etcpal_string_to_uuid	(	const char *	str,
		EtcPalUuid *	uuid
	)

Create a UUID from a string representation.

Parses a string-represented UUID and fills in a EtcPalUuid structure with the result. The input should be of the form: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx (hexadecimal letters can be upper- or lowercase).

Parameters

[in]	str	The null-terminated string to convert.
[out]	uuid	UUID to fill in with the parse result.

Returns

true (parse successful) or false (parse failure).

etcpal_uuid_to_string()

bool etcpal_uuid_to_string	(	const EtcPalUuid *	uuid,
		char *	buf
	)

Create a string representation of a UUID.

The resulting string will be of the form: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx (lowercase is used for hexadecimal letters per RFC 4122 and common convention).

Parameters

[in]	uuid	UUID to convert to a string.
[out]	buf	Character buffer to which to write the resulting string. To avoid undefined behavior, this buffer must be at least of size ETCPAL_UUID_STRING_BYTES.

Returns

true (conversion successful) or false (invalid argument).