msnp-wiki/docs/commands/usr.md

# Introduction
`USR` is a command introduced with [MSNP2](../versions/msnp2.md).

The command exists in all services, without a request or response payload.

Specifies a user that wants to authenticate to the service.
For the command that is used when sending this to a Dispatch Server, read [XFR](xfr.md).

This command can only be sent once. Any further uses of this command in the same session is Undefined Behavour.

# Client/Request

## Dispatch Server or Notification Server

### The Initial request
`USR TrID security-package I user-handle`

Depending on the version of the protocol you are using, `security-package` can be:
* `CTP`: Clear Text Password. Only in [MSNP2](../versions/msnp2.md).
* `MD5`: MD5-based authentication. Only in [MSNP2](../versions/msnp2.md) to [MSNP7](../versions/msnp7.md).
* `TWN`: "Tweener", Passport 1.4 or compatible authentication service. Since [MSNP8](../versions/msnp8.md).
* `SSO`: Single Sign On, usually a more advanced Passport 3.0 authentication method. Since [MSNP15](../versions/msnp15.md).

### The Subsequent request
`USR TrID security-package S {...response-args}`

Where `response-args` can be anything, but based on `security-package` it can be:
* `CTP`: Your password in plain text.
* `MD5`: The server's login challenge concatenated with your password.
* `TWN`: The `from-PP` parameter in the `Authentication-Info` header sent in response to Passport 1.4,
  or if using Passport 3.0, the `<wsse:BinarySecurityToken>` of the relevant `<wst:RequestSecurityTokenResponse>`.
* `SSO`: The same as Passport 3.0 in `TWN`, but with the extra parameter
  being the custom challenge response encoded as base64.

## Switchboard Server
`USR TrID user-handle cookie`

Where `user-handle` is your current user handle.

Where `cookie` is the relevant parameter given from [XFR](xfr.md) or [RNG](rng.md).

# Server/Response

## Dispatch Server or Notification Server

### Requesting a Subsequent action
`USR TrID OK security-package S {...challenge}`

Where `challenge`, based on the `security-package` is:
* `CTP`: Nothing. This parameter is omitted.
* `MD5`: The login challenge to concatenate with your password.
* `TWN`: The Passport login parameters.
* `SSO`: The Passport login policy and a base64-encoded key.

### Successfully authenticated
`USR TrID OK user-handle {friendly-name} {verified} {unknown}`

Where `OK` is always `OK`.

Where `user-handle` is your user handle.

Where `friendly-name` is your current Friendly Name. Removed in [MSNP10](../versions/msnp10.md).

Where `verified` is the account's verification status,
where 0 is unverified, and 1 is verified. Added since [MSNP6](../versions/msnp6.md).

Where `unknown` is an unknown value,
where 0 is something, and 1 is something else. Added since [MSNP8](../versions/msnp8.md).

## Switchboard Server
`USR TrID OK user-handle friendly-name`

Where `user-handle` is your current user handle.

Where `friendly-name` is your current friendly name.

# Examples

## Notification Server

### Using CTP
*Only in [MSNP2](../versions/msnp2.md).*
```
C: USR 1 CTP I example@hotmail.com
S: USR 1 CTP S
C: USR 2 CTP S password
S: USR 2 OK example@hotmail.com example%20user
```

### Using MD5
*Only in [MSNP2](../versions/msnp2.md) to [MSNP7](../versions/msnp7.md).*
```
C: USR 3 MD5 I example@hotmail.com
S: USR 3 MD5 S 1234567890.123456789
C: USR 4 MD5 S f59af8f2fa91d38aff7c870c17f99903
S: USR 4 OK example@hotmail.com example%20user
```

### Using TWN
*Since [MSNP8](../versions/msnp8.md).*
```
C: USR 5 TWN I example@hotmail.com
S: USR 5 MD5 S passport=parameters,neat=huh,lc=1033,id=507
```
*The HTTPS interlude has been moved to the [Passport 1.4](../services/passport14.md) article.*
```
USR 6 TWN S t=token&p=profile
USR 6 OK example@hotmail.com example%20user
```

### Using SSO
*Since [MSNP15](../versions/msnp15.md).*

*NOTE: This has been line-breaked.
Lines beginning with `..` followed by a space are continuations of the previous line.*
```
C: USR 7 SSO I example@hotmail.com
S: USR 7 SSO S MBI_KEY_OLD AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=
```

*The HTTPS and key-encryption interlude has been removed from here
and is to reinstated as two seperate pages.*

```
C: USR 8 SSO S t=ticket HAAAAAEAAAADZgAABIAAAAgAAAAUAAAASAAAAAAAAA
.. AAAAAA7XgT5ohvaZdoXdrWUUcMF2G8OK2JohyYcK5l5M
.. JSitab33scxJeK/RQXcUr0L+R2ZA9CEAzn0izmUzSMp
.. 2LZdxSbHtnuxCmptgtoScHp9E26HjQVkA9YJxgK/HM=
S: USR 8 OK example@hotmail.com
```

### Invalid username or password
```
C: USR 9 TWN I example@hotmail.com
S: USR 9 TWN S passport=parameters,neat=huh,lc=1033,id=507
C: USR 10 TWN S t=not*a*passport*ticket&p=not*a*profile*either
S: 911 10
```

Server disconnects client.

### Account not verfiied
*This will show the "Account Verification Required" dialog in [MSNP6](../versions/msnp6.md) clients?*
```
C: USR 11 MD5 I example@hotmail.com
S: USR 11 MD5 S 1234567890.123456789
C: USR 12 MD5 S f59af8f2fa91d38aff7c870c17f99903
S: 924 12
```

### Wrong server for this account
```
C: USR 13 TWN I example@hotmail.com
S: 931 13
```

## Switchboard Server
```
C: USR 14 example@passport.com 1234567890.1234567890.1234567890
S: USR 14 OK example@passport.com example%20user
```

# Known changes
* [MSNP3](../versions/msnp3.md): Removed the `CTP` security package.
* [MSNP6](../versions/msnp6.md): Added account verification bit to [USR OK](#successfully-authenticated).
* [MSNP8](../versions/msnp8.md): Added an unknown bit to [USR OK](#successfully-authenticated) and
  removed the `MD5` security package, and replaced with the `TWN` security package.
* [MSNP15](../versions/msnp15.md): Added support for the `SSO` security package.