[uuid] Add uuid_aton() to parse a UUID from a string

Add uuid_aton() to parse a UUID value from a string (analogous to
inet_aton(), inet6_aton(), sock_aton(), etc), treating it as a
32-digit hex string with optional hyphen separators.  The placement of
the separators is not checked: each byte within the hex string may be
separated by a hyphen, or not separated at all.

Add dedicated self-tests for UUID parsing and formatting (already
partially covered by the ":uuid" and ":guid" settings self-tests).

Signed-off-by: Michael Brown <mcb30@ipxe.org>

diff --git a/src/core/base16.c b/src/core/base16.c
index f9e0f3364f2077cae6dde1fc3158a2d87f2a2bb7..47e35f41480aff6f3ca3bc84f792114321225e7f 100644 (file)
--- a/src/core/base16.c
+++ b/src/core/base16.c
@@ -78,12 +78,23 @@ int hex_decode ( char separator, const char *encoded, void *data, size_t len ) {
        unsigned int count = 0;
        unsigned int sixteens;
        unsigned int units;
+       int optional;
 
+       /* Strip out optionality flag from separator character */
+       optional = ( separator & HEX_DECODE_OPTIONAL );
+       separator &= ~HEX_DECODE_OPTIONAL;
+
+       /* Decode string */
        while ( *encoded ) {
 
                /* Check separator, if applicable */
-               if ( count && separator && ( ( *(encoded++) != separator ) ) )
-                       return -EINVAL;
+               if ( count && separator ) {
+                       if ( *encoded == separator ) {
+                               encoded++;
+                       } else if ( ! optional ) {
+                               return -EINVAL;
+                       }
+               }
 
                /* Extract digits.  Note that either digit may be NUL,
                 * which would be interpreted as an invalid value by

diff --git a/src/core/uuid.c b/src/core/uuid.c
index c43d4216f80cb8d19e18493d5db09b198363ec17..b6600af71b2cf3258cf08fed6d04a666a14fb6b5 100644 (file)
--- a/src/core/uuid.c
+++ b/src/core/uuid.c
@@ -25,7 +25,9 @@ FILE_LICENCE ( GPL2_OR_LATER_OR_UBDL );
 
 #include <stdint.h>
 #include <stdio.h>
+#include <errno.h>
 #include <byteswap.h>
+#include <ipxe/base16.h>
 #include <ipxe/uuid.h>
 
 /** @file
@@ -53,3 +55,29 @@ const char * uuid_ntoa ( const union uuid *uuid ) {
                  uuid->canonical.e[4], uuid->canonical.e[5] );
        return buf;
 }
+
+/**
+ * Parse UUID
+ *
+ * @v string           UUID string
+ * @v uuid             UUID to fill in
+ * @ret rc             Return status code
+ */
+int uuid_aton ( const char *string, union uuid *uuid ) {
+       int len;
+       int rc;
+
+       /* Decode as hex string with optional '-' separator */
+       len = hex_decode ( ( '-' | HEX_DECODE_OPTIONAL ), string, uuid->raw,
+                          sizeof ( *uuid ) );
+       if ( len < 0 ) {
+               rc = len;
+               return rc;
+       }
+
+       /* Check length */
+       if ( len != sizeof ( *uuid ) )
+               return -EINVAL;
+
+       return 0;
+}

diff --git a/src/include/ipxe/base16.h b/src/include/ipxe/base16.h
index 8c44da17eb4551355c72986d94e8f12ba43eca0d..c9e430e7e63bbb5f2790b711c81a3b9c4a18a566 100644 (file)
--- a/src/include/ipxe/base16.h
+++ b/src/include/ipxe/base16.h
@@ -12,6 +12,9 @@ FILE_LICENCE ( GPL2_OR_LATER_OR_UBDL );
 #include <stdint.h>
 #include <string.h>
 
+/** Treat separator as optional while decoding */
+#define HEX_DECODE_OPTIONAL 0x80
+
 /**
  * Calculate length of base16-encoded data
  *

diff --git a/src/include/ipxe/errfile.h b/src/include/ipxe/errfile.h
index 662f84964a4d88c7d8a71e5cd76b4a027029393a..7cff594d534a409f3d99981dc43db3ec74bdf76f 100644 (file)
--- a/src/include/ipxe/errfile.h
+++ b/src/include/ipxe/errfile.h
@@ -79,6 +79,7 @@ FILE_LICENCE ( GPL2_OR_LATER_OR_UBDL );
 #define ERRFILE_cachedhcp             ( ERRFILE_CORE | 0x00270000 )
 #define ERRFILE_acpimac                       ( ERRFILE_CORE | 0x00280000 )
 #define ERRFILE_efi_strings           ( ERRFILE_CORE | 0x00290000 )
+#define ERRFILE_uuid                  ( ERRFILE_CORE | 0x002a0000 )
 
 #define ERRFILE_eisa                ( ERRFILE_DRIVER | 0x00000000 )
 #define ERRFILE_isa                 ( ERRFILE_DRIVER | 0x00010000 )

diff --git a/src/include/ipxe/uuid.h b/src/include/ipxe/uuid.h
index 24c46acafd14d49d2ca90dc2fb70602ae3817e02..4874b738201944f56a2e274966e47447ac307f4c 100644 (file)
--- a/src/include/ipxe/uuid.h
+++ b/src/include/ipxe/uuid.h
@@ -48,5 +48,6 @@ static inline void uuid_mangle ( union uuid *uuid ) {
 }
 
 extern const char * uuid_ntoa ( const union uuid *uuid );
+extern int uuid_aton ( const char *string, union uuid *uuid );
 
 #endif /* _IPXE_UUID_H */

diff --git a/src/tests/tests.c b/src/tests/tests.c
index 90cec948971241d4a222d2932943417f178e08c8..cb296049e91bf925582bebacd43fc2d9fffa4631 100644 (file)
--- a/src/tests/tests.c
+++ b/src/tests/tests.c
@@ -84,3 +84,4 @@ REQUIRE_OBJECT ( nap_test );
 REQUIRE_OBJECT ( x25519_test );
 REQUIRE_OBJECT ( des_test );
 REQUIRE_OBJECT ( mschapv2_test );
+REQUIRE_OBJECT ( uuid_test );

diff --git a/src/tests/uuid_test.c b/src/tests/uuid_test.c
new file mode 100644 (file)
index 0000000..42dc526
--- /dev/null
+++ b/src/tests/uuid_test.c
@@ -0,0 +1,156 @@
+/*
+ * Copyright (C) 2024 Michael Brown <mbrown@fensystems.co.uk>.
+ *
+ * This program is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU General Public License as
+ * published by the Free Software Foundation; either version 2 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful, but
+ * WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program; if not, write to the Free Software
+ * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
+ * 02110-1301, USA.
+ *
+ * You can also choose to distribute this program under the terms of
+ * the Unmodified Binary Distribution Licence (as given in the file
+ * COPYING.UBDL), provided that you have satisfied its requirements.
+ */
+
+FILE_LICENCE ( GPL2_OR_LATER_OR_UBDL );
+
+/** @file
+ *
+ * UUID tests
+ *
+ */
+
+/* Forcibly enable assertions */
+#undef NDEBUG
+
+#include <string.h>
+#include <byteswap.h>
+#include <ipxe/uuid.h>
+#include <ipxe/test.h>
+
+/** Define an inline UUID value */
+#define UUID( A, B, C, D, E0, E1, E2, E3, E4, E5 ) {           \
+               .a = htonl ( A ),                               \
+               .b = htons ( B ),                               \
+               .c = htons ( C ),                               \
+               .d = htons ( D ),                               \
+               .e = { E0, E1, E2, E3, E4, E5 },                \
+       }
+
+/**
+ * Report a uuid_ntoa() test result
+ *
+ * @v uuid             UUID
+ * @v text             Expected textual representation
+ * @v file             Test code file
+ * @v line             Test code line
+ */
+static void uuid_ntoa_okx ( const union uuid *uuid, const char *text,
+                           const char *file, unsigned int line ) {
+       const char *actual;
+
+       /* Format address */
+       actual = uuid_ntoa ( uuid );
+       DBG ( "uuid_ntoa ( %08x-%04x-%04x-%04x-%02x%02x%02x%02x%02x%02x ) = "
+             "\"%s\"\n", ntohl ( uuid->canonical.a ),
+             ntohs ( uuid->canonical.b ), ntohs ( uuid->canonical.c ),
+             ntohs ( uuid->canonical.d ), uuid->canonical.e[0],
+             uuid->canonical.e[1], uuid->canonical.e[2], uuid->canonical.e[3],
+             uuid->canonical.e[4], uuid->canonical.e[5], actual );
+       okx ( strcmp ( actual, text ) == 0, file, line );
+}
+#define uuid_ntoa_ok( value, text ) do {                               \
+       static const union uuid uuid = {                                \
+               .canonical = value,                                     \
+       };                                                              \
+       uuid_ntoa_okx ( &uuid, text, __FILE__, __LINE__ );              \
+       } while ( 0 )
+
+/**
+ * Report a uuid_aton() test result
+ *
+ * @v text             Textual representation
+ * @v uuid             Expected UUID
+ * @v file             Test code file
+ * @v line             Test code line
+ */
+static void uuid_aton_okx ( const char *text, const union uuid *uuid,
+                           const char *file, unsigned int line ) {
+       union uuid actual;
+
+       /* Parse address */
+       okx ( uuid_aton ( text, &actual ) == 0, file, line );
+       DBG ( "uuid_aton ( \"%s\" ) = %s\n", text, uuid_ntoa ( &actual ) );
+       okx ( memcmp ( &actual, uuid, sizeof ( actual ) ) == 0, file, line );
+};
+#define uuid_aton_ok( text, value ) do {                               \
+       static const union uuid uuid = {                                \
+               .canonical = value,                                     \
+       };                                                              \
+       uuid_aton_okx ( text, &uuid, __FILE__, __LINE__ );              \
+       } while ( 0 )
+
+/**
+ * Report a uuid_aton() failure test result
+ *
+ * @v text             Textual representation
+ * @v file             Test code file
+ * @v line             Test code line
+ */
+static void uuid_aton_fail_okx ( const char *text, const char *file,
+                                unsigned int line ) {
+       union uuid actual;
+
+       /* Attempt to parse address */
+       okx ( uuid_aton ( text, &actual ) != 0, file, line );
+}
+#define uuid_aton_fail_ok( text ) \
+       uuid_aton_fail_okx ( text, __FILE__, __LINE__ )
+
+/**
+ * Perform UUID self-tests
+ *
+ */
+static void uuid_test_exec ( void ) {
+
+       /* uuid_ntoa() tests */
+       uuid_ntoa_ok ( UUID ( 0x18725ca6, 0xd699, 0x4e4d, 0xb501,
+                             0xc3, 0x80, 0x91, 0xd2, 0xa4, 0x33 ),
+                      "18725ca6-d699-4e4d-b501-c38091d2a433" );
+       uuid_ntoa_ok ( UUID ( 0x1a969b23, 0xc7d5, 0x40fe, 0xb79a,
+                             0xc9, 0x2e, 0xa3, 0x4a ,0xb4, 0x5b ),
+                      "1a969b23-c7d5-40fe-b79a-c92ea34ab45b" );
+
+       /* uuid_aton() tests */
+       uuid_aton_ok ( "62b907a8-e1a7-460e-82f7-667d84270c84",
+                      UUID ( 0x62b907a8, 0xe1a7, 0x460e, 0x82f7,
+                             0x66, 0x7d, 0x84, 0x27, 0x0c, 0x84 ) );
+       uuid_aton_ok ( "F5D0349C-EF7C-4AD4-B40B-FC2E522A7327",
+                      UUID ( 0xf5d0349c, 0xef7c, 0x4ad4, 0xb40b,
+                             0xfc, 0x2e, 0x52, 0x2a, 0x73, 0x27 ) );
+       uuid_aton_ok ( "4edd80ff7b43465589a02b1e7cffa196",
+                      UUID ( 0x4edd80ff, 0x7b43, 0x4655, 0x89a0,
+                             0x2b, 0x1e, 0x7c, 0xff, 0xa1, 0x96 ) );
+
+       /* uuid_aton() failure tests */
+       uuid_aton_fail_ok ( "628d677b-cf38-471e-9ad9-c8a5d9220055b6" );
+       uuid_aton_fail_ok ( "5071ca26-fc5f-4580-887a-46d9a103e4" );
+       uuid_aton_fail_ok ( "453aee96:0fb5-4aeb-aecd-d060b2121218" );
+       uuid_aton_fail_ok ( "1ccb524a-b8b9-4b17-x5e2-7996867edc7d" );
+       uuid_aton_fail_ok ( "" );
+}
+
+/** UUID self-test */
+struct self_test uuid_test __self_test = {
+       .name = "uuid",
+       .exec = uuid_test_exec,
+};