Protocols/OSCAR/Sign On

From NINA Wiki
Revision as of 03:24, 27 March 2020 by AD (talk | contribs) (→‎Step 3: Online)
Jump to navigation Jump to search
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.

  1. The clientLogin call checks the key, loginId, and password and performs any rate limit or captcha challenges
  2. 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:

[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

Example:

URL: 

https://api.screenname.nina.bz/auth/clientLogin?f=xml

POST Data: 

k=thekey&s;=chattingChuck&pwd;=WeakPassword&clientVersion;=3&clientName;=Cool+Client

Assuming correct loginId, password, and no CAPTCHA challenge, a good response will look like the following: 

<response xmlns="https://api.login.nina.bz">
  <statusCode>200</statusCode>
  <statusText>OK</statusText>
  <data>
    <token>
      <expiresIn>86400</expiresIn>      <a>%2FwEAAAAAm3uC7kLggQUTUxDaptz5ddrYlsBinH5jBpi3aKVFOwRZUdy4VC3HBXkdtUaFOTM8E9og492eGQi3X0cIrwRfN5SsuA%2BE9nGhXtbQt%2BHoaa8Fw9yMTuuuks3%2F8ZRh0IyGOaLWhQssgtB3vEoEEQPSc4ZZcUARXm0b3GBfEW5E3QGjTvi6tRPsVpmnfSQ%3D</a>
    </token>
    <sessionSecret>m3UPFGcH5hmKSv24</sessionSecret>
  </data>
</response>

Extract the token->a and sessionSecret elements and save for later.

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 (see Step #1). 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.

Example: This example is based on this and the previous step. 

$sessionKey = hmac_sha256_base64("m3UPFGcH5hmKSv24", "WeakPassword");

It will look something like: 

$sessionKey = "wEOki901gedaIeJbMAy5k+hv4iJgfvshgM+cWtk+s1g=";

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.nina.bz/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";

The above will look something like this: 

$uri = "http://api.oscar.nina.bz/aim/startOSCARSession";
$queryString = "a=" 
   . uri_encode("%2FwEAAAAAm3uC7kLggQUTUxDaptz5ddrYlsBinH5jBpi3aKVFOwRZUdy4VC3HBXkdtUaFOTM8E9og492eGQi3X0cIrwRfN5SsuA" 
       . "%2BE9nGhXtbQt%2BHoaa8Fw9yMTuuuks3%2F8ZRh0IyGOaLWhQssgtB3vEoEEQPSc4ZZcUARXm0b3GBfEW5E3QGjTvi6tRPsVpmnfSQ%3D") 
   . "&clientName;=" . uri_encode("Cool Client")
   . "&clientVersion;=3&f;=xml&k;=thekey&ts;=1203799990";
$hashData= "GET&" . uri_encode($uri) . "&" . uri_encode($queryString);
$digest = hmac_sha256_base64($hashData, $sessionKey);
$url = $uri . "?" . $queryString . "&sig;_sha256=$digest";
// The above $url may also have the parameter of _sha25sig_sha256 instead of the client so chooses.

The above variables should have the values that look something like: 

$queryString = "a=%252FwEAAAAAm3uC7kLggQUTUxDaptz5ddrYlsBinH5jBpi3aKVFOwRZUdy4VC3HBXkdtUaFOTM8E9og492eGQi3X0cIrwRfN5SsuA%252BE9nGhXtbQt%252BHoaa8Fw9yMTuuuks3%252F8ZRh0IyGOaLWhQssgtB3vEoEEQPSc4ZZcUARXm0b3GBfEW5E3QGjTvi6tRPsVpmnfSQ%253D&clientName;=Cool%20Client&clientVersion;=3&f;=xml&k;=thekey&ts;=1203799990";

$hashData = "GET&http;%3A%2F%2Fapi.oscar.aol.com%2Faim%2FstartOSCARSession&a;%3D%25252FwEAAAAAm3uC7kLggQUTUxDaptz5ddrYlsBinH5jBpi3aKVFOwRZUdy4VC3HBXkdtUaFOTM8E9og492eGQi3X0cIrwRfN5SsuA%25252BE9nGhXtbQt%25252BHoaa8Fw9yMTuuuks3%25252F8ZRh0IyGOaLWhQssgtB3vEoEEQPSc4ZZcUARXm0b3GBfEW5E3QGjTvi6tRPsVpmnfSQ%25253D%26clientName%3DCool%2520Client%26clientVersion%3D3%26f%3Dxml%26k%3Dthekey%26ts%3D1203799990";

$digest = "WrxLjKmMfXpM3beElxc5HpARu/yuoMX4pvhVW2T6B+w=";

$url = "http://api.oscar.aol.com/aim/startOSCARSession?a=%252FwEAAAAAm3uC7kLggQUTUxDaptz5ddrYlsBinH5jBpi3aKVFOwRZUdy4VC3HBXkdtUaFOTM8E9og492eGQi3X0cIrwRfN5SsuA%252BE9nGhXtbQt%252BHoaa8Fw9yMTuuuks3%252F8ZRh0IyGOaLWhQssgtB3vEoEEQPSc4ZZcUARXm0b3GBfEW5E3QGjTvi6tRPsVpmnfSQ%253D&clientName;=Cool%20Client&clientVersion;=3&f;=xml&k;=thekey&ts;=1203799990&sig;_sha256=WrxLjKmMfXpM3beElxc5HpARu/yuoMX4pvhVW2T6B+w=";

Assuming no errors, a reply like the following should be received: 

<response xmlns="http://developer.nina.bz/xsd/aim.xsd">
  <statusCode>200</statusCode>
  <statusText>Ok</statusText>
  <data>
    <host>192.168.1.1</host>
    <port>9343</port>   <cookie>yoOR9mTV9hGH2vHNXtDytoHTu4q/yYpzkQzrs9L0GKg9ePe29nfS6J0+mIJD0ibMndzjde1AsumqQ6q+1pW95IyNHIhLxDm0PKF+aV8Mg05WZ7guQwiaNGPGXOq5qHI4kIyuVFU1kb9suwStkn+awsySalirJvTJbnbws2RqEV7MsBNF99MUJl+PEHuvEtqAAPuq0HvUGiFqPLC25D+cTYFmLMRwoQPtqIaHHAlaxo+kSWDTAKLzXGZ1JS/6Jd1p2HqPaBjCXuawVFpbwJT+DepJojJHGA4YMGh+YxM8dIfG8IH28w3/cqMZB/RDKaqZX+p0/AH4eqg34+BtYrfq/g==</cookie>
  </data>
</response>

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.

BE SURE to decode (base64) the cookie value before sending it in the next step.

Next steps:

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.

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:

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
Retrieved from "https://wiki.nina.chat/index.php?title=Protocols/OSCAR/Sign_On&oldid=2039"