1 /* SPDX-License-Identifier: GPL-2.0+ */ 2 /* 3 * Copyright (C) 2014 Samsung Electronics 4 * Przemyslaw Marczak <p.marczak@samsung.com> 5 * Copyright 2022-2023 Arm Limited and/or its affiliates <open-source-office@arm.com> 6 * 7 * Authors: 8 * Abdellatif El Khlifi <abdellatif.elkhlifi@arm.com> 9 */ 10 #ifndef __UUID_H__ 11 #define __UUID_H__ 12 13 #include <linux/bitops.h> 14 #include <linux/kconfig.h> 15 16 /* 17 * UUID - Universally Unique IDentifier - 128 bits unique number. 18 * There are 5 versions and one variant of UUID defined by RFC4122 19 * specification. A UUID contains a set of fields. The set varies 20 * depending on the version of the UUID, as shown below: 21 * - time, MAC address(v1), 22 * - user ID(v2), 23 * - MD5 of name or URL(v3), 24 * - random data(v4), 25 * - SHA-1 of name or URL(v5), 26 * 27 * Layout of UUID: 28 * timestamp - 60-bit: time_low, time_mid, time_hi_and_version 29 * version - 4 bit (bit 4 through 7 of the time_hi_and_version) 30 * clock seq - 14 bit: clock_seq_hi_and_reserved, clock_seq_low 31 * variant: - bit 6 and 7 of clock_seq_hi_and_reserved 32 * node - 48 bit 33 * 34 * source: https://www.ietf.org/rfc/rfc4122.txt 35 * 36 * UUID binary format (16 bytes): 37 * 38 * 4B-2B-2B-2B-6B (big endian - network byte order) 39 * 40 * UUID string is 36 length of characters (36 bytes): 41 * 42 * 0 9 14 19 24 43 * xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx 44 * be be be be be 45 * 46 * where x is a hexadecimal character. Fields are separated by '-'s. 47 * When converting to a binary UUID, le means the field should be converted 48 * to little endian and be means it should be converted to big endian. 49 * 50 * UUID is also used as GUID (Globally Unique Identifier) with the same format 51 * but with some fields stored in little endian. 52 * 53 * GUID: 54 * 0 9 14 19 24 55 * xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx 56 * le le le be be 57 * 58 * GUID is used e.g. in GPT (GUID Partition Table) as a partiions unique id. 59 */ 60 61 /* This is structure is in big-endian */ 62 struct uuid { 63 unsigned int time_low; 64 unsigned short time_mid; 65 unsigned short time_hi_and_version; 66 unsigned char clock_seq_hi_and_reserved; 67 unsigned char clock_seq_low; 68 unsigned char node[6]; 69 } __packed; 70 71 /* Bits of a bitmask specifying the output format for GUIDs */ 72 #define UUID_STR_FORMAT_STD 0 73 #define UUID_STR_FORMAT_GUID 0x1 74 #define UUID_STR_UPPER_CASE 0x2 75 76 /* Use UUID_STR_LEN + 1 for string space */ 77 #define UUID_STR_LEN 36 78 #define UUID_BIN_LEN sizeof(struct uuid) 79 80 #define UUID_VERSION_MASK 0xf000 81 #define UUID_VERSION_SHIFT 12 82 #define UUID_VERSION 0x4 83 84 #define UUID_VARIANT_MASK 0xc0 85 #define UUID_VARIANT_SHIFT 7 86 #define UUID_VARIANT 0x1 87 88 int uuid_str_valid(const char *uuid); 89 90 /* 91 * uuid_str_to_bin() - convert string UUID or GUID to big endian binary data. 92 * 93 * @param uuid_str - pointer to UUID or GUID string [37B] or GUID shorcut 94 * @param uuid_bin - pointer to allocated array for big endian output [16B] 95 * @str_format - UUID string format: 0 - UUID; 1 - GUID 96 * Return: 0 if OK, -EINVAL if the string is not a valid UUID 97 */ 98 int uuid_str_to_bin(const char *uuid_str, unsigned char *uuid_bin, 99 int str_format); 100 101 /* 102 * uuid_bin_to_str() - convert big endian binary data to string UUID or GUID. 103 * 104 * @param uuid_bin: pointer to binary data of UUID (big endian) [16B] 105 * @param uuid_str: pointer to allocated array for output string [37B] 106 * @str_format: bit 0: 0 - UUID; 1 - GUID 107 * bit 1: 0 - lower case; 2 - upper case 108 */ 109 void uuid_bin_to_str(const unsigned char *uuid_bin, char *uuid_str, 110 int str_format); 111 112 /* 113 * uuid_guid_get_bin() - this function get GUID bin for string 114 * 115 * @param guid_str - pointer to partition type string 116 * @param guid_bin - pointer to allocated array for big endian output [16B] 117 */ 118 int uuid_guid_get_bin(const char *guid_str, unsigned char *guid_bin); 119 120 /* 121 * uuid_guid_get_str() - this function get string for GUID. 122 * 123 * @param guid_bin - pointer to string with partition type guid [16B] 124 * 125 * Returns NULL if the type GUID is not known. 126 */ 127 const char *uuid_guid_get_str(const unsigned char *guid_bin); 128 129 /* 130 * gen_rand_uuid() - this function generates a random binary UUID version 4. 131 * In this version all fields beside 4 bits of version and 132 * 2 bits of variant are randomly generated. 133 * 134 * @param uuid_bin - pointer to allocated array [16B]. Output is in big endian. 135 */ 136 void gen_rand_uuid(unsigned char *uuid_bin); 137 138 /* 139 * gen_rand_uuid_str() - this function generates UUID v4 (random) in two string 140 * formats UUID or GUID. 141 * 142 * @param uuid_str - pointer to allocated array [37B]. 143 * @param - uuid output type: UUID - 0, GUID - 1 144 */ 145 void gen_rand_uuid_str(char *uuid_str, int str_format); 146 147 struct efi_guid; 148 149 /** 150 * gen_v5_guid() - generate little endian v5 GUID from namespace and other seed data. 151 * 152 * @namespace: pointer to UUID namespace salt 153 * @guid: pointer to allocated GUID output 154 * @...: NULL terminated list of seed data as pairs of pointers 155 * to data and their lengths 156 */ 157 void gen_v5_guid(const struct uuid *namespace, struct efi_guid *guid, ...); 158 159 /** 160 * uuid_str_to_le_bin() - Convert string UUID to little endian binary data. 161 * @uuid_str: pointer to UUID string 162 * @uuid_bin: pointer to allocated array for little endian output [16B] 163 * 164 * UUID string is 36 characters (36 bytes): 165 * 166 * xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx 167 * 168 * where x is a hexadecimal character. Fields are separated by '-'s. 169 * When converting to a little endian binary UUID, the string fields are reversed. 170 * 171 * Return: 172 * 173 * uuid_bin filled with little endian UUID data 174 * On success 0 is returned. Otherwise, failure code. 175 */ 176 int uuid_str_to_le_bin(const char *uuid_str, unsigned char *uuid_bin); 177 178 #endif 179