include/asterisk/dundi.h

   1 /*
   2  * Asterisk -- An open source telephony toolkit.
   3  *
   4  * Copyright (C) 1999 - 2005, Digium, Inc.
   5  *
   6  * Mark Spencer <markster@digium.com>
   7  *
   8  * See http://www.asterisk.org for more information about
   9  * the Asterisk project. Please do not directly contact
  10  * any of the maintainers of this project for assistance;
  11  * the project provides a web site, mailing lists and IRC
  12  * channels for your use.
  13  *
  14  * This program is free software, distributed under the terms of
  15  * the GNU General Public License Version 2. See the LICENSE file
  16  * at the top of the source tree.
  17  */
  18
  19 /*! \file
  20  * \brief Distributed Universal Number Discovery (DUNDi)
  21  * See also \ref AstDUNDi
  22  */
  23
  24 #ifndef _ASTERISK_DUNDI_H
  25 #define _ASTERISK_DUNDI_H
  26
  27 #include "asterisk/channel.h"
  28
  29 #define DUNDI_PORT 4520
  30
  31 /*!\brief A DUNDi Entity ID is essentially a MAC address, brief and unique */
  32 struct _dundi_eid {
  33         unsigned char eid[6];
  34 } __attribute__ ((__packed__));
  35
  36 typedef struct _dundi_eid dundi_eid;
  37
  38 struct dundi_hdr {
  39         unsigned short strans;                  /*!< Source transaction */
  40         unsigned short dtrans;                  /*!< Destination transaction */
  41         unsigned char iseqno;                   /*!< Next expected incoming sequence number */
  42         unsigned char oseqno;                   /*!< Outgoing sequence number */
  43         unsigned char cmdresp;                  /*!< Command / Response */
  44         unsigned char cmdflags;                 /*!< Command / Response specific flags*/
  45         unsigned char ies[0];
  46 } __attribute__ ((__packed__));
  47
  48 struct dundi_ie_hdr {
  49         unsigned char ie;
  50         unsigned char len;
  51         unsigned char iedata[0];
  52 } __attribute__ ((__packed__));
  53
  54 #define DUNDI_FLAG_RETRANS              (1 << 16)       /*!< Applies to dtrans */
  55 #define DUNDI_FLAG_RESERVED             (1 << 16)       /*!< Applies to strans */
  56
  57 #define DUNDI_PROTO_NONE                0               /*!< No answer yet */
  58 #define DUNDI_PROTO_IAX                 1               /*!< IAX version 2 */
  59 #define DUNDI_PROTO_SIP                 2               /*!< Session Initiation Protocol */
  60 #define DUNDI_PROTO_H323                3               /*!< ITU H.323 */
  61
  62 #define DUNDI_FLAG_NONEXISTENT          (0)             /*!< Isn't and can't be a valid number */
  63 #define DUNDI_FLAG_EXISTS               (1 << 0)        /*!< Is a valid number */
  64 #define DUNDI_FLAG_MATCHMORE            (1 << 1)        /*!< Might be valid if you add more digits */
  65 #define DUNDI_FLAG_CANMATCH             (1 << 2)        /*!< Might be a match */
  66 #define DUNDI_FLAG_IGNOREPAT            (1 << 3)        /*!< Keep dialtone */
  67 #define DUNDI_FLAG_RESIDENTIAL          (1 << 4)        /*!< Destination known to be residential */
  68 #define DUNDI_FLAG_COMMERCIAL           (1 << 5)        /*!< Destination known to be commercial */
  69 #define DUNDI_FLAG_MOBILE               (1 << 6)        /*!< Destination known to be cellular/mobile */
  70 #define DUNDI_FLAG_NOUNSOLICITED        (1 << 7)        /*!< No unsolicited calls of any kind through this route */
  71 #define DUNDI_FLAG_NOCOMUNSOLICIT       (1 << 8)        /*!< No commercial unsolicited calls through this route */
  72
  73 #define DUNDI_HINT_NONE                 (0)
  74 #define DUNDI_HINT_TTL_EXPIRED          (1 << 0)        /*!< TTL Expired */
  75 #define DUNDI_HINT_DONT_ASK             (1 << 1)        /*!< Don't ask for anything beginning with data */
  76 #define DUNDI_HINT_UNAFFECTED           (1 << 2)        /*!< Answer not affected by entity list */
  77
  78 struct dundi_encblock {                         /*!< AES-128 encrypted block */
  79         unsigned char iv[16];                   /*!< Initialization vector of random data */
  80         unsigned char encdata[0];               /*!< Encrypted / compressed data */
  81 } __attribute__ ((__packed__));
  82
  83 struct dundi_answer {
  84         dundi_eid eid;                          /*!< Original source of answer */
  85         unsigned char protocol;                 /*!< Protocol (DUNDI_PROTO_*) */
  86         unsigned short flags;                   /*!< Flags relating to answer */
  87         unsigned short weight;                  /*!< Weight of answers */
  88         unsigned char data[0];                  /*!< Protocol specific URI */
  89 } __attribute__ ((__packed__));
  90
  91 struct dundi_hint {
  92         unsigned short flags;                   /*!< Flags relating to answer */
  93         unsigned char data[0];                  /*!< For data for hint */
  94 } __attribute__ ((__packed__));
  95
  96 #define DUNDI_CAUSE_SUCCESS             0       /*!< Success */
  97 #define DUNDI_CAUSE_GENERAL             1       /*!< General unspecified failure */
  98 #define DUNDI_CAUSE_DYNAMIC             2       /*!< Requested entity is dynamic */
  99 #define DUNDI_CAUSE_NOAUTH              3       /*!< No or improper authorization */
 100 #define DUNDI_CAUSE_DUPLICATE           4       /*!< Duplicate request */
 101 #define DUNDI_CAUSE_TTL_EXPIRED         5       /*!< Expired TTL */
 102 #define DUNDI_CAUSE_NEEDKEY             6       /*!< Need new session key to decode */
 103 #define DUNDI_CAUSE_BADENCRYPT          7       /*!< Badly encrypted data */
 104
 105 struct dundi_cause {
 106         unsigned char causecode;                /*!< Numerical cause (DUNDI_CAUSE_*) */
 107         char desc[0];                           /*!< Textual description */
 108 } __attribute__ ((__packed__));
 109
 110 struct dundi_peer_status {
 111         unsigned int flags;
 112         unsigned short netlag;
 113         unsigned short querylag;
 114         dundi_eid peereid;
 115 } __attribute__ ((__packed__));
 116
 117 #define DUNDI_PEER_PRIMARY              (1 << 0)
 118 #define DUNDI_PEER_SECONDARY            (1 << 1)
 119 #define DUNDI_PEER_UNAVAILABLE          (1 << 2)
 120 #define DUNDI_PEER_REGISTERED           (1 << 3)
 121 #define DUNDI_PEER_MOD_OUTBOUND         (1 << 4)
 122 #define DUNDI_PEER_MOD_INBOUND          (1 << 5)
 123 #define DUNDI_PEER_PCMOD_OUTBOUND       (1 << 6)
 124 #define DUNDI_PEER_PCMOD_INBOUND        (1 << 7)
 125
 126 #define DUNDI_COMMAND_FINAL             (0x80)          /*!< Or'd with other flags */
 127
 128 #define DUNDI_COMMAND_ACK               (0 | 0x40)      /*!< Ack a message */
 129 #define DUNDI_COMMAND_DPDISCOVER        1               /*!< Request discovery */
 130 #define DUNDI_COMMAND_DPRESPONSE        (2 | 0x40)      /*!< Respond to a discovery request */
 131 #define DUNDI_COMMAND_EIDQUERY          3               /*!< Request information for a peer */
 132 #define DUNDI_COMMAND_EIDRESPONSE       (4 | 0x40)      /*!< Response to a peer query */
 133 #define DUNDI_COMMAND_PRECACHERQ        5               /*!< Pre-cache Request */
 134 #define DUNDI_COMMAND_PRECACHERP        (6 | 0x40)      /*!< Pre-cache Response */
 135 #define DUNDI_COMMAND_INVALID           (7 | 0x40)      /*!< Invalid dialog state (does not require ack) */
 136 #define DUNDI_COMMAND_UNKNOWN           (8 | 0x40)      /*!< Unknown command */
 137 #define DUNDI_COMMAND_NULL              9               /*!< No-op */
 138 #define DUNDI_COMMAND_REGREQ            (10)            /*!< Register Request */
 139 #define DUNDI_COMMAND_REGRESPONSE       (11 | 0x40)     /*!< Register Response */
 140 #define DUNDI_COMMAND_CANCEL            (12)            /*!< Cancel transaction entirely */
 141 #define DUNDI_COMMAND_ENCRYPT           (13)            /*!< Send an encrypted message */
 142 #define DUNDI_COMMAND_ENCREJ            (14 | 0x40)     /*!< Reject an encrypted message */
 143
 144 #define DUNDI_COMMAND_STATUS            15              /*!< Status command */
 145
 146 /*
 147  * Remember that some information elements may occur
 148  * more than one time within a message
 149  */
 150
 151 #define DUNDI_IE_EID                    1       /*!< Entity identifier (dundi_eid) */
 152 #define DUNDI_IE_CALLED_CONTEXT         2       /*!< DUNDi Context (string) */
 153 #define DUNDI_IE_CALLED_NUMBER          3       /*!< Number of equivalent (string) */
 154 #define DUNDI_IE_EID_DIRECT             4       /*!< Entity identifier (dundi_eid), direct connect */
 155 #define DUNDI_IE_ANSWER                 5       /*!< An answer (struct dundi_answer) */
 156 #define DUNDI_IE_TTL                    6       /*!< Max TTL for this request / Remaining TTL for the response  (short)*/
 157 #define DUNDI_IE_VERSION                10      /*!< DUNDi version (should be 1) (short) */
 158 #define DUNDI_IE_EXPIRATION             11      /*!< Recommended expiration (short) */
 159 #define DUNDI_IE_UNKNOWN                12      /*!< Unknown command (byte) */
 160 #define DUNDI_IE_CAUSE                  14      /*!< Success or cause of failure */
 161 #define DUNDI_IE_REQEID                 15      /*!< EID being requested for EIDQUERY*/
 162 #define DUNDI_IE_ENCDATA                16      /*!< AES-128 encrypted data */
 163 #define DUNDI_IE_SHAREDKEY              17      /*!< RSA encrypted AES-128 key */
 164 #define DUNDI_IE_SIGNATURE              18      /*!< RSA Signature of encrypted shared key */
 165 #define DUNDI_IE_KEYCRC32               19      /*!< CRC32 of encrypted key (int) */
 166 #define DUNDI_IE_HINT                   20      /*!< Answer hints (struct ast_hint) */
 167
 168 #define DUNDI_IE_DEPARTMENT             21      /*!< Department, for EIDQUERY (string) */
 169 #define DUNDI_IE_ORGANIZATION           22      /*!< Organization, for EIDQUERY (string) */
 170 #define DUNDI_IE_LOCALITY               23      /*!< City/Locality, for EIDQUERY (string) */
 171 #define DUNDI_IE_STATE_PROV             24      /*!< State/Province, for EIDQUERY (string) */
 172 #define DUNDI_IE_COUNTRY                25      /*!< Country, for EIDQUERY (string) */
 173 #define DUNDI_IE_EMAIL                  26      /*!< E-mail addy, for EIDQUERY (string) */
 174 #define DUNDI_IE_PHONE                  27      /*!< Contact Phone, for EIDQUERY (string) */
 175 #define DUNDI_IE_IPADDR                 28      /*!< IP Address, for EIDQUERY (string) */
 176 #define DUNDI_IE_CACHEBYPASS            29      /*!< Bypass cache (empty) */
 177
 178 #define DUNDI_IE_PEERSTATUS             30      /*!< Peer/peer status (struct dundi_peer_status) */
 179
 180 #define DUNDI_FLUFF_TIME                2000    /*!< Amount of time for answer */
 181 #define DUNDI_TTL_TIME                  200     /*!< Incremental average time */
 182
 183 #define DUNDI_DEFAULT_RETRANS           5
 184 #define DUNDI_DEFAULT_RETRANS_TIMER     1000
 185 #define DUNDI_DEFAULT_TTL               120     /*!< In seconds/hops like TTL */
 186 #define DUNDI_DEFAULT_VERSION           1
 187 #define DUNDI_DEFAULT_CACHE_TIME        3600    /*!< In seconds */
 188 #define DUNDI_DEFAULT_KEY_EXPIRE        3600    /*!< Life of shared key In seconds */
 189 #define DUNDI_DEF_EMPTY_CACHE_TIME      60      /*!< In seconds, cache of empty answer */
 190 #define DUNDI_WINDOW                    1       /*!< Max 1 message in window */
 191
 192 #define DEFAULT_MAXMS                   2000
 193
 194 struct dundi_result {
 195         unsigned int flags;
 196         int weight;
 197         int expiration;
 198         int techint;
 199         dundi_eid eid;
 200         char eid_str[20];
 201         char tech[10];
 202         char dest[256];
 203 };
 204
 205 struct dundi_entity_info {
 206         char country[80];
 207         char stateprov[80];
 208         char locality[80];
 209         char org[80];
 210         char orgunit[80];
 211         char email[80];
 212         char phone[80];
 213         char ipaddr[80];
 214 };
 215
 216 /*! \brief Lookup the given number in the given dundi context (or e164 if unspecified) using the given callerid (if specified) and return up to maxret results in the array specified.
 217    returns the number of results found or -1 on a hangup of teh channel. */
 218 int dundi_lookup(struct dundi_result *result, int maxret, struct ast_channel *chan, const char *dcontext, const char *number, int nocache);
 219
 220 /*! \brief Retrieve information on a specific EID */
 221 int dundi_query_eid(struct dundi_entity_info *dei, const char *dcontext, dundi_eid eid);
 222
 223 /*! \brief Pre-cache to push upstream peers */
 224 int dundi_precache(const char *dcontext, const char *number);
 225
 226 #endif /* _ASTERISK_DUNDI_H */