Protocols/OSCAR/TLV

From NINA Wiki
Revision as of 10:34, 14 February 2021 by AD (talk | contribs)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigation Jump to search
OSCAR Protocol
IntroductionTermsClients
Basic
DatatypesFLAPSNACTLV
UUIDsErrorsTool IDs
Host Interaction
Rate LimitsMigrationMessages
Other Services
ADMINADVERTALERT
BARTBOSBUCPCHAT
CHAT_NAV
Tutorials
Sign OnBARTRendezvous
ICBMLocateBuddies
Foodgroups
OSERVICE (0x0001)
LOCATE (0x0002)
BUDDY (0x0003)
ICBM (0x0004)
ADVERT (0x0005)
INVITE (0x0006)
ADMIN (0x0007)
POPUP (0x0008)
PD (0x0009)
USER_LOOKUP (0x000A)
STATS (0x000B)
TRANSLATE (0x000C)
CHAT_NAV (0x000D)
CHAT (0x000E)
ODIR (0x000F)
BART (0x0010)
FEEDBAG (0x0013)
ICQ (0x0015)
BUCP (0x0017)
ALERT (0x0018)
PLUGIN (0x0022)
UNNAMED_FG_24 (0x0024)
MDIR (0x0025)
ARS (0x044A)

TLVs notes from another

TLVs are a very common structure used in the OSCAR protocol to represent dynamically typed data. Parsers should always ignore unknown tags as to not break old clients when new protocol items are added. Possible values for tags are determined by where the TLV is in the protocol; these possible values belong to a TLV class. In the wild, the term type is sometimes used interchangeably with tag, however this document uses tag to reference the integer value associated with the TLV and type as the datatype associated with that tag.

Name Size Notes
Type uint16 (word) Numeric type or "tag" of the data, possible values are defined in the TLV class for the group of TLVs
Length uint16 (word) Length in bytes of the variable data
Value blob The data inside the TLV of len length; usually another datatype is used to represent the data - this is described in the TLV class

TLVs are usually used in an array of TLV form, allowing the protocol to easily be expanded. Having just one TLV without an array does not gain much since it only allows one item to be described. There are two common methods for adding an array of TLVs to datatypes and SNACs. An additional method also exists to add an array of TLVs to SNACs.

The most common is a tlvBlock which is a u16 number of TLVs followed by that many TLVs. The less common is a tlvLBlock which instead of counting the number of TLVs, counts the size of all the TLVs. The third, which is only available in SNACs, is the tlvRestBlock which says any remaining bytes in the SNAC are TLVs.

Name Size Notes
tlvBlock uint16 (word) + data Two byte number of elements, followed by that many elements
tlvLBlock uint16 (word) + data Two byte length of elements, followed by that many bytes of elements

Common TLVs

From Aleksandr Shutko: Common tlv set.

Common tlv set.


 


Here is a common set of widely used tlvs:


 00 01   word   TLV.Type(0x01) - screen name (uin)
 xx xx   word   TLV.Length
 xx ..   string   screen name (uin)
 00 02   word   TLV.Type(0x02) - new password
 xx xx   word   TLV.Length
 xx ..   array   new password string
 00 03   word   TLV.Type(0x03) - client identity string
 xx xx   word   TLV.Length
 xx ..   string   client identity string (name, version)
 00 04   word   TLV.Type(0x04) - error description url
 xx xx   word   TLV.Length
 xx ..   string   error description url string
 00 05   word   TLV.Type(0x05) - reconnect here
 xx xx   word   TLV.Length
 xx ..   string   server address & port string
 00 06   word   TLV.Type(0x06) - authorization cookie
 xx xx   word   TLV.Length
 xx ..   array   authorization cookie
 00 07   word   TLV.Type(0x07) - snac version
 xx xx   word   TLV.Length
        ?
 00 08   word   TLV.Type(0x08) - error subcode
 xx xx   word   TLV.Length
 xx xx   word   error subcode (family specific)
 00 09   word   TLV.Type(0x09) - disconnect reason
 xx xx   word   TLV.Length
 xx xx   word   disconnect reason (see table below)
 00 0A   word   TLV.Type(0x0A) - reconnect hostname
 xx xx   word   TLV.Length
        ?
 00 0B   word   TLV.Type(0x0B) - url
 xx xx   word   TLV.Length
 xx ..   string   url
 00 0C   word   TLV.Type(0x0C) - debug data
 xx xx   word   TLV.Length
 xx xx   word   debug data
 00 0D   word   TLV.Type(0x0D) - service (family) id
 xx xx   word   TLV.Length
 xx xx   word   service (family) id
 00 0E   word   TLV.Type(0x0E) - client country (2 symbols)
 xx xx   word   TLV.Length
 xx ..   string   client country
 00 0F   word   TLV.Type(0x0F) - client language (2 symbols)
 xx xx   word   TLV.Length
 xx ..   string   client language
 00 10   word   TLV.Type(0x10) - script
 xx xx   word   TLV.Length
        ?
 00 11   word   TLV.Type(0x11) - user email
 xx xx   word   TLV.Length
 xx ..   string   user email string
 00 12   word   TLV.Type(0x12) - old password
 xx xx   word   TLV.Length
 xx ..   string   old password string
 00 13   word   TLV.Type(0x13) - registration status
 xx xx   word   TLV.Length
 xx xx   word   registration status (1 - no disclosure, 2 - limit disclosure, 3 - full disclosure (?))
 00 14   word   TLV.Type(0x14) - distribution number
 00 04   word   TLV.Length
 xx xx xx xx   dword   distribution number
 00 15   word   TLV.Type(0x15) - personal text
 xx xx   word   TLV.Length
        ?
 00 16   word   TLV.Type(0x16) - client id
 00 02   word   TLV.Length
 xx xx   word   client id number
 00 17   word   TLV.Type(0x17) - client major version
 00 02   word   TLV.Length
 xx xx   word   client major version
 00 18   word   TLV.Type(0x18) - client minor version
 00 02   word   TLV.Length
 xx xx   word   client minor version
 00 19   word   TLV.Type(0x19) - client lesser version
 00 02   word   TLV.Length
 xx xx   word   client lesser version
 00 1A   word   TLV.Type(0x1A) - client build number
 00 02   word   TLV.Length
 xx xx   word   client build number
 00 25   word   TLV.Type(0x25) - password hash (MD5)
 00 10   word   TLV.Length
      xx xx xx xx
 xx xx xx xx
 xx xx xx xx
 xx xx xx xx
  array   password hash (MD5)
 00 40   word   TLV.Type(0x40) - latest beta build number
 xx xx   word   TLV.Length
 xx xx xx xx   dword   latest beta build number
 00 41   word   TLV.Type(0x41) - latest beta install url
 xx xx   word   TLV.Length
 xx ..   string   latest beta install url
 00 42   word   TLV.Type(0x42) - latest beta info url
 xx xx   word   TLV.Length
 xx ..   string   latest beta info url
 00 43   word   TLV.Type(0x43) - latest beta version
 xx xx   word   TLV.Length
 xx ..   string   latest beta version
 00 44   word   TLV.Type(0x44) - latest release build number
 xx xx   word   TLV.Length
 xx xx xx xx   dword   latest release build number
 00 45   word   TLV.Type(0x45) - latest release install url
 xx xx   word   TLV.Length
 xx ..   string   latest release install url
 00 46   word   TLV.Type(0x46) - latest release info url
 xx xx   word   TLV.Length
 xx ..   string   latest release info url
 00 47   word   TLV.Type(0x47) - latest release version
 xx xx   word   TLV.Length
 xx ..   string   latest release version
 00 48   word   TLV.Type(0x48) - beta digest signature (MD5)
 00 20   word   TLV.Length
 xx ...   string   hexadecimal string for beta digest signature (MD5)
 00 49   word   TLV.Type(0x49) - release digest signature (MD5)
 00 20   word   TLV.Length
 xx ...   string   hexadecimal string for release digest signature (MD5)
 00 54   word   TLV.Type(0x54) - change password url
 xx xx   word   TLV.Length
 xx ...   string   change password url


 
 


From Aleksandr Shutko: Basic OSCAR information: TLV

 TLV (Type-Length-Value) tuple description 
 

     TLVs are a very convenient and efficient method of putting data into an organized format, especially variable length strings, etc. TLV literally stands for "Type, Length, Value". And that's exactly what it is: a 16bit Type code, a 16bit value for the length of the Value field, and then the actual data in the Value field (variable length). Here is TLV format:

 xx xx   word   TLV type number
 xx xx   word   TLV length value
 ...... TLV data


     TLVs can be be in SNACs, but that's not required. TLVs often are used directly in the FLAP Data Field, but normally are inside of SNACs. More than one TLV of each Type code may exist in a single FLAP command (SNAC or not). TLVs must follow the strict tuple-rule, or they're really not TLVs, they're raw data. One tlv may contain nested tlv chain inside.

     TLVs are a big win. They make sending a variable length string like, e.g., "afritz@iname" as simple as defining a TLV with values {0x0011, 0x000c, "afritz@iname.com"}. (The type 0x0011 is used throughout the authorization process as the "email address type".) A side note about strings: strings in this protocol are never NULL-terminated. If they look like they are, that's probably a word-length value behind it.