stun_msg.h

来自「一个开源的sip源代码」· C头文件 代码 · 共 1,601 行 · 第 1/4 页

 * This structure describes STUN SOURCE-ADDRESS attribute.
 * The SOURCE-ADDRESS attribute is present in Binding Responses.  It
 * indicates the source IP address and port that the server is sending
 * the response from.  Its syntax is identical to that of MAPPED-
 * ADDRESS.
 *
 * Note that the usage of this attribute has been deprecated by the 
 * RFC 3489-bis standard.
 */
typedef struct pj_stun_sockaddr_attr pj_stun_src_addr_attr;


/**
 * This describes the STUN REFLECTED-FROM attribute.
 * The REFLECTED-FROM attribute is present only in Binding Responses,
 * when the Binding Request contained a RESPONSE-ADDRESS attribute.  The
 * attribute contains the identity (in terms of IP address) of the
 * source where the request came from.  Its purpose is to provide
 * traceability, so that a STUN server cannot be used as a reflector for
 * denial-of-service attacks.
 */
typedef struct pj_stun_sockaddr_attr pj_stun_reflected_from_attr;


/**
 * This describes STUN USERNAME attribute.
 * The USERNAME attribute is used for message integrity.  It identifies
 * the shared secret used in the message integrity check.  Consequently,
 * the USERNAME MUST be included in any request that contains the
 * MESSAGE-INTEGRITY attribute.
 */
typedef struct pj_stun_string_attr pj_stun_username_attr;


/**
 * This describes STUN PASSWORD attribute.
 * If the message type is Shared Secret Response it MUST include the
 * PASSWORD attribute.
 */
typedef struct pj_stun_string_attr pj_stun_password_attr;


/**
 * This describes STUN LIFETIME attribute.
 * The lifetime attribute represents the duration for which the server
 * will maintain an allocation in the absence of data traffic either
 * from or to the client.  It is a 32 bit value representing the number
 * of seconds remaining until expiration.
 */
typedef struct pj_stun_uint_attr pj_stun_lifetime_attr;


/**
 * This describes STUN BANDWIDTH attribute.
 * The bandwidth attribute represents the peak bandwidth, measured in
 * kbits per second, that the client expects to use on the binding.  The
 * value represents the sum in the receive and send directions.
 */
typedef struct pj_stun_uint_attr pj_stun_bandwidth_attr;


/**
 * This describes the STUN REMOTE-ADDRESS attribute.
 * The REMOTE-ADDRESS specifies the address and port of the peer as seen
 * from the STUN relay server.
 */
typedef struct pj_stun_sockaddr_attr pj_stun_remote_addr_attr;


/**
 * This describes the STUN DATA attribute.
 * The DATA attribute is present in Send Indications and Data
 * Indications.  It contains raw payload data that is to be sent (in the
 * case of a Send Request) or was received (in the case of a Data
 * Indication)..
 */
typedef struct pj_stun_binary_attr pj_stun_data_attr;


/**
 * This describes the STUN RELAY-ADDRESS attribute.
 * The RELAY-ADDRESS is present in Allocate responses.  It specifies the
 * address and port that the server allocated to the client.
 */
typedef struct pj_stun_sockaddr_attr pj_stun_relay_addr_attr;


/**
 * This describes the REQUESTED-ADDRESS-TYPE attribute.
 * The REQUESTED-ADDRESS-TYPE attribute is used by clients to request
 * the allocation of a specific address type from a server.  The
 * following is the format of the REQUESTED-ADDRESS-TYPE attribute.

 \verbatim

      0                   1                   2                   3
      0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
     |        Family                 |           Reserved            |
     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

 \endverbatim
 */
typedef struct pj_stun_uint_attr pj_stun_req_addr_type;

/**
 * This describes the STUN REQUESTED-PORT-PROPS attribute.
 * This attribute allows the client to request certain properties for
 * the port that is allocated by the server.  The attribute can be used
 * with any transport protocol that has the notion of a 16 bit port
 * space (including TCP and UDP).  The attribute is 32 bits long.  Its
 * format is:

 \verbatim

    0                   1                   2                   3
    0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |                           Reserved = 0                  |B| A |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

 \endverbatim  
 */
typedef struct pj_stun_uint_attr pj_stun_req_port_props_attr;


/**
 * This describes the STUN REQUESTED-TRANSPORT attribute.
 * This attribute is used by the client to request a specific transport
 * protocol for the allocated transport address.  It is a 32 bit
 * unsigned integer.  Its values are: 0x0000 for UDP and 0x0000 for TCP.
 */
typedef struct pj_stun_uint_attr pj_stun_req_transport_attr;


/**
 * This describes the STUN REQUESTED-IP attribute.
 * The REQUESTED-IP attribute is used by the client to request that a
 * specific IP address be allocated to it.
 */
typedef struct pj_stun_sockaddr_attr pj_stun_req_ip_attr;

/**
 * This describes the XOR-REFLECTED-FROM attribute, as described by
 * draft-macdonald-behave-nat-behavior-discovery-00.
 * The XOR-REFLECTED-FROM attribute is used in place of the REFLECTED-
 * FROM attribute.  It provides the same information, but because the
 * NAT's public address is obfuscated through the XOR function, It can
 * pass through a NAT that would otherwise attempt to translate it to
 * the private network address.  XOR-REFLECTED-FROM has identical syntax
 * to XOR-MAPPED-ADDRESS.
 */
typedef struct pj_stun_sockaddr_attr pj_stun_xor_reflected_from_attr;

/**
 * This describes the PRIORITY attribute from draft-ietf-mmusic-ice-13.
 * The PRIORITY attribute indicates the priority that is to be
 * associated with a peer reflexive candidate, should one be discovered
 * by this check.  It is a 32 bit unsigned integer, and has an attribute
 * type of 0x0024.
 */
typedef struct pj_stun_uint_attr pj_stun_priority_attr;

/**
 * This describes the USE-CANDIDATE attribute from draft-ietf-mmusic-ice-13.
 * The USE-CANDIDATE attribute indicates that the candidate pair
 * resulting from this check should be used for transmission of media.
 * The attribute has no content (the Length field of the attribute is
 * zero); it serves as a flag.
 */
typedef struct pj_stun_empty_attr pj_stun_use_candidate_attr;

/**
 * This structure describes STUN XOR-INTERNAL-ADDRESS attribute from
 * draft-wing-behave-nat-control-stun-usage-00.
 * This attribute MUST be present in a Binding Response and may be used
 * in other responses as well.  This attribute is necessary to allow a
 * STUN client to 'walk backwards' and communicate directly with all of
 * the STUN-aware NATs along the path.
 */
typedef pj_stun_sockaddr_attr pj_stun_xor_internal_addr_attr;

/**
 * This describes the STUN TIMER-VAL attribute.
 * The TIMER-VAL attribute is used only in conjunction with the Set
 * Active Destination response.  It conveys from the server, to the
 * client, the value of the timer used in the server state machine.
 */
typedef struct pj_stun_uint_attr pj_stun_timer_val_attr;

/**
 * This describes ICE-CONTROLLING attribute.
 */
typedef struct pj_stun_uint64_attr pj_stun_ice_controlling_attr;

/**
 * This describes ICE-CONTROLLED attribute.
 */
typedef struct pj_stun_uint64_attr pj_stun_ice_controlled_attr;

/**
 * This structure describes a parsed STUN message. All integral fields
 * in this structure (including IP addresses) will be in the host
 * byte order.
 */
typedef struct pj_stun_msg
{
    /**
     * STUN message header.
     */
    pj_stun_msg_hdr     hdr;

    /**
     * Number of attributes in the STUN message.
     */
    unsigned		attr_count;

    /**
     * Array of STUN attributes.
     */
    pj_stun_attr_hdr   *attr[PJ_STUN_MAX_ATTR];

} pj_stun_msg;


/** STUN decoding options */
enum pj_stun_decode_options
{
    /** 
     * Tell the decoder that the message was received from datagram
     * oriented transport (such as UDP).
     */
    PJ_STUN_IS_DATAGRAM	    = 1,

    /**
     * Tell pj_stun_msg_decode() to check the validity of the STUN
     * message by calling pj_stun_msg_check() before starting to
     * decode the packet.
     */
    PJ_STUN_CHECK_PACKET    = 2,

    /**
     * This option current is only valid for #pj_stun_session_on_rx_pkt().
     * When specified, it tells the session NOT to authenticate the
     * message.
     */
    PJ_STUN_NO_AUTHENTICATE = 4
};


/**
 * Get STUN message method name.
 *
 * @param msg_type	The STUN message type (in host byte order)
 *
 * @return		The STUN message method name string.
 */
PJ_DECL(const char*) pj_stun_get_method_name(unsigned msg_type);


/**
 * Get STUN message class name.
 *
 * @param msg_type	The STUN message type (in host byte order)
 *
 * @return		The STUN message class name string.
 */
PJ_DECL(const char*) pj_stun_get_class_name(unsigned msg_type);


/**
 * Get STUN attribute name.
 *
 * @return attr_type	The STUN attribute type (in host byte order).
 *
 * @return		The STUN attribute type name string.
 */
PJ_DECL(const char*) pj_stun_get_attr_name(unsigned attr_type);


/**
 * Get STUN standard reason phrase for the specified error code.
 *
 * @param err_code	The STUN error code.
 *
 * @return		The STUN error reason phrase.
 */
PJ_DECL(pj_str_t) pj_stun_get_err_reason(int err_code);


/**
 * Create a generic STUN message.
 *
 * @param pool		Pool to create the STUN message.
 * @param msg_type	The 14bit message type.
 * @param magic		Magic value to be put to the mesage; for requests,
 *			the value should be PJ_STUN_MAGIC.
 * @param tsx_id	Optional transaction ID, or NULL to let the
 *			function generates a random transaction ID.
 * @param p_msg		Pointer to receive the message.
 *
 * @return		PJ_SUCCESS on success.
 */
PJ_DECL(pj_status_t) pj_stun_msg_create(pj_pool_t *pool,
					unsigned msg_type,
					pj_uint32_t magic,
					const pj_uint8_t tsx_id[12],
					pj_stun_msg **p_msg);

/**
 * Create STUN response message. 
 *
 * @param pool		Pool to create the mesage.
 * @param req_msg	The request message.
 * @param err_code	STUN error code. If this value is not zero,
 *			then error response will be created, otherwise
 *			successful response will be created.
 * @param err_msg	Optional error message to explain err_code.
 *			If this value is NULL and err_code is not zero,
 *			the error string will be taken from the default
 *			STUN error message.
 * @param p_response	Pointer to receive the response.
 *
 * @return		PJ_SUCCESS on success, or the appropriate error.
 */
PJ_DECL(pj_status_t) pj_stun_msg_create_response(pj_pool_t *pool,
						 const pj_stun_msg *req_msg,
						 unsigned err_code,
						 const pj_str_t *err_msg,
						 pj_stun_msg **p_response);


/**
 * Add STUN attribute to STUN message.
 *
 * @param msg		The STUN message.
 * @param attr		The STUN attribute to be added to the message.
 *
 * @return		PJ_SUCCESS on success, or PJ_ETOOMANY if there are
 *			already too many attributes in the message.
 */
PJ_DECL(pj_status_t) pj_stun_msg_add_attr(pj_stun_msg *msg,
					  pj_stun_attr_hdr *attr);


/**
 * Print the STUN message structure to a packet buffer, ready to be 
 * sent to remote destination. This function will take care about 
 * calculating the MESSAGE-INTEGRITY digest as well as FINGERPRINT
 * value, if these attributes are present in the message.
 *
 * If application wants to apply credential to the message, it MUST
 * include a blank MESSAGE-INTEGRITY attribute in the message, as the
 * last attribute or the attribute before FINGERPRINT. This function will
 * calculate the HMAC digest from the message using  the supplied key in
 * the parameter. The key should be set to the password if short term 
 * credential is used, or calculated from the MD5 hash of the realm, 
 * username, and password using #pj_stun_create_key() if long term 
 * credential is used.
 *
 * If FINGERPRINT attribute is present, this function will calculate
 * the FINGERPRINT CRC attribute for the message. The FINGERPRINT MUST
 * be added as the last attribute of the message.
 *
 * @param msg		The STUN message to be printed. Upon return,
 *			some fields in the header (such as message
 *			length) will be updated.
 * @param pkt_buf	The buffer to be filled with the packet.
 * @param buf_size	Size of the buffer.
 * @param options	Options, which currently must be zero.
 * @param key		Authentication key to calculate MESSAGE-INTEGRITY
 *			value. Application can create this key by using
 *			#pj_stun_create_key() function.
 * @param p_msg_len	Upon return, it will be filed with the size of 
 *			the packet in bytes, or negative value on error.
 *
 * @return		PJ_SUCCESS on success or the appropriate error code.
 */
PJ_DECL(pj_status_t) pj_stun_msg_encode(pj_stun_msg *msg,
				        pj_uint8_t *pkt_buf,
				        unsigned buf_size,
				        unsigned options,
					const pj_str_t *key,
				        unsigned *p_msg_len);


/**
 * Create authentication key to be used for encoding the message with
 * MESSAGE-INTEGRITY. If short term credential is used (i.e. the realm
 * argument is NULL or empty), the key will be copied from the password.
 * If long term credential is used, the key will be calculated from the
 * MD5 hash of the realm, username, and password.
 *
 * @param pool		Pool to allocate memory for the key.
 * @param key		String to receive the key.
 * @param realm		The realm of the credential, if long term credential
 *			is to be used. If short term credential is wanted,
 *			application can put NULL or empty string here.
 * @param username	The username.
 * @param passwd	The clear text password.
 */