1 /* 2 * libjingle 3 * Copyright 2004--2005, Google Inc. 4 * 5 * Redistribution and use in source and binary forms, with or without 6 * modification, are permitted provided that the following conditions are met: 7 * 8 * 1. Redistributions of source code must retain the above copyright notice, 9 * this list of conditions and the following disclaimer. 10 * 2. Redistributions in binary form must reproduce the above copyright notice, 11 * this list of conditions and the following disclaimer in the documentation 12 * and/or other materials provided with the distribution. 13 * 3. The name of the author may not be used to endorse or promote products 14 * derived from this software without specific prior written permission. 15 * 16 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR IMPLIED 17 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF 18 * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO 19 * EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 20 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, 21 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; 22 * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, 23 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR 24 * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF 25 * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 26 */ 27 28 #ifndef __STUN_H__ 29 #define __STUN_H__ 30 31 // This file contains classes for dealing with the STUN and TURN protocols. 32 // Both protocols use the same wire format. 33 34 #include <string> 35 #include <vector> 36 37 #include "talk/base/basictypes.h" 38 #include "talk/base/bytebuffer.h" 39 40 namespace cricket { 41 42 // These are the types of STUN & TURN messages as of last check. 43 enum StunMessageType { 44 STUN_BINDING_REQUEST = 0x0001, 45 STUN_BINDING_RESPONSE = 0x0101, 46 STUN_BINDING_ERROR_RESPONSE = 0x0111, 47 STUN_SHARED_SECRET_REQUEST = 0x0002, 48 STUN_SHARED_SECRET_RESPONSE = 0x0102, 49 STUN_SHARED_SECRET_ERROR_RESPONSE = 0x0112, 50 STUN_ALLOCATE_REQUEST = 0x0003, 51 STUN_ALLOCATE_RESPONSE = 0x0103, 52 STUN_ALLOCATE_ERROR_RESPONSE = 0x0113, 53 STUN_SEND_REQUEST = 0x0004, 54 STUN_SEND_RESPONSE = 0x0104, 55 STUN_SEND_ERROR_RESPONSE = 0x0114, 56 STUN_DATA_INDICATION = 0x0115 57 }; 58 59 // These are the types of attributes defined in STUN & TURN. Next to each is 60 // the name of the class (T is StunTAttribute) that implements that type. 61 enum StunAttributeType { 62 STUN_ATTR_MAPPED_ADDRESS = 0x0001, // Address 63 STUN_ATTR_RESPONSE_ADDRESS = 0x0002, // Address 64 STUN_ATTR_CHANGE_REQUEST = 0x0003, // UInt32 65 STUN_ATTR_SOURCE_ADDRESS = 0x0004, // Address 66 STUN_ATTR_CHANGED_ADDRESS = 0x0005, // Address 67 STUN_ATTR_USERNAME = 0x0006, // ByteString, multiple of 4 bytes 68 STUN_ATTR_PASSWORD = 0x0007, // ByteString, multiple of 4 bytes 69 STUN_ATTR_MESSAGE_INTEGRITY = 0x0008, // ByteString, 20 bytes 70 STUN_ATTR_ERROR_CODE = 0x0009, // ErrorCode 71 STUN_ATTR_UNKNOWN_ATTRIBUTES = 0x000a, // UInt16List 72 STUN_ATTR_REFLECTED_FROM = 0x000b, // Address 73 STUN_ATTR_TRANSPORT_PREFERENCES = 0x000c, // TransportPrefs 74 STUN_ATTR_LIFETIME = 0x000d, // UInt32 75 STUN_ATTR_ALTERNATE_SERVER = 0x000e, // Address 76 STUN_ATTR_MAGIC_COOKIE = 0x000f, // ByteString, 4 bytes 77 STUN_ATTR_BANDWIDTH = 0x0010, // UInt32 78 STUN_ATTR_DESTINATION_ADDRESS = 0x0011, // Address 79 STUN_ATTR_SOURCE_ADDRESS2 = 0x0012, // Address 80 STUN_ATTR_DATA = 0x0013, // ByteString 81 STUN_ATTR_OPTIONS = 0x8001 // UInt32 82 }; 83 84 enum StunErrorCodes { 85 STUN_ERROR_BAD_REQUEST = 400, 86 STUN_ERROR_UNAUTHORIZED = 401, 87 STUN_ERROR_UNKNOWN_ATTRIBUTE = 420, 88 STUN_ERROR_STALE_CREDENTIALS = 430, 89 STUN_ERROR_INTEGRITY_CHECK_FAILURE = 431, 90 STUN_ERROR_MISSING_USERNAME = 432, 91 STUN_ERROR_USE_TLS = 433, 92 STUN_ERROR_SERVER_ERROR = 500, 93 STUN_ERROR_GLOBAL_FAILURE = 600 94 }; 95 96 extern const std::string STUN_ERROR_REASON_BAD_REQUEST; 97 extern const std::string STUN_ERROR_REASON_UNAUTHORIZED; 98 extern const std::string STUN_ERROR_REASON_UNKNOWN_ATTRIBUTE; 99 extern const std::string STUN_ERROR_REASON_STALE_CREDENTIALS; 100 extern const std::string STUN_ERROR_REASON_INTEGRITY_CHECK_FAILURE; 101 extern const std::string STUN_ERROR_REASON_MISSING_USERNAME; 102 extern const std::string STUN_ERROR_REASON_USE_TLS; 103 extern const std::string STUN_ERROR_REASON_SERVER_ERROR; 104 extern const std::string STUN_ERROR_REASON_GLOBAL_FAILURE; 105 106 class StunAttribute; 107 class StunAddressAttribute; 108 class StunUInt32Attribute; 109 class StunByteStringAttribute; 110 class StunErrorCodeAttribute; 111 class StunUInt16ListAttribute; 112 class StunTransportPrefsAttribute; 113 114 // Records a complete STUN/TURN message. Each message consists of a type and 115 // any number of attributes. Each attribute is parsed into an instance of an 116 // appropriate class (see above). The Get* methods will return instances of 117 // that attribute class. 118 class StunMessage { 119 public: 120 StunMessage(); 121 ~StunMessage(); 122 type()123 StunMessageType type() const { return static_cast<StunMessageType>(type_); } length()124 uint16 length() const { return length_; } transaction_id()125 const std::string& transaction_id() const { return transaction_id_; } 126 SetType(StunMessageType type)127 void SetType(StunMessageType type) { type_ = type; } 128 void SetTransactionID(const std::string& str); 129 130 const StunAddressAttribute* GetAddress(StunAttributeType type) const; 131 const StunUInt32Attribute* GetUInt32(StunAttributeType type) const; 132 const StunByteStringAttribute* GetByteString(StunAttributeType type) const; 133 const StunErrorCodeAttribute* GetErrorCode() const; 134 const StunUInt16ListAttribute* GetUnknownAttributes() const; 135 const StunTransportPrefsAttribute* GetTransportPrefs() const; 136 137 void AddAttribute(StunAttribute* attr); 138 139 // Parses the STUN/TURN packet in the given buffer and records it here. The 140 // return value indicates whether this was successful. 141 bool Read(talk_base::ByteBuffer* buf); 142 143 // Writes this object into a STUN/TURN packet. Return value is true if 144 // successful. 145 void Write(talk_base::ByteBuffer* buf) const; 146 147 private: 148 uint16 type_; 149 uint16 length_; 150 std::string transaction_id_; 151 std::vector<StunAttribute*>* attrs_; 152 153 const StunAttribute* GetAttribute(StunAttributeType type) const; 154 }; 155 156 // Base class for all STUN/TURN attributes. 157 class StunAttribute { 158 public: ~StunAttribute()159 virtual ~StunAttribute() {} 160 type()161 StunAttributeType type() const { 162 return static_cast<StunAttributeType>(type_); 163 } length()164 uint16 length() const { return length_; } 165 166 // Reads the body (not the type or length) for this type of attribute from 167 // the given buffer. Return value is true if successful. 168 virtual bool Read(talk_base::ByteBuffer* buf) = 0; 169 170 // Writes the body (not the type or length) to the given buffer. Return 171 // value is true if successful. 172 virtual void Write(talk_base::ByteBuffer* buf) const = 0; 173 174 // Creates an attribute object with the given type and len. 175 static StunAttribute* Create(uint16 type, uint16 length); 176 177 // Creates an attribute object with the given type and smallest length. 178 static StunAddressAttribute* CreateAddress(uint16 type); 179 static StunUInt32Attribute* CreateUInt32(uint16 type); 180 static StunByteStringAttribute* CreateByteString(uint16 type); 181 static StunErrorCodeAttribute* CreateErrorCode(); 182 static StunUInt16ListAttribute* CreateUnknownAttributes(); 183 static StunTransportPrefsAttribute* CreateTransportPrefs(); 184 185 protected: 186 StunAttribute(uint16 type, uint16 length); 187 SetLength(uint16 length)188 void SetLength(uint16 length) { length_ = length; } 189 190 private: 191 uint16 type_; 192 uint16 length_; 193 }; 194 195 // Implements STUN/TURN attributes that record an Internet address. 196 class StunAddressAttribute : public StunAttribute { 197 public: 198 StunAddressAttribute(uint16 type); 199 200 #if (_MSC_VER < 1300) 201 enum { SIZE = 8 }; 202 #else 203 static const uint16 SIZE = 8; 204 #endif 205 family()206 uint8 family() const { return family_; } port()207 uint16 port() const { return port_; } ip()208 uint32 ip() const { return ip_; } 209 SetFamily(uint8 family)210 void SetFamily(uint8 family) { family_ = family; } SetIP(uint32 ip)211 void SetIP(uint32 ip) { ip_ = ip; } SetPort(uint16 port)212 void SetPort(uint16 port) { port_ = port; } 213 214 bool Read(talk_base::ByteBuffer* buf); 215 void Write(talk_base::ByteBuffer* buf) const; 216 217 private: 218 uint8 family_; 219 uint16 port_; 220 uint32 ip_; 221 }; 222 223 // Implements STUN/TURN attributs that record a 32-bit integer. 224 class StunUInt32Attribute : public StunAttribute { 225 public: 226 StunUInt32Attribute(uint16 type); 227 228 #if (_MSC_VER < 1300) 229 enum { SIZE = 4 }; 230 #else 231 static const uint16 SIZE = 4; 232 #endif 233 value()234 uint32 value() const { return bits_; } 235 SetValue(uint32 bits)236 void SetValue(uint32 bits) { bits_ = bits; } 237 238 bool GetBit(int index) const; 239 void SetBit(int index, bool value); 240 241 bool Read(talk_base::ByteBuffer* buf); 242 void Write(talk_base::ByteBuffer* buf) const; 243 244 private: 245 uint32 bits_; 246 }; 247 248 // Implements STUN/TURN attributs that record an arbitrary byte string 249 class StunByteStringAttribute : public StunAttribute { 250 public: 251 StunByteStringAttribute(uint16 type, uint16 length); 252 ~StunByteStringAttribute(); 253 bytes()254 const char* bytes() const { return bytes_; } 255 256 void SetBytes(char* bytes, uint16 length); 257 258 void CopyBytes(const char* bytes); // uses strlen 259 void CopyBytes(const void* bytes, uint16 length); 260 261 uint8 GetByte(int index) const; 262 void SetByte(int index, uint8 value); 263 264 bool Read(talk_base::ByteBuffer* buf); 265 void Write(talk_base::ByteBuffer* buf) const; 266 267 private: 268 char* bytes_; 269 }; 270 271 // Implements STUN/TURN attributs that record an error code. 272 class StunErrorCodeAttribute : public StunAttribute { 273 public: 274 StunErrorCodeAttribute(uint16 type, uint16 length); 275 ~StunErrorCodeAttribute(); 276 277 #if (_MSC_VER < 1300) 278 enum { MIN_SIZE = 4 }; 279 #else 280 static const uint16 MIN_SIZE = 4; 281 #endif 282 error_code()283 uint32 error_code() const { return (class_ << 8) | number_; } error_class()284 uint8 error_class() const { return class_; } number()285 uint8 number() const { return number_; } reason()286 const std::string& reason() const { return reason_; } 287 288 void SetErrorCode(uint32 code); SetErrorClass(uint8 eclass)289 void SetErrorClass(uint8 eclass) { class_ = eclass; } SetNumber(uint8 number)290 void SetNumber(uint8 number) { number_ = number; } 291 void SetReason(const std::string& reason); 292 293 bool Read(talk_base::ByteBuffer* buf); 294 void Write(talk_base::ByteBuffer* buf) const; 295 296 private: 297 uint8 class_; 298 uint8 number_; 299 std::string reason_; 300 }; 301 302 // Implements STUN/TURN attributs that record a list of attribute names. 303 class StunUInt16ListAttribute : public StunAttribute { 304 public: 305 StunUInt16ListAttribute(uint16 type, uint16 length); 306 ~StunUInt16ListAttribute(); 307 308 size_t Size() const; 309 uint16 GetType(int index) const; 310 void SetType(int index, uint16 value); 311 void AddType(uint16 value); 312 313 bool Read(talk_base::ByteBuffer* buf); 314 void Write(talk_base::ByteBuffer* buf) const; 315 316 private: 317 std::vector<uint16>* attr_types_; 318 }; 319 320 // Implements the TURN TRANSPORT-PREFS attribute, which provides information 321 // about the ports to allocate. 322 class StunTransportPrefsAttribute : public StunAttribute { 323 public: 324 StunTransportPrefsAttribute(uint16 type, uint16 length); 325 ~StunTransportPrefsAttribute(); 326 327 #if (_MSC_VER < 1300) 328 enum { SIZE1 = 4, SIZE2 = 12 }; 329 #else 330 static const uint16 SIZE1 = 4; 331 static const uint16 SIZE2 = 12; 332 #endif 333 preallocate()334 bool preallocate() const { return preallocate_; } preference_type()335 uint8 preference_type() const { return prefs_; } address()336 const StunAddressAttribute* address() const { return addr_; } 337 SetPreferenceType(uint8 prefs)338 void SetPreferenceType(uint8 prefs) { prefs_ = prefs; } 339 340 // Sets the preallocate address to the given value, or if 0 is given, it sets 341 // to not preallocate. 342 void SetPreallocateAddress(StunAddressAttribute* addr); 343 344 bool Read(talk_base::ByteBuffer* buf); 345 void Write(talk_base::ByteBuffer* buf) const; 346 347 private: 348 bool preallocate_; 349 uint8 prefs_; 350 StunAddressAttribute* addr_; 351 }; 352 353 // The special MAGIC-COOKIE attribute is used to distinguish TURN packets from 354 // other kinds of traffic. 355 const char STUN_MAGIC_COOKIE_VALUE[] = { 0x72, char(0xc6), 0x4b, char(0xc6) }; 356 357 // Returns the (successful) response type for the given request type. 358 StunMessageType GetStunResponseType(StunMessageType request_type); 359 360 // Returns the error response type for the given request type. 361 StunMessageType GetStunErrorResponseType(StunMessageType request_type); 362 363 } // namespace cricket 364 365 #endif // __STUN_H__ 366