src/libstrongswan/utils/identification.h

   1 /*
   2  * Copyright (C) 2009-2015 Tobias Brunner
   3  * Copyright (C) 2005-2009 Martin Willi
   4  * Copyright (C) 2005 Jan Hutter
   5  *
   6  * Copyright (C) secunet Security Networks AG
   7  *
   8  * This program is free software; you can redistribute it and/or modify it
   9  * under the terms of the GNU General Public License as published by the
  10  * Free Software Foundation; either version 2 of the License, or (at your
  11  * option) any later version.  See <http://www.fsf.org/copyleft/gpl.txt>.
  12  *
  13  * This program is distributed in the hope that it will be useful, but
  14  * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
  15  * or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  16  * for more details.
  17  */
  18
  19 /**
  20  * @defgroup identification identification
  21  * @{ @ingroup utils
  22  */
  23
  24
  25 #ifndef IDENTIFICATION_H_
  26 #define IDENTIFICATION_H_
  27
  28 typedef enum id_type_t id_type_t;
  29 typedef struct identification_t identification_t;
  30 typedef enum id_match_t id_match_t;
  31 typedef enum id_part_t id_part_t;
  32
  33 #include <utils/chunk.h>
  34 #include <collections/enumerator.h>
  35
  36 /**
  37  * Matches returned from identification_t.match
  38  */
  39 enum id_match_t {
  40         /* no match */
  41         ID_MATCH_NONE = 0,
  42         /* match to %any ID */
  43         ID_MATCH_ANY = 1,
  44         /* match with maximum allowed wildcards */
  45         ID_MATCH_MAX_WILDCARDS = 2,
  46         /* match with only one wildcard */
  47         ID_MATCH_ONE_WILDCARD = 19,
  48         /* perfect match, won't get better */
  49         ID_MATCH_PERFECT = 20,
  50 };
  51
  52 /**
  53  * enum names for id_match_t.
  54  */
  55 extern enum_name_t *id_match_names;
  56
  57 /**
  58  * ID Types in a ID payload.
  59  */
  60 enum id_type_t {
  61
  62         /**
  63          * private type which matches any other id.
  64          */
  65         ID_ANY = 0,
  66
  67         /**
  68          * ID data is a single four (4) octet IPv4 address.
  69          */
  70         ID_IPV4_ADDR = 1,
  71
  72         /**
  73          * ID data is a fully-qualified domain name string.
  74          * An example of a ID_FQDN is "example.com".
  75          * The string MUST not contain any terminators (e.g., NULL, CR, etc.).
  76          */
  77         ID_FQDN = 2,
  78
  79         /**
  80          * ID data is a fully-qualified RFC822 email address string.
  81          * An example of an ID_RFC822_ADDR is "jsmith@example.com".
  82          * The string MUST NOT contain any terminators.
  83          */
  84         ID_USER_FQDN   = 3,     /* IKEv1 only */
  85         ID_RFC822_ADDR = 3,     /* IKEv2 only */
  86
  87         /**
  88          * ID data is an IPv4 subnet (IKEv1 only)
  89          */
  90         ID_IPV4_ADDR_SUBNET = 4,
  91
  92         /**
  93          * ID data is a single sixteen (16) octet IPv6 address.
  94          */
  95         ID_IPV6_ADDR = 5,
  96
  97         /**
  98          * ID data is an IPv6 subnet (IKEv1 only)
  99          */
 100         ID_IPV6_ADDR_SUBNET = 6,
 101
 102         /**
 103          * ID data is an IPv4 address range (IKEv1 only)
 104          */
 105         ID_IPV4_ADDR_RANGE = 7,
 106
 107         /**
 108          * ID data is an IPv6 address range (IKEv1 only)
 109          */
 110         ID_IPV6_ADDR_RANGE = 8,
 111
 112         /**
 113          * ID data is the binary DER encoding of an ASN.1 X.501 Distinguished Name
 114          */
 115         ID_DER_ASN1_DN = 9,
 116
 117         /**
 118          * ID data is the binary DER encoding of an ASN.1 X.509 GeneralName
 119          */
 120         ID_DER_ASN1_GN = 10,
 121
 122         /**
 123          * ID data is an opaque octet stream which may be used to pass vendor-
 124          * specific information necessary to do certain proprietary
 125          * types of identification.
 126          */
 127         ID_KEY_ID = 11,
 128
 129         /**
 130          * Private ID type which represents a GeneralName of type URI
 131          */
 132         ID_DER_ASN1_GN_URI = 201,
 133 };
 134
 135 /**
 136  * enum names for id_type_t.
 137  */
 138 extern enum_name_t *id_type_names;
 139
 140 /**
 141  * Type of an ID sub part.
 142  */
 143 enum id_part_t {
 144         /** Username part of an RFC822_ADDR */
 145         ID_PART_USERNAME,
 146         /** Domain part of an RFC822_ADDR */
 147         ID_PART_DOMAIN,
 148
 149         /** Top-Level domain of a FQDN */
 150         ID_PART_TLD,
 151         /** Second-Level domain of a FQDN */
 152         ID_PART_SLD,
 153         /** Another Level domain of a FQDN */
 154         ID_PART_ALD,
 155
 156         /** Country RDN of a DN */
 157         ID_PART_RDN_C,
 158         /** CommonName RDN of a DN */
 159         ID_PART_RDN_CN,
 160         /** Description RDN of a DN */
 161         ID_PART_RDN_D,
 162         /** Email RDN of a DN */
 163         ID_PART_RDN_E,
 164         /** EmployeeNumber RDN of a DN */
 165         ID_PART_RDN_EN,
 166         /** GivenName RDN of a DN */
 167         ID_PART_RDN_G,
 168         /** Initials RDN of a DN */
 169         ID_PART_RDN_I,
 170         /** DN Qualifier RDN of a DN */
 171         ID_PART_RDN_DNQ,
 172         /** dmdName RDN of a DN */
 173         ID_PART_RDN_DMDN,
 174         /** Pseudonym RDN of a DN */
 175         ID_PART_RDN_PN,
 176         /** UniqueIdentifier RDN of a DN */
 177         ID_PART_RDN_ID,
 178         /** Locality RDN of a DN */
 179         ID_PART_RDN_L,
 180         /** Name RDN of a DN */
 181         ID_PART_RDN_N,
 182         /** Organization RDN of a DN */
 183         ID_PART_RDN_O,
 184         /** OrganizationUnit RDN of a DN */
 185         ID_PART_RDN_OU,
 186         /** Surname RDN of a DN */
 187         ID_PART_RDN_SN,
 188         /** SerialNumber RDN of a DN */
 189         ID_PART_RDN_SERIAL_NUMBER,
 190         /** StateOrProvince RDN of a DN */
 191         ID_PART_RDN_ST,
 192         /** Title RDN of a DN */
 193         ID_PART_RDN_T,
 194 };
 195
 196 /**
 197  * Generic identification, such as used in ID payload.
 198  *
 199  * @todo Support for ID_DER_ASN1_GN is minimal right now. Comparison
 200  * between them and ID_IPV4_ADDR/RFC822_ADDR would be nice.
 201  */
 202 struct identification_t {
 203
 204         /**
 205          * Get the encoding of this id, to send over
 206          * the network.
 207          *
 208          * Result points to internal data, do not free.
 209          *
 210          * @return                      a chunk containing the encoded bytes
 211          */
 212         chunk_t (*get_encoding) (identification_t *this);
 213
 214         /**
 215          * Get the type of this identification.
 216          *
 217          * @return                      id_type_t
 218          */
 219         id_type_t (*get_type) (identification_t *this);
 220
 221         /**
 222          * Create a hash value for this identification_t object.
 223          *
 224          * @param inc           optional value for incremental hashing
 225          * @return                      hash value
 226          */
 227         u_int (*hash) (identification_t *this, u_int inc);
 228
 229         /**
 230          * Check if two identification_t objects are equal.
 231          *
 232          * @param other         other identification_t object
 233          * @return                      TRUE if the IDs are equal
 234          */
 235         bool (*equals) (identification_t *this, identification_t *other);
 236
 237         /**
 238          * Check if an ID matches a wildcard ID.
 239          *
 240          * An identification_t may contain wildcards, such as
 241          * *.strongswan.org. This call checks if a given ID
 242          * (e.g. tester.strongswan.org) belongs to a such wildcard
 243          * ID. Returns > 0 if
 244          * - IDs are identical
 245          * - other is of type ID_ANY
 246          * - other contains a wildcard and matches this
 247          *
 248          * The larger the return value is, the better is the match. Zero means
 249          * no match at all, 1 means a bad match, and 2 a slightly better match.
 250          *
 251          * @param other         the ID containing one or more wildcards
 252          * @return                      match value as described above
 253          */
 254         id_match_t (*matches) (identification_t *this, identification_t *other);
 255
 256         /**
 257          * Check if an ID is a wildcard ID.
 258          *
 259          * If the ID represents multiple IDs (with wildcards, or
 260          * as the type ID_ANY), TRUE is returned. If it is unique,
 261          * FALSE is returned.
 262          *
 263          * @return                      TRUE if ID contains wildcards
 264          */
 265         bool (*contains_wildcards) (identification_t *this);
 266
 267         /**
 268          * Create an enumerator over subparts of an identity.
 269          *
 270          * Some identities are built from several parts, e.g. an E-Mail consists
 271          * of a username and a domain part, or a DistinguishedName contains several
 272          * RDNs.
 273          * For identity without subtypes (support), an empty enumerator is
 274          * returned.
 275          *
 276          * @return                      an enumerator over (id_part_t type, chunk_t data)
 277          */
 278         enumerator_t* (*create_part_enumerator)(identification_t *this);
 279
 280         /**
 281          * Clone a identification_t instance.
 282          *
 283          * @return                      clone of this
 284          */
 285         identification_t *(*clone) (identification_t *this);
 286
 287         /**
 288          * Destroys a identification_t object.
 289          */
 290         void (*destroy) (identification_t *this);
 291 };
 292
 293 /**
 294  * Creates an identification_t object from a string.
 295  *
 296  * The input string may be e.g. one of the following:
 297  * - ID_IPV4_ADDR:              192.168.0.1
 298  * - ID_IPV6_ADDR:              2001:0db8:85a3:08d3:1319:8a2e:0370:7345
 299  * - ID_FQDN:                   www.strongswan.org (optionally with a prepended @)
 300  * - ID_RFC822_ADDR:    alice@wonderland.org
 301  * - ID_DER_ASN1_DN:    C=CH, O=Linux strongSwan, CN=bob
 302  *
 303  * In favor of pluto, domainnames are prepended with an @, since
 304  * pluto resolves domainnames without an @ to IPv4 addresses. Since
 305  * we use a separate host_t class for addresses, this doesn't
 306  * make sense for us.
 307  *
 308  * A distinguished name may contain one or more of the following RDNs:
 309  * ND, UID, DC, CN, S, SN, serialNumber, C, L, ST, O, OU, T, D,
 310  * N, G, I, dnQualifier, ID, EN, EmployeeNumber, E, Email, emailAddress, UN,
 311  * unstructuredName, TCGID.
 312  *
 313  * To skip automatic type detection the following prefixes may be used to
 314  * enforce a specific type: ipv4:, ipv6:, rfc822:, email:, userfqdn:, fqdn:,
 315  * dns:, asn1dn:, asn1gn: and keyid:. If a # follows the :, the remaining data
 316  * is interpreted as hex encoded binary data for that ID, otherwise the raw
 317  * string following the prefix is used as identity data, without conversion.
 318  * To specify a non-standard ID type, the numerical type may be prefixed
 319  * between curly brackets, building a prefix. For instance the "{1}:" prefix
 320  * defines an ID_IPV4_ADDR type.
 321  *
 322  * This constructor never returns NULL. If it does not find a suitable
 323  * conversion function, it will copy the string to an ID_KEY_ID.
 324  *
 325  * @param string        input string, which will be converted
 326  * @return                      identification_t
 327  */
 328 identification_t * identification_create_from_string(char *string);
 329
 330 /**
 331  * Creates an identification from a chunk of data, guessing its type.
 332  *
 333  * @param data          identification data
 334  * @return                      identification_t
 335  */
 336 identification_t * identification_create_from_data(chunk_t data);
 337
 338 /**
 339  * Creates an identification_t object from an encoded chunk.
 340  *
 341  * @param type          type of this id, such as ID_IPV4_ADDR
 342  * @param encoded       encoded bytes, such as from identification_t.get_encoding
 343  * @return                      identification_t
 344  */
 345 identification_t * identification_create_from_encoding(id_type_t type, chunk_t encoded);
 346
 347 /**
 348  * Creates an identification_t object from a sockaddr struct
 349  *
 350  * @param sockaddr              sockaddr struct which contains family and address
 351  * @return                              identification_t
 352  */
 353 identification_t * identification_create_from_sockaddr(sockaddr_t *sockaddr);
 354
 355 /**
 356  * printf hook function for identification_t.
 357  *
 358  * Arguments are:
 359  *      identification_t *identification
 360  */
 361 int identification_printf_hook(printf_hook_data_t *data,
 362                                                         printf_hook_spec_t *spec, const void *const *args);
 363
 364 #endif /** IDENTIFICATION_H_ @}*/