Cloudmark Authority Plug-in for SpamAssassin -- connects SA to 
locally-running Cloudmark anti-spam filtering system.

Jeremy Robin, Kent Brake, Doug McCasland
Cloudmark Inc. 2007-8


------------------------------------------------------------------
Introduction

For several years, SpamAssassin has had built-in support for connecting
to Cloudmark's free Razor2 spam-checking service.  For each message being
checked, SA calls a Razor2 agent program.  The agent generates two types of 
message fingerprints and then connects to Cloudmark via the Internet to 
see if the message has been reported as spam by others.  SA uses the 
results to increase or decrease the message's spam score.

Because Razor2 is not suited to high-volume email traffic, Cloudmark 
developed a carrier-grade product called Authority, now used by major ISPs
to handle millions of messages per day.  Here are some benefits of the 
Authority product.

* The Authority daemon runs continuously, accepting requests to check messages. 

* An in-memory fingerprint database is maintained, with micro-updates 
  from Cloudmark downloaded every minute.
  
* Each message is checked using that database, not over the Internet,
  so message checking is much faster.  

* An expanded set of fingerprints (currently 12), resulting in much greater 
  accuracy than Razor2.  Rapid response to the latest spam campaigns is 
  automatically enabled.
  
ISPs and other email providers who already use SpamAssassin can now
get the same benefits of Authority -- without a big server integration
project.  The Cloudmark Authority Plug-in for SpamAssassin lets SA do
spam-checking via Authority.  It is a simple installation, and it works 
entirely within pre-existing MTA and SpamAssassin setups.


------------------------------------------------------------------
Cloudmark Plug-in Architecture

Here are the server components:

* Cloudmark Authority Engine (CMAE).  A server daemon.  Loads the 
  Cartridge, maintains an in-memory database from Cloudmark micro-updates,
  accepts client connections, generates fingerprints, and provides results.
  
* Cloudmark Cartridge.  A dynamic library.  Contains the latest
  fingerprint algorithms and micro-update technology.  This component
  can be updated independently of CMAE.
  
And the client components:

* Cloudmark CMAE client perl interface (Cloudmark::CMAE::Client.pm).  
  Used by perl scripts to talk with CMAE, employs CMAE Client API.
  
* CMAE.pm (SpamAssassin::Plugin::CMAE.pm).  The Cloudmark Plug-in, 
  located in SA's Plugin directory.  Written according to SA's plugin 
  standard, this module uses subroutines from the CMAE client perl 
  interface to interact with the CMAE server.
  
* /etc/sa_cmae_plugin.cfg.  Configures the behavior of the Plug-in.

The CMAE daemon runs all the time.  SpamAssassin (either the 
spamd daemon or the spamassassin command) connects to CMAE, via the 
client side of the Plug-in, to request Cloudmark spam filtering.  

If CMAE is not running for some reason, spamassassin/spamd will simply
skip to the next phase of its processing, and mail delivery will continue.  


------------------------------------------------------------------
Installation

There are two installation paths you can follow:

***************
a. Full integration with SpamAssassin.  Choose this when you're ready
   to start filtering your MTA's email with the Cloudmark Plug-in running.
   Root access is required.

   Please follow the instructions in the INSTALL file.


***************
b. The Quick Test installation.  Choose this if you would like to try out
   the Cloudmark software, without changing any of your system files.  Root
   access not required.  (A full integration can be easily done afterward.)

   Please cd to the quicktest sub-directory and follow the instructions in 
   the README.quicktest file.


======================================================================
Copyright (c) 2008, Cloudmark, Inc.  All rights reserved. 

Redistribution and use in source and binary forms, with or without 
modification, are permitted provided that the following conditions are 
met: 
    * Redistributions of source code must retain the above copyright 
      notice, this list of conditions and the following disclaimer. 
    * Redistributions in binary form must reproduce the above copyright 
      notice, this list of conditions and the following disclaimer in the 
      documentation and/or other materials provided with the distribution. 
    * Neither the name of Cloudmark, Inc. nor the 
      names of its contributors may be used to endorse or promote products 
      derived from this software without specific prior written permission. 
      THIS SOFTWARE IS PROVIDED BY CLOUDMARK, INC. ``AS IS'' AND ANY EXPRESS OR 
      IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 
      OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 
      IN NO EVENT SHALL CLOUDMARK, INC. BE LIABLE FOR ANY DIRECT, INDIRECT, 
      INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 
      NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 
      DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 
      THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 
      (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 
      THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 

EXPORT LAWS: THIS LICENSE ADDS NO RESTRICTIONS TO THE EXPORT LAWS OF YOUR 
JURISDICTION. It is licensee's responsibility to comply with any export 
regulations applicable in licensee's jurisdiction. Under CURRENT (May 2000) 
U.S. export regulations this software is eligible for export from the U.S. and 
can be downloaded by or otherwise exported or re-exported worldwide EXCEPT to 
U.S. embargoed destinations which include Cuba, Iraq, Libya, North Korea, Iran, 
Syria, Sudan, Afghanistan and any other country to which the U.S. has embargoed 
goods and services. 
 









