840915 - [Settings] FDN Support in Gaia

Status: VERIFIED FIXED

(Firefox OS Graveyard :: Gaia::Settings, defect)

Description

[David Scravaglieri [:scravag]]

As a user I can enable / disable FDN in settings.

When I enable / disable FDN, PIN2 is asked.

Comment 1

[Etienne Segonzac (:etienne)]

So... to start we're going to need a more detailed user story :)

Comment 2

[David Scravaglieri [:scravag]]

Proposal:

In Settings, tap "SIM Security" item shows a list with "SIM PIN on/off", "Change PIN2", "Enable FDN".

- "SIM PIN on/off" shows the regular panel for PIN code
- "Change PIN2" shows a panel that let the user enter the old PIN2 and the new PIN2 + validate
- "Enable FDN" shows a panel with on/off and "FDN list"
   a) on/off ask for PIN2 code
      a.1) If wrong PIN2 code is entered 3 times, ask for PUK2
   b) FDN list -> Add from Contacts (one or many)
   c) FDN list -> Add a new number (not in Contacts)
      c.1) opens a panel with "First Name", "Last Name", "Phone Number"
   d) FDN list -> Modify an entry
      d.1) opens a panel with "First Name", "Last Name", "Phone Number" field, filled with the old values
   e) FDN list -> Delete an entry from the list
   f) FDN list -> Delete all entries from the list

Comment 3

[David Scravaglieri [:scravag]]

PIN2 must be asked each time FDN list panel is opened. So the requirements are modified as follow

In Settings, tap "SIM Security" item shows a list with "SIM PIN on/off",
"Change PIN2", "FDN".

- "SIM PIN on/off" shows the regular panel for PIN code
- "Change PIN2" shows a panel that let the user enter the old PIN2 and the
new PIN2 + validate
- "FDN" asks for PIN2 then shows a panel with on/off and a "FDN list"
    a) If wrong PIN2 code is entered 3 times, ask for PUK2
    b) on/off enables or disables FDN
    c) FDN list -> Add from Contacts (one or many)
    d) FDN list -> Add a new number (not in Contacts)
       c.1) opens a panel with "First Name", "Last Name", "Phone Number"
    e) FDN list -> Modify an entry
       d.1) opens a panel with "First Name", "Last Name", "Phone Number"
 field, filled with the old values
    f) FDN list -> Delete an entry from the list (with confirmation)
    g) FDN list -> Delete all entries from the list (with confirmation)

Comment 4

[Dietrich Ayala (:dietrich)]

Confirmed not required for 1.0.1 (shira) release by carrier. Marking blocking-b2g:-.

Comment 5

[Dietrich Ayala (:dietrich)]

Partner requirement for 1.1, requesting blocking for leo.

Comment 6

[Joe Cheng [:jcheng] (please needinfo)]

this should be part of v1.1.0 delivery and requires UX input

Comment 7

[Dietrich Ayala (:dietrich)]

Blocking- until Product team determines if this is actually required by carrier for 1.1. If so, it's a non-trivial number of stories, so should be processed like the rest of 1.1 features have been.

Comment 8

[Kev Needham [:kev]]

There's two user stories:

As a user, I can enable and/or disable my SIM-based Fixed Dialing Numbers (FDN) mode by entering the PIN2 password on my phone to ensure that I have control over when calls can only be made to the numbers I add to the FDN list.

As a user, I can add, modify, and delete entries in the Fixed Dialing Numbers (FDN) list on my SIM card to manage which numbers my phone can connect voice calls and SMS messages to when FDN is enabled.

Comment 9

[Peter Dolanjski [:pdol]]

Casey, can you look at creating UX for this?

Comment 10

[Casey Yee]

Sure we'll get this lined up.   I'll need some use cases around how users use FDN.  I will ping Kev about this and discuss.

Comment 11

[Casey Yee]

Waiting on confirmation on which milestone this work will be slated for before we begin resourcing UX around this requirement.

Comment 12

[Dylan Oliver [:doliver]]

Kev, did you get a chance to talk with 1.1 partners to see if we can push this out to 1.2?

Comment 13

[Anshul]

Any update if this is a 1.1 requirement?

Comment 14

[Kev Needham [:kev]]

I'm still waiting on final go/nogo. I have spoken with partner, but don't have a final answer/approval that it's not a requirement for 1.1. Had hoped to have it today, but will likely be tomorrow given the time of day now.

Comment 15

[Dietrich Ayala (:dietrich)]

Per Kev's communication w/ launch partner today, no longer a hard requirement for 1.1. Removing nomination.

Comment 16

[Kev Needham [:kev]]

Agreed. Note that this is a hard blocker for 1.next (1.2).

Comment 17

[Gabriele Svelto [:gsvelto] (PTO)]

Since FDN contacts are set using the same API as ADN contacts this might depend on bug 850098.

Comment 18

[Joe Cheng [:jcheng] (please needinfo)]

listed as must have in v1.2 for COMM team. koi+

Comment 19

[Al Tsai [:atsai]]

MozTrap #9026, #9027, #9028, #9035, #9036, #9038, #9039, #9040, #9041, #9042

Comment 20

[Yoshi Cheng-Hao Huang [:allstars.chh][:allstarschh][:yoshi]]

(In reply to David Scravaglieri [:scravag] from comment #2)
>    a) on/off ask for PIN2 code
>       a.1) If wrong PIN2 code is entered 3 times, ask for PUK2
>    b) FDN list -> Add from Contacts (one or many)
>    c) FDN list -> Add a new number (not in Contacts)
>       c.1) opens a panel with "First Name", "Last Name", "Phone Number"
>    d) FDN list -> Modify an entry
>       d.1) opens a panel with "First Name", "Last Name", "Phone Number"
> field, filled with the old values
>    e) FDN list -> Delete an entry from the list
>    f) FDN list -> Delete all entries from the list

The point (a) might be some problems here,
For the modems on Android, they expect when doing updating FDN contact or enabling FDN feature, the platform side would pass 'pin2' passcode as well.
That means "every time" we edit a FDN contact, we need to supply pin2 as well.(PIN2 needs to be prompted every time, not just for the 1st time)

In the sequence mentioned in Comment 2, it implies 
a) we unlock PIN2
b) we could update FDN contacts as many as possible

which might not work on Android.
As the modem would expect when updating 1st FDN entry, platform would supply pin2, not doing unlock pin2 before updating FDN entry.

As you can see ril.h from hardware/ril/include/telephony,
it says 

/**
 * RIL_REQUEST_ENTER_SIM_PIN2
 *
 * Supplies SIM PIN2. Only called following operation where SIM_PIN2 was
 * returned as a a failure from a previous operation.


But if you interpret comment 2 as

a): User types pin2, but instead calling mozIccManager.unlockCardLock, the Gaia app 'keeps' the pin2 in its data structure

b): When updating FDN entry, Gaia app would supply the pin2 in the parameter of mozIccManager.updateContact("fdn", pin2);

I think that's okay.

Thanks

Comment 21

[Yoshi Cheng-Hao Huang [:allstars.chh][:allstarschh][:yoshi]]

(In reply to David Scravaglieri [:scravag] from comment #3)
>     c) FDN list -> Add from Contacts (one or many)
>     d) FDN list -> Add a new number (not in Contacts)
>        c.1) opens a panel with "First Name", "Last Name", "Phone Number"
>     e) FDN list -> Modify an entry
>        d.1) opens a panel with "First Name", "Last Name", "Phone Number"
>  field, filled with the old values

Also for SIM contact, there's only 1 name field, 
so only the name written to nsIContactProperties.name would be saved.

Also the length of name has some limitation.(But it depends on the SIM card). So if you try to merge first name and last name into one name, it's highly possibly be truncated. 


Thanks

Comment 22

[Joe Cheng [:jcheng] (please needinfo)]

this bug can probably be public. any reason this is not?

Comment 23

[Joe Cheng [:jcheng] (please needinfo)]

Kaze, do you mind providing an update in the bug? thanks

Comment 24

[Fabien Cazenave [:kaze]]

Attachment: link to pull request

https://github.com/mozilla-b2g/gaia/pull/11878

Comment 25

[Fabien Cazenave [:kaze]]

Attachment: UX specs

Here are the specs I’ve used. The proposed implementation is slightly different in order to be more consistent with the current SIM PIN dialogs.

Comment 26

[Arthur Chen [:arthurcc][inactive after 6/30]]

Comment on attachment 802170 [details]
link to pull request

Thank you for the effort! r=me with the comment addressed.

Comment 27

[Fabien Cazenave [:kaze]]

Comment on attachment 802170 [details]
link to pull request

Étienne, would you review the dialer part please?

Comment 28

[Etienne Segonzac (:etienne)]

Comment on attachment 802170 [details]
link to pull request

Thanks for the test, r=me on the dialer part

Comment 29

[Fabien Cazenave [:kaze]]

Merged on master: https://github.com/mozilla-b2g/gaia/commit/2d870100a945272824f8e42a8c52aac095fe907e

Comment 30

[Carol Yang [:cyang]]

Hi Kaze, just a little curious, for PIN, it seems like whether it's enable/disable of lock or changing of pin, lockType is 'pin'. I'm wondering why for PIN2, enable/disable of lock has lockType 'fdn' but changing of pin2 has lockType 'pin2'. It seems like the lockType should both be 'pin2', no?

Comment 31

[Fabien Cazenave [:kaze]]

Hi Carol! Yes, it’s confusing and I don’t really know why it’s like that: all I know is that it’s what the backend requires.

Short story: `fdn' vs. `pin2' is confusing but it works, and maybe we could make it more consistent by changing the Gecko part (= dom/system/gonk/ril_worker.js + possibly a bit more code).

Now for the long story, `IccHelper.setCardLock(options)' is used to enable/disable/change the PIN2 code, and the `options' parameter is very specific to each action:
 - to enable/disable PIN lock: { lockType: 'pin',  pin:  pin, enabled: true/false }
 - to change the PIN code:     { lockType: 'pin',  pin:  pin, newPin: newPin }
 - to enable/disable FDN:      { lockType: 'fdn',  pin2: pin, enabled: true/false }
 - to change the PIN2 code:    { lockType: 'pin2', pin:  pin, newPin: newPin }

Overall, I agree it would be more consistent to enable/disable FDN with this:
                               { lockType: 'pin2', pin:  pin, enabled: true/false }

… which would require to modify the `iccSetCardLock' function in Gecko (dom/system/gonk/ril_worker.js). But maybe there’s a good reason for the code to be like that in Gecko?

For an even longer story (and to add more confusion to that), this lockType variable is also used by `IccHelper.getCardLockRetryCount(lockType, callback)', which returns the number of remaining tries for each action. And for this method, we always use `pin2' as lockType for enabling/disabling FDN and changing the PIN2 code.

Unfortunately this only works with the commercial RIL and it relies on non-standard stuff, so it hasn’t been much tested so far. In other words, I’m not completely sure whether we should use `pin2' or `fdn' here: if the number of remaining tries isn’t displayed when *first* trying to enter the PIN2 code, then I should have used `fdn' (and a follow-up bug would be required).

I hope the long stories make some sense. Yoshi, maybe you can make it clearer?

Comment 32

[Yoshi Cheng-Hao Huang [:allstars.chh][:allstarschh][:yoshi]]

(In reply to Carol Yang [:cyang] from comment #30)
Hi, Carol

> Hi Kaze, just a little curious, for PIN, it seems like whether it's
> enable/disable of lock or changing of pin, lockType is 'pin'. I'm wondering
> why for PIN2, enable/disable of lock has lockType 'fdn' 

There's no such thing as enable/disable PIN2.
As you can also see from cardState, there's no card state for 'pin2Required'.
PIN2 will always be checked when updating some data, i.e. FD.

Comment 33

[Yoshi Cheng-Hao Huang [:allstars.chh][:allstarschh][:yoshi]]

(In reply to Fabien Cazenave [:kaze] from comment #31)
Hi, Kaze
Thanks for the detail answer. :)

Mostly are correct,
but I got some different comments inline.
 
> Now for the long story, `IccHelper.setCardLock(options)' is used to
> enable/disable/change the PIN2 code, 

As I explained above, there's no such thing as 'enable/disable PIN2'/

> 
> Overall, I agree it would be more consistent to enable/disable FDN with this:
>                                { lockType: 'pin2', pin:  pin, enabled:
> true/false }
> 

No, PIN2 is used to protect some data in the SIM card, like FD(Fixed Dialling), and some phonebook storage(not used in FirefoxOS/Android).

Also notice that each time when you update a FDN contact, pin2 will be needed, even you have provide pin2 in the last session.

As your previous comment, you can find that you mentioned
'pin lock', 'pin code',

In the FD (lockType:'fdn') case, we're trying to provide pin2 code to unlock FD lock, not unlocking PIN2 lock.

PIN2 is different from PIN(1), as you can see in cardState, there is pinRequired, but no pin2Required.

> 
> For an even longer story (and to add more confusion to that), this lockType
> variable is also used by `IccHelper.getCardLockRetryCount(lockType,
> callback)', which returns the number of remaining tries for each action. And
> for this method, we always use `pin2' as lockType for enabling/disabling FDN
> and changing the PIN2 code.
> 
Do the comment above can resolve your question?

In 3GPP, there are different actions will require PIN2.
- enable/disable FD
- Editing FDN
- some secordary phonebook management.

All of these will influence the retry count of PIn2.

Feel free to ni? or ask me if you still have questions,
I'll try to explain it from the 3GPP spec.

Comment 34

[Carol Yang [:cyang]]

Thanks Kaze & Yoshi for the explanations!

> In the FD (lockType:'fdn') case, we're trying to provide pin2 code to unlock
> FD lock, not unlocking PIN2 lock.

It just seems a little inconsistent since for lockType:'pin', PIN1 is provided to unlock SC lock, also not unlocking PIN1 technically. So seems like the same logic would be appled for PIN2/FDN.

Comment 35

[Yoshi Cheng-Hao Huang [:allstars.chh][:allstarschh][:yoshi]]

(In reply to Carol Yang [:cyang] from comment #34)
> It just seems a little inconsistent since for lockType:'pin', PIN1 is
> provided to unlock SC lock, also not unlocking PIN1 technically. 

Hi, Carol
Sorry for my late reply,
it is a Chinese National Holidays this week.

But to my understanding, SC is a facility lock to enable/disable SIM lock, it's not used to 'unblock' or 'unlock' SIM lock. And it's only used in TS 27.007.
Even in TS 102.221, it uses 'ENABLE PIN', 'DISABLE PIN', 'UNBLOCK PIN', not using 'SC' term here. 

Another thing is for the design of WebAPI. Even only some web-developers know about PIN, but most of them don't know those facility locks as we do. So the WebAPI is designed to remove those complicated terms in 3GPP spec, but meanwhile we still need to make it correct.
(I guess you may ask the same question 'What about FD and PIN2'? more on that in the discussion of PIN2 below). I agree if we're talking about TS 27.007, it's correct if we say the lock is locked by SC. But here we're talking WebAPI, we should try to make these 3GPP terms more easily to understand and use.

The same reasoning goes if you'd say,
what about if we change the lockLock to 'sc' when trying to enable/disable PIN lock.

Back to the PIN2 you asked in the first place,
because PIN2 is not quite the same as PIN1 as you know,
PIN2 is more likely 'Goes with some functionality'.
And there's no cardState as 'pin2Required', but actually there's an error called 'PIN2 Required' in ril.h, TS 27.007 and TS 102.221, and it is used to supply PIN2 if the previous action doesn't provide it.

For example, if I try to enable to FD lock but without PIN2, 
+CLCK FD  ---->
+CME Err 17 (PIN2 Required) <----
+CPIN SIM PIN2 <pin2 code>  --->
OK <---

But the 3GPP spec doesn't mention what happened if we didn't supply PIN2 when we got 'PIN2 Required' error.

So if the WebAPI were desinged to use 'lockType: pin2' for enabling/disabling FDN.
When developers first look at this API, he/she may ask when will this 'lockType: pin2' be used, since there's no cardState as 'pin2Required'.
He needs to read some documentation and know, 'aha, it's for enabling/disabling FDN(FD if you prefer using TS 27.007 term)'.

If I were a Web-Developer, one question I had in mind could be
"Why the lockType is pin2 when I try to enable FDN"?

We might answer "We need to unblock PIN2 when we enable/disable FDN."
But actually PIN2 is also used in some other features than FDN,
So this is the 1st reason I didn't use pin2 as the lockType at first.

The 2nd reason is TS 51.011, clause 9.2.11, 9.2.12
For enable/disable CHV, there is only for CHV1, not for CHV2.
So if we're going to say this API(the WebAPI) is to enable/disable PIN2,
it might not be correct per TS 51.011.

The 3rd reason is to go with updating a 'fdn' contact.
We have an API called 'updateContact' in Icc,
should we use pin2 in the parameters when updating fdn?
Or should we create another 'unlockCardLock{lockType: pin2,...}' for separating PIN2 ?

If we were to choose the latter one, unlockCardLock(lockType: pin2, ...}
That makes us back to 3GPP spec as I mentioned in the first place.
The calling seq goes like

var req = icc.updateContact('fdn', contact);
icc.onpin2 = function () { 
  icc.unlockCardLock{lockType: 'pin2', ...}; 
};

The onpin2 callback seems make things more complicated,
what's worse is what if we didn't call unlockCardLock?
And what if we call some functions with pin2 supplied?

like  
var req = icc.updateContact('fdn', contact);
icc.onpin2 = function () { 
  icc.setCardLock({lockType: 'pin2', pin2: '<pin2_code>', enabled: true/false}); 
};

Can this pin2 supplied in setCardLock can make the first call (updataContact) succeed?
3GPP spec doesn't mention when happened if we didn't provide pin2 afterwards,
and we don't want our WebAPI to be designed as 'implementation-dependent' on these cases.

Finally we decide to update updateContact('fdn', contact, pin2) to make things easier. Therefore there's also no API to unlock PIN2 as well.

Above is the background story for why 'lockType: pin2' isn't considered in enable/disable and unblock(or unlock). 

But we do have some APIs used pin2 as 'lockType', like change PIN2, and get retry count.

Again, welcome to provide your opinion here or ni? for me if you have any question.

Comment 36

[Carol Yang [:cyang]]

Hi Yoshi, thanks so much for the detailed explanation!

> But actually PIN2 is also used in some other features than FDN,

I think this was mainly my concern.. when other features that require PIN2 is needed, we would then need a new lockType rather than be able to piggy back off of 'pin2'. Anyway, this might be thinking about a problem that does not exist so maybe that can be dealt with when we cross that bridge.

Comment 37

[Al Tsai [:atsai]]

Gaia:     1e9470b9b6df630eddf1c4c8b25b3170ee786b0e
Gecko:    http://hg.mozilla.org/releases/mozilla-aurora/rev/48faa2668dd8
BuildID   20130929004004
Version   26.0a2
DuT       Buri