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