Ignore:
Timestamp:
Feb 26, 2007 2:33:14 AM (17 years ago)
Author:
bennylp
Message:

Added CRC32 code to pjlib-util, and implemented STUN FINGERPRINT and MESSAGE-INTEGRITY

File:
1 edited

Legend:

Unmodified
Added
Removed

  • pjproject/trunk/pjlib-util/include/pjlib-util/stun_msg.h

    r1001 r1002  
    602602     * The raw data. 
    603603     */ 
    604     char               *data; 
     604    pj_uint8_t         *data; 
    605605 
    606606} pj_stun_binary_attr; 
    … …  
    10471047 
    10481048 
     1049/** STUN decoding options */ 
     1050enum pj_stun_options 
     1051{ 
     1052    /**  
     1053     * Tell the decoder that the message was received from datagram 
     1054     * oriented transport (such as UDP). 
     1055     */ 
     1056    PJ_STUN_IS_DATAGRAM     = 1, 
     1057 
     1058    /** 
     1059     * Tell pj_stun_msg_decode() to check the validity of the STUN 
     1060     * message by calling pj_stun_msg_check() before starting to 
     1061     * decode the packet. 
     1062     */ 
     1063    PJ_STUN_CHECK_PACKET    = 2 
     1064}; 
     1065 
    10491066/** 
    10501067 * Get STUN message method name. 
    … …  
    10881105 
    10891106/** 
    1090  * Create a blank STUN message. 
     1107 * Create a generic STUN message. 
    10911108 * 
    10921109 * @param pool          Pool to create the STUN message. 
    … …  
    11061123                                        pj_stun_msg **p_msg); 
    11071124 
     1125/** 
     1126 * Create STUN response message.  
     1127 * 
     1128 * @param pool          Pool to create the mesage. 
     1129 * @param req_msg       The request message. 
     1130 * @param err_code      STUN error code. If this value is not zero, 
     1131 *                      then error response will be created, otherwise 
     1132 *                      successful response will be created. 
     1133 * @param err_msg       Optional error message to explain err_code. 
     1134 *                      If this value is NULL and err_code is not zero, 
     1135 *                      the error string will be taken from the default 
     1136 *                      STUN error message. 
     1137 * @param p_response    Pointer to receive the response. 
     1138 * 
     1139 * @return              PJ_SUCCESS on success, or the appropriate error. 
     1140 */ 
     1141PJ_DECL(pj_status_t) pj_stun_msg_create_response(pj_pool_t *pool, 
     1142                                                 const pj_stun_msg *req_msg, 
     1143                                                 unsigned err_code, 
     1144                                                 const pj_str_t *err_msg, 
     1145                                                 pj_stun_msg **p_response); 
     1146 
    11081147 
    11091148/** 
    … …  
    11191158                                          pj_stun_attr_hdr *attr); 
    11201159 
    1121  
    1122 /** 
    1123  * Check that the PDU is potentially a valid STUN message. This function 
    1124  * is useful when application needs to multiplex STUN packets with other 
    1125  * application traffic. When this function returns PJ_SUCCESS, there is a 
    1126  * big chance that the packet is a STUN packet. 
    1127  * 
    1128  * Note that we cannot be sure that the PDU is a really valid STUN message  
    1129  * until we actually parse the PDU. 
    1130  * 
    1131  * @param pdu           The packet buffer. 
    1132  * @param pdu_len       The length of the packet buffer. 
    1133  * @param options       Options. 
    1134  * 
    1135  * @return              PJ_SUCCESS if the PDU is a potentially valid STUN 
    1136  *                      message. 
    1137  */ 
    1138 PJ_DECL(pj_status_t) pj_stun_msg_check(const void *pdu, unsigned pdu_len, 
    1139                                        unsigned options); 
    1140  
    1141  
    1142 /** 
    1143  * Parse incoming packet into STUN message. 
    1144  * 
    1145  * @param pool          Pool to allocate the message. 
    1146  * @param pdu           The incoming packet to be parsed. 
    1147  * @param pdu_len       The length of the incoming packet. 
    1148  * @param options       Parsing flags. 
    1149  * @param p_msg         Pointer to receive the parsed message. 
    1150  * @param p_parsed_len  Optional pointer to receive how many bytes have 
    1151  *                      been parsed for the STUN message. This is useful 
    1152  *                      when the packet is received over stream oriented 
    1153  *                      transport. 
    1154  * @param p_err_code    Optional pointer to receive STUN error code when 
    1155  *                      parsing failed. 
    1156  * @param uattr_cnt     Optional pointer to specify the number of elements 
    1157  *                      in uattr array. On return, this will be filled with 
    1158  *                      the actual number of attributes set in the uattr. 
    1159  * @param uattr         Optional array to receive unknown attribute types. 
    1160  * 
    1161  * @return              PJ_SUCCESS on success or the appropriate error code. 
    1162  */ 
    1163 PJ_DECL(pj_status_t) pj_stun_msg_decode(pj_pool_t *pool, 
    1164                                         const pj_uint8_t *pdu, 
    1165                                         unsigned pdu_len, 
    1166                                         unsigned options, 
    1167                                         pj_stun_msg **p_msg, 
    1168                                         unsigned *p_parsed_len, 
    1169                                         unsigned *p_err_code, 
    1170                                         unsigned *uattr_cnt, 
    1171                                         pj_uint16_t uattr[]); 
    11721160 
    11731161/** 
    … …  
    12061194                                        unsigned *p_msg_len); 
    12071195 
     1196/** 
     1197 * Check that the PDU is potentially a valid STUN message. This function 
     1198 * is useful when application needs to multiplex STUN packets with other 
     1199 * application traffic. When this function returns PJ_SUCCESS, there is a 
     1200 * big chance that the packet is a STUN packet. 
     1201 * 
     1202 * Note that we cannot be sure that the PDU is a really valid STUN message  
     1203 * until we actually parse the PDU. 
     1204 * 
     1205 * @param pdu           The packet buffer. 
     1206 * @param pdu_len       The length of the packet buffer. 
     1207 * @param options       Additional options to be applied in the checking, 
     1208 *                      which can be taken from pj_stun_options. One of the 
     1209 *                      useful option is PJ_STUN_IS_DATAGRAM which means that 
     1210 *                      the pdu represents a whole STUN packet. 
     1211 * 
     1212 * @return              PJ_SUCCESS if the PDU is a potentially valid STUN 
     1213 *                      message. 
     1214 */ 
     1215PJ_DECL(pj_status_t) pj_stun_msg_check(const pj_uint8_t *pdu, unsigned pdu_len, 
     1216                                       unsigned options); 
     1217 
     1218 
     1219/** 
     1220 * Decode incoming packet into STUN message. 
     1221 * 
     1222 * @param pool          Pool to allocate the message. 
     1223 * @param pdu           The incoming packet to be parsed. 
     1224 * @param pdu_len       The length of the incoming packet. 
     1225 * @param options       Parsing flags, according to pj_stun_options. 
     1226 * @param p_msg         Pointer to receive the parsed message. 
     1227 * @param p_parsed_len  Optional pointer to receive how many bytes have 
     1228 *                      been parsed for the STUN message. This is useful 
     1229 *                      when the packet is received over stream oriented 
     1230 *                      transport. 
     1231 * @param p_response    Optional pointer to receive an instance of response 
     1232 *                      message, if one can be created. If the packet being 
     1233 *                      decoded is a request message, and it contains error, 
     1234 *                      and a response can be created, then the STUN  
     1235 *                      response message will be returned on this argument. 
     1236 * 
     1237 * @return              PJ_SUCCESS if a STUN message has been successfully 
     1238 *                      decoded. 
     1239 */ 
     1240PJ_DECL(pj_status_t) pj_stun_msg_decode(pj_pool_t *pool, 
     1241                                        const pj_uint8_t *pdu, 
     1242                                        unsigned pdu_len, 
     1243                                        unsigned options, 
     1244                                        pj_stun_msg **p_msg, 
     1245                                        unsigned *p_parsed_len, 
     1246                                        pj_stun_msg **p_response); 
     1247 
     1248/** 
     1249 * Verify credential in the STUN message. Note that before calling this 
     1250 * function, application must have checked that the message contains 
     1251 * PJ_STUN_ATTR_MESSAGE_INTEGRITY attribute by calling pj_stun_msg_find_attr() 
     1252 * function, because this function will reject the message with 401 error 
     1253 * if it doesn't contain PJ_STUN_ATTR_MESSAGE_INTEGRITY attribute. 
     1254 * 
     1255 * @param msg           The message to be verified. 
     1256 * @param realm         Realm, if long term credential is required. If 
     1257 *                      short term credential is required, this argument 
     1258 *                      must be set to NULL. 
     1259 * @param username      If this attribute is specified, then the USERNAME 
     1260 *                      attribute in the message will be compared against 
     1261 *                      this value. If NULL is specified, then this function 
     1262 *                      will accept any usernames. 
     1263 * @param password      The password. 
     1264 * @param options       Options, must be zero for now. 
     1265 * @param pool          If response is to be created, then memory will 
     1266 *                      be allocated from this pool. 
     1267 * @param p_response    Optional pointer to receive the response message 
     1268 *                      then the credential in the request fails to 
     1269 *                      authenticate. 
     1270 * 
     1271 * @return              PJ_SUCCESS if credential is verified successfully. 
     1272 *                      If the verification fails and \a p_response is not 
     1273 *                      NULL, an appropriate response will be returned in 
     1274 *                      \a p_response. 
     1275 */ 
     1276PJ_DECL(pj_status_t) pj_stun_verify_credential(const pj_stun_msg *msg, 
     1277                                               const pj_str_t *realm, 
     1278                                               const pj_str_t *username, 
     1279                                               const pj_str_t *password, 
     1280                                               unsigned options, 
     1281                                               pj_pool_t *pool, 
     1282                                               pj_stun_msg **p_response); 
     1283 
    12081284 
    12091285/** 
    … …  
    12441320 
    12451321/** 
    1246  * Create a generic STUN IP address attribute for IPv4 address. Note that 
    1247  * the port and ip_addr parameters are in host byte order. 
     1322 * Create a generic STUN IP address attribute. The \a addr_len and 
     1323 * \a addr parameters specify whether the address is IPv4 or IPv4 
     1324 * address. 
    12481325 * 
    12491326 * @param pool          The pool to allocate memory from. 
    … …  
    12671344 
    12681345/** 
     1346 * Create and add generic STUN IP address attribute to a STUN message. 
     1347 * The \a addr_len and \a addr parameters specify whether the address is  
     1348 * IPv4 or IPv4 address. 
     1349 * 
     1350 * @param pool          The pool to allocate memory from. 
     1351 * @param msg           The STUN message. 
     1352 * @param attr_type     Attribute type, from #pj_stun_attr_type. 
     1353 * @param xor_ed        If non-zero, the port and address will be XOR-ed 
     1354 *                      with magic, to make the XOR-MAPPED-ADDRESS attribute. 
     1355 * @param addr_len      Length of \a addr parameter. 
     1356 * @param addr          A pj_sockaddr_in or pj_sockaddr_in6 structure. 
     1357 * 
     1358 * @return              PJ_SUCCESS on success or the appropriate error code. 
     1359 */ 
     1360PJ_DECL(pj_status_t)  
     1361pj_stun_msg_add_generic_ip_addr_attr(pj_pool_t *pool, 
     1362                                     pj_stun_msg *msg, 
     1363                                     int attr_type,  
     1364                                     pj_bool_t xor_ed, 
     1365                                     unsigned addr_len, 
     1366                                     const pj_sockaddr_t *addr); 
     1367 
     1368/** 
    12691369 * Create a STUN generic string attribute. 
    12701370 * 
    … …  
    12821382                                   pj_stun_generic_string_attr **p_attr); 
    12831383 
     1384/** 
     1385 * Create and add STUN generic string attribute to the message. 
     1386 * 
     1387 * @param pool          The pool to allocate memory from. 
     1388 * @param msg           The STUN message. 
     1389 * @param attr_type     Attribute type, from #pj_stun_attr_type. 
     1390 * @param value         The string value to be assigned to the attribute. 
     1391 * 
     1392 * @return              PJ_SUCCESS on success or the appropriate error code. 
     1393 */ 
     1394PJ_DECL(pj_status_t)  
     1395pj_stun_msg_add_generic_string_attr(pj_pool_t *pool, 
     1396                                    pj_stun_msg *msg, 
     1397                                    int attr_type, 
     1398                                    const pj_str_t *value); 
    12841399 
    12851400/** 
    … …  
    12991414                                 pj_stun_generic_uint_attr **p_attr); 
    13001415 
     1416/** 
     1417 * Create and add STUN generic 32bit value attribute to the message. 
     1418 * 
     1419 * @param pool          The pool to allocate memory from. 
     1420 * @param msg           The STUN message 
     1421 * @param attr_type     Attribute type, from #pj_stun_attr_type. 
     1422 * @param value         The 32bit value to be assigned to the attribute. 
     1423 * 
     1424 * @return              PJ_SUCCESS on success or the appropriate error code. 
     1425 */ 
     1426PJ_DECL(pj_status_t)  
     1427pj_stun_msg_add_generic_uint_attr(pj_pool_t *pool, 
     1428                                  pj_stun_msg *msg, 
     1429                                  int attr_type, 
     1430                                  pj_uint32_t value); 
     1431 
    13011432 
    13021433/** 
    … …  
    13111442pj_stun_msg_integrity_attr_create(pj_pool_t *pool, 
    13121443                                  pj_stun_msg_integrity_attr **p_attr); 
    1313  
    13141444 
    13151445/** 
    … …  
    13321462 
    13331463/** 
    1334  * Create an empty instance of STUN UNKNOWN-ATTRIBUTES attribute. 
     1464 * Create instance of STUN UNKNOWN-ATTRIBUTES attribute and copy the 
     1465 * unknown attribute array to the attribute. 
    13351466 * 
    13361467 * @param pool          The pool to allocate memory from. 
    … …  
    13441475pj_stun_unknown_attr_create(pj_pool_t *pool, 
    13451476                            unsigned attr_cnt, 
    1346                             pj_uint16_t attr[], 
     1477                            const pj_uint16_t attr[], 
    13471478                            pj_stun_unknown_attr **p_attr); 
    13481479 
    1349  
    1350 /** 
    1351  * Create a blank binary attribute. 
     1480/** 
     1481 * Create and add STUN UNKNOWN-ATTRIBUTES attribute to the message. 
     1482 * 
     1483 * @param pool          The pool to allocate memory from. 
     1484 * @param msg           The STUN message. 
     1485 * @param attr_cnt      Number of attributes in the array (can be zero). 
     1486 * @param attr          Optional array of attributes. 
     1487 * 
     1488 * @return              PJ_SUCCESS on success or the appropriate error code. 
     1489 */ 
     1490PJ_DECL(pj_status_t)  
     1491pj_stun_msg_add_unknown_attr(pj_pool_t *pool, 
     1492                             pj_stun_msg *msg, 
     1493                             unsigned attr_cnt, 
     1494                             const pj_uint16_t attr[]); 
     1495 
     1496/** 
     1497 * Create STUN binary attribute. 
    13521498 * 
    13531499 * @param pool          The pool to allocate memory from. 
    13541500 * @param attr_type     The attribute type, from #pj_stun_attr_type. 
     1501 * @param data          Data to be coped to the attribute, or NULL 
     1502 *                      if no data to be copied now. 
     1503 * @param length        Length of data, or zero if no data is to be 
     1504 *                      copied now. 
    13551505 * @param p_attr        Pointer to receive the attribute. 
    13561506 * 
    … …  
    13601510pj_stun_binary_attr_create(pj_pool_t *pool, 
    13611511                           int attr_type, 
     1512                           const pj_uint8_t *data, 
     1513                           unsigned length, 
    13621514                           pj_stun_binary_attr **p_attr); 
    13631515 
     1516/** 
     1517 * Create STUN binary attribute and add the attribute to the message. 
     1518 * 
     1519 * @param pool          The pool to allocate memory from. 
     1520 * @param msg           The STUN message. 
     1521 * @param attr_type     The attribute type, from #pj_stun_attr_type. 
     1522 * @param data          Data to be coped to the attribute, or NULL 
     1523 *                      if no data to be copied now. 
     1524 * @param length        Length of data, or zero if no data is to be 
     1525 *                      copied now. 
     1526 * @param p_attr        Pointer to receive the attribute. 
     1527 * 
     1528 * @return              PJ_SUCCESS on success or the appropriate error code. 
     1529 */ 
     1530PJ_DECL(pj_status_t) 
     1531pj_stun_msg_add_binary_attr(pj_pool_t *pool, 
     1532                            pj_stun_msg *msg, 
     1533                            int attr_type, 
     1534                            const pj_uint8_t *data, 
     1535                            unsigned length); 
     1536 
    13641537 
    13651538/** 
Note: See TracChangeset for help on using the changeset viewer.