# Pidgin Client Setup

This guide explains how to configure [Pidgin](https://www.pidgin.im/) 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/).

2. **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.

2. **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.

3. **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.