Protocols/OSCAR/Sign On

From NINA Wiki
Revision as of 00:29, 14 February 2021 by AD (talk | contribs) (From Aleksandr Shutko: Detailed OSCAR login sequence description)
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)


NINA clients (AIM, ICQ, et al) have several ways to authenticate and sign on to the network. While AOL may have discontinued all legacy methods, we have brought them back so that all clients and other software that may interact with the network will be fully functional.

This page provides an overview of all of the available methods, primarily from the perspective of the sequence of events and linking to pages with further information.

Stage 1: Initial Authorization

Over the years, the NINA/ICQ/AIM backend has supported several different methods for authentication. Until the NINA project began taking over the responsibility for the OSCAR protocol, the only publicly supported login method was clientLogin.

We actually support all authentication methods, even legacy ones, in order to support the full range of clients. Due to complexity and level of detail, each method had been separated into sub-articles.

FLAP
This is the oldest method of sign on, used prior to AIM 3.5. It is not to be confused with the FLAP-level sign on for BOSS and other services.
BUCP
This method is used from AIM 3.5 to AIM 5.9, for ICQ, and can be wrapped in TLS.
UAS
Kerberos-based authentication is used in AIM 6+.
clientLogin
This web-based login can be used by both OSCAR clients and WebAPI clients.

Stage 2: Connecting to BOSS

Connect to the host and port (optionally over TLS) provided in the previous step, regardless of the method it was obtained.

Step #1 - Send FLAP SIGNON Frame

Once connected, the client should send a FLAP__FRAME_SIGNON with the login cookie and any version information it would like to provide.

Field Size Value
u08 flapHeader.startMarker '*'
u08 flapHeader.frameType 0x01 (FLAP__FRAME_SIGNON)
u16 flapHeader.sequenceNumber XX
u16 flapHeader.payloadLength YY
u32 version 0x01
u16 tlvs[0].tag 0x06 (FLAP__SIGNON_TAGS_LOGIN_COOKIE)
u16 tlvs[0].len 0x100
blob tlvs[0].value base64 decoded $cookie value from Step #2
u16 tlvs[1].tag 0x4A (OSERVICE__MULTICONN_FLAGS)
u16 tlvs[1].len 0x01
u08 tlvs[1].value 0x01
  1. It should then listen for a FLAP__FRAME_SIGNON from BOSS before continuing.
  2. Once it has received the FLAP__FRAME_SIGNON, the client can start sending SNAC messages to the server.


From Aleksandr Shutko: CLI_COOKIE: server BOS login request

CLI_COOKIE   


Client use this to login to BOS server. This packet contain cookie, received during authorization. Client should send it to FLAP channel 0x01. See also login sequence info.

 00 00 00 01 dword protocol version number


 00 06   word   TLV.Type(0x06) - authorization cookie
 xx xx   word   TLV.Length
 xx ..   array   authorization cookie
may contain other tlv from the following list (+).


Example SNAC dump with flap header:


  2A 01 10 1F 01 08 00 00 00 01 00 06 01 00 37 37 *.............77
  37 37 37 37 3F 29 44 42 7B 43 31 34 65 32 44 61 7777?)DB.C14e2Da
  31 44 42 66 65 34 42 30 32 30 30 44 61 44 44 39 1DBfe4B0200DaDD9
  42 35 63 32 35 42 63 33 30 64 44 61 32 66 33 66 B5c25Bc30dDa2f3f
  38 63 36 32 65 35 63 7C 65 38 40 41 41 41 41 41 8c62e5c.e8@AAAAA
  41 41 41 41 41 41 41 41 41 41 41 41 41 41 41 41 AAAAAAAAAAAAAAAA
  41 41 41 41 41 41 41 41 41 41 41 41 41 41 41 41 AAAAAAAAAAAAAAAA
  41 41 41 41 41 41 41 41 41 41 41 41 41 41 41 41 AAAAAAAAAAAAAAAA
  41 41 41 41 41 41 41 41 41 41 41 41 41 41 41 41 AAAAAAAAAAAAAAAA
  41 41 41 41 41 41 41 41 41 41 41 41 41 41 41 41 AAAAAAAAAAAAAAAA
  41 41 41 41 41 41 41 41 41 41 41 41 41 41 41 41 AAAAAAAAAAAAAAAA
  41 41 41 41 41 41 41 41 41 41 41 41 41 41 41 41 AAAAAAAAAAAAAAAA
  41 41 41 41 41 41 41 41 41 41 41 41 41 41 41 41 AAAAAAAAAAAAAAAA
  41 41 41 41 41 41 41 41 41 41 41 41 41 41 41 41 AAAAAAAAAAAAAAAA
  41 41 41 41 41 41 41 41 41 41 41 41 41 41 41 41 AAAAAAAAAAAAAAAA
  41 41 41 41 41 41 41 41 41 41 41 41 41 41 41 41 AAAAAAAAAAAAAAAA
  41 41 41 41 41 41 41 41 41 41 41 41 41 41       AAAAAAAAAAAAAA

Stage 3: Going Online

Once the connection has been established and the FLAP signon frames have been exchanged, the client can start sending SNACs to the server.

Step 1: Rights Requests

Usually the first thing the client sends are all the rights queries and a FEEDBAG__QUERY SNAC. It can and should send all these requests in parallel for a quicker login experience.

  1. Client queries the BUDDY foodgroup for rights: BUDDY__RIGHTS_QUERY
  2. Query the PD foodgroup rights: PD_RIGHTS_QUERY
  3. Query the LOCATE foodgroup rights: LOCATE_RIGHTS_QUERY
  4. Query the FEEDBAG foodgroup rights: FEEDBAG_RIGHTS_QUERY
  5. Query what the Buddy List and preferences are: FEEDBAG_QUERY

Step 2: FEEDBAG Use and Client Online

Once all the rights replies and feedbag replies are received, it is time to tell the server that the client is ready to proceed.

  1. First tell the server that the feedbag looks OK and the client is ready to use it: FEEDBAG_USE
  2. Next we tell the client we are ready to appear online to everyone else and our version numbers: OSERVICE_CLIENT_ONLINE

Step 3: Online

The client is now considered online, visible to other users, and will start to receive BUDDY__ARRIVED for any online buddies.

Next steps:


From Aleksandr Shutko: Detailed OSCAR login sequence description

 Login sequence   


  <>   Auth connect
  >>   cli_ident
  <<   srv_cookie
  <>   Auth disconnect
  <>   BOS connect
  >>   cli_cookie
  <<   SNAC(01,03)
  >>   SNAC(01,17)
  <<   SNAC(01,18)
  >>   SNAC(01,06)
  <<   SNAC(01,07)
  >>   SNAC(01,08)
  >>   SNAC(13,02)
  >>   SNAC(13,05)
  >>   SNAC(02,02)
  >>   SNAC(03,02)
  >>   SNAC(04,04)
  >>   SNAC(09,02)
  <<   SNAC(02,03)
  <<   SNAC(03,03)
  <<   SNAC(04,05)
  <<   SNAC(09,03)
  <<   SNAC(13,03)
  <<   SNAC(13,0F)
  >>   SNAC(13,07)
  >>   SNAC(02,04)
  >>   SNAC(04,02)
  >>   SNAC(01,1E)
  >>   SNAC(01,02)


From Aleksandr Shutko: Detailed OSCAR login sequence description

 Login sequence   


  <>   Auth connect
  >>   SNAC(17,06)
  <<   SNAC(17,07)
  >>   SNAC(17,02)
  <<   SNAC(17,03)
  <>   Auth disconnect
  <>   BOS connect
  >>   cli_cookie
  <<   SNAC(01,03)
  >>   SNAC(01,17)
  <<   SNAC(01,18)
  >>   SNAC(01,06)
  <<   SNAC(01,07)
  >>   SNAC(01,08)
  >>   SNAC(13,02)
  >>   SNAC(13,05)
  >>   SNAC(02,02)
  >>   SNAC(03,02)
  >>   SNAC(04,04)
  >>   SNAC(09,02)
  <<   SNAC(02,03)
  <<   SNAC(03,03)
  <<   SNAC(04,05)
  <<   SNAC(09,03)
  <<   SNAC(13,03)
  <<   SNAC(13,0F)
  >>   SNAC(13,07)
  >>   SNAC(02,04)
  >>   SNAC(04,02)
  >>   SNAC(01,1E)
  >>   SNAC(01,02)

FLAP Login Sign On Errors (Temp)

Standard Format Login Errors during Phase 1

These occur in response to the initial Phase 1 login command sent from the client. All Standard Format login errors follow this format. This error command is always in the Command Family 0x04. All variable-length strings are assumed to be 1 byte long when doing position numbers.

Position Data Size Data
1 Word 0x0001
3 Word Screen Name Length (not including null)
5 ASCIIZ String Screen Name that failed (null-terminated)
6 Byte 0x04
7 Word Error Message URL Length (not including null)
9 ASCIIZ String Error Message URL (null-terminated)
10 Byte 0x08
11 Byte 0x00
12 Byte 0x02
13 Word Specific Error Code

The current list of known "Specific Error Code"s:

Specific Error Code Error Msg URL Meaning
0x0001 http://www.aim.aol.com/errors/UNREGISTERED_SCREENNAME.html Invalid Screen Name
0x0005 http://www.aim.aol.com/errors/MISMATCH_PASSWD.html SN/Pasword Mismatch (Invalid Password)


From Aleksandr Shutko: AUTH_FAILED: server authorization failed response

AUTH_FAILED   


This is the server error reply for for cli_ident packet. It contain authorization error code (see list bellow). It always come from FLAP channel 0x04. See also channel 0x01 authorization sequence info. Here is known authorization error codes list:

  0x0001   Invalid nick or password
  0x0002   Service temporarily unavailable
  0x0003   All other errors
  0x0004   Incorrect nick or password, re-enter
  0x0005   Mismatch nick or password, re-enter
  0x0006   Internal client error (bad input to authorizer)
  0x0007   Invalid account
  0x0008   Deleted account
  0x0009   Expired account
  0x000A   No access to database
  0x000B   No access to resolver
  0x000C   Invalid database fields
  0x000D   Bad database status
  0x000E   Bad resolver status
  0x000F   Internal error
  0x0010   Service temporarily offline
  0x0011   Suspended account
  0x0012   DB send error
  0x0013   DB link error
  0x0014   Reservation map error
  0x0015   Reservation link error
  0x0016   The users num connected from this IP has reached the maximum
  0x0017   The users num connected from this IP has reached the maximum (reservation)
  0x0018   Rate limit exceeded (reservation). Please try to reconnect in a few minutes
  0x0019   User too heavily warned
  0x001A   Reservation timeout
  0x001B   You are using an older version of ICQ. Upgrade required
  0x001C   You are using an older version of ICQ. Upgrade recommended
  0x001D   Rate limit exceeded. Please try to reconnect in a few minutes
  0x001E   Can't register on the ICQ network. Reconnect in a few minutes
  0x0020   Invalid SecurID
  0x0022   Account suspended because of your age (age < 13)



 00 01   word   TLV.Type(0x01) - screen name (uin)
 xx xx   word   TLV.Length
 xx ..   string   Screen name (uin)
 00 04   word   TLV.Type(0x04) - error page description url
 xx xx   word   TLV.Length
 xx ..   string (ascii)   error description page url string
 00 08   word   TLV.Type(0x08) - authorization error
 00 02   word   TLV.Length
 xx xx   word   Authorization error code (see above)


 00 0C   word   TLV.Type(0x0C) - unknown
 00 02   word   TLV.Length
 xx xx   word   unknown field
 May contain other tlv from the following list


Example SNAC dump with flap header:


  2A 04 C3 2C 00 16 00 01 00 06 37 37 37 37 37 37 *..,......777777
  00 08 00 02 00 05 00 0C 00 02 00 01             ............

TLV Class: FLAP__SIGNON_TAGS

These tags are used in the FLAP signon frame to BOS. They appear right after the 4 byte version number.

@MAKE NOTE: Difference between ones used if BUCP is in use and ones if clientLogin or w/e was used

Name Tag Type Notes
OSERVICE__TLV_TAGS_CLIENT_IDENTITY 0x03 string Yet another client name
OSERVICE__TLV_TAGS_LOGIN_COOKIE 0x06 blob Login cookie returned by startOSCARSession
OSERVICE__TLV_TAGS_MAJOR_VERSION 0x17 uint16 (word) Client major version: (1) if the client version is "1.2.3"
OSERVICE__TLV_TAGS_MINOR_VERSION 0x18 uint16 (word) Client minor version: (2) if the client version is "1.2.3"
OSERVICE__TLV_TAGS_POINT_VERSION 0x19 uint16 (word) Client minor version: (3) if the client version is "1.2.3"
OSERVICE__TLV_TAGS_BUILD_NUM 0x1A uint16 (word) Client build number, usually monotonically increasing
OSERVICE__TLV_TAGS_MULTICONN_LEVEL 0x4A uint8 (byte) [Class: OSERVICE__MULTICONN_FLAGS] Should almost always be 0x01
OSERVICE__TLV_TAGS_CLIENT_RECONNECT 0x94 uint8 (byte) Client claims it is reconnecting because it got knocked off

Class: OSERVICE__MULTICONN_FLAGS

These flags control how multiple instances are handled by the servers and if current sessions need to be bumped off when a new session signs on.

Name Value Notes
OSERVICE__MULTICONN_LEVEL_OLD_CLIENT 0x00 Don't use
OSERVICE__MULTICONN_LEVEL_MULTI 0x01 This is a recent client that understands multiple instances
OSERVICE__MULTICONN_LEVEL_SINGLE 0x03 This is a recent client that understands multiple instances but does not want them