Difference between revisions of "AppSuite:OX Guard MailFilter"

(Add guard-backend-mailfilter package info)
 
Line 3: Line 3:
 
It is possible to add the Sieve test “PGP Signature” as well as the action “encrypt incoming” to the mailfilter functionality of Appsuite.  This utilizes the sieve  Extprograms plugin to call Guard through an api to either verify signatures or return the email encrypted.
 
It is possible to add the Sieve test “PGP Signature” as well as the action “encrypt incoming” to the mailfilter functionality of Appsuite.  This utilizes the sieve  Extprograms plugin to call Guard through an api to either verify signatures or return the email encrypted.
  
== Overview: ==
+
== Overview ==
  
The user creates either the filter test “PGP Signature” or action “Encrypt email”.  This creates a sieve rule that calls and external script with the users ID and Context.  Only pre-configured scripts can be called, there isn’t any ability for someone to create their own external scripts to be called.
+
The user creates either the filter test “PGP Signature” or action “Encrypt email”.  This creates a sieve rule that calls an external script with the user's ID and Context.  Only pre-configured scripts can be called, there isn’t any ability for someone to create their own external scripts to be called.
  
Incoming emails then go through the Sieve filter, which then calls the external script with the users ID and Context as parameters.
+
Incoming emails then go through the Sieve filter, which then calls the external script with the user's ID and Context as parameters.
  
The external script calls a Guard server through an api call.  Response is returned to the script.  Either marked as signed, or the encrypted content of the email is returned.
+
The external script calls the Guard server through an api call.  Response is returned to the script.  Either marked as signed, or the encrypted content of the email is returned.
  
 
== Setup: ==
 
== Setup: ==
Line 31: Line 31:
 
Of course, the sieve protocol must be enabled and managesieve must be already working.
 
Of course, the sieve protocol must be enabled and managesieve must be already working.
  
=== Scripts: ===
+
=== Scripts ===
  
There are currently two scripts, one to test the email signatures, another to encrypt the email.  Add/create scripts in the following location (assuming the above configuration).  Replace the username/password rest:secret with the rest username and password configured with Guard.
+
There are currently two scripts, one to test the email signatures, another to encrypt the email.  Add/create scripts in the following location (assuming the above configuration).  Replace the username/password rest:secret with the REST username and password configured with Guard.
  
 
/usr/lib/dovecot/sieve-filter/guard.sh
 
/usr/lib/dovecot/sieve-filter/guard.sh
Line 91: Line 91:
 
<pre>
 
<pre>
 
   yum install open-xchange-guard-backend-mailfilter
 
   yum install open-xchange-guard-backend-mailfilter
</pre>
 
 
=== SUSE ===
 
<pre>
 
  zipper in open-xchange-guard-backend-mailfilter
 
 
</pre>
 
</pre>
  
  
== Configuration: ==
+
== Configuration ==
  
 
The guard mailfilter functionality must be enabled on the middleware.  Recommend adding the configuration to guard-api.properties on the middleware servers:
 
The guard mailfilter functionality must be enabled on the middleware.  Recommend adding the configuration to guard-api.properties on the middleware servers:
Line 111: Line 106:
 
com.openexchange.mail.filter.guard..guardSignatureScript=guard-sig.sh
 
com.openexchange.mail.filter.guard..guardSignatureScript=guard-sig.sh
  
== MailFilter User Interface: ==
+
== MailFilter User Interface ==
  
 
Assuming the user has guard-mail and mailfilter capabilities, they will now be able to add the configured test and actions for Guard.
 
Assuming the user has guard-mail and mailfilter capabilities, they will now be able to add the configured test and actions for Guard.

Latest revision as of 21:56, 5 August 2020

OX Guard MailFilter Integration

It is possible to add the Sieve test “PGP Signature” as well as the action “encrypt incoming” to the mailfilter functionality of Appsuite.  This utilizes the sieve  Extprograms plugin to call Guard through an api to either verify signatures or return the email encrypted.

Overview

The user creates either the filter test “PGP Signature” or action “Encrypt email”.  This creates a sieve rule that calls an external script with the user's ID and Context.  Only pre-configured scripts can be called, there isn’t any ability for someone to create their own external scripts to be called.

Incoming emails then go through the Sieve filter, which then calls the external script with the user's ID and Context as parameters.

The external script calls the Guard server through an api call.  Response is returned to the script.  Either marked as signed, or the encrypted content of the email is returned.

Setup:

Dovecot sieve extension ExtPrograms must be enabled.  This adds three different capabilities to sieve vnd.dovecot.pipe, vnd.dovecot.filter, and vnd.dovecot.exectue (pipe is not required for these scripts), but they are disabled by default.  “Filter” and “execute” must be enabled for users, and then the directories containing the scripts must be configured.

Example configuration:

90-sieve.conf

plugin {  
    sieve = file:~/sieve;active=~/.dovecot.sieve  
    sieve_default = /var/lib/dovecot/sieve/default.sieve  
    sieve_plugins = sieve_extprograms  
    sieve_extensions = +vnd.dovecot.filter +vnd.dovecot.execute  
    # The directory contains the scripts that are available for the filter and execute  
    # commands.  
     sieve_filter_bin_dir = /usr/lib/dovecot/sieve-filter  
     sieve_execute_bin_dir = /usr/lib/dovecot/sieve-execute  
}

Of course, the sieve protocol must be enabled and managesieve must be already working.

Scripts

There are currently two scripts, one to test the email signatures, another to encrypt the email.  Add/create scripts in the following location (assuming the above configuration).  Replace the username/password rest:secret with the REST username and password configured with Guard.

/usr/lib/dovecot/sieve-filter/guard.sh

#!/bin/bash  
GUARD="${GUARD_SERVER:-localhost:8009}"

## Send the stdin to guard using curl, store result

encrypted=$(curl -s -X POST -F file=@- "http://${GUARD}/oxguard/pgpmail?action=encrypt_mime&user=${1}&context=${2}&respondWithJSON=true" --user rest:secret )

## Check for errors and basic sanity check

if [[ $encrypted == \{\"error* ]] ;  
then  
  logger "Guard sieve encrypter error: $encrypted"  
  ## Error, exit  
  exit 1  
fi

## Return the encrypted text. Preserve /r

echo -e "$encrypted"

/usr/lib/dovecot/sieve-execute/guard-sig.sh

#!/bin/bash  
GUARD="${GUARD_SERVER:-localhost:8009}"

## Send the stdin to guard using curl, store result

verified=$(curl -s -X POST -F file=@- "http://${GUARD}/oxguard/pgpmail?action=verify&user=${1}&context=${2}&simple=true&respondWithJSON=true" --user rest:secret )  
logger $verified  

## Check if returns true

if [[ $verified == "{\"data\":true}" ]] ;  
then  
  exit 0  
fi  
if [[ $verified == \{\"error* ]] ;  
then  
  logger "Guard sieve signature error: $verified"  
fi  
exit 1

There is no requirement that these scripts are in different directories.  Dovecot requires that scripts are not world writable.  In addition, as these scripts contain the rest username/password, recommend changing the owner to vmail and restricting permissions to 700

Middleware Packages

On the middleware nodes the open-xchange-guard-backend-mailfilter package needs to be installed. This should be on the same nodes as the open-xchange-guard-backend-plugin package is installed.

Debian

  apt-get install open-xchange-guard-backend-mailfilter

Redhat

  yum install open-xchange-guard-backend-mailfilter


Configuration

The guard mailfilter functionality must be enabled on the middleware.  Recommend adding the configuration to guard-api.properties on the middleware servers:

com.openexchange.mail.filter.guard.sieveEnabled=true

The script names may be configured differently, but default to the following:

com.openexchange.mail.filter.guard.guardEncryptScript=guard.sh

com.openexchange.mail.filter.guard..guardSignatureScript=guard-sig.sh

MailFilter User Interface

Assuming the user has guard-mail and mailfilter capabilities, they will now be able to add the configured test and actions for Guard.