SIM Unlocker
============

Gero Treuner (Author and Copyright 2011-09-09)
Stuttgart (Germany)

http://www.70t.de/projects/k3765-z_unlock

License GPLv3+



This is a script to unlock the SIM card on a broadband (GPRS, UMTS)
modem contained in a USB device after insertion. Although it is
designed and tested for the model "K3765-Z" (distributed by Vodafone)
it should be no hard work to make it fit for other devices.

It was motivated by annoying PIN requesting popups and too many checks
whether the device is ready.



Prerequisites
-------------

* GNU/Linux or other POSIX machine
* UDEV activated
* "chat" program installed (usually part of PPP)



Files contained in this package
-------------------------------

README                        	This file
k3765-z_unlock                	The main script
k3765-z_unlock.8            	Manual page
51_vmc_zte_local.rules        	UDEV rules



Installation
------------

1.
Choose whether you want to install the script for multiple users, or
for a single user. Permissions should be limited to a specific group
for multiple users, or to your user for single-user installation. This
is because the required PIN of the SIM card should be kept as private
as possible.

For multiple users, get the name of the group. If you don't want to
create a new group. it would be a good idea to choose the group to
which the modem device is set ("dialout" on Debian).

2.
Choose places where the main script, the manual page and the run
directory should be located. Recommended directories are:

Multi-user installation:
Main script:	/usr/local/sbin
Manual page:	/usr/local/share/man/man8
Run:		/var/run/k3765-z_unlock

Single-user installation ($HOME means your home directory):
All of above:	$HOME/.k3765-z_unlock

3.
Check the path of the chat command. Probably that is /usr/sbin/chat.
Check whether the dash shell is available.

4.
Get the serial number of your modem device: Connect it to your computer
and run this command (eventually adapt chat's directory):
	/usr/sbin/chat -t 1 -e 'OK-AT-OK AT+CGSN' </dev/ttyUSB1 >/dev/ttyUSB1

5.
Login with root access rights.

6.
Create the run directory:
	mkdir <run-path-chosen-in-step-2>

For multi-user installation change group and permissions to this:
	chown :<group-chosen-in-step-1> <run-path-chosen-in-step-2>
	chmod g+w <run-path-chosen-in-step-2>

For single-user installation change permissions to this:
	chmod og-rwx <run-path-chosen-in-step-2>

7.
Edit the file k3765-z_unlock:
- Set VARRUNDIR to <run-path-chosen-in-step-2>.
- Set DEVICE_SERIAL to <serial-number-in-step-4>
- Set DEVICE_PIN to the PIN code to unlock the SIM card.
- If <chat-path-in-step-3> is not in one of the directories
  /usr/bin, /bin, /usr/sbin, then add the path to PATH variable.
- If the dash shell is not available as checked in step 3, then change
  the shell in line 1 to /bin/bash (which hopefully is there).

8.
Install the edited k3765-z_unlock file to
<main-script-path-chosen-in-step-2>.

For multi-user installation change group and permissions to this:
	chown :<group-chosen-in-step-1> <main-script-path-chosen-in-step-2>
	chmod o-rwx <main-script-path-chosen-in-step-2>

9.
Install k3765-z_unlock.8 to <manual-page-path-chosen-in-step-2>

10.
Edit the file 51_vmc_zte_local.rules to contain
<main-script-path-chosen-in-step-2> as value for the variable "RUN",
which must be enclosed in quotation marks.

11.
Install the UDEV rules contained in the edited file
51_vmc_zte_local.rules. How this is done depends on your distribution.
On Debian just copy the file to the directory /etc/udev/rules.d.
See the manual pages for UDEV and the documention of your Linux
(or other POSIX system) distribution.

12.
Start operation by executing the command:
	<main-script-path-chosen-in-step-2> -force



Troubleshooting
---------------

Of course the USB broadband modem must be plugged to the computer.

Device /dev/ttyUSB1:
	If the device /dev/ttyUSB1 is not there then something is wrong
	with your general system setup. See the documention of the
	system in this case.

	If you have multiple USB devices providing terminal devices,
	the path of the TTY device may be different than /dev/ttyUSB1.
	See the system log or /sys filesystem for more information.
	
	This script is not designed to handle varying devices names.
	This would not be easy, because the modem provides multiple
	devices, and the right one must be selected among them.

Control file:
	If the control file with name "accepted" (directory selected in
	installation step 2, for instance the complete path could
	typically be /var/run/k3765-z_unlock/accepted) is not present,
	the script is inactive because risk to permanently lock the
	SIM card is avoided.

	To start running the script the -force option is required.
	If unsure whether this is your "last try" first reset the retry
	counter of your SIM card by entering your PIN manually - if
	accepted 2 more attempts should not harm.
	Then execute the command k3765-z_unlock from the directory
	where you installed it (from installation step 2, for instance
	/usr/local/sbin, used in this example):
		/usr/local/sbin/k3765-z_unlock -force

	After that check if the "accepted" file mentioned above is
	present now. if not, continue with the next item.

Conversation with modem:
	The chat program, which is used to communicate with the modem,
	can log via syslog. The output location depends on your
	configuration. Examine some files in the directory /var/log,
	chances should be good for "messages", "syslog" or "debug".

	The logging is enabled when k3765-z_unlock is invoked with the
	-force option, or you can enable it permanently be editing the
	script, changing the variable DEBUG to "true".

	A good example looks like this:
	
		chat[27965]: abort on (ERROR)
		chat[27965]: abort on (+CPIN: READY)
		chat[27965]: abort on (+CPIN: SIM PUK)
		chat[27965]: expect (OK)
		chat[27965]: alarm
		chat[27965]: send (AT^M)
		chat[27965]: expect (OK)
		chat[27965]: ^M
		chat[27965]: OK
		chat[27965]:  -- got it
		chat[27965]: send (AT+CGSN^M)
		chat[27965]: expect (356561040123456)
		chat[27965]: ^M
		chat[27965]: ^M
		chat[27965]: 356561040123456
		chat[27965]:  -- got it
		chat[27965]: send (AT+CPIN?^M)
		chat[27965]: expect (+CPIN: SIM PIN)
		chat[27965]: ^M
		chat[27965]: ^M
		chat[27965]: OK^M
		chat[27965]: ^M
		chat[27965]: +CPIN: SIM PIN
		chat[27965]:  -- got it
		chat[27965]: send (AT+CPIN=1234^M)
		chat[27965]: expect (OK)
		chat[27965]: ^M
		chat[27965]: ^M
		chat[27965]: OK
		chat[27965]:  -- got it

	On errors try to enter the commands seen above manually and
	check the results. This is done with so-called terminal
	programs like miniterm or kermit.

	As these are standard commands, you can try to get the support
	of the phone provider to solve the problem (ha ha).

Still does not work:
	Although the author of this script is going to answer general
	questions and is interested in fixing errors regarding this
	script, he definitely does not have time to solve individual
	problems regarding your setup or environment. Please keep in
	mind that the work behind the script is done in spare time and
        is available without a fee.
	Please refer to internet resources, or look for someone near
	to you who can do that, like an administrator.



Caveats
-------

During the communication with the modem the PIN is visible in the list
of processes (for instance with the ps command) which is not really
secure.

To solve this some arguments for the chat programm must be delivered
via a file. This suggests to introduce a configuration as base for
generating this file. As the handling of configuration is more in the
domain of operating system distributions, this is left out at the
moment.
Maybe someone tests more broadband adapters or adds support for them,
or another one needs multiple configurations for a bunch of modems
- we will see what requirements matter.