dundi.h

Go to the documentation of this file.

/*
 * Asterisk -- An open source telephony toolkit.
 *
 * Copyright (C) 1999 - 2005, Digium, Inc.
 *
 * Mark Spencer <[email protected]>
 *
 * See http://www.asterisk.org for more information about
 * the Asterisk project. Please do not directly contact
 * any of the maintainers of this project for assistance;
 * the project provides a web site, mailing lists and IRC
 * channels for your use.
 *
 * This program is free software, distributed under the terms of
 * the GNU General Public License Version 2. See the LICENSE file
 * at the top of the source tree.
 */

/*! \file
 * \brief Distributed Universal Number Discovery (DUNDi)
 * See also \arg \ref AstDUNDi
 */

#ifndef _ASTERISK_DUNDI_H
#define _ASTERISK_DUNDI_H

#include "asterisk/channel.h"
#include "asterisk/utils.h"

#define DUNDI_PORT 4520

typedef struct ast_eid dundi_eid;

struct dundi_hdr {
   unsigned short strans;        /*!< Source transaction */
   unsigned short dtrans;        /*!< Destination transaction */
   unsigned char iseqno;         /*!< Next expected incoming sequence number */
   unsigned char oseqno;         /*!< Outgoing sequence number */
   unsigned char cmdresp;        /*!< Command / Response */
   unsigned char cmdflags;       /*!< Command / Response specific flags*/
   unsigned char ies[0];
} __attribute__((__packed__));

struct dundi_ie_hdr {
   unsigned char ie;
   unsigned char len;
   unsigned char iedata[0];
} __attribute__((__packed__));

#define DUNDI_FLAG_RETRANS    (1 << 16)   /*!< Applies to dtrans */
#define DUNDI_FLAG_RESERVED      (1 << 16)   /*!< Applies to strans */

enum {
   /*! No answer yet */
   DUNDI_PROTO_NONE = 0,
   /*! IAX, version 2 */
   DUNDI_PROTO_IAX  = 1,
   /*! SIP - Session Initiation Protocol, RFC 3261 */
   DUNDI_PROTO_SIP  = 2,
   /*! ITU H.323 */
   DUNDI_PROTO_H323 = 3,
};

enum {
   /*! Isn't and can't be a valid number */
   DUNDI_FLAG_NONEXISTENT =    (0),
   /*! Is a valid number */
   DUNDI_FLAG_EXISTS =         (1 << 0),
   /*! Might be valid if you add more digits */
   DUNDI_FLAG_MATCHMORE =      (1 << 1),
   /*! Might be a match */
   DUNDI_FLAG_CANMATCH =       (1 << 2),
   /*! Keep dialtone */
   DUNDI_FLAG_IGNOREPAT =      (1 << 3),
   /*! Destination known to be residential */
   DUNDI_FLAG_RESIDENTIAL =    (1 << 4),
   /*! Destination known to be commercial */
   DUNDI_FLAG_COMMERCIAL =     (1 << 5),
   /*! Destination known to be cellular/mobile */
   DUNDI_FLAG_MOBILE =         (1 << 6),
   /*! No unsolicited calls of any kind through this route */
   DUNDI_FLAG_NOUNSOLICITED =  (1 << 7),
   /*! No commercial unsolicited calls through this route */
   DUNDI_FLAG_NOCOMUNSOLICIT = (1 << 8),
};

enum {
   DUNDI_HINT_NONE =        (0),
   /*! TTL Expired */
   DUNDI_HINT_TTL_EXPIRED = (1 << 0),
   /*! Don't ask for anything beginning with data */
   DUNDI_HINT_DONT_ASK =    (1 << 1),
   /*! Answer not affected by entity list */
   DUNDI_HINT_UNAFFECTED =  (1 << 2),
};

struct dundi_encblock {          /*!< AES-128 encrypted block */
   unsigned char iv[16];         /*!< Initialization vector of random data */
   unsigned char encdata[0];     /*!< Encrypted / compressed data */
} __attribute__((__packed__));

struct dundi_answer {
   dundi_eid eid;          /*!< Original source of answer */
   unsigned char protocol;       /*!< Protocol (DUNDI_PROTO_*) */
   unsigned short flags;         /*!< Flags relating to answer */
   unsigned short weight;        /*!< Weight of answers */
   unsigned char data[0];        /*!< Protocol specific URI */
} __attribute__((__packed__));

struct dundi_hint {
   unsigned short flags;         /*!< Flags relating to answer */
   unsigned char data[0];        /*!< For data for hint */
} __attribute__((__packed__));

enum {
   /*! Success */
   DUNDI_CAUSE_SUCCESS =     0,
   /*! General unspecified failure */
   DUNDI_CAUSE_GENERAL =     1,
   /*! Requested entity is dynamic */
   DUNDI_CAUSE_DYNAMIC =     2,
   /*! No or improper authorization */
   DUNDI_CAUSE_NOAUTH =      3,
   /*! Duplicate request */
   DUNDI_CAUSE_DUPLICATE =   4,
   /*! Expired TTL */
   DUNDI_CAUSE_TTL_EXPIRED = 5,
   /*! Need new session key to decode */
   DUNDI_CAUSE_NEEDKEY =     6,
   /*! Badly encrypted data */
   DUNDI_CAUSE_BADENCRYPT =  7,
};

struct dundi_cause {
   unsigned char causecode;      /*!< Numerical cause (DUNDI_CAUSE_*) */
   char desc[0];           /*!< Textual description */
} __attribute__((__packed__));

struct dundi_peer_status {
   unsigned int flags;
   unsigned short netlag;
   unsigned short querylag;
   dundi_eid peereid;
} __attribute__((__packed__));

enum {
   DUNDI_PEER_PRIMARY =        (1 << 0),
   DUNDI_PEER_SECONDARY =      (1 << 1),
   DUNDI_PEER_UNAVAILABLE =    (1 << 2),
   DUNDI_PEER_REGISTERED =     (1 << 3),
   DUNDI_PEER_MOD_OUTBOUND =   (1 << 4),
   DUNDI_PEER_MOD_INBOUND =    (1 << 5),
   DUNDI_PEER_PCMOD_OUTBOUND = (1 << 6),
   DUNDI_PEER_PCMOD_INBOUND =  (1 << 7),
};

#define DUNDI_COMMAND_FINAL      (0x80)      /*!< Or'd with other flags */

#define DUNDI_COMMAND_ACK     (0 | 0x40)  /*!< Ack a message */
#define DUNDI_COMMAND_DPDISCOVER 1     /*!< Request discovery */
#define DUNDI_COMMAND_DPRESPONSE (2 | 0x40)  /*!< Respond to a discovery request */
#define DUNDI_COMMAND_EIDQUERY      3     /*!< Request information for a peer */
#define DUNDI_COMMAND_EIDRESPONSE   (4 | 0x40)  /*!< Response to a peer query */
#define DUNDI_COMMAND_PRECACHERQ 5     /*!< Pre-cache Request */
#define DUNDI_COMMAND_PRECACHERP (6 | 0x40)  /*!< Pre-cache Response */
#define DUNDI_COMMAND_INVALID    (7 | 0x40)  /*!< Invalid dialog state (does not require ack) */
#define DUNDI_COMMAND_UNKNOWN    (8 | 0x40)  /*!< Unknown command */
#define DUNDI_COMMAND_NULL    9     /*!< No-op */
#define DUNDI_COMMAND_REGREQ     (10)     /*!< Register Request */
#define DUNDI_COMMAND_REGRESPONSE   (11 | 0x40) /*!< Register Response */
#define DUNDI_COMMAND_CANCEL     (12)     /*!< Cancel transaction entirely */
#define DUNDI_COMMAND_ENCRYPT    (13)     /*!< Send an encrypted message */
#define DUNDI_COMMAND_ENCREJ     (14 | 0x40) /*!< Reject an encrypted message */

#define DUNDI_COMMAND_STATUS     15    /*!< Status command */

/*
 * Remember that some information elements may occur
 * more than one time within a message
 */

#define DUNDI_IE_EID       1  /*!< Entity identifier (dundi_eid) */
#define DUNDI_IE_CALLED_CONTEXT     2  /*!< DUNDi Context (string) */
#define DUNDI_IE_CALLED_NUMBER      3  /*!< Number of equivalent (string) */
#define DUNDI_IE_EID_DIRECT      4  /*!< Entity identifier (dundi_eid), direct connect */
#define DUNDI_IE_ANSWER       5  /*!< An answer (struct dundi_answer) */
#define DUNDI_IE_TTL       6  /*!< Max TTL for this request / Remaining TTL for the response  (short)*/
#define DUNDI_IE_VERSION      10 /*!< DUNDi version (should be 1) (short) */
#define DUNDI_IE_EXPIRATION      11 /*!< Recommended expiration (short) */
#define DUNDI_IE_UNKNOWN      12 /*!< Unknown command (byte) */
#define DUNDI_IE_CAUSE        14 /*!< Success or cause of failure */
#define DUNDI_IE_REQEID       15 /*!< EID being requested for EIDQUERY*/
#define DUNDI_IE_ENCDATA      16 /*!< AES-128 encrypted data */
#define DUNDI_IE_SHAREDKEY    17 /*!< RSA encrypted AES-128 key */
#define DUNDI_IE_SIGNATURE    18 /*!< RSA Signature of encrypted shared key */
#define DUNDI_IE_KEYCRC32     19 /*!< CRC32 of encrypted key (int) */
#define DUNDI_IE_HINT         20 /*!< Answer hints */

#define DUNDI_IE_DEPARTMENT      21 /*!< Department, for EIDQUERY (string) */
#define DUNDI_IE_ORGANIZATION    22 /*!< Organization, for EIDQUERY (string) */
#define DUNDI_IE_LOCALITY     23 /*!< City/Locality, for EIDQUERY (string) */
#define DUNDI_IE_STATE_PROV      24 /*!< State/Province, for EIDQUERY (string) */
#define DUNDI_IE_COUNTRY      25 /*!< Country, for EIDQUERY (string) */
#define DUNDI_IE_EMAIL        26 /*!< E-mail addy, for EIDQUERY (string) */
#define DUNDI_IE_PHONE        27 /*!< Contact Phone, for EIDQUERY (string) */
#define DUNDI_IE_IPADDR       28 /*!< IP Address, for EIDQUERY (string) */
#define DUNDI_IE_CACHEBYPASS     29 /*!< Bypass cache (empty) */

#define DUNDI_IE_PEERSTATUS      30    /*!< Peer/peer status (struct dundi_peer_status) */

#define DUNDI_FLUFF_TIME      2000  /*!< Amount of time for answer */
#define DUNDI_TTL_TIME        200   /*!< Incremental average time */

#define DUNDI_DEFAULT_RETRANS    5
#define DUNDI_DEFAULT_RETRANS_TIMER 1000
#define DUNDI_DEFAULT_TTL     120   /*!< In seconds/hops like TTL */
#define DUNDI_DEFAULT_VERSION    1
#define DUNDI_DEFAULT_CACHE_TIME 3600  /*!< In seconds */
#define DUNDI_DEFAULT_KEY_EXPIRE 3600  /*!< Life of shared key In seconds */
#define DUNDI_DEF_EMPTY_CACHE_TIME  60 /*!< In seconds, cache of empty answer */
#define DUNDI_WINDOW       1  /*!< Max 1 message in window */

#define DEFAULT_MAXMS         2000

struct dundi_result {
   unsigned int flags;
   int weight;
   int expiration;
   int techint;
   dundi_eid eid;
   char eid_str[20];
   char tech[10];
   char dest[256];
};

struct dundi_entity_info {
   char country[80];
   char stateprov[80];
   char locality[80];
   char org[80];
   char orgunit[80];
   char email[80];
   char phone[80];
   char ipaddr[80];
};

/*!
 * \brief Lookup the given number in the given dundi context.
 * Lookup number in a given dundi context (if unspecified use e164), the given callerid (if specified)
 * and return up to maxret results in the array specified.
 * \retval the number of results found.
 * \retval -1 on a hangup of the channel.
*/
int dundi_lookup(struct dundi_result *result, int maxret, struct ast_channel *chan, const char *dcontext, const char *number, int nocache);

/*! \brief Retrieve information on a specific EID */
int dundi_query_eid(struct dundi_entity_info *dei, const char *dcontext, dundi_eid eid);

/*! \brief Pre-cache to push upstream peers */
int dundi_precache(const char *dcontext, const char *number);

#endif /* _ASTERISK_DUNDI_H */