This is merely a historical archive of years 2008-2021, before the migration to mailman3.
A maintained and still updated list archive can be found at https://lists.osmocom.org/hyperkitty/list/gerrit-log@lists.osmocom.org/.
Harald Welte gerrit-no-reply at lists.osmocom.orgReview at https://gerrit.osmocom.org/2124 Update README file with general information and convert to Markdown Change-Id: Ic9f95c073b17bfe689dea7672c67e5c081c01dae --- R README.md 1 file changed, 63 insertions(+), 23 deletions(-) git pull ssh://gerrit.osmocom.org:29418/osmo-sim-auth refs/changes/24/2124/1 diff --git a/README b/README.md similarity index 72% rename from README rename to README.md index fe46693..e532a87 100644 --- a/README +++ b/README.md @@ -1,10 +1,50 @@ -= osmo-sim-auth = +# 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. -== prerequisites == +osmo-sim-auth is part of the [Osmocom](https://osmocom.org/) Open Source +Mobile Communications projects. + +## iHomepage + +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 at 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](https://osmocom.org/projects/cellular-infrastructure/wiki/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 @@ -12,7 +52,7 @@ * Installed python program and pyscard library -=== smart card reader === +### smart card reader Any reader supported by pcsc-lite will work. However, a reader compatible with the USB CCID device class is much recommended. @@ -20,7 +60,7 @@ 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: -{{{ +``` V 1.4.17 (c) 2001-2009, Ludovic Rousseau <ludovic.rousseau at free.fr> Compiled with PC/SC lite version: 1.5.5 Scanning present readers... @@ -32,12 +72,12 @@ 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 -{{{ +If you only get +``` PC/SC device scanner V 1.4.17 (c) 2001-2009, Ludovic Rousseau <ludovic.rousseau at free.fr> Compiled with PC/SC lite version: 1.5.5 @@ -47,7 +87,7 @@ 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. @@ -55,17 +95,17 @@ setup are likely wrong. -=== pyscard === +### 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/ +<http://pyscard.sourceforge.net/> -== running osmo-sim-auth == +## running osmo-sim-auth -{{{ +``` $ ./osmo-sim-auth.py --help Usage: osmo-sim-auth.py [options] @@ -75,13 +115,13 @@ -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 === +### classic GSM authentication This mode will use the "RUN GSM ALGORITHM" command as specified in GMS TS 11.11 @@ -90,16 +130,16 @@ * 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 === +### UMTS authentication This mode will use the "AUTHENTICATE" command as specified in 3GPP TS 31.102 @@ -108,7 +148,7 @@ * 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 ==== +#### successful operation In this case, the tool will output the following values obtained from the card: @@ -121,7 +161,7 @@ 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, @@ -139,15 +179,15 @@ GSM Authentication SRES: 215fdb4d Kc: 6de816a759a42912 -}}} +``` -==== synchronization required ==== +#### 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, @@ -162,4 +202,4 @@ GSM Authentication SRES: 215fdb4d Kc: 6de816a759a42912 -}}} +``` -- To view, visit https://gerrit.osmocom.org/2124 To unsubscribe, visit https://gerrit.osmocom.org/settings Gerrit-MessageType: newchange Gerrit-Change-Id: Ic9f95c073b17bfe689dea7672c67e5c081c01dae Gerrit-PatchSet: 1 Gerrit-Project: osmo-sim-auth Gerrit-Branch: master Gerrit-Owner: Harald Welte <laforge at gnumonks.org>