SIMPHONE USER MANUAL (version 0.8)

Simphone is a highly secure peer-to-peer application with the appearance of an "instant messenger". Because of its complete decentralization, some things work in a specific way, and you should read this technical manual in order to get acquainted with it.

1. System Requirements

To use Simphone, you need:

2. Installation

On Windows (XP or version 7 or later), please extract simphone.exe by dragging it out of the downloaded ZIP file and dropping it to your Desktop or any other convenient location and then click the extracted simphone.exe to use it.

On Mac OS (version 10.6 or later), place the downloaded ZIP file to any convenient location and then click on it to unpack simphone.app. You can then use Simphone by clicking the unpacked simphone.app.

On GNU/Linux x64, please unpack the downloaded ZIP file to your home directory or any convenient location. You can then start the unpacked simphone executable by clicking it or from the command line (shell).

unix installer (advanced)

If you use FreeBSD or another unix-like system, or if the GNU/Linux ZIP does not work for you (for example, because your computer is not x64), you can use the generic unix installer as described below.

Before you begin, please make sure that your home directory has at least a couple of gigabytes of free disk space and the system has at least 512 megabytes of free memory (one gigabyte is recommended).

Place the downloaded unix installer into your home directory, and type the following commands from the "shell" prompt (also known as a "Terminal" application) to unpack and start the installer:

   cd
   gzip -df simphone_installer.shar.gz
   sh ./simphone_installer.shar

This process may take a very long time (depending on the speed of your computer and eventually of your internet connection), so please do not interrupt it while working (you can use the computer to do other tasks in the mean time).

A few tools and libraries are needed in order to create a Simphone unix executable. If some of them are not found, the installer will try to fetch them automatically from the internet servers of your unix system for you. If you have ran the installer as non-root, it will try to prompt you for your password or for the root password (inside the Terminal application) at that point. This usually happens only the first time you run the installer; when it does, please make sure you are connected to the internet and either type the required password or re-run the installer as root.

At the end of the process, the installer will explicitly report either SUCCESS or FAILURE; in case of success, it will have created simphone (the executable file) inside the current directory (your home directory). You can then proceed to use simphone by clicking it, or you can copy it to another location or to another similar unix system and use it from there.

There may be some warnings printed at the end of the installation process; these mean that simphone was created but some bits of functionality are not and cannot be made available with your system.

In case of a total failure, the installer will explicitly report why it failed and eventually what you need to do to make it work. If this happens, please send the error messages to the Creators of Simphone.

3. Network Configuration

Simphone employs advanced router traversal techniques so it can work even if no incoming internet connectivity is available, but it works faster and better if it is. That is why it is in your own interest to enable incoming connections if you can do so.

If you are behind a "home" router, the easiest way to enable incoming connections is to log on to your router via its web interface and enable UPNP.

If you are an advanced user and UPNP is either not available or not desired, you can forward the Simphone server port number instead. To do so, first click 'Settings' (from the 'Main' menu of Simphone) and choose the 'Network' tab. Check the 'Listen for incoming connections at port number' checkbox and then click 'OK'. You can change the port number before that, if you like.

Afterwards, log on to your router via its web interface and forward the chosen port number to the computer where Simphone is running (you could also forward all ports by adding your computer to the router DMZ - sometimes also known as exposed host - if your router offers such a function). You should enable both TCP and UDP for the forwarded port, but if you can forward the port only for a single protocol, please choose TCP.

If you have incoming network connectivity, but your operating system includes a firewall, you will also need to configure it so as to allow Simphone (or/and its chosen port number) to receive incoming connections. On Windows and Mac OS, Simphone will try to do this for you (it will prompt you for the Administrator password if necessary). Note however that this works only for the built-in firewall; third-party firewalls (such as ones included with anti-virus programs) require you taking care of that manually.

4. Key Generation

To sign up for the use of Simphone, you do not need to register anywhere. Instead of that, you use:

Both the secret key and the simphone address are rather long in order to fulfill the high security requirements.

A secret key will be automatically generated for you on first use. By default, this key can be used only with the computer where it was generated.

While this is good enough for a quick start that allows you to try out Simphone, it is better to generate a key that can be used with any computer (also known as a seed), because:

To generate such a seed, uncheck the 'Generate a key for use only with this computer' checkbox when you first start Simphone. The generated seed will be shown to you as a word list; write it down and store it to a safe location (outside your computer). If you do not wish to encrypt your key file and contact list, check the 'My filesystem is secure: do not require that I enter key (store private key for auto-login)' checkbox as soon as the seed is shown. Failing to do that will prompt you to enter your seed each time you start Simphone; this can also be avoided later by clicking the 'Auto login' button from the 'Window' tab of 'Settings' (from the 'Main' menu of Simphone).

5. Communication

After you have successfully generated a key, Simphone will display your contact list. Initially, there are three contacts in this list:

You can set your online status by clicking the status icon in the right bottom corner of the Simphone window.

The simphone system contact is your link to the Creators of Simphone. While we will never spam you, we reserve the right to send important security announcements to all users through this contact. If you do not require such functionality, you can permanently delete the simphone system contact by right-clicking it. In this case no data transfer of any kind between you and the simphone system contact can ever take place, unless you undelete it.

You can store notes by typing chat messages to yourself; these aren't sent anywhere.

The test contact exists only in your contact list; no network packets are sent for this contact. If you do not wish to see the test contact or yourself, you can delete either one or both of them; doing so has no other but a visual effect on the contact list.

To add a real contact, click 'Add contact' (from the 'Contacts' menu of Simphone) and enter the simphone address of your contact. They would then receive a contact request from you.

In order to know in a secure way, who you are really communicating with, you need to click the 'Verify' button in the chat window of your contact. This is done only once; the Verify button will disappear when both sides have verified each other. Note that unverified contacts are displayed in italics in your contact list. Communication with an unverified contact is NOT guaranteed to be secure (private), even if there's no doubt to their identity.

You can use the same simphone identity (key/address) at more than one computer, but not at the same time. If you are logged on with the same identity from more than one computer at the same time, the least recent one(s) will automatically change their status to offline, while the most recent one remains online. You can later change the offline status back to online manually, in which case the computer where you did this becomes the most recent one, and the previous most recent one will automatically change its status to offline.

If you have logged on with the same identity at another computer for the first time, your contact list will initially be empty, but you will automatically receive contact requests from your existing contacts as they log on. You do not usually need to add these contacts manually to each computer where you use Simphone, unless you want to speed up the process.

6. Network Diagnostics

Because Simphone is completely peer-to-peer, some functions may take more time than they do with "centralized" instant messengers. You can send messages and make audio calls at any time, but they will be delivered only when BOTH you and your contact are online at the same time (in case of an audio call, they will receive a "missed call" notification, so they can call you back). That is why you should leave Simphone "always on" as much as possible.

Also note, that while you can change your status to offline without stopping Simphone, doing so is not recommended; better use the invisible status instead. Changing your status from offline to online or vice versa generates a burst of network traffic, as Simphone attempts to notify your contacts about your changed status.

Decentralization also means that online status of your contacts is indicative, not definitive. It may easily happen that a contact is shown offline, but goes online as soon as you send them a message, or vice versa. It usually takes a few minutes to find a contact who has changed their IP address recently. Likewise, it may take a while for your own status to change to online after you start Simphone (especially when you start it for the first time). Neither of these should discourage you from sending a message or a contact request; it might just take a while before you receive a reply for the first time.

To see information about a contact, right-click it and choose 'Info'. The test contact's info contains diagnostics (system) information, including your simphone address. The 'Connection' flags can be watched in order to monitor your internet connectivity. Presence of 'TCP in', 'SSL in', 'DHT in' or 'UPNP' usually indicates that incoming connectivity is available (although it may take quite a while for these flags to be updated). 'TCP out' and 'DHT out' indicate that outgoing connectivity is available (both of them should be present).

Explanations of contact info items (as well as of settings and some other GUI elements) are available as tooltips. To see them, point the mouse to the item you want to see, without clicking it. If your window is visible but not on focus, click the window title to bring it on focus, before you point the mouse.

7. Audio Device Troubleshooting

If you do not use headphones, your contacts may hear an echo of their own voice while talking to you. To help them out, you can turn software echo cancellation on by fully checking it from the 'Audio' tab of 'Settings' (from the 'Main' menu of Simphone).

However, echo cancellation may impair audio quality, so it's best not to turn it on generally; please leave the checkbox partially-checked instead (unless there's a real problem with echo).

If you hear an echo of your own voice while talking to someone, you can turn echo cancellation on by right-clicking the contact and choosing 'Settings' from that contact's context menu.

The rest of this chapter contains tips on what to do in case audio calls do not work at all.

To check if your audio device is working, you can use the 'Audio test' button from the 'Audio' tab of 'Settings'.

If audio calls connect, but then disconnect in five seconds or if you cannot understand what your contact is saying, the first thing you should try is change the audio sampling rate from the 'Audio' tab of 'Settings'.

unwritten or unread audio frames (shown in contact info during a live audio call) usually indicate problems with the audio device. lost audio frames usually indicate network problems (unless combined with unwritten or unread frames at your peer).

It may also help to set an audio latency value (particularly if you use GNU/Linux), or/and switch between SYSTEM DEFAULT and an explicitly named (ALSA) audio device. Additionally, if you can install the ALSA OSS emulation, you should use it by choosing /dev/dsp as your audio device. Even though each of these three names usually refers to the same physical device, only some of them may work (depending on your setup). Another (advanced) audio setting, which may improve (or degrade) audio calls under GNU/Linux is available by typing the following command to the simphone console (chat with the test contact):

   set audio.samples 320

To reset the setting back to its default value, type:

   unset audio.samples

This setting is effective only for subsequent audio calls (you first need to hang up your current call, if any).

If you use pulseaudio and increasing the audio latency value does not help, reset the pulseaudio and ALSA configuration to default. The safest way to do so is create a new user account on the Linux machine and check if Simphone audio then works. If it does, you can proceed to find out what exactly you need to reset under your old account in order to get your audio device to work with Simphone.

8. Data Files (advanced)

All data are usually kept in a subdirectory called .simphone/user under your home directory. Simphone will create this directory when started for the first time, unless you used command-line arguments to instruct it to store its data elsewhere, as described below.

On Windows, the path to your home directory would be something like:

   c:\Users\<windows-username>

Most files are in a "binary" format (cannot be read with standard tools) but your chat history is stored in plain text inside the history subdirectory of .simphone/user. You can read or manipulate your history files with a plain text editor, a web browser or an XML viewer/editor. If you want to edit the files, please quit Simphone first.

File encryption employed by Simphone is only meant as an optional bit of additional protection, not as a replacement for filesystem encryption. You are advised to encrypt your whole filesystem through a third-party open-source utility, in order to prevent unauthorized persons from stealing your secret key and your other data. Physical security of your computer is even more important; filesystem encryption helps only if physical security is breached in a non-subtle way.

If you want Simphone to store its data to a different location (such as a USB stick or a specially encrypted filesystem), the easiest way to do so is through the -portable command-line argument. By starting

   simphone -portable

you tell Simphone to create the .simphone/user subdirectory under the directory where the program is, instead of under your home directory.

If you want to use multiple simphone identities, you have to explicitly store each one to a different subdirectory, instead of the (default) user subdirectory. You can do so by giving the (full) path to that directory as a -user command-line argument when starting Simphone, for example:

   simphone -user "name1"
   simphone -user "name2"

There are a few other command-line arguments, which are available to advanced users. You can see a list of them by starting:

   simphone -help

9. Anonymous usage (advanced)

Simphone is a program that allows you to communicate with your contacts, so if any of them know who you are, then you are not anonymous.

However, Simphone can be used with the TOR network in order to hide your IP address from your contacts. If you want to do this, be sure you fully understand how TOR works. Start the TOR daemon (service) when you're ready to go.

Afterwards, you need to generate a simphone identity to use with TOR. For security reasons, you MUST start Simphone in offline mode to do so, by starting:

   simphone -offline

When you have generated your secret key and logged on, click 'Settings' (from the 'Main' menu of Simphone) and choose the 'Network' tab. Check the 'I want to use TOR proxy at port' checkbox and click 'OK' after you've made sure the chosen TOR port is correct. You can now change your status to online.

If you ever uncheck the TOR proxy setting that you initially checked, your IP address will be revealed to your contacts (you should not do this). If you're paranoid about it, you can start Simphone in offline mode each time and go online only after you've made sure the checkbox is checked.

Simphone does not leak DNS queries to the local network, even if TOR claims otherwise. However, DHT queries are sent locally as TOR does not support UDP. Usually they cannot be seen by your contacts.

Please understand that the speed or latency of your connection may be unacceptable when using TOR. Audio calls may or may not work.