mozilla-services/msisdn-gateway — pull request #33 by Natim (2014-05-16 11:57:37+00:00)
Title: Alternative proposal for supporting SMS-MT and SMS-MO-MT

IMO, there could be better separation of concerns and decoupling of the concerns in this API.

After discussing with @warner, I've come to think about this problem as two separate concerns:

1) verification of a MSISDN a device claims to have, and
2) the discovery of your MSISDN via SMS-MO-MT (if the device doesn't already know it)

I propose we design two separate APIs for each of these two concerns, and then if the device knows your MSISDN it does 1), and if it doesn't, it does 2) and then 1).

I believe this will yield a solution whose security properties are easier to reason about and is more decoupled. For example, the API for 2) can be untrusted, and be run by anyone. As it stands now, the server side SMS sending/receiving service has unfortunate coupling with the MSISDN verification component. IIUC, the service that receives the MO SMS from the client sends out the verification code in a MT SMS, which is later verified by the HTTP endpoint.

Here's a rough sketch of what I had in mind:

**MSISDN verification API via SMS-MT**

`POST /msisdn/register` (msisdn, mcc, mnc, nonce, roaming) -> (sessionToken, mtNumber) + server triggers SMS (code, nonce) to msisdn number from mtNumber
`POST /msisdn/unregister` (sessionToken) -> ()
`POST /msisdn/verify_code` (sessionToken, code, cert) -> (signedCert)
`POST /msisdn/resend_code` (sessionToken) -> ()

**SMS endpoint discovery API**

`POST /sms/discover` (mcc, mnc, roaming) -> (moNumber, mtNumber)

**MSISDN discovery API**

(phone -> provider) send SMS-MO to moNumber from msisdn (nonce)
(provider -> phone) send SMS-MT to msisdn from mtNumber (nonce, msisdn)

One could optionally factor the mtNumber discovery out of `/msisdn/register` and just use `/sms/discover`. That's just an optimization unless the mtNumber might be different for each of those flows.

------------------------------------------------

Reframing the flows from https://etherpad.mozilla.org/flow-msisdn:

**SMS Mobile Terminated**

=> POST /msisdn/register msisdn, nonce, roaming
<= session token, mtNumber
<= SMS to msisdn from mtNumber with code, nonce
=> POST /msisdn/verify_code sessionToken, code
<= OK (certificate)

**SMS Mobile Originated**

=> POST /sms/discover (mcc, mnc, roaming)
<= moNumber, mtNumber

=> SMS to moNumber from msisdn with nonce1
<= SMS to msisdn from mtNumber with nonce1, msisdn

(now, just do the SMS Mobile Terminated flow)
=> POST /msisdn/register msisdn, nonce2, roaming
<= session token, mtNumber
<= SMS to msisdn from mtNumber with code, nonce2
=> POST /msisdn/verify_code sessionToken, code, public key
<= OK (certificate)