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)

Connection overview

3.0 Connection Management

Every protocol begins with a single step...

3.1 The Life and Times of OSCAR, the Real-Time Messenger (Overview)

Before connections are made to any of the BOS or special-purpose servers, you must first be authorized by the Authorization Server (login.oscar.aol.com). This will return a cookie that automatically authorizes you to connect to any of the BOS or special-purpose (eg, Advertisement, Chat, etc) servers. This streamlines the login process quite a bit.

The normal steps taken to create an average AIM session are as follows:

	1. Connect to Authorizer and retrieve Cookie.
	2. Connect to the Authorizer-recommended BOS server and initiate BOS service
	3. (Optional) Connect to Advertisements server and retrieve first block of ads (repeat at regular interval)
	4. (Optional) Connect to any other non-BOS services that may be available (AFAIK, none at this point)

The last three steps may actually be done in any order (and for the third and fourth step, probably not at all). But, authorization must always come first.

3.2 OSCAR Authorization

OSCAR has a sense of the "single-login" concept. You login once and get a "cookie" that automatically authorizes you to use any of the OSCAR-associated services, just by sending them your cookie.

The first step of the process is connecting to the Authorizer. This currently resides at the DNS address login.oscar.aol.com. It also appears that you may connect to any port and get the same response. (The AIM clients use 5190, James uses 443, I've used 21 (telnet) before as well.)

After the connection, the client must send the "Authorization Request" command. The server also sends a 4b+FLAP command to the client after each new connection, called the "Connection Acknowledge" command. This may be accepted and processed before or after the inital command from the client (for use it dispatch routines, this can be used as a sign that the inital login should be sent). The response to this ("Authorization Response") contains the cookie to be used for the BOS and other connections. But, if the the Authorization Request fails, you'll get back any one of the several "Authorization Errors". After you've gotten your cookie, it's safe to disconnect yourself from the Authorizer.

3.3 BOS Singon

The next step is usually to connect to and initiate service with the BOS. The address of the BOS you should connect to is listed in the Authorization Response. The first step for this connection is to send the BOS-Signon command to the server. But, for the purposes of dispatching, it may be best to wait to send this command until the Connection Acknowledge command is recieved from the server immediatly after the connection opens, although this is optional and can be processed afterwards.

Normal BOS signon looks something like this...

	1. Server sends Connection Acknowledge
	2. Client sends BOS SignOn command.
	3. Server sends BOS Host-Ready.
	4. Client sends Rate Information Request.
	5. Server sends Rate Information Response.
	6. Client sends Rate Information Acknowledge.
	7. Client requests (in no particular order):
		+ Set Privacy Flags
		+ Request Our User Information
		+ Request New Service
		+ Optional: Request BOS Rights
		+ Optional: Request Buddy List Rights
		+ Optional: Request Locate Rights
		+ Optional: Request ICBM Parameter Information
	8. Server sends all the information requested (again, in no particular order):
		+ Our User Information Response
		+ BOS Rights Response
		+ Buddy List Rights Response
		+ Locate Rights Response
		+ ICBM Parameter Information Response
		+ New Service Redirect
	9. (Aparently Optional) Client sends a SNAC of family 0x0009, subtype 0x0004, data {0x0000, 0x001f}.
	10. (Aparently Optional) Client sends a SNAC of family 0x0009, subtype 0x0007, no data.
	11. Client sends up buddy list using the Add Buddy to Buddy List command.
	12. Client sends up user's profile using the Set User Information command.
	13. Client sends the Set Initial ICBM Parameter command.
	14. Client sends the Client Ready command.

At that point, you can either quit and begin processing live events, or you may use the information provided in the New Service Redirect command to connect to the Advertisments or other server.

3.4 Logout

Logging off of AIM is about the simplest thing you can do. The abrupt way to do it is just closing the connection to the main message server. That will normally do it. Sometimes, though, the AIM client sends a small command to the server before it closes, but expects no response. I've found the best way is just to close it forget about it.

This "logout command" is just a FLAP without a Data Field, and the Data Field Length set to 0x0000.

[Source: Server] Connection Acknowledge
This is sent by the server after a new connection has been opened and is ready for duplex operation.

Container	Data				TLV Type
RAW		FLAP Header (channel 0x01)
DWORD		FLAP version (0x00000001)

[Source: Client] Authorization Request - notes from another

Send as the first command to the Authorizer, and is used for requesting authorization and the associated cookie.

Container	Data				TLV Type
RAW		FLAP Header (channel 0x01)
RAW		0x0000
RAW		0x0001
TLV1		Screen Name			0x0001
TLV2		"Encrypted" Password		0x0002
TLV3		ClientProfile			0x0003
TLV4		Unknown: 0x0001			0x0016
TLV5		Client Version Major		0x0017
TLV6		Client Version Minor		0x0018
TLV7		Client Version Build		0x001a
TLV8		Country Code			0x000e
TLV9		Language Code			0x000f
TLV10		Unknown: 0x0015			0x0009

[Source: Server] Authorization Successful Response - notes from another

This is sent in response to successful completion of the Authorization Requeset command. This contains the cookie used to connect to the rest of the BOS and AIM-related services.

Container	Data				TLV Type
RAW		FLAP Header (channel 0x04)
TLV		Screen Name			0x0001
TLV		BOS Server IP			0x0005
TLV		Authorization Cookie		0x0006
TLV		EMail Address			0x0011
TLV		Registration Status		0x0013

[Source: Server] Auth error notes from another

This/these are sent back instead of the Authorization Response command in the case of authorization failure. 

Container	Data				TLV Type
RAW		FLAP Header (channel 0x04)
TLV		Screen Name			0x0001
TLV		Error Message URL		0x0004
TLV		Error Code			0x0008

Currently Known Error Codes for TLV Type 0x0008:

Error Code	0x0001
	http://www.aim.aol.com/errors/UNREGISTERED_SCREENNAME.html
	Invalid Screen Name

Error Code	0x0005
	http://www.aim.aol.com/errors/MISMATCH_PASSWD.html
	SN/Pasword Mismatch (Invalid Password)

BOS Signon Request [Source: Client]

Send as the first command to the BOS connection. The Cookie comes from the Authorization Response.

Container	Data				TLV Type
RAW		FLAP Header (channel 0x01)
RAW		0x0000
RAW		0x0001
TLV		Authorization Cookie		0x0006

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)

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