Linux version
Our SW is delivered as open source code
It can compile on most of Linux versions, as log as you install g++ (gnu C++ compiler)
We add a binary version, currently compiled on Ubuntu 22.04
It is always better to recompile on your machine:
rm program_uicc ; make program_uicc
APN
APN is not in the USIM, it is a parameter to set in the UE
ADM code
UICC version 4 can use any ADM code, nevertheless you have to provide one (any 8 figures value) to overwrite the telecom values.
The adm code is on each invoice for UICC before serial OC004000. If you enter 8 successive times a wrong ADM, the card update will be locked: the IMSI/Ki/… update won’t be possible anymore.
Error codes
a UICC/SIM answers by standard codes.
A list of them:
Complete list of APDU responses
OP and OPc
OPc is the result of a operation between OP (means operator key) and Ki (user key)
The OP is never used in the telecom protocol.
So, if you specify a OP in the file hss.conf and in our option ‘–xx’, they should compute the same OPc
program_uicc displays the computed OPc if you pass option –xx
The HSS updates all OPc values in the database if you specify the OP in hss.conf (else set it to the empty string: “”)
Either you never use OP and set directly OPc in both HSS and program_uicc, or you use OP: both are fine.
SQN (3GPP sequence number)
In the uicc, the SQN increments by +32 after each successful authentication, the HSS must do the same.
If the SQN is not correct, the uicc will detect it and refuse the authentication challenge.
3GPP defines a authorized gap, to not block a UICC if some failure occurs: the UICC accepts SQN greater than the current one, for at least 10*32 range (so any value between curennt_value+32 and current_value+32 is ok).
Our uicc starts at 0, we test all of them before shipping, so SQN is usually set to 32 when they are new.
If the synchronization is lost, there is a way to know the current SQN in a uicc (assuming you have the OPc and the Ki).
Program_uicc offers to discover the current SQN: add –authenticate option.
This option do a authentication trial (as do the UE+HSS when the UE attaches to the network) with a SQN that is likely wrong.
Authentication should fail (as the SQN is not good), but the UICC answer allows to decode the SQN.
program_uicc verifies the correct SQN doing a correct authentication and displays the result (the SQN to set in HSS database).
AMF
If your HSS require to set it, the value is 0x8000
This value is hard coded inside OAI HSS, it is the right value for regular UICC from any brand.
VoLTE
No ISIM files in our cards.
So, if you need to setup a IMS server, for VoLTE, for SMS service, the identifiers are coming from the USIM data.
When you use our USIM programming software, you specify the IMSI and the MNC size. IMSI is <MCC><MNC><MSIN>
The document: GSM Association Official Document NG.102 – IMS Profile for Converged IP Communications tells us:
If the UICC does not contain an ISIM application, then an IMPI derived from the USIM’s IMSI as per section 13.3 of 3GPP TS 23.003 [7] must be used.
The SIP URI, domain is defined in TS 23.003 and 23.228
Domain name is: ims.mnc<usimMNC>.mcc<usimMCC>.3gppnetwork.org
the IMPI is: <usimIMSI>@ims.mnc<usimMNC>.mcc<usimMCC>.3gppnetwork.org
So, the IMPU is sip:<IMPI>