Cloudmark Authority Engine

Cloudmark 

Authority Engine 

SDK Guide

Copyright © 2006 Cloudmark, Inc. All rights reserved. 

This document may not, in whole or in part, be copied, photocopied, reproduced, 

translated or reduced to any electronic medium or machine readable form without prior 

consent in writing from: 

Cloudmark, Inc. 128 King Street, 2nd Floor, San Francisco, CA 94107 

All examples with names, company names or companies that appear in this guide are 

fictitious and do not refer to, or portray, in name or substance, any actual names, 

organizations, entities or institutions. Any resemblance to any real person, organization, 

entity or institution is purely coincidental. 

While every effort has been made to ensure technical accuracy, information in this 

document is subject to change without notice and does not represent a commitment on 

the part of Cloudmark, Inc. Cloudmark makes no warranties with respect to this 

documentation and disclaims any implied warranties of merchantability and fitness for 

a particular purpose. Cloudmark shall not be liable for any errors or for incidental or 

consequential damages in connection with the furnishing, performance or use of this 

manual or examples herein. 

Cloudmark Authority Engine version 1.5 

Last modified: March 14, 2006

Contents 

CONTENTS 

CHAPTER 1 About This Guide . . . . . . . . . . . . . 1 

CHAPTER 2 System Requirements . . . . . . . . . . . 3 

Windows . . . . . . . . . . . . . . . . . . . . . . . . . 3 

Development Environment . . . . . . . . . . . . . . . . . . . 3 

File Manifest . . . . . . . . . . . . . . . . . . . . . . . . 3 

Platform Dependencies . . . . . . . . . . . . . . . . . . . . 4 

Linux . . . . . . . . . . . . . . . . . . . . . . . . . . 4 


File Manifest . . . . . . . . . . . . . . . . . . . . . . . . 5 


Solaris . . . . . . . . . . . . . . . . . . . . . . . . . . 7 


File Manifest . . . . . . . . . . . . . . . . . . . . . . . . 7 


FreeBSD . . . . . . . . . . . . . . . . . . . . . . . . . 9 


File Manifest . . . . . . . . . . . . . . . . . . . . . . . . 9 

Platform Dependencies . . . . . . . . . . . . . . . . . . . 10 

CHAPTER 3 Application Development . . . . . . . . . . 11 

How CMAE detects spam . . . . . . . . . . . . . . . . . . .11 

Spam filtering basics . . . . . . . . . . . . . . . . . . . .12 

Obtaining message scores . . . . . . . . . . . . . . . . . . 12 

Classifying messages based on score . . . . . . . . . . . . . . 13 

Applying actions to messages . . . . . . . . . . . . . . . . . 13 

iii

Contents 

Designing your application . . . . . . . . . . . . . . . . . 14 

CHAPTER 4 API Reference . . . . . . . . . . . . . . 15 

Conventions . . . . . . . . . . . . . . . . . . . . . . . 15 

Scoring messages . . . . . . . . . . . . . . . . . . . . . . 15 

Object Management . . . . . . . . . . . . . . . . . . . . . 16 

Synchronization and Threading. . . . . . . . . . . . . . . . . 16 

Memory Management . . . . . . . . . . . . . . . . . . . . 16 

Call Sequence . . . . . . . . . . . . . . . . . . . . . . . 17 

Error Codes . . . . . . . . . . . . . . . . . . . . . . . . 17 

Constants . . . . . . . . . . . . . . . . . . . . . . . . 18 

Structures . . . . . . . . . . . . . . . . . . . . . . . . 18 

Callback Functions . . . . . . . . . . . . . . . . . . . . 19 

CMAE Functions . . . . . . . . . . . . . . . . . . . . . 22 

Scoring Functions . . . . . . . . . . . . . . . . . . . . . 25 

Envelope Functions . . . . . . . . . . . . . . . . . . . . 27 

CHAPTER 5 The CMAE SDK Client and Daemon . . . . . . 35 

The CMAE daemon . . . . . . . . . . . . . . . . . . . . 35 

The CMAE client library. . . . . . . . . . . . . . . . . . . 37 

The CMAE client binary . . . . . . . . . . . . . . . . . . . 42 

APPENDIX A Sample Code . . . . . . . . . . . . . . 45 

Index . . . . . . . . . . . . . . . . . 49 

iv

About This Guide 

CHAPTER 

1 

The Cloudmark Authority Engine Software Development Kit (the CMAE 

SDK) enables C/C++ developers to add the spam-filtering functionality of 

the Cloudmark Authority Engine (CMAE) to applications that run on 

Linux, Solaris and Windows. 

Filtering email for spam with CMAE has several advantages: 

• universal compatibility with a wide range of network components; 

CMAE deploys in nearly any environment that uses firewalls, border 

systems, email management tools, anti-virus filters and other SMTP 

message processors 

• minimal impact on network resources 

• continuous, real-time adaptation to the latest trends in spam-, 

worldwide. CMAE is automatically updated with new spam definitions 

as they are created via micro-updates: light-weight, Cloudmark-issued 

update files that enhance the spam-filtering functionality of CMAE, 

without requiring any downtime 

• up-to-date spam-filtering technology. Cloudmark periodic microupdates 

This guide provides the information necessary to develop applications 

using the CMAE SDK: 

• Chapter 2, “System Requirements”, lists the hardware and software 

platforms, IDEs, and compilation tools required by the CMAE SDK. 

• Chapter 3, “Application Development”, provides guidelines for 

developing applications with the CMAE SDK. 

• Chapter 4, “API Reference”, details each API call available in the 

CMAE SDK. 

• Chapter 5, “The CMAE SDK Client and Daemon”, describes the 

lightweight client and daemon provided with the CMAE SDK. 

• Appendix A, “Sample Code”, illustrates the usage of the CMAE SDK 

with a small example program. 

1

Cloudmark Authority Engine SDK Guide Chapter 1 

2

System Requirements 

CHAPTER 

2 

This section lists the platforms supported by the CMAE SDK, as well as 

the development requirements for each: 

• “Windows” below 

• “Linux” on page 4 

• “Solaris” on page 7 

• “FreeBSD” on page 9 

Windows 

The CMAE SDK for Windows runs on Microsoft Windows Server 2000 

and 2003 (with the latest service packs installed). 

Development Environment 

The CMAE SDK for Windows integrates with Microsoft Visual Studio 

.NET 7.1 using the Multithreaded DLL settings for runtime library 

inclusion. For other development environments, use standard settings. 

File Manifest 

The resources included with the CMAE SDK for Windows are: 

Table 1 

File 

cmae.h 

cmae.dll 

Windows file manifest 

Description 

Header file for the CMAE C interface 

The CMAE dynamic library implementation 

3


Table 1 

File 

cmae.lib 

example.c 

Windows file manifest 

Description 

The library file for implicit linking of the CMAE dynamic library 

An example application; run it like this: 

example 

example 

example.vcproj 

example.sln 

engtest.exe 

A precompiled version of example.c and the associated Visual 

Studio project files 

A more comprehensive precompiled version of engine.c that 

scores all messages in an mbox file 

In addition to the files included in the SDK, you must also download the 

latest cartridge update. The cartridge contains the latest algorithms for 

analyzing messages and detecting spam. 

Platform Dependencies 

The CMAE SDK for Windows requires the following libraries: 

Table 2 

DLL 

Windows platform dependencies 

Folder 

msvcr71.dll 

msvcp71.dll 

[SystemDir]\system32 

[SystemDir]\system32 

Linux 

The CMAE SDK for Linux is supported by Pentium II hardware and 

above, running Red Hat Enterprise Linux ES 2.1 or higher or Redhat 

Desktop 8 or higher. 

! The CMAE SDKis not compatible with the AMD K6 processor. 

4 Linux

Chapter 2 



The CMAE SDK for Linux is compiled by two different versions of gcc; 

specifically, versions 2.96 and 3.2. When developing your application, use 

only the build compiled for its target platform: 

• If your application is targeted for Red Hat Enterprise Linux ES 2.1, use 

the gcc 2.96-complied build. 

• If it targets Red Hat Desktop and Red Hat Enterprise Linux ES 3.0 or 

higher, use the gcc 3.2-compiled build. 

File Manifest 

The resources included with the CMAE SDK for Linux are: 

Table 3 

Linux file manifest 

Table 4 

File 

cmae.h 

cmae_port.h 

cmae_error.h 

cmae_envelope.h 

libcmae.so 

example.c 

examp 

engtest 

cmae_client.h 

libcmaeclient.so 

cmae_server 

cmae_client 

Description 

Header file for the C interface to CMAE 

A subsidiary header file required by cmae.h 



The CMAE library to add to the multi-threaded runtime libraries used 

to compile your application 


example 

A precompiled version of example.c 

A more comprehensive precompiled version of example.c that scores 

all messages in an mbox file 

Header file for the C interface to the CMAE lightweight client 

The shared library containing the CMAE lightweight client 

The CMAE daemon 

A simple CMAE client binary 




Linux 5



The library dependencies for each build differ. The next two tables list the 

dependencies for each. 

The gcc 2.96-compiled build requires these libraries: 

Table 5 Linux platform dependencies for GCC 2.96 

Library 

libz.so.1 

libpthread.so.0 

libdl.so.2 

libstdc++-libc6.2-2.so.3 

libm.so.6 

libc.so.6 

ld-linux.so.2 

Directory 

/usr/lib 

/lib 

/lib 

/usr/lib 

/lib 

/lib 

/lib 

The gcc 3.2-compiled build requires these libraries: 

Table 6 Linux platform dependencies for GCC 3.2 

Table 7 

Library 

libz.so.1 


libdl.so.2 

libstdc++.so.5 

libgcc_s.so.1 

libm.so.6 

libc.so.6 

ld-linux.so.2 

Directory 

/usr/lib 

/lib 

/usr/lib 

/usr/lib 

/lib 

/lib 

/lib 

/lib 

6 Linux

Chapter 2 


Solaris 

The CMAE SDK for Solaris is supported by the Sun Microsystems’ 

UltraSPARC hardware platform running Solaris 8 or 9 (with the latest 

patch clusters installed). 

! For best application performance on Solaris 8, Cloudmark recommends 

using the T2 threading libraries found in /usr/lib/lwp. 


The CMAE SDK for Solaris is compiled by two different versions of gcc; 

specifically, 2.95.3 and 3.2.3. 

File Manifest 

The resources included with the CMAE SDK for Solaris are: 

Solaris 7


Table 8 

Linux file manifest 

Table 9 

File 

cmae.h 

cmae_port.h 

cmae_error.h 


libcmae.so 

example.c 

examp 

engtest 

cmae_client.h 


cmae_server 

cmae_client 

Description 





The CMAE library to add to the multi-threaded runtime 

libraries used to compile your application 


example 


A more comprehensive precompiled version of example.c that 










Both gcc-compiled builds of the CMAE SDK for Solaris depend on the 

same libraries; however, additional libraries are required by each build, 

depending on the version chosen by the tool-chain: 

• The gcc 2.95.3-compiled build requires libstc++.so.2.10.0. 

• The gcc 3.2.3-compiled build requires libstdc++.so.5 and libgcc_s.so.1. 

Both builds require these libraries: 

Table 10 

Solaris platform dependencies 

Library 

libz.so 


Directory 

/usr/lib 

/usr/lib 

8 Solaris

Chapter 2 


Table 10 


Library 

libsocket.so.1 

libnsl.so.1 

libresolv.so.2 

libdl.so.1 

librt.so.1 

libstdc++.so.2.10.0 

libm.so.1 

libc.so.1 

libmp.so.2 

libaio.so.1 

libthread.so.1 

Directory 

/usr/lib 

/usr/lib 

/usr/lib 

/usr/lib 

/usr/lib 

/usr/local/lib 

/usr/lib 

/usr/lib 

/usr/lib 

/usr/lib 

/usr/lib/lwp 

FreeBSD 


The FreeBSD build requires FreeBSD 4.11 / i386 and gcc-3.3.6. 

File Manifest 

The resources included with the CMAE SDK for FreeBSD are: 

Table 11 

File 

cmae.h 

FreeBSD file manifest 

Description 


cmae_port.h 

cmae_error.h 


libcmae.so 

example.c 




The CMAE library to add to the multi-threaded runtime 

libraries used to compile your application 


example 

FreeBSD 9


Table 11 

FreeBSD file manifest 

File 

examp 

engtest 

cmae_client.h 


cmae_server 

cmae_client 

Description 


A more comprehensive precompiled version of example.c that 










The FreeBSD build requires these libraries: 

Table 12 


Library 

libc_r.so.4 

libm.so.2 

Directory 

/usr/lib 

/usr/lib 

On the FreeBSD platform, applications linked against CMAE must use the 

reentrant version of the C library. The default C compiler on the system, 

gcc, will select the correct libraries when passed the -pthread flag. 

10 FreeBSD

Application Development 

CHAPTER 

3 

This chapter provides guidelines for developing a CMAE-enabled 

application using the SDK. 

How CMAE detects spam 

Cloudmark has developed a set of fingerprinting algorithms designed to 

intelligently analyze messages and detect spam. When subjected to these 

algorithms, all messages that are part of a spam attack will produce the 

same fingerprint, even if the spammer randomizes portions of each 

message. CMAE maintains an in-memory list of bad fingerprints, updated 

every minute with micro-updates from the Cloudmark Collaborative 

Security Network. 

The Cloudmark Collaborative Security Network consists of millions of 

users submitting real-time feedback about the legitimacy of the messages 

they receive. A Trust Evaluation System tracks the reputation of each user, 

so that each user’s feedback is weighted based on reputation. 

Depending on a message’s fingerprint and the feedback from the 

Cloudmark user community, CMAE assigns a spam confidence score to 

the message, from 0 to 100. A score of 0 means the message is certainly 

legitimate, while a score of 100 means the message is certainly spam. 

Most messages receive a score that lies somewhere between these two 

numbers. You configure a threshold that determines the range of scores 

that represent spam. 

11


Spam filtering basics 

The basic steps for filtering spam in your application are as follows: 

1. obtain a score for each message 

2. classify each message as spam or legitimate 

3. apply an appropriate action to each message 

Cloudmark recommends scanning messages more than once. Because spam 

scores are affected by community feedback, a message’s score may change 

after the community has had time to submit feedback. 

For example, messages that were sent overnight should be re-scanned in 

the morning, after users have awakened and submitted feedback about 

them. In general, re-scan the message store every few hours or so, in order 

to filter spam that was recently detected by the community rather than by 

existing fingerprints. 

Obtaining message scores 

To obtain a score for a given message, you use the API to pass the message 

(without its envelope) to CMAE, which returns a score. There are three 

methods for doing this: 

• CMAE_ScoreRFC822() 

This is the simplest method, in which you provide only the message 

string (headers and body as a properly-formatted RFC822 message) and 

receive a score in return. See “CMAE_ScoreRFC822” on page 25. 

• CMAE_ScoreEnvelopeRFC822() 

This method provides both the RFC822-formatted message and its 

envelope as input. The envelope object is built using the provided 

envelope functions. The message and its envelope are scored as a unit. 

Whitelist filters are also applied to both the envelope data and the 

message. See “CMAE_ScoreEnvelopeRFC822” on page 26. 

12 Spam filtering basics

Chapter 3 

Application Development 

Classifying messages based on score 

Once your application has obtained a score from 0 to 100 from CMAE, it 

must use the score to classify the message. You can do this using one or 

more threshold values: 

• one threshold 

A single threshold represents the minimum score that qualifies a 

message as spam. Messages with a score greater than or equal to this 

value are treated as spam, while messages with a score less than this 

value are treated as legitimate. Initially, a threshold of 95 is 

recommended as the default value. 

• two or more thresholds 

The highest threshold represents the minimum score for messages that 

are certainly spam, while the lowest threshold represents the maximum 

score for messages that are certainly legitimate. Messages with scores 

that fall between these two thresholds are suspected spam. Depending 

on how many thresholds you establish, you can take action based on 

varying degrees of certainty about a message’s legitimacy. 

After some experimentation, users may want to fine-tune these values 

based on the actual rate of accuracy. Your application should provide a 

way for users to modify the threshold value. 

! For cartridge 3043 only, CMAE returns one of only two scores: 0 or 

100. 

Applying actions to messages 

Your application must provide functionality that applies an action to a 

message of a given classification. Examples of such actions may include the 

following: 

• moving spam to a mailbox folder specifically designated for it 

• adding a header to a message to trigger actions in other email processing 

applications 

• placing a text identifier in the subject line of suspected spam that allows 

users to readily identify it in their mail clients 

Spam filtering basics 13


Designing your application 

There are two major options for designing your application: 

• run CMAE directly within your application 

This method entails a few moments of initialization time, as it requires 

loading both CMAE and its filtering data. If the latest micro-update is 

not already on disk, then downloading it from Cloudmark may require 

a minute or more, depending on available bandwidth. The CMAE 

process must run on the same host as the MTA. 

Once CMAE and its data set are loaded, queries to CMAE can take 

place efficiently. No further setup or tear-down is required. With both 

the MTA and CMAE on the same host, messages can be passed quickly 

without using network resources. 

! The fork() function is not supported under this scenario. 

• create a daemon that encapsulates CMAE, then query the daemon using 

a lightweight client layer 

Using this approach, the cost of initializing the client layer should be 

negligible. Potential benefits of this approach include the ability to 

perform the filtering work outside of the application, sharing a single 

filtering daemon among multiple application instances, and the ability 

to run the daemon on a different host than the MTA. 

14 Designing your application

API Reference 

CHAPTER 

4 

This chapter provides API conventions for developing CMAE-enabled 

applications; they are followed by a complete list of functions, constants, 

and structures available in the CMAE SDK and usage details for each. 

Conventions 

The CMAE API is a standards-based C interface and can be compiled by 

any ANSI C compiler. The functions, constants and structures of the API 

are defined in cmae.h, the header file for the C interface. 

Scoring messages 

The CMAE SDK provides two methods for scoring messages: 

• The first method passes an entire message to CMAE to obtain a score 

for it, including both the headers and body, using only one function 

(CMAE_ScoreRFC822). While this the simplest method, it is also the 

most resource intensive. 

• The second method passes one or more parts of a message to CMAE, 

which returns a score based on only the provided subset of SMTP data 

(e.g., just the envelope or the headers, or both). With it, messages can be 

scored at various stages of the SMTP transaction, from the initial 

network connection to the receipt of the message body. This method 

enables your application to optimize CMAE message scoring 

performance by, for example, bypassing analysis of the headers and 

body content for messages with a specific IP address in their envelope. 

To score a message using its SMTP envelope, construct an envelope object 

(CMAE_Envelope) with the envelope handling functions prior to scoring it 

(CMAE_ScoreEnvelopeRFC822). The constructed envelope must be freed 

15


after scoring with the CMAE_EnvelopeDone function. See “Envelope 

Functions” on page 27. 

Object Management 

CMAE_Envelope objects are instantiated by CMAE_Init and 

CMAE_EnvelopeInit, and are freed by the CMAE_Shutdown and 

CMAE_EnvelopeDone destructors, respectively; however, if the objects are 

instantiated by CMAE, they are freed automatically. 

All CMAE_Envelope objects must be synchronized by your application. 

Synchronization and Threading 

CMAE is thread-safe and can process multiple messages in multiple 

threads. 

When initializing CMAE, your application should not call any API 

functions until CMAE_Init is done (with the exception of registering 

callback functions). Conversely, your application should wait until all API 

functions in every thread are done before shutting down CMAE via 

CMAE_Shutdown. 

Memory Management 

To manage CMAE memory allocation, your application can register both 

the CMAE_MallocCB and CMAE_FreeCB callbacks before initializing 

CMAE. If your application does not register both callbacks before 

CMAE_Init is called, CMAE will use its built-in memory allocation 

scheme. 

Note that the functions specified as arguments for the CMAE_LogCB, 

CMAE_MallocCB, and CMAE_FreeCB functions do not guard against 

multiple entry. For CMAE_MallocCB in particular, avoid calls that may 

allocate memory, such as stdio.h functions like printf(). 

16 Conventions

Chapter 4 

API Reference 

Call Sequence 

The following call sequence is recommended: 

1. Override the callback functions for memory allocation management and 

logging. 

2. Initialize the Authority Engine with CMAE_Init. 

3. Call scoring and accessor functions. 

4. Release CMAE with CMAE_Shutdown. 

Error Codes 

All CMAE API functions return a CMAE_ERR type that indicates the 

success or failure of the function call. A function call that succeeds returns 

CMAE_ERR_NONE. A function call that fails returns a CMAE_ERR 

enumeration that indicates the reason for failure. There are three 

exceptions: CMAE_strerror, CMAE_MicroupdatesVersion, and 

CMAE_CartridgeVersion. 

Your application must provide error handling routines for every error code 

returned by a function. The possible error codes are: 

Table 1 

Error codes 

Constant 

CMAE_ERR_BADARG 

CMAE_ERR_BADFILE 

CMAE_ERR_ENGINE 

CMAE_ERR_MALLOC 

CMAE_ERR_NOFILE 

CMAE_ERR_NOINIT 

CMAE_ERR_NONE 

CMAE_ERR_STATE 

Description 

The function argument(s) was invalid 

A necessary file or resource—such as the cartridge—is 

malformed and cannot be opened by CMAE 

CMAE failed during the function call 

Memory allocation errors reported by the function call 

The specified file was not found 

A function was called prior to CMAE initialization 

No errors were returned by the function 

An operation was performed on an object in the wrong state, 

including multiple initialization 

Conventions 17


Constants 

The following constants provide CMAE version information and should be 

used to manage multiple version compatibility. 

CMAE_INTERFACE_VERSION_1 Version of the CMAE C interface in 

use by your application, which is passed to CMAE_Init(). 

const unsigned int CMAE_INTERFACE_VERSION_1 

Use this constant to maintain backward-compatibility in your application 

to other applications that use earlier versions of the interface. 

! Cloudmark strives to maintain backward-compatibility between new 

and prior versions of the C interface. 

CMAE_InterfaceVersion Version of the CMAE C interface in use by 

your application, returned as an integer, which is updated with each new 

version of the interface. 

const unsigned int CMAE_InterfaceVersion 

CMAE_Version Version of CMAE linked to your application, as a 

human-readable string. As best practice, your application should log this 

value when initializing CMAE. 

const char *CMAE_Version 

Structures 

The following structures define the configuration parameters for CMAE: 

CMAE_Config 

Description 

Specifies the maximum number of bytes in the header and body 

content of a message to use for scoring. 

Syntax typedef struct { 

unsigned int MaxInspectHeaderSize; 

unsigned int MaxInspectBodySize; 

unsigned int UseMsgAnalysis; 

} CMAE_Config; 

18 Constants

Chapter 4 

API Reference 

CMAE_Config 

Parameters • MaxInspectHeaderSize 

The maximum size of the header to use for scoring. 

• MaxInspectBodySize 

Maximum size of the message content to use for scoring. 

• UseMsgAnalysis 

When non-zero, UseMsgAnalysis generates message analysis 

callbacks. To debug scoring issues, your application should register 

the callbacks with CMAE_MsgAnalysisCB and then, for example, 

add the returned values to the message as a header for later 

analysis. 

A size of less than 32k is recommended for both 

MaxInspectHeaderSize and MaxInspectBodySize. 

See also “CMAE_Configure” on page 23 

CMAE_Envelope 

Description 

An opaque handle to parts of the envelope structure. When 

instantiated, it contains each part of the envelope for a given message. 

CMAE_Envelope is managed by CMAE; only use the CMAE_Envelope 

accessor functions to manipulate it. See “Envelope Functions” on 

page 27. 

“Object Management” on page 16 provides additional information on 

CMAE_Envelope. 

Syntax 

Parameters 

See also 

Callback Functions 

The CMAE SDK callback functions enable logging and provide accuracy 

debugging and memory management facilities. 

Callback Functions 19


CMAE_LogCB 

Description 

Syntax 

Acquires the log messages and levels generated by the built-in logging 

functionality of CMAE. 

Your application should register for this callback and provide any 

functionality required to handle CMAE log messages. 

CMAE_ERR CMAE_LogCB( 

void (*CallBack)(CMAE_LOG LogLevel, 

const char *ASCIIFacility, 

const char *ASCIIMsg)); 

Parameters • [in] CallBack 

Pointer to a function in your application; passes the three 

parameters described next. Passing in NULL as the argument 

removes the callback registration, restoring the default behavior. 

• [in] LogLevel 

The severity of the log message as one of the following constants: 

- CMAE_LOG_ERROR 

An error that requires operator intervention; your application 

must provide error handling for this error 

- CMAE_LOG_WARNING 

Warnings returned by CMAE; your application is not required 

handle warnings, but should as best practice 

- CMAE_LOG_INFO 

General information returned by CMAE during normal 

operation; provides verbose logging capability 

• [in] ASCIIFacility 

The service that requested the logging; may be NULL. 

• [in] ASCIIMessage 

The log message as text. 

Return values See “Error Codes” on page 17. 

20 Callback Functions

Chapter 4 

API Reference 

CMAE_MallocCB 

Description 

Syntax 

Overrides the built-in memory allocation scheme of CMAE. 

The registered callback CMAE_MallocCB requires the same semantics 

as the malloc() call in C. When registered, the callback must return a 

valid pointer to a region of memory that has the number of bytes 

specified in size_t free. If unable to allocate memory, the callback must 

return NULL. Note that while CMAE uses this callback, the cartridges 

do not. 

This callback must be used in tandem with “CMAE_FreeCB” on 

page 21. 

If this callback is not registered, CMAE will manage memory allocation 

internally. 

CMAE_ERR CMAE_MallocCB (void 

*(*CallBack)(size_t Size)); 


Pointer to a function in your application that returns a pointer to 

the amount of memory allocated to CMAE (via the size_t 

parameter). Passing in NULL as the argument removes the callback 

registration, restoring the default behavior. 


CMAE_FreeCB 

Description 

Syntax 

Overrides the built-in memory allocation scheme of CMAE. 

The registered callback CMAE_FreeCB requires the same semantics as 

the free() call in C. The parameter passed to the registered callback 

contains the pointer returned by CMAE_MallocCB. Note that while 

CMAE uses this callback, the cartridges do not. 

This callback must be used in tandem with “CMAE_MallocCB” on 

page 21. 

If this callback is not registered, CMAE will manage memory allocation 

internally. 

CMAE_ERR CMAE_FreeCB(void (*CallBack)(void 

*Block)); 


Pointer to a function in the application to the allocated memory 

space via the *Block parameter; this pointer must be acquired 

from the callback function registered with CMAE_MallocCB. 

Passing in NULL as the argument removes the callback registration, 

restoring the default behavior. 


Callback Functions 21


CMAE_MsgAnalysisCB 

Description 

Syntax 

Acquires message analysis information from Cloudmark for 

troubleshooting scoring issues. 

Your application should register for this callback, if possible; doing so 

helps improve the effectiveness of CMAE. 

CMAE_ERR CMAE_MsgAnalysisCB 

(void (*CallBack) 

(const char *ASCIIMsg, 

void *AnalysisUserData)); 


Pointer to a function in the application with the specified 

parameters. Passing in NULL as the argument removes the callback 

registration, restoring the default behavior. 


See also “CMAE_MsgAnalysisUserData” on page 25 

CMAE Functions 

CMAE functions are used to do the following: 

• control initialization of the Authority Engine 

• configure the Authority Engine while in use 

• query the version of the cartridge and micro-updates 

• acquire the full text description of any error code 

CMAE_Init 

Description 

Syntax 

Initializes CMAE. 

CMAE_Init is not reentrant. Your application—and any threads it 

creates—must wait until CMAE_Init is complete before calling other 

CMAE functions; otherwise, the functions will return 

CMAE_ERR_NOINIT. 

CMAE_ERR CMAE_Init(unsigned int 

InterfaceVersion, 

const CMAE_Config *Config, 

const char *CartridgeDirectory, 

const char *ConfigDirectory); 

22 CMAE Functions

Chapter 4 

API Reference 

CMAE_Init 

Parameters • [in] InterfaceVersion 

Version of the CMAE C interface in use by your application. Set it 

to CMAE_INTERFACE_VERSION_1. 

• [in] Config 

Configuration updates for CMAE, contained in a CMAE_Config 

object. 

• [in] CartridgeDirectory 

The cartridge directory path. 

Always set CartridgeDirectory to the directory path containing the 

cartridge. 

• [in] ConfigDirectory 

Directory path to the configuration file. 

Always set ConfigDirectory with the directory path to the cartridge 

configuration file. 

Return values 

If the CartridgeDirectory or ConfigDirectory parameters are NULL, this 

function returns CMAE_ERR_BADARG 

See also See “Error Codes” on page 17. 

CMAE_Configure 

Description 

Syntax 

Applies a set of configuration parameters to CMAE when it is running. 

CMAE_ERR CMAE_Configure( 

const CMAE_Config *NewConfig); 

Parameters • [in] NewConfig 

The set of CMAE configuration parameters contained in 

CMAE_Config. 

See also See “Error Codes” on page 17. 

CMAE_Shutdown 

Description 

Syntax 

Shuts down CMAE gracefully, releasing all resources used by it. All 

scoring threads must be idle before this interface is called. The 

application must ensure that no messages are being processed when 

this function is called. 

Call CMAE_Shutdown during the exit sequence of your application. 

CMAE_Shutdown is not reentrant. Your application—and the threads 

it creates—must not call any CMAE functions during or after CMAE 

shutdown. 

CMAE_ERR CMAE_Shutdown(void); 


CMAE Functions 23


CMAE_CartridgeVersion 

Description 

Syntax 

Return values 

Returns the version of the cartridge in use by CMAE. 

Call CMAE_CartridgeVersion after CMAE_Init is complete; otherwise, 

the function calls will return CMAE_ERR_NOINIT. 

const char *CMAE_CartridgeVersion(void); 

CMAE_CartridgeVersion returns a pointer (as a constant) to a nullterminated 

text buffer containing the cartridge version. 

See also “Constants” on page 18. 

CMAE_MicroupdatesVersion 

Description 

Syntax 

Return values 

Returns the version of the last micro-updates file downloaded from 

Cloudmark. 

Call CMAE_MicroupdatesVersion after CMAE_Init is complete; 

otherwise, the function calls will return CMAE_ERR_NOINIT. 

int CMAE_MicroupdatesVersion(void); 

CMAE_MicroupdatesVersion returns the version of the current microupdates 

file via a pointer to an integer. 

See also “Constants” on page 18. 

CMAE_strerror 

Description 

Syntax 

Returns the text description of a CMAE_ERR error code constant 

returned by another function. 

const char *CMAE_strerror(CMAE_ERR Error); 

Parameters • [in] Error 

The CMAE_ERR error code constant returned by any given 

function. 

Return values 

CMAE_strerror returns a pointer (as a constant) to a null-terminated 

text buffer describing the error message in human-readable form 

(instead of a CMAE_ERR error code constant). 

See also “Error Codes” on page 17 

24 CMAE Functions

Chapter 4 

API Reference 

Scoring Functions 

The following functions provide CMAE with the necessary message data 

for facilitating the scoring process: 

CMAE_MsgAnalysisUserData 

Description 

Syntax 

Associates user data acquired by your application with a given 

message. 

Call CMAE_MsgAnalysisUserData before calling another scoring 

function, such as CMAE_ScoreRFC822. 

This function sets the AnalysisUserData field of the callback for the 

current thread and is reset after a scoring function is complete. 

CMAE_ERR CMAE_SetUserData (void 

*AnalysisUserData); 

Parameters • [in] AnalysisUserData 

Opaque user data. 


See also “CMAE_MsgAnalysisCB” on page 22 

CMAE_ScoreRFC822 

Description 

Syntax 

Returns the score generated by CMAE for an RFC822-compliant 

message. 

CMAE_ScoreRFC822 sets ScoreMask to CMAE_SCORE_CONTENT. 

The message envelope is not used by CMAE when calculating its score. 

CMAE_ERR CMAE_ScoreRFC822 (const char 

*RFC822Content, 

double *ScoreOut); 

Parameters • [in] RFC822Content 

An RFC822-compliant message. 

• [out] ScoreOut 

The score returned by CMAE for an RFC822-compliant message. 


See also “CMAE_ScoreRFC822Len” on page 26 

Scoring Functions 25


CMAE_ScoreRFC822Len 

Description 

Syntax 


message of a specified length. 

CMAE_ScoreRFC822Len increases the performance of CMAE by 

allowing your application to specify the length of a message instead of 

requiring CMAE to calculate it before scoring the message. 

CMAE_ERR CMAE_ScoreRFC822 (const char 

*RFC822Content, 

size_t RFC822ContentLength, 


Parameters • [in] RFC822Content 


• [in] RFC822ContentLength 

The length (in bytes) of an RFC822-compliant message. 


The score returned by CMAE. 


See also “CMAE_ScoreRFC822” on page 25 

CMAE_ScoreEnvelopeRFC822 

Description 

Syntax 

Returns the score generated by CMAE using an RFC822-compliant 

message and its envelope. 

CMAE_ERR CMAE_ScoreEnvelopeRFC822(const 

CMAE_Envelope Envelope, 

const char *RFC822Content, 


Parameters • [in] Envelope 

The SMTP envelope of an RFC822-compliant message. 

• [in] RFC822Content 





See also “CMAE_ScoreRFC822” on page 25 

26 Scoring Functions

Chapter 4 

API Reference 

CMAE_ScoreEnvelopeRFC822Len 

Description 


message of a specified length, and its envelope. 

CMAE_ScoreEnvelopeRFC822Len increases the performance of CMAE 

by allowing your application to specify the length of the message and 

its envelope instead of requiring CMAE to calculate it prior to scoring 

the message. 

Syntax CMAE_ERR CMAE_ScoreEnvelopeLenRFC822 ( 

const CMAE_Envelope Envelope, 






• [in] RFC822Content 


• [in] RFC822ContentLength 

The length (in bytes) of an RFC822-compliant message. 




See also • “CMAE_ScoreEnvelopeRFC822” on page 26 

• “CMAE_ScoreRFC822” on page 25 

Envelope Functions 

Envelope functions are located in cmae_envelope.h. Use the envelope 

functions to initialize (and destroy) CMAE_Envelope objects and manage 

configuration properties for them. 

Envelope Functions 27


CMAE_EnvelopeInit 

Description 

Syntax 

Initializes a CMAE_Envelope object. 

The CMAE_Envelope object initialized by this function is used by 

CMAE_ScoreEnvelopeRFC822 for scoring an RFC822-compliant 

message. 

CMAE_EnvelopeInit registers with CMAE_MallocCB to allocate 

memory for the CMAE_Envelope object before initializing it. 

CMAE_ERR CMAE_EnvelopeInit (CMAE_Envelope 

*EnvelopeOut); 

Parameters • [out] EnvelopeOut 

The SMTP envelope as an opaque CMAE_Envelope construct. 


See also • “CMAE_ScoreEnvelopeRFC822Len” on page 27 

• “CMAE_EnvelopeDone” on page 28 

CMAE_EnvelopeDone 

Description 

Syntax 

Releases a CMAE_Envelope object created by CMAE_EnvelopeInit. 

If Envelope is set to null, CMAE returns CMAE_ERR_BADARG. 

Calling CMAE_EnvelopeDone on a CMAE_Envelope object that was 

created by CMAE—and not CMAE_Envelope may cause memory leaks 

in your application. 

The CMAE_EnvelopeDone function should be called after the 

application has finished scoring the message to release the Envelope. 

The Authority Engine does not cache the Envelope pointer so failure to 

call CMAE_EnvelopeDone may result in memory leaks. 

CMAE does not cache envelope pointers and, consequently, cannot 

release CMAE_Envelope objects created byCMAE_EnvelopeInit. Your 

application should cache the CMAE_Envelope pointer for releasing the 

envelope after the message is scored. 

Failure to call CMAE_EnvelopeDone after the message is scored may 

cause memory leaks in your application. In addition, releasing a 

CMAE_Envelope object created by CMAE—instead of by 

CMAE_EnvelopeInit—may also cause memory leaks. 

CMAE_ERR CMAE_EnvelopeDone (CMAE_Envelope 

Envelope); 


The opaque CMAE_Envelope object previously created with 

CMAE_EnvelopeInit. 

28 Envelope Functions

Chapter 4 

API Reference 

CMAE_EnvelopeDone 


See also • “CMAE_ScoreRFC822Len” on page 26 

• “CMAE_ScoreEnvelopeRFC822Len” on page 27 

CMAE_EnvelopeFromHost 

Description 

Syntax 

The CMAE_EnvelopeFromHost function associated the connecting 

host’s name with SMTP envelope information stored in the Envelope 

object. 

The CMAE_Envelope object created by this function is used by 

CMAE_ScoreEnvelopeRFC822 to check the whitelist for the IP address 

of the RFC822-compliant message. 

The validity of the hostname is not evaluated. 

CMAE_ERR CMAE_EnvelopeFromHost 

(CMAE_Envelope Envelope, 

const char *Host); 


The CMAE_Envelope object with which to associate the email 

address. 

• [in] Host 

The hostname of the connecting host. This must be a fullyqualified 

hostname. 

Return values 

If no error occurs, CMAE_EnvelopeFromHost returns a value of 

CMAE_ERR_NONE. If a NULL pointer is passed into the Envelope 

parameter, the function will return CMAE_ERR_BADARG. 

CMAE_EnvelopeFromIP 

Description 

Syntax 

Adds the MailFrom IP address contained in the SMTP envelope to a 

CMAE_Envelope object. 


CMAE_ScoreEnvelopeRFC822 to check the whitelist for the IP address 

of the RFC822-compliant message. 

CMAE_ERR CMAE_EnvelopeFromIP (CMAE_Envelope 

Envelope, 

unsigned long IPAddress); 



CMAE_EnvelopeFromIP 


The SMTP envelope as a CMAE_Envelope object. 

• [in] IPAddress 

The IP address contained in the MailFrom header of the envelope, 

in network byte order. 

If IPAddress is set to null, CMAE returns CMAE_ERR_BADARG. In 

addition, CMAE does not validate IP addresses. 




• “CMAE_EnvelopeRcptTo” on page 31 

CMAE_EnvelopeHelo 

Description 

Syntax 

Adds the HELO domain string contained in the SMTP envelope to a 


If HeloDomain is set to null, CMAE returns CMAE_ERR_BADARG. 


CMAE_ScoreEnvelopeRFC822 to check the whitelist for the Helo 

domain string in the RFC822-compliant message. 

CMAE_ERR CMAE_EnvelopeHelo (CMAE_Envelope 

Envelope, 

const char *HeloDomain); 



• [in] HeloDomain 

The HELO domain string. 






Chapter 4 

API Reference 

CMAE_EnvelopeMailFrom 

Description 

Syntax 

Adds the MailFrom address contained in the SMTP envelope to a 



CMAE_ScoreEnvelopeRFC822 to check the whitelist for the MailFrom 

address of the RFC822-compliant message. 

CMAE_ERR CMAE_EnvelopeMailFrom (CMAE_Envelope 

Envelope, 

const char *EmailAddress); 



• [in] EmailAddress 

The SMTP MailFrom address. 

If EmailAddress is set to null, CMAE returns CMAE_ERR_BADARG. 

In addition, CMAE does not validate MailFrom addresses. 





CMAE_EnvelopeRcptTo 

Description 

Syntax 

Adds the RcptTo address contained in the SMTP envelope to a 


The MailFrom address added to the CMAE_Envelope object by this 

function is used by CMAE_ScoreEnvelopeRFC822 for scoring an 

RFC822-compliant message. 

Your application must call CMAE_EnvelopeRcptTo once for each 

recipient. 

CMAE_ERR CMAE_EnvelopeRcptTo (CMAE_Envelope 

Envelope, 

const char *EmailAddress); 



• [in] EmailAddress 

The SMTP RcptTo address. 

If EmailAddress is set to null, CMAE returns CMAE_ERR_BADARG. 

In addition, CMAE does not validate the address. 



CMAE_EnvelopeRcptTo 




• “CMAE_EnvelopeFromIP” on page 29 

CMAE_EnvelopeGetFromHost 

Description 

Syntax 

The CMAE_EnvelopeGetFromHost function is an accessor for 

obtaining the hostname in the CMAE_Envelope object. 

This function returns the hostname contained in the Envelope. If there 

is no hostname associated with the Envelope, then the returned value 

is NULL. 

CMAE_ERR CMAE_EnvelopeGetFromHost 

(const CMAE_Envelope Envelope, 

const char **HostOut); 


The CMAE_Envelope object of interest. 

• [out] HostOut 

The hostname previously stored in the Envelope. This must be a 

fully-qualified hostname. 

Return values 

If no error occurs, CMAE_EnvelopeGetFromHost returns a value of 

CMAE_ERR_NONE. If a NULL pointer is passed into the Envelope 

parameter, the function will return CMAE_ERR_BADARG. If a NULL 

pointer is passed into the IPAddressOut parameter, the function will 

return CMAE_ERR_BADARG. 

CMAE_EnvelopeGetFromIP 

Description 

Syntax 

Gets the IP address from a CMAE_Envelope object created by 


If there is no IP address in the CMAE_Envelope object, the IPAddress 

parameter returns zero. 

CMAE_ERR CMAE_EnvelopeGetFromIP 


unsigned long *IPAddressOut); 


Chapter 4 

API Reference 

CMAE_EnvelopeGetFromIP 


The envelope as a CMAE_Envelope object. 

• [out] IPAddress 

The MailFrom IP address contained in the CMAE_Envelope object, 

in network byte order. 

CMAE does not validate the MailFrom IP addresses. 


CMAE_EnvelopeGetHelo_Config 

Description 

Syntax 

Gets the HELO domain string from a CMAE_Envelope object created 

by CMAE_EnvelopeInit. 

If there is no HELO domain string in the CMAE_Envelope object, the 

HeloDomainOut parameter returns null. 

CMAE_ERR CMAE_EnvelopeGetHelo (CMAE_Envelope 

Envelope, 

const char **HeloDomainOut); 



• [out] HeloDomainOut 

The Helo domain string contained in the CMAE_Envelope object. 

Your application should not free the HeloDomainOut parameter; it 

is freed when the CMAE_Envelope object is released. 


CMAE_EnvelopeGetMailFrom 

Description 

Gets the MailFrom address from a CMAE_Envelope object created by 


If there is no MailFrom address in the CMAE_Envelope object, the 

IPAddress parameter returns null. 

Syntax CMAE_ERR CMAE_EnvelopeGetMailFrom ( 


const char **EmailAddressOut); 



• [out] EmailAddressOut 

The MailFrom address contained in the CMAE_Envelope object. 




CMAE_EnvelopeGetRcptToSize 

Description 

Syntax 

Gets the number of RcptTo addresses in an envelope. 

If there are no RcptTo addresses contained in the CMAE_Envelope 

object, then the SizeOut parameter returns zero. 

CMAE_ERR CMAE_EnvelopeGetRcptToSize 


unsigned *SizeOut); 



• [out] SizeOut 

The number of RcptTo addresses in the envelope. 


CMAE_EnvelopeGetRcptTo 

Description 

Syntax 

Gets the RcptTo address from a CMAE_Envelope object with the 

specified index. 

Index numbers are for RcptTo addresses are generated in 

monotonically increasing order, starting at zero and ending at the 

value of the SizeOut parameter of CMAE_EnvelopeGetRcptToSize, 

minus 1. 

If there are no RcptTo addresses contained in the CMAE_Envelope 

object, then the EmailAddressOut parameter returns null. 

CMAE_ERR CMAE_EnvelopeGetRcptTo 


unsigned Index, 

const char **EmailAddressOut); 



If Envelope is set to null, CMAE returns CMAE_ERR_BADARG. 

• [in] Index 

The index of the RcptTo address in the CMAE_Envelope object. 

• [out] EmailAddressOut 

The RcptTo address. 

Your application should not free the EmailAddressOut parameter; 

it is freed when the CMAE_Envelope object is released. 



The CMAE SDK Client and 

Daemon 

CHAPTER 

5 

In some cases, the message processing model may not lend itself to direct 

communication with the resource-intensive CMAE. To facilitate quick 

spam score queries without compromising performance, the CMAE SDK 

now includes a lightweight client program with a corresponding message 

scoring daemon and C API. 

The following components are included: 

• the CMAE daemon 

The daemon listens in the background for client requests. 

• the CMAE client C library 

You can use these functions to add the client functionality to your own 

programs. 

• a CMAE client binary 

This simple program is suitable for production. It retrieves a spam 

confidence score for any single message. 


By default, cmae_server listens in the background for spam score queries 

from the client. You can start it with the following options: 

Table 1 

cmae_server runtime arguments 

Option Description 

-h Print help and exit. 

-d Debug mode. Stay in the foreground and log to stderr. 

35


Table 1 

cmae_server runtime arguments 

-v Print the version number. 

-c Read the server configuration from the specified file. Default: 

$CMAE_CS_CONFIG 

! Make sure that libcmae.so is in the daemon’s $LD_LIBRARY_PATH. 

If the -c option is not specified, the server runs with the default 

configuration. You can configure the server and the client to share the 

same configuration file. Each will ignore the directives that pertain to the 

other. The cmae_server recognizes the following configuration directives: 

Table 2 

cmae_server configuration directives 

Directive Description Default 

address IP address or hostname on which to listen all 

port Port number on which to listen 2703 

workers Number of worker threads 4 

max clients 

max message size 

idle timeout 

Maximum number of simultaneous client 

connections 

Maximum size, in bytes, of message to accept 

from the client 

Number of seconds of inactivity, after which 

the server disconnects from the client 

0 (no limit) 

0 (no limit) 

0 (no timeout) 

server log priority Minimum event priority to log NOTICE 

server log file Filename of the server log none (log to syslog) 

server syslog facility Syslog facility daemon 

cartridge code dir Cartridge code directory . 

cartridge config dir Cartridge configuration directory . 

max inspect header 

max inspect body 

Maximum bytes of the header to examine; this 

directive is deprecated 

Maximum bytes of the body to examine; this 

directive is deprecated 

65536 

256000 

36 The CMAE daemon

Chapter 5 

The CMAE SDK Client and Daemon 

The CMAE client library 

The client’s C interface is available by linking to libcmaeclient.so and its 

header file, cmae_client.h. The general steps for using the CMAE client 

library are as follows: 

1. Start the CMAE server. 

2. Call CMAE_Client_Open() once to establish a connection to the 

daemon. 

3. For each message to be scored, call one of the following functions: 

CMAE_Client_ScoreRFC822() 

CMAE_Client_ScoreRFC822Len() 

CMAE_Client_ScoreEnvelopeRFC822() 

CMAE_Client_ScoreEnvelopeRFC822Len() 

4. When you are finished collecting the scores, call CMAE_Client_Close() 

once to close the connection. 

This procedure is sufficiently lightweight to be performed once per 

message, even if your mail volume is high. 

! The CMAE library and the CMAE client library are mutually exclusive. 

The results of linking both libraries into the same application are 

undefined. 

CMAE_Client_Default_Port 

Description 

Syntax 

Parameters 

The default port on which the daemon listens, in host byte order. This 

is currently port 2703. Because the default port can change in future 

releases, Cloudmark recommends setting a port number of your own 

choice. 

None. 

unsigned short 

CMAE_Client_Default_Port(void); 

The CMAE client library 37


CMAE_Client_Open 

Description 

Syntax 

This function sets up a client connection to the daemon. 

Be sure to clear errno before calling this function, and check errno 

after any failure. Many failures are the result of failed system calls. 

CMAE_ERR CMAE_Client_Open 

(CMAE_Client_Session *SessionOut, 

const char *ServerName, 

unsigned long ServerIPAddr, 

unsigned short ServerPort 

unsigned ConnectTimeout); 

Parameters • [in]ServerName 

The specified ServerName, if any, can be either a hostname or an 

IP address in network byte order. 

• [in]ServerIPAddr 

If no ServerName is specified, then ServerIPAddr must be an IP 

address in network byte order. 

• [in]ServerPort 

Specify the server port in host byte order. If ServerPort is set to 

zero, then the client uses the default port in 

CMAE_Client_Default_Port(). 

• [in]ConnectTimeout 

The time, in seconds, after which this connection expires. Specify 

zero (0) to use the system default TCP timeout. 

• [out]SessionOut 

A session identifier. 

Return values 

On success, this function returns a value of CMAE_ERR_NONE and 

sets *SessionOut to a CMAE_Client_Session value; otherwise, it 

returns a negative error code. See “Error Codes” on page 17. 

CMAE_Client_ScoreRFC822 

Description 

Syntax 

This function retrieves a spam score for an RFC822-compliant 

message. 

CMAE_ERR 

CMAE_Client_ScoreRFC822(CMAE_Client_Session 

Session, 



38 The CMAE client library

Chapter 5 


CMAE_Client_ScoreRFC822 

Parameters • [in]Session 

The session identifier returned by CMAE_Client_Open. 

• [in]RFC822Content 


• [out]ScoreOut 

The spam score for the specified message. 

Return values 


sets *ScoreOut to a score from 0 to 100, where 0 means the message 

is certainly legitimate and 100 means it is certainly spam. Otherwise, it 


CMAE_Client_ScoreRFC822Len 

Description 

Syntax 

This function retrieves a spam score for an RFC822-compliant message 

of a specified length. 

CMAE_ERR CMAE_Client_ScoreRFC822Len 

(CMAE_Client_Session Session, 




Parameters • [in]CMAE_Client_Session 




• [in]RFC822ContentLength 

The length, in bytes, of the specified message. 



Return values 





CMAE_Client_ScoreEnvelopeRFC822 

Description 

Syntax 


and its envelope. 

CMAE_ERR CMAE_Client_ScoreEnvelopeRFC822 







CMAE_Client_ScoreEnvelopeRFC822 

Parameters • [in]CMAE_Client_Session 


• [in]Envelope 






Return values 





CMAE_Client_ScoreEnvelopeRFC822Len 

Description 

Syntax 


of a specified length, and its envelope. 

CMAE_ERR CMAE_Client_ScoreEnvelopeRFC822Len 








• [in]Envelope 

The SMTP envelope of the specified message. 



• [in]RFC822ContentLength 

The length, in bytes, of the specified message. 



Return values 





40 The CMAE client library

Chapter 5 


CMAE_Client_GetProtocolTimeout 

Description 

Syntax 

This gets the value of the protocol timeout. The default is zero (no 

timeout). 

CMAE_ERR CMAE_Client_GetProtocolTimeout 


unsigned *ProtocolTimeout); 

Parameters • [out]ProtocolTimeout 

The timeout, in seconds, for protocol send/receive. 

Return values 

On success, this function returns zero. On failure, it returns a negative 

error code. See “Error Codes” on page 17. 

CMAE_Client_SetProtocolTimeout 

Description 

Syntax 

This sets the value of the protocol timeout. The default is zero (no 

timeout). Generally, you do not need to set a timeout unless you wish 

to quickly detect a possible failure of the network or the server. 

CMAE_ERR CMAE_Client_SetProtocolTimeout 


unsigned ProtocolTimeout); 

Parameters • [in]ProtocolTimeout 

The timeout, in seconds, for protocol send/receive. 

Return values 

On success, this function returns zero. On failure, it returns a negative 

error code. See “Error Codes” on page 17. 

CMAE_Client_Close 

Description 

Syntax 

This function closes a client connection to the daemon. 

Once a session has been closed with this function, its session identifier 

cannot be re-used. 

CMAE_ERR 

CMAE_Client_Close(CMAE_Client_Session 

Session); 


The session identifier of the session to close. 

Return values 

On success, this function returns a value of CMAE_ERR_NONE; 

otherwise, it returns a negative error code. See “Error Codes” on 

page 17. 



The CMAE client binary 

The client binary, cmae_client, is provided for scripting and testing 

purposes. It reads an RFC822 message from standard input or from a file, 

then returns a spam confidence score obtained from the CMAE daemon. 

You can invoke it like this: 

cmae_client [-d] [-c ] [-[INHFT] ] [] 

Table 3 

cmae_client runtime arguments 

Argument Description Default 

-h print help and exit 

-v version 

-t exit with status of 6 if spam confidence 

reaches configured threshold 

print spam confidence 

-d debug: log to stderr 

-c read configuration from $CMAE_CS_CONFIG 

-I IP address of sending host localhost 

-N Name of sending host (reverse DNS of IP) 

-H HELO string 

-F Sender email address 

-T Recipient email address--multiple -T is OK 

file containing an RFC822 message stdin 

The following exit codes may be returned: 

Table 4 

cmae_client exit codes 

Exit code 

Description 

0 Success 

6 When the -t runtime argument is specified, this exit code indicates that the 

message is spam. 

64 Command line usage error; check Table 3 above 

66 Cannot open the email message 

69 The CMAE server is unreachable on the specified host and port 

70 Internal error 

71 System error 

76 Remote error in protocol; the CMAE server was reached, but the attempt to 

obtain a score failed 

42 The CMAE client binary

Chapter 5 


If the -c option is not specified, the client runs with the default 

configuration values. You can configure the server and the client to share 

the same configuration file. Each will ignore the directives that pertain to 

the other. The client-specific configuration directives are as follows: 

Table 5 

cmae_client configuration directives 

Directive Description Default 

address IP address or hostname to listen on all 

port port to listen on 2703 

client log priority minimum event priority to log NOTICE 

client log file log file none (log to syslog) 

client syslog facility syslog facility user 

client protocol timeout network send/receive timeout none 

threshold spam confidence threshold for -t option 96 

The CMAE client binary 43


44 The CMAE client binary

Sample Code 

APPENDIX 

A 

The program listed here (example.c) shows the minimum amount of 

coding required to score messages with CMAE. The example.c file is 

located in the example directory of the CMAE SDK. 

/* 

* 

* C:\>c:\example.exe spam.txt 

* Score: 99.999997 

* 

*/ 

#include 

#include 

#ifdef _WIN32 

#include 

#define ETCDIR ".\\etc" 

#define LIBDIR ".\\lib" 

#else 

#include 

#define ETCDIR "./etc" 

#define LIBDIR "./lib" 

#endif 

/* Include Cloudmark Authority Engine */ 

#include "cmae.h" 

/* Logging callback function */ 

void LogCB(CMAE_LOG MsgLevel, const char *Facility, const char 

*ASCIIMsg) 

{ 

printf("%d:%s: %s\n", MsgLevel, Facility ? Facility : "", ASCIIMsg ? ASCIIMsg : ""); 

} 

/* MSG Analysis CB */ 

void MsgAnalysisCB(const char *ASCIIMsg, void *UserData) 

{ 

45

Cloudmark Desktop User’s Guide 

Appendix A 

} 

printf("(%p) %s\n", UserData, ASCIIMsg); 

/* Main */ 

int main(int argc, char *argv[]) 

{ 

CMAE_Config config; 

char mail[65536]; 

double score; 

CMAE_ERR ret; 

size_t readlen; 

const char *cv; 

FILE *mailfile; 

if (argc != 2) { 

fprintf(stderr, "usage: %s \n", argv[0]); 

return 1; 

} 

/* Initialize engine */ 

CMAE_LogCB(LogCB); 

CMAE_MsgAnalysisCB(MsgAnalysisCB); 

config.MaxInspectHeaderSize = 65536; 

config.MaxInspectBodySize = 32767; 

config.UseMsgAnalysis = 1; 

if ((ret = CMAE_Init(CMAE_INTERFACE_VERSION_1, &config, 

LIBDIR, ETCDIR)) != 0) 

{ 

fprintf(stderr, "init error: %s\n", CMAE_strerror(ret)); 

return 1; 

} 

/* CMAE_CartrdigeVersion may be NULL if CMAE_Init returned 

error */ 

cv = CMAE_CartridgeVersion(); 

printf("Cartridge version : %s\n", cv?cv:"(null)"); 

printf("Microupdates version: %d\n", 

CMAE_MicroupdatesVersion()); 

/* Read the email from the provided file */ 

if ((mailfile=fopen(argv[1], "r")) == NULL) { 

fprintf(stderr, "Could not open file %s\n", argv[1]); 

return 1; 

} 

46

Appendix A 

Sample Code 

if ((readlen = fread(mail, 1, sizeof(mail)-1, mailfile))

Cloudmark Desktop User’s Guide 

Appendix A 

48

Index 

INDEX 

A 

ANSI C 15 

C 

callbacks 19 

cartridge 4, 5, 8, 10, 13, 23, 24, 36 

client 35, 37 

Cloudmark Collaborative Security 

Network 11 

cmae.dll 3 

cmae.h 3, 5, 8, 9, 15 

cmae.lib 4 

CMAE_CartridgeVersion 24 

cmae_client 5, 8, 10 

cmae_client.h 5, 8, 10, 37 

CMAE_Client_GetProtocolTimeout 4 

1 

CMAE_Client_Open 37 

CMAE_Client_SetProtocolTimeout 4 

1 

CMAE_Config 18, 23 

CMAE_Configure 23 

CMAE_Envelope 15, 19, 27 

cmae_envelope.h 5, 8, 9 

CMAE_EnvelopeDone 28 

CMAE_EnvelopeFromHost 29 

CMAE_EnvelopeFromIP 29 

CMAE_EnvelopeGetFromHost 32 

CMAE_EnvelopeGetFromIP 32 

CMAE_EnvelopeGetHelo_Config 33 

CMAE_EnvelopeGetMailFrom 33 

CMAE_EnvelopeGetRcptTo 34 

CMAE_EnvelopeGetRcptToSize 34 

CMAE_EnvelopeHelo 30 

CMAE_EnvelopeInit 28, 32 

CMAE_EnvelopeMailFrom 31 

CMAE_EnvelopeRcptTo 31 

CMAE_ERR_BADARG 17, 28, 29, 

30, 32 

CMAE_ERR_BADFILE 17 

CMAE_ERR_ENGINE 17 

CMAE_ERR_MALLOC 17 

CMAE_ERR_NOFILE 17 

CMAE_ERR_NOINIT 17, 22, 24 

CMAE_ERR_NONE 17, 29, 32 

CMAE_ERR_STATE 17 

cmae_error.h 5, 8, 9 

CMAE_FreeCB 21 

CMAE_Init 18, 22, 24 

CMAE_INTERFACE_VERSION_1 1 

8, 23 

CMAE_InterfaceVersion 18 

CMAE_LogCB 20 

CMAE_MallocCB 21, 28 

CMAE_MicroupdatesVersion 24 

CMAE_MsgAnalysisCB 22 

CMAE_MsgAnalysisUserData 25 

cmae_port.h 5, 8, 9 

CMAE_ScoreEnvelopeRFC822 12, 

15, 26, 28, 29, 31 

CMAE_ScoreEnvelopeRFC822Len 27 

CMAE_ScoreRFC822 12, 25 

CMAE_ScoreRFC822Len 26 

cmae_server 5, 8, 10, 35 

CMAE_Shutdown 23 

CMAE_strerror 24 

CMAE_Version 18 

configuration 42, 43 

constants 18 

49

Index 

D 

daemon 14, 35 

debug mode 35 

logging 36 

debug mode 35 

E 

engtest 5, 8, 10 

engtest.exe 4 

envelope functions 27 

error codes 17 

example.c 4, 5, 8, 9, 45 

example.sln 4 

example.vcproj 4 

G 

gcc 5, 6, 7, 8 

L 

ld-linux.so.2 6 

libaio.so.1 9 

libc.so.1 9 

libc.so.6 6 

libc_r.so.4 10 

libcmae.so 5, 8, 9 

libcmaeclient.so 5, 8, 10, 37 

libdl.so.1 9 

libdl.so.2 6 

libgcc_s.so.1 6 

libm.so.1 9, 10 

libm.so.6 6 

libmp.so.2 9 

libnsl.so.1 9 

libpthread.so.0 6 

libpthread.so.1 8 

libresolv.so.2 9 

librt.so.1 9 

libsocket.so.1 9 

libstdc++.so.2.10.0 9 

libstdc++.so.5 6 

libstdc++-libc6.2-2.so.3 6 

libthread.so.1 9 

libz.so 8 

libz.so.1 6 

Linux 4 

logging 20, 35, 36 

M 

memory leaks 28 

memory management 16, 21 

messages 

applying actions to 13 

classifying 13 

scoring 12, 15, 25, 35 

Microsoft Visual Studio 3 

Microsoft Windows 3 

micro-updates 11, 14, 24 

msvcp71.dll 4 

msvcr71.dll 4 

O 

object management 16 

P 

performance 26, 27 

R 

Red Hat Enterprise Linux 4 

Redhat Desktop 4 

re-scanning messages 12 

S 

Solaris 7 

spam 11 

filtering 12 

score 11, 12 

structures 18 

synchronization 16 

T 

threading 16 

Trust Evaluation System 11 

U 

UltraSPARC 7 

50

Index 

W 

whitelist 29, 30 

51

Index 

52

Cloudmark Authority Engine

You also want an ePaper? Increase the reach of your titles

Delete template?

Save as template?