3
SMTP Scanner Interface APIs

This chapter describes the Oracle Email SMTP scanner interface APIs that can be used to create customized clients, integrate applications, and support certain extensions.

This chapter contains the following topics:

• Overview
• Format and Entry
• Scanner Interface APIs
• Callback Routine Descriptions

Overview

SMTP server can be integrated with custom procedures for filtering and scanning. These procedures are implemented as C language functions and linked with the server. Each filter or scanner must implement a set of functions that the server calls at different stages of processing. Within each scanner, there is a set of callback functions that can be called to retrieve message headers and data.

Format and Entry

Format and typical entry in the LDAP server parameter specifying the list of scanner interfaces:

shared-library-path, when-to-call, [internal | host:port], function set:   
(initialization, register callback, scan  message, send, receive, 
close),scanner_flags,system_flags

where:

• shared-library-path is the full path of the C shared library. This is loaded by the server at startup.
• when-to-call is the point at which the C-interface should be called. The possible values are:
  • ENV - After receiving the message envelope
  • DATA - After receiving the complete message and before local delivery
  • RELAY - Just before relaying a message
  • NEVER - Essentially disables using the interface
• host and port specify the host and port at which a virus scanner maybe listening for input.
• Internal is used for scanners that do not talk to any external entity for filtering.
• scanner_flag any flags the scanner needs to pass to the initialization function.
• system_flags are the MTA defined flags. Curently the only value defined is repairmsg=0/1. If set to 0, and the message is damaged it is discarded by the scanner interface. If set to True, the message is repaired. If set to False, the MTA behaviour is same as failure for damaged messages.

Example

/work/orahome/lib/libsym.so,DATA,host9999:6000,(essym_init,essym_registercb,    
essym_scanmsg, essym_send, essym_recv, essym_close),0, repair_msg=1

Scanner Interface APIs

The following functions must be implemented by each scanner:

• vgctx: Virus scanner interface global context. This is the global context that is initialized and managed by the scanner APIs. It is passed to each scanner interface call.
• vlctx: Virus scanner interface local context for each message. This is initialized and used for each message.
• smtplctx: SMTP server local context. This is for internal use by the server.
• msgin: Buffer containing the message, unused in the current release.

Initialization()

Parameters: void **vgctx, char *host, sb4 port, char *system_flags, char *scanner_flags

Retcode: int

Description:

This is called once during the lifetime of by the server at startup, once during the lifetime of the process. Perform scanner initialzation with minimal step of creating a global context for scanner use (return pointer a void in vgctx for subsequent use by the framework.

• Store host and port, and optionally establish connections to virus scanner for future use.
• If the system_flags parameter is set to repairmsg=1, then repair message is turned on
• Scanner_flags are the flags set in the scanner definition

register_callback()

Parameters: void *vgctx, int (*cb)(void*, void*,void*), unsigned int flags)

Retcode: int

Description:

The server provides a set of functions that the scanner can call to get message information. The function names of these are not predefined but are passed by the server to this function. After the call to initialization(), the server calls this for each of sever functions available to get message data. Store call back routine cb for later use in scan message.

The flags parameter specifies the kind of callback with following values:

• 0: Retrieve and Send Message
• 1: Receive and Store Message
• 2: Fetch Envelope
• 3: Get Message size
• 4: Get Message Id
• 5: Free memory
• 6: Set Scanner Version definition

scan_message()

Parameters: (void *vgctx, void *smtplctx, char *msgin, char *errmsg)

Retcode: int

Description:

• The server for each message calls this. Perform steps needed to scan message and retrieve results from virus scanner. Use callbacks to retrieve-send and receive-store message headers and body.
• msgin is used to pass the entire message in memory so that callback for retrieve-send cannot be used to fetch messages from the mail store.
• For errors, errmsg should be populated with description of error. errmsg buffer allocated in the server of size 512 bytes.

Return Value:

• 0 (successful)
• 1 (failure)
• 2 (repaired)
• 3, <0 (errors)

send()

Parameters: (void *vlctx, char *buf, int buflen)

Retcode: int

Description:

• The scanner should call the callback retrieve and send message for getting the message body. Internally this callback calls this Send() function multiple times to provide the message to the scanner.
• Buflen is the length of the buffer buf.
• Return: < 0 errors in sending.

recv()

Parameters: (void *vlctx, char *buf, int *buflen)

Retcode: int

Description:

• The scanner should call receive and store message callback for passing any changed message back to the scanner. The callback internally call recv() function to fetch the message data.
• Buflen is the number of bytes the scanner recv() should put in the buffer buf. If fewer than *buflen bytes received due to EOF, update buflen with the actual number of bytes.
• Return: <0 errors in receiving

close()

Parameters: (void *vgctx);

Retcode: void

Description: This is called once at server exit. Perform any cleanup necessary, such as close connections, and free memory.

Callback Routine Descriptions

These functions are available to retrieve message data. The signature of all callbacks is generic. For example, int (*cb) (void *, void *, void *). The parameter value types are given below for each call back.

Send Message

Fetches the message for the scanner.

Parameters: (void *vgctx, void *vlctx, void *smtplctx)

Receive Message

Reads the changed message from the scanner.

Parameters: (void *vgctx, void *vlctx, void *smtplctx)

Get Envelope

Gets the message envelope.

Parameters: (void *vgctx, void *output, void *smtplctx)

where:

output is of type char ** (memory allocated in framework) with the envelope information in the format host=hostname|mailfrom=sender info|rcptto=(rcpt1,rcpt2,...).

Get Message Size

Retrieves the message size.

Parameters: (void *vgctx, void *output, void *smtplctx)

where output is pointer to integer with the result containing the message size.

Free Memory

Frees the output parameter of the Get Envelope callback.

Parameters: (void *vgctx, void *input, void *smtplctx)

where:

input is the pointer to the buffer to be freed. This buffer must have been allocated earlier by the framework.

Set Version Definition

Sets the version of the scanner which was used to scan the message.

Parameters: (void *vgctx, void *input, void *smtplctx)

where:

input is a string containing version definition string for virus scanner. This routine should be called by the scanner API if the version definition information is available from virus scanner.