This short document will show you how to use the basic features of TinRoof. It is assumed that you already have an AOL Instant Messenger screen name and are familiar with using standard IM software.
Paragraphs written in italics provide information of a more technical nature. Knowledge of this information is not necessary for running TinRoof. It is provided to satisfy your curiosity.
Contents:You can run TinRoof by executing the tinroof.jar package that you downloaded. From a command line interface, run the command "java -jar tinroof.jar". On most operating systems, you can also double-click on the tinroof.jar file icon. TinRoof was developed using the latest (at the time) version of the Java SDK, version 1.4.2_03. You may need to download a more recent version of the Java JRE here to run TinRoof.
The login screen will ask you for your AIM screen name, your AIM password, and a "TinRoof password." This password must be at least 8 characters long. It is used to protect the certificates you store on your hard disk between sessions. If you want TinRoof to remember your passwords, just click the checkboxes. Warning: Saved passwords are stored in plain text in obvious locations. Use this feature with caution. It is recommended that you never save your TinRoof password, as this defeats its purpose.
Ready to go? Just click "Login" and TinRoof will connect you to the AIM server.
Once logged in, your buddy list will be retrieved and you can chat with buddies just as you would with a standard AIM client. But TinRoof offers more than this. To use the special services offered by TinRoof, you will first need to generate a "Certificate" that you will share with other TinRoof buddies. Click on Edit->My Certificate, and the Certificate Manager window will pop up. Click on the "Generate a new Certificate" button. This may take a few seconds, or longer on older computers.
TinRoof generates 1024 bit RSA public/private key pairs. TinRoof uses these keys to perform a "handshake" that authenticates direct connections used for file transfers. The current release of TinRoof does not perform any encryption of the actual data transfer.
File searches and transfers can only be done between buddies who have exchanged TinRoof certificates. As you add certificates for more buddies, your file searches will have a greater chance of success. There are two ways for buddies to share certificates.
The easy way: Right click on the entry of a buddy you know to be running TinRoof. Click on the "Send Certificate" item and your certificate will be sent over an IM. Your buddy can then send their certificate to you, or you can right click on their entry again and click "Request Certificate." Once you have stored a certificate for this buddy, you will notice that their icon has switched from an AOL logo to a lock.
The secure way: Sending certificates over an unencrypted medium like the AIM server is inherently risky. Though unlikely, it is possible that someone could forge a certificate and send it to you as if they were your buddy. Short of personally handing your buddy a disk with your certificate saved on it, there is no way to be 100% certain that the certificate sent by one buddy is the one received by the other. One way that is safer than sending certificates over an IM is by emailing them. To create a certificate file, go back to Edit->My Certificate. In the "Export TinRoof Certificate" section, choose a directory to create the file in and then click the "Export" button. You now have a certificate file that you can email you buddy. They will email their certificate to you as well. Once you have downloaded the certificate from their email, rigth click on the buddy's entry and choose "Import Buddy's Certificate." Locate the certificate file in the dialog window that pops up, and click "Import."
To make a directory on your computer viewable by TinRoof buddies, you need to share that directory. Go to "View"->"Shared Directories", and click on the on the "Share Directory" button in the window that pops up. Your shared directories will be listed in this window, and you can unshare one of them by highlighting it and clicking the "Unshare Selected" button. Important: Only the directories listed are shared. Subdirectories of shared directories are not shared.
To start a new search, just type a search string in the text field below your buddy list and hit Enter. This will cause the search window to pop up. (You can also also display this window by going to "View"->"Search Window"). You can navigate through your current searches by using the combo box in this window. When you select a new current search, the search results table will be updated.
As mentioned above, your file searches will only be sent to buddies whose certificates you have stored. Also, your computer will only process search requests from these certified buddies.
Once you have found a file shared by a buddy that you would like to download, just double click on that file's entry in the search window. A download window will pop up and keep you informed of the status of the download. If your buddy is using all of their upload slots, you will be informed that this download is "Queued".
If you are on a local network: TinRoof needs to know your "external" IP address to initiate downloads. If you are behind a router, TinRoof will only be able to determine your "local" IP address. If you don't know your external IP address, you can get it from www.whatsmyip.org or similar sites. Then go to "View->File Transfer Settings" and type in the correct external IP.
If you are behind a firewall: You must enable port forwarding to be able to initiate file transfers. (This is not a TinRoof issue and so won't be covered here). Then go to "View"->"File Transfer Settings." Click on the "Use fixed port" check box, and select the range of ports you have exposed.
An alternative solution to the above problems is to select "Push Downloads," in which case your computer will request that the buddy play the role of the "server" during file transfers. Only use this option if you have to, since if your buddy has the same option selected, you will not be able to transfer files.
By default, file transfers are initiated by the downloading computer sending a file request as a specially formatted IM. This computer then sets up a server socket and waits for the uploading computer to connect. TinRoof's default behavior is to use ephemeral ports for downloads, but this behavior will not work from behind a firewall. Setting a fixed port range and reconfiguring the firewall for port forwarding will permit downloading. There is a connection timeout of 10 seconds implemented for a fixed-port-range server socket to prevent permanent blocking of the port.
If you want to send a file to a TinRoof buddy, right click on their icon and select "Send File." Choose the file to be sent from the dialog window and click the "Send" button. Note that you must have resolved firewall and external IP issues covered above, as your computer will be the "server" when sending a file.