User Guide

This page needs work! Please help by adding more content, reorganizing, anything. Thanks!

<em>

[edit] Account Properties

[edit] Ignore SSL warnings

SSL certificates are used to offer encrypted communication between the client and the server.

There are servers which use self-signed SSL certificates. If your Jabber server is one of those, you may get an error like this:

The [servername] certificate failed the authenticity test.
Reason: Certificate is self-signed.

Psi is warning you that the certificate is not trusted. You should be able to connect by pressing 'Continue', however this will not work when you are registering a new account.

This is not a problem with Psi. This is a problem with your server's certificate. If you don't want Psi to warn you about an untrusted certificate, then the server administrator needs to get the certificate signed by a Certificate Authority (like Verisign).

If you are aware of the security issues and want to "trust" a self-signed certificate, for one thing, be sure you do trust the administrator. We've seen some server admins who are doing this as a hobby not a business and they don't wish to shell out cash for a properly signed certificate. (Hint, SSL certs are cheap now.)

If you still wish to use a self-signed certificate but don't want to get the warning on each login, you simply need to check this option (Ignore SSL warnings) in 'Account Properties' dialog for the account you wish to log into.

If you enable this option, be aware that it is easy for an attacker to send you another self-signed certificate (which will then be trusted), without you noticing it. Better explicitly install the certificate as a trusted certificate in Psi, and leave this option unchecked.

[edit] File Transfer

[edit] Introduction

File transfer with Psi depends like everything in Psi on the XMPP/Jabber protocol standards. To accomplish a file transfer, the sender and the receiver have to establish a connection which allows them to transfer binary data streams between each other.

[edit] Binary Streaming Methods

In XMPP there are two different methods defined to manage a binary data stream: in-band and out-of-band. Both are described below.

[edit] In-Band

In this method the data is sent in pieces on the same XML connection used for chatting.

Disadvantages

In this method all of the traffic flows inline over the Jabber server(s) to which the sender and the receiver are connected. This creates additional load on the Jabber server(s), making it potentially difficult for some high-traffic servers to support.

Furthermore, due to the inline nature of this method, the transfer speed is often much slower than through a direct (Out-Of-Band) connection.

Advantages

One advantage is a bit of anonymity between the sender and the receiver as only the server knows their IP-addresses. Furthermore, this method requires no special configuration on the client side, making the ability to send a file automatic among established peers.:

Psi currently doesn't support data transfer over an In-Band data stream.

[edit] Out-Of-Band

In this method a separate connection is made for the binary data transfer. The clients themselves have to negotiate a working data stream/connection by sending each other their IP-addresses or the address of a proxy which is capable of connecting the partners together.

Disadvantage

This method carries added complexity when firewalls are involved between the sender and receiver. This can be minimized by using a proxy server, which also adds a layer of anonymity as the sender and the receiver need not know know each others IP-addresses.

Advantage

The transfer speed may be faster with this method. Throughput is generally limited only by the connection speed of the sender and receiver.

This is the only method Psi can currently use to execute a file transfer.

[edit] Configuration

Options, Application tab

A very important fact about file transfer with Psi is, that the client must be enabled to connect through a TCP port to an external computer. The default port for this is 8010 but it can be freely changed in the "Options" dialog available through the main menu of Psi. The option is called "Data Transfer Port" and resides on the "Application" tab.

Also on this tab is the option "Data Transfer External Address" which is to be used when Psi is not able to detect your external IP-address because you are connected to the internet through a router.

• If you have a static internet address you can fill it in this field.
• If your provider assigns a dynamic address to you everytime you connect to the internet, you should use a dynamic DNS name which contains your current IP-address. Two well known providers for free dynamic DNS are DynDNS.org and No-IP, a more scalable and also free offer is available at the german noxa.de Network (seems to be only accessible in german language at the moment).

For a file transfer to work, at least one of the partners has to be able to act as a server and is reachable through a direct connection on the defined Data Transfer Port. If you use a common home router, you could specify a static port mapping (often called "Virtual Server") to your computer or better use a triggered port mapping by defining the Data Transfer Port Psi uses (mostly 8010) as the trigger to bind exactly the same port to your local machine.

Account Properties, Misc tab

If everything above hasn't helped you, or is in anyway not possible on your network your last chance is to use a Data Transfer Proxy. You can tell Psi to use such a proxy by opening your "Account Setup" window through the main menu and modify your currently used profile. On the account modification dialog "Psi: Account Properties" go to the tab "Misc" and use the text-box labeled "Data Transfer Proxy" to set the proxy's address. "Data Transfer Proxy" expects a JID and not a FQDN.

The most popular proxies are "proxy.jabber.org" (hosted by the Jabber Foundation) and "proxy64.jabber.ccc.de" (hosted by the Chaos Computer Club from germany). Also you can look if your XMPP Server provides his own proxy, by doing a Service Discovery on your XMPP Server. If you see something like "SOCKS5 Bytestreams Service" you can enter the corresponding JID as "Data Transfer Proxy".

Now you should be able to send and receive files. If not, your network configuration probably prohibits Out-Of-Band file transfer through Psi, or you might have missed something above.

[edit] Sending files

A transfer can be started by:

• right-clicking on a contact in your roster and then choosing "Send File"
• simply by dragging a file from the shell over a contact in your roster and drop it there.

Send file dialog box

This will open a "Send File" dialog in which you can:

• choose the account from which you want to send the file by using the drop down menu labeled "Identity"
• define the JID, including the resource to whom you want to send the file by editing the "To" text-box (should be automatically filled)
• specify a path to the file you want to send by using the text-box labeled "File" or the button near to it if you didn't use the drag & drop way to open the "Send File" dialog.
• optional: you can give your partner a description of the file you want to send her/him by typing anything into the "Description" text-box.

As soon as everything is correctly filled in you can start the negotiation and transfer process by clicking on the "Send" button. The animations states that Psi is still working on it's task. After the choosen receiver accepted the file and has choosen a path for the incoming file to save and if everything is configured the right way, the Transfer Manager will open and display a progress bar indicating the state of the file transfer. If the Transfer Manager doesn't appear either your partner has declined the file transfer or no data stream connection could be established. If the last case is right, read about Configuration paragraph.

[edit] Transfer Manager

The Transfer Manager window lists every file transfer and indicates the progress of every one. It will save every previous transaction until the "Clear Finished" button is pressed or the entry is individualy deleted by right-clicking and using the "Clear" option. Also transfers which are not yet finished can be aborted by right-clicking and using "Cancel". The Transfer Manager can be opened manually through the same named entry in the main menu of Psi.

[edit] Technical Details

After a file transfer request is sent to a Jabber user and this user accepts the request, both partners are sending their IP-addresses, DNS-names or those of a proxy to the partner. Both will then try to establish a connection through any of these. If this works a Out-Of-Band binary data stream connection is established and will be used to transfer the file.

[edit] Encryption

Warning: You should be aware of the fact that neither the file itself nor the file name and the file description will be sent encrypted although you are using OpenPGP encryption for chatting. If you want an encrypted file transfer you have to encrypt the file manually before transfer. On Windows you can use the your OpenPGP keys and Windows Privacy Tools (WinPT) or any other file encryption tool to do this.

[edit] Foreign Networks

A file transfer to different instant-messaging network through a Gateways (Transports) is not impossible. But it resides in the responsibility of the Gateway you use to offer this ability. At the moment there seem to be very few Gateways which support such a feature. Psi is only a XMPP-client and so it will never be responsible for this to work.

[edit] The Future

In the future it will most likely be possible to send files to contacts which are offline and also to receive file if the sender is already offline. This will be possible due to a WebDAV based storage service which the XMPP server has to offer to it's users. Actualy this process is discussed about at the Jabber Foundation as JEP-0129.

Also it is possible that in a later version Psi will support In-Band binary stream connections which would help all people who cannot use file transfer because of firewall and routing limitations.

Google Talk have implemented File Transfer via Jingle - this makes it far more likely that a file transfer will succeed. There is a Google Summer of Code 2006 Project to implement Jingle File Transfer in Psi.

[edit] External Links

• FTP Website Creation/Configuration

[edit] History

[edit] GnuPG

There are 2 types of encryption:

• end-to-end (e2e) encryption - Psi supports GnuPG
• client-to-server (c2s) encryption - Psi supports SSL/TLS for encrypted communication with the server

TODO: to be merged to be merged

[edit] Setting up GnuPG

(could be moved to something like... "Helper Documents")

No matter how well designed a messaging network is, it is often possible for someone to intercept and read your messages. Although we cannot stop the possibility of someone intercepting your message, we can stop them reading it by encrypting it.

Rather than re-inventing the wheel by developing encryption especially for Psi, we use a very fine encryption program called Gnu Privacy Guard (GnuPG). GnuPG is a free replacement for Pretty Good Privacy (PGP), and suits Psi better because it runs on Windows, Mac and Linux. To use encryption in Psi, you will first need to install and configure GnuPG.

First, download and install GnuPG. The method for doing this will vary depending on your Operating System. A correct installation of GnuPG on Windows will add a registry key that tells the system where gpg.exe is located. If you cannot open a command prompt window and run gpg.exe, then you will need to ensure that the gpg.exe executable is in your PATH. Refer to your Windows manual for how to change the executable PATH.

[edit] Creating Key Pairs

(could be moved to something like... "Helper Documents")

To use GnuPG, you will need to create something called a key pair. One key is public, you give this to your friends. When they message you, Psi encrypts their messages with your public key, and you unscramble it using your private key. Never give your private key to anyone at all, ever! By keeping your private key secure, your friends are guaranteed of your identity when they chat to you. To create a key pair, use this command:

gpg --gen-key

You will be asked the length of key to create; 1024 bit is fine. You will also be asked for a passphrase. This will be the password to your private key, so you'll need to remember it! You may also be asked for a comment; this is optional. You might also like to upload your public key to the keyserver network so that your friends can automatically download it, but that's beyond the scope of this document. Read your GnuPG documentation, or download a graphical GnuPG front-end like WinPT or GPGshell.

[edit] Configuring Psi

After you have configured GnuPG you must make sure that you have QCA gnupg plugin for libqca2 installed in your system (in ubuntu it's available in the repositories through the libqca2-plugin-gnupg package). After making sure the plugin is installed, quit and restart Psi in order for it to detect the installation. Now, click the Psi menu and select Account Setup. Choose the account you wish to use encryption with, and click the Modify button. When the Account Properties dialog appears, select the Details tab and click the Select Key button in the OpenPGP section. If this button is greyed out, make sure you have restarted Psi since installing GnuPG. Select your private key and click the OK button. You will be returned to the Account Properties dialog and prompted for your private key password.

[edit] Assigning GnuPG keys

[edit] Using Encryption

Before reading this section, you should read the Setting up Encryption chapter. It explains how to set up GnuPG for use with Psi.

encrypt button To be able to send someone encrypted messages, you need to have their public key in your GnuPG keychain. For someone to be able to send encrypted messages to you, they need to have your public key. To learn how to import and export keys, read your GnuPG documentation, or use a graphical front end like WinPT or GPGshell.

If you have the public key of the friend you wish to have an encrypted chat to, and he has yours, then you can click the encrypt icon shown in the picture on the right.

chat encrypted After clicking the button, type and send a message. You may be prompted to select your friend's public key. Choose it and click the OK button. You will see a green message in your chat window, saying that encryption has been enabled (shown on the left). The lock icon will show a closed lock with a gold glow around it, indicating that GnuPG is successfully scrambling your chats.

The example above shows a chat being encrypted. You can also encrypt regular messages by clicking the same icon in the message window.

[edit] Usage

Once set up, end-to-end encryption can be used for encrypted Chats or encrypted Messages.

[edit] Troubleshooting

• FAQ: How can I avoid having to enter my GnuPG password each time I log in ?
• Investigating GnuPG Problems

[edit] Psi Options

[edit] Application

[edit] Chat

[edit] Events

[edit] Status

Psi has the possibility to change status automatically, when the computer is idle. This feature platform dependant and it might not work because of various platform-related reasons.

Windows

* the idle detection on Windows 9x,Me is embedded in the idleui.dll library, coming with Psi.exe in the same folder

* some anti-virus software might detect by error the library as dangerous object, even removing it from the system - the library does not have any malicious behaviour embedded (we have been notified that this happens with some versions of McAffe Antivirus)

MacOS

* nobody reported missing functionality on this plaform

Linux

* you need the XScreenSaver extension

* most distributions have this, but you might not have it or have it disabled

Due to the increasing demand of new features, the developers have planned a rewrite for the Status System. The design document with the new vision can be found here.

[edit] Appearance

[edit] Emoticons

Location: Psi Button > Options > Appearance > Emoticons

This is the page where you can the emoticons used by Psi in chats and messages.

• to enable emoticons, make sure you check 'Enable Emoticons' - this also enables Text Formatting.
• The list displayed here allows you to see the emoticons which will be used by Psi, by priority. What does that mean? Assuming you have 2 emoticon-sets mapping ":)" to 2 different images, when ":)" needs to be shown on the screen Psi will use the image in the top-most emoticon-set. If the first emoticon set does not have ":D" image for example, it will be looked in the following emoticon-sets and the first one found is displayed.

[edit] GroupChat

[edit] Sound

Include: http://forum.psi-im.org/post/25460

[edit] Advanced

 <store>
   <certificate>
     <data>Lots of nice data here</data>
   </certificate>
   <certificate>
     <data>Data of another cert</data>
   </certificate>
   ...
 </store>