Content.idl

Go to the documentation of this file.

   /**
 * @file   Content.idl
 * @brief  Set Spam Filter, Antivirus Settings, Attachment Filter.
 *
 * @author Dusan Juhas
 *
 * @copyright Copyright © 2017 Kerio Technologies s.r.o.
 */

#import <kerio/web/idl/SharedStructures.idl>
#import <AdminStructures.idl> //DistanceOrNull

module kerio {
module jsonapi {
module admin {

enum AttachmentAction {
   Block,
   Accept
};

enum AttachmentType {
   FileName,
   MimeType
};

/**
 * Attachment filter rule item
 */
struct AttachmentItem {
   kerio::web::KId      id;
   boolean           enabled;    ///< the rule is in use
   AttachmentType    type;       ///< type of the rule
   string            content;    ///< *,? wildcards are supported
   AttachmentAction  action;        ///< what to do if the rule maches
   string            description;   ///<
};

typedef sequence<AttachmentItem> AttachmentItemList;

/**
 * Attachment filter settings
 */
struct AttachmentSetting {
   boolean                 enabled;       ///< attachment filter is on/off
   boolean                 warnSender;       ///< sender will (not) obtain warning message
   kerio::web::OptionalString forwardOriginal;  ///< where to forward original message
   kerio::web::OptionalString forwardFiltered;  ///< where to forward filtered message
   boolean                 enableZipContentFilter; ///< checks zip content for prohibited extennsions
};

/**
 * Note: fields name and content must be assigned if used in set methods
 */
struct AntivirusOption {
   string   name;
   string   content;
   string   defaultValue;                 ///< read only value
};

typedef sequence<AntivirusOption> AntivirusOptionList;

/**
 * Note: field id must be assigned if used in set methods
 */
struct AntivirusPlugin {
   string            id;                  ///< example: avir_avg
   string            description;         ///< example: AVG Email Server Edition
   boolean           areOptionsAvailable;
   AntivirusOptionList  options;
};

typedef sequence<AntivirusPlugin> AntivirusPluginList;

struct IntegratedEngine {
   boolean     checkForUpdates;  ///< should we periodically ask for a new version?
   long     updatePeriod;     ///< update checking period in hours
   DistanceOrNull databaseAge;      ///< how old is virus database
   DistanceOrNull lastUpdateCheck;  ///< how long is since last database update check
   string      databaseVersion;  ///< virus database version
   string      engineVersion;    ///< scanning engine version
   boolean     isPluginAvailable;   ///< says if plugins dll is on hardrive
   boolean     isLiveProtectionEnabled;
};

/**
 * What to do with an infected file
 */
enum ReactionOnVirus {
   DiscardMessage,      ///< completely dicard the message
   RemoveVirus       ///< deliver the message but remove malicious code
};

/**
 * What to do with a corrupted or encrypted file
 */
enum ReactionOnNotScanned {
   DeliverWithWarning,  ///< deliver original message with prepended warning
   SameAsVirus       ///< the same reaction as for ReactionOnVirus
};

/**
 * Are all possible states covered
 */
enum AntivirusStatus {
   AntivirusOk,      ///< no message is needed
   NoAntivirus,      ///< neither internal nor external antivirus is active
   InternalFailure,  ///< problem with internal intivirus
   ExternalFailure,  ///< problem with external intivirus
   DoubleFailer      ///< both internal and external antivirus has failed
};

struct FoundVirusBehavior {
   ReactionOnVirus            reaction;
   kerio::web::OptionalString forwardOriginal;     ///< should be original message forwarded?
   kerio::web::OptionalString forwardFiltered;     ///< should be filtered message forwarded?
};

struct AntivirusSetting {
   boolean              useIntegrated;    ///< integrated antivirus is used?
   boolean              useExternal;      ///< an external antivirus is used? note: both internal and extenal can be used together
   AntivirusStatus         status;           ///< status of antivirus to be used for informative massage
   AntivirusPluginList     plugins;       ///< list of available antivirus plugins
   string               selectedId;       ///< identifier of currently selected antivirus plugin
   IntegratedEngine     engine;           ///< integrated engine settings
   FoundVirusBehavior      virusReaction;    ///< found virus reaction setting
   ReactionOnNotScanned notScannedReaction;  ///< found corruption or encryption reaction type
};

enum UpdateStatus {
   UpdateStarted,
   UpdateFinished,
   UpdateError,
   UpdateDownloadIni,
   UpdateDownloadData,
   UpdateUpToDate
};

struct IntegratedAvirUpdateStatus {
   UpdateStatus status;                ///< state of update process
   long percent;                       ///< percent of downloaded data
};

enum BlockOrScore {
   BlockMessage,  ///< block the message
   ScoreMessage   ///< add SPAM score to the message
};

/**
 * Custom setting of blacklist spammer IP addresses
 */
struct BlackListSetting {
   boolean        enabled;
   kerio::web::KId   id;         ///< global identifier
   string         name;
   BlockOrScore   action;
   long        score;
};

enum SpamAction {
   LogToSecurity, ///< only log to security log
   BlockAction,   ///< block the meassage
   ScoreAction    ///< increase spam score
};

struct CallerId {
   boolean                 enabled;
   SpamAction              action;
   long                 score;
   boolean                 applyOnTesting;
   kerio::web::OptionalEntity exceptionIpGroup;       ///< switchable custom white list IP group
};

struct Spf {
   boolean                 enabled;
   SpamAction              action;
   long                 score;
   kerio::web::OptionalEntity exceptionIpGroup;       ///< switchable custom white list IP group
};

struct Repellent {
   boolean                 enabled;
   long                 delay;
   kerio::web::OptionalEntity customWhiteList;        ///< switchable custom white list IP group
   boolean                 reportToSecurity;       ///< do (not) report a spam attack to security log
};

enum BayesState {
    Disabled,                                               ///< Bayes database statistics are not provided
   Learning,
   Active
};

/**
 * State of the Greylisting client.
 */
enum GreylistingStatus {
   GreylistingOff,
   GreylistingOn,
   GreylistingError     ///< Greylisting encountered an error. Call Content.testGreylistConnection() for a more detailed error description.
};

struct Greylisting {
   boolean enabled;        ///< is greylisting enabled? 
                        /// When enabled is set to true, the setAntiSpamSetting method attempts to connect to the greylisting service asynchronously. 
                        /// When enabled is set to false, connection to the greylisting service is closed.
   kerio::web::OptionalEntity customWhiteList; ///< switchable custom whitelist IP group
   GreylistingStatus status;  ///< read only: current status
   string messagesAccepted;   ///< read only: messages accepted
   string messagesDelayed;    ///< read only: messages temoprarily rejected
   string messagesSkipped;    ///< read only: messages skipped
};

enum IntegratedAntiSpamStatus {
   AntiSpamReady,
   AntiSpamDisabled,
   AntiSpamNotLicenced,
   AntiSpamNotInitialized,
   AntiSpamNotConnected
};

struct IntegratedAntiSpamEngine {
   boolean enabled;
   long score;           ///< Spam score(default 10)
   long negativeScore;   ///< Score for legit messages (default 0)
   boolean submitSpam;   ///< Submit spam samples(default on)
   boolean submitLegit;  ///< Submit legit samples(default on)
   IntegratedAntiSpamStatus status; ///< [READ-ONLY]
   boolean isLicensed;  ///< [READ-ONLY] Is license valid and not expired? If false engine is not running no matter on value in enabled.
};

struct AntiSpamSetting {
   boolean                 isRatingEnabled;        ///< is spam filter rating enabled?
   boolean                 isRatingRelayEnabled;      ///< is rating of messages sent from trustworthy relay agents enabled?
   long                 tagScore;
   long                 blockScore;
   kerio::web::OptionalString subjectPrefix;          ///< SPAM is marked with this prefix
   boolean                 sendBounce;             ///< send bounce message to the sender of SPAM?
   kerio::web::OptionalString quarantineAddress;         ///< forward SPAM to a Quarantine address?
   kerio::web::OptionalEntity customWhiteList;        ///< switchable custom white list IP group
   BlackListSetting        customBlackList;        ///< switchable custom blacklist list IP group
   boolean                 sendBounceCustom;       ///< send bounce message to the sender if rejection was done by custom rule(s)?
   kerio::web::OptionalString quarantineAddressCustom;   ///< forward custom rules identified SPAM to a Quarantine address?
   boolean                 useSurbl;               ///< use Spam URI Realtime Block List database?
   BayesState              filterStatus;           ///< read only: Bayesian filter status
   long                 learnedAsSpam;          ///< read only: number of messages that Bayesian filter learned as Spam
   long                 learnedAsNotSpam;       ///< read only: number of messages that Bayesian filter learned as NOT a Spam
   boolean                 isCustomSigningKey;        ///< Custom signing key is used for DKIM validation
   CallerId             callerSetting;          ///< Caller ID setting
   string                  callerUrl;              ///< read only: Caller ID URL with detailed info
   Spf                     spfSetting;             ///< Sender Policy Framework setting
   Repellent               repellentSetting;
   Greylisting             greylistingStatus;
   boolean                 useCustomRulesInSmtp;      ///<
   IntegratedAntiSpamEngine    integratedAntiSpamSetting;  ///< Kerio Anti-Spam
};

struct BlackList {
   kerio::web::KId      id;            ///< global identifier
   boolean           enabled;
   string            dnsSuffix;
   string            description;
   BlockOrScore      action;        ///< what to do if IP address is found on blacklist
   long           score;
   boolean           askDirectly;
};

typedef sequence<BlackList> BlackListList;

enum CustomRuleKind {
   Header,
   Body
};

enum CustomRuleType {
   IsEmpty,
   IsMissing,
   ContainsAddress,
   ContainsDomain,
   ContainsSubstring,
   ContainsBinary
};

enum CustomRuleAction {
   TreatAsSpam,
   TreatAsNotSpam,
   IncreaseSpamScore
};

struct CustomRule {
   kerio::web::KId      id;            ///< global identifier
   boolean           enabled;
   CustomRuleKind    kind;
   string            header;
   string            content;
   string            description;
   CustomRuleType    type;
   CustomRuleAction  action;
   long           score;
   DistanceOrNull    lastUsed;
};

typedef sequence<CustomRule> CustomRuleList;

enum HourOrDay {
   Hour,
   Day
};

interface Content {

   /**
    * Add a blacklist item.
    *
    * @param errors - error message list
    * @param items - array of new items
    */
   void addBlackLists(out kerio::web::ErrorList errors, in BlackListList items);

   /**
    * Get antiSPAM settings.
    *
    * @param setting - new antivirus filter settings
    */
   void getAntiSpamSetting(out AntiSpamSetting setting);

   /**
    * Get antivirus filter settings.
    *
    * @param setting - new antivirus filter settings
    */
   void getAntivirusSetting(out AntivirusSetting setting);

   /**
    * Get a list of attachment filter rules.
    *
    * @param filterRules - attachment filter rules
    */
   void getAttachmentRules(out AttachmentItemList filterRules);

   /**
    * Obtain attachment filter settings.
    *
    * @param setting - current attachment filter settings
    */
   void getAttachmentSetting(out AttachmentSetting setting);

   /**
    * When adding a new attachment rule this can be used to find out available values.
    *
    * @param fileNames - list of available file names
    * @param mimeTypes - list of available MIME types
    */
   void getAvailableAttachments(out kerio::web::StringList fileNames, out kerio::web::StringList mimeTypes);

   /**
    * Obtain all blacklist items.
    *
    * @param list - blacklist items
    */
   void getBlackListList(out BlackListList list);

   /**
    * Obtain all custom rules.
    *
    * @param list - custom rules
    * @param totalItems - amount of rules for given search condition, useful when a limit is defined in search query
    * @param query - condition and limit definition (orderBy is ignored)
    */
   void getCustomRuleList(out CustomRuleList list, out long totalItems, in kerio::web::SearchQuery query);

   /**
    * Remove blacklist items.
    *
    * @param errors - error message list
    * @param ids - identifier list of blacklists to be deleted
    */
   void removeBlackLists(out kerio::web::ErrorList errors, in kerio::web::KIdList ids);

   /**
    * Remove custom rules which are not used for a specified time.
    *
    * @param number - how many hours/days is the rule unused
    * @param unit - which unit is used to measure
    */
   void removeUnusedCustomRules(in long number, in HourOrDay unit);

   /**
    * Set antiSPAM filter settings.
    *
    * @param setting - new antivirus filter settings
    */
   void setAntiSpamSetting(in AntiSpamSetting setting);

   /**
    * Set antivirus filter settings.
    *
    * @param errors - error message; Value of inputIndex means type of antivirus (integrated = 0 and external = 1).
    * @param setting - new antivirus filter settingss
    */
   void setAntivirusSetting(out kerio::web::ErrorList errors, in AntivirusSetting setting);

   /**
    * Set list of attachment filter rules.
    *
    * @param filterRules - attachment filter rules
    */
   void setAttachmentRules(in AttachmentItemList filterRules);

   /**
    * Set attachment filter settings.
    *
    * @param setting - new attachment filter settings
    */
   void setAttachmentSetting(in AttachmentSetting setting);

   /**
    * Set blacklist item.
    *
    * @param errors - error message list
    * @param ids - list of blacklist global identifier(s)
    * @param pattern - pattern to use for new values
    */
   void setBlackLists(out kerio::web::ErrorList errors, in kerio::web::KIdList ids, in BlackList pattern);

   /**
    * Set custom rules.
    *
    * @param list - custom rule records
    */
   void setCustomRuleList(in CustomRuleList list);

   /**
    * Test connection to the greylisting service. Returns nothing if successful.
    */
   void testGreylistConnection();

   /**
    * Test connection to the anti-spam service. Returns nothing if successful.
    */
   void testIntegratedAntiSpamEngine(out IntegratedAntiSpamStatus status);

   /**
    * Get progress of antivirus updating.
    *
    * @param status - status of the update process
    */
   void updateAntivirusStatus(out IntegratedAvirUpdateStatus status);

   /**
    * Force update of the integrated antivirus.
    */
   void updateIntegratedAntivirus();
};

}; }; };//end of namespace