AppSuite:OX Guard: Difference between revisions
No edit summary |
|||
(8 intermediate revisions by 2 users not shown) | |||
Line 12: | Line 12: | ||
OX Guard is a fully integrated security add-on to OX App Suite that provides end users with a flexible email and file encryption solution. OX Guard is a highly scalable, multi server, feature rich solution that is so simple-to-use that end users will actually use it. With a single click a user can take control of their security and send secure emails and share encrypted files. This can be done from any device to both OX App Suite and non-OX App Suite users. | OX Guard is a fully integrated security add-on to OX App Suite that provides end users with a flexible email and file encryption solution. OX Guard is a highly scalable, multi server, feature rich solution that is so simple-to-use that end users will actually use it. With a single click a user can take control of their security and send secure emails and share encrypted files. This can be done from any device to both OX App Suite and non-OX App Suite users. | ||
OX Guard uses standard PGP encryption for the encryption of email and files. PGP has been around for a long time, yet has not really caught on with the masses. This is generally blamed on the confusion and complications of managing the keys, understanding trust, PGP format types, and lack of trusted central key repositories. Guard simplifies all of this, making PGP encryption as easy as a one click process, with no keys to keep track of, yet the options of advanced PGP management for those that know how. | OX Guard uses standard PGP encryption for the encryption of email and files. S/Mime is also supported since version 2.10.7. PGP has been around for a long time, yet has not really caught on with the masses. This is generally blamed on the confusion and complications of managing the keys, understanding trust, PGP format types, and lack of trusted central key repositories. Guard simplifies all of this, making PGP encryption as easy as a one click process, with no keys to keep track of, yet the options of advanced PGP management for those that know how. | ||
This article will guide you through the installation of Guard and describes the basic configuration and software requirements. As it is intended as a quick walk-through it assumes an existing installation of the operating system including a single server App Suite setup as well as average system administration skills. This guide will also show you how to setup a basic installation with none of the typically used distributed environment settings. The objective of this guide is: | This article will guide you through the installation of Guard and describes the basic configuration and software requirements. As it is intended as a quick walk-through it assumes an existing installation of the operating system including a single server App Suite setup as well as average system administration skills. This guide will also show you how to setup a basic installation with none of the typically used distributed environment settings. The objective of this guide is: | ||
Line 63: | Line 63: | ||
=== Important Notes === | === Important Notes === | ||
==== | ==== Customization ==== | ||
OX Guard version supports branding / theming using the configuration cascade, defining a templateID for a user or context. Check the [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardCustomization OX Guard | OX Guard version supports branding / theming using the configuration cascade, defining a templateID for a user or context. Check the [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardCustomization OX Guard Customization] article for more details. | ||
==== Mail Resolver ==== | ==== Mail Resolver ==== | ||
Line 96: | Line 96: | ||
The components required for the Guard server <code>open-xchange-guard</code> and either <code>open-xchange-guard-file-storage</code> or <code>open-xchange-guard-s3-storage</code> depending on what storage you want to use. The examples below make use of the <code>open-xchange-guard-file-storage</code>. Adjust the commands accordingly to fit your needs. In addition <code>open-xchange</code> and <code>open-xchange-core</code> are required to run OX Guard. | The components required for the Guard server <code>open-xchange-guard</code> and either <code>open-xchange-guard-file-storage</code> or <code>open-xchange-guard-s3-storage</code> depending on what storage you want to use. The examples below make use of the <code>open-xchange-guard-file-storage</code>. Adjust the commands accordingly to fit your needs. In addition <code>open-xchange</code> and <code>open-xchange-core</code> are required to run OX Guard. | ||
=== Debian Linux 9.0 (Stretch) === | <!-- === Debian Linux 9.0 (Stretch) === | ||
If not already done, add the following repositories to your Open-Xchange apt configuration: | If not already done, add the following repositories to your Open-Xchange apt configuration: | ||
Line 112: | Line 112: | ||
$ apt-get update | $ apt-get update | ||
$ apt-get install open-xchange-guard open-xchange-guard-file-storage | $ apt-get install open-xchange-guard open-xchange-guard-file-storage | ||
The packages <code>open-xchange-guard-ui</code> <code>open-xchange-rest</code> and <code>open-xchange-guard-backend-plugin</code> missing in the distributed installation have to be installed on the node running the middleware. The package <code>open-xchange-guard-ui-static</code> must be installed in the frontend (apache node). | The packages <code>open-xchange-guard-ui</code> <code>open-xchange-rest</code> and <code>open-xchange-guard-backend-plugin</code> missing in the distributed installation have to be installed on the node running the middleware. The package <code>open-xchange-guard-ui-static</code> must be installed in the frontend (apache node). --> | ||
=== Debian Linux 10.0 (Buster) *Version 2.10.3+ only* === | <!-- === Debian Linux 10.0 (Buster) *Version 2.10.3+ only* === | ||
If not already done, add the following repositories to your Open-Xchange apt configuration: | If not already done, add the following repositories to your Open-Xchange apt configuration: | ||
Line 130: | Line 130: | ||
$ apt-get update | $ apt-get update | ||
$ apt-get install open-xchange-guard open-xchange-guard-file-storage | $ apt-get install open-xchange-guard open-xchange-guard-file-storage | ||
The packages <code>open-xchange-guard-ui</code> <code>open-xchange-rest</code> and <code>open-xchange-guard-backend-plugin</code> missing in the distributed installation have to be installed on the node running the middleware. The package <code>open-xchange-guard-ui-static</code> must be installed in the frontend (apache node). | The packages <code>open-xchange-guard-ui</code> <code>open-xchange-rest</code> and <code>open-xchange-guard-backend-plugin</code> missing in the distributed installation have to be installed on the node running the middleware. The package <code>open-xchange-guard-ui-static</code> must be installed in the frontend (apache node). --> | ||
=== Debian Linux 11.0 (Bullseye) *Version 2.10.6+ only* === | === Debian Linux 11.0 (Bullseye) *Version 2.10.6+ only* === | ||
Line 208: | Line 208: | ||
$ yum update | $ yum update | ||
$ yum install open-xchange-guard open-xchange-guard-file-storage | $ yum install open-xchange-guard open-xchange-guard-file-storage | ||
The packages <code>open-xchange-guard-ui</code> <code>open-xchange-rest</code> and <code>open-xchange-guard-backend-plugin</code> missing in the distributed installation have to be installed on the node running the middleware. The package <code>open-xchange-guard-ui-static</code> must be installed in the frontend (apache node). | |||
=== Redhat Enterprise Linux 8 === | |||
If not already done, add the following repositories to your Open-Xchange yum configuration: | |||
[open-xchange-guard-stable-guard] | |||
name=Open-Xchange-guard-stable-guard | |||
baseurl=https://software.open-xchange.com/products/guard/stable/guard/RHEL8/ | |||
gpgkey=https://software.open-xchange.com/oxbuildkey.pub | |||
enabled=1 | |||
gpgcheck=1 | |||
metadata_expire=0m | |||
[ox-backend] | |||
name=Open-Xchange-backend | |||
baseurl=https://software.open-xchange.com/products/appsuite/stable/backend/RHEL8/ | |||
gpgkey=https://software.open-xchange.com/oxbuildkey.pub | |||
enabled=1 | |||
gpgcheck=1 | |||
metadata_expire=0m | |||
and then run for a single node installation: | |||
$ dnf update | |||
$ dnf install open-xchange-rest open-xchange-guard open-xchange-guard-file-storage open-xchange-guard-ui open-xchange-guard-ui-static open-xchange-guard-backend-plugin | |||
or the following for a distributed installation: | |||
$ dnf update | |||
$ dnf install open-xchange-guard open-xchange-guard-file-storage | |||
The packages <code>open-xchange-guard-ui</code> <code>open-xchange-rest</code> and <code>open-xchange-guard-backend-plugin</code> missing in the distributed installation have to be installed on the node running the middleware. The package <code>open-xchange-guard-ui-static</code> must be installed in the frontend (apache node). | The packages <code>open-xchange-guard-ui</code> <code>open-xchange-rest</code> and <code>open-xchange-guard-backend-plugin</code> missing in the distributed installation have to be installed on the node running the middleware. The package <code>open-xchange-guard-ui-static</code> must be installed in the frontend (apache node). | ||
Line 242: | Line 273: | ||
This section contains information about updating a 2.10.0 version (e.g. for patch fixes). Upgrading from prior versions is discussed in different articles. | This section contains information about updating a 2.10.0 version (e.g. for patch fixes). Upgrading from prior versions is discussed in different articles. | ||
=== Debian Linux 9.0 (Stretch) === | <!-- === Debian Linux 9.0 (Stretch) === | ||
If not already done, add the following repositories to your Open-Xchange apt configuration: | If not already done, add the following repositories to your Open-Xchange apt configuration: | ||
Line 256: | Line 287: | ||
If you want to see, what apt-get is going to do without actually doing it, you can run: | If you want to see, what apt-get is going to do without actually doing it, you can run: | ||
$ apt-get dist-upgrade -s</source> | $ apt-get dist-upgrade -s</source> --> | ||
=== Debian Linux 10.0 (Buster) === | <!-- === Debian Linux 10.0 (Buster) === | ||
If not already done, add the following repositories to your Open-Xchange apt configuration: | If not already done, add the following repositories to your Open-Xchange apt configuration: | ||
Line 264: | Line 295: | ||
deb <https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/guard/stable/guard/updates/DebianBuster /> | deb <https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/guard/stable/guard/updates/DebianBuster /> | ||
deb <https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/backend/DebianBuster /</source>> | deb <https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/backend/DebianBuster /</source>> | ||
Then run: | |||
$ apt-get update | |||
$ apt-get dist-upgrade</source> | |||
If you want to see, what apt-get is going to do without actually doing it, you can run: | |||
$ apt-get dist-upgrade -s</source> --> | |||
=== Debian Linux 11.0 (Bullseye) === | |||
If not already done, add the following repositories to your Open-Xchange apt configuration: | |||
deb <https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/guard/stable/guard/updates/DebianBullseye /> | |||
deb <https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/backend/DebianBullseye /</source>> | |||
Then run: | Then run: | ||
Line 273: | Line 320: | ||
$ apt-get dist-upgrade -s</source> | $ apt-get dist-upgrade -s</source> | ||
Line 324: | Line 372: | ||
$ yum update | $ yum update | ||
$ yum upgrade</source> | $ yum upgrade</source> | ||
=== Redhat Enterprise Linux 8=== | |||
If not already done, add the following repositories to your Open-Xchange yum configuration: | |||
[open-xchange-guard-stable-guard-updates] | |||
name=Open-Xchange-guard-stable-guard-updates | |||
baseurl=https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/guard/stable/guard/updates/RHEL7/ | |||
gpgkey=https://software.open-xchange.com/oxbuildkey.pub | |||
enabled=1 | |||
gpgcheck=1 | |||
metadata_expire=0m | |||
[ox-backend] | |||
name=Open-Xchange-backend | |||
baseurl=https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/backend/updates/RHEL7/ | |||
gpgkey=https://software.open-xchange.com/oxbuildkey.pub | |||
enabled=1 | |||
gpgcheck=1 | |||
metadata_expire=0m</source> | |||
and then run: | |||
$ dnf update | |||
$ dnf upgrade</source> | |||
Line 482: | Line 557: | ||
Guard provides three capabilities for users in the environment as well as a basic "core" level: | Guard provides three capabilities for users in the environment as well as a basic "core" level: | ||
'''PGP''' | |||
* Guard: <code>com.openexchange.capability.guard</code> | * Guard: <code>com.openexchange.capability.guard</code> | ||
Line 488: | Line 565: | ||
* Guard Docs: <code>com.openexchange.capability.guard-docs</code> | * Guard Docs: <code>com.openexchange.capability.guard-docs</code> | ||
The "core" Guard enabled a basic read functionality for Guard encrypted emails. We recommend enabling this for all users, as this allows all recipients to read Guard emails sent to them. Great opportunity for upsell. Recipients with only Guard enabled can then do a secure reply to the sender, but they can't start a new email or add recipients. | '''S/Mime''' | ||
* S/Mime: <code>com.openexchange.capability.smime</code> | |||
The "core" Guard enabled a basic read functionality for Guard PGP encrypted emails. We recommend enabling this for all users, as this allows all recipients to read Guard emails sent to them. Great opportunity for upsell. Recipients with only Guard enabled can then do a secure reply to the sender, but they can't start a new email or add recipients. | |||
'''Guard Mail''', '''Guard Drive''' and '''Guard Docs''' are additional options for users. "Guard Mail" allows users the full functionality of Guard emails. "Guard Drive" allows for encryption and decryption of Drive files and "Guard Docs" allows direct integration of Guard into Documents. | '''Guard Mail''', '''Guard Drive''' and '''Guard Docs''' are additional options for users. "Guard Mail" allows users the full functionality of Guard emails. "Guard Drive" allows for encryption and decryption of Drive files and "Guard Docs" allows direct integration of Guard into Documents. | ||
'''S/Mime''' enables S/Mime functionality for users (as of 2.10.7). May be used alone or with the above Guard capabilities. | |||
==== Guard Mail: ==== | Each of those Guard components is enabled for all users that have the according capability configured. Please note that users need to have the Drive permission set to use Guard Drive. So the users that have Guard Drive enabled must be a subset of those users with OX Drive permission. Since v7.6.0 we enforce this via the default configuration. Those capabilities can be activated for specific user by using the Open-Xchange provisioning scripts: | ||
==== Guard PGP Mail: ==== | |||
<source lang="bash">$ /opt/open-xchange/sbin/changeuser -c 1 -A oxadmin -P admin_password -u testuser --config/com.openexchange.capability.guard-mail=true</source> | <source lang="bash">$ /opt/open-xchange/sbin/changeuser -c 1 -A oxadmin -P admin_password -u testuser --config/com.openexchange.capability.guard-mail=true</source> | ||
Line 501: | Line 584: | ||
<source lang="bash">$ /opt/open-xchange/sbin/changeuser -c 1 -A oxadmin -P admin_password -u testuser --config/com.openexchange.capability.guard-drive=true</source> | <source lang="bash">$ /opt/open-xchange/sbin/changeuser -c 1 -A oxadmin -P admin_password -u testuser --config/com.openexchange.capability.guard-drive=true</source> | ||
'''Please Note''': Guard Drive requires Guard Mail to be configured for the user as well. In addition, these capabilities may be configured globally by editing the <code>guard-api.properties</code> file on the OX backend. | '''Please Note''': Guard Drive requires Guard Mail to be configured for the user as well. In addition, these capabilities may be configured globally by editing the <code>guard-api.properties</code> file on the OX backend. | ||
=== S/Mime (as of 2.10.7) === | |||
See [[AppSuite:OX_Guard_Smime | OX Guard S/Mime]] for more details on S/Mime | |||
=== External Guest recipients === | === External Guest recipients === | ||
Line 527: | Line 614: | ||
==== External ==== | ==== External ==== | ||
Starting with Guard 2.0, Guard will use public PGP Key servers if configured to find PGP Public keys. | Starting with Guard 2.0, Guard will use public PGP Key servers if configured to find PGP Public keys. | ||
External PGP servers to use can be configured in the guard.properties file on the Guard servers. These can be "trusted" or "untrusted" servers. Trusted servers might be internal servers containing known, trusted keys. Untrusted servers may be public servers that are not necessarily to be trusted (users will have keys marked as trusted or untrusted). | |||
<source lang="bash"> | <source lang="bash">com.openexchange.guard.trustedPGPDirectory = hkp://localservice.somewhere:113711</source> | ||
<source lang="bash">com.openexchange.guard.untrustedPGPDirectory = hkp://keys.gnupg.net:11371, hkp://pgp.mit.edu:11371</source> | |||
'''Please Note''' PGP | '''Please Note''' PGP key servers by default append the path /pks when the record is obtained from an SRV record. The proxy (also included in Apache config above) routes anything under /pks to the OX Guard PGP server. | ||
<source lang="bash">ProxyPass /pks balancer://oxguard/pgp</source> | <source lang="bash">ProxyPass /pks balancer://oxguard/pgp</source> | ||
Latest revision as of 07:49, 8 July 2024
OX Guard (Version 2.10)
For previous versions of OX Guard, please click here
- Installation and information of OX Guard 2.0 - 2.2
- Installation and information of OX Guard 2.4 - 2.8
If upgrading from 2.6 or 2.8, please see
Overview
OX Guard is a fully integrated security add-on to OX App Suite that provides end users with a flexible email and file encryption solution. OX Guard is a highly scalable, multi server, feature rich solution that is so simple-to-use that end users will actually use it. With a single click a user can take control of their security and send secure emails and share encrypted files. This can be done from any device to both OX App Suite and non-OX App Suite users.
OX Guard uses standard PGP encryption for the encryption of email and files. S/Mime is also supported since version 2.10.7. PGP has been around for a long time, yet has not really caught on with the masses. This is generally blamed on the confusion and complications of managing the keys, understanding trust, PGP format types, and lack of trusted central key repositories. Guard simplifies all of this, making PGP encryption as easy as a one click process, with no keys to keep track of, yet the options of advanced PGP management for those that know how.
This article will guide you through the installation of Guard and describes the basic configuration and software requirements. As it is intended as a quick walk-through it assumes an existing installation of the operating system including a single server App Suite setup as well as average system administration skills. This guide will also show you how to setup a basic installation with none of the typically used distributed environment settings. The objective of this guide is:
- To setup a single server installation
- To setup a single Guard instance on an existing Open-Xchange installation, no cluster
- To use the database service on the existing Open-Xchange installation for Guard, no replication
- To provide a basic configuration setup, no mail server configuration
Key Features
- Simple security at the touch of a button
- Provides user based security - Separate from provider
- Supplementary security to Provider based security - Layered
- Powerful features yet simple to use and understand
- Security - Inside and outside of the OX environment
- Email and Drive integration
- Uses proven PGP security
Availability
If an OX App Suite customer would like to evaluate OX Guard integration, the first step is to contact OX Sales. OX Sales will then work on the request and send prices and license/API (for the hosted infrastructure) key details to the customer.
Requirements
Please review OX Guard Requirements for a full list of requirements.
Since OX Guard is a Microservice it can either be added to an existing Open-Xchange installation or it can be deployed on a dedicated environment. The version of Guard installed is dependent on the Appsuite version installed. Please refer to the version matrix below.
Prerequisites
- Open-Xchange REST API
- Grizzly HTTP connector (open-xchange-grizzly)
- A supported Java Virtual Machine (Java 8)
- An Open-Xchange App Suite installation (see version Matrix)
- Please Note: To get access to the latest minor features and bug fixes, you need to have a valid license. The article Updating OX-Packages explains how that can be done.
Version Matrix
Core Version | Guard Version |
---|---|
7.10.5 | 2.10.5 |
7.10.6 | 2.10.6 |
Important Notes
Customization
OX Guard version supports branding / theming using the configuration cascade, defining a templateID for a user or context. Check the OX Guard Customization article for more details.
Mail Resolver
READ THIS VERY CAREFULLY; BEFORE PROCEEDING WITH GUARD INSTALLATION!
The Guard installation must be able to determine if an email recipient is a local OX user or if it should be a guest account. The default MailResolver uses the context domain name to do this. On many installations, domains may extend across multiple context and multiple database shards. In these cases, the default MailResolver won't work. In addition, if a custom authentication package is used, the Mail Resolver will likely not work.
Once Guard is installed, please be sure to test the mail resolver using:
/opt/open-xchange/sbin/guard test email@domain
to see if the mail Resolver works.
If the test does not work, you will likely need a custom Mail Resolver. Please see Mail Resolver page
This resolver software depends heavily on your local deployment.
Download and Installation
General
The installation of the open-xchange-guard-backend-plugin
package which is required for Guard and the main open-xchange-guard
package in version 2.4.0 or higher will eventually execute database update tasks if installed and activated. Please take this into account.
There are several components to the Guard service. They can be all installed on the same server as the OX middleware or on a separate server.
The components required for the OX middleware are: open-xchange-rest
, open-xchange-guard-backend-plugin
and open-xchange-guard-ui
.
The components required for the OX frontend are: open-xchange-guard-ui-static
and optionally open-xchange-guard-help-en-us
(or preferred language for help files).
The components required for the Guard server open-xchange-guard
and either open-xchange-guard-file-storage
or open-xchange-guard-s3-storage
depending on what storage you want to use. The examples below make use of the open-xchange-guard-file-storage
. Adjust the commands accordingly to fit your needs. In addition open-xchange
and open-xchange-core
are required to run OX Guard.
Debian Linux 11.0 (Bullseye) *Version 2.10.6+ only*
If not already done, add the following repositories to your Open-Xchange apt configuration:
deb https://software.open-xchange.com/products/guard/stable/guard/DebianBullseye / deb https://software.open-xchange.com/products/appsuite/stable/backend/DebianBullseye /
and then run for a single node installation:
$ apt-get update $ apt-get install open-xchange-rest open-xchange-guard open-xchange-guard-file-storage open-xchange-guard-ui open-xchange-guard-ui-static open-xchange-guard-backend-plugin
or the following for a distributed installation:
$ apt-get update $ apt-get install open-xchange-guard open-xchange-guard-file-storage
The packages open-xchange-guard-ui
open-xchange-rest
and open-xchange-guard-backend-plugin
missing in the distributed installation have to be installed on the node running the middleware. The package open-xchange-guard-ui-static
must be installed in the frontend (apache node).
Redhat Enterprise Linux 7 or CentOS 7
If not already done, add the following repositories to your Open-Xchange yum configuration:
[open-xchange-guard-stable-guard] name=Open-Xchange-guard-stable-guard baseurl=https://software.open-xchange.com/products/guard/stable/guard/RHEL7/ gpgkey=https://software.open-xchange.com/oxbuildkey.pub enabled=1 gpgcheck=1 metadata_expire=0m
[ox-backend] name=Open-Xchange-backend baseurl=https://software.open-xchange.com/products/appsuite/stable/backend/RHEL7/ gpgkey=https://software.open-xchange.com/oxbuildkey.pub enabled=1 gpgcheck=1 metadata_expire=0m
and then run for a single node installation:
$ yum update $ yum install open-xchange-rest open-xchange-guard open-xchange-guard-file-storage open-xchange-guard-ui open-xchange-guard-ui-static open-xchange-guard-backend-plugin
or the following for a distributed installation:
$ yum update $ yum install open-xchange-guard open-xchange-guard-file-storage
The packages open-xchange-guard-ui
open-xchange-rest
and open-xchange-guard-backend-plugin
missing in the distributed installation have to be installed on the node running the middleware. The package open-xchange-guard-ui-static
must be installed in the frontend (apache node).
Redhat Enterprise Linux 8
If not already done, add the following repositories to your Open-Xchange yum configuration:
[open-xchange-guard-stable-guard] name=Open-Xchange-guard-stable-guard baseurl=https://software.open-xchange.com/products/guard/stable/guard/RHEL8/ gpgkey=https://software.open-xchange.com/oxbuildkey.pub enabled=1 gpgcheck=1 metadata_expire=0m
[ox-backend] name=Open-Xchange-backend baseurl=https://software.open-xchange.com/products/appsuite/stable/backend/RHEL8/ gpgkey=https://software.open-xchange.com/oxbuildkey.pub enabled=1 gpgcheck=1 metadata_expire=0m
and then run for a single node installation:
$ dnf update $ dnf install open-xchange-rest open-xchange-guard open-xchange-guard-file-storage open-xchange-guard-ui open-xchange-guard-ui-static open-xchange-guard-backend-plugin
or the following for a distributed installation:
$ dnf update $ dnf install open-xchange-guard open-xchange-guard-file-storage
The packages open-xchange-guard-ui
open-xchange-rest
and open-xchange-guard-backend-plugin
missing in the distributed installation have to be installed on the node running the middleware. The package open-xchange-guard-ui-static
must be installed in the frontend (apache node).
Univention Corporate Server
If you have purchased the OX App Suite for UCS, the OX Guard is part of the offering. OX Guard is available in the Univention App Center. Please check the UMC module App Center for the installation of the OX Guard at your already available environment.
Please note: By default, OX Guard generates the link to the secure content for external recipients on the basis of the local fully qualified domain name (FQDN). If the local FQDN is not reachable from the Internet, it has to be specified manually. This can be done by setting a UCR variable, e.g. via the UMC module "Univention Configuration Registry". The variable has to contain the external FQDN of the OX Guard system:
oxguard/cfg/guard.properties/com.openexchange.guard.externalEmailURL=HOSTNAME.DOMAINNAME
Update OX Guard
This section contains information about updating a 2.10.0 version (e.g. for patch fixes). Upgrading from prior versions is discussed in different articles.
Debian Linux 11.0 (Bullseye)
If not already done, add the following repositories to your Open-Xchange apt configuration:
deb <https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/guard/stable/guard/updates/DebianBullseye /> deb <https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/backend/DebianBullseye /</source>>
Then run:
$ apt-get update $ apt-get dist-upgrade</source>
If you want to see, what apt-get is going to do without actually doing it, you can run:
$ apt-get dist-upgrade -s</source>
Redhat Enterprise Linux 7 or CentOS 7
If not already done, add the following repositories to your Open-Xchange yum configuration:
[open-xchange-guard-stable-guard-updates] name=Open-Xchange-guard-stable-guard-updates baseurl=https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/guard/stable/guard/updates/RHEL7/ gpgkey=https://software.open-xchange.com/oxbuildkey.pub enabled=1 gpgcheck=1 metadata_expire=0m
[ox-backend] name=Open-Xchange-backend baseurl=https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/backend/updates/RHEL7/ gpgkey=https://software.open-xchange.com/oxbuildkey.pub enabled=1 gpgcheck=1 metadata_expire=0m</source>
and then run:
$ yum update $ yum upgrade</source>
Redhat Enterprise Linux 8
If not already done, add the following repositories to your Open-Xchange yum configuration:
[open-xchange-guard-stable-guard-updates] name=Open-Xchange-guard-stable-guard-updates baseurl=https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/guard/stable/guard/updates/RHEL7/ gpgkey=https://software.open-xchange.com/oxbuildkey.pub enabled=1 gpgcheck=1 metadata_expire=0m
[ox-backend] name=Open-Xchange-backend baseurl=https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/backend/updates/RHEL7/ gpgkey=https://software.open-xchange.com/oxbuildkey.pub enabled=1 gpgcheck=1 metadata_expire=0m</source>
and then run:
$ dnf update $ dnf upgrade</source>
Univention Corporate Server
If you have purchased the OX App Suite for UCS, the OX Guard is part of the offering. OX Guard is available in the Univention App Center. Please check the UMC module App Center for the update of the OX Guard.
Configuration
The following gives an overview of the most important settings to enable Guard for users on the Open-Xchange installation. Some of those settings have to be modified in order to establish the database and REST API access from the Guard service. All settings relating to the Guard backend component are located in the configuration file guard-core.properties
located in /opt/open-xchange/etc
. The default configuration should be sufficient for a basic "up-and-running" setup (with the exception of defining the database username and password). Please refer to the inline documentation of the configuration file for more advanced options. Additional information can be found in the Guard Configuration article.
Basic Configuration
$ vim /opt/open-xchange/etc/guard-core.properties
Guard database for storing Guard user information, main lookup tables:
com.openexchange.guard.oxguardDatabaseHostname=localhost
Guard database that stores keys for guest users. May be the same as above. New guest shards will be created on this database as needed. If not supplied, will use the oxguardDatabaseHostname
:
com.openexchange.guard.oxguardShardDatabase=localhost
Username and Password for the databases above:
com.openexchange.guard.databaseUsername=openexchange
com.openexchange.guard.databasePassword=db_password
Open-Xchange REST API host:
com.openexchange.guard.restApiHostname=localhost
Open-Xchange REST API username and password (need to be defined in the OX backend in the "Configure services" below):
com.openexchange.guard.restApiUsername=apiusername
com.openexchange.guard.restApiPassword=apipassword
External URL for this Open-Xchange installation. This setting will be used to generate the link to the secure content for external recipients:
com.openexchange.guard.externalEmailURL=URL_TO_OX
Middleware Configuration on OX Guard node
If you are installing OX Guard on a node that until yet did not host an Open-Xchange middleware you have to additionally configure some parts of the following properties files:
configdb.properties
: information about the existing configuration database.server.properties
: information about the connections have to be set.system.properties
: at leastSERVER_NAME
should be set.
Sevices Configuration
Apache
Configure the mod_proxy_http
module by adding the Guard API.
Debian GNU/Linux 9.0 and 10.0
$ vim /etc/apache2/sites-enabled/000-default.conf
Redhat Enterprise Linux 6/7 or CentOS 6/7
$ vim /etc/httpd/conf.d/ox.conf
Add the following section into VirtualHost definition:
<Directory /var/www/html/guard> Options -Indexes </Directory>
Debian GNU/Linux 9.0 and 10.0
$ vim /etc/apache2/conf-enabled/proxy_http.conf
Redhat Enterprise Linux 6/7 or CentOS 6/7
$ vim /etc/httpd/conf.d/proxy_http.conf
<Proxy balancer://oxguard> Order deny,allow Allow from all BalancerMember http://localhost:8009/ timeout=1800 smax=0 ttl=60 retry=60 loadfactor=100 route=OX1 ProxySet stickysession=JSESSIONID|jsessionid scolonpathdelim=ON SetEnv proxy-initial-not-pooled SetEnv proxy-sendchunked </Proxy> ProxyPass /appsuite/api/oxguard balancer://oxguard/oxguard ProxyPass /pks balancer://oxguard/pgp ProxyPass /.well-known/openpgpkey/hu balancer://oxguard/hu
Please Note: The Guard API settings must be inserted before the existing ProxyPass /appsuite/api
parameter.
Also Note: If you already have a Proxy balancer for the OX backend with the same URL (say http://localhost:8080) then you don't need the second BalancerMember entry, and you can just have the ProxyPass address that balancer instead.
After the configuration is done, restart the Apache webserver
$ apachectl restart
Open-Xchange Middleware Configuration
Edit the guard-api.properties
configuration file for the OX backend where the guard-backend-plugin was installed. Please remove comments in front of the following settings to the configuration file guard-api.properties
on the Open-Xchange backend servers:
$ vim /opt/open-xchange/etc/guard-api.properties
# OX Guard general permission, required to activate Guard in the AppSuite UI.
com.openexchange.capability.guard=true
# Default theme template id for all users that have no custom template id configured.
com.openexchange.guard.templateID=0
Configure the API username and password that you assigned to Guard in the server.properties
file:
$ vim /opt/open-xchange/etc/server.properties
# Specify the user name used for HTTP basic auth by internal REST servlet
com.openexchange.rest.services.basic-auth.login=apiusername
# Specify the password used for HTTP basic auth by internal REST servlet
com.openexchange.rest.services.basic-auth.password=apipassword
Finally, the OX backend needs to know where the Guard server is located. This is used to notify the Guard server of changes in users, and to send emails marked for signature. The URL for the Guard server should include the URL suffix /guardadmin
. In the event of a cluster setup, any Guard server can be referenced here, as it is not session specific, though ideally would have a HTTP load balancer/failover URL:
$ vim /opt/open-xchange/etc/guard-api.properties
# Specifies the URI to the OX Guard end-point; e.g. http://guard.host.invalid:8081/guardadmin
# Default is empty
com.openexchange.guard.endpoint=http://guardserver:8009/guardadmin
Restart the OX backend
$ /etc/init.d/open-xchange restart
SELinux
Running SELinux prohibits your local Open-Xchange backend service to connect to localhost:8009, which is where the Guard backend service listens to. In order to allow localhost connections to 8009 execute the following:
$ setsebool -P httpd_can_network_connect 1
Generating the oxguardpass
Once the Guard configuration (database and backend configuration) and the service configuration has been applied, the Guard administration script needs to be executed in order to create the master password file in /opt/open-xchange/etc/oxguardpass
. The initiation only needs to be done once for a multi server setup, for details please see the sections Optional and/or Clustering.
Please Note: If you run a cluster of OX / Guard nodes, only execute this command on ONE node. Not on all nodes! See OX Guard Clustering for details.
$ /opt/open-xchange/sbin/guard --init
Please Note: It is important to understand that the master password file located at /opt/open-xchange/etc/oxguardpass
is required to reset user passwords; without them the administrator will not be able to reset user passwords anymore in the future. The file contains the passwords used to encrypt the master database key, as well as passwords used to encrypt protected data in the users table. It must be the same on all Guard servers.
Test Setup
Not required, but it is a good idea to test the Guard setup before enabling for any users. The test function will verify that Guard has a good connection to the OX backend, and that it can resolve email addresses to users.
To test, use an email address that exists on the OX backend (john@example.com for this example)
/opt/open-xchange/sbin/guard --test john@example.com
Guard should return information from the OX backend regarding the user associated with "john@example.com". Problems resolving information for the user should be resolved before using Guard. Check Rest API passwords and settings if errors returned.
Enabling Guard for Users
Guard provides three capabilities for users in the environment as well as a basic "core" level:
PGP
- Guard:
com.openexchange.capability.guard
- Guard Mail:
com.openexchange.capability.guard-mail
- Guard Drive:
com.openexchange.capability.guard-drive
- Guard Docs:
com.openexchange.capability.guard-docs
S/Mime
- S/Mime:
com.openexchange.capability.smime
The "core" Guard enabled a basic read functionality for Guard PGP encrypted emails. We recommend enabling this for all users, as this allows all recipients to read Guard emails sent to them. Great opportunity for upsell. Recipients with only Guard enabled can then do a secure reply to the sender, but they can't start a new email or add recipients.
Guard Mail, Guard Drive and Guard Docs are additional options for users. "Guard Mail" allows users the full functionality of Guard emails. "Guard Drive" allows for encryption and decryption of Drive files and "Guard Docs" allows direct integration of Guard into Documents.
S/Mime enables S/Mime functionality for users (as of 2.10.7). May be used alone or with the above Guard capabilities.
Each of those Guard components is enabled for all users that have the according capability configured. Please note that users need to have the Drive permission set to use Guard Drive. So the users that have Guard Drive enabled must be a subset of those users with OX Drive permission. Since v7.6.0 we enforce this via the default configuration. Those capabilities can be activated for specific user by using the Open-Xchange provisioning scripts:
Guard PGP Mail:
$ /opt/open-xchange/sbin/changeuser -c 1 -A oxadmin -P admin_password -u testuser --config/com.openexchange.capability.guard-mail=true
Guard Drive:
$ /opt/open-xchange/sbin/changeuser -c 1 -A oxadmin -P admin_password -u testuser --config/com.openexchange.capability.guard-drive=true
Please Note: Guard Drive requires Guard Mail to be configured for the user as well. In addition, these capabilities may be configured globally by editing the guard-api.properties
file on the OX backend.
S/Mime (as of 2.10.7)
See OX Guard S/Mime for more details on S/Mime
External Guest recipients
Starting in Guard 2.10.0, when an encrypted email is sent to a user that does not have Guard, a guest account is created for them in appsuite. The recipient uses the Guest account to read the encrypted email. These guest users MUST have guard capabilities. To do this, guard capability must be added to guest accounts.
/opt/open-xchange/etc/share.properties
com.openexchange.share.guestCapabilityMode=static
com.openexchange.share.staticGuestCapabilities=guard
In a distributed system, the Guest accounts should not be considered transient. Guard servers must be able to verify the guest account exists in the session storage services.
com.openexchange.share.transientSessions=false
Guest Storage
When an encrypted email is sent to an external Guest, a copy of the fully encrypted email is stored on the server. This is used to create an inbox of encrypted emails for the guest. By entering in a password, the emails can be decrypted and displayed.
How these files are stored depend on which package, open-xchange-guard-file-storage or open-xchange-guard-s3-storage, was installed.
The file retention policy is configured in the guard-core.properties file.
Recipient key detection
Local
Guard needs to determine if an email recipients email address is an internal or external (non-ox) user.
To detect if the recipient is an account on the same OX Guard system there is a mechanism needed to map a recipient mail address to the correct local OX context. The default implementation delivered in the product achieves that by looking up the mail domain (@example.com) within the list of context mappings. That is at least not possible in case of ISPs where different users/contexts use the same mail domain. In case your OX system does not use mail domains in context mappings it is required to deploy an OX OSGi bundle implementing the com.openexchange.mailmapping.MailResolver
class or by interfacing Guard with your mail resolver system. Please see OX Guard Mail Resolver for details.
External
Starting with Guard 2.0, Guard will use public PGP Key servers if configured to find PGP Public keys.
External PGP servers to use can be configured in the guard.properties file on the Guard servers. These can be "trusted" or "untrusted" servers. Trusted servers might be internal servers containing known, trusted keys. Untrusted servers may be public servers that are not necessarily to be trusted (users will have keys marked as trusted or untrusted).
com.openexchange.guard.trustedPGPDirectory = hkp://localservice.somewhere:113711
com.openexchange.guard.untrustedPGPDirectory = hkp://keys.gnupg.net:11371, hkp://pgp.mit.edu:11371
Please Note PGP key servers by default append the path /pks when the record is obtained from an SRV record. The proxy (also included in Apache config above) routes anything under /pks to the OX Guard PGP server.
ProxyPass /pks balancer://oxguard/pgp
Guard keys are also discoverable using the webkey service as specified here: https://tools.ietf.org/html/draft-koch-openpgp-webkey-service-02 This is enabled if you include the
ProxyPass /.well-known/openpgpkey/hu balancer://oxguard/hu
in the proxy_http.conf as above. Please note that the well-known request is targeted at the domain part of the mail address. Therefore clients will request for a mail address name@example.com the URI https://example.com/.well-known/openpgpkey/hu/...
That means that there is the very likely need that some sort of proxying or rewriting from the webserver providing the domain needs to happen. For example for proxying using Apache 2.4 it would roughly look like this:
SSLProxyEngine on
<LocationMatch /.well-known/openpgpkey/>
ProxyPass https://ox.example.com/.well-known/openpgpkey/
</LocationMatch>
Clustering
You can run multiple OX Guard servers in your environment to ensure high availability or enhance scalability. OX Guard integrates seamlessly into the existing Open-Xchange infrastructure by using the existing interface standards and is therefor transparent to the environment. A couple of things have to be prepared in order to loosely couple OX Guard servers with Open-Xchange servers in a cluster.
MySQL
The MySQL servers need to be configured in order to allow access to the configdb of Open-Xchange. To do so you need to set the following configuration in the MySQL my.cnf
:
bind = 0.0.0.0
This allows the Guard backend to bind to the MySQL host which is configured in the guard-core.properties
file with com.openexchange.guard.configdbHostname
. After the bind for the MySQL instance is configured and the OX Guard backend would be able to connect to the configured host, you have to grant access for the OX Guard service on the MySQL instance to manage the databases. Do so by connecting to the MySQL server via the MySQL client. Authenticate if necessary and execute the following, please note that you have to modify the hostname / IP address of the client who should be able to connect to this database, it should include all possible OX Guard servers:
GRANT ALL PRIVILEGES ON *.* TO 'openexchange'@'oxguard.example.com' IDENTIFIED BY ‘secret’;
Apache
OX Guard uses the Open-Xchange REST API to store and fetch data from the Open-Xchange databases. The REST API is a servlet running in the Grizzly container. By default it is not exposed as a servlet through Apache and is only accessibly via port 8009. In order to use Apache's load balancing via mod_proxy
we need to add a servlet called "preliminary" to proxy_http.conf
, example based on a clustered mod_proxy
configuration:
<Location /preliminary> Order Deny,Allow Deny from all # Only allow access from Guard servers within the network. Do not expose this # location outside of your network. In case you use a load balancing service in front # of your Apache infrastructure you should make sure that access to /preliminary will # be blocked from the Internet / outside clients. Examples: # Allow from 192.168.0.1 # Allow from 192.168.1.1 192.168.1.2 # Allow from 192.168.0. </Location> ProxyPass /preliminary balancer://oxcluster/preliminary
Make sure that the balancer is properly configured in the mod_proxy
configuration. Examples on how to do so can be found in our clustering configuration for Open-Xchange AppSuite. Like explained in the example above, please make sure that this location is only available in your internal network, there is no need to expose /preliminary
to the public, it is only used by Guard servers to connect to the OX backend. If you have a load balancer in front of the Apache cluster you should consider blocking access to /preliminary
from WAN to restrict access to the servlet to internal network services only.
Now add the OX Guard BalancerMembers
to the oxguard balancer configuration (also in proxy_http.conf
) to address all your OX Guard nodes in the cluster in this balancer configuration. The configuration has to be applied to all Apache nodes within the cluster.
If the Apache server is a dedicated server /
instance you also have to install the OX Guard UI-Static package on all Apache nodes in the cluster in order to provide static files like images or CSS to the OX Guard client. Example for Debian (the OX Guard repository has to be configured in the package management prior):
$ apt-get install open-xchange-guard-ui-static
Open-Xchange
Disable the Open-Xchange IPCheck for session verification. This is required because OX Guard will use the users session cookie to connect to the Open-Xchange REST API, but as a different IP address than the OX Guard server has been used during authentication the request would fail if you don't disable the IPCheck:
$ vim /opt/open-xchange/etc/server.properties
and set:
com.openexchange.IPCheck=false
The OX Guard UI package has to be installed on all Open-Xchange backend nodes as well, example for Debian (the OX Guard repository has to be configured in the package management prior):
$ apt-get install open-xchange-guard-ui
Restart the Open-Xchange service afterwards.
OX Guard
For details in clustering Guard servers, please see OX Guard Clustering. It is critical that all Guard servers have the same oxguardpass
file. Please see the clustering link for details. Do not run /opt/open-xchange/sbin/guard --init
on more than one server.
After all the services like MySQL, Apache and Open-Xchange have been configured you need to update the OX Guard backend configuration to point to the correct API endpoints. Set the REST API endpoint to an Apache server by setting the following value in /opt/open-xchange/etc/guard-core.properties
:
com.openexchange.guard.restApiHostname=apache.example.com
Per default Guard will try to connect to port 8009 to this host, but as we configured the REST API to be proxies thorugh the servlet /preliminary
on every Apache we now also need to change the target port for the REST API. You can do so by adding the following line into /opt/open-xchange/etc/guard-core.properties
:
com.openexchange.guard.oxBackendPort=80
Please also change all settings in regards to MySQL like com.openexchange.guard.configdbHostname
, com.openexchange.guard.oxguardDatabaseHostname
, com.openexchange.guard.databaseUsername
or om.openexchange.guard.databasePassword
.
Afterwards restart the OX Guard service and check the log file if the OX Guard backend is able to connect to the configured REST API.
Multi Node
If you have multiple OX and Guard installations, please see the following documentation OX Guard Modular Setup.
Mail Filter Integration (2.10.4+)
To add additional mail filter tests (verify PGP signature, or encrypt incoming), please see MailFilter Integration
Support API
The OX Guard Support API enables administrative access to various functions for maintaining OX Guard from a client in a role as a support employee. A client has to do a BASIC AUTH authentication in order to access the API. Username and password can be configured in the guard-core.properties file using the following settings:
# Specify the username and password for accessing the Support API of Guard com.openexchange.guard.supportApiUsername= com.openexchange.guard.supportApiPassword=
In contrast to the rest of the OX Guard requests, the OX Guard support API requests are accessible using: /guardsupport. This distinction allows more flexible configuration since the support API should not always be accessible from everywhere.
Warning: Exposing the support API to the internet could be huge security risk. Only add to Apache if you know what you are doing.
Reset password
POST /guardsupport/?action=reset_password
Performs a password reset and sends a new random generated password to a specified email address by the user or a default address if the user did not specify an email address. (Since Guard 2.0)
Parameters:
email
– The email address of the user to reset the password fordefault
(optional) – The email address to send the new password to, if the user did not specify a secondary email address
Response: PRIMARY if the reset was sent to the primary email address. SECONDARY if the reset email was sent to the secondary email address that the user specified
Expose key
POST /guardsupport/?action=expose_key
Marks a deleted user key temporary as “exposed” and creates a unique URL for downloading the exposed key. Automatic resetting of exposed keys to "not exposed" is scheduled once a day and resets all exposed keys which have been exposed before X hours, where X can be configured using com.openexchange.guard.exposedKeyDurationInHours in the guard.properties files. (Since Guard 2.0)
Parameters:
email
– The email address of the user to expose the deleted keys forcid
– The context id
Response: A URL pointing to the downloadable exposed keys.
Delete user
POST /guardsupport/?action=delete_user
Deletes all keys related to a certain user. The keys are backed up and can be exposed using the “expose_key” call. (Since Guard 2.0)
Parameters:
user_id
– The user's idcid
- The context id
Upgrade User (Release 2.10 and later)
POST /guardsupport/?action=upgrade_guest
Upgrades a Guest account. This action copies all of the keys from the Guest account to a full OX account, assuming that user has Guard capabilities.
Parameters:
email
- The email address of the Guest useruser_id
– The user's new idcid
- The user's new context id
Customisation
Guard's templates are customisable at the user and context level. Please see Customisation for details.
Entropy
Guard requires entropy (randomness) to generate the private/public keys that are used. Depending on the server and it's environment, this may become a problem. Please see Entropy for a possible solution.