V'0);2Message Exchange Programmer's Guide;

Message Exchange Programmer's Guide





+

February, 2001



@This manual describes how to customize Message Exchange through programming.

.Revision/Update Information: This is a revised manual.

.Operating System and Version:VAX/VMS V5.5 or later

OpenVMS Alpha V6.2 or later

"Software Version:Message Exchange V5.2


25 February 2001

EThe information in this document is subject to change without notice Aand should not be construed as a commitment by MadGoat Software. CMadGoat Software assumes no responsibility for any errors that may appear in this document.

<No part of this publication may be reproduced, transmitted, Btranscribed, stored in a retrieval system, or translated into any Glanguage or computer language, in any form or by any means electronic, Hmechanical, magnetic, optical, chemical, or otherwise without the prior 'written permission of MadGoat Software.

CUse of this software and documentation is subject to the terms and .conditions set forth in the License Agreement.

AThe Licensed Materials are provided with RESTRICTED RIGHTS. Use, Hduplication, or disclosure by the Government is subject to restrictions Has set forth in subparagraph (c)(1)(ii) of the Rights in Technical Data <and Computer Software clause at DFARS §252.227-7013 or 8subparagraphs (c)(1) and (2) of the Commercial Computer FSoftware---Restricted Rights at 48 CFR §52.227-19, as applicable.

EMadGoat, Message Exchange, and MX are trademarks of MadGoat Software.

>The following are trademarks of Digital Equipment Corporation:               
DEC DECnet P.S.I.
ULTRIX VAX  VAXcluster
VMS AXP  VMScluster


CMultiNet and TCPware are registered trademarks of Process Software Corporation.

;LISTSERV is a registered trademark of L-Soft International.

AWIN/TCP and Pathway are registered trademarks of Attachmate, Inc.

Copyright ©2001



 ,  
GContents
 


$

Preface



HMessage Exchange (MX) provides two forms of customization: an interface Gfor a site-specific transport, and interfaces for modifying addresses. EThis manual describes how to write routines or programs to use these interfaces for customizing MX.

4

Intended Audience



DThis manual is intended for systems programmers who will be writing code to customize MX.5

Document Structure



%This guide consists of four chapters.

EExample code for all of these interfaces is provided in the Examples subset of the installation kit.4

Related Documents



?You can find additional information in the following documents:

 


J

Chapter 1
The SITE Transport Interface




AMX provides delivery agents and message entry agents for various Ftransports, including TCP/IP, and UUCP. If your site has some network Dtransport that is not supported by MX, you can interface it with MX %through the SITE transport interface.\

1.1 The SITE Delivery Interface



CWhen you use the MCP DEFINE PATH command to route mail to the SITE Hpath, the MX_SITE delivery agent takes messages routed to that path and Hfeeds them into a subprocess that executes a command procedure you must Fprovide. The command procedure must be called MX_EXE:SITE_DELIVER.COM and must accept four parameters.

HThe first parameter is the "route" parameter, which is either Gthe host name part of the address or the value of the /ROUTE qualifier Afrom the DEFINE PATH command that routed the message to the SITE Hdelivery agent. This parameter can be used to distinguish among several 3installed site-specific delivery agents, if needed.

GThe second parameter is the name of a temporary file that contains the Hmessage, including all of the RFC822 headers (corresponding to the DATA Apart of an SMTP transaction). The third parameter is the name of >another temporary file that contains the recipient's address, Ccorresponding to the RCPT TO addresses of an SMTP transaction. The @fourth parameter is the RFC822 address of the originator of the Gmessage, corresponding to the MAIL FROM address of an SMTP transaction.

GYour delivery procedure and the programs it invokes must not cause the Esubprocess to terminate, nor should they rely on specifics about the Gfilenames provided. The procedure MUST exit with a success status code Eto let MX know that the message was delivered successfully. If there Hwas an error in the delivery and you wish MX to return an error message Fto the sender, you should exit with a non-success status code. If the Hseverity of the status is SEVERE (also called FATAL), the SITE delivery Aagent will return an error message to the sender. Otherwise, the Emessage will be queued for another attempt. The MCP SET SITE command Hcontrols how many attempts will be made before the delivery agent gives <up; the default is 96, with 30 minutes between each attempt.

 F  
Example 1-1 Sample SITE_DELIVER.COM
 

"
L$! Simple SITE_DELIVER.COM which invokes a real program to do all the work. K$! This file must be placed in MX_EXE: for use with the MX SITE interface. "$! It is invoked by MX_SITE with: $! L$!  @MX_EXE:SITE_DELIVER  route msg-file-spec dest-file-spec origin-address $! B$! The originator address is stuck in a file since it can contain J$! characters that might confuse DCL when we invoke the delivery program. $! G$! This is a simple procedure which ignores the "route" parameter.  If N$! you have multiple SITE delivery paths available, use the "route" parameter =$! to route the message to the appropriate delivery program. $! $ SET NOON $! ,$ DELIVER = "$my_mail_system:enter_message" $!  $ CREATE my_temp_dir:SENDER.TMP )$ OPEN/APPEND TMP my_temp_dir:SENDER.TMP $ WRITE TMP P4 $ CLOSE TMP $! )$ DELIVER 'P2 'P3 my_temp_dir:SENDER.TMP $ STAT = $STATUS "$ DELETE my_temp_dir:SENDER.TMP;* 
$ EXIT 'STAT 


 S

1.2 SITE Message Entry



EThe SITE message entry program should be used by your SITE transport Cagent to enter a message into the MX message queue. The program is Gcalled MX_SITE_IN and resides in MX_EXE. It should be invoked as a DCL foreign command:

 

"
"$ MX_ENTER = "$MX_EXE:MX_SITE_IN" <$ MX_ENTER  msg-file-spec  dest-file-spec  [origin-address] 




EMX_SITE_IN takes up to three parameters, which correspond exactly to Hthe last three parameters passed out by the MX_SITE delivery agent. The :first parameter should be the name of a file containing a Fproperly-formatted RFC822 message. The second parameter should be the Fname of a file containing a list of RFC822 route addresses (they must Fhave the surrounding angle brackets, just as in an SMTP transaction). CThe third parameter, which is optional, should be the RFC822 route Gaddress of the sender (also including the surrounding angle brackets). GIf the third parameter is omitted, the address of the user running the 2program will be used as the origin of the message.


L

Chapter 2
Address Modification Interface




?MX provides an interface for altering envelope addresses. This Ainterface allows you to add your own routines for performing two ;different types of address modifications. For each type of Fmodification, the routines must be part of a shareable library, which >gets mapped into the appropriate parts of MX at run-time with LIB$FIND_IMAGE_SYMBOL.

AThe address modification routines are located through the use of logical names. ' ,              
Logical name Modification type
 MX_SITE_ADDRESS_REWRITER M Modifying headers and envelope addresses for outgoing and incoming mail
 MX_SITE_DOM_EXPANSION ' Modifying or expanding host names
 MX_SITE_NAME_CONVERSION ? Translating local aliases or performing directory lookups


EIn each case, the logical name must be defined /SYSTEM/EXEC and must Ftranslate to the name of an image that has been linked /SHARE/NOTRACE >and INSTALLed on the system. If you name the shareable images EADDRESS_REWRITER.EXE, DOMAIN_EXPANSION.EXE, and NAME_CONVERSION.EXE, Drespectively, and place them in the MX_ROOT:[EXE] directory, the MX Bstartup procedure will automatically create the logical names and %INSTALL the shareable images for you.

GExamples of routines for performing address modifications are included Din the directory MX_ROOT:[EXAMPLES] (if they have been installed). R

2.1 Address Rewriting



GThe site address rewriter routines are called by the Router process to Fallow RFC822 header address rewrites on all outgoing mail, regardless Eof its origin, and on envelope addresses for incoming mail. The main Cpurpose for these routines is to allow site-specific user and host naming conventions.

wThe name conversion routines, described in Section 2.3, provide a means Dfor implementing user aliases, but it does not affect domain names. FWith the address rewriter routines, both usernames and host names can Bbe modified. To ease mail delivery, many sites prefer to hide the Hvarious machines used at that site by supplying a generic site name for Gthe address. For example, the generic domain MADGOAT.COM might be used @for all addresses, even though the machines in use may be named (HUNTER.MADGOAT.COM and MATT.MADGOAT.COM.

GSample address rewriter modules are provided in the Examples subset of the installation kit.

HThe routines that must be provided by an address rewriter are described on the following pages.!


?

INIT



Initialization routine.



Format



INIT context




RETURNS

                
 VMS usage:  cond_value
type:  longword (unsigned)
access:  write only
 mechanism:  by value


EThe INIT routine must return a success status value in order for the ,other address rewriting routines to be used.




ARGUMENTS



context


                
 VMS usage: context
type:  longword (unsigned)
access: modify
 mechanism:  by reference

HThis is a longword passed by reference to your routine that you may use Bfor any purpose, such as allocating a block of memory for keeping contextual information.



DESCRIPTION

=This routine is called by the Router before any calls to the GREWRITE_HEADER and REWRITE_ENVELOPE routines. You may use this routine Bto set up any context or perform any housekeeping tasks needed to ;prepare for the subsequent calls to the REWRITE_* routines.

ASince your routines must be reentrant, you should not use static Cstorage for keeping track of state information or other contextual Hinformation. Instead, you should allocate a block of dynamic memory and /return its address in context.

"
I

REWRITE_HEADER



2Routine to rewrite an address in an RFC822 header.



Format

>

REWRITE_HEADER context, inaddr, outaddr, header_code




RETURNS

                
 VMS usage:  cond_value
type:  longword (unsigned)
access:  write only
 mechanism:  by value


BTo indicate a successful rewrite, return SS$_NORMAL or some other Esuccess status code. If you do not return a success status code, the 2caller will assume that the rewrite did not occur.




ARGUMENTS



context


                
 VMS usage: context
type:  longword (unsigned)
access: modify
 mechanism:  by reference

;This is the same value that was passed to the INIT routine.

inaddr


                
 VMS usage:  char_string
type:  character string
access:  read only
 mechanism: " by descriptor (fixed-length)

*The RFC822 header address to be rewritten.

outaddr


                
 VMS usage:  char_string
type:  character string
access:  write only
 mechanism:  by descriptor

GA string into which your routine should copy the rewritten address, if Fexpansion was successful. You must use the STR$ string routines (such 6as STR$COPY_DX) to copy the string into this argument.

header_code


                
 VMS usage:
type:  longword (unsigned)
access:  read only
 mechanism:  by value

>A value representing one of the following RFC822 header types: & (                                                              
Description Symbolic name Value
From:  MX_K_HDR_FROM  1
Sender:  MX_K_HDR_SENDER  2
To:  MX_K_HDR_TO  3
 Resent-To:  MX_K_HDR_R_TO  4
CC:  MX_K_HDR_CC  5
 Resent-CC:  MX_K_HDR_R_CC  6
BCC:  MX_K_HDR_BCC  7
 Resent-BBC:  MX_K_HDR_R_BCC  8
 Reply-To:  MX_K_HDR_REPLY_TO  17
 Resent-Reply-To:  MX_K_HDR_R_REPLY_TO  19
 Resent-From:  MX_K_HDR_R_FROM  20
 Resent-Sender:  MX_K_HDR_R_SENDER  21


EThe symbolic names are defined in MX_HDR.H in MX_ROOT:[EXAMPLES], if you installed the examples.




DESCRIPTION

DThis routine is called to rewrite an address appearing in an RFC822 Fheader on all outgoing mail, regardless of its origin. The address of Fthe context block you allocated in the INIT routine is passed in here Bfor any information you need to keep track of between calls. This Broutine may be called more than once between one pair of INIT and CLEANUP calls.
"
K

REWRITE_ENVELOPE



.Routine to rewrite an RFC821 envelope address.



Format

3

REWRITE_ENVELOPE context, inaddr, outaddr




RETURNS

                
 VMS usage:  cond_value
type:  longword (unsigned)
access:  write only
 mechanism:  by value


BTo indicate a successful rewrite, return SS$_NORMAL or some other Esuccess status code. If you do not return a success status code, the 2caller will assume that the rewrite did not occur.




ARGUMENTS



context


                
 VMS usage: context
type:  longword (unsigned)
access: modify
 mechanism:  by reference

;This is the same value that was passed to the INIT routine.

inaddr


                
 VMS usage:  char_string
type:  character string
access:  read only
 mechanism: " by descriptor (fixed-length)

BThe RFC821 envelope address to be rewritten. RFC821 addresses are 4enclosed in angle brackets (<>). For example, H"<GENE@MADGOAT.COM>" is a valid RFC821 envelope address.

outaddr


                
 VMS usage:  char_string
type:  character string
access:  write only
 mechanism:  by descriptor

GA string into which your routine should copy the rewritten address, if Fexpansion was successful. You must use the STR$ string routines (such 6as STR$COPY_DX) to copy the string into this argument.



/  
Note

?The rewritten address must be a valid RFC821 address, %including the angle brackets.



DESCRIPTION

@This routine is called to rewrite an RFC821 envelope address on Bincoming mail. Envelope addresses are the addresses of the actual Frecipients of incoming mail and may or may not correspond directly to the RFC822 headers.

FThe address of the context block you allocated in the INIT routine is Epassed in here for any information you need to keep track of between Ecalls. This routine may be called more than once between one pair of INIT and CLEANUP calls.

!
Q

REWRITE_VIRTUAL_DOMAIN



ERoutine for indicating whether a domain name is considered a virtual local domain.



Format

1

REWRITE_VIRTUAL_DOMAIN context, domname




RETURNS

                
 VMS usage:  longword_unsigned
type:  longword (unsigned)
access:  write only
 mechanism:  by value


DThis routine should return 1 if the domain name is to be considered Flocal, or 0 if it is to be considered remote for the purposes of SMTP anti-relay checking.




ARGUMENTS



context


                
 VMS usage: context
type:  longword (unsigned)
access: modify
 mechanism:  by reference

;This is the same value that was passed to the INIT routine.

domname


                
 VMS usage:  char_string
type:  character string
access:  read only
 mechanism: " by descriptor (fixed-length)

<A domain name to be checked for virtual local domain status.



DESCRIPTION

GThis routine is called by the SMTP server to find out whether or not a Ddomain name should be considered local for relay-checking purposes. EThis callout routine can be used to extend the built-in LOCAL_DOMAIN Blist checking, normally done by the SMTP server, to include those Gdomains managed by the ADDRESS_REWRITER callout. Such domain names are )called "virtual" local domains.

@This routine is optional, and is called only if provided by the ADDRESS_REWRITER callout module.

$
B

CLEANUP



Context cleanup routine.



Format



CLEANUP context




RETURNS

                
 VMS usage:  cond_value
type:  longword (unsigned)
access:  write only
 mechanism:  by value


DThis routine should return a status value indicating the success or Gfailure of the cleanup operation. The caller may or may not ignore the returned value.




ARGUMENTS



context


                
 VMS usage: context
type:  longword (unsigned)
access: modify
 mechanism:  by reference

CThe address of the context block you allocated in the INIT routine.



DESCRIPTION

FThis routine is called to clean up after a series of REWRITE_* calls. GYou should clean up the context information and deallocate the context $block allocated by the INIT routine.

FIf you did not allocate a context block in the INIT routine, you must Dstill have a CLEANUP routine, even if it just returns to the caller.



 T

2.2 Host Name Expansion



BThe site host name routines are called by the Router process just Fbefore path identification. The main purpose for these routines is to Fexpand abbreviated host names into full host names that will properly <match one of the paths defined in the MX configuration file.

HWhen you install SMTP support with MX, host name expansion routines are Eautomatically provided that call on the underlying TCP/IP package to Dcatch abbreviated host names that might be recognized by the TCP/IP Dname resolver but are not defined in the MX configuration file. The Gsource for these routines is included in MX_ROOT:[EXAMPLES] for you to modify if needed.

?The routines that must be provided by a host name expander are !described on the following pages.


?

INIT



Initialization routine.



Format



INIT context




RETURNS

                
 VMS usage:  cond_value
type:  longword (unsigned)
access:  write only
 mechanism:  by value


EThe INIT routine must return a success status value in order for the $other expansion routines to be used.




ARGUMENTS



context


                
 VMS usage: context
type:  longword (unsigned)
access: modify
 mechanism:  by reference

HThis is a longword passed by reference to your routine that you may use Bfor any purpose, such as allocating a block of memory for keeping contextual information.



DESCRIPTION

DThis routine is called by the Router before any calls to the EXPAND Groutine. You may use this routine to set up any context or perform any Hhousekeeping tasks needed to prepare for the subsequent calls to EXPAND.

ASince your routines must be reentrant, you should not use static Cstorage for keeping track of state information or other contextual Hinformation. Instead, you should allocate a block of dynamic memory and /return its address in context.


A

EXPAND



Routine to expand a host name.



Format

+

EXPAND context, hostname, expname




RETURNS

                
 VMS usage:  cond_value
type:  longword (unsigned)
access:  write only
 mechanism:  by value


DTo indicate a successful expansion, return SS$_NORMAL or some other Esuccess status code. If you do not return a success status code, the 0caller will assume that expansion did not occur.




ARGUMENTS



context


                
 VMS usage: context
type:  longword (unsigned)
access: modify
 mechanism:  by reference

;This is the same value that was passed to the INIT routine.

hostname


                
 VMS usage:  char_string
type:  character string
access:  read only
 mechanism: " by descriptor (fixed-length)

The host name to be expanded.

expname


                
 VMS usage:  char_string
type:  character string
access:  write only
 mechanism:  by descriptor

HA string into which your routine should copy the expanded host name, if Fexpansion was successful. You must use the STR$ string routines (such 6as STR$COPY_DX) to copy the string into this argument.



DESCRIPTION

HThis routine is called to perform a host name expansion. The address of Fthe context block you allocated in the INIT routine is passed in here Bfor any information you need to keep track of between calls. This Broutine may be called more than once between one pair of INIT and CLEANUP calls.

B

CLEANUP



Context cleanup routine.



Format



CLEANUP context




RETURNS

                
 VMS usage:  cond_value
type:  longword (unsigned)
access:  write only
 mechanism:  by value


DThis routine should return a status value indicating the success or Gfailure of the cleanup operation. The caller may or may not ignore the returned value.




ARGUMENTS



context


                
 VMS usage: context
type:  longword (unsigned)
access: modify
 mechanism:  by reference

CThe address of the context block you allocated in the INIT routine.



DESCRIPTION

GThis routine is called to clean up after a series of EXPAND calls. You Cshould clean up the context information and deallocate the context $block allocated by the INIT routine.

FIf you did not allocate a context block in the INIT routine, you must Dstill have a CLEANUP routine, even if it just returns to the caller.



 P

2.3 Name Conversion



GThe local name conversion routines are used by the MX_MAILSHR VMS Mail Einterface to translate a username into an alias and by the Router to Btranslate aliases back into real usernames. This can be used, for Eexample, to map usernames into "real" names and vice-versa.

HThe following pages describe the routines that must be provided for the name conversion interface.

FIn addition to the required CONVERT routine, an optional FULL_CONVERT Hroutine may be provided to allow for conversion of a username to a full 9RFC822 address, as opposed to just username substitution.


?

INIT



Initialization routine.



Format



INIT context




RETURNS

                
 VMS usage:  cond_value
type:  longword (unsigned)
access:  write only
 mechanism:  by value


EThe INIT routine must return a success status value in order for the $other expansion routines to be used.




ARGUMENTS



context


                
 VMS usage: context
type:  longword (unsigned)
access: modify
 mechanism:  by reference

HThis is a longword passed by reference to your routine that you may use Bfor any purpose, such as allocating a block of memory for keeping contextual information.



DESCRIPTION

EThis routine is called by the Router before any calls to the CONVERT Groutine. You may use this routine to set up any context or perform any Ahousekeeping tasks needed to prepare for the subsequent calls to CONVERT.

ASince your routines must be reentrant, you should not use static Cstorage for keeping track of state information or other contextual Hinformation. Instead, you should allocate a block of dynamic memory and /return its address in context.


C

CONVERT



DRoutine to convert a username to an alias or an alias to a username.



Format

0

CONVERT context, code, inname, outname




RETURNS

                
 VMS usage:  cond_value
type:  longword (unsigned)
access:  write only
 mechanism:  by value


BOn successful conversion, return SS$_NORMAL or some other success Dstatus code. If you do not return a success status code, the caller )will assume that expansion did not occur.




ARGUMENTS



context


                
 VMS usage: context
type:  longword (unsigned)
access: modify
 mechanism:  by reference

;This is the same value that was passed to the INIT routine.

code


                
 VMS usage:  longword_unsigned
type:  longword (unsigned)
access:  read only
 mechanism:  by reference

FThis argument indicates what type of name conversion should occur. It &will have one of the following values: "          
Value Meaning
 1 + Perform alias-to-username conversion.
 2 + Perform username-to-alias conversion.


inname


                
 VMS usage:  char_string
type:  character string
access:  read only
 mechanism: " by descriptor (fixed-length)

The name to be converted.

outname


                
 VMS usage:  char_string
type:  character string
access:  write only
 mechanism:  by descriptor

FA string into which your routine should copy the result. This is only )used if you return a success status code.



DESCRIPTION

9This routine is called to perform a name conversion. For Galias-to-username translation, a string containing the potential alias Fis passed in inname. If the conversion succeeds, the Faddress returned in outname must be in RFC821 format:

   

"
<username@hostname> 



GThis format must be used even if the address is intended for the local host.

BFor username-to-alias conversion, the username to be converted is Bpassed in inname. If no conversion is performed, Areturn a non-success status code; otherwise, provide a result in Foutname. The result should be only the local part of Fan address; no host name should be appended nor any punctuation added.

GThis routine may be called more than once between one pair of INIT and CLEANUP calls.


C

CLEANUP



Context cleanup routine.



Format



CLEANUP context




RETURNS

                
 VMS usage:  cond_value
type:  longword (unsigned)
access:  write only
 mechanism:  by value


DThis routine should return a status value indicating the success or Gfailure of the cleanup operation. The caller may or may not ignore the returned value.




ARGUMENTS



context


                
 VMS usage: context
type:  longword (unsigned)
access: modify
 mechanism:  by reference

CThe address of the context block you allocated in the INIT routine.



DESCRIPTION

HThis routine is called to clean up after a series of CONVERT calls. You Cshould clean up the context information and deallocate the context $block allocated by the INIT routine.

FIf you did not allocate a context block in the INIT routine, you must Dstill have a CLEANUP routine, even if it just returns to the caller.


H

FULL_CONVERT



ERoutine to convert a username to an alias (as a full RFC822 address).



Format

5

FULL_CONVERT context, code, inname, outname




RETURNS

                
 VMS usage:  cond_value
type:  longword (unsigned)
access:  write only
 mechanism:  by value


BOn successful conversion, return SS$_NORMAL or some other success Dstatus code. If you do not return a success status code, the caller *will assume that conversion did not occur.




ARGUMENTS



context


                
 VMS usage: context
type:  longword (unsigned)
access: modify
 mechanism:  by reference

;This is the same value that was passed to the INIT routine.

code


                
 VMS usage:  longword_unsigned
type:  longword (unsigned)
access:  read only
 mechanism:  by reference

HThis argument indicates what type of name conversion should occur. Only 'the following value should be accepted: "      
Value Meaning
 2 + Perform username-to-alias conversion.


?All other values for this argument are reserved for future use.

inname


                
 VMS usage:  char_string
type:  character string
access:  read only
 mechanism: " by descriptor (fixed-length)

The name to be converted.

outname


                
 VMS usage:  char_string
type:  character string
access:  write only
 mechanism:  by descriptor

FA string into which your routine should copy the result. This is only )used if you return a success status code.



DESCRIPTION

=This routine is called to perform a username-to-full-address 6conversion. The username to be converted is passed in Ainname. If no conversion is performed, return a Dnon-success status code. Unlike the CONVERT routine, the result you ?provide in outname on a successful conversion Gmust be a full RFC822-type address (user@host format).

GThis routine may be called more than once between one pair of INIT and 8CLEANUP calls, and may be intermixed with CONVERT calls.






I

Chapter 3
SMTP Authentication Callout




EThe MX SMTP server supports the SMTP extension for authentication of Eclients, with built-in support for a private authentication database >(when using the CRAM-MD5 authentication mechanism) as well as Eauthentication using the VMS user authorization file (when using the +PLAIN and LOGIN authentication mechanisms).

BThe authentication callout provides a way to replace the built-in FPLAIN/LOGIN authentication mechanism, so that usernames and passwords Fmay be validated against an alternative source besides the SYSUAF, or Cto extend the authentication system to include additional features C(such as customized intrusion detection and evasion or per-message accounting).

GThe authentication callout routines are located through the use of the Elogical name MX_SITE_SMTP_AUTHENTICATION, which should be defined in @executive mode in the system logical name table to point to the .shareable image containing the callout module.

BAn example of an authentication callout module is provided in the )Examples saveset of the installation kit.!


@

INIT



Initialization routine.



Format



INIT context




RETURNS

                
 VMS usage:  cond_value
type:  longword (unsigned)
access:  write only
 mechanism:  by value


EThe INIT routine must return a success status value in order for the )other authentication routines to be used.




ARGUMENTS



context


                
 VMS usage: context
type:  longword (unsigned)
access: modify
 mechanism:  by reference

HThis is a longword passed by reference to your routine that you may use Bfor any purpose, such as allocating a block of memory for keeping contextual information.



DESCRIPTION

BThis routine is called by the SMTP server before any calls to the HAUTHENTICATE or ACCOUNTING routines. You may use this routine to set up .any context or perform any housekeeping tasks.

FNote that the SMTP server is multi-threaded, so while this routine is Acalled no more than once per SMTP session, there may be multiple Hsimultaneous sessions active in the SMTP server at one time. Since your Broutines must be reentrant, you should not use static storage for Dkeeping track of state information or other contextual information. FInstead, you should allocate a block of dynamic memory and return its $address in context.

)
H

AUTHENTICATE



!Routine to authenticate a client.



Format

E

AUTHENTICATE context, usrnam, pass, cliaddr, cliaddrlen, sessid, authstat, astadr, astprm




RETURNS

                
 VMS usage:  cond_value
type:  longword (unsigned)
access:  write only
 mechanism:  by value


EThe return status is used only to determine whether this routine has Hcompleted synchronously (non-success status) or asynchronously (success status).




ARGUMENTS



context


                
 VMS usage: context
type:  longword (unsigned)
access: modify
 mechanism:  by reference

1The context longword, as set by the INIT routine.

usrnam


                
 VMS usage:  char_string
type:  character string
access:  read only
 mechanism: # by descriptor (fixed-length)

$The username provided by the client.

pass


                
 VMS usage:  char_string
type:  character string
access:  read only
 mechanism: # by descriptor (fixed-length)

$The password provided by the client.

cliaddr


                
 VMS usage:  sockaddr
type:  socket address
access:  read only
 mechanism:  by reference

@A socket address structure containing the address of the client.

cliaddrlen


                
 VMS usage:  longword_unsigned
type:  longword (unsigned)
access:  read only
 mechanism:  by value

EThe size, in bytes, of the cliaddr socket address structure.

sessid


                
 VMS usage:  longword_unsigned
type:  longword (unsigned)
access:  write only
 mechanism:  by reference

GA "session identifier" to be returned for this authenticated DSMTP session, if authentication is successful. If set to a non-zero Gvalue, the SMTP server will include this value in the Received: header 6of any message sent by the client during this session.

authstatus


                
 VMS usage:  cond_value
type:  longword (unsigned)
access:  write only
 mechanism:  by reference

;A VMS status code indicating the success or failure of the Gauthentication sequence. If this routine completes synchronously, this Gvalue should be set before returning to the caller. Typical values for Eauthstatus are SS$_NORMAL for success, and SS$_INVLOGIN for failure.

astadr


                
 VMS usage:  ast_procedure
type:  procedure entry mask
access: " call without stack unwinding
 mechanism:  by reference

HThe address of the caller's AST completion routine. If the AUTHENTICATE Broutine needs to perform asynchronous I/O, its own AST completion Froutine should call this routine to indicate to the caller that it is finished.

astprm


                
 VMS usage:  user_arg
type:  longword (unsigned)
access:  read only
 mechanism:  by value

=Argument to be passed to the caller's AST completion routine.



DESCRIPTION

@ This routine performs authentication for a username/password H combination. If this routine requires any I/O operation that may not D complete immediately, it should use asynchronous I/O and its AST K completion routine should call the AST routine that is passed in by the caller.

I Only one authentication request will ever be outstanding for a single I authentication context, so the context block can be used to store the J caller's AST routine address, AST parameter, and authentication status 7 address for later use by its AST completion routine.

@ Note that the SMTP server provides the username and password E exactly as sent by the client. No case conversion, blank 5 stripping, or other editing is done by the server.

"
F

ACCOUNTING



CRoutine to record the acceptance of a message in an accounting log.



Format

=

ACCOUNTING context, sessid, msgsize, fromadr, toadr




RETURNS

                
 VMS usage:  cond_value
type:  longword (unsigned)
access:  write only
 mechanism:  by value


BThe SMTP server currently ignores the returned status. For future Gcompatibility, however, you should return a status code indicating the -success or failure of the accounting request.




ARGUMENTS



context


                
 VMS usage: context
type:  longword (unsigned)
access: modify
 mechanism:  by reference

;This is the same value that was passed to the INIT routine.

sessid


                
 VMS usage:  longword_unsigned
type:  longword (unsigned)
access:  read only
 mechanism:  by reference

EThis argument contains the session ID value that was returned by the AUTHENTICATE routine.

msgsize


                
 VMS usage:  longword_unsigned
type:  longword (unsigned)
access:  read only
 mechanism:  by reference

BThe size, in bytes, of the body of the message sent by the client.

fromadr


                
 VMS usage:  char_string
type:  character string
access:  read only
 mechanism:  by descriptor

DThe SMTP MAIL FROM: address provided by the client for this message.

toadr


                
 VMS usage:  char_string
type:  character string
access:  read only
 mechanism:  by descriptor

HThe SMTP RCPT TO: address provided by the client for this message. Note Hthat this routine is called once for each recipient named by the client.



DESCRIPTION

I This routine is called by the SMTP server after a message is accepted G from the authenticated client. Note that this routine may be called @ multiple times for each message---once per recipient address.

E Note that this routine is optional; it is only called by the SMTP K server if it is provided by the installed authentication callout module.

$
C

CLEANUP



Context cleanup routine.



Format



CLEANUP context




RETURNS

                
 VMS usage:  cond_value
type:  longword (unsigned)
access:  write only
 mechanism:  by value


DThis routine should return a status value indicating the success or Gfailure of the cleanup operation. The caller may or may not ignore the returned value.




ARGUMENTS



context


                
 VMS usage: context
type:  longword (unsigned)
access: modify
 mechanism:  by reference

CThe address of the context block you allocated in the INIT routine.



DESCRIPTION

CThis routine is called to clean up at the end of an authentication Esequence or session. You should clean up the context information and ;deallocate the context block allocated by the INIT routine.

FIf you did not allocate a context block in the INIT routine, you must Dstill have a CLEANUP routine, even if it just returns to the caller.






J

Chapter 4
Character-Conversion Callout




GThe MX VMS MAIL interface supports conversion between the local native Bcharacter set and a character set used in e-mail messages. MX has Ebuilt-in support for using the ISO-Latin-1 character set for network Emessages, with either ISO-Latin-1 or the DEC Multinational Character 'Set as the local, native character set.

HIf you need to use any other character sets for either local or network Dmessages, you should install a character conversion callout module. HExample code for this module is provided in the Examples saveset of the installation kit.



/  
Note

GThe routines in this module must be reentrant, as a single process may Ahave multiple conversion sequences active simultaneously.
!
@

INIT



Initialization routine.



Format

:

INIT code, context, [lcslen], lcsname, [ncsname]




RETURNS

                
 VMS usage:  cond_value
type:  longword (unsigned)
access:  write only
 mechanism:  by value


GIf a success status is returned, the CONVERT routine will be called to perform the conversion.




ARGUMENTS

code


                
 VMS usage:  longword_unsigned
type:  longword (unsigned)
access:  read only
 mechanism:  by reference

CA coded value indicating the direction of the conversion. Possible values are: &          
Value Description
 1 C Conversion from local character set to network character set.
 2 C Conversion from network character set to local character set.
,Note that this value is passed by reference.


ARGUMENTS



context


                
 VMS usage: context
type:  longword (unsigned)
access: modify
 mechanism:  by reference

HThis is a longword passed by reference to your routine that you may use Bfor any purpose, such as allocating a block of memory for keeping contextual information.


lcslen


                
 VMS usage:  word_unsigned
type:  word (unsigned)
access:  write only
 mechanism:  by reference

GIf provided by the caller, the INIT routine should write the length of Ethe local character set name in this parameter. If this parameter is 3null, the caller does not need the length returned.

lcsname


                
 VMS usage:  char_string
type:  character string
access:  write only
 mechanism:  by descriptor

?The name of the local character set. This should be one of the Bcharacter set names registered with the Internet Assigned Numbers BAuthority, preferably the "MIME preferred" charset name.



/  
Note

CThis argument and lcslen should be filled in even if this 3routine returns a non-success status value.


ncsname


                
 VMS usage:  char_string
type:  character string
access:  read only
 mechanism:  by descriptor

HThe name of the network character set to be used for the conversion. If Gthis parameter is null, the callout module's default network character Eset should be used. Otherwise, this routine should make sure that it Ccan support conversion between the specified character set and the local character set.



DESCRIPTION

HThis routine is called by the MX VMS MAIL interface (in MX_MAILSHR, the CMX Router agent, and the MX Local agent) to initialize a character conversion sequence.

HThis routine should validate the parameters provided and return success Hstatus only if the callout will handle the requested conversion. If the Dnetwork and local character sets are identical, this routine should return a non-success status.

DAny context required for the conversion should be allocated by this Eroutine. The context should store information about the direction of 7the conversion, provided in the code argument.

$
C

CONVERT



-Perform character-set conversion on a string.



Format

G

CONVERT context, instr, [outlen], outstr, [converted], [remaining] 




RETURNS

                
 VMS usage:  cond_value
type:  longword (unsigned)
access:  write only
 mechanism:  by value


EA success value indicates that characters have been converted and/or ,copied between the input and output strings.




ARGUMENTS



context


                
 VMS usage: context
type:  longword (unsigned)
access: modify
 mechanism:  by reference

1The context longword, as set by the INIT routine.

instr


                
 VMS usage:  char_string
type:  character string
access:  read only
 mechanism: # by descriptor (fixed-length)

1The string containing characters to be converted.

outlen


                
 VMS usage:  word_unsigned
type:  word (unsigned)
access:  write only
 mechanism:  by reference

HIf non-null, the actual length of the converted output string should be returned in this argument.

outstr


                
 VMS usage:  char_string
type:  character string
access:  write only
 mechanism: # by descriptor (fixed-length)

GThe output string. The descriptor for this string will always point to @a fixed-length string, either static (DSC$K_CLASS_S) or dynamic (DSC$K_CLASS_D).

converted


                
 VMS usage:  longword_unsigned
type:  longword (unsigned)
access:  write only
 mechanism:  by reference

FIf non-null, this argument should be set to 1 if there any characters Gin the input string were translated before being written to the output Astring. If the conversion resulted in a simply copy of identical 0characters, this argument should be set to zero.

remaining


                
 VMS usage:  word_unsigned
type:  word (unsigned)
access:  write only
 mechanism:  by reference

HIf non-null, this argument should be set to the number of characters in Hthe input string that were not processed by this call. This should only Chappen if the output string is not large enough to hold the entire converted input string.



DESCRIPTION

GThis routine is called to perform character set conversion on a string.
&
E

GETCSNAME



Returns a character set name.



Format

.

GETCSNAME context, code, [len], name




RETURNS

                
 VMS usage:  cond_value
type:  longword (unsigned)
access:  write only
 mechanism:  by value



ARGUMENTS



context


                
 VMS usage: context
type:  longword (unsigned)
access: modify
 mechanism:  by reference

2The context that was returned by the INIT routine.

code


                
 VMS usage:  longword_unsigned
type:  longword (unsigned)
access:  read only
 mechanism:  by reference

DThis argument indicates which character set name should be returned: &          
Value Description
 1  The local character set.
 2 The network character set.
DNote that the returned name should be fore the actual character set Ginvolved in the current conversion sequence, not the default character set supported by the callout.

len


                
 VMS usage:  word_unsigned
type:  word (unsigned)
access:  write only
 mechanism:  by reference

EIf non-null, this argument should be set to the length, in bytes, of the returned name.

name


                
 VMS usage:  char_string
type:  character string
access:  write only
 mechanism: " by descriptor (fixed-length)

GThis argument should be set to the name of the requested character set.



DESCRIPTION

DThis routine is called during a conversion sequence to retrieve the =name of either the local or network character set being used.
#
B

FINISH



Context cleanup routine.



Format



FINISH context




RETURNS

                
 VMS usage:  cond_value
type:  longword (unsigned)
access:  write only
 mechanism:  by value



ARGUMENTS



context


                
 VMS usage: context
type:  longword (unsigned)
access: modify
 mechanism:  by reference

?The address of the context block allocated in the INIT routine.



DESCRIPTION

HThis routine is called to clean up at the end of a conversion sequence. GYou should clean up the context information and deallocate the context $block allocated by the INIT routine.

FIf you did not allocate a context block in the INIT routine, you must Cstill have a FINISH routine, even if it just returns to the caller.



"


H

Chapter 5
SMTP Client Access Callout




FThe MX SMTP server normally accepts all incoming connections from any Eclient, regardless of the client's source address. The client access ASITE callout provides a way to modify this behavior and exercise Dadministrative control over which clients have access to the server.

FThe client access callout routines are located through the use of the Elogical name MX_SITE_CLIENT_ACCESS_CHECK, which should be defined in @executive mode in the system logical name table to point to the .shareable image containing the callout module.

@An example of a client access callout module is provided in the )Examples saveset of the installation kit.%


@

INIT



Initialization routine.



Format



INIT context




RETURNS

                
 VMS usage:  cond_value
type:  longword (unsigned)
access:  write only
 mechanism:  by value


EThe INIT routine must return a success status value in order for the Eother client access check routines to be used; otherwise, the server assumes that access is granted.




ARGUMENTS



context


                
 VMS usage: context
type:  longword (unsigned)
access: modify
 mechanism:  by reference

HThis is a longword passed by reference to your routine that you may use Bfor any purpose, such as allocating a block of memory for keeping contextual information.



DESCRIPTION

HThis routine is called by the SMTP server before any calls to the CHECK Groutine. You may use this routine to set up any context or perform any housekeeping tasks.

FNote that the SMTP server is multi-threaded, so while this routine is Acalled no more than once per SMTP session, there may be multiple Hsimultaneous sessions active in the SMTP server at one time. Since your Broutines must be reentrant, you should not use static storage for Dkeeping track of state information or other contextual information. FInstead, you should allocate a block of dynamic memory and return its $address in context.

&
A

CHECK



%Routine to check access for a client.



Format

E

CHECK context, cliaddr, cliaddrlen, accstat, astadr, astprm




RETURNS

                
 VMS usage:  cond_value
type:  longword (unsigned)
access:  write only
 mechanism:  by value


EThe return status is used only to determine whether this routine has Hcompleted synchronously (non-success status) or asynchronously (success status).




ARGUMENTS



context


                
 VMS usage: context
type:  longword (unsigned)
access: modify
 mechanism:  by reference

1The context longword, as set by the INIT routine.

cliaddr


                
 VMS usage:  sockaddr
type:  socket address
access:  read only
 mechanism:  by reference

@A socket address structure containing the address of the client.

cliaddrlen


                
 VMS usage:  longword_unsigned
type:  longword (unsigned)
access:  read only
 mechanism:  by value

EThe size, in bytes, of the cliaddr socket address structure.

accstatus


                
 VMS usage:  cond_value
type:  longword (unsigned)
access:  write only
 mechanism:  by reference

BA VMS status code indicating the success or failure of the access Echeck. If this routine completes synchronously, this value should be 7set before returning to the caller. Typical values for Haccstatus are SS$_NORMAL for success, and SS$_INVLOGIN (or any &other non-success status) for failure.

astadr


                
 VMS usage:  ast_procedure
type:  procedure entry mask
access: " call without stack unwinding
 mechanism:  by reference

AThe address of the caller's AST completion routine. If the CHECK Broutine needs to perform asynchronous I/O, its own AST completion Froutine should call this routine to indicate to the caller that it is finished.

astprm


                
 VMS usage:  user_arg
type:  longword (unsigned)
access:  read only
 mechanism:  by value

=Argument to be passed to the caller's AST completion routine.



DESCRIPTION

H This routine checks whether the SMTP client at the specified address I should be granted access to the SMTP server. If this routine requires F any I/O operation that may not complete immediately, it should use G asynchronous I/O and its AST completion routine should call the AST + routine that is passed in by the caller.

G Only one access check request will ever be outstanding for a single G access check context, so the context block can be used to store the J caller's AST routine address, AST parameter, and authentication status 7 address for later use by its AST completion routine.

(
C

CLEANUP



Context cleanup routine.



Format



CLEANUP context




RETURNS

                
 VMS usage:  cond_value
type:  longword (unsigned)
access:  write only
 mechanism:  by value


DThis routine should return a status value indicating the success or Gfailure of the cleanup operation. The caller may or may not ignore the returned value.




ARGUMENTS



context


                
 VMS usage: context
type:  longword (unsigned)
access: modify
 mechanism:  by reference

CThe address of the context block you allocated in the INIT routine.



DESCRIPTION

EThis routine is called to clean up after an access check. You should Bclean up the context information and deallocate the context block allocated by the INIT routine.

FIf you did not allocate a context block in the INIT routine, you must Dstill have a CLEANUP routine, even if it just returns to the caller.



 .
^ Contents