Project

General

Profile

VoLTE IMS Android Carrier Privileges » History » Version 4

herlesupreeth, 05/14/2020 05:18 PM
Updated README as per CoIMS app v 0.9

1 1 herlesupreeth
h1. VoLTE IMS Android Carrier Privileges / CoIMS (Carrier Config overriding IMS settings)
2 1 herlesupreeth
3 3 laforge
In general, 3GPP specifications do not require any specific SIM card in order to use VoLTE or IMS.
4 3 laforge
5 3 laforge
However, unfortunately handset manufacturers don't seem to care much about 3GPP specifications and introduce all kinds of strange mechanisms in order to restrict the use of VoLTE/IMS to certain operators - whether by using explicit white-lists, or by coming up with mechanisms like Android Carrier Privileges to disallow the user from configuring IMS credentials on his phone.
6 3 laforge
7 3 laforge
This is a guide for overriding IMS settings to force enable VoLTE/VoWiFi using "Android Carrier Privileges":https://source.android.com/devices/tech/config/uicc
8 2 laforge
9 2 laforge
h2. Overview
10 2 laforge
11 2 laforge
* Android provides some APIs only to Android Apps by the operator
12 2 laforge
* Android identifies such Apps via the signing key with which they were signed
13 2 laforge
* The signing key (well, a hash of it) is stored on the SIM card
14 2 laforge
* This storage is not done as a simple file on the SIM filesystem, but in some special additional card application on the SIM-Card, a so-called ARA-M
15 2 laforge
** There is an Open Source implementation of this applet by Bertrand Martel at https://github.com/bertrandmartel/aram-applet
16 2 laforge
17 2 laforge
This document describes how to put everything together
18 1 herlesupreeth
19 1 herlesupreeth
(this guide by Supreeth Herle was first published at https://github.com/herlesupreeth/CoIMS_Wiki and is reproduce here with permission)
20 1 herlesupreeth
21 1 herlesupreeth
h2. Requirements
22 1 herlesupreeth
23 1 herlesupreeth
* A programmable version of USIM/ISIM with KIC1, KID1 and KIK1, or a non-programmable USIM/ISIM with ARA-M application but with option to push certficates to ARA-M via OTA
24 1 herlesupreeth
** [[sysmoUSIM-SJS1]] is a known-working, publicly available option
25 1 herlesupreeth
* VoLTE/VoWiFi capable phone with Android Pie or above
26 1 herlesupreeth
* PCSC, serial card reader (SIM card programmer)
27 1 herlesupreeth
* Java v1.8
28 1 herlesupreeth
29 1 herlesupreeth
h2. My Setup
30 1 herlesupreeth
31 1 herlesupreeth
* [[sysmoUSIM-SJS1]]-4ff USIM with ADM keys
32 1 herlesupreeth
* OnePlus 5t UE with Android Pie
33 1 herlesupreeth
* Gemalto SIM programmer
34 1 herlesupreeth
35 1 herlesupreeth
h2. Big shout out and credits to following people for their awesome work
36 1 herlesupreeth
37 1 herlesupreeth
"Martin Paljak":https://github.com/martinpaljak for GlobalPlatformPro (gp.jar) - A tool to load and manage applets on compatible JavaCards from command line
38 1 herlesupreeth
39 4 herlesupreeth
"Bertrand Martel":https://github.com/bertrandmartel for ARA-M applet (applet.cap) - ARA-M implementation for JavaCards. ARA-M is an application (typically present on a SIM card) which manage access rules that are enforced by an Access Control Enforcer (typically present on Android device). The enforcer makes sure the rules from the ARAM are enforced. An access rule is composed of an AID, a certificate hash (SHA1/SHA256 of client application cert) and a set of rules. The Access Control enforcer will allow/deny a client application (for example an Android app) to send APDU to a Secure Element (SE) applet based on these rules
40 1 herlesupreeth
41 1 herlesupreeth
h2. Steps
42 1 herlesupreeth
43 1 herlesupreeth
h3. Step 1: Clone repository and fetch details of the SIM
44 1 herlesupreeth
45 1 herlesupreeth
In order to install and/or manage Java Card applets on your SIM card, make sure to have KIC1, KID1 and KIK1 keys. KIC1, KID1 and KIK1 could differ from one SIM card to another so make sure to have the correct keys. If you have a non-programmable USIM/ISIM with ARA-M application and have option to push certficates to ARA-M via OTA, jump to Step 4
46 1 herlesupreeth
47 1 herlesupreeth
<pre>
48 1 herlesupreeth
$ git clone https://github.com/herlesupreeth/CoIMS_Wiki
49 1 herlesupreeth
$ cd CoIMS_Wiki
50 1 herlesupreeth
$ alias gp="java -jar $PWD/gp.jar"
51 1 herlesupreeth
</pre>
52 1 herlesupreeth
53 1 herlesupreeth
Example: In [[sysmoUSIM-SJS1]]-4ff USIM cards, the key mappings for GlobalPlatformPro are as follows
54 1 herlesupreeth
|_.sysmoUSIM key |_.GlobalPlatformPro argument |
55 1 herlesupreeth
|KIC1|--key-enc|
56 1 herlesupreeth
|KID1|--key-mac|
57 1 herlesupreeth
|KIK1|--key-dek|
58 1 herlesupreeth
59 1 herlesupreeth
Fetch details of the SIM by replacing KIC1, KID1 and KIK1 with correct keys respective to your SIM card. Execution of below command should not result in any error. If there is an error, please check the error and double check everything before proceeding
60 1 herlesupreeth
<pre>
61 4 herlesupreeth
$ gp --key-enc <KIC1> --key-mac <KID1> --key-dek <KIK1> -lvi
62 1 herlesupreeth
</pre>
63 1 herlesupreeth
64 1 herlesupreeth
h3. Step 2: Unlock the SIM card for easier installation of applet as follows (Optional)
65 1 herlesupreeth
66 1 herlesupreeth
*Proceed with caution when unlocking SIM card as it could brick your USIM/ISIM if incorrect KIC1, KID1 and KIK1 keys are used*
67 1 herlesupreeth
<pre>
68 4 herlesupreeth
$ gp --key-enc <KIC1> --key-mac <KID1> --key-dek <KIK1> --unlock
69 1 herlesupreeth
</pre>
70 1 herlesupreeth
71 1 herlesupreeth
Example: A sysmoUSIM-SJS1-4ff USIM card with following keys is unlocked as follows
72 1 herlesupreeth
73 1 herlesupreeth
KIC1 = --key-enc = 975B496CED1F2FB984145A55AB31A585
74 1 herlesupreeth
75 1 herlesupreeth
KID1 = --key-mac = E7207B567F9D08726A6EFBD90C50DA9A
76 1 herlesupreeth
77 1 herlesupreeth
KIK1 = --key-dek = DEAA4E9A9B3BC6FC5EFF77A8E9925632
78 1 herlesupreeth
79 1 herlesupreeth
<pre>
80 1 herlesupreeth
$ gp --key-enc 975B496CED1F2FB984145A55AB31A585 --key-mac E7207B567F9D08726A6EFBD90C50DA9A --key-dek DEAA4E9A9B3BC6FC5EFF77A8E9925632 --unlock
81 1 herlesupreeth
Default type=DES3 bytes=404142434445464748494A4B4C4D4E4F kcv=8BAF47 set as master key for A000000003000000
82 1 herlesupreeth
</pre>
83 1 herlesupreeth
84 1 herlesupreeth
h3. Step 3: Install ARA-M Java Card applets on USIM/ISIM
85 1 herlesupreeth
86 1 herlesupreeth
*Proceed with caution when installing applets on SIM card as it could brick your USIM/ISIM if incorrect KIC1, KID1 and KIK1 keys are used*
87 1 herlesupreeth
88 1 herlesupreeth
Install the ARA-M applet (applet.cap). The following command must execute without any errors.
89 1 herlesupreeth
90 1 herlesupreeth
<pre>
91 1 herlesupreeth
# If SIM is not unlocked in Step 2
92 4 herlesupreeth
$ gp --key-enc <KIC1> --key-mac <KID1> --key-dek <KIK1> --install applet.cap
93 1 herlesupreeth
# If SIM is unlocked in Step 2
94 1 herlesupreeth
$ gp --install applet.cap
95 1 herlesupreeth
</pre>
96 1 herlesupreeth
97 1 herlesupreeth
h3. Step 4: Push the SHA-1 certifcate of the Carrier Config Android app onto ARA-M in USIM/ISIM
98 1 herlesupreeth
99 1 herlesupreeth
The Carrier Config Android app which will be installed in Step 5 is signed with following SHA1 key
100 1 herlesupreeth
101 1 herlesupreeth
SHA1: E4:68:72:F2:8B:35:0B:7E:1F:14:0D:E5:35:C2:A8:D5:80:4F:0B:E3
102 1 herlesupreeth
103 1 herlesupreeth
In order to provide Carrier Privileges to Carrier Config app, push the above SHA1 certifcate as follows
104 1 herlesupreeth
105 1 herlesupreeth
<pre>
106 1 herlesupreeth
# If SIM is not unlocked in Step 2
107 4 herlesupreeth
$ gp --key-enc <KIC1> --key-mac <KID1> --key-dek <KIK1> -a 00A4040009A00000015141434C0000 -a 80E2900033F031E22FE11E4F06FFFFFFFFFFFFC114E46872F28B350B7E1F140DE535C2A8D5804F0BE3E30DD00101DB080000000000000001
108 1 herlesupreeth
# If SIM is unlocked in Step 2
109 1 herlesupreeth
$ gp -a 00A4040009A00000015141434C0000 -a 80E2900033F031E22FE11E4F06FFFFFFFFFFFFC114E46872F28B350B7E1F140DE535C2A8D5804F0BE3E30DD00101DB080000000000000001
110 1 herlesupreeth
</pre>
111 1 herlesupreeth
112 1 herlesupreeth
The split-up of above APDU sent to SIM card is as follows
113 1 herlesupreeth
114 1 herlesupreeth
<pre>
115 1 herlesupreeth
#### REF-AR-DO for UICC Carrier Privileges
116 1 herlesupreeth
117 1 herlesupreeth
|REF-AR-DO|T|E2    | |                  | |                                        |
118 1 herlesupreeth
|         |L|2F    | |                  | |                                        |
119 1 herlesupreeth
|         |V|REF-DO|T|E1                | |                                        |
120 1 herlesupreeth
|         | |      |L|1E                | |                                        |
121 1 herlesupreeth
|         | |      |V|AID-REF-DO        |T|4F                                      |
122 1 herlesupreeth
|         | |      | |                  |L|06                                      |
123 1 herlesupreeth
|         | |      | |                  |V|FFFFFFFFFFFF                            |
124 1 herlesupreeth
|         | |      | |DeviceAppID-REF-DO|T|C1                                      |
125 1 herlesupreeth
|         | |      | |                  |L|14                                      |
126 1 herlesupreeth
|         | |      | |                  |V|E46872F28B350B7E1F140DE535C2A8D5804F0BE3|
127 1 herlesupreeth
|         | |AR-DO |T|E3                | |                                        |
128 1 herlesupreeth
|         | |      |L|0D                | |                                        |
129 1 herlesupreeth
|         | |      |V|APDU-AR-DO        |T|D0                                      |
130 1 herlesupreeth
|         | |      | |                  |L|01                                      |
131 1 herlesupreeth
|         | |      | |                  |V|01 (Always)                             |
132 1 herlesupreeth
|         | |      | |PERM-AR-DO        |T|DB                                      |
133 1 herlesupreeth
|         | |      | |                  |L|08                                      |
134 1 herlesupreeth
|         | |      | |                  |V|0000000000000001                        |
135 1 herlesupreeth
</pre>
136 1 herlesupreeth
137 1 herlesupreeth
To check the list of installed certificates use the following command
138 1 herlesupreeth
139 1 herlesupreeth
<pre>
140 1 herlesupreeth
# If SIM is not unlocked in Step 2
141 1 herlesupreeth
$ gp --key-enc KIC1 --key-mac KID1 --key-dek KIK1 -acr-list
142 1 herlesupreeth
RULE #0 :
143 1 herlesupreeth
       AID  : FFFFFFFFFFFF
144 1 herlesupreeth
       HASH : E46872F28B350B7E1F140DE535C2A8D5804F0BE3
145 1 herlesupreeth
       APDU rule   : ALWAYS(0x01)
146 1 herlesupreeth
# If SIM is unlocked in Step 2
147 1 herlesupreeth
$ gp -acr-list
148 1 herlesupreeth
RULE #0 :
149 1 herlesupreeth
       AID  : FFFFFFFFFFFF
150 1 herlesupreeth
       HASH : E46872F28B350B7E1F140DE535C2A8D5804F0BE3
151 1 herlesupreeth
       APDU rule   : ALWAYS(0x01)
152 1 herlesupreeth
</pre>
153 1 herlesupreeth
154 1 herlesupreeth
_If you have a non-programmable USIM/ISIM with ARA-M application and have option to push certficates to ARA-M via OTA, push the above SHA1 certificate on to the SIM_
155 1 herlesupreeth
156 1 herlesupreeth
h3. Step 5: Install the Carrier Config Android app from Play Store
157 1 herlesupreeth
158 1 herlesupreeth
Make sure the SIM card is placed in the default/first SIM slot of the device (only for multi-sim capable devices)
159 1 herlesupreeth
160 1 herlesupreeth
Download the "CoIMS":https://play.google.com/store/apps/details?id=com.sherle.coims Carrier Config app from play store. Then, run the app
161 1 herlesupreeth
162 1 herlesupreeth
Important points/values to note after running the app for this app to enable VoLTE
163 1 herlesupreeth
164 1 herlesupreeth
* "App has Carrier Privileges" must be true
165 4 herlesupreeth
* "SIM Carrier Id" must not be -1 (i.e Unknown Carrier)- Not shown in Android 8.0 and 8.1 devices
166 1 herlesupreeth
* "carrier_volte_provisioned_bool" must be true
167 1 herlesupreeth
168 4 herlesupreeth
h3. Step 6: Additional IMS settings only for Samsung and Mediatek chipset devices
169 4 herlesupreeth
170 4 herlesupreeth
After installation of the app, access the options menu on the right hand top corner and select Samsung/Mediatek IMS Settings option based on your device chipset and edit the IMS settings accordingly to enable desired IMS features
171 4 herlesupreeth
172 1 herlesupreeth
h2. Debugging
173 1 herlesupreeth
174 1 herlesupreeth
Use adb debugging with filter for "ims" keyword
175 1 herlesupreeth
176 1 herlesupreeth
h3. Potential reasons for this method not working
177 1 herlesupreeth
178 4 herlesupreeth
# If the value of CarrierIdentifier indicated in the app is -1 (i.e Unknown Carrier) - Not shown in Android 8.0 and 8.1 devices
179 1 herlesupreeth
#* If PLMN is on the following list (https://android.googlesource.com/platform/packages/providers/TelephonyProvider/+/master/assets/carrier_list.textpb) Resolution: Wait for vendor to release an update and hopefully it contains the updated carrier list
180 1 herlesupreeth
#*If PLMN is not on the following list (https://android.googlesource.com/platform/packages/providers/TelephonyProvider/+/master/assets/carrier_list.textpb) Resolution: Refer the following link (https://source.android.com/devices/tech/config/carrierid#integrating_carrier_ids_with_carrierconfig)
181 1 herlesupreeth
# If the SIM is placed in non-default SIM slot in a multi-SIM phones i.e. SIM in slot 1 (SIM slot 0 (default), SIM slot 1) of device
Add picture from clipboard (Maximum size: 48.8 MB)