Introduction to

    ClamMail POP3 proxy server for Windows


BranSoft home page


  1. Why ClamMail ?

ClamMail was created because I didn't find any free alternative. ClamMail is a personal (but in a positive meaning) POP3 proxy for Windows which can also filter emails deleting malware. It is licensed under the GNU General Public License - no dual licensing or free for non-commercial only!

Personal means here that it should not be used in network larger then a few computers due to the internal architecture (starting one thread for each request) – no test was done how it behaves when the request count is higher.

ClamMail can be used as a POP3 proxy only and (and this was the main reason to create it) to filter incoming emails and delete all unwanted malwares (viruses, trojans, phishings and more).

Of course, if your POP3 server is protected by a good antivirus software (for example ClamAV for Linux/Solaris/FreeBSD), ClamMail would not be required.


ClamMail POP3 personal proxy is released under the GNU General Public license. Only.
(to avoid ambiguity: you may charge to distribute ClamMail (costs of distributing,packing,writing documentation,CD etc) and any other service you provide along the way. You may not charge for the ClamMail itself)

Use it, share with others, support if you wish. You could also make a small donation (contact brandys@bransoft.com) to help extend this project to a full antivirus product not only a POP3 proxy.


  1. Credits


This application is using the libclamav.dll from the Windows port of ClamAV – the excellent GPL antivirus software (http://www.clamav.net).

As of the time of writing this introduction, libclamav.dll is using ClamAV version 0.80 with some fixes, but not the current CVS version. This is of course still a problem as long as my pure Windows port is not merged into ClamAV CVS.

If you want to compile libclamav.dll and freshclam.dll on your own look at the page: http://www.bransoft.com/clamav.html

This application is using Synapse - non-visual Delphi objects for Internet communication and various protocols (http://www.ararat.cz/synapse)


Official home page of ClamMail is here : http://www.bransoft.com.


  1. Requirements


A system running Windows 98/Me or Windows NT/2000/XP is required. On Windows 2000/XP ClamMail is installed as an auto-started service running in the LocalSystem account context. During installation the service is started if supported by the OS and the default configuration is probably functional. However, changing the configuration (especially mirrors for signatures updates) is required.

Under Windows 98/Me ClamMail is running as a hidden process (hidden means here that ClamMail has no visible window).

This program could also work with Windows 95, however, Winsock 2 and iphlpapi.dll are missing and required.

There may be some problems on Windows NT 4.0 or previous. (I don't even know if it works with such old versions, latest service packs and Internet Explorer 5.5+ may be required). The current installer should not be limited by the NT version. If it works for you please send me a note to include it to the FAQ .

Due to the fact that ClamMail is using Synapse there are some limitation for accounts under which this program can run.


From the Synapse readme:


„On WinNT standardly RAW sockets work if program is running under user with administrators provilegies. To use RAW sockets under another users, you must create the following registry variable and set its value to DWORD 1:
HKLM\System\CurrentControlSet\Services\Afd\Parameters\DisableRawSecurity
After you change the registry, you need to restart your computer!”


  1. Usage

Basic:

1. Set the user name in your email client application settings to contain also the destination POP3 server like this:


user\POP3_server[:port][+|-]


The port is optional and defaults to 110. It is required only if the destination POP3 server is using a non-standard port.

"+" if full SSL is required on this port

"-" to disable STLS/STARTTLS negotiation in authorization stage



2. Set the POP3 server tin your email client to localhost (or the host name in your local network, where ClamMail is installed).

3. Set the authentication method to simple (ClamMail is using other methods like APOP transparently)


Important:

You must set a proper DNS server and the mirrors for updating the clamav database to the nearest of your location. Please check the ClamMail applet in the Control Panel.


Advanced:

If the destination server is using SSL (port 995) you should download or compile the OpenSSL DLL files, put them into the program directory and restart the ClamMail service using the Control Panel applet.



  1. Configuration

On all supported operating systems the configuration of the program (or service) is done using Control Panel applet. Due to system differences the services must be restarted to apply configuration changes. There is no option to stop ClamMail on Windows 98/Me and it is started during system boot (using an autostart entry).


Important:

The first thing ClamMail does on start is to update the ClamAV antivirus databases (main.cvd and daily.cvd) as it is distributed without those files. This could take some time depending on your internet connection and the chosen ClamAV database mirror (the main.cvd size is about 1,5MB). However, daily.cvd (daily updates) is rather small and subsequent updates are rather quick even if the ClamMail main proxy is suspended during the update process. Clients cannot connect to proxy while an update is in progress. Yes, this is a known design flaw and should be changed, but not in version 1.0 release :-)
If first update fails , the second one and subsequent are started with about 2 minutes period. After the first succesfull update (which means that databases are updated or recognized as fresh) this period is extended to the value set in control panel applet.
This is implemented in such way to allow quick update for ADSL internet connection which could be in "not established" state when clammail service is started on system boot.


Notice:


Control panel options:



Use ClamAV scan engine

If not checked, ClamMail is working as simple POP3 proxy only without filtering any emails.

Limit archives scan

Max files in single archive

Archives with more than this number of files will not be scanned.


Max archive file size

Archives larger that this limit will not be scanned.


Max recursion level

If an archive contains another archive which contains another archive within, and so on, and if such recursion is deeper that given limit this archive won't be scanned.


Max compression level

Archives which contain some files with a compression ratio bigger than this limit will not be scanned (this prevents some obscure DoS attack when small archive contains really big empty files). Notice: some files are compressible beyond this limit.

Report broken executable

Treat broken executables like malware (for example broken EXE file) Report such files as Broken.Executable malware. Use with caution.

Debug level

None

Only important informations,warnings and errors are logged into event logged


Mail debug

All commands sent by the email client, ClamMail proxy and destination POP3 server is logged if dbgview or any other special program is running.

Mail + Clam debug

The same as above plus all debug information from the libclamav.dll engine is logged.

Mail + Clam+ Update debug

The same as above plus the update process and DNS resolution is stored in update.log file.

Mail + Clam + Update + Email

Full debug. Also all email data is logged if dbgview is used. Very slow.



Proxy server IP

IP address to which the server should bind on start. ClamMail uses this IP. In case of 0.0.0.0 all available interfaces are used. Using localhost (127.0.0.1) ClamMail will accept only local connections. Notice: do not open ports on globally available IP interfaces without a correctly configured firewall

Proxy server port

ClamMail will listen on this port

Max data length

Maximal incoming data stream size in bytes from POP3 server in a single request response (either reply or one line of email data stream) . Used to avoid memory overflow by DOS attack. Use 0 (zero) to disable this limitation. Note : each attachment is encoded to many lines (ex.: MIME). This limits ONLY one line length.Avoid to download large e-mails by setting option in e-mail client as it's his duty.

Connection timeout

After this timeout a connection to the destination POP3 server is closed. Also connections to ClamMail POP3 proxy server from any client email is limited by this timeout. Default is 20 seconds (should be sufficient). This is timeout between throwing TCP/IP packets.



Clean email, report virus by modification of email body

Infected email will be cleaned (all attachments and the email body are deleted), the email body is being replaced by a special notification text. Email headers remain unchanged.

Clean email, report as error

Infected email will be cleaned (all attachments and email body are deleted),an error will be reported to the user (and the connection will be dropped). Infected email is being deleted from destination POP3 server. Users will retrieve other emails after connecting once again. This option is not recommended.

Don not clean email, only modify email header

Instead of cleaning email, only some special email header parts are added:

X-Virus-Scanner with ClamMail signature and versions

and X-Virus with malware found name.

Cleaned email message

Text of special email notification in simple HTML. The email body is being replaced by this message if the first user action above is used.

Notice: %s will be replaced by the actual malware name. Only one such item must be used in this text.

Charset encoding

Used to properly display localized version of the notification text (see above).



DNS info server

This is the DNS record (type TXT) published by the ClamAV team. By querying this record, ClamMail learns what the latest virus database is and eventually download the newly released database. Notice: do not clear this field, unless you really know what you are doing!

Database mirrors

ClamAV antivirus signature database is mirrored all over the world. Please configure ClamMail to download the database from the mirror closest to you. Add something like db.XY.clamav.net where XY represents your Country code. Check http://www.iana.org/cctld/cctld-whois.htm for the complete list of Country codes.You must keep database.clamav.net at the bottom of the list. Remove it only if you really know what you are doing.

Check every

ClamMail checks for a database update once as soon as it starts and then periodically, at the interval defined here. Checking too often is just a waste of resources, so you are not allowed to set this value below 15.



If malware is found ClamMail can report this fact also by sending a notification email to someone else (e.g. an sysadmin). Set e-mail notification parameters here.



On this page, the status of the ClamMail service can be checked and changed (only on Windows NT/XP/2000) ,last signatures update could be reviewed ,system tray icon could be enabled to monitor ClamMail behaviour.



I wish to thank all people which help me with creating this program.
Especially:

Pete - for creating good-looking home page for ClamMail



Best Regards
Bogusław Brandys
BranSoft