Protocols/OSCAR/Sign On

OSCAR Protocol

Introduction • Terms • Clients

Basic

Datatypes • FLAP • SNAC • TLV

UUIDs • Errors • Tool IDs

Host Interaction

Rate Limits • Migration • Messages

Other Services

ADMIN • ADVERT • ALERT

BART • BOS • BUCP • CHAT

CHAT_NAV

Tutorials

Sign On • BART • Rendezvous

ICBM • Locate • Buddies

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:

• Getting a User's Buddy Icon
• Sending and Receiving typing events.
• Sending and Receiving IMs.
• Getting a User's Buddy Info

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

From Aleksandr Shutko: Detailed OSCAR login sequence description

OSCAR login

Login stage I:   <a href="#l0001">Authorization</a>  Login stage II:   <a href="#l0002">Protocol negotiation </a>  Login stage III:   <a href="#l0003">Services setup</a>  Login stage IV:   <a href="#l0004">Final actions</a>  Example #1:   Login with MD5 based authorization  Example #2:   Login with channel 0x01 based authorization

<a name="L0001"></a>Login stage I: Authorization         Currently there is two ways to pass authentification in OSCAR protocol. First is FLAP channel 0x01 authorization (password not crypted but roasted), second is MD5 based where password is MD5 crypted. In both ways server could return error or authorization cookie + BOS address. Here is both auth sequences (client<->server):  1. Channel 0x01 authorization (success)   <>   connect   Client connects to authorizer server   >>   cli_ident   Client send login request   <<   srv_cookie   Server reply via BOS address / cookie   <>   disconnect   Client disconnects from authorizer  2. MD5 based authorization   <>   connect   Client connects to authorizer server   >>   SNAC(17,06)   Client sends md5-authkey request   <<   SNAC(17,07)   Server sends md5-authkey string   >>   SNAC(17,02)   Client sends authorization request   <<   SNAC(17,03)   Server sends authorization reply   <>   disconnect   Client disconnects from authorizer      In channel 0x01 authorization server may replace srv_cookie packet reply via auth_failed packet which contain authorization error code. In MD5 based authorization sequence server always reply via SNAC(17,03) which may contain cookie / BOS address or authorization error code.      When authorization sequence successfully finishes client has authorization cookie, ip address and port of the BOS server. At this point it should disconnect from authorizer and connect to BOS. This is the point where login stage II (protocol negotiation) started.

<a name="L0002"></a>Login stage II: Protocol negotiation         After authorization client should extract BOS server/auth cookie from reply packet, connect to BOS and send cookie via special FLAP channel 0x01 packet named cli_cookie. In reply server will return list of supported services - SNAC(01,03). Then client should ask needed services version numbers using SNAC(01,17). After that client will receive services version numbers server has - SNAC(01,18). Note that client never shouldn't send snacs to services not listed in SNAC(01,03). It should use service request SNAC(01,04) instead.  Protocol negotiation   <>   connect   Client connects to BOS server   >>   cli_cookie   Client sends cookie   <<   SNAC(01,03)   Server sends supported services list   >>   SNAC(01,17)   Client ask for services version numbers   <<   SNAC(01,18)   Server sends its services version numbers      After negotiation client should setup current connection. It request rate limitations information via SNAC(01,06). Then server will return connection rate limitations info - SNAC(01,07). At this point client start calculating its rate level on every SNAC it send. Server rate limitations information SNAC should be acked using SNAC(01,08). Now connection ready.  Protocol negotiation   >>   SNAC(01,06)   Client ask server for rate limits info   <<   SNAC(01,07)   Server sends rate limits information   >>   SNAC(01,08)   Client ack connection rate limits

<a name="L0003"></a>Login stage III: Services setup         Most of the services has limitations which you can request via SNAC(xx,02). For example client should know max_contact_buddies for BLM service. ICBM service has message default limits and client can change them as you need. Client also should send its capabilities list to Location service.  Protocol negotiation   >>   SNAC(02,02)   Client ask server location service limitations   <<   SNAC(02,03)   Server replies via location service limitations   >>   SNAC(02,04)   Client sends its capabilities / profile to server   >>   SNAC(03,02)   Client ask server BLM service limitations   <<   SNAC(03,03)   Server replies via BLM service limitations   >>   SNAC(04,04)   Client ask server for ICBM service parameters   <<   SNAC(04,05)   Server sends ICBM service parameters to client   >>   SNAC(04,02)   Client change default ICBM parameters command   >>   SNAC(09,02)   Client ask server PRM service limitations   <<   SNAC(09,03)   Server sends PRM service limitations to client   >>   SNAC(13,02)   Client ask server for SSI service limitations   <<   SNAC(13,03)   Server sends SSI service limitations to client   >>   SNAC(13,05)   Client check if its local SSI copy is up-to-date   <<   SNAC(13,0F)   Server tell client its local copy up-to-date   >>   SNAC(13,07)   Client activates server SSI data      Note that this order is not strict and client can send several requests and then wait for replies. But it should remember about rate limitations.

<a name="L0004"></a>Login stage IV: Final actions         This is last login actions you should perform. ICQ client at this stage set its DC information and status on main connection via SNAC(01,1E). Login sequence finishes by client ready SNAC(01,02) which contain version/build numbers for protocol dlls.  Final actions   >>   SNAC(01,1E)   Client sends its DC info and status to server   >>   SNAC(01,02)   Client READY command      After SNAC(01,02) client command server start broadcast client presence to its buddies and client start receiving messages and presence notifications. ICQ client should also check for offline messages.