(no commit message)
[strongswan.git] / src / libstrongswan / utils / identification.h
1 /**
2 * @file identification.h
3 *
4 * @brief Interface of identification_t.
5 *
6 */
7
8 /*
9 * Copyright (C) 2005-2006 Martin Willi
10 * Copyright (C) 2005 Jan Hutter
11 * Hochschule fuer Technik Rapperswil
12 *
13 * This program is free software; you can redistribute it and/or modify it
14 * under the terms of the GNU General Public License as published by the
15 * Free Software Foundation; either version 2 of the License, or (at your
16 * option) any later version. See <http://www.fsf.org/copyleft/gpl.txt>.
17 *
18 * This program is distributed in the hope that it will be useful, but
19 * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
20 * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
21 * for more details.
22 */
23
24
25 #ifndef IDENTIFICATION_H_
26 #define IDENTIFICATION_H_
27
28 #include "types.h"
29
30 #define MAX_WILDCARDS 14
31 /**
32 * printf() specifier to print a identification.
33 */
34 #define IDENTIFICATION_PRINTF_SPEC 'D'
35
36 typedef enum id_type_t id_type_t;
37
38 /**
39 * @brief ID Types in a ID payload.
40 *
41 * @ingroup utils
42 */
43 enum id_type_t {
44
45 /**
46 * private type which matches any other id.
47 */
48 ID_ANY = 0,
49
50 /**
51 * ID data is a single four (4) octet IPv4 address.
52 */
53 ID_IPV4_ADDR = 1,
54
55 /**
56 * ID data is a fully-qualified domain name string.
57 * An example of a ID_FQDN is "example.com".
58 * The string MUST not contain any terminators (e.g., NULL, CR, etc.).
59 */
60 ID_FQDN = 2,
61
62 /**
63 * ID data is a fully-qualified RFC822 email address string.
64 * An example of an ID_RFC822_ADDR is "jsmith@example.com".
65 * The string MUST NOT contain any terminators.
66 */
67 ID_RFC822_ADDR = 3,
68
69 /**
70 * ID data is an IPv4 subnet (IKEv1 only)
71 */
72 ID_IPV4_ADDR_SUBNET = 4,
73
74 /**
75 * ID data is a single sixteen (16) octet IPv6 address.
76 */
77 ID_IPV6_ADDR = 5,
78
79 /**
80 * ID data is an IPv6 subnet (IKEv1 only)
81 */
82 ID_IPV6_ADDR_SUBNET = 6,
83
84 /**
85 * ID data is an IPv4 address range (IKEv1 only)
86 */
87 ID_IPV4_ADDR_RANGE = 7,
88
89 /**
90 * ID data is an IPv6 address range (IKEv1 only)
91 */
92 ID_IPV6_ADDR_RANGE = 8,
93
94 /**
95 * ID data is the binary DER encoding of an ASN.1 X.501 Distinguished Name
96 */
97 ID_DER_ASN1_DN = 9,
98
99 /**
100 * ID data is the binary DER encoding of an ASN.1 X.509 GeneralName
101 */
102 ID_DER_ASN1_GN = 10,
103
104 /**
105 * ID data is an opaque octet stream which may be used to pass vendor-
106 * specific information necessary to do certain proprietary
107 * types of identification.
108 */
109 ID_KEY_ID = 11,
110
111 /**
112 * private type which represents a GeneralName of type URI
113 */
114 ID_DER_ASN1_GN_URI = 201,
115
116 };
117
118 /**
119 * String mappings for id_type_t.
120 */
121 extern enum_names id_type_names;
122
123 typedef struct identification_t identification_t;
124
125 /**
126 * @brief Generic identification, such as used in ID payload.
127 *
128 * The following types are possible:
129 * - ID_IPV4_ADDR
130 * - ID_FQDN
131 * - ID_RFC822_ADDR
132 * - ID_IPV6_ADDR
133 * - ID_DER_ASN1_DN
134 * - ID_DER_ASN1_GN
135 * - ID_KEY_ID
136 * - ID_DER_ASN1_GN_URI
137 *
138 * @b Constructors:
139 * - identification_create_from_string()
140 * - identification_create_from_encoding()
141 *
142 * @todo Support for ID_DER_ASN1_GN is minimal right now. Comparison
143 * between them and ID_IPV4_ADDR/RFC822_ADDR would be nice.
144 *
145 * @ingroup utils
146 */
147 struct identification_t {
148
149 /**
150 * @brief Get the encoding of this id, to send over
151 * the network.
152 *
153 * @warning Result points to internal data, do NOT free!
154 *
155 * @param this the identification_t object
156 * @return a chunk containing the encoded bytes
157 */
158 chunk_t (*get_encoding) (identification_t *this);
159
160 /**
161 * @brief Get the type of this identification.
162 *
163 * @param this the identification_t object
164 * @return id_type_t
165 */
166 id_type_t (*get_type) (identification_t *this);
167
168 /**
169 * @brief Check if two identification_t objects are equal.
170 *
171 * @param this the identification_t object
172 * @param other other identification_t object
173 * @return TRUE if the IDs are equal
174 */
175 bool (*equals) (identification_t *this, identification_t *other);
176
177 /**
178 * @brief Check if an ID matches a wildcard ID.
179 *
180 * An identification_t may contain wildcards, such as
181 * *@strongswan.org. This call checks if a given ID
182 * (e.g. tester@strongswan.org) belongs to a such wildcard
183 * ID. Returns TRUE if
184 * - IDs are identical
185 * - other is of type ID_ANY
186 * - other contains a wildcard and matches this
187 *
188 * @param this the ID without wildcard
189 * @param other the ID containing a wildcard
190 * @param wildcards returns the number of wildcards
191 * @return TRUE if match is found
192 */
193 bool (*matches) (identification_t *this, identification_t *other, int *wildcards);
194
195 /**
196 * @brief Check if an ID is a wildcard ID.
197 *
198 * If the ID represents multiple IDs (with wildcards, or
199 * as the type ID_ANY), TRUE is returned. If it is unique,
200 * FALSE is returned.
201 *
202 * @param this identification_t object
203 * @return TRUE if ID contains wildcards
204 */
205 bool (*contains_wildcards) (identification_t *this);
206
207 /**
208 * @brief Clone a identification_t instance.
209 *
210 * @param this the identification_t object to clone
211 * @return clone of this
212 */
213 identification_t *(*clone) (identification_t *this);
214
215 /**
216 * @brief Destroys a identification_t object.
217 *
218 * @param this identification_t object
219 */
220 void (*destroy) (identification_t *this);
221 };
222
223 /**
224 * @brief Creates an identification_t object from a string.
225 *
226 * @param string input string, which will be converted
227 * @return
228 * - created identification_t object, or
229 * - NULL if unsupported string supplied.
230 *
231 * The input string may be e.g. one of the following:
232 * - ID_IPV4_ADDR: 192.168.0.1
233 * - ID_IPV6_ADDR: 2001:0db8:85a3:08d3:1319:8a2e:0370:7345
234 * - ID_FQDN: @www.strongswan.org (@indicates FQDN)
235 * - ID_RFC822_ADDR: alice@wonderland.org
236 * - ID_DER_ASN1_DN: C=CH, O=Linux strongSwan, CN=bob
237 *
238 * In favour of pluto, domainnames are prepended with an @, since
239 * pluto resolves domainnames without an @ to IPv4 addresses. Since
240 * we use a seperate host_t class for addresses, this doesn't
241 * make sense for us.
242 *
243 * A distinguished name may contain one or more of the following RDNs:
244 * ND, UID, DC, CN, S, SN, serialNumber, C, L, ST, O, OU, T, D,
245 * N, G, I, ID, EN, EmployeeNumber, E, Email, emailAddress, UN,
246 * unstructuredName, TCGID.
247 *
248 * @ingroup utils
249 */
250 identification_t * identification_create_from_string(char *string);
251
252 /**
253 * @brief Creates an identification_t object from an encoded chunk.
254 *
255 * @param type type of this id, such as ID_IPV4_ADDR
256 * @param encoded encoded bytes, such as from identification_t.get_encoding
257 * @return identification_t object
258 *
259 * In contrast to identification_create_from_string(), this constructor never
260 * returns NULL, even when the conversion to a string representation fails.
261 *
262 * @ingroup utils
263 */
264 identification_t * identification_create_from_encoding(id_type_t type, chunk_t encoded);
265
266 #endif /* IDENTIFICATION_H_ */