UDIF: Universal Digital Identification Framework 1.0.0.0a (A1)
A quantum-secure cryptographic identification
topology.h
Go to the documentation of this file.
1/* 2025 Quantum Resistant Cryptographic Solutions Corporation
2 * All Rights Reserved.
3 *
4 * NOTICE: This software and all accompanying materials are the exclusive
5 * property of Quantum Resistant Cryptographic Solutions Corporation (QRCS).
6 * The intellectual and technical concepts contained within this implementation
7 * are proprietary to QRCS and its authorized licensors and are protected under
8 * applicable U.S. and international copyright, patent, and trade secret laws.
9 *
10 * CRYPTOGRAPHIC STANDAARS:
11 * - This software includes implementations of cryptographic algorithms such as
12 * SHA3, AES, and others. These algorithms are public domain or standardized
13 * by organizations such as NIST and are NOT the property of QRCS.
14 * - However, all source code, optimizations, and implementations in this library
15 * are original works of QRCS and are protected under this license.
16 *
17 * RESTRICTIONS:
18 * - Redistribution, modification, or unauthorized distribution of this software,
19 * in whole or in part, is strictly prohibited.
20 * - This software is provided for non-commercial, educational, and research
21 * purposes only. Commercial use in any form is expressly forbidden.
22 * - Licensing and authorized distribution are solely at the discretion of QRCS.
23 * - Any use of this software implies acceptance of these restrictions.
24 *
25 * DISCLAIMER:
26 * This software is provided "as is," without warranty of any kind, express or
27 * implied, including but not limited to warranties of merchantability or fitness
28 * for a particular purpose. QRCS disclaims all liability for any direct, indirect,
29 * incidental, or consequential damages resulting from the use or misuse of this software.
30 *
31 * FULL LICENSE:
32 * This software is subject to the **Quantum Resistant Cryptographic Solutions
33 * Proprietary License (QRCS-PL)**. The complete license terms are included
34 * in the LICENSE.txt file distributed with this software.
35 *
36 * Written by: John G. Underhill
37 * Contact: contact@qrcscorp.ca
38 */
39
40#ifndef UDIF_TOPOLOGY_H
41#define UDIF_TOPOLOGY_H
42
43#include "udif.h"
44#include "certificate.h"
45#include "ipinfo.h"
46#include "list.h"
47#include "timestamp.h"
48
80
81/*---------------------------------------------------------------------------
82 MACRO DEFINITIONS
83---------------------------------------------------------------------------*/
84
92#if defined(UDIF_NETWORK_PROTOCOL_IPV6)
93# define UDIF_TOPOLOGY_NODE_ENCODED_SIZE (UDIF_CHILD_CERTIFICATE_ISSUER_PREFIX_SIZE + UDIF_CERTIFICATE_ISSUER_SIZE + UDIF_CERTIFICATE_SEPERATOR_SIZE + \
94 UDIF_CHILD_CERTIFICATE_ADDRESS_PREFIX_SIZE + QSC_IPINFO_IPV6_STRNLEN + UDIF_CERTIFICATE_SEPERATOR_SIZE + \
95 UDIF_ROOT_CERTIFICATE_HASH_PREFIX_SIZE + (UDIF_CERTIFICATE_HASH_SIZE * 2U) + UDIF_CERTIFICATE_SEPERATOR_SIZE + \
96 UDIF_CHILD_CERTIFICATE_SERIAL_PREFIX_SIZE + (UDIF_CERTIFICATE_SERIAL_SIZE * 2U) + UDIF_CERTIFICATE_SEPERATOR_SIZE + \
97 UDIF_CHILD_CERTIFICATE_DESIGNATION_PREFIX + UDIF_NETWORK_DESIGNATION_SIZE + UDIF_CERTIFICATE_SEPERATOR_SIZE + \
98 UDIF_CHILD_CERTIFICATE_VALID_FROM_PREFIX_SIZE + QSC_TIMESTAMP_STRING_SIZE + UDIF_CERTIFICATE_SEPERATOR_SIZE + \
99 UDIF_CHILD_CERTIFICATE_EXPIRATION_TO_PREFIX_SIZE + QSC_TIMESTAMP_STRING_SIZE + UDIF_CERTIFICATE_SEPERATOR_SIZE)
100#else
101# define UDIF_TOPOLOGY_NODE_ENCODED_SIZE (UDIF_CHILD_CERTIFICATE_ISSUER_PREFIX_SIZE + UDIF_CERTIFICATE_ISSUER_SIZE + UDIF_CERTIFICATE_SEPERATOR_SIZE + \
102 UDIF_CHILD_CERTIFICATE_ADDRESS_PREFIX_SIZE + QSC_IPINFO_IPV4_STRNLEN + UDIF_CERTIFICATE_SEPERATOR_SIZE + \
103 UDIF_ROOT_CERTIFICATE_HASH_PREFIX_SIZE + (UDIF_CERTIFICATE_HASH_SIZE * 2U) + UDIF_CERTIFICATE_SEPERATOR_SIZE + \
104 UDIF_CHILD_CERTIFICATE_SERIAL_PREFIX_SIZE + (UDIF_CERTIFICATE_SERIAL_SIZE * 2U) + UDIF_CERTIFICATE_SEPERATOR_SIZE + \
105 UDIF_CHILD_CERTIFICATE_DESIGNATION_PREFIX_SIZE + UDIF_NETWORK_DESIGNATION_SIZE + UDIF_CERTIFICATE_SEPERATOR_SIZE + \
106 UDIF_CHILD_CERTIFICATE_VALID_FROM_PREFIX_SIZE + QSC_TIMESTAMP_STRING_SIZE + UDIF_CERTIFICATE_SEPERATOR_SIZE + \
107 UDIF_CHILD_CERTIFICATE_EXPIRATION_TO_PREFIX_SIZE + QSC_TIMESTAMP_STRING_SIZE + UDIF_CERTIFICATE_SEPERATOR_SIZE)
108#endif
109
114#define UDIF_TOPOLOGY_NODE_MINIMUM_ISSUER_SIZE 3U
115
120#define UDIF_TOPOLOGY_NODE_NOT_FOUND -1
121
126#define UDIF_NETWORK_TOPOLOGY_MAX_SIZE 1024U
127
132#define UDIF_NETWORK_TOPOLOGY_NODE_SIZE (UDIF_CERTIFICATE_ADDRESS_SIZE + \
133 UDIF_CERTIFICATE_HASH_SIZE + \
134 UDIF_CERTIFICATE_SERIAL_SIZE + \
135 UDIF_CERTIFICATE_ISSUER_SIZE + \
136 UDIF_CERTIFICATE_EXPIRATION_SIZE + \
137 UDIF_CERTIFICATE_DESIGNATION_SIZE)
138
139/*---------------------------------------------------------------------------
140 STATIC CONSTANTS
141---------------------------------------------------------------------------*/
142
146static const char UDIF_TOPOLOGY_NETWORK_DELIMITER[] = "/";
147
151static const char UDIF_TOPOLOGY_CTYPE_DELIMITER[] = ".";
152
156static const char UDIF_TOPOLOGY_ALIAS_DELIMITER[] = ":";
157
158/*---------------------------------------------------------------------------
159 DATA STRUCTURES
160---------------------------------------------------------------------------*/
161
177
184UDIF_EXPORT_API typedef struct udif_topology_list_state
185{
186 uint8_t* topology;
187 uint32_t count;
188} udif_topology_list_state;
189
190/*---------------------------------------------------------------------------
191 FUNCTION PROTOTYPES
192---------------------------------------------------------------------------*/
193
204UDIF_EXPORT_API void udif_topology_address_from_issuer(char* address, const char* issuer, const udif_topology_list_state* list);
205
214UDIF_EXPORT_API void udif_topology_node_add_alias(udif_topology_node_state* node, const char* alias);
215
225UDIF_EXPORT_API bool udif_topology_nodes_are_equal(const udif_topology_node_state* a, const udif_topology_node_state* b);
226
236UDIF_EXPORT_API uint8_t* udif_topology_child_add_empty_node(udif_topology_list_state* list);
237
246UDIF_EXPORT_API void udif_topology_child_add_item(udif_topology_list_state* list, const udif_topology_node_state* node);
247
259UDIF_EXPORT_API bool udif_topology_canonical_to_issuer_name(char* issuer, size_t isslen, const char* domain, const char* cname);
260
271UDIF_EXPORT_API bool udif_topology_issuer_to_canonical_name(char* cname, size_t namelen, const char* issuer);
272
282UDIF_EXPORT_API void udif_topology_child_register(udif_topology_list_state* list, const udif_child_certificate* ccert, const char* address);
283
292UDIF_EXPORT_API void udif_topology_list_clone(const udif_topology_list_state* tlist, udif_topology_list_state* tcopy);
293
303UDIF_EXPORT_API void udif_topology_list_deserialize(udif_topology_list_state* list, const uint8_t* input, size_t inplen);
304
312UDIF_EXPORT_API void udif_topology_list_dispose(udif_topology_list_state* list);
313
321UDIF_EXPORT_API void udif_topology_list_initialize(udif_topology_list_state* list);
322
333UDIF_EXPORT_API bool udif_topology_list_item(const udif_topology_list_state* list, udif_topology_node_state* node, size_t index);
334
343UDIF_EXPORT_API size_t udif_topology_list_remove_duplicates(udif_topology_list_state* list);
344
354UDIF_EXPORT_API size_t udif_topology_list_server_count(const udif_topology_list_state* list, udif_network_designations ntype);
355
365UDIF_EXPORT_API size_t udif_topology_list_serialize(uint8_t* output, const udif_topology_list_state* list);
366
375UDIF_EXPORT_API size_t udif_topology_list_size(const udif_topology_list_state* list);
376
387UDIF_EXPORT_API size_t udif_topology_list_to_string(const udif_topology_list_state* list, char* output, size_t outlen);
388
399UDIF_EXPORT_API size_t udif_topology_list_update_pack(uint8_t* output, const udif_topology_list_state* list, udif_network_designations ntype);
400
411UDIF_EXPORT_API size_t udif_topology_list_update_unpack(udif_topology_list_state* list, const uint8_t* input, size_t inplen);
412
424UDIF_EXPORT_API size_t udif_topology_ordered_server_list(udif_topology_list_state* olist, const udif_topology_list_state* tlist, udif_network_designations ntype);
425
433UDIF_EXPORT_API void udif_topology_node_clear(udif_topology_node_state* node);
434
443UDIF_EXPORT_API void udif_topology_node_copy(const udif_topology_node_state* source, udif_topology_node_state* destination);
444
453UDIF_EXPORT_API void udif_topology_node_deserialize(udif_topology_node_state* node, const uint8_t* input);
454
464UDIF_EXPORT_API size_t udif_topology_node_encode(const udif_topology_node_state* node, char output[UDIF_TOPOLOGY_NODE_ENCODED_SIZE]);
465
475UDIF_EXPORT_API bool udif_topology_node_exists(const udif_topology_list_state* list, const uint8_t* serial);
476
486UDIF_EXPORT_API int32_t udif_topology_node_get_index(const udif_topology_list_state* list, const uint8_t* serial);
487
498UDIF_EXPORT_API bool udif_topology_node_find(const udif_topology_list_state* list, udif_topology_node_state* node, const uint8_t* serial);
499
510UDIF_EXPORT_API bool udif_topology_node_find_address(const udif_topology_list_state* list, udif_topology_node_state* node, const char* address);
511
522UDIF_EXPORT_API bool udif_topology_node_find_alias(const udif_topology_list_state* list, udif_topology_node_state* node, const char* alias);
523
533UDIF_EXPORT_API bool udif_topology_node_find_ads(const udif_topology_list_state* list, udif_topology_node_state* node);
534
545UDIF_EXPORT_API bool udif_topology_node_find_issuer(const udif_topology_list_state* list, udif_topology_node_state* node, const char* issuer);
546
556UDIF_EXPORT_API bool udif_topology_node_find_root(const udif_topology_list_state* list, udif_topology_node_state* node);
557
566UDIF_EXPORT_API void udif_topology_node_remove(udif_topology_list_state* list, const uint8_t* serial);
567
576UDIF_EXPORT_API void udif_topology_node_remove_duplicate(udif_topology_list_state* list, const char* issuer);
577
587UDIF_EXPORT_API bool udif_topology_node_verify_ads(const udif_topology_list_state* list, const udif_child_certificate* ccert);
588
599UDIF_EXPORT_API bool udif_topology_node_verify_issuer(const udif_topology_list_state* list, const udif_child_certificate* ccert, const char* issuer);
600
610UDIF_EXPORT_API bool udif_topology_node_verify_root(const udif_topology_list_state* list, const udif_root_certificate* rcert);
611
621UDIF_EXPORT_API size_t udif_topology_node_serialize(uint8_t* output, const udif_topology_node_state* node);
622
632UDIF_EXPORT_API void udif_topology_root_register(udif_topology_list_state* list, const udif_root_certificate* rcert, const char* address);
633
642UDIF_EXPORT_API void udif_topology_from_file(const char* fpath, udif_topology_list_state* list);
643
652UDIF_EXPORT_API void udif_topology_to_file(const udif_topology_list_state* list, const char* fpath);
653
654#if defined(UDIF_DEBUG_MODE)
662UDIF_EXPORT_API bool udif_topology_functions_test();
663#endif
664
665#endif
certificate.h
UDIF Certificate Handling Functions.
udif_topology_list_state
The UDIF topology list structure.
Definition topology.h:185
udif_topology_list_state::topology
uint8_t * topology
Definition topology.h:186
udif_topology_list_state::count
uint32_t count
Definition topology.h:187
udif_topology_node_state
The UDIF topology node structure.
Definition topology.h:169
udif_topology_node_state::expiration
udif_certificate_expiration expiration
Definition topology.h:174
udif_topology_node_state::chash
uint8_t chash[UDIF_CERTIFICATE_HASH_SIZE]
Definition topology.h:171
udif_topology_node_state::address
char address[UDIF_CERTIFICATE_ADDRESS_SIZE]
Definition topology.h:170
udif_topology_node_state::serial
uint8_t serial[UDIF_CERTIFICATE_SERIAL_SIZE]
Definition topology.h:172
udif_topology_node_state::designation
udif_network_designations designation
Definition topology.h:175
udif_topology_node_state::issuer
char issuer[UDIF_CERTIFICATE_ISSUER_SIZE]
Definition topology.h:173
udif_topology_list_size
UDIF_EXPORT_API size_t udif_topology_list_size(const udif_topology_list_state *list)
Get the byte size of the serialized list.
Definition topology.c:449
udif_topology_node_verify_root
UDIF_EXPORT_API bool udif_topology_node_verify_root(const udif_topology_list_state *list, const udif_root_certificate *rcert)
Verify that the root certificate matches the hash stored in the topology.
Definition topology.c:1133
udif_topology_canonical_to_issuer_name
UDIF_EXPORT_API bool udif_topology_canonical_to_issuer_name(char *issuer, size_t isslen, const char *domain, const char *cname)
Translate a canonical name to an issuer name.
Definition topology.c:109
udif_topology_node_verify_issuer
UDIF_EXPORT_API bool udif_topology_node_verify_issuer(const udif_topology_list_state *list, const udif_child_certificate *ccert, const char *issuer)
Verify that an issuing node's certificate matches the hash stored in the topology.
Definition topology.c:1107
udif_topology_node_find_alias
UDIF_EXPORT_API bool udif_topology_node_find_alias(const udif_topology_list_state *list, udif_topology_node_state *node, const char *alias)
Return the node pointer in the list matching the alias string.
Definition topology.c:785
udif_topology_address_from_issuer
UDIF_EXPORT_API void udif_topology_address_from_issuer(char *address, const char *issuer, const udif_topology_list_state *list)
Returns an IP address from an issuer string.
Definition topology.c:12
udif_topology_list_clone
UDIF_EXPORT_API void udif_topology_list_clone(const udif_topology_list_state *tlist, udif_topology_list_state *tcopy)
Clone a topology list.
Definition topology.c:220
udif_topology_node_remove
UDIF_EXPORT_API void udif_topology_node_remove(udif_topology_list_state *list, const uint8_t *serial)
Find and remove a node from the topology.
Definition topology.c:987
udif_topology_node_find
UDIF_EXPORT_API bool udif_topology_node_find(const udif_topology_list_state *list, udif_topology_node_state *node, const uint8_t *serial)
Return the node pointer in the list matching the serial number.
Definition topology.c:711
udif_topology_list_dispose
UDIF_EXPORT_API void udif_topology_list_dispose(udif_topology_list_state *list)
Dispose of the topology list and release memory.
Definition topology.c:267
udif_topology_list_deserialize
UDIF_EXPORT_API void udif_topology_list_deserialize(udif_topology_list_state *list, const uint8_t *input, size_t inplen)
Deserialize a topology list.
Definition topology.c:235
udif_topology_to_file
UDIF_EXPORT_API void udif_topology_to_file(const udif_topology_list_state *list, const char *fpath)
Copy a topology list to a file.
Definition topology.c:1328
udif_topology_list_initialize
UDIF_EXPORT_API void udif_topology_list_initialize(udif_topology_list_state *list)
Initialize the topology list.
Definition topology.c:283
udif_topology_node_encode
UDIF_EXPORT_API size_t udif_topology_node_encode(const udif_topology_node_state *node, char output[UDIF_TOPOLOGY_NODE_ENCODED_SIZE])
Encode a topological node into a printable string.
udif_topology_ordered_server_list
UDIF_EXPORT_API size_t udif_topology_ordered_server_list(udif_topology_list_state *olist, const udif_topology_list_state *tlist, udif_network_designations ntype)
Return a list of nodes of a type, sorted by serial number.
Definition topology.c:527
udif_topology_list_remove_duplicates
UDIF_EXPORT_API size_t udif_topology_list_remove_duplicates(udif_topology_list_state *list)
Remove duplicate nodes from the topology.
Definition topology.c:320
udif_topology_root_register
UDIF_EXPORT_API void udif_topology_root_register(udif_topology_list_state *list, const udif_root_certificate *rcert, const char *address)
Register a root to a topology list.
Definition topology.c:1158
udif_topology_child_add_item
UDIF_EXPORT_API void udif_topology_child_add_item(udif_topology_list_state *list, const udif_topology_node_state *node)
Add a node to the topology list.
Definition topology.c:87
udif_topology_list_serialize
UDIF_EXPORT_API size_t udif_topology_list_serialize(uint8_t *output, const udif_topology_list_state *list)
Serialize a topology list.
Definition topology.c:420
udif_topology_nodes_are_equal
UDIF_EXPORT_API bool udif_topology_nodes_are_equal(const udif_topology_node_state *a, const udif_topology_node_state *b)
Compare two topological nodes for equality.
Definition topology.c:618
UDIF_TOPOLOGY_NODE_ENCODED_SIZE
#define UDIF_TOPOLOGY_NODE_ENCODED_SIZE
The size of an encoded node string.
Definition topology.h:101
udif_topology_list_update_unpack
UDIF_EXPORT_API size_t udif_topology_list_update_unpack(udif_topology_list_state *list, const uint8_t *input, size_t inplen)
Unpack a node update set to the topology list.
Definition topology.c:497
udif_topology_list_update_pack
UDIF_EXPORT_API size_t udif_topology_list_update_pack(uint8_t *output, const udif_topology_list_state *list, udif_network_designations ntype)
Pack a node update set to an array.
Definition topology.c:468
udif_topology_node_get_index
UDIF_EXPORT_API int32_t udif_topology_node_get_index(const udif_topology_list_state *list, const uint8_t *serial)
Find the index number of a node in an array.
Definition topology.c:958
udif_topology_node_find_issuer
UDIF_EXPORT_API bool udif_topology_node_find_issuer(const udif_topology_list_state *list, udif_topology_node_state *node, const char *issuer)
Return the node pointer in the list matching the name string.
Definition topology.c:858
udif_topology_from_file
UDIF_EXPORT_API void udif_topology_from_file(const char *fpath, udif_topology_list_state *list)
Copy a topology list from a file.
Definition topology.c:1299
udif_topology_list_item
UDIF_EXPORT_API bool udif_topology_list_item(const udif_topology_list_state *list, udif_topology_node_state *node, size_t index)
Get a node from the index.
Definition topology.c:294
udif_topology_list_server_count
UDIF_EXPORT_API size_t udif_topology_list_server_count(const udif_topology_list_state *list, udif_network_designations ntype)
Get the count of a type of node in the database.
Definition topology.c:393
udif_topology_node_deserialize
UDIF_EXPORT_API void udif_topology_node_deserialize(udif_topology_node_state *node, const uint8_t *input)
Deserialize a topological node.
Definition topology.c:686
udif_topology_node_find_ads
UDIF_EXPORT_API bool udif_topology_node_find_ads(const udif_topology_list_state *list, udif_topology_node_state *node)
Return the ADC node from the list.
Definition topology.c:822
udif_topology_node_remove_duplicate
UDIF_EXPORT_API void udif_topology_node_remove_duplicate(udif_topology_list_state *list, const char *issuer)
Remove a node from the topology with the same issuer name.
Definition topology.c:1035
udif_topology_list_to_string
UDIF_EXPORT_API size_t udif_topology_list_to_string(const udif_topology_list_state *list, char *output, size_t outlen)
Convert the topology list to a printable string.
Definition topology.c:1181
udif_topology_node_copy
UDIF_EXPORT_API void udif_topology_node_copy(const udif_topology_node_state *source, udif_topology_node_state *destination)
Copy a source node to a destination node structure.
Definition topology.c:669
udif_topology_node_serialize
UDIF_EXPORT_API size_t udif_topology_node_serialize(uint8_t *output, const udif_topology_node_state *node)
Serialize a topological node structure, including the mfk.
Definition topology.c:1052
udif_topology_node_find_root
UDIF_EXPORT_API bool udif_topology_node_find_root(const udif_topology_list_state *list, udif_topology_node_state *node)
Return the ARS server node from the list.
Definition topology.c:905
udif_topology_node_add_alias
UDIF_EXPORT_API void udif_topology_node_add_alias(udif_topology_node_state *node, const char *alias)
Add an alias string to an issuer path.
Definition topology.c:585
udif_topology_child_register
UDIF_EXPORT_API void udif_topology_child_register(udif_topology_list_state *list, const udif_child_certificate *ccert, const char *address)
Register a child to a topology list.
Definition topology.c:187
udif_topology_node_find_address
UDIF_EXPORT_API bool udif_topology_node_find_address(const udif_topology_list_state *list, udif_topology_node_state *node, const char *address)
Return the node pointer in the list matching the address string.
Definition topology.c:748
udif_topology_issuer_to_canonical_name
UDIF_EXPORT_API bool udif_topology_issuer_to_canonical_name(char *cname, size_t namelen, const char *issuer)
Translate an issuer name to a canonical name.
Definition topology.c:147
udif_topology_node_clear
UDIF_EXPORT_API void udif_topology_node_clear(udif_topology_node_state *node)
Erase a node structure.
Definition topology.c:653
udif_topology_node_verify_ads
UDIF_EXPORT_API bool udif_topology_node_verify_ads(const udif_topology_list_state *list, const udif_child_certificate *ccert)
Verify that the ADC certificate matches the hash stored in the topology.
Definition topology.c:1082
udif_topology_node_exists
UDIF_EXPORT_API bool udif_topology_node_exists(const udif_topology_list_state *list, const uint8_t *serial)
Queries on the serial number if the node is in the database.
Definition topology.c:941
udif_topology_child_add_empty_node
UDIF_EXPORT_API uint8_t * udif_topology_child_add_empty_node(udif_topology_list_state *list)
Get an empty node pointer from the topology list.
Definition topology.c:43
udif.h
UDIF Common Definitions and Core Library Configuration.
UDIF_CERTIFICATE_HASH_SIZE
#define UDIF_CERTIFICATE_HASH_SIZE
The size of the certificate hash in bytes.
Definition udif.h:892
UDIF_CERTIFICATE_ADDRESS_SIZE
#define UDIF_CERTIFICATE_ADDRESS_SIZE
The maximum IP address length.
Definition udif.h:862
udif_network_designations
udif_network_designations
The UDIF device designation.
Definition udif.h:1297
UDIF_CERTIFICATE_SERIAL_SIZE
#define UDIF_CERTIFICATE_SERIAL_SIZE
The certificate serial number field length.
Definition udif.h:923
UDIF_CERTIFICATE_ISSUER_SIZE
#define UDIF_CERTIFICATE_ISSUER_SIZE
The maximum certificate issuer string length. The last character must be a string terminator.
Definition udif.h:899