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.
Contents
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 |
- It should then listen for a FLAP__FRAME_SIGNON from BOSS before continuing.
- Once it has received the FLAP__FRAME_SIGNON, the client can start sending SNAC messages to the server.
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.
- Client queries the BUDDY foodgroup for rights: BUDDY__RIGHTS_QUERY
- Query the PD foodgroup rights: PD_RIGHTS_QUERY
- Query the LOCATE foodgroup rights: LOCATE_RIGHTS_QUERY
- Query the FEEDBAG foodgroup rights: FEEDBAG_RIGHTS_QUERY
- 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.
- First tell the server that the feedbag looks OK and the client is ready to use it: FEEDBAG_USE
- 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
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 |
