mk6i-open-oscar-server/docs/CLIENT_PIDGIN.md

Pidgin Client Setup

This guide explains how to configure Pidgin to connect to Open OSCAR Server, either unencrypted or over SSL.

Prerequisites

1. Pidgin with AIM Support

Use one of the following:

- **Modern Pidgin**: Install the [retro-prpl](https://github.com/pidgin/retro-prpl) plugin, which adds AIM and
  ICQ support.
- **Pidgin 2.14.2**: The last version that supported AIM natively. Download it from
  [SourceForge](https://sourceforge.net/projects/pidgin/files/Pidgin/2.14.2/).

1. Open OSCAR Server Instance

Configure and run an Open OSCAR Server instance using one of the available guides.

- For a simple **unencrypted** installation, follow the release setup guide for your operating system.
    - [Windows](./WINDOWS.md)
    - [Linux](./LINUX.md)
    - [macOS (Intel & Apple Silicon)](./MACOS.md)
- For an advanced **SSL-enabled** installation, follow the [Docker Setup Guide](./DOCKER.md).

Setup Procedure

1. Add an AIM Account

Open Accounts → Manage Accounts → Add... and select AIM as the protocol. On the Basic tab, enter your screen name as the Username and your password.

1. Configure the Connection

On the Advanced tab, configure the connection type that matches your server installation.

- **Unencrypted**: Set **Server** and **Port** according to the `OSCAR_ADVERTISED_LISTENERS_PLAIN` configuration
  found in `config/settings.env`. For example, if `OSCAR_ADVERTISED_LISTENERS_PLAIN=LOCAL://127.0.0.1:5190`, set
  **Server** to `127.0.0.1` and **Port** to `5190`. Set **Connection security** to **Don't use encryption**.
- **SSL**: Set **Server** and **Port** according to the `OSCAR_ADVERTISED_LISTENERS_SSL` configuration found in
  `config/ssl/settings.env`. For example, if `OSCAR_ADVERTISED_LISTENERS_SSL=LOCAL://ras.dev:5193`, set **Server**
  to `ras.dev` and **Port** to `5193`. Set **Connection security** to **Require encryption**.

For both connection types, set Authentication method to MD5-based.

Click Add to save the account. Pidgin signs on immediately.

1. Sign On and Accept the Certificates (SSL Only)

If your server uses the certificate generated by make docker-cert, which is signed by the server's private root CA, Pidgin warns twice that it cannot validate the certificate. Click Accept both times. Pidgin remembers both certificates, so the warnings do not appear again.

- The first warning is for your server's hostname, during authentication.
- The second warning is for `bos.oscar.aol.com` and says the certificate claims to be from your server's hostname
  instead. Pidgin checks the connection made after authentication against this hardcoded AOL hostname, so the
  warning appears even with a certificate from a trusted CA.