Documentation
¶
Overview ¶
Package sd_id128 reads, generates, and processes 128-bit ID values.
These 128-bit IDs are a generalization of DCE UUIDs (of which Microsoft GUIDs are one implementation), but use a simpler string format. This package imposes no structure on the used IDs, unlike UUIDs, but are fully compatible with those types of IDs.
DCE UUID: https://tools.ietf.org/html/rfc4122
Microsoft GUID: https://msdn.microsoft.com/en-us/library/windows/desktop/aa373931(v=vs.85).aspx
The UUID string representation is a (zero-padded) 32-digit hexadecimal number with a hyphen after the 8th, 12th, 16th, and 20th digits (for a total length of 36 glyphs). This package supports this format, but the primary ("plain") string representation is simply a (zero-padded) 32-digit hexadecimal number.
For example:
Plain: 6ba7b8109dad11d180b400c04fd430c8 UUID : 6ba7b810-9dad-11d1-80b4-00c04fd430c8
Several restrictions are imposed on the structure of UUIDs. Most notably, the most significant 1-3 bits of the 8th octet specify the UUID type ("variant"); unless dealing with legacy UUIDs, the most significant 2 bits of the octet will be "10", specifying a RFC 4122 type UUID. Assuming RFC 4122 type, the most significant 4 bits of the 6th octet then specify the sub-type ("version"), which could impose complicated requirements on the rest of the UUID.
This package doesn't really care about all of these UUID structure requirements. Nothing in this package ever inspects an ID's structure. However, because it is anticipated that the IDs generated by this package might be used in a context where a UUID is required, many of the functions that emit an ID ensure that the ID emitted is structured to be a valid UUID.
Index ¶
Constants ¶
This section is empty.
Variables ¶
Functions ¶
This section is empty.
Types ¶
type ID128 ¶
type ID128 [16]byte
func GetBootUUID ¶
GetBootUUID returns a UUID unique to this boot; it is generated by the kernel once very early in the boot process.
This is read as a UUID (with trailing newline) from "/proc/sys/kernel/random/boot_id".
It may be relied on that the Linux kernel sets boot_id to a UUID with the UUID type ("variant") set to RFC 4122 format, and the sub-type ("version") set appropriately.
See random(4) for more information.
random(4): http://man7.org/linux/man-pages/man4/random.4.html
func GetInvocationUUID ¶
GetInvocationUUID returns a UUID unique to this invocation of the currently executed service.
This is read from the "INVOCATION_ID" environment variable, which is expected to be set by the service manager.
It may be relied on that the service manager sets this to a UUID with the UUID type ("variant") set to RFC 4122 format, and the sub-type ("version") set appropriately.
The error returned is ErrNone if the service manager did not set INVOCATION_ID, or ErrInvalid if the value of INVOCATION_ID could not be parsed.
See sd_id128_get_invocation(3) for more information.
sd_id128_get_invocation(3): https://www.freedesktop.org/software/systemd/man/sd_id128_get_invocation.html
BUG(lukeshu): GetInvocationUUID uses a mechanism specified by "what systemd currently does", rather than a stable specification.
func GetMachineID ¶
GetMachineID returns a unique identifier for this operating system installation.
This is read as a plain hexadecimal number (with an optional trailing newline) from "/etc/machine-id".
Note that unlike every other "Get*ID" function, the ID returned by GetMachineID is not guaranteed to be a valid UUID, though values generated by systemd v30 and later are valid UUIDs.
See machine-id(5) for more information.
machine-id(5): https://www.freedesktop.org/software/systemd/man/machine-id.html
func GetRandomUUID ¶
GetRandomUUID generates a random UUID (122 random bits).
For convenience when a valid UUID is needed, rather than returning a totally random 128-bit number, this sets the UUID type ("variant") to RFC 4122 format, and the sub-type ("version") to "4", which is (pseudo) random generation. This leaves 122 random bits.
The pseudorandom number generator used is cryptographically secure.
func Parse ¶
Parse parses a 128-bit ID represented either in the plain string format, or in the UUID string format.
If you need to validate that the string is in one format or the other, then you should use the ParsePlain or ParseUUID functions.
If the input string does not match either of these formats, then ErrInvalid is returned.
func ParsePlain ¶
ParsePlain parses a 128-bit ID represented in the plain string format.
If you would like more flexibility, and would like to accept either the plain string format or the UUID string format, then you should use the Parse function.
If the input string is not a 32-digit hexadecimal number, then ErrInvalid is returned.
func ParseUUID ¶
ParsePlain parses a 128-bit ID represented in the UUID string format.
If you would like more flexibility, and would like to accept either the plain string format or the UUID string format, then you should use the Parse function.
If the input string is not a 36-character UUID string, then ErrInvalid is returned. This function does not validate the variant or version bit fields, nor does it validate any structure implied by them.
func (ID128) String ¶
String formats the ID as a plain zero-padded 32-digit hexadecimal number.
Notes ¶
Bugs ¶
GetInvocationUUID uses a mechanism specified by "what systemd currently does", rather than a stable specification.
GetInvocationUUID might logically belong in the sd_daemon package, but we defer to the C-language libsystemd's placement of sd_id128_get_invocation() in sd-id128.h.
GetInvocationUUID should distrust the environment in certain situations, similarly to GNU libc secure_getenv.
Source Files