The first time pysiriproxy is executed on your system (assuming it has been installed), the following directory will be created in your home directory. The typical location of this directory is:
~/.pysiriproxy
Note
All instructions will refer to this directory location even though it may be located in different place on your system.
The default contents of the configuration directory will look like:
./pysiriproxy.cfg
- ./certificates
- ca.pem cert.log server.passless.crt server.passless.key
- ./plugins:
- __init__.py buttonTest.py locationTest.py resetPlugin.py testPlugin.py
- ./scripts:
- gen_certs.sh openssl.cnf setDnsmasq.sh
The contents are described below:
The pysiriproxy configuration file is named pysiriproxy.cfg and it has the standard ConfigParser format. This configuration contains the following configuration sections and settings which can alter how pysiriproxy will run:
- The General section:
- PluginsDir – This setting contains the path where pysiriproxy plugins are located.
- The Server section:
- Host – This setting contains the hostname for Apple’s web server.
- Port – This setting contains the port number for Apple’s web server.
- The iPhone section:
- Port – This setting contains the port number which the iPhone will connect to.
- KeyFile – This setting contains the path to the key file which was generated by the certificate generation process.
- CertFile – This setting contains the path to the crt file which was generated by the certificate generation process.
- The Logging section:
- LogLevel – This setting contains the log level used by pysiriproxy. This can have the following values: DEBUG, INFO, WARN, or ERROR. This setting controls the amount of output which is logged by the system.
- DebugLevel – This setting contains the debug level to use for the system, where a value of 0 indicates a higher importance.
- The Responses section:
- Error – This setting contains a string which Siri will say in the event that an Exception is encountered during the process of processing an iPhone request.
The plugins directory is the location where pysiriproxy expects all plugins to be stored. At runtime, pysiriproxy will load all of the Python files located in this directory into memory and the loaded plugins will then be used to intercept the communications between the iPhone and Apple’s web server.
After the initial installation of pysiriproxy, the plugins directory will contain the following files:
- __init__.py – This file is needed to allow pysiriproxy to import the plugin scripts at runtime.
- buttonTest.py – This is an example of a plugin that creates buttons which the user is able to interact with to perform different tasks.
- locationTest.py – This is an example of a plugin that allows the user to test creating map locations, and getting directions between two map locations.
- resetPlugin.py – This is a plugin which performs the task of resetting the request context in the event that an object is received that cancels the current request.
- testPlugin.py – This is an example of plugin that demonstrates how to command Siri to interact with the user in various ways, such as: asking the user a question, or displaying text to the user.
Note
Developers should never need to modify the __init__.py, or resetPlugin.py files.
Developers can create new plugins by adding a new Python file to the plugins directory. This file should contain a subclass of the BasePlugin class, and should have the .py extension. These new plugins will be loaded by pysiriproxy at the start of the system.
Please see the section on Writing plugins for instructions on how to create a custom plugin.
The scripts directory contains various scripts needed by pysiriproxy. The scripts are as follows:
- gen_certs.sh – This script generates the certificate files needed to create the correct permissions to connect to Apple’s web server.
- openssl.cnf – This is a configuration file used by the gen_certs script to generate the certificate files.
- setDnsmasq.sh – This script takes an IP address as its only argument and modifies the /etc/dnsmasq.conf to use the given IP address. It also handles restarting dnsmasq to use the new settings.
The certificates directory contains the certificate files generated by the gen_certs script. Once the certificates have been generated this directory will contain the following files:
- ca.pem – The security certificate which should be sent to the iPhone which will use pysiriproxy.
- cert.log – The log file created by the gen_certs script.
- server.passless.crt – The certificate file generated by the gen_certs script.
- server.passless.key – The key file generated by the gen_certs script.
The pysiriproxy certificates can be generated by running the following commands (assuming the installation process was followed exactly):
$ cd /opt/pysiriproxy
$ ./siriproxy --gencerts
In order for your iPhone to have the correct permissions to interact with pysiriproxy, you must first generate the certificate files (see the section on generating certificates for pysiriproxy), and then you must install the certificate onto your iPhone.
In order to install the certificate on your iPhone you must copy the ~/pysiriproxy/certificates/ca.pem file onto your iPhone. The easiest method for doing this is through e-mail.
On your iPhone, you should be able to open the e-mail attachment and it should give you the option to open the file in Safari. Once opened, you will have the option to install the certificate onto your phone. Select yes and continue through the remaining prompts.
The certificate is now installed onto your iPhone. You can edit this at any time by navigating through the following menus:
Settings > General > Profiles > SiriProxyCA
This will give you the ability to view settings about the certificate, or to remove the certificate from your phone.
The next step in the configuration process is to set up your computer to properly intercept requests for Apple’s web server. This is done through use of the dnsmasq tool (see the section on installing dnsmasq). Dnsmasq needs to be configured with the IP address of the machine on which it is running in order to properly function. The following steps will help you easily configure dnsmasq to use the IP address of your choosing:
Once the pysiriproxy configuration directory has been created, there will be a script called ~/.pysiriproxy/scripts/setDnsmasq.sh which can be used to quickly change the IP address used by dnsmasq.
Here is an example of how to use this script to set the dnsmasq IP address to use 192.168.0.5:
$ sh ~/.pysiriproxy/scripts/setDnsmasq.sh 192.168.0.5
This script should be run with the IP address of your machine which is connected to the same network as the iPhone. You will not be able to successfully use pysiriproxy if both the machine running dnsmasq and the iPhone are not connected to the same network.
The final step in the configuration process is to set up the wireless settings for the iPhone so that its requests are processed by the machine running dnsmasq. This is done by modifying the DNS option of the wireless network. The following will describe how this is done:
On the iPhone, navigate through the following menus:
Settings > WiFi
On this menu you should first connect to the desired wireless network, and then once connected click on the blue arrow to modify the settings for that wireless network.
This will bring you to the settings menu for your wireless network. Scroll down and select the text in the DNS option. This will allow you to enter the IP address for the machine running dnsmasq. This should be the same IP address as was used when configuring dnsmasq. This will force all DNS requests to be processed by the machine running dnsmasq, which allows pysiriproxy to intercept the commands being sent to Apple’s server.
Note
If you find that you wish to reset the DNS settings for this wireless network you can do so by deleting the entire IP address from the DNS option. Once you do this, and leave the menu you will find that the DNS option will be reset to its original value.
With the release of iOS 6 Apple has updated Siri to use different servers than it was using in the previous version of iOS. As of release 0.0.6, the pysiriproxy server has been updated to accept requests from iPhones running either iOS 5 or iOS 6 with only a single configuration change.
This is accomplished by generating a generic SSL certificate for the iPhone which supports the *.apple.com server. This should allow the same certificate to support future changes to the Apple server.
The setDnsmasq.sh script properly configures dnsmasq to route requests for both the Guzzoni and Kryten servers to the local machine.
The pysiriproxy server is now setup, by default, to route queries to the iOS 6 server at kryten.apple.com rather than the iOS 5 server at guzzoni.apple.com. If you wish to change which server is being used modify the Hosts property under the Server section to be the desired server address.
The only configuration change needed to change whether pysiriproxy supports iOS 5 or iOS 6 phones is to change the configuration file ~/.pysiriproxy/pysiriproxy.cfg. The Hosts setting under the Server section needs to be updated according to which version of iOS you would like the server to support.
For iOS 5 the file should read:
Host = "guzzoni.apple.com"
And for iOS 6 the file should read:
Host = "kryten.apple.com"
A special thanks to Aaron (meluvalli) for his help with thoroughly investigating and testing support for iOS 6.