| Version 5.4
Introduction
Installation
SysAdmin
Network
Objects
Storage
E-mail
Real-Time
Access
Services
Directory
Clusters
Applications
Miscellaneous
Licensing
WebMail
Pronto!
PBX
Applications | Data | CLI/API | Rules | CG/PL | PBXApp | XIMSS | WebApp | WSSP | Helpers
# Helper Applications Helper Protocol External Authentication External Message Filters External RADIUS Helpers External CDR Processor External Banner System The CommuniGate Pro Server can use external programs to implement various operations - message scanning, user authentication, RADIUS login policies, etc. All these external programs are handled in the same way, and they communicate with the Server using a simple Helper Interface protocol. See the System Administration section to learn how to specify the Helper programs to use.

## Helper Protocol

When the Helper program is launched, the Server sends commands to the Helper process via the process standard input. The Server reads the program responses from the process standard output.

Commands and responses are text lines, ending with the EOL symbol(s) used in the Server OS.

Each command starts with a sequence number, and the response produced with the Helper program starts with the same number. This method allows the Helper program to process several requests simultaneously, and it can return responses in any order.

The Helper program can send information responses at any time. An information response starts with the asterisk (`*`) symbol. The Server ignores information responses, but they can be seen in the Server Log.

The response lines generated with a Helper program should not be larger than 4096 bytes.

Note: communication between the Server and an Helper program takes place via OS pipes, and many programming libraries buffer output data sent to pipes. Check that your Helper program uses some form of the flush command after it sends a response to its standard output, otherwise the response will not reach the Server.

Helper programs are started with the CommuniGate Pro base directory as their current directory.

Helper programs should not write anything to their standard error streams, unless they want to report a reason for the failure before quitting. CommuniGate Pro reads the program standard error stream only after the program has terminated, and if the program writes into that stream while processing Server commands, the program will be suspended by the OS when the standard error pipe buffer is full.

The Interface Version command is used to provide compatibility between different versions of Helper programs and different versions of the CommuniGate Pro Server. The Server sends this command specifying the protocol version it implements:
`nnnnnn INTF serverInterfaceVersion`
where:

  nnnnnn
    a unique sequence number for this request
  serverInterfaceVersion
    the version of the Helper protocol implemented by this version of the CommuniGate Pro Server

The Helper program should return the INTF response and the supported protocol version.
`nnnnnn INTF programInterfaceVersion`
If the returned number is smaller than the Server protocol version, the Server will use this (older) protocol version.

When the Server shuts down or when it needs to stop the Helper program, it sends the `QUIT` command, and then closes the process standard input. The Helper program should send the `OK` response and it should quit within 5 seconds.

Sample session (I: - server commands sent to the program standard input, O: - responses the program writes to its standard output, COMMAND - a Helper-specific command):

  `O: * My Helper program started
  I: 00001 INTF 1
  O: 00001 INTF 1
  I: 00002 COMMAND parameters
  O: 00002 OK
  I: 00003 COMMAND parameters
  I: 00004 COMMAND parameters
  O: * processing 00003 will take some time
  O: 00004 ERROR description
  O: 00003 OK
  I: 00005 QUIT
  O: * processed: 5 requests. Quitting.
  O: 00005 OK
  I: stdin closed`

The sample above shows that the Server does not wait for a response before it sends the next command, and that it can accept responses for several pending commands in any order - as long as each command receives a response within the specified time limit.

## External Authentication

External Authenticator programs can be used to provide authentication, provisioning, and routing services using external data sources.

The External Authenticator Interface protocol is based on the generic Helper Protocol.

This manual describes the External Authenticator Interface Version 11.

When a user should be authenticated using the clear text method, the Server sends the following command:
`nnnnnn VRFY (mode) name@domain password [loginAddress]`
where:

  nnnnnn
    a unique sequence number for this request
  mode
    the name of the service (IMAP, POP, FTP, etc.) that requested this authentication operation.
    This parameter can be absent if the request has been received from an unnamed Server component.
    If the service name is specified, it is enclosed into the parenthesis.
  name
    user Account name
  domain
    user Account Domain name
  password
    password string to verify. If the password contains special symbols, the password is encoded as a quoted String.
  loginAddress
    the network address from which the user logs in.
    This parameter can be absent if the password is checked by an internal Server component.
    If the parameter is specified, it is enclosed into square brackets.

When a user should be authenticated using a secure SASL method, the following command is sent:
`nnnnnn SASL(method) (mode) name@domain password key [loginAddress]`
where:

  method
    the name of the secure SASL method used (`CRAM-MD5`, `APOP`)
  key
    the challenge string sent to the client mailer. If the challenge contains special symbols, it is encoded as a quoted String.

If the password is accepted, the External Authenticator should return a positive response:
`nnnnnn OK`

If the password was not accepted, a negative response should be returned:
`nnnnnn ERROR optional-error-message`

If the password is accepted, and there is an authentication response to be returned to the client, a positive response with a quoted string should be returned:
`nnnnnn RETURN "authentication-response"`

SASL password verification requires that the External Authenticator program correctly implements all supported SASL methods and algorithms. Alternatively, the External Authenticator program can return the user plain text password, making the Server verify the password and calculate necessary authentication responses. The user plain text password should be returned as a quoted string:
`nnnnnn PLAIN "plain-text-password"`

Sample session (I: - server commands sent to the program standard input, O: - responses the program writes to its standard output):

  `I: 00001 INTF 1
  O: 00001 INTF 1
  I: 00010 VRFY user1@domain1.com dsyui134
  O: 00010 OK
  I: 00011 VRFY (IMAP) user2@domain2.com jskj23#45 [10.0.3.4]
  O: 00011 ERROR incorrect password
  I: 00012 SASL(CRAM-MD6) user4@domain2.com hdkj547812329394055 <pop-23456@mydomain.com> [10.0.1.4]
  I: 00013 VRFY (IMAP) user2@domain2.com "jskj23\"45"
  O: 00013 OK
  O: 00012 ERROR unsupported SASL method
  I: 00014 SASL(DIGEST-MD5) user4@domain2.com 012345 "user:qop:zz:mmm:uri" [10.0.1.4]
  O: 00014 RETURN "0123456789AAAA"
  I: 00015 SASL(DIGEST-MD5) user4@domain2.com 012345 "user:qop:zz:mmm:uri" [10.0.1.4]
  O: 00015 PLAIN "my$$password"
  `

The External Authentication program can be used to retrieve plain text passwords from external databases.

To retrieve a password, the Server sends the following command:
`nnnnnn READPLAIN name@domain`
where:

  name@domain
    the full name (address) of the target Account.

The program should return the user plain text password as a quoted string:
`nnnnnn PLAIN "plain-text-password"`
If the program cannot retrieve the plain text password, it should return the FAILURE response.

The External Authentication program can be used to process unknown names, too. For example, the program can consult an external database, check if the user exists in that database, create an Account, Alias, Group, Mailing List, or Forwarder using the CommuniGate Pro CLI/API, and return a positive response to the Server. In this case, CommuniGate Pro will re-try to open a Domain object with the specified name.

To check an unknown name, the Server sends the following command:
`nnnnnn NEW name@domain relayType`
where:

  relayType
    `[MAIL]` if the command is sent as a part of mail-type routing process,
    `[SIGNAL]` if the command is sent as a part of signal-type routing process,
    `[ACCESS]` if the command is sent as a part of access-type routing process.
  name@domain
    the full name (address) of the unknown local object.

If the program sends the `OK` response, the Server tries to find the name object in the domain Domain again.

If the program sends the `ROUTED address` response, the Server takes the supplied address response and restarts the Router procedure with this address. The routed address gets a "can Relay" attribute, unless it is specified with the `[NORELAY]` prefix.

If the program sends the `FAILURE` response, the Server Router returns a "temporary internal error" code (this code causes the SMTP module to return a 4xx error code, not a permanent 5xx error code).

If the program sends any other response, the Server Router returns the "unknown user account" error.

Sample session:

  `I: 00010 NEW user1@domain1.com [MAIL]
  O: 00010 ERROR this account is not known
  I: 00011 NEW user2@domain2.com [MAIL]
  I: 00012 NEW user3@domain2.com [ACCESS]
  O: 00012 OK
  O: 00011 ROUTED [NORELAY] userX@domain2.com
  `

The Consult External for Unknown Domain Setting tells the Server to use the External Authenticator program when an unknown name is addressed.

The External Authentication program can be used to assist in address Routing. If an address is routed to the `@external` domain, the address "local part" is passed to the External Authentication program using the ROUTE command:
`nnnnnn ROUTE <address> relayType`
where:

  relayType
    `[MAIL]` if the command is sent as a part of mail-type routing process,
    `[SIGNAL]` if the command is sent as a part of signal-type routing process,
    `[ACCESS]` if the command is sent as a part of access-type routing process.
  address
    the local part of the address with the `external` domain part.

If the program sends the `ROUTED address` response, the Server takes the supplied address response and restarts the Router procedure with this address. The routed address gets a "can Relay" attribute if the address is specified with the `[RELAY]` prefix.

If the program sends the `FAILURE` response, the Server Router returns a "temporary internal error" code (this code causes the SMTP module to return a 4xx error code, not a permanent 5xx error code).

If the program sends any other response, the Server Router returns the "cannot route the address" error.

Sample session:

  `I: 00010 ROUTE <user1> [MAIL]
  O: 00010 ERROR this account is blocked
  I: 00011 ROUTE <user2%domain1.dom> [MAIL]
  I: 00012 ROUTE <"user3##name"%domain2.dom> [SIGNAL]
  O: 00012 FAILURE internal error
  O: 00011 ROUTED [RELAY] userX@domain100.dom
  `

The External Authentication program can be used to assist in provisioning operations. If the Consult External on Provision Domain Setting is enabled, the Server sends the following commands to the External Authentication program:

before an Account is created:
  `nnnnnn PRECREATE [authAccount] accountName@domainName accountType initialSettings`
  initialSettings is a dictionary.
  If this operation fails, the Account is not created.
after an Account is created:
  `nnnnnn POSTCREATE [authAccount] accountName@domainName accountType initialSettings`
  If this operation fails, the newly created Account is removed.
before an Account is renamed:
  `nnnnnn PRERENAME [authAccount] accountName@domainName newAccountName@newDomainName`
  If this operation fails, the Account is not renamed.
after an Account is renamed:
  `nnnnnn POSTRENAME [authAccount] accountName@domainName newAccountName@newDomainName`
  If this operation fails, the renamed Account is renamed back.
before an Account is removed:
  `nnnnnn PREDELETE [authAccount] accountName@domainName`
  If this operation fails, the Account is not removed.
after an Account is removed:
  `nnnnnn POSTDELETE [authAccount] accountName@domainName`
before an Account License Class is changed:
  `nnnnnn PRETYPECHANGE [authAccount] accountName@domainName newClass`
  If this operation fails, the Account License Class is not changed.
after an Account License Class is changed:
  `nnnnnn POSTTYPECHANGE [authAccount] accountName@domainName newClass`
before an Account settings are updated:
  `nnnnnn PREUPDATE [authAccount] accountName@domainName newSettings`
  If this operation fails, the Account settings are not updated.
after an Account settings are updated:
  `nnnnnn POSTUPDATE [authAccount] accountName@domainName newSettings`
before an Account password is updated:
  `nnnnnn PREPWDCHANGE [authAccount] accountName@domainName newPassword`
  If this operation fails, the Account password is not updated.
The password is one of Account settings, so the PREUPDATE command will follow this one.

authAccount is the name of the Account performing the provisioning operation. If it is not known, this account name and the square brackets surrounding it are omitted.

The program should either send an `OK` response, or a `FAILURE "errorCode"` response.

## External Message Filters

External Message Filter programs are used for content filtering (anti-virus and anti-spam filtering).

The External Filter Interface protocol is based on the generic Helper Protocol.
This section describes the External Filter protocol version 3.

- The program should process the External Filter requests:
  `seqNum FILE fileName`
    where fileName is the name of the file the program should scan.
- If message processing should proceed, the response line should have the following format:
  `seqNum OK`
- If message processing should proceed, but the external filter wishes to add a header field to the message, the response line should have the following format:
  `seqNum ADDHEADER header-field-text`
    where header-field-text is a text string with one or several RFC822 header fields. This (optionally multi-line) text should be placed into the response line in the CommuniGate Pro String format
- If a message should be rejected the response line should have the following format:
  `seqNum ERROR report`
    where report is a text string explaining why the message is rejected. This (optionally multi-line) text should be placed into the response line in the CommuniGate Pro String format
- If a message should be discarded the response line should have the following format:
  `seqNum DISCARD`
- If message processing should be postponed (because of the license limitations, for example), the response line should have the following format:
  `seqNum REJECTED report`
    where report is a text string explaining why the message processing should be postponed.
- If the program receives a request it cannot process, it should return the FAILURE response:
  `seqNum FAILURE`
    where seqNum is the request identifier.
  If the program has sent the FAILURE response or any unlisted response, the Server places a record into the Log and proceeds as if it has received the OK response.
- The program SHOULD be ready to process several requests simultaneously (using several threads). Since the External Filter program is used with the Server-Wide Rules (processed with the Enqueuer Server component), the program should be ready to handle N concurrent requests, when N is the number of Enqueuer "processors" (threads).
- The program MAY be implemented as a single-threaded one, so it reads the next request only after the previous request has been processed. But this design can result in severe performance degradation of the entire Server: when a single-threaded External Filter program is scanning a large message, other messages are not being enqueued.

If the external program crashes, CommuniGate Pro suspends the Enqueuer process until the external program is restarted.

## External RADIUS Helpers

External RADIUS programs can be used to provide additional checks for authentication operations performed via the RADIUS module, as well as to add additional attributes into RADIUS responses.

The External RADIUS Interface protocol is based on the generic Helper Protocol.
This manual describes the External RADIUS Interface Version 2.

If the External RADIUS program is enabled, it is used after the user password is verified. The Server sends it the following command:
`nnnnnn LOGIN name@domain attributes settings`
where:

  nnnnnn
    a unique sequence number for this request
  name
    user Account name
  domain
    user Account Domain name
  attributes
    a dictionary with all request attributes.
  settings
    a dictionary with the Account settings.

If the login request is accepted, the Helper program should return a positive response:
`nnnnnn ACCEPT attributes`
where:

  nnnnnn
    the request sequence number
  attributes
    a dictionary with the attributes to be added to the RADIUS response.

If the password was not accepted, a negative response should be returned:
`nnnnnn REJECT optional-error-message`

If the External RADIUS program is enabled, it is used to process the `Start`, `Stop`, and `Interim-Update` accounting requests. The Server sends the following command:
`nnnnnn ACCNT command name@domain attributes`
where:

  nnnnnn
    a unique sequence number for this request
  command
    the accounting command (`started`, `ended`, `updated`)
  name
    user Account name
  domain
    user Account Domain name
  attributes
    a dictionary with request attributes.

The Helper program should return a positive response:
`nnnnnn OK`
where:

  nnnnnn
    the request sequence number

The attributes in dictionaries should use the attribute type numeric values as keys (for example `27` for `Session-Timeout`).

The following attributes are interpreted as 32-bit integer values and they are encoded as numeric strings in dictionaries:
`NAS-Port`, `Service-Type`, `Framed-Protocol`, `Framed-Routing`, `Framed-MTU`, `Framed-Compression`, `Login-Service`, `Login-TCP-Port`, `Framed-IPX-Network`, `Session-Timeout`, `Idle-Timeout`, `Termination-Action`, `Framed-AppleTalk-Link`, `Framed-AppleTalk-Network`, `Event-Timestamp`, `NAS-Port-Type`, `Port-Limit`, `ARAP-Zone-Access`, `Password-Retry`, `Prompt`, `Tunnel-Type`, `Tunnel-Medium-Type`, `Tunnel-Preference`, `Acct-Interim-Interval`, `Acct-Delay-Time`, `Acct-Input-Octets`, `Acct-Output-Octets`, `Acct-Authentic`, `Acct-Session-Time`, `Acct-Input-Packets`, `Acct-Output-Packets`, `Acct-Terminate-Cause`, `Acct-Link-Count`, `Acct-Input-Gigawords`, `Acct-Output-Gigawords`.

The following attributes are interpreted as 32-bit IP addresses and they are encoded as `aaa.bbb.ccc.ddd` strings in dictionaries:
`NAS-IP-Address`, `Framed-IP-Address`, `Framed-IP-Netmask`, `Login-IP-Host`.

The following attributes are ignored in Helper responses:
`User-Name`, `User-Password`, `CHAP-Password`, `State`, `Proxy-State`, `EAP-Message`, `Message-Authenticator`, `Acct-Status-Type`.

All other attribute values are encoded either as a String or as DataBlocks. The Server uses the DataBlocks format for those attribute values that contain bytes outside the hexadecimal 0x20-0x7F range.
The DataBlock format must be used if the value contains binary zero bytes.

If an attribute has multiple values, the attribute value is encoded as an Array.

The following attributes are added to the attribute dictionaries passed to the Helper:

`0`
  the RADIUS protocol request ID. It can be used to detect retransmitted packets (duplicate requests)
`secretKey` (authentication requests only)
  a string value with the RADIUS module "shared secret" setting.
`authData` (authentication requests only)
  a 16-byte DataBlock containing the "authentication data" portion of the RADIUS request.

The Vendor-specific attributes are presented using keys with negative numeric values. The key absolute value is the "VendorID" value. For each VendorID, the associated element is a dictionary. This dictionary keys are Vendor-specific "vendor types", with associated "specific attributes". The "specific attributes" values can be stored as String, DataBlocks, Number, or Arrays of Strings, DataBlocks, and/or Numbers.

Sample session (I: - server commands sent to the program standard input, O: - responses the program writes to its standard output):

  `I: 00001 INTF 1
  O: 00001 OK 1
  I: 00002 LOGIN user1@domain1.com {0=#15; 1="User1";4=10.0.0.1;32="NAS 1";31=4153837164;"-311"={9=#777;10="ZZZ";}; authData=[AbndghAbndgh1sjkjkss3T=]; secretKey=a123;} {RealName="User"; NATIP="192.168.1.3";}
  O: 00002 ACCEPT {8=192.168.1.3; 9=255.255.255.0; 13=(0,3);}
  I: 00003 LOGIN user1@domain1.com {0=#16; 1="uSEr1";32="NAS 2";31=415.5512.12; 8=192.168.1.3; authData=[Abnd278sjkljsljkjksFG=]; secretKey=a123;} {NATIP="10.0.1.114";}
  O: 00003 REJECT
  I: 00004 ACCNT started user1@domain1.com {0=#17;1="uSEr1";32="NAS 2";31=415.5512.12; 8=192.168.1.3;}
  O: 00004 OK
  `

Note: the Server can send several concurrent requests for the same target Account.

Note: the External RADIUS program is called when the target Account is open. In a Dynamic Cluster system this means that External RADIUS programs should run on backend servers, and that External RADIUS programs running on different backend servers will never get requests for the same Account at the same time.

## External CDR Processor

External CDR Processor programs can be used to process CDRs (Call Detail Records) generated with the Signal component when a call is attempted, established, or tiered down. They can also process CDR records generated with CG/PL applications.

The External CDR Processor Interface protocol is based on the generic Helper Protocol.
This manual describes the External CDR Processor Interface Version 1.

If the External CDR Processor program is enabled, the Signal module generated CDRs and sends them to the program.

When a CDR is composed, the Server sends the following command:
`nnnnnn CDR cdr_data`
where:

  nnnnnn
    a unique sequence number for this request
  cdr_data
    CDR data in the Signal component format or in the CG/PL Application format.

when the record is processed, the program should return a positive response:
`nnnnnn OK`

## External Banner System

External Banner System programs can be used to provide XIMSS and other clients with "banner" data (advertising information that a client presents to the user).

The External Banner System Interface protocol is based on the generic Helper Protocol.
This manual describes the External Banner System Interface Version 1.

When a client requests a banner, the Server sends the following command:
`nnnnnn BANNER bannerType [ accountName@domainName ] [ INFO bannerSetting ] [ PREFS bannerPreference ] [ PARAM paramData ]`
where:

  nnnnnn
    a unique sequence number for this request
  bannerType
    if the banner type string specified with the client application (specifies the client application and its banner type, for example: prontoEmailTop, myClientLeftBanner).
  accountName@domainName
    full name of the Account requesting a banner.
  bannerSetting
    (optional) the `BannerInfo` Account Setting value.
  bannerPreference
    (optional) the `BannerClass` Account Preference value.
  paramData
    (optional) the text presentation of the parameter object specified with the client application.

When the record is processed, the program should return a positive response:
`nnnnnn RESULT resultData`
where:

  resultData
    the text presentation of the banner info.

The program can also return a blocking response:
`nnnnnn BLOCK`
The specified bannerType is added to the list of "blocked" types. If any client requests a banner of a "blocked" type, an empty response is returned immediately, without calling the External Banner System program.

If the External Banner System program is not running, any banner request immediately produces an empty response.

CommuniGate® Pro Guide. Copyright © 1998-2012, Stalker Software, Inc.