A command line tool for (U)SIM authentication
Go to file
Ludovic Rousseau 50579f1ae7 Fix pycodestyle issues
osmo-sim-auth.py:45:12: E711 comparison to None should be 'if cond is None:'
osmo-sim-auth.py:131:20: E712 comparison to True should be 'if cond is True:' or 'if cond:'

Change-Id: I959ea84b8369a0a37bb65c47824a4c4e8d4630cc
2020-10-28 17:24:57 +00:00
card SIM API's to fetch information from SIM file system like Kc, LOCI, MSISDN etc. Added -p option for fetching SIM information based on the parameter passed. 2017-06-03 00:21:09 -07:00
README.md README.md: fix typo 2020-10-25 14:35:27 +01:00
osmo-sim-auth.py Fix pycodestyle issues 2020-10-28 17:24:57 +00:00

README.md

osmo-sim-auth

This 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.

osmo-sim-auth is part of the Osmocom Open Source Mobile Communications projects.

Homepage

The official homepage of the project is http://osmocom.org/projects/osmo-sim-auth/wiki

GIT Repository

You can clone from the official osmo-sim-auth.git repository using

git clone git://git.osmocom.org/osmo-sim-auth.git

There is a cgit interface at http://git.osmocom.org/osmo-sim-auth/

Mailing List

Discussions related to osmo-sim-auth are happening on the openbsc@lists.osmocom.org mailing list, please see https://lists.osmocom.org/mailman/listinfo/openbsc for subscription options and the list archive.

Please observe the Osmocom Mailing List Rules when posting.

Contributing

Our coding standards are described at https://osmocom.org/projects/cellular-infrastructure/wiki/Coding_standards

We us a gerrit based patch submission/review process for managing contributions. Please see https://osmocom.org/projects/cellular-infrastructure/wiki/Gerrit for more details

The current patch queue for osmo-sim-auth can be seen at https://gerrit.osmocom.org/#/q/project:osmo-sim-auth+status:open

prerequisites

We assume that you have

  • A smart card reader compatible with pcsc-lite
  • Installed python program and pyscard library
  • You may also need to install and start the pcscd service

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 may also need to install the 'pcscd' service.

You should get an output like:

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

plus many more lines of output decoding the ATR.

If you only get

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, 

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.

pyscard

pyscard can be installed from packages of major Linux distributions, for example 'apt-get install python-pyscard'.

If you want to build it from source, it is available from http://pyscard.sourceforge.net/

pcscd

If you encounter errors like

smartcard.pcsc.PCSCExceptions.EstablishContextException: 'Failure to establish context: Service not available.'

or

SCardEstablishContext: Service not available.

you may have to install and run the pcscd service, for example:

apt-get install pcscd systemctl start pcscd

running osmo-sim-auth

$ ./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)

you can run the program in two modes:

  • running GSM authentication (classic SIM card protocol)
  • running UMTS authentication (USIM card protocol)

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
$ ./osmo-sim-auth.py -r 00000000000000000000000000000000 -s
Testing SIM card with IMSI 901700000000403

GSM Authentication
SRES:   215fdb4d
Kc:     6de816a759a42912

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

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.

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

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.

./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