1 /**
2  * Copyright(c) 2012 Trusted Logic.   All rights reserved.
3  *
4  * Redistribution and use in source and binary forms, with or without
5  * modification, are permitted provided that the following conditions
6  * are met:
7  *
8  *  * Redistributions of source code must retain the above copyright
9  *    notice, this list of conditions and the following disclaimer.
10  *  * Redistributions in binary form must reproduce the above copyright
11  *    notice, this list of conditions and the following disclaimer in
12  *    the documentation and/or other materials provided with the
13  *    distribution.
14  *  * Neither the name Trusted Logic nor the names of its
15  *    contributors may be used to endorse or promote products derived
16  *    from this software without specific prior written permission.
17  *
18  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
19  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
20  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
21  * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
22  * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
23  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
24  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
25  * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
26  * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
27  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
28  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
29  */
30 
31 #ifndef __LIB_UUID_H__
32 #define __LIB_UUID_H__
33 
34 
35 #include "s_type.h"
36 
37 
38 #ifdef __cplusplus
39 extern "C" {
40 #endif
41 #if 0
42 }  /* balance curly quotes */
43 #endif
44 
45 /**
46  * LIB_UUID is deprecated use S_UUID instead.
47  * @deprecated
48  */
49 typedef S_UUID LIB_UUID;
50 /**
51  * LIB_UUID_STRING_SIZE is deprecated use UUID_STRING_SIZE instead.
52  * @deprecated
53  */
54 #define LIB_UUID_STRING_SIZE  36
55 
56 /**
57  * Defines the UUID string size in characters
58  *
59  * E.g. "f81d4fae-7dec-11d0-a765-00a0c91e6bf6"
60  **/
61 #define UUID_STRING_SIZE  36
62 
63 /**
64  * Converts the string representation of an UUID to the binary representation as
65  * a S_UUID type. The binary UUID structure must be provided by the caller.
66  *
67  * @param   pIdentifierString  The UTF-8 representation of the identifier. This
68  *          string does not need to be zero terminated. The decoder reads only
69  *          the {UUID_STRING_SIZE} first bytes.
70  *
71  * @param   pIdentifier  The identifer structure receiving the binary value of
72  *          the identifier.
73  *
74  * @return  TRUE in case of success, FALSE if the string does not conform to the
75  *          syntax of UUID as defined in RFC 4122
76  *          (http://www.ietf.org/rfc/rfc4122.txt)
77  **/
78 bool libUUIDFromString(
79       IN  const uint8_t* pIdentifierString,
80       OUT S_UUID* pIdentifier);
81 
82 /**
83  * Converts the binary representation of an UUID to the string representation.
84  *
85  * @param   pIdentifier  The identifer structure with the binary value of the
86  *          identifier.
87  *
88  * @param   pIdentifierString  The buffer receiving the UTF-8 representation of
89  *          the identifier. This string is not zero terminated. The encoder
90  *          writes only the first {UUID_STRING_SIZE} bytes.
91  *
92  **/
93 void libUUIDToString(
94       IN  const S_UUID* pIdentifier,
95       OUT uint8_t* pIdentifierString);
96 
97 /**
98  * Generates an UUID from the specified MD5 hash value, as specified in section
99  * 4.3, Algorithm for Creating a Name-Based UUID, of RFC 4122.
100  *
101  * This function assumes that the hash value is 128-bit long.
102  *
103  * @param pHashData A pointer to the first byte of the MD5 hash data. Only the
104  * first 16 bytes of this hash data will be used to generate the UUID.
105  *
106  * @param pIdentifier A pointer to the placeholder receiving the generated
107  * identifier.
108  **/
109 void libUUIDFromMD5Hash(
110       IN  const uint8_t* pHashData,
111       OUT S_UUID* pIdentifier);
112 
113 /**
114  * Generates an UUID from the specified SHA-1 hash value, as specified in
115  * section 4.3, Algorithm for Creating a Name-Based UUID, of RFC 4122.
116  *
117  * This function assumes that the hash value is 128-bit long.
118  *
119  * @param pHashData A pointer to the first byte of the SHA-1 hash data. Only the
120  * first 16 bytes of this hash data will be used to generate the UUID.
121  *
122  * @param pIdentifier A pointer to the placeholder receiving the generated
123  * identifier.
124  **/
125 void libUUIDFromSHA1Hash(
126       IN  const uint8_t* pHashData,
127       OUT S_UUID* pIdentifier);
128 
129 /**
130  * Checks if an identifier is the nil identifier as specified in RFC 4122.
131  *
132  * @param   pIdentifier  The identifier to check.
133  *
134  * @return  TRUE if the identifier is the nil identifier, FALSE otherwise.
135  **/
136 bool libUUIDIsNil(
137       IN  const S_UUID* pIdentifier);
138 
139 /**
140  * Sets an identifier to the nil value as specified in RFC 4122.
141  *
142  * @param   pIdentifier  The identifier to set to nil.
143  **/
144 void libUUIDSetToNil(
145       OUT S_UUID* pIdentifier);
146 
147 #if 0
148 {  /* balance curly quotes */
149 #endif
150 #ifdef __cplusplus
151 }  /* closes extern "C" */
152 #endif
153 
154 
155 #endif  /* !defined(__LIB_UUID_H__) */
156