SIM card related Projects » osmo-sim-auth

h1. osmo-sim-auth

{{>toc}}

osmo-sim-auth is a small script that can be used with a PC-based smart card

reader to obtain GSM/UMTS authentication parameters from a SIM/USIM

card.

The program can be found in the git repository at git://git.osmocom.org/osmo-sim-auth, web-based browsing is available at http://cgit.osmocom.org/cgit/osmo-sim-auth

h2. prerequisites

We assume that you have

* A smart card reader compatible with pcsc-lite

* Installed python program and pyscard library

h3. smart card reader

Any reader supported by pcsc-lite will work.  However, a reader

compatible with the USB CCID device class is much recommended.

Please verify that the hardware and driver setup is working, e.g. by

using the 'pcsc_scan' tool included with pcsc-lite.  You should get an

output like:

<pre>

V 1.4.17 (c) 2001-2009, Ludovic Rousseau <ludovic.rousseau@free.fr>

Compiled with PC/SC lite version: 1.5.5

Scanning present readers...

0: [[OmniKey]] CardMan 5121 00 00

Wed Dec  7 01:32:37 2011

 Reader 0: [[OmniKey]] CardMan 5121 00 00

  Card state: Card inserted, Shared Mode, 

  ATR: 3B 9F 95 80 1F C7 80 31 E0 73 FE 21 13 57 12 29 11 02 01 00 00 C2

ATR: 3B 9F 95 80 1F C7 80 31 E0 73 FE 21 13 57 12 29 11 02 01 00 00 C2

</pre>

plus many more lines of output decoding the ATR.

If you only get 

<pre>

PC/SC device scanner

V 1.4.17 (c) 2001-2009, Ludovic Rousseau <ludovic.rousseau@free.fr>

Compiled with PC/SC lite version: 1.5.5

Scanning present readers...

0: [[OmniKey]] CardMan 5121 00 00

Wed Dec  7 01:35:08 2011

 Reader 0: [[OmniKey]] CardMan 5121 00 00

  Card state: Card removed, 

</pre>

then your card was not detected in the reader. 

If you don't even get any displayed readers, your hardware and/or driver

setup are likely wrong.

h3. pyscard

pyscard can be installed from packages of major Linux distributions.

If you want to build it from source, it is available from

http://pyscard.sourceforge.net/

h2. running osmo-sim-auth

<pre>

$ ./osmo-sim-auth.py --help

Usage: osmo-sim-auth.py [options]

Options:

  -h, --help            show this help message and exit

  -a AUTN, --autn=AUTN  AUTN parameter from AuC

  -r RAND, --rand=RAND  RAND parameter from AuC

  -d, --debug           Enable debug output

  -s, --sim             SIM mode (default: USIM)

</pre>

you can run the program in two modes:

* running GSM authentication (classic SIM card protocol)

* running UMTS authentication (USIM card protocol)

h3. classic GSM authentication

This mode will use the "RUN GSM ALGORITHM" command as specified in GMS

TS 11.11

You have to specify

* the 16 byte RAND value from the AuC (-r) as 32 hex digits

* the '-s' flag to enable SIM mode

<pre>

$ ./osmo-sim-auth.py -r 00000000000000000000000000000000 -s

Testing SIM card with IMSI 901700000000403

GSM Authentication

SRES:   215fdb4d

Kc:     6de816a759a42912

</pre>

h3. UMTS authentication

This mode will use the "AUTHENTICATE" command as specified in 3GPP TS

31.102

You have to specify

* the 16 byte RAND value from the AuC (-r) as 32 hex digits

* the 16 byte AUTN value from the AuC (-a) as 32 hex digits

h4. successful operation

In this case, the tool will output the following values obtained from

the card:

* RES authentication result value

* CK ciphering key

* IK integrity key

* Kc for inter-RAN handover from UMTS -> 2G

Secondly, the tool will re-run the authentication in "2G authentication

context" in order to obtain the SRES result.  This value would be used

if a 3G/2G dual-mode phone registers on a 2G network.

<pre>

python ./osmo-sim-auth.py -r 00000000000000000000000000000000 -a ec9320c2c2000000e1dd22c1ad3e2d3d 

[+] UICC AID found:

found [AID 1] 3GPP || USIM || (255, 134) || (255, 255) || (137, 255,

255, 255, 255)

[+] USIM AID selection succeeded

Testing USIM card with IMSI 901700000000403

UMTS Authentication

RES:    e9fc88ccc8a35381

CK:     7200a184d8f2c758fbdf87900ddbf275

IK:     12cb2dd3e0ec8378f6fc1d606c619f47

Kc:     6de816a759a42912

GSM Authentication

SRES:   215fdb4d

Kc:     6de816a759a42912

</pre>

h4. synchronization required

In this case, the AUTHENTICATE command will return the AUTS parameter,

which has to be sent to the AuC in order to re-synchronzie the SQN

counter which is kept in both the USIM as well as the AuC.

<pre>

./osmo-sim-auth.py -r 00000000000000000000000000000000 -a ec9320c2c2120000c8b7de2a3449f1bd

[+] UICC AID found:

found [AID 1] 3GPP || USIM || (255, 134) || (255, 255) || (137, 255,

255, 255, 255)

[+] USIM AID selection succeeded

Testing USIM card with IMSI 901700000000403

UMTS Authentication

AUTS:   8711a0ec9e2be2f766881a64605b

GSM Authentication

SRES:   215fdb4d

Kc:     6de816a759a42912

</pre>

h4. Authentication Error

If you receive SW 98 62, it means that your AUTN parameter somehow is wrong.

Please try to understand how mutual USIM authentication works, and read the thread at

http://lists.osmocom.org/pipermail/simtrace/2013-March/000468.html

"osmo-auc-gen":http://cgit.osmocom.org/libosmocore/tree/utils/osmo-auc-gen.c which is part

of libosmocore can help you to generate the correct parameters.