Protocols/OSCAR/Sign On: Difference between revisions
No edit summary |
No edit summary |
||
Line 14: | Line 14: | ||
Next steps: | Next steps: | ||
* [[Protocols/OSCAR/Sign_On# | * [[Protocols/OSCAR/Sign_On#Stage_2:_Connecting_to_BOSS|Connecting to BOSS]] | ||
=== BUCP === | === BUCP === | ||
Next steps: | Next steps: | ||
* [[Protocols/OSCAR/Sign_On# | * [[Protocols/OSCAR/Sign_On#Stage_2:_Connecting_to_BOSS|Connecting to BOSS]] | ||
=== UAS === | === UAS === | ||
Next steps: | Next steps: | ||
* [[Protocols/OSCAR/Sign_On# | * [[Protocols/OSCAR/Sign_On#Stage_2:_Connecting_to_BOSS|Connecting to BOSS]] | ||
=== clientLogin === | === clientLogin === | ||
Line 103: | Line 103: | ||
Next steps: | Next steps: | ||
* [[Protocols/OSCAR/Sign_On# | * [[Protocols/OSCAR/Sign_On#Stage_2:_Connecting_to_BOSS|Connecting to BOSS]] | ||
* [[Protocols/OSCAR/Sign_On/Single_Sign_On_to_Web_Pages|Single Signon to Web Pages] Tutorial | * [[Protocols/OSCAR/Sign_On/Single_Sign_On_to_Web_Pages|Single Signon to Web Pages] Tutorial | ||
Revision as of 11:08, 26 March 2020
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.
FLAP
This refers to the FLAP__FRAME_SIGNON authentication method for a user to authenticate to the network. This works similar to, but is not the same as, FLAP__FRAME_SIGNON sequences used to connect to BOS and other services.
Next steps:
BUCP
Next steps:
UAS
Next steps:
clientLogin
The clientLogin method allows the client to collect the user name and password and make a simple web service call to retrieve authentication credentials. These credentials are then used in future web service calls to sign requests to help against man in the middle and reply attacks.
Authentication and requesting the BOSS connection normally requires two web service calls.
- The clientLogin call checks the key, loginId, and password and performs any rate limit or captcha challenges
- The startOSCARSession call requests a BOSS connection and returns where the client needs to connect to and a one time use cookie to present to the BOSS server for authentication. This call requires an OAuth style URL signing which is described along with clientLogin. URL signing requires the computers clock to be accurate or the use of hostTime returned by clientLogin, parameters are in alphabetical order, and percent-encoding uses upper case characters.
Here is an example of the sign on process:
Step #1 - Authentication Request
The client should collect the loginId and password for the user. It should not do any length or character validations. A POST web service call should be made to:
https://api.screenname.nina.bz/auth/clientLogin?f=[FORMAT]
...with a POST body of...
k=[KEY]&s;=[LOGINID]&pwd;=[PASSWORD]&clientVersion;=[CLIENTVERSION]&clientName;=[clientName]
...and a content type of application/x-www-form-urlencoded with the following values for the query string:
- [FORMAT]
- Format to return the response in; XML, AMF3, PHP, JSON are all supported
- [KEY]
- Client key obtained from here
- [LOGINID]
- URI encoded loginId entered by the user
- [PASSWORD]
- URI encoded password entered by the user
- [clientVersion]
- A single number representing the client version number for metrics and tracking, usually the build number
- [clientName]
- URI encoded friendly name representing the client being used
Step #2 - Authentication Reply
There can be several intermediate replies before a successful authentication is completed. These include incorrect passwords, need for extra credentials, or the need for the user to complete a CAPTCHA challenge. To test if a client supports CAPTCHA challenges correctly it can add an extra parameter of forceRateLimit=true. It is recommended that all clients test CAPTCHA support.
When successfully authenticated, the token->a and sessionSecret need to be extracted from the results. The sessionSecret is used to generate a sessionKey that will be used on future calls. For example, the startOSCARSession service, the start page, and the expressions page all require the sessionKey.
The sessionKey is calculated using:
sessionKey = hmac_sha256_base64($sessionSecret, $password);
For example, if the sessionSecret was "AB123FO" and the user's password was "weakpassword", then the sessionKey would be "ZyCaA1QlF8oBzh0QXeXNCf+7qUItBaiXwk3xOVcFZhY=" Historically some hmac_sha256_base64 do not return valid base64 data. All these APIs require valid base64 data, so check the implementation being used.
Step #3 - Start OSCAR Session Request
Once successfully authenticated, the client needs to connect to the BOSS server to start the AIM session. This is done by requesting a BOSS reservation and then connecting to the BOSS server. Requesting the BOSS reservation is done with a startOSCARSession WIM call.
This call requires an OAuth style URL signing which is described along with clientLogin. URL signing requires the computers clock to be accurate or the use of hostTime returned by clientLogin, parameters are in alphabetical order, and percent-encoding uses upper case characters.
- [FORMAT]
- Format to return the response in: XML, AMF3, PHP, JSON are all supported
- [KEY]
- Client key obtained from here
- [TOKEN]
- The URI encoded token extracted from clientLogin
- [clientVersion]
- A single number representing the client version number for metrics and tracking
- [clientName]
- A URI encoded friendly name representing the client being used
- [TIME]
- The current time, in seconds, since UNIX EPOCH
- [USETLS]
- Should the connection to BOSS use TLS
$uri = "http://api.oscar.aol.com/aim/startOSCARSession"; $queryString = "a=[TOKEN]&clientName;=CLIENTNAME]&clientVersion;=[CLIENTVERSION]&f;=[FORMAT]&k;=[KEY]&ts;=[TIME]&useTLS;=[USETLS]"; $hashData= "GET&" . uri_encode($uri) . "&" . uri_encode($queryString); $digest = hmac_sha256_base64($hashData, $sessionKey); $url = $uri . "?" . $queryString . "&sig;_sha256=$digest";
Step #4 - Start OSCAR Session Reply
On a successful startOSCARSession, the backend will return where the BOSS server is running, the cookie to present to the BOSS server, and the certname that should be validated when connecting to BOSS if TLS was selected. At this point the client should connect to BOSS using FLAP or FLAP over TLS and start sending SNACs back and forth.
Next steps:
- Connecting to BOSS
- [[Protocols/OSCAR/Sign_On/Single_Sign_On_to_Web_Pages|Single Signon to Web Pages] Tutorial
Stage 2: Connecting to BOSS
Stage 3: Going Online
------------------------------------------------------------------------------------------- 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 |